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 `DanceType`s 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.