Game.AnimationUpdateSystem

Assembly: Assembly-CSharp
Namespace: Game.Tools

Type: class

Base: GameSystemBase

Summary:
AnimationUpdateSystem is an ECS System responsible for updating Animation component data for entities that have transform and prefab references. It builds a temporary map of prefab-specific Animation templates (AnimationMapJob) and then updates per-entity Animation components (AnimationUpdateJob) by selecting the closest relevant animation source (original/interpolated transform or prefab-based animations) and computing runtime parameters such as target position, rotation, sway pivot and push factor. The system uses Burst-compiled IJobChunk jobs, ComponentTypeHandle and ComponentLookup accessors, and a NativeParallelMultiHashMap to share prefab animation templates between jobs. It schedules jobs with dependency chaining and disposes the temporary map once the scheduled jobs complete.

---

Fields

• private EntityQuery m_UpdatedQuery
  Stores the query used to find entities that need their Animation components written (ReadWrite Animation) and that also have a Transform and Updated tag while excluding Deleted. This query is used as the primary scheduling target for the job that writes Animation data.

• private EntityQuery m_AnimatedQuery
  Stores the query used to collect entities that provide prefab-level Animation templates (ReadOnly Animation, Temp, Transform). This query is scheduled first to populate the NativeParallelMultiHashMap that the writer job reads from.

• private TypeHandle __TypeHandle
  Internal struct instance that caches ComponentTypeHandle and ComponentLookup instances (read-only and read-write) used by the jobs. It is filled in OnCreateForCompiler / __AssignHandles and then used to get actual handles when scheduling jobs.

Properties

• This type does not expose public properties.
  Note: the nested TypeHandle struct contains multiple ComponentTypeHandle and ComponentLookup fields used internally by the system and the scheduled jobs.

Constructors

• public AnimationUpdateSystem()
  Default constructor. Marked with [Preserve] in source to avoid stripping. No special initialization beyond base construction — queries and type handles are initialized in OnCreate / OnCreateForCompiler.

Methods

• protected override void OnCreate()
  Creates and configures the two EntityQuery objects: m_UpdatedQuery (entities whose Animation should be updated) and m_AnimatedQuery (entities providing animation templates). Calls RequireForUpdate(m_UpdatedQuery) so the system only runs when there are entities matching the update query.

• protected override void OnUpdate()
  Main scheduling method. It:

• Allocates a NativeParallelMultiHashMap (temporary, with Allocator.TempJob) to collect prefab animation templates.
• Prepares and schedules AnimationMapJob (IJobChunk) to populate the map with Animation entries from entities that have a non-default rotation and a PrefabRef.
• Prepares and schedules AnimationUpdateJob (IJobChunk, Burst) that reads transforms, temp, owner, prefab geometry, interpolated transforms, and the animation map to compute and write per-entity Animation component data. It computes the nearest relevant animation source and calculates m_PushFactor and m_SwayPivot based on prefab geometry and pivot.
• Disposes the NativeParallelMultiHashMap by passing the writer job's JobHandle to Dispose so disposal occurs after job completion.

• Assigns the scheduled JobHandle back to base.Dependency so other systems respect dependencies.

• protected override void OnCreateForCompiler()
  Called to initialize handles/queries for the ahead-of-time generated code path. It calls __AssignQueries and __TypeHandle.__AssignHandles to ensure ComponentTypeHandle/ComponentLookup fields are prepared for scheduling.

• private void __AssignQueries(ref SystemState state)
  Internal helper used during the compiler-targeted initialization. In this implementation it creates then disposes a temporary EntityQueryBuilder — needed for the generated boilerplate.

• (Nested) AnimationMapJob : IJobChunk
  Burst-compiled job that iterates over chunks of entities matching m_AnimatedQuery, reads Animation and PrefabRef components and adds Animation templates to the NativeParallelMultiHashMap keyed by the prefab Entity. It only adds templates where the Animation's rotation is not the default quaternion (so only valid templates are considered).

• (Nested) AnimationUpdateJob : IJobChunk
  Burst-compiled job that iterates over chunks of entities matching m_UpdatedQuery and updates their Animation component. For each entity it:

• Tries to use an InterpolatedTransform (preferred) or original Transform as the animation source (target position/rotation).
• Falls back to the entity's own transform if no original exists.
• Scans prefab-specific animation templates from the NativeParallelMultiHashMap to find the closest template by distance to the entity's position and selects it if closer than the original source.
• Computes m_PushFactor using prefab geometry size, pivot, and deltaTime (guarded against division by near-zero).
• Writes resulting Animation back to the component array for the entity.

Notes on threading and memory: - Jobs are Burst-compiled where marked [BurstCompile], improving performance. - NativeParallelMultiHashMap is allocated with a fixed initial capacity (100 in this implementation) — capacity should be chosen appropriately for expected number of distinct prefabs to avoid reallocation overhead. - The map is disposed by scheduling the Dispose with the job handle so it will be freed only after jobs that use it complete.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // This system already sets up its queries internally. If you need to create your own
    // systems that interact with AnimationUpdateSystem, ensure you use matching queries or
    // require update/order appropriately.
    // Example: require your system to run after this one:
    // RequireForUpdate(GetEntityQuery(ComponentType.ReadWrite<Animation>()));
}

Additional Modding Tips - If you need to override or extend animation selection, consider: - Adding or modifying Animation components before this system runs (use ordering or explicit system dependencies). - Creating a system that runs after AnimationUpdateSystem to post-process Animation components for special cases. - Be careful when changing component layouts or the Animation struct: both jobs assume specific fields (m_Position, m_TargetPosition, m_Rotation, m_SwayPivot, m_PushFactor) and binary compatibility matters for Burst jobs. - Tune NativeParallelMultiHashMap initial capacity (currently 100) to match the number of distinct prefabs you expect to reduce contention and rehashes. - Maintain safety with ComponentLookup reads inside jobs — the job uses TryGetComponent via the ComponentLookup API; keep those component types present and read-only when used in Burst jobs.