jeremy
e08ad2f3e9
NAMING.md/AUDIT.md/UNWIRED.md are the conventions-doc pivot after the mass-rename was killed; committing so the bridge repo tree is clean. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
224 lines
11 KiB
Markdown
224 lines
11 KiB
Markdown
# 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.
|