Animation Layers

Agents animate through a stack of layers. Walking, idling and turning are always at the bottom. Above them sit the layers you define in a profile, and every action animation plays on one of those. Give a layer an avatar mask and it drives only the bones in the mask, so an agent can carry a crate with its arms while its legs keep walking.

There is no Animator Controller to author. The layer stack is built for each agent when it starts, from the profile in module settings.

The layer profile

The profile is an ordered list of layers. Open BardTreeLtd > Civil AI > Module Settings, go to the Animation tab and set Layer Profile. If you have none, press Create Default Profile; it makes a profile with two layers:

Layer	Mask	Used for
Action	None	Whole-body actions: sitting down, sawing, sleeping
Upper Body	None	Things the arms do while the legs carry on. Give it a mask first.

Each layer has:

Field	What it does
Name	How animation groups pick this layer. Renaming it orphans anything pointing at the old name.
Mask	An Avatar Mask. Bones in the mask take this layer's clip; bones outside it keep playing locomotion.
Additive	Adds the clip on top of the layers below instead of replacing them. Leave it off unless the clip was authored as an offset from a rest pose.
Weight	How much of the layer shows when something is playing on it. Usually 1.
Fade Seconds	How long the layer takes to blend in when a clip starts and out when it ends.

Layers are picked by name, never by position, so you can reorder the list without anything moving.

You can also create a profile directly from Create > BardTreeLtd > Civil AI > Animation > Profile and assign it yourself.

Picking a layer for an animation

Every animation group on a behaviour tree node has a Layer dropdown, next to Rigid Sets and Selection Mode. It lists the layers in your profile.

Leave it on (first layer) and the clips play on the first layer in the profile. That is what every animation group made before 0.15.0 does, so nothing you already have changes.

If a group names a layer the profile does not define, its clips play on the first layer and a warning is logged once.

Walking while carrying something

The reason layers exist. Before, carrying meant a complete set of core animations per carry style, each with its own walk and idle. Now it is one clip on a masked layer.

1. Make an Avatar Mask from Create > Avatar Mask. In its Humanoid section, turn off the legs, feet and root, leaving the spine, arms and head on.
2. In the profile, put that mask on the Upper Body layer.
3. On the action's animation group, set Layer to Upper Body and add your carry clip.

The agent walks with its legs and carries with its arms, and it does not matter which core animation set it is in.

note

Use an override layer with a mask for this, not Additive. A masked layer takes the bones in the mask outright, which is what holding and gesturing want. Additive is for offsets — a lean, a breathing cycle — and needs clips authored for it.

Blending

The Animation tab also holds the blend times, all in seconds:

Setting	Covers
Core Set Blend	Changing between core animation sets, when an agent moves from one group to another. 0.25.
Layer Blend	A layer fading in and out, for any layer whose own Fade Seconds is left at 0. 0.15.
Clip Crossfade	Moving from one clip to the next inside a sequence — start to middle, middle to end. 0.1.
Turn Rate At Full Weight	Degrees per second at which the rotate clip is fully blended in. 90.

Holding a pose

An animation group with Hold Last Pose on keeps its final frame showing when the sequence ends, rather than fading back to locomotion. Use it for anything that ends somewhere the agent stays, such as sitting down or lying down. The layer stays up until something else plays on it.

Pausing the game holds every pose as it is. A seated agent stays seated.

Seeing what is playing

Select an agent in play mode and open the Animation section of its inspector. It shows the core animation group the agent is using, the idle, move and rotate weights, and for each layer its weight, clip, time, mask and whether it is holding a pose. This replaces watching the Animator window.

Checking your setup

Run BardTreeLtd > Civil AI > Validate Animation Setup whenever something looks wrong. It reports:

• no layer profile, or one with no layers
• layers with no name, or two with the same name
• an additive layer with no mask
• core animations without Loop Time enabled. The state machine looped a clip whether or not the clip said to; the layer stack does not, so an idle without Loop Time freezes on its last frame
• animation groups naming a layer the profile does not have
• agents with no Animator, or none with an Avatar
• prefabs still pointing at the old Animator Controller. Nothing reads it now; the reference can be cleared

Next step

Animation Sets covers what goes in a core and dynamic set, and Animation Editor covers ordering core groups by requirement.