Epic: Robust custom enemy/boss 3D-model pipeline (editor-free, in-game verified)

[jarlbrak]

Vision

A documented, repeatable, editor-free method to give any custom FTK enemy a custom 3D body that renders CORRECTLY in-game: a single coherent body (not a shattered triangle cloud), correctly scaled, upright and centered where the enemy stands and its health bar floats, skeletally animating without crumpling, and recognizable as the intended creature. The driving proof case is the Hollow Mire boss "Mudwretch Foreman" (ftkmf_mudwretch_foreman), a reskin of the vanilla enTroll01 troll. Everything stays visual-only: co-op-deterministic, save-safe, no new networked or serialized state, ids via IdAllocator.

Motivation

The prior session proved a custom boss body can be loaded and skinned at runtime, but it also exposed a chain of failure modes that must not recur. They become the hard constraints and the gates for this epic:

1. Swapping SkinnedMeshRenderer.sharedMesh on the already-initialized vanilla SMR leaves Unity 2017.2 skin buffers bound to the OLD mesh, so new vertices skin from stale data and explode. (Fix found and kept: render on a brand-new SMR that shares the live skeleton and disable the original, EnemyVisualPatch.BuildFreshSkin.)
2. Rigid single-bone weighting stops the shatter but the body rigidly follows one bone and crumples under animation. Real multi-bone weights are required.
3. Nearest-surface weight transfer from the troll produces imperfect weights (head verts bleed to Chest_M, arm-end verts to Hip_L / finger bones), giving a folded, hunched deformation.
4. Placement and scale are unreliable: the body renders small and off-center ("nothing where the boss should be"). It must appear upright, correctly scaled, and centered at the combat position.
5. The TRELLIS AI-generated mesh is low-poly and the mud texture is flat (a real quality ceiling). For this epic the art bar is correctness-first; fidelity uplift is a separate later effort.
6. Prior "it is fixed" claims came from judging zoomed crops. Pass/fail must come from a full-frame check against objective criteria, not a hand-picked zoom.

This is the rendering-pipeline foundation under the Custom Campaign Platform (epic #5) and the Hollow Mire work (spec #57, work items #61 and #62): without a fool-proof custom-body method, bespoke bosses cannot reliably look like themselves.

Scope

In scope

• Editor-free authoring of custom enemy bodies (Blender plus Python scripts only).
• Rigging against the exact enTroll01 skeleton and bind pose (37 bones, bind is itself a T-pose) with clean multi-bone weights and a validated bind-pose match.
• Runtime loading and fresh-SMR skinning, keeping the BuildFreshSkin shatter fix.
• Placement, scale, and orientation correctness at the enemy combat position (upright, centered under the health bar, correctly scaled).
• An offline preview rasterizer plus an automated in-game full-frame visual gate with objective pass criteria.
• A spike comparison of approaches A, B, and C against the same gate, ending in one chosen path with recorded rationale.
• The Mudwretch Foreman as the proof and acceptance case.
• End-to-end documentation of the repeatable method.

Out of scope

• Unity-editor-dependent authoring as the primary path. Approach A (AssetBundle) is retained only as a documented reference/fallback while the editor-free constraint stands.
• Raising mesh or texture fidelity beyond "recognizable and correct" (art-quality uplift is a future, separate effort).
• New gameplay, combat behavior, stats, or networked state for the boss (visual-only).
• Authoring new animation clips; reuse the troll's existing animation set.
• Hot-reload or asset streaming (co-op forbids non-identical mods).
• Generalizing beyond skeletal, troll-based reskins past what the documented method naturally covers (a future epic).

Success Criteria

• The Mudwretch Foreman renders in-game and PASSES the automated full-frame visual gate: a single connected body (no triangle cloud), upright, centered under its health bar, correctly scaled relative to the troll skeleton, recognizable as a mud/bog creature.
• The body skins under animation across at least one full combat idle and attack cycle without crumpling, folding, or hunching (multi-bone weights validated).
• Pass/fail is produced by the agent-harness full-frame screenshot check against documented objective criteria, reproducible across runs (not a zoomed crop).
• An offline rasterizer preview predicts the in-game pass/fail before the game is launched (preview and in-game result agree).
• All three approaches are evaluated against the same gate and a single path is chosen with recorded rationale and ftk-architect sign-off.
• A second custom enemy can be given a custom body by following the documentation alone, editor-free.
• Stays visual-only and deterministic: no new networked/serialized state, ids via IdAllocator; framework builds in Release and logs SELF-TEST PASS.

Child Specs

• Spec: Visual-verification gate (Spec: Visual-verification gate (objective in-game PASS/FAIL for custom enemy bodies) #66) -- offline rasterizer preview plus an automated agent-harness full-frame in-game screenshot check, with objective pass criteria (connected, upright, centered under health bar, scaled, recognizable). The measuring instrument, built first.
• Spec: Approach spike and bake-off -- the spike runs per approach against the same gate, starting with B. Decomposed into per-approach specs rather than one combined bake-off:
  • Spec: Runtime-glTF approach spike (B) (Spec: Runtime-glTF approach spike (B): coherent in-game boss body, gated to PASS or pivot #72) -- fix the runtime skinned-mesh reconstruction shatter so the Mudwretch Foreman reaches a gate four-criterion in-game PASS with offline/in-game agreement; carries an objective pivot clause (if the gate proves B cannot be made robust editor-free, recommend A or C). Run first because the loader and the BuildFreshSkin-shaped fix are closest to hand.
  • Spec: AssetBundle approach spike (A) -- reference/fallback under the editor-free constraint (only if B pivots).
  • Spec: Procedural on-skeleton approach spike (C) -- alternative path judged by the same gate (only if B pivots).
• Spec: Chosen-pipeline implementation -- harden the winning path end to end (clean multi-bone weights, bind-pose match, loader, keep BuildFreshSkin); produce the Mudwretch body asset.
• Spec: Placement, scale, and animation correctness -- guarantee upright, centered, correctly scaled, and crumple-free skinning under the troll's animations at the combat position.
• Spec: Pipeline documentation and repeatability -- update docs/AI-MODEL-PIPELINE.md into a repeatable editor-free method for any custom enemy body, with the Mudwretch Foreman as the worked example.

Dependency Graph

graph TD
    A[Spec: Visual-verification gate] --> B[Spec: Approach spike and bake-off]
    B --> C[Spec: Chosen-pipeline implementation]
    C --> D[Spec: Placement, scale, and animation correctness]
    C --> E[Spec: Pipeline documentation and repeatability]
    D --> E

Loading

Open Questions

• Editor-free vs Approach A: AssetBundle baking generally requires the Unity editor. Is A evaluated only as a documented reference/fallback (likely disqualified for the primary path), or is there an acceptable editor-free bundle-baking route? (Resolve in the spike spec.)
• What exact numeric thresholds define "centered" and "correctly scaled" in the full-frame screenshot (pixel bounding box vs health-bar anchor; body-height ratio to the troll)? (Pin tolerances in the visual-gate spec.)
• Source mesh under correctness-first: keep the current TRELLIS mesh, or substitute a cleaner editor-free source mesh if rigging the blocky mesh cannot reach "recognizable"? (Decide in the chosen-pipeline spec.)
• Weight-transfer method: harden nearest-surface KNN (05b_rig_numpy.py) vs a weight-diffusion/inpainting pass to fix the head-to-Chest_M and arm-to-Hip_L bleed. Which is reliable enough editor-free?
• Keep the uncommitted working-tree BuildFreshSkin fix and the real-weights mudwretch_rigged.glb as the spike-B starting point, or reset the asset side? (Recommend keeping the fix; decide the asset reset in the spike.)

[jarlbrak]

Spec #72 (runtime-glTF spike, approach B) concluded: B is ROBUST for reconstruction

Verdict (FR-6): runtime-glTF (B) can build a coherent custom boss body editor-free. The Mudwretch Foreman now renders in-game as a single coherent hulking golem (was an exploded triangle cloud). Root cause was a missing SMR skin rebind (fixed: reassign smr.bones after the sharedMesh swap) plus ~145 degenerate sliver triangles from the offline rig (cleaned via tools/ai-model-pipeline/06_clean_slivers.py). Decode/loader were proven sound. No pivot to A (AssetBundle) or C (procedural) is needed for the reconstruction problem.

The full four-criterion visual-gate PASS was NOT reached, but for reasons ORTHOGONAL to A/B/C (they would affect any approach equally), so they do not change the approach verdict. These are carried forward to this epic's "Placement, scale, and animation correctness" child:

1. In-place boss scaling. The combat body is a fresh scale-1.0 clone; the registered EnemyVisual.scale (CEL-root) is the single scale authority. To grow the boss without off-frame drift it must be scaled feet-anchored (Root_M), not via a compounding inner seam.
2. scaled gate band is stock-troll-specific. The band (height [1.20,1.65], area [1.45,2.60]) encodes the bulky troll silhouette; the slimmer AI golem tops out ~1.0 area_ratio even fully detected. Needs per-chassis calibration (or a shape-normalized metric).
3. In-game silhouette gate is scene/pose dominated. On the SAME coherent mesh, connected component count swung 1..5 and upright 7deg..65deg across runs (doorway vegetation segmented as extra components + dark-armor noise + combat pose). Needs fixed-pose capture or boss-region scene masking to track coherence reliably.
4. (optional) Re-enable real multi-bone weights (was Task: Optional - re-enable multi-bone weights and confirm the gate still passes (#72 Phase 4, P2) #76) together with the offline-rig weight-transfer hardening.

Evidence + full writeup: docs/spike-72-artifacts/SPIKE-72-FINDINGS.md on campaign-d1-hollow-mire. NFR-4 honored (spec #66 gate unchanged).