t1k:unity:animation:core
| Field | Value |
|---|---|
| Module | animation |
| Version | 3.33.4 |
| Effort | high |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:animation:coreUnity Animation System
Section titled “Unity Animation System”Core Systems
Section titled “Core Systems”| System | Use When |
|---|---|
| Mecanim | Character locomotion, state machines, blend trees |
| Playable API | Runtime blending without AnimatorController, procedural animation |
| Timeline | Cinematic sequences, choreographed events, cutscenes |
| Animation Rigging | IK (arm/leg), head tracking, weapon aiming (post-bake pose) |
Animator — Quick API Reference
Section titled “Animator — Quick API Reference”Animator anim = GetComponent<Animator>();
// Parametersanim.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);
// Querybool inRun = anim.GetCurrentAnimatorStateInfo(0).shortNameHash == Animator.StringToHash("Run");float progress = anim.GetCurrentAnimatorStateInfo(0).normalizedTime;
// Layer blendinganim.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, andRandomare passed IN as parameters, never called inside — that is what makes the decisions unit-testable in an EditMode assembly with no scene and noAnimator.<Name>AnimatorView— thinsealed MonoBehaviour. Owns only Unity handles:static readonly intparameter hashes, the previous-frame floats the mapping is stateless about, and an[Inject] Constructthat builds aDisposableBagdisposed inOnDestroy.
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.
Playable API — Quick Setup
Section titled “Playable API — Quick Setup”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.
Hard rules
Section titled “Hard rules”- Trigger auto-reset —
SetTrigger()resets after one frame; call once per input event - Hash parameters — use
Animator.StringToHash("name")for per-frame reads, not raw strings - graph.Destroy() mandatory — leaks GPU/CPU resources if skipped
- Root motion conflict — disable NavMesh/CharacterController when
applyRootMotion = true - Animator.Rebind() expensive — avoid at runtime; Instantiate prefab instead
- Timeline vs Animator conflict — playing both simultaneously causes flickering; pause Animator when Timeline takes over
- Crossfade on the state EDGE only — re-issuing
CrossFadeInFixedTimeevery frame restarts the dynamic transition and the clip never advances (reads as a character frozen mid-pose while every Inspector value looks correct) CrossFadeInFixedTimeoverCrossFade—CrossFade’s duration is normalized against the current state’s length, so one number means a different wall-clock fade per source state
File Organization
Section titled “File Organization”Assets/├── Animations/│ ├── Controllers/ # .controller assets│ ├── Clips/ # .anim assets│ ├── Rigging/ # RigBuilder, constraint prefabs│ └── Behaviors/ # StateMachineBehaviour scripts└── Timeline/ # .timeline assetsRelated Skills
Section titled “Related Skills”t1k-unity-rendering-cinemachine— Animation-driven cameras (Timeline)t1k-unity-rendering-vfx-graph— Animation-triggered VFXt1k-unity-base-input-system— Input-driven animation parameterst1k-unity-dots-rendering-graphics— ECS rendering (uset1k-unity-dots-core-implementeragent)
Reference Files
Section titled “Reference Files”| File | Contents |
|---|---|
references/mecanim-guide.md | BlendTree types, root motion, AnimationEvents, StateMachineBehaviour, IK Rigging, performance, gotchas |
references/playable-timeline-guide.md | Playable graph, custom PlayableBehaviour, Timeline tracks, SignalTrack, runtime binding, gotchas |
references/animator-mapping-view-split.md | Pure 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 |
Visual change notice
Section titled “Visual change notice”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:
ScreenCapturein Play mode pert1k-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.