Skip to content

t1k:unity:animation:core

FieldValue
Moduleanimation
Version3.33.4
Efforthigh
Tools—

Keywords: animated character, animation, animator, animator layer weight, animator mapping, animator parameter, animator speed, animator view, blend tree, character animation logic, clip, crossfade, drive animator, SetBool, SetFloat, SetTrigger, state machine, StringToHash, unity

/t1k:unity:animation:core

SystemUse When
MecanimCharacter locomotion, state machines, blend trees
Playable APIRuntime blending without AnimatorController, procedural animation
TimelineCinematic sequences, choreographed events, cutscenes
Animation RiggingIK (arm/leg), head tracking, weapon aiming (post-bake pose)
Animator anim = GetComponent<Animator>();
// Parameters
anim.SetBool("grounded", true);
anim.SetFloat("moveSpeed", 3.5f, dampTime: 0.1f, deltaTime: Time.deltaTime);
anim.SetTrigger("attack"); // call once per input event only
// Direct play (bypass FSM)
anim.CrossFade("RunState", duration: 0.2f);
anim.Play("IdleState", layer: 0, normalizedTime: 0f);
// Query
bool inRun = anim.GetCurrentAnimatorStateInfo(0).shortNameHash == Animator.StringToHash("Run");
float progress = anim.GetCurrentAnimatorStateInfo(0).normalizedTime;
// Layer blending
anim.SetLayerWeight(1, 0.5f); // upper-body overlay at 50%

→ See references/mecanim-guide.md for BlendTree types, root motion, AnimationEvents, StateMachineBehaviour, Animation Rigging IK, performance tips, and gotchas.

Driving an Animator From Gameplay — Mapping/View Split

Section titled “Driving an Animator From Gameplay — Mapping/View Split”

Do NOT put gameplay decisions inside the MonoBehaviour that talks to the Animator. Split every animated character in two:

  • <Name>AnimatorMapping — public static class, no Unity lifecycle. Owns every DECISION: thresholds, hysteresis, smoothing, state selection, envelopes. dt, Time, and Random are passed IN as parameters, never called inside — that is what makes the decisions unit-testable in an EditMode assembly with no scene and no Animator.
  • <Name>AnimatorView — thin sealed MonoBehaviour. Owns only Unity handles: static readonly int parameter hashes, the previous-frame floats the mapping is stateless about, and an [Inject] Construct that builds a DisposableBag disposed in OnDestroy.

DI delivery is free: [Inject] Construct fires on any component under a hierarchy the installer passes to IObjectResolver.InjectGameObject(root) — children at any depth. A new animator view on an already-injected root needs no container registration, no RegisterComponentInHierarchy, no FindAnyObjectByType.

Freeze idiom: animator.speed = 0f holds the current pose so a ragdoll/tumble reads as limp; a frozen Animator ignores every parameter, so no state flip or latch is needed. Restore with = 1f.

→ See references/animator-mapping-view-split.md for the full pattern: pure-mapping rules, the view shape, the InjectGameObject delivery fact, edge-only crossfades, Animator-on-child placement, pooled-instance resets, the testing recipe, and a new-character checklist.

PlayableGraph graph = PlayableGraph.Create();
var mixer = AnimationMixerPlayable.Create(graph, 2);
graph.Connect(AnimationClipPlayable.Create(graph, clipWalk), 0, mixer, 0);
graph.Connect(AnimationClipPlayable.Create(graph, clipRun), 0, mixer, 1);
AnimationPlayableOutput.Create(graph, "Anim", animator).SetSourcePlayable(mixer);
graph.Play();
mixer.SetInputWeight(0, 0.7f);
mixer.SetInputWeight(1, 0.3f);
// CRITICAL: graph.Destroy() in OnDisable/OnDestroy

→ See references/playable-timeline-guide.md for full graph patterns, custom PlayableBehaviour, Timeline setup, SignalTrack events, runtime binding, and gotchas.

  1. Trigger auto-reset — SetTrigger() resets after one frame; call once per input event
  2. Hash parameters — use Animator.StringToHash("name") for per-frame reads, not raw strings
  3. graph.Destroy() mandatory — leaks GPU/CPU resources if skipped
  4. Root motion conflict — disable NavMesh/CharacterController when applyRootMotion = true
  5. Animator.Rebind() expensive — avoid at runtime; Instantiate prefab instead
  6. Timeline vs Animator conflict — playing both simultaneously causes flickering; pause Animator when Timeline takes over
  7. Crossfade on the state EDGE only — re-issuing CrossFadeInFixedTime every frame restarts the dynamic transition and the clip never advances (reads as a character frozen mid-pose while every Inspector value looks correct)
  8. CrossFadeInFixedTime over CrossFade — CrossFade’s duration is normalized against the current state’s length, so one number means a different wall-clock fade per source state
Assets/
├── Animations/
│ ├── Controllers/ # .controller assets
│ ├── Clips/ # .anim assets
│ ├── Rigging/ # RigBuilder, constraint prefabs
│ └── Behaviors/ # StateMachineBehaviour scripts
└── Timeline/ # .timeline assets
  • t1k-unity-rendering-cinemachine — Animation-driven cameras (Timeline)
  • t1k-unity-rendering-vfx-graph — Animation-triggered VFX
  • t1k-unity-base-input-system — Input-driven animation parameters
  • t1k-unity-dots-rendering-graphics — ECS rendering (use t1k-unity-dots-core-implementer agent)
FileContents
references/mecanim-guide.mdBlendTree types, root motion, AnimationEvents, StateMachineBehaviour, IK Rigging, performance, gotchas
references/playable-timeline-guide.mdPlayable graph, custom PlayableBehaviour, Timeline tracks, SignalTrack, runtime binding, gotchas
references/animator-mapping-view-split.mdPure mapping + thin view split, injected dt/Random for testability, StringToHash + DisposableBag view shape, InjectGameObject DI delivery, animator.speed = 0f freeze, edge-only crossfade, pooled resets, checklist

A visible change made with this skill (UI, sprites, 3D, shaders, VFX, animation, lighting, scene layout; audio excluded) follows core rule visual-change-discord-notice:

  • Capture OLD before the first edit and NEW after the last (screen: ScreenCapture in Play mode per t1k-unity-editor-cli, windowed or Xvfb only because rendering is needed; 3D, shader, VFX: same-scene frame grab; 2D asset: the file).
  • Return the paths and a draft Discord post to the orchestrator, which posts; the PR links the post or carries visual-notice-waiver: <reason>. Logic only: “no visible change”. No capture: “screenshots pending: ”, never a fake image.