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

+253 -18
View File
@@ -3,13 +3,16 @@
use avian3d::prelude::ColliderConstructor;
use bevy::light::{NotShadowCaster, NotShadowReceiver};
use bevy::prelude::*;
use bevy::render::render_resource::Face;
use serde::Deserialize;
use std::collections::{HashMap, HashSet};
use crate::{
asset_server_path, inspector_component_active, standard_material_asset_path, ColliderDesc,
ColliderShapeDesc, EditorAssetRef, InspectorOrder, LevelObject, MaterialDesc, MaterialOverride,
StaticMeshRenderer, StaticMeshRendererEntry, COMPONENT_COLLIDER_DESC, COMPONENT_MATERIAL_DESC,
asset_server_path, authoring_component_active, standard_material_asset_path,
AuthoringComponentStates, ColliderDesc, ColliderShapeDesc, EditorAssetRef,
HydratedRendererMaterialBinding, InspectorOrder, LevelObject, MaterialAlphaMode, MaterialAsset,
MaterialDesc, MaterialInstanceAsset, MaterialOverride, MaterialRef, StaticMeshRenderer,
StaticMeshRendererEntry, COMPONENT_COLLIDER_DESC, COMPONENT_MATERIAL_DESC,
COMPONENT_STATIC_MESH_RENDERER,
};
@@ -35,16 +38,39 @@ struct ResolvedStaticMeshMaterial {
material_label: String,
}
#[derive(Debug, Clone)]
pub(crate) struct ResolvedRendererDraw {
pub mesh_label: String,
pub source_node: Option<String>,
}
/// Cache for generated static mesh artifact lookups.
#[derive(Resource, Default)]
pub struct StaticMeshArtifactCache {
parts: HashMap<(String, String), ResolvedStaticMeshPart>,
materials: HashMap<(String, String), ResolvedStaticMeshMaterial>,
draw_bindings: HashMap<(String, String), ResolvedRendererDraw>,
loaded_assets: HashSet<String>,
failed_assets: HashSet<String>,
project_materials: HashMap<MaterialRef, Handle<StandardMaterial>>,
}
impl StaticMeshArtifactCache {
pub(crate) fn resolve_draw_binding(
&mut self,
asset_id: &str,
slot_id: &crate::ComponentInstanceId,
) -> Option<ResolvedRendererDraw> {
let key = (asset_id.to_string(), slot_id.0.clone());
if let Some(binding) = self.draw_bindings.get(&key) {
return Some(binding.clone());
}
if !self.loaded_assets.contains(asset_id) && !self.failed_assets.contains(asset_id) {
self.load_artifact(asset_id);
}
self.draw_bindings.get(&key).cloned()
}
fn resolve(&mut self, mesh: &EditorAssetRef) -> Option<ResolvedStaticMeshPart> {
if !mesh.is_resolved() {
return None;
@@ -95,17 +121,18 @@ impl StaticMeshArtifactCache {
} else {
part.id.clone()
};
self.parts.insert(
(asset_id.to_string(), part_id),
ResolvedStaticMeshPart {
source_path: manifest.source.path.clone(),
let slot_id = format!("slot:{part_id}");
self.draw_bindings.insert(
(asset_id.to_string(), slot_id),
ResolvedRendererDraw {
mesh_label: part.mesh_label.clone(),
material_label: part.material_label.clone(),
source_node: part.source_node.clone(),
},
);
if let Some(material_label) = part.material_label {
if let Some(material_label) = part.material_label.clone() {
let material_id = part
.material_id
.clone()
.filter(|id| !id.trim().is_empty())
.unwrap_or_else(|| material_id_from_label(&material_label));
self.materials
@@ -115,6 +142,24 @@ impl StaticMeshArtifactCache {
material_label,
});
}
if part.skinned
|| manifest.metadata.animation_count > 0
|| manifest.metadata.skin_count > 0
{
warn!(
"Static mesh artifact part {} requires an animated/skinned hierarchy and was excluded from StaticMeshRenderer hydration",
part.mesh_label
);
continue;
}
self.parts.insert(
(asset_id.to_string(), part_id),
ResolvedStaticMeshPart {
source_path: manifest.source.path.clone(),
mesh_label: part.mesh_label.clone(),
material_label: part.material_label.clone(),
},
);
}
self.loaded_assets.insert(asset_id.to_string());
}
@@ -130,9 +175,19 @@ impl StaticMeshArtifactCache {
struct StaticMeshResolveManifest {
source: StaticMeshResolveSource,
#[serde(default)]
metadata: StaticMeshResolveMetadata,
#[serde(default)]
parts: Vec<StaticMeshResolvePart>,
}
#[derive(Debug, Default, Deserialize)]
struct StaticMeshResolveMetadata {
#[serde(default)]
animation_count: usize,
#[serde(default)]
skin_count: usize,
}
#[derive(Debug, Deserialize)]
struct StaticMeshResolveSource {
path: String,
@@ -147,6 +202,10 @@ struct StaticMeshResolvePart {
material_id: Option<String>,
#[serde(default)]
material_label: Option<String>,
#[serde(default)]
source_node: Option<String>,
#[serde(default)]
skinned: bool,
}
#[allow(clippy::type_complexity)]
@@ -162,6 +221,7 @@ pub fn hydrate_static_mesh_renderers(
Option<&MaterialDesc>,
Option<&MaterialOverride>,
Option<&ColliderDesc>,
Option<&AuthoringComponentStates>,
Option<&InspectorOrder>,
),
(
@@ -172,6 +232,7 @@ pub fn hydrate_static_mesh_renderers(
Changed<MaterialDesc>,
Changed<MaterialOverride>,
Changed<ColliderDesc>,
Changed<AuthoringComponentStates>,
Changed<InspectorOrder>,
)>,
),
@@ -179,15 +240,17 @@ pub fn hydrate_static_mesh_renderers(
children: Query<&Children>,
generated_parts: Query<(), With<HydratedStaticMeshPart>>,
) {
for (entity, renderer, parent_material, material_override, collider, order) in &renderers {
for (entity, renderer, parent_material, material_override, collider, states, order) in
&renderers
{
despawn_static_mesh_parts(&mut commands, entity, &children, &generated_parts);
if !inspector_component_active(order, COMPONENT_STATIC_MESH_RENDERER) {
if !authoring_component_active(states, order, COMPONENT_STATIC_MESH_RENDERER) {
continue;
}
let parent_material =
parent_material.filter(|_| inspector_component_active(order, COMPONENT_MATERIAL_DESC));
let parent_material = parent_material
.filter(|_| authoring_component_active(states, order, COMPONENT_MATERIAL_DESC));
let collider =
collider.filter(|_| inspector_component_active(order, COMPONENT_COLLIDER_DESC));
collider.filter(|_| authoring_component_active(states, order, COMPONENT_COLLIDER_DESC));
spawn_static_mesh_parts(
&mut commands,
&asset_server,
@@ -237,6 +300,7 @@ pub fn spawn_static_mesh_parts(
asset_server,
materials,
artifact_cache,
renderer,
entry,
&resolved,
parent_material,
@@ -253,6 +317,11 @@ pub fn spawn_static_mesh_parts(
Name::new(name),
Mesh3d(mesh_handle),
MeshMaterial3d(material_handle),
HydratedRendererMaterialBinding {
owner: parent,
slot_id: effective_material_slot_id(entry),
effective_material: effective_material_ref(renderer, entry).cloned(),
},
entry.local_transform,
Visibility::Visible,
ChildOf(parent),
@@ -296,6 +365,7 @@ fn material_for_entry(
asset_server: &AssetServer,
materials: &mut Assets<StandardMaterial>,
artifact_cache: &mut StaticMeshArtifactCache,
renderer: &StaticMeshRenderer,
entry: &StaticMeshRendererEntry,
resolved: &ResolvedStaticMeshPart,
parent_material: Option<&MaterialDesc>,
@@ -315,8 +385,13 @@ fn material_for_entry(
return materials.add(material_from_desc(asset_server, override_material));
}
if let Some(material_ref) = entry.material.as_ref() {
if let Some(resolved_material) = artifact_cache.resolve_material(material_ref) {
if let Some(material_ref) = effective_material_ref(renderer, entry) {
if let Some(handle) =
resolve_shared_material(asset_server, materials, artifact_cache, material_ref)
{
return handle;
}
if let Some(resolved_material) = artifact_cache.resolve_material(&material_ref.0) {
let source_path = asset_server_path(&resolved_material.source_path);
return asset_server.load(standard_material_asset_path(
&source_path,
@@ -325,16 +400,121 @@ fn material_for_entry(
}
debug!(
"Static mesh material ref unresolved: asset_id='{}' material='{}' label='{}'",
material_ref.asset_id, material_ref.sub_asset_id, material_ref.label
material_ref.0.asset_id, material_ref.0.sub_asset_id, material_ref.0.label
);
}
// Read-only compatibility path for schema-v1/v2 scenes. The explicit project upgrader moves
// this reference into `RendererMaterialSet` and clears the legacy draw-part field.
if let Some(material_ref) = entry.material.as_ref() {
let material_ref = MaterialRef::new(material_ref.clone());
if let Some(handle) =
resolve_shared_material(asset_server, materials, artifact_cache, &material_ref)
{
return handle;
}
if let Some(resolved_material) = artifact_cache.resolve_material(&material_ref.0) {
let source_path = asset_server_path(&resolved_material.source_path);
return asset_server.load(standard_material_asset_path(
&source_path,
&resolved_material.material_label,
));
}
}
if let Some(label) = resolved.material_label.as_deref() {
let source_path = asset_server_path(&resolved.source_path);
return asset_server.load(standard_material_asset_path(&source_path, label));
}
materials.add(StandardMaterial::default())
materials.add(error_material())
}
fn effective_material_slot_id(entry: &StaticMeshRendererEntry) -> crate::ComponentInstanceId {
if entry.material_slot_id.0.trim().is_empty() {
entry.id.clone()
} else {
entry.material_slot_id.clone()
}
}
fn effective_material_ref<'a>(
renderer: &'a StaticMeshRenderer,
entry: &'a StaticMeshRendererEntry,
) -> Option<&'a MaterialRef> {
let slot_id = effective_material_slot_id(entry);
renderer.materials.effective_material(&slot_id)
}
fn resolve_shared_material(
asset_server: &AssetServer,
materials: &mut Assets<StandardMaterial>,
cache: &mut StaticMeshArtifactCache,
reference: &MaterialRef,
) -> Option<Handle<StandardMaterial>> {
if let Some(handle) = cache.project_materials.get(reference) {
return Some(handle.clone());
}
let path = reference.0.source_path.as_deref()?;
let desc_and_state = MaterialAsset::load_from_path(path)
.map(|asset| (asset.material, asset.render_state))
.or_else(|_| {
let instance = MaterialInstanceAsset::load_from_path(path)?;
let base_path = instance.base.0.source_path.as_deref().ok_or_else(|| {
format!(
"material instance {} has no loadable base path",
instance.label
)
})?;
let base = MaterialAsset::load_from_path(base_path)?;
let mut desc = base.material;
instance.apply_to(&mut desc);
Ok::<_, String>((desc, base.render_state))
})
.ok()?;
let mut material = material_from_desc(asset_server, &desc_and_state.0);
material.alpha_mode = match desc_and_state.1.alpha_mode {
MaterialAlphaMode::Opaque => AlphaMode::Opaque,
MaterialAlphaMode::Cutout => AlphaMode::Mask(desc_and_state.1.alpha_cutoff),
};
material.cull_mode = (!desc_and_state.1.double_sided).then_some(Face::Back);
let handle = materials.add(material);
cache
.project_materials
.insert(reference.clone(), handle.clone());
Some(handle)
}
pub(crate) fn resolve_renderer_material_handle(
asset_server: &AssetServer,
materials: &mut Assets<StandardMaterial>,
cache: &mut StaticMeshArtifactCache,
reference: &MaterialRef,
) -> Option<Handle<StandardMaterial>> {
if let Some(handle) = resolve_shared_material(asset_server, materials, cache, reference) {
return Some(handle);
}
let resolved = cache.resolve_material(&reference.0)?;
let source_path = asset_server_path(&resolved.source_path);
Some(asset_server.load(standard_material_asset_path(
&source_path,
&resolved.material_label,
)))
}
pub(crate) fn renderer_error_material(
materials: &mut Assets<StandardMaterial>,
) -> Handle<StandardMaterial> {
materials.add(error_material())
}
fn error_material() -> StandardMaterial {
StandardMaterial {
base_color: Color::srgb(1.0, 0.0, 1.0),
perceptual_roughness: 0.35,
metallic: 0.0,
..default()
}
}
fn labeled_asset_path(path: &str, label: &str) -> String {
@@ -392,3 +572,58 @@ fn stable_sub_asset_slug(label: &str) -> String {
}
slug.trim_matches('_').to_string()
}
#[cfg(test)]
mod tests {
use super::*;
use std::path::PathBuf;
struct TestManifest(PathBuf);
impl Drop for TestManifest {
fn drop(&mut self) {
let _ = std::fs::remove_file(&self.0);
}
}
fn write_manifest(asset_id: &str, animation_count: usize, skinned: bool) -> TestManifest {
let path = PathBuf::from(static_mesh_manifest_path(asset_id));
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(
&path,
format!(
r#"(
source: (path: "assets/models/test.glb"),
metadata: (animation_count: {animation_count}),
parts: [(
id: "mesh:test",
mesh_label: "Mesh0/Primitive0",
skinned: {skinned},
)],
)"#
),
)
.unwrap();
TestManifest(path)
}
#[test]
fn cache_refuses_skin_bound_parts() {
const ASSET_ID: &str = "7cd29974-1503-4084-b4a0-7483d0a57d7d";
let _manifest = write_manifest(ASSET_ID, 0, true);
let mut cache = StaticMeshArtifactCache::default();
let reference = EditorAssetRef::new(ASSET_ID, "mesh:test", "Test");
assert!(cache.resolve(&reference).is_none());
}
#[test]
fn cache_refuses_geometry_from_animated_sources() {
const ASSET_ID: &str = "7f6fcf6a-e978-4dc6-8738-16d52fc3ed03";
let _manifest = write_manifest(ASSET_ID, 1, false);
let mut cache = StaticMeshArtifactCache::default();
let reference = EditorAssetRef::new(ASSET_ID, "mesh:test", "Test");
assert!(cache.resolve(&reference).is_none());
}
}