animation/docs/animations/UNWIRED.md

Unwired Animations — GDD vs. Animation Controller Gap Analysis (2026-07-24)

Cross-references what the GDD design calls for against what the production animation controller actually wires (PlayerController.SetupAnimations() + CharacterAnimDriver + ToolActionResolver + ThrowActionCatalog + graph builder). Companion to AUDIT.md (which covers disk-vs-wired). This doc answers: of the animations the design needs, which are missing from the game?

Method: GDD shot-list (GDD.md + GDD_TODO + tech-tree colonist-tasks.json) ∩ controller trace. Every "wired" claim is code-anchored; see AUDIT.md §7 for files.

Gap types

• MISSING — GDD needs it; no clip loaded and no trigger path. Author + wire.
• DEAD — clip is already loaded in SetupAnimations() but nothing triggers it. Cheap win: only needs a driver/trigger case, no new art.
• COLLAPSED — GDD wants N distinct animations but they all resolve to one clip (biggest offender: 12 dance types → 1 Dance_Loop). Needs per-variant clips + mapping.

---

The big picture

The production animator wires ~55 game-keys off 9 GLB packs. Against the GDD's design surface (~80 colonist tasks, 12+ dances, boat wayfinding, survival states, combat reactions) there are three structural holes:

1. The signature mechanic is one clip. All 12 sim DanceTypes and every ceremony collapse to the single dance key (UAL1 Dance_Loop). 6 of the 12 aren't even exposed in the client UI. This is the largest gap by design weight.
2. The colonist economy is visually collapsed. ~80 tasks map to ~8 work clips; whole task families (animal husbandry, water/weed/compost, carry modes, star observation) have no distinct animation.
3. No survival/reaction layer. Wounded, hungry, hit-reaction, celebration — none wired, despite the Valheim-style needs model being core to §9.

---

1. Dance & Ceremony — SIGNATURE MECHANIC (highest priority)

Wired: dance (UAL1 Dance_Loop) — one clip, played for every DanceType. pray (Kevin Reverence01_Loop) for worship.

Animation	GDD	Gap	Note
Water Dance	§1/§25	COLLAPSED	→ generic dance
Fire Dance	§1/§25	COLLAPSED	→ generic dance
Moon/Tide Dance	§1/§25	COLLAPSED	naming drift: sim=RainDance, TSK=Tide, icon=tidedance (dead branch)
Fertility Dance	§1/§25	COLLAPSED	asset exists (fertility_dance_01) in test-bed only, not wired to avatar
Food Dance	§1/§25	COLLAPSED	→ generic dance
Taming Dance	§1/§25	COLLAPSED	asset exists (taming_dance_01) test-bed only
Rain Dance	§25/§13	COLLAPSED	→ generic dance
Sailing Dance	§1 (Age 2)	COLLAPSED + not in client UI	sim-only DanceType
War Dance (Haka)	§1/§28i	COLLAPSED + not in client UI	assets exist (war_dance_01, hakadance1_static) test-bed only
Building Dance	§1 (Age 2)	COLLAPSED + not in client UI
Colony Shield Dance	§1 (Age 2)	COLLAPSED + not in client UI
Age Progression Dance	§1 (Age 3)	COLLAPSED + not in client UI
Star Watching Dance	§8f (Age 3)	COLLAPSED + not in client UI
Christening Solo	§10 (ends Act 1)	MISSING	bespoke solo ceremony
Dance-off attack/defend moves (QWEASD)	§23/§25	MISSING	rhythm-combo move set — core to PvP dance-off
Dance-off power-up / bonus moves	§23	MISSING	potion/food/artifact-unlocked
Body percussion / clapping / thigh-slap	§13	MISSING	in test-bed composites only, no production path
Instrument-play-during-dance	§25/§13	MISSING	drum/conch/flute buff pose
Colonist formation choreography	§1/TODO	MISSING	colonists perform in formation

Client/sim mismatch (confirmed): sim DanceType = 12 (GameSystems.cs:151); client DancePanel.cs:11 exposes 6. Even the exposed 6 all play one avatar clip.

---

2. Work / Tools / Colonist Economy

Wired distinct work clips: chop, mine, fish, gathering (Farm_Harvest), farm (PlantSeed), hammer/build (Fixing_Kneeling), interact, weapon_attack, hold.

DEAD (loaded, no trigger — cheap wins)

Key	Clip	Note
skin	SkinningGround01_R_Loop	GDD needs skinning bench (§skin); no CharacterAnimDriver case
watering	Farm_Watering	GDD §2a "water crops"; colonist farm never routes to watering
carry	Walk_Carry_Loop	GDD §19 carry modes; test-bed only in production
sit	GroundSit_Idle_Loop	no player/colonist case

MISSING (no clip)

Animation	GDD / TSK	Note
Hoe / till land	§2a, TSK	field prep
Weed	§2a "colonists weed"	field tending
Compost	TSK	fertility upkeep
Tend irrigation / terraced gardens	TSK	paddy/terrace upkeep
Feed chickens / pigs	§2d, TSK	pen feeding
Collect eggs	TSK	coop gather
Herd animals	TSK	drive livestock
Milk goats	TSK	milking pose
Shear animals	TSK	shearing pose
Breed animals	TSK	pen interaction
Tend kennel (dogs)	TSK	care pose
Tend pearl oyster bed	TSK	shore/underwater tend
Dive for shells/coral	§27, TSK	underwater gather (swim exists; no gather-underwater)
Shell open/close timed grab	§27 shell mechanic	timed reach
Cook (dedicated)	§29b/c	currently routes to generic interact
Backpack crafting (player, no bench)	§6	craft key never loaded → pulse placeholder
Bench crafting (generic, 12 benches)	§8j	PlayCraft/PlayBuild fall through to placeholder pulse
Rebuild ruins (Spirit Temple / Dance Arena)	§8f	restoration work
Fuel HQ	TSK, §10	feed the hearth
Stock birdhouse / collect feathers	§8l	charisma chain
Operate trade building	§15c	trade-post interaction
Load / unload trade canoe	TSK	dock cargo
Observe stars / stick-chart trace	§8f	sky-watch tracing minigame

COLLAPSED

GDD wants	Reality
gather coconuts/bamboo/vines/flint/shells/starfish, forage berries/herbs/lotus	all → gathering (Farm_Harvest)
multi-level directional chop (5 wedges, 4 facings — flagship visible-work, §4a)	single chop loop
Carry modes: EquipHand / TwoHandCarry / ShoulderCarry / plate-tray (§19)	none — carry clip loaded but dead

---

3. Combat

Wired: punch, run_punch, throw (OverhandThrow), spear/axe/ball throws (Kevin, via ThrowActionCatalog), shield_block, weapon_attack (Sword_Attack), death.

DEAD (loaded, no trigger)

sword_block, melee_light_combo, shield_idle, shield_break, shield_dash, shield_sprint, swim_drown, swim_drowned, swim_left, swim_right.

MISSING

Animation	GDD	Note
Hit reaction / stagger	§5a-ii, §5b	player + enemy take-damage — nothing wired
Enemy / spirit attack set	§5a/§5b	humanoid-rigged spirits, ≥1 attack each
Retrieve thrown spear (walk-over pickup)	§5a-ii	ground-item recovery beat

COLLAPSED

7+ weapon types (spear/axe/knife/club/trident/adze/biface) → one Sword_Attack thrust. (May be acceptable; flag for weapon-feel pass.)

---

4. Boat / Canoe / Voyage

Wired: canoe_sit (helm idle), canoe_dismount, run_to_dive, swim.

Animation	GDD	Gap
Paddle (active propulsion)	§3, §10	MISSING — only seated idle
Seat-switch between roles	§3, TODO §7	MISSING
Wayfinding: star reading	§3/§24	MISSING
Wayfinding: swell reading	§3	MISSING
Wayfinding: bird following	§3/§24	MISSING
Wayfinding: storm navigation	§3	MISSING
Colonist crew / sail (autonomous)	§3, TSK "Sail"	MISSING

(Voyage is sim-resolved, so these are posed beats, not a steering controller.)

---

5. Emote / Social / Interaction

Wired: pray only. No emote wheel / emote input exists in production.

Animation	GDD	Gap
Shrine offering (kneel/offer)	§8b	MISSING
Kava ceremony	§16	MISSING
Meditate (god-mode, vulnerable)	TODO §12	MISSING
Greet / elder first-contact	§10 tutorial	MISSING
Talk to colonists	§10 tutorial	MISSING
Feast / first-feast celebration	§10 arc	MISSING
Sit	§social	DEAD (clip loaded, no trigger)

Note: kevin_*_social clips (HandClap, Cheer, HandWave, Angry, Dance01-13) are reachable only through the test-bed JSONs — no production path.

---

6. Locomotion & Reaction States

Wired loco is strong: idle, 8-dir walk/jog, sprint(+enter/exit), 8-dir crouch, turns, jump, running_jump, full swim set.

Animation	GDD	Gap
Wade (50%-speed shore water)	§27 zone 2–4m	MISSING
Idle variants / fidget	§9c, disconnect-idle	MISSING — one idle only
Idle-at-hearth cluster	§10	MISSING
Crouch enter / exit	—	DEAD (loaded; SetCrouching plays idle/walk directly)
Wounded / low-health degraded	§5a-ii, §9	MISSING
Hungry / thirsty posture	§9a needs	MISSING
Low-mana / low-morale	§25	MISSING
Celebration	§10 feast, §22 victory	MISSING
Persist-as-idle-figure (disconnect)	§Recent	partially — reuses idle

(No cold state — tropical setting; correctly absent.)

---

Priority ranking (studio lens)

1. Per-dance choreography + dance-off move set — the marquee feature is a single looping clip. Author 12 dance clips + the QWEASD attack/defend moves + Christening Solo. Also fix the sim(12)↔client(6) DanceType mismatch and dead tidedance icon branch.
2. Colonist work legibility — animal husbandry family, water/weed/compost, carry modes, cook, star observation. "Real swings at real trees" is a named selling point (§Recent); right now most of the economy plays 8 clips.
3. Survival/combat reaction layer — hit-reaction, wounded, hungry, celebration. Core to the Valheim needs model but invisible.
4. Boat wayfinding poses — 4 wayfinding beats + paddle + crew.
5. Quick wins (DEAD clips — wiring only, no new art): skin, watering, carry, sit, crouch_enter/exit, sword_block, melee_light_combo, shield set, swim_drown*.

---

Notes / caveats

• "COLLAPSED" is a design call, not always a defect (weapon variants, forage variety may be intentionally shared). Dance collapse is unambiguously a gap — it's the signature.
• The assets/dances/*.json test-bed dances (haka_tutorial, war_challenge, etc.) are authoring/preview only; they have no code path to the in-game player or colonist.
• Several dance assets already exist in dancegen/ (fertility/taming/war) but are wired only to the test-bed, not to the production avatar. Bridging that is cheaper than authoring.