Enum TransformUsageFlags
Controls how Transform components on GameObjects are converted to entity data.
Namespace: Unity.Entities
Syntax
[Flags]
public enum TransformUsageFlags
Remarks
These flags help to reduce the number of unnecessary transform components in baked entities based on their intended use at runtime.
The Dynamic flag replicates as close as possible the GameObject data and structure. These flags are used whenever an entity is requested during conversion, for example, via GetEntity(). Bakers for default GameObject components add the appropriate TransformUsageFlags too. For example, in the case of the baker for MeshRenderer, Renderable is added as a TransformUsageFlag.
More than one baker can indicate different TransformUsageFlags for the same entity. All those flags are combined together before the transform components are added to the entity. For example if a baker requests for an entity to be Dynamic and another baker requests for the same entity to be in WorldSpace, the entity is considered to be Dynamic and in WorldSpace when the transform components are added to the entity.
These are a few examples on how to use TransformUsageFlags can help to reduce the number of unnecessary transforms components on entities:
If you have a GameObject representing a building and that building contains a child GameObject that is a window (these entities aren't going to move at runtime). If both entities are only marked as Renderable, then they don't need to be in a hierarchy and all their transform information can be combined in a LocalToWorld component (in WorldSpace). In this case both entities only have a LocalToWorld component and they don't have LocalTransform and Parent unnecessarily.
In another example, the same window GameObject could be part of a ship instead of a building. In that case, the ship is marked as Dynamic and the window is still Renderable. The window entity ends up with all the required transform components to follow the ship around when it sails (LocalToWorld, LocalTransform and Parent).
A building GameObject could have a helicopter GameObject on the roof (as a child). In this case the building is still Renderable, but the helicopter is marked as Dynamic because it can take off. The helicopter has the transform components to be moved (LocalToWorld, LocalTransform), but it isn't parented to the building and its transform data is in world space.
In the case of a ship with a helicopter, both are marked as dynamic and the helicopter entity is a child of the ship, so it follows the ship around when it sails. In this particular case when the helicopter takes off, the hierarchy needs to be broken manually at runtime and the transform data converted to world space.
If the helicopter can shoot some bullets, the bullet entity prefab should be marked as Dynamic so it can be instantiated at the right position and moved.
There is also a case where an Entity might be stripped out from the final world during baking. This happens when there is no baker adding a TransformUsageFlag to it (TranformUsageFlags.None counts as adding a TransformUsageFlag). An example of this is a GameObject that's created in the Editor Hierarchy to group their children at authoring time for organizational purposes, but has no use at runtime. In this case, the children are moved to world space. There is an exception to this stripping rule, if an entity that has no TransformUsageFlags has a Dynamic parent and Dynamic children, then that entity is considered Dynamic as well and it isn't stripped out.
Fields
Name | Description | Value |
---|---|---|
None | Specifies that the entity doesn't need transform components. Unless something else requests other flags, this entity doesn't have any transform related components and isn't part of a hierarchy. This doesn't affect its membership in any LinkedEntityGroup components that might be created based on the source GameObject hierarchy. |
0 |
Renderable | Indicates that an entity requires the necessary transform components to be rendered (LocalToWorld), but it doesn't require the transform components needed to move the entity at runtime. Renderable entities are placed in WorldSpace if none of their parents in the hierarchy are Dynamic. |
1 |
Dynamic | Indicates that an entity requires the necessary transform components to be moved at runtime (LocalTransform, LocalToWorld). Renderable children of a Dynamic entity are also treated as Dynamic and they receive a Parent component. A Dynamic usage also implies Renderable, therefore there you don't need to indicate that a Dynamic entity is also Renderable. |
2 |
WorldSpace | Indicates that an entity needs to be in world space, even if they have a Dynamic entity as a parent. This means that an entity doesn't have a Parent component and all their transform component data is baked in world space. A WorldSpace usage implies Renderable but not Dynamic, but Dynamic can be used with the WorldSpace flag. |
4 |
NonUniformScale | Indicates that an entity requires transform components to represent non uniform scale. For Dynamic entities, all the scale information is stored in a PostTransformMatrix component. For Renderable only entities, the scale information is combined into the LocalToWorld component. If a GameObject contains a non uniform scale, this flag is considered implicitly for Renderable and Dynamic entities. |
8 |
ManualOverride | Indicates that you want to take full manual control over the transform conversion of an entity. This flag is an override: when it is set, all other flags are ignored. Baking doesn't add any transform related components to the entity. The entity doesn't have a parent, and it doesn't have any children attached to it. |
16 |