ZOA Entity Rig

EntityArchetypeDefinition holds five references and one string, and each slot answers a different question about the entity. The EntityRigVisualProfileDefinition answers what it looks like: the base skinned-mesh prefab, semantic material slots, bone sockets, LOD levels and optional overlays. The AnimationProfileDefinition answers how it moves: the tagged-clip table the resolver matches the active state against. The SoundProfileDefinition answers how it sounds: the semantic event table covering footsteps, vocals, foley and weapons. The EntityStateGraphDefinition answers how transitions are timed. The RigPolicyDefinition answers which IK constraints get generated and how the procedural fallback feels.

Because they are separate assets, they are separately shareable. A soldier, a guard and a civilian can all reference the same human sound profile and the same rig policy while differing only in visual and animation profile. Embedded data would make that sharing impossible, so the archetype holds references instead.

The EntityKind field, Player, AiCharacter, Interactable, Ambient or the Unspecified sentinel that validators flag, tells the builder which wiring template to use. DefaultLocomotionTag is a spawn-time baseline, useful for an AI archetype that should start crouched rather than standing.

EntityRigBuilder.Build is static and stateless. It takes an existing root GameObject, an archetype, a required IEntityStateProvider and an optional IEntitySoundEmitter, mutates the root, and returns an EntityRigBuildResult carrying handles to the root, controller, visual root, animator and audio player.

The sequence is five steps. It instantiates the visual profile's base prefab as a child named Visual, reusing an existing child of that name rather than duplicating it so the builder can be run repeatedly during authoring iteration. It finds the Animator in that sub-tree. It adds an EntityRigController if the root does not already have one. It attaches an AudioEventPlayer, assigns the archetype's sound profile to it if the player has none, and wraps it in an adapter implementing IEntitySoundEmitter, unless the caller supplied a custom emitter. Then it calls Rebind on the controller, which re-flattens the resolution caches.

An archetype with no visual profile or no base prefab simply gets no visual sub-tree, which is the correct outcome for an ambient sound source. The builder is the single entry point for rig composition, so new capabilities such as cloth or footprint effects extend the builder instead of being wired at each call site.

Every frame the controller asks its IEntityStateProvider for a StateTagSet and compares it with last frame's. If nothing changed it does nothing, except on the very first frame where it forces a resolve so an entity whose initial state happens to be the empty set still picks a clip.

When the state has changed, the controller checks the hold window before honouring the transition. If a hold is still counting down, it finds the first dimension that differs between the old and new state, looks up that dimension's TransitionPolicy, and only allows the transition through if that policy's trigger is OnEvent. Reactions interrupt under that rule: hit and stagger sit on the Reaction dimension, whose default trigger is OnEvent with no hold, so a flinch lands immediately while a locomotion change during a posture hold waits its turn.

Resolving calls AnimationProfileResolver.ResolveBestMatch against the flattened entry list. On a hit, the controller derives a state hash from the winning clip's name and calls CrossFadeInFixedTime with the policy's crossfade duration, then arms the hold window with the policy's minimum hold. On a miss it clears the hold so the next state change is honoured immediately.

The hot path allocates nothing. The flattened entry lists for both animation and sound are built once at bind time, resolution returns an int index, and the head bone used by the procedural bob is located once during Bind rather than searched per frame.

When resolution produces no match at all, and the archetype's rig policy allows it, the controller drives the rig procedurally instead of freezing. Today that is a breath: a sine on the head bone's local Y at the policy's BreathFrequency and BreathAmplitude, accumulating phase against delta time.

Treat it as the floor of the system rather than a feature you author toward. An archetype with an empty animation profile falls straight through to it, so a rig with only a visual profile bound still looks alive. Set AllowProceduralFallback to false on the rig policy when the entity should hold its last pose instead, which is usually right for a door or a vehicle.

A SocketBinding pairs a semantic SocketId with a transform path inside the visual prefab, plus optional position and Euler rotation offsets for when a bone's pivot does not sit where the socket should. The runtime resolves the path once at bind time and caches the transform.

SocketId is a short canonical enum: Head, Neck, ChestUpper and ChestLower, SpineAttachUpper and SpineAttachLower, WaistRight and WaistLeft, HipBack, the two shoulders, the two hands and the two feet, EyesAnchor, MouthAnchor, WeaponPrimary and WeaponSecondary, plus Custom for anything bespoke. The list stays short because equipment and attachment systems mount against these ids, and a sprawling enum makes that contract useless.

Sockets are seeded at FBX import time by name heuristics, so a bone called hand_r seeds RightHand, and every one of them is individually overridable by the author afterwards. The same is true of material slots and LOD levels: most of the visual profile is populated by the importer and the author's job is usually confirming rather than typing.

A MaterialSlot names the renderer path, the slot index on that renderer, and a semantic material id. It never references a URP or HDRP material asset directly. The id resolves through the material resolver chain at runtime, so the same archetype ships against either pipeline.

VisualOverlay works the same way for add-on geometry. An overlay names an optional prefab, an optional mount socket, and a set of free-form activation tags; the runtime activates it when at least one of its tags is asserted on the entity, so an armour piece or a helmet appears without the archetype needing a variant.