Game.Rendering.AnimatedSystem

Assembly: Game
Namespace: Game.Rendering

Type: class

Base: GameSystemBase, IPreDeserialize

Summary:
AnimatedSystem is the central animation management system used by the rendering pipeline. It: - Manages loading/unloading of animation assets and caches (animations, rest poses, index maps). - Allocates and tracks GPU/CPU memory via NativeHeapAllocator instances for bones, animation elements, and index data. - Builds and updates compute buffers (meta, anim, index, bone, instance/transition buffers) and dispatches a compute shader that blends animation layers and converts local coordinate data (optionally with motion vectors). - Provides thread/job-safe writers (AllocationData / AnimationData) so other systems can enqueue allocation requests and animation frames from jobs; coordinates with job dependencies via m_AllocateDeps. - Contains several small Burst-compiled jobs (AddAnimationInstancesJob, UpdateAnimationPriorityJob, EndAllocationJob) and multiple nested/utility structs for frame and allocation bookkeeping.

Fields

private RenderingSystem m_RenderingSystem
Holds a reference to the RenderingSystem (used to query render-time flags such as motion vectors) retrieved from the world.
private PrefabSystem m_PrefabSystem
Reference to PrefabSystem used to read CharacterStyle/animation asset data when loading animations.
private NativeHeapAllocator m_BoneAllocator
Allocator for bone data (BoneElement) used by compute shader bone buffers.
private NativeHeapAllocator m_AnimAllocator
Allocator for animation element data (Colossal.Animations.Animation.Element).
private NativeHeapAllocator m_IndexAllocator
Allocator for index buffers (hierarchy, shape, bone indices, inverse bone maps).
private NativeList<MetaBufferData> m_MetaBufferData
CPU-side list of per-meta data that is uploaded to the GPU meta compute buffer.
private NativeList<int> m_FreeMetaIndices
Free list for meta slot reuse.
private NativeList<int> m_UpdatedMetaIndices
List of meta indices that have changed and need to be uploaded to the GPU meta buffer.
private NativeList<RestPoseInstance> m_InstanceIndices
Instances to be processed by compute shader for rest-pose / instance setup.
private NativeList<AnimatedInstance> m_BodyInstances
Body animation instance entries for compute shader blending.
private NativeList<AnimatedInstance> m_FaceInstances
Face animation instance entries.
private NativeList<AnimatedInstance> m_CorrectiveInstances
Corrective animation instances.
private NativeList<AnimatedTransition> m_BodyTransitions
Single-transition body transitions.
private NativeList<AnimatedTransition2> m_BodyTransitions2
Double-transition body transitions (two blend sources).
private NativeQueue<AllocationRemove> m_BoneAllocationRemoves
Queued bone allocation releases (deferred until safe to release).
private NativeQueue<IndexRemove> m_MetaBufferRemoves
Queued meta buffer removals (deferred).
private ComputeShader m_AnimationComputeShader
Compute shader used to blend animations and convert coordinates. Kernel indices are cached on OnCreate.
private ComputeBuffer m_BoneBuffer
GPU structured buffer holding current bone TRS/matrices.
private ComputeBuffer m_BoneHistoryBuffer
History buffer for motion vectors (if enabled).
private ComputeBuffer m_MetaBuffer
GPU buffer that stores meta data for instances.
private ComputeBuffer m_AnimBuffer
GPU buffer with animation element data.
private ComputeBuffer m_IndexBuffer
GPU buffer for various index tables (hierarchy, shapes, bones, inverse-bones).
private Dictionary<string,int> m_PropIDs
Name-to-id mapping for animated prop IDs.
private NativeQueue<AnimationFrameData> m_TempAnimationQueue
Temporary native queue used to enqueue animation frame info from jobs (created lazily).
private NativeQueue<ClipPriorityData> m_TempPriorityQueue
Temporary native queue used to enqueue clip priority updates from jobs (created lazily).
private JobHandle m_AllocateDeps
Job dependency handle that callers can supply; AnimatedSystem waits/completes this when handling allocations. Used to coordinate safe allocation/release.
private bool m_IsAllocating
Flag indicating allocation operations are in progress (used to delay buffer resizing and GPU updates until jobs complete).

(There are many more private fields and kernel/property IDs used for compute shader binding; above are the most important for modders.)

Properties

(No public properties exposed by this system. Interaction is done via methods returning helper structs.)

Constructors

public AnimatedSystem()
Default constructor (preserved). Initialization of most runtime state is performed in OnCreate.

Methods

protected override void OnCreate()
Initializes allocators, native lists/queues, loads and instantiates the animation compute shader, caches kernel indices and shader property IDs, creates initial allocations and default meta entry. This prepares the system to accept allocation and animation writers.
protected override void OnDestroy()
Cleans up: completes any outstanding allocation jobs, disposes allocators and native lists/queues, releases all ComputeBuffers, and destroys the compute shader instance.
protected override void OnUpdate()
Called each frame by the world. If allocations finished (m_IsAllocating), it completes dependencies, resizes buffers and updates animations/meta/instances. Then calls PlayAnimations which binds buffers and dispatches compute shader kernels to perform blending and coordinate conversion.
public void PreDeserialize(Context context)
Implements IPreDeserialize. Clears allocators, lists, and queues prior to deserialization to ensure a consistent starting state when loading a saved game.
public AllocationData GetAllocationData(out JobHandle dependencies)
Used by other systems to obtain a thread-safe AllocationData writer and the current dependencies handle. Callers enqueue allocation/removal requests (AllocateBones/ReleaseBones/AddMetaBufferData/RemoveMetaBufferData) from jobs and return the writer's JobHandle via AddAllocationWriter.
public AnimationData GetAnimationData(out JobHandle dependencies)
Returns an AnimationData writer (which holds parallel writers for two native queues) to allow other systems to enqueue animation frames and clip priority updates from jobs. Also returns the current dependencies (to chain jobs) and marks the system as allocating.
public void AddAllocationWriter(JobHandle handle)
Set/extend m_AllocateDeps with a producer job handle after scheduling jobs that used AllocationData.
public void AddAnimationWriter(JobHandle handle)
Set/extend m_AllocateDeps with a producer job handle after scheduling jobs that used AnimationData.
public AnimatedPropID GetPropID(string name)
Get or create a small integer ID for a named animated prop; used to reference per-prop animation data compactly.
public void GetBoneStats(out uint allocatedSize, out uint bufferSize, out uint count)
Query memory/buffer statistics for bones. Blocks until allocation jobs complete.
public void GetAnimStats(out uint allocatedSize, out uint bufferSize, out uint count)
Query animation allocator stats and counts.
public void GetIndexStats(out uint allocatedSize, out uint bufferSize, out uint count)
Query index allocator stats.
public void GetMetaStats(out uint allocatedSize, out uint bufferSize, out uint count)
Query meta buffer statistics.
Internal/Burst jobs and helpers (not public API but useful to know):
AddAnimationInstancesJob (IJob, Burst) — dequeues AnimationFrameData and populates instance & transition NativeLists for GPU.
UpdateAnimationPriorityJob (IJob, Burst) — applies queued priority updates and prunes/sorts the clip priority list.
EndAllocationJob (IJob, Burst) — processes deferred allocation and meta removals by time, releases memory and compacts meta lists.
LoadAnimation / UnloadAnimation — manage CPU/GPU allocation when an animation is loaded/unloaded; writes anim info to GPU buffers.
CacheRestPose / UnCacheRestPose — store rest pose into entity buffers.
PlayAnimations — main GPU-binding routine; sets buffers and dispatches compute shader kernels.

Usage Example

Example of how a mod system could enqueue animation frames from a job / system and provide job dependencies to AnimatedSystem:

// Example inside another system (pseudo-code):
protected override void OnUpdate()
{
    var animatedSystem = World.GetOrCreateSystemManaged<Game.Rendering.AnimatedSystem>();
    JobHandle deps;
    var animationWriter = animatedSystem.GetAnimationData(out deps); // obtains a writer and current dependencies

    // Schedule a job that uses animationWriter (AnimationData.SetAnimationFrame) from a job
    var producerJob = new MyProduceAnimationJob {
        // pass animationWriter fields or parameters needed
    }.Schedule(deps);

    // Tell AnimatedSystem about the producer job so it can wait for it
    animatedSystem.AddAnimationWriter(producerJob);
}

// Or on the main thread, you can directly enqueue a single frame:
var animatedSystem = world.GetOrCreateSystemManaged<Game.Rendering.AnimatedSystem>();
JobHandle dummy;
var animData = animatedSystem.GetAnimationData(out dummy);
animData.SetAnimationFrame(characterElement, clipsBuffer, animatedComponent, new float2(0f,0f), priority: 1, reset: false);
animatedSystem.AddAnimationWriter(default(JobHandle));

Notes for modders: - Use GetAnimationData/GetAllocationData to safely enqueue work from jobs. Always supply the returned dependencies (via AddAnimationWriter/AddAllocationWriter) so AnimatedSystem can synchronize correctly. - Do not directly manipulate internal ComputeBuffers or NativeHeapAllocator instances — use the provided API (AllocationData / AnimationData) and let AnimatedSystem manage GPU uploads and buffer resizing. - If you need motion-vector-correct bone data, check RenderingSystem.motionVectors; AnimatedSystem automatically dispatches a different compute kernel and maintains a bone history buffer when motion vectors are enabled.