Blacksite/docs/editor/extensibility.md

Authoring component extensibility

The authoring component registry is the lifecycle boundary between game-owned components and the editor. Stable component IDs are API keys; reflected Rust type paths are serialization adapters and may change during refactors.

Register a statically linked component

Derive Component, Reflect, and Default, and expose Bevy's component/default reflection data:

#[derive(Component, Reflect, Default)]
#[reflect(Component, Default)]
struct WeaponTuning {
    damage: f32,
}

During editor setup, call editor::ui::component_registry::register_authoring_component::<WeaponTuning>(...) with an EditorComponentDescriptor and inspector callback. The descriptor's stable id must never be a Rust type path. Registration fails on duplicate IDs or reflected types, and startup checks that all declared types and relationships resolve.

Once registered, the component automatically participates in registry presence checks, scene save filtering, default add/reset, reflected copy/paste and removal, and atomic component history. The inspector callback owns the component's UI body; mutations should use history::reflected_component_transaction so component data and the derived ActorKind hint undo together.

Composition and enable state

ActorKind is a compatibility/display hint, not a component container. Requirements and conflicts belong to component registrations. Render, light, audio, physics, and gameplay behaviors may be composed unless an explicit conflict prohibits the pair; primary geometry sources are mutually exclusive.

Persisted enablement lives in AuthoringComponentStates. InspectorOrder only controls visual card order. Runtime and hydration code must use authoring_component_active(states, legacy_order, component_type_path); the legacy order argument preserves disabled state while schema-v3 scenes migrate.

Current boundary

Whole-entity spawn/duplicate snapshots and built-in inspector bodies still contain typed adapters. Do not extend those match lists for new component-only edits: use the registry transaction API. Dynamic-library component types are not supported; extensions are statically linked and registered before the editor's startup validation runs.