EN-055: animation instancing + staged-commit aux-texture/normal-kind fixes

[proggeramlug]

Implements EN-055 (engine#106) and fixes the two staged-path bugs its consumer hit.

instantiateAnimation

ModelAnimation's parsed clip data (skeleton, keyframe tracks, rest rotations) is immutable after load — now Arc-shared, with mixer/joint state per instance. instantiateAnimation(src) allocates a new handle over the shared set. Deref coercion absorbed the refactor (zero fallout sites). AnimMixer moved to its own module — first slice of EN-052, and it pays the models.rs line-ratchet budget. FFI on all surfaces (macro + manifest + TS + web real-impl + watchOS stub); validate-ffi + check-file-lines green; 127 shared tests pass.

Measurement corrected the ticket's premise: the shooter's per-slot anim parses were 43 ms, not the 5.5 s SH-049 blamed (real cost = serial loadModel texture decode). The API is still right — crowds want instances (2–4 ms for 14 slots) — but the boot win came from fixing the staged path:

bloom_commit_model fixes (quality-critical)

• Aux-texture remap: only texture_idx was remapped; normal/MR/emissive/occlusion kept staged-local indices — the round-5 "stale aux-texture remap" bug, which silently stripped SH-046 character maps from any staged model.
• Normal-map registration kind: everything went through the sRGB/albedo register_texture; normal maps now carry is_normal (set by load_gltf_staged's material pre-walk) and register via register_texture_kind's linear/LEADR path, matching loadModel.

Verified by the consumer (shooter EN-055 PR)

Boot 8,702 → 4,372 ms (parallel stageModels + fixed commits); title capture shows the bsuit's maps pixel-faithful through the staged path; AITEST behavioral run clean.

Also

fetch-dxc.ps1 no longer claims missing DXC DLLs are non-fatal — with DynamicDxc, a missing dxcompiler.dll drops the entire DX12 backend from the wgpu instance and the broken Vulkan surface path turns that into a boot crash (reproduced twice today). EN-058 severity upgraded.

Summary by CodeRabbit

• New Features

  • Added support for creating independent animation instances from loaded model animations.
  • Exposed the new animation-instantiation helper through the public API and WebAssembly interface.
  • Added improved animation state support, including crossfades, additive layers, looping, and optional root motion.

• Bug Fixes

  • Improved staged model loading so normal maps and additional material textures are preserved and applied correctly.
  • Ensured animation instances maintain independent playback state while sharing model animation data efficiently.

[coderabbitai]

📝 Walkthrough

Walkthrough

Animation instances now share parsed clip data while owning independent mixer and joint state, with new native and TypeScript APIs. Staged model textures preserve normal-map classification and remap all material texture references during commit. DXC failure documentation is corrected.

Changes

Animation instantiation

Layer / File(s)	Summary
Shared animation state and instance ownership native/shared/src/lib.rs, native/shared/src/anim_mixer.rs, native/shared/src/models.rs	AnimMixer is moved into a public module, and ModelAnimation shares parsed data through Arc while retaining per-instance runtime state.
Animation instance creation native/shared/src/models.rs	ModelManager::instantiate_animation creates a new animation handle with shared source data and fresh mixer, joint, and mask state.
Animation API wiring native/shared/src/ffi_core/models.rs, native/web/material_ffi.rs, native/watchos/ffi_stubs.rs, package.json, src/models/index.ts, src/index.ts	The new animation-instantiation entry point is wired through native, WebAssembly, watchOS, Perry, and TypeScript interfaces.

Texture staging and commit

Layer / File(s)	Summary
Normal-map staging metadata native/shared/src/staging.rs, native/shared/src/models.rs	StagedTexture records normal-map classification, and glTF loading assigns it from material references.
Texture registration and index remapping native/shared/src/ffi_core/models.rs	Model commits use kind-aware texture registration and remap all supported per-mesh texture indices.

DXC configuration documentation

Layer / File(s)	Summary
DXC failure behavior note tools/fetch-dxc.ps1	The comment documents fatal behavior when DynamicDxc is configured without the required DLLs.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant TypeScript
  participant NativeFFI
  participant ModelManager
  participant SourceAnimation
  TypeScript->>NativeFFI: bloom_instantiate_animation(src)
  NativeFFI->>ModelManager: instantiate_animation(src)
  ModelManager->>SourceAnimation: read shared animation data
  ModelManager-->>NativeFFI: create fresh runtime state
  NativeFFI-->>TypeScript: return new animation handle

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main changes: animation instancing plus staged-commit texture fixes.
Description check	✅ Passed	It includes a clear summary, verification details, and reviewer notes, though it does not follow the exact template headings.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/en-055-anim-instancing

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

package.json (1)

1186-1192: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Clear the consumer game's .perry-cache/.

As per coding guidelines, remember to clear the consumer game's .perry-cache/ directory since a new FFI function has been added to the manifest.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@package.json` around lines 1186 - 1192, Clear the consumer game's
.perry-cache/ directory after adding the bloom_instantiate_animation FFI
function to the manifest, ensuring stale generated cache data is removed before
validation.

Source: Coding guidelines

native/shared/src/models.rs (1)

505-527: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Initialize joint matrices to identity to prevent pose leaking.

If instantiate_animation is called on a source handle that is already playing, the new instance will inherit the source's current pose. This can cause a 1-frame visual pop if the new instance is rendered before its first advance_and_update call. Initializing these vectors to mat4_identity() ensures a clean rest-pose start.

♻️ Proposed fix

             Some(a) => ModelAnimation {
                 skeleton: a.skeleton.clone(),
                 animations: a.animations.clone(),
                 ref_rest_rotations: a.ref_rest_rotations.clone(),
-                joint_matrices: a.joint_matrices.clone(),
+                joint_matrices: vec![mat4_identity(); a.joint_matrices.len()],
                 mixer: AnimMixer::default(),
-                joint_world: a.joint_world.clone(),
+                joint_world: vec![mat4_identity(); a.joint_world.len()],
                 mask_weights: vec![0.0; a.mask_weights.len()],
                 mask_cached_root: -1,
             },

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@native/shared/src/models.rs` around lines 505 - 527, Update
instantiate_animation so the new ModelAnimation initializes joint_matrices and
joint_world with identity matrices sized to the source skeleton, rather than
cloning the source’s current pose; keep the shared skeleton/animation data and
fresh mixer/mask state unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@native/shared/src/staging.rs`:
- Around line 10-14: Replace the image-level is_normal tracking in the staged
texture flow with per-material-use texture-kind tracking. Update
load_gltf_staged and the commit-time registration path around
register_texture_kind so an image referenced as both normal and base-color is
registered appropriately for each usage, either by creating separate staged
entries or by propagating the role through commit; do not apply one global role
to all references.

---

Nitpick comments:
In `@native/shared/src/models.rs`:
- Around line 505-527: Update instantiate_animation so the new ModelAnimation
initializes joint_matrices and joint_world with identity matrices sized to the
source skeleton, rather than cloning the source’s current pose; keep the shared
skeleton/animation data and fresh mixer/mask state unchanged.

In `@package.json`:
- Around line 1186-1192: Clear the consumer game's .perry-cache/ directory after
adding the bloom_instantiate_animation FFI function to the manifest, ensuring
stale generated cache data is removed before validation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5cb0550d-504e-4bc4-9742-3904becd8b46

📥 Commits

Reviewing files that changed from the base of the PR and between 898cb4c and 323a6c9.

📒 Files selected for processing (11)

• native/shared/src/anim_mixer.rs
• native/shared/src/ffi_core/models.rs
• native/shared/src/lib.rs
• native/shared/src/models.rs
• native/shared/src/staging.rs
• native/watchos/src/ffi_stubs.rs
• native/web/src/material_ffi.rs
• package.json
• src/index.ts
• src/models/index.ts
• tools/fetch-dxc.ps1

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== file outline ==\n'
ast-grep outline native/shared/src/staging.rs --view expanded || true

printf '\n== relevant symbols ==\n'
rg -n "is_normal|load_gltf_staged|decode_and_stage_texture|register_texture_kind|StagedTexture|normal_texture|base_color|texture kind" native/shared/src/staging.rs native/shared/src -S

printf '\n== staging.rs excerpt ==\n'
sed -n '1,220p' native/shared/src/staging.rs

printf '\n== nearby commit/registry code ==\n'
rg -n "register_texture_kind|commit.*texture|is_normal" native/shared/src -S

Repository: Bloom-Engine/engine

Length of output: 23816

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== list files in native/shared/src ==\n'
git ls-files native/shared/src | sed -n '1,120p'

printf '\n== ast outline for candidate files that mention registration ==\n'
for f in $(git ls-files native/shared/src | grep -E 'staging\.rs|texture|gltf|commit'); do
  echo "--- $f ---"
  ast-grep outline "$f" --view expanded 2>/dev/null || true
done

Repository: Bloom-Engine/engine

Length of output: 6973

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== models.rs around load_gltf_with_textures ==\n'
sed -n '1430,1535p' native/shared/src/models.rs

printf '\n== models.rs around load_gltf_staged ==\n'
sed -n '1800,1875p' native/shared/src/models.rs

printf '\n== texture_store.rs register_texture_kind ==\n'
sed -n '80,165p' native/shared/src/renderer/texture_store.rs

printf '\n== ffi_core/models.rs texture commit path ==\n'
sed -n '800,875p' native/shared/src/ffi_core/models.rs

Repository: Bloom-Engine/engine

Length of output: 17010

---

Track texture kind per material use, not per image. A glTF image can be reused as both a normal map and a base-color texture; this image-level is_normal flag forces one registration kind for every reference to that image, so one of the roles renders incorrectly. Split the staged texture by usage or carry the role through commit.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@native/shared/src/staging.rs` around lines 10 - 14, Replace the image-level
is_normal tracking in the staged texture flow with per-material-use texture-kind
tracking. Update load_gltf_staged and the commit-time registration path around
register_texture_kind so an image referenced as both normal and base-color is
registered appropriately for each usage, either by creating separate staged
entries or by propagating the role through commit; do not apply one global role
to all references.