Build renderer and material component foundations

Add dedicated skinned rendering, pose restoration, shared Material and Material Instance slots, registry-driven components, Surface/Solari integration, transactional schema upgrades, navigation authoring, documentation, and evaluation evidence.
This commit is contained in:
Rbanh committed 2026-07-12 00:24:06 -04:00
1 parent 0553a85220
commit 0798aa5d57
169 files changed
+27098 -3469

No files matched your search

+268 -20
View File
@@ -80,16 +80,39 @@ impl ComponentInstanceId {
#[derive(Component, Reflect, Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[reflect(Component, Default, Debug, PartialEq, Serialize, Deserialize)]
pub struct InspectorOrder {
/// Stable component IDs used by current scenes.
#[serde(default)]
pub component_ids: Vec<String>,
/// Legacy reflected type paths used by schema-v3 scenes.
#[serde(default)]
pub component_type_names: Vec<String>,
/// Legacy schema-v3 storage. New authoring writes active state to
/// [`AuthoringComponentStates`]; this field remains readable so old scenes can
/// be upgraded without losing disabled components.
#[serde(default)]
pub component_states: Vec<InspectorComponentState>,
}
/// Persisted active state for authoring components.
///
/// This is intentionally separate from [`InspectorOrder`]: hydration and runtime
/// behavior must not depend on how the editor happens to arrange component cards.
#[derive(Component, Reflect, Default, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[reflect(Component, Default, Debug, PartialEq, Serialize, Deserialize)]
pub struct AuthoringComponentStates {
#[serde(default)]
pub states: Vec<InspectorComponentState>,
}
/// Per-component inspector metadata that must survive scene save/load.
#[derive(Reflect, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[reflect(Default, Debug, PartialEq, Serialize, Deserialize)]
pub struct InspectorComponentState {
/// Stable authoring component identity used by current scenes.
#[serde(default)]
pub component_id: String,
/// Legacy schema-v3 reflected type path.
#[serde(default)]
pub type_name: String,
#[serde(default = "default_true")]
pub active: bool,
@@ -98,6 +121,7 @@ pub struct InspectorComponentState {
impl Default for InspectorComponentState {
fn default() -> Self {
Self {
component_id: String::new(),
type_name: String::new(),
active: true,
}
@@ -106,41 +130,64 @@ impl Default for InspectorComponentState {
impl InspectorOrder {
pub fn is_component_active(&self, type_name: &str) -> bool {
let component_id = authoring_component_key(type_name);
self.component_states
.iter()
.find(|state| state.type_name == type_name)
.find(|state| {
state.component_id == component_id
|| state.type_name == type_name
|| state.type_name == component_id
})
.map(|state| state.active)
.unwrap_or(true)
}
pub fn set_component_active(&mut self, type_name: impl Into<String>, active: bool) {
let type_name = type_name.into();
if let Some(state) = self
.component_states
.iter_mut()
.find(|state| state.type_name == type_name)
{
let component_id = authoring_component_key(&type_name).to_string();
if let Some(state) = self.component_states.iter_mut().find(|state| {
state.component_id == component_id
|| state.type_name == type_name
|| state.type_name == component_id
}) {
state.component_id = component_id;
state.type_name.clear();
state.active = active;
} else {
self.component_states
.push(InspectorComponentState { type_name, active });
self.component_states.push(InspectorComponentState {
component_id,
type_name: String::new(),
active,
});
}
}
pub fn ensure_component_order(&mut self, present: &[&str]) {
for type_name in present {
let component_id = authoring_component_key(type_name);
if !self
.component_type_names
.component_ids
.iter()
.any(|existing| existing == type_name)
.any(|existing| existing == component_id)
{
self.component_type_names.push((*type_name).to_string());
self.component_ids.push(component_id.to_string());
}
}
// Once the editor touches order, the stable-ID representation is
// authoritative and legacy paths no longer need to be re-saved.
self.component_type_names.clear();
}
pub fn ordered_components<'a>(&self, present: &[&'a str]) -> Vec<&'a str> {
let mut ordered = Vec::new();
for component_id in &self.component_ids {
if let Some(present_type) = present
.iter()
.find(|present| authoring_component_key(present) == component_id)
{
ordered.push(*present_type);
}
}
for type_name in &self.component_type_names {
if let Some(present_type) = present.iter().find(|present| **present == type_name) {
ordered.push(*present_type);
@@ -157,29 +204,186 @@ impl InspectorOrder {
pub fn move_component(&mut self, type_name: &str, offset: isize, present: &[&str]) -> bool {
self.ensure_component_order(present);
let Some(index) = self
.component_type_names
.component_ids
.iter()
.position(|existing| existing == type_name)
.position(|existing| existing == authoring_component_key(type_name))
else {
return false;
};
let target = (index as isize + offset)
.clamp(0, self.component_type_names.len() as isize - 1) as usize;
let target =
(index as isize + offset).clamp(0, self.component_ids.len() as isize - 1) as usize;
if target == index {
return false;
}
let item = self.component_type_names.remove(index);
self.component_type_names.insert(target, item);
let item = self.component_ids.remove(index);
self.component_ids.insert(target, item);
true
}
}
impl AuthoringComponentStates {
pub fn is_component_active(&self, type_name: &str) -> bool {
let component_id = authoring_component_key(type_name);
self.states
.iter()
.find(|state| {
state.component_id == component_id
|| state.type_name == type_name
|| state.type_name == component_id
})
.map(|state| state.active)
.unwrap_or(true)
}
pub fn set_component_active(&mut self, type_name: impl Into<String>, active: bool) {
let type_name = type_name.into();
let component_id = authoring_component_key(&type_name).to_string();
if let Some(state) = self.states.iter_mut().find(|state| {
state.component_id == component_id
|| state.type_name == type_name
|| state.type_name == component_id
}) {
state.component_id = component_id;
state.type_name.clear();
state.active = active;
} else {
self.states.push(InspectorComponentState {
component_id,
type_name: String::new(),
active,
});
}
}
pub fn remove_component(&mut self, type_name: &str) {
let component_id = authoring_component_key(type_name);
self.states.retain(|state| {
state.component_id != component_id
&& state.type_name != type_name
&& state.type_name != component_id
});
}
}
/// Returns whether a persisted authoring component is enabled.
///
/// `legacy_order` is consulted only when an older scene has not yet been migrated
/// to [`AuthoringComponentStates`].
pub fn authoring_component_active(
states: Option<&AuthoringComponentStates>,
legacy_order: Option<&InspectorOrder>,
type_name: &str,
) -> bool {
states
.map(|states| states.is_component_active(type_name))
.or_else(|| legacy_order.map(|order| order.is_component_active(type_name)))
.unwrap_or(true)
}
pub fn inspector_component_active(order: Option<&InspectorOrder>, type_name: &str) -> bool {
order
.map(|order| order.is_component_active(type_name))
.unwrap_or(true)
}
// Stable authoring component identities. These are editor/protocol keys; reflected
// Rust type paths remain serialization details and may change during refactors.
pub const AUTHORING_COMPONENT_PRIMITIVE: &str = "render.primitive";
pub const AUTHORING_COMPONENT_BRUSH: &str = "render.brush";
pub const AUTHORING_COMPONENT_STATIC_MESH_RENDERER: &str = "render.static_mesh_renderer";
pub const AUTHORING_COMPONENT_SKINNED_MESH_RENDERER: &str = "render.skinned_mesh_renderer";
pub const AUTHORING_COMPONENT_MATERIAL: &str = "render.material";
pub const AUTHORING_COMPONENT_LIGHT: &str = "render.light";
pub const AUTHORING_COMPONENT_ANIMATION_CONTROLLER: &str = "animation.controller";
pub const AUTHORING_COMPONENT_AUDIO_SOURCE: &str = "audio.source";
pub const AUTHORING_COMPONENT_AUDIO_LISTENER: &str = "audio.listener";
pub const AUTHORING_COMPONENT_RIGID_BODY: &str = "physics.rigid_body";
pub const AUTHORING_COMPONENT_COLLIDER: &str = "physics.collider";
pub const AUTHORING_COMPONENT_LEGACY_PHYSICS_BODY: &str = "physics.legacy_body";
pub const AUTHORING_COMPONENT_PLAYER_SPAWN: &str = "gameplay.player_spawn";
pub const AUTHORING_COMPONENT_WEAPON_SPAWN: &str = "gameplay.weapon_spawn";
pub const AUTHORING_COMPONENT_TRIGGER_VOLUME: &str = "gameplay.trigger_volume";
pub const AUTHORING_COMPONENT_TEAM_SPAWN: &str = "gameplay.team_spawn";
pub const AUTHORING_COMPONENT_OBJECTIVE: &str = "gameplay.objective";
pub const AUTHORING_COMPONENT_POST_PROCESS_VOLUME: &str = "render.post_process_volume";
pub const AUTHORING_COMPONENT_NAVIGATION_BOUNDS: &str = "navigation.bounds";
pub const AUTHORING_COMPONENT_NAVIGATION_OBSTACLE: &str = "navigation.obstacle";
pub const AUTHORING_COMPONENT_NAVIGATION_AREA: &str = "navigation.area";
pub const AUTHORING_COMPONENT_NAVIGATION_LINK: &str = "navigation.link";
/// Resolves either a stable authoring ID or a reflected Rust type path to its
/// stable editor/protocol identity. Unknown extension keys are returned as
/// `None` and remain usable as-is by generic state/order storage.
pub fn authoring_component_id(key: &str) -> Option<&'static str> {
match key {
AUTHORING_COMPONENT_PRIMITIVE | COMPONENT_PRIMITIVE => Some(AUTHORING_COMPONENT_PRIMITIVE),
AUTHORING_COMPONENT_BRUSH | COMPONENT_BRUSH_DESC => Some(AUTHORING_COMPONENT_BRUSH),
AUTHORING_COMPONENT_STATIC_MESH_RENDERER | COMPONENT_STATIC_MESH_RENDERER => {
Some(AUTHORING_COMPONENT_STATIC_MESH_RENDERER)
}
AUTHORING_COMPONENT_SKINNED_MESH_RENDERER | "shared::animation::SkinnedMeshRenderer" => {
Some(AUTHORING_COMPONENT_SKINNED_MESH_RENDERER)
}
AUTHORING_COMPONENT_MATERIAL | COMPONENT_MATERIAL_DESC => {
Some(AUTHORING_COMPONENT_MATERIAL)
}
AUTHORING_COMPONENT_LIGHT | COMPONENT_LIGHT_DESC => Some(AUTHORING_COMPONENT_LIGHT),
AUTHORING_COMPONENT_ANIMATION_CONTROLLER | "shared::animation::AnimationControllerDesc" => {
Some(AUTHORING_COMPONENT_ANIMATION_CONTROLLER)
}
AUTHORING_COMPONENT_AUDIO_SOURCE | COMPONENT_AUDIO_SOURCE_DESC => {
Some(AUTHORING_COMPONENT_AUDIO_SOURCE)
}
AUTHORING_COMPONENT_AUDIO_LISTENER | COMPONENT_AUDIO_LISTENER_DESC => {
Some(AUTHORING_COMPONENT_AUDIO_LISTENER)
}
AUTHORING_COMPONENT_RIGID_BODY | COMPONENT_RIGID_BODY_DESC => {
Some(AUTHORING_COMPONENT_RIGID_BODY)
}
AUTHORING_COMPONENT_COLLIDER | COMPONENT_COLLIDER_DESC => {
Some(AUTHORING_COMPONENT_COLLIDER)
}
AUTHORING_COMPONENT_LEGACY_PHYSICS_BODY | COMPONENT_PHYSICS_BODY => {
Some(AUTHORING_COMPONENT_LEGACY_PHYSICS_BODY)
}
AUTHORING_COMPONENT_PLAYER_SPAWN | COMPONENT_PLAYER_SPAWN => {
Some(AUTHORING_COMPONENT_PLAYER_SPAWN)
}
AUTHORING_COMPONENT_WEAPON_SPAWN | COMPONENT_WEAPON_SPAWN => {
Some(AUTHORING_COMPONENT_WEAPON_SPAWN)
}
AUTHORING_COMPONENT_TRIGGER_VOLUME | COMPONENT_TRIGGER_VOLUME => {
Some(AUTHORING_COMPONENT_TRIGGER_VOLUME)
}
AUTHORING_COMPONENT_TEAM_SPAWN | COMPONENT_TEAM_SPAWN => {
Some(AUTHORING_COMPONENT_TEAM_SPAWN)
}
AUTHORING_COMPONENT_OBJECTIVE | COMPONENT_OBJECTIVE_MARKER => {
Some(AUTHORING_COMPONENT_OBJECTIVE)
}
AUTHORING_COMPONENT_POST_PROCESS_VOLUME | COMPONENT_POST_PROCESS_VOLUME => {
Some(AUTHORING_COMPONENT_POST_PROCESS_VOLUME)
}
AUTHORING_COMPONENT_NAVIGATION_BOUNDS | "shared::navigation::NavigationBounds" => {
Some(AUTHORING_COMPONENT_NAVIGATION_BOUNDS)
}
AUTHORING_COMPONENT_NAVIGATION_OBSTACLE | "shared::navigation::NavigationObstacle" => {
Some(AUTHORING_COMPONENT_NAVIGATION_OBSTACLE)
}
AUTHORING_COMPONENT_NAVIGATION_AREA | "shared::navigation::NavigationArea" => {
Some(AUTHORING_COMPONENT_NAVIGATION_AREA)
}
AUTHORING_COMPONENT_NAVIGATION_LINK | "shared::navigation::NavigationLink" => {
Some(AUTHORING_COMPONENT_NAVIGATION_LINK)
}
_ => None,
}
}
pub fn authoring_component_key(key: &str) -> &str {
authoring_component_id(key).unwrap_or(key)
}
pub const COMPONENT_PRIMITIVE: &str = "shared::components::Primitive";
pub const COMPONENT_BRUSH_DESC: &str = "shared::components::BrushDesc";
pub const COMPONENT_STATIC_MESH_RENDERER: &str = "shared::components::StaticMeshRenderer";
@@ -700,6 +904,11 @@ pub struct MeshRenderSlot {
pub id: ComponentInstanceId,
pub name: String,
pub mesh: EditorAssetRef,
/// Stable renderer material slot used by this draw part.
#[serde(default)]
pub material_slot_id: ComponentInstanceId,
/// Legacy inline imported-material reference. Schema-v4 migration moves this into the
/// renderer's shared `RendererMaterialSet`.
#[serde(default)]
pub material: Option<EditorAssetRef>,
#[serde(default)]
@@ -718,6 +927,7 @@ impl Default for MeshRenderSlot {
id: ComponentInstanceId::default(),
name: "Mesh".into(),
mesh: EditorAssetRef::default(),
material_slot_id: ComponentInstanceId::default(),
material: None,
local_transform: Transform::default(),
visible: true,
@@ -730,6 +940,9 @@ impl Default for MeshRenderSlot {
/// Backward-compatible alias for old code paths while scenes migrate to slots.
pub type StaticMeshRendererEntry = MeshRenderSlot;
/// Public renderer-foundation name for one static draw part.
pub type StaticMeshPart = MeshRenderSlot;
/// Reflectable static mesh renderer. Hydration turns entries into child `Mesh3d`
/// entities and source/default materials.
#[derive(Component, Reflect, Debug, Clone, PartialEq, Serialize, Deserialize)]
@@ -737,15 +950,48 @@ pub type StaticMeshRendererEntry = MeshRenderSlot;
pub struct StaticMeshRenderer {
#[serde(default, alias = "entries")]
pub slots: Vec<MeshRenderSlot>,
#[serde(default)]
pub materials: crate::RendererMaterialSet,
}
impl StaticMeshRenderer {
pub fn empty() -> Self {
Self { slots: Vec::new() }
Self {
slots: Vec::new(),
materials: crate::RendererMaterialSet::default(),
}
}
pub fn single(slot: MeshRenderSlot) -> Self {
Self { slots: vec![slot] }
pub fn single(mut slot: MeshRenderSlot) -> Self {
if slot.material_slot_id.0.trim().is_empty() {
slot.material_slot_id = ComponentInstanceId::new(format!("slot:{}", slot.id.0));
}
let source_material = slot.material.clone().map(crate::MaterialRef::new);
let materials = crate::RendererMaterialSet {
slots: vec![crate::RendererMaterialSlot {
id: slot.material_slot_id.clone(),
name: slot.name.clone(),
source_material,
material: None,
}],
orphaned_assignments: Vec::new(),
};
Self {
slots: vec![slot],
materials,
}
}
pub fn material_slot_for_part(
&self,
part: &MeshRenderSlot,
) -> Option<&crate::RendererMaterialSlot> {
let slot_id = if part.material_slot_id.0.trim().is_empty() {
&part.id
} else {
&part.material_slot_id
};
self.materials.slot(slot_id)
}
}
@@ -1147,6 +1393,7 @@ pub enum ActorKind {
Empty,
Brush,
StaticMesh,
SkinnedMesh,
ImportedModel,
Light,
PrefabAnchor,
@@ -1158,6 +1405,7 @@ pub enum ActorKind {
Objective,
AudioSource,
AudioListener,
Navigation,
}
/// Inspector upper bound for point/spot [`LightDesc::intensity`] (lumens).