Blacksite/docs/adr/0018-componentized-actor-inspector-and-materials.md

ADR 0018: Componentized actor inspector and materials

Status

Accepted.

Context

The actor inspector had started to expose too many unrelated concerns through a single static mesh renderer entry: source model paths, mesh labels, material overrides, shadow flags, and collider generation. That made imported FBX/glTF actors look format-specific and prevented a Unity-style component list where rendering, collision, rigid body state, and material overrides are separate authoring concepts.

The editor component system spec also requires stable actor/component IDs, registered editor-visible components, Transform pinned at the top, and an Add Component footer rather than an ad hoc button near Transform.

Decision

• Actors now have stable editor-facing identity components (ActorId, ActorName) and repeatable authoring items use ComponentInstanceId.
• Editor-visible actor components are described by an EditorComponentRegistry; the Add Component footer reads from this registry.
• InspectorOrder stores editor component order plus per-component active state. Collapse state is session-only UI state; active state is persisted with the scene and is undoable.
• StaticMeshRenderer stores MeshRenderSlot values that reference imported content-browser assets through EditorAssetRef { asset_id, sub_asset_id, label }. Actor renderer data does not store source FBX/glTF paths.
• Static mesh hydration resolves EditorAssetRef through generated artifacts in assets/meshes/generated/.
• Collision and rigid body state are separate authoring components: ColliderDesc and RigidBodyDesc. Mesh collider generation creates ColliderDesc::StaticMesh instead of renderer collider flags.
• Materials are shader-schema aware. MaterialDesc stores a ShaderRefDesc, typed shader parameters, texture bindings, StandardMaterial fields, and optional asset references. When an actor has an active MaterialDesc, static mesh hydration uses it before imported slot/source materials. Slot material references remain source/default selectors, not a separate actor material editing surface. Shared material assets remain content-browser assets.

Consequences

• New model placement creates StaticMeshRenderer plus optional RigidBodyDesc/ColliderDesc; legacy PhysicsBody remains loadable for old scenes.
• Actor inspectors show imported asset selectors for mesh/source-material slots instead of source-path text fields.
• Disabling a component in the inspector keeps its authoring data but prevents hydration/runtime systems from using it. Mesh, material, light, physics, and post-process hydration strip stale runtime components when active state changes.
• Existing static mesh artifacts without part IDs are still resolved by deriving stable sub-asset IDs from loader labels.
• Custom shader support is schema-driven; v1 stores and edits typed parameters, while runtime rendering currently maps built-in Lit/Unlit through Bevy StandardMaterial.