Docs: DR-052 SoD facing + underwater feel — build spec, session log, gotchas archive 07-16, skinned-kit cookbook recipe, CLAUDE.md facing contract (net-zero condensations)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-16 00:54:53 -07:00
parent 4fa2cb0de4
commit a083e77a9e
6 changed files with 207 additions and 9 deletions
@@ -267,3 +267,27 @@ The direction that landed (operator-approved): **the interest lives in the LIGHT
 ### Posed STATIC hero bake (style-proof placement without the Rukhanka pipeline)
 To drop a posed suit/creature into the staging scene as a static mesh (skinned Rukhanka bake is separate `/dots-dev` work): in Blender — **apply the `Armature` modifier** on each skinned mesh (bakes the current pose into geometry), **`visual_transform_apply` + clear constraints** on bone-parented kit (eyes/lamp Child-Of), then export a static glb (meshes only, no armature). ⚠ both `modifier_apply` and `export_scene.gltf` need the **window `temp_override`** after `open_mainfile` (context.active_object). Import via `import_model_file`, `InstantiatePrefab` at the slot — glTFast carries the embedded materials (Synty atlas + emission).
 ```
+
+## 12. Skinned attachment kit → existing Unity rig (proven 07-16, Bathynaut dome/tank/lamp)
+
+Rigid accessories that must RIDE an already-in-engine Rukhanka rig (helmet, packs, lamps). Full failure-chain + Unity-side detail: gotchas archive 2026-07-16 + [[DR-052_SoD_Facing_Underwater_Feel]].
+
+```python
+# 1. BIND (non-destructive, saved into the master): per piece — one vgroup named for the target
+#    bone, ALL verts weight 1.0, + an Armature modifier. Pieces stay editable.
+o.vertex_groups.new(name="Head").add(range(len(o.data.vertices)), 1.0, 'REPLACE')
+o.modifiers.new("Armature", 'ARMATURE').object = ARM
+# 2. JOIN copies per SHADER ROLE (palette brass vs emissive glow) -> 2 export meshes, vgroups merge by name.
+# 3. EXPORT — ★ UNHIDE THE ARMATURE FIRST: a hidden armature can't be selected and the FBX
+#    exports SILENTLY SKINLESS (static meshes, no vgroups). Restore hidden after.
+ARM.hide_set(False)
+bpy.ops.export_scene.fbx(filepath=out, use_selection=True, object_types={'ARMATURE','MESH'},
+    apply_scale_options='FBX_SCALE_UNITS', apply_unit_scale=True, add_leaf_bones=False, bake_anim=False)
+```
+
+Unity side (`PlayerRigTools.AttachBathynautKit` / `GraftSmr` is the reference implementation):
+- Rebind `smr.bones` by NAME onto the target skeleton (Blender dedup suffixes `.001` → strip to base name; safe when the kit only weights unambiguous bones).
+- **REBASE, never reuse bindposes**: a Blender FBX roundtrip imports cm bones under a 0.01 armature (regardless of scale option) while Synty-native rigs are meter-scale → raw bindpose reuse renders ×100 off. Bake verts to rest-world; bindposes = `Matrix4x4.TRS(m.GetColumn(3), m.rotation, Vector3.one).inverse` (RIGID, scale-stripped).
+- **`mesh.RecalculateTangents()` is mandatory** — a tangent-less procedural skinned mesh fails Rukhanka/BRG registration (`BatchMeshID not present`) and the WHOLE rig disappears.
+- Persist rebased meshes as `Rebased_*.asset` (Clear+refill an existing asset = GUID-stable re-runs).
+- Emissive pieces: `ProjectM/EmissiveGloamSkinned` (hand-written HLSL + Rukhanka `ComputeDeformedVertex`; the DOTS-instanced `_DeformedMeshIndex` block must be declared BEFORE the include, and the property must ALSO be in the Properties block for the baker's `HasProperty` validation). BRG-only: invisible in plain classic scenes, correct in the baked ECS world.