Blacksite/.cursor/plans/static_mesh_asset_refactor_2026-06-05.plan.md

Static Mesh Asset Refactor Plan

Date: 2026-06-05

Scope

• Normalize glTF/GLB and FBX model placement through one static mesh renderer authoring component.
• Generate project static mesh manifests under assets/meshes/generated/.
• Preserve explicit scene-instance placement for full SceneRoot behavior.
• Redesign the actor inspector around component cards and add renderer slot controls.

Implementation Slices

1. Add StaticMeshRenderer shared authoring data, validation, scene save allowlist, history snapshots, and hydration.
2. Extend the asset registry import settings with placement mode, hierarchy mode, material policy, collider generation, and generated manifest path.
3. Add glTF/FBX static mesh manifest generation and route model drag/drop through renderer placement by default.
4. Expose asset import settings and static mesh renderer controls in editor UI.
5. Update ADR/docs/README and verify with focused checks.

Shipped Behavior

• StaticAsset placement creates ActorKind::StaticMesh + StaticMeshRenderer.
• SceneInstance placement keeps ActorKind::ImportedModel + ModelRef.
• SingleActor hierarchy mode stores all mesh parts on one renderer.
• SourceHierarchy mode creates a root with child static mesh actors.
• Static mesh hydration spawns generated child Mesh3d parts with source materials, shadow flags, and optional Avian mesh collider constructors.