kronic/Project-M
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: DR-022 animation pipeline + /dots-dev commit phase

Browse Source 
DR-022 + session log for the Rukhanka/Synty player-animation slice; CLAUDE.md stack row + Animation (Rukhanka) build gotchas + client asmdef refs; add Phase 10 (operator-approved commit) to the dots-dev skill.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Luis Gonzalez
2026-06-06 18:18:14 -07:00
parent 951b7ec273
commit 1e23246568
4 changed files with 126 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+13 -1
View File
@@ -17,6 +17,7 @@ Multiplayer game on **Unity DOTS (Entities) + Netcode for Entities** — server-
| `com.unity.transport` | 2.7.2 | (transitive) |
| `com.unity.burst` | 1.8.29 | (transitive) |
| `com.unity.mathematics` | 1.3.3 | (transitive) |
| `com.rukhanka.animation` | **2.9.0** | Local pkg (`Packages/com.rukhanka.animation`). ECS skeletal animation (Burst CPU/GPU skinning). Declares entities.graphics 1.4.16 → resolves on 6.4.0 via SemVer floor. Netcode replication **OFF** → client-derived. See [[DR-022_Animation_Pipeline_Rukhanka_Synty]]. |
Values match `packages-lock.json` (reconciled 2026-06-02; URP 17.4.0, test-framework 1.6.0, ugui 2.0.0, multiplayer.center 1.0.1). **History:** briefly tried **6.6.0a6** (renumbers Netcode→6.6.0/Physics→6.5.0/Entities→6.5.0) but its Netcode/Transport runtime is a **confirmed engine bug** ("invalid wrapped network interface") → reverted. If returning to 6.6, expect the renumber + re-test runtime. See [[DR-002_Unity66_Alpha_Netcode_Transport]] and `Docs/Vault/_Meta/CLAUDE_Build_Gotchas_Archive.md`.
@@ -27,7 +28,7 @@ Root namespace: **`ProjectM`**. Code lives under `Assets/_Project/Scripts/` in f
| Assembly | Namespace | Runs in | References |
|---|---|---|---|
| `ProjectM.Simulation` | `ProjectM.Simulation` | **client + server** worlds | Entities, **Unity.Transforms**, Collections, Mathematics, Burst, Unity.Physics, Unity.NetCode |
| `ProjectM.Client` | `ProjectM.Client` | client world only | + Simulation, Unity.Entities.Graphics, **Unity.InputSystem**, Unity.Transforms |
| `ProjectM.Client` | `ProjectM.Client` | client world only | + Simulation, Unity.Entities.Graphics, **Unity.InputSystem**, Unity.Transforms, Unity.NetCode, **Unity.Physics + Unity.CharacterController** (KinematicCharacterBody source-gen), **Rukhanka.Runtime** (animation) |
| `ProjectM.Server` | `ProjectM.Server` | server world only | + Simulation, **Unity.Transforms**, Unity.NetCode |
| `ProjectM.Authoring` | `ProjectM.Authoring` | bake time (+ scene runtime) | Simulation, Entities, **Unity.Entities.Hybrid**, Collections, Mathematics, Unity.NetCode |
@@ -104,6 +105,17 @@ Long-form originals + the milestone each came from: `Docs/Vault/_Meta/CLAUDE_Bui
- **Active scheme = last-meaningful-actuation-wins, replicated as `byte`** (`PlayerInput.Scheme`, KBM=0/Gamepad=1 — byte because compared in Bursted `AbilityFireSystem`). Server gates the `AutoTarget` cone to gamepad only → precise mouse, gamepad-only assist.
- **Cursor/reticle = client `PresentationSystemGroup` `SystemBase` (`AimReticleSystem`) that OBSERVES.** Re-raycast the KBM ground point INSIDE that system (PresentationSystemGroup runs after the follow-cam's LateUpdate) — latching from the gather drifts a frame behind. Hardware cursor hidden while aiming + focused, restored on focus-loss/`OnDestroy`.
### Animation (Rukhanka) ★
Full rationale: [[DR-022_Animation_Pipeline_Rukhanka_Synty]]. Skeletal animation = **Rukhanka 2.9** (Entities-native; the only maintained option on the 6.4 stack — Latios/Kinemation isn't 6.4-compatible, Unity's official ECS-animation is vaporware). **Netcode replication OFF** (`RUKHANKA_WITH_NETCODE` undefined) → animation is **client-derived**: a client-only `SystemBase` (`PlayerAnimationDriveSystem`, `[WorldSystemFilter(LocalSimulation|ClientSimulation)]` + `[UpdateBefore(RukhankaAnimationSystemGroup)]`) reads replicated state and writes params via `AnimatorParametersAspect`/`FastAnimatorParameter`. No new `[GhostField]`s; no `DefaultVariant` strip (with the define off, no Rukhanka component is a ghost component → ghost hash/snapshot unchanged).
- **The rig must bake on the SAME entity that holds the gameplay components the drive job reads.** Rukhanka puts the param buffer + index-table on the GO with `RigDefinitionAuthoring`, so put `Animator` + `RigDefinitionAuthoring` on the **player root** (not a child) and flatten the skeleton + SMRs under it — else the single-entity drive query matches nothing.
- **CPU engine still skins via Entities-Graphics GPU deformation → needs a deformation-aware material** (`AnimatedLitShader`, a multi-target ShaderGraph that includes a `UniversalTarget`; Synty atlas → its `_BaseColorMap`). Stock URP/Lit renders **unskinned static** + a `"does not support skinning"` warning — NOT magenta (magenta = reusing an HDRP sample `.mat`).
- **Importing the Rukhanka "Animation Samples"** (the only source of `AnimatedLitShader`) drags in 26 sample **subscenes** (one NRE's Rukhanka's **unguarded clip baker** — `AnimationClipBaker.ReadCurvesFromTransform` reads a null bone Transform on a missing-bone clip), sample **systems that run in your worlds**, and a conflicting **TextMesh Pro** folder. Fix: `MoveAsset` the 3 deformation ShaderGraphs to `_Project/Shaders/` (GUID-preserving → material ref intact), then delete the samples tree.
- **First Rukhanka bake is ~60 s, synchronous on the main thread** (editor telemetry freezes → looks like a hang, isn't); the animation blob is cached after → fast re-plays.
- **The server runs Rukhanka unless you strip it** — its **deformation** systems use `[WorldSystemFilter(Default)]` (Default ⊇ ServerSimulation) so they run on the server's baked bones/meshes (the animation group is created server-side too but left empty by the bootstrap). **`ServerStripAnimationSystem`** (server-only one-shot, `[WorldSystemFilter(ServerSimulation)]`) disables every `Rukhanka.Runtime` system on the server (disabling a group cascades to its children; matched by assembly name → no type ref). *Only Play-validation caught this — the static `WorldFlags` read said the server was clean; it wasn't.*
- **Build the controller via the `AnimatorController` API** (`manage_animation` silently drops enum/Vector blend-tree fields). **Skeleton-root detection = walk up from a bone to the soldier's direct child**, NOT `SkinnedMeshRenderer.rootBone` (that's the *bounds* root — the head SMR's is `Spine_03`; using it destroys the lower skeleton).
- **Synty Polygon characters share one Generic skeleton**; the FBX needs **Optimize Game Objects OFF** (Rukhanka requirement; SciFiSpace was already so). Entity origin = capsule **center** (~1 m up) → offset the **un-keyed `Root` bone** local Y (clips key no Root/Hips position → Rukhanka bakes the offset as a constant → it persists through animation). Root motion **OFF** (the CC owns the transform; the blend tree is velocity-driven).
- **`Unity.Physics` must be a DIRECT asmdef ref** for any system whose source-gen touches `KinematicCharacterBody` (it nests `Unity.Physics.ColliderKey`) → else CS8377/CS0012 in `*.g.cs` (same class as the `Unity.Transforms` direct-ref rule).
### MCP / editor workflow ★
- **Edit Assets `.cs` ONLY via MCP `apply_text_edits` / `create_script`** (Unity's scripting pipeline) — the raw `Write` tool does NOT reliably trigger a recompile on an unfocused editor → tests/`execute_code` run a **stale assembly**. A raw-`Write`-created NEW `.cs` is worse — it gets **no `.meta` / no test-discovery** until `refresh_unity scope=all mode=force` (it compiles, but EditMode silently won't run it). (`Write`/`Edit` are fine for non-asset files: this vault, asmdef JSON, etc.) For comment/string-precise edits to existing scripts, `script_apply_edits` **`anchor_replace`** (regex anchor) + **`delete_method`** work cleanly even on a `struct : ISystem` (unlike `replace_method`).
- **`apply_text_edits` with MULTIPLE non-adjacent edits in one call can MISALIGN** (a paired replace+delete hit the line *above* the target). One edit per call (or strict bottom-first), always with `precondition_sha256` (it returns the current SHA on mismatch). **`create_script` won't overwrite** an existing path; full-file rewrites = whole-span `apply_text_edits` (its brace-balance validator guards botched spans) or `manage_script delete`+`create_script` (NON-GUID-referenced files only — systems/tests, never authoring MonoBehaviours). `script_apply_edits replace_method` is safe for class methods but still **can't target a `struct : ISystem`** (use whole-span). [[DR-017_Persistent_Base_Player_Driven_Pacing]]