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

+211 -4
View File
@@ -1,15 +1,73 @@
//! Serializable material asset files under `assets/materials/`.
//! Versioned material, material-instance, and surface-shader asset documents.
use bevy::prelude::*;
use serde::{Deserialize, Serialize};
use crate::{MaterialDesc, MaterialParameter, MaterialShaderKind, MaterialTextureBinding};
use crate::{
EditorAssetRef, MaterialDesc, MaterialParameter, MaterialRef, MaterialShaderKind,
MaterialTextureBinding,
};
pub const MATERIAL_ASSET_SCHEMA_VERSION: u32 = 1;
pub const MATERIAL_INSTANCE_SCHEMA_VERSION: u32 = 1;
pub const SURFACE_SHADER_SCHEMA_VERSION: u32 = 1;
const fn default_material_schema_version() -> u32 {
MATERIAL_ASSET_SCHEMA_VERSION
}
const fn default_material_instance_schema_version() -> u32 {
MATERIAL_INSTANCE_SCHEMA_VERSION
}
const fn default_surface_shader_schema_version() -> u32 {
SURFACE_SHADER_SCHEMA_VERSION
}
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
pub enum MaterialAlphaMode {
#[default]
Opaque,
Cutout,
}
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
pub struct MaterialRenderState {
#[serde(default)]
pub alpha_mode: MaterialAlphaMode,
#[serde(default = "default_alpha_cutoff")]
pub alpha_cutoff: f32,
#[serde(default)]
pub double_sided: bool,
}
const fn default_alpha_cutoff() -> f32 {
0.5
}
impl Default for MaterialRenderState {
fn default() -> Self {
Self {
alpha_mode: MaterialAlphaMode::Opaque,
alpha_cutoff: default_alpha_cutoff(),
double_sided: false,
}
}
}
/// RON material asset: label plus authoring [`MaterialDesc`].
#[derive(Debug, Clone, Serialize, Deserialize)]
#[derive(Asset, TypePath, Debug, Clone, Serialize, Deserialize)]
pub struct MaterialAsset {
#[serde(default = "default_material_schema_version")]
pub schema_version: u32,
pub label: String,
/// Legacy path/label retained for v0 compatibility. New assets use `shader_ref`.
#[serde(default)]
pub shader: Option<String>,
#[serde(default)]
pub shader_ref: Option<EditorAssetRef>,
#[serde(default)]
pub render_state: MaterialRenderState,
pub material: MaterialDesc,
}
@@ -21,6 +79,81 @@ impl MaterialAsset {
}
}
/// Explicit reusable overrides over one project Material asset.
#[derive(Asset, TypePath, Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct MaterialInstanceAsset {
#[serde(default = "default_material_instance_schema_version")]
pub schema_version: u32,
pub label: String,
pub base: MaterialRef,
#[serde(default)]
pub parameters: Vec<MaterialParameter>,
#[serde(default)]
pub textures: Vec<MaterialTextureBinding>,
}
impl MaterialInstanceAsset {
pub fn load_from_path(catalog_path: &str) -> Result<Self, String> {
let text = std::fs::read_to_string(catalog_path)
.map_err(|err| format!("could not read {catalog_path}: {err}"))?;
ron::from_str(&text)
.map_err(|err| format!("invalid material-instance RON in {catalog_path}: {err}"))
}
/// Applies this instance's sparse overrides without mutating the shared base asset.
pub fn apply_to(&self, material: &mut MaterialDesc) {
for parameter in &self.parameters {
match (parameter.name.as_str(), &parameter.value) {
("base_color", crate::MaterialParameterValue::Color(value)) => {
material.base_color = *value;
}
("metallic", crate::MaterialParameterValue::Float(value)) => {
material.metallic = *value;
}
("roughness", crate::MaterialParameterValue::Float(value)) => {
material.roughness = *value;
}
("emissive_color", crate::MaterialParameterValue::Color(value)) => {
material.emissive_color = *value;
}
("emissive_intensity", crate::MaterialParameterValue::Float(value)) => {
material.emissive_intensity = *value;
}
_ => upsert_parameter(&mut material.parameters, parameter.clone()),
}
}
for texture in &self.textures {
let path = texture
.texture
.as_ref()
.and_then(|reference| reference.source_path.clone());
match texture.name.as_str() {
"base_color_texture" => material.base_color_texture = path,
"emissive_texture" => material.emissive_texture = path,
"normal_map_texture" => material.normal_map_texture = path,
"metallic_roughness_texture" => material.metallic_roughness_texture = path,
_ => upsert_texture(&mut material.textures, texture.clone()),
}
}
}
}
fn upsert_parameter(values: &mut Vec<MaterialParameter>, value: MaterialParameter) {
if let Some(existing) = values.iter_mut().find(|entry| entry.name == value.name) {
*existing = value;
} else {
values.push(value);
}
}
fn upsert_texture(values: &mut Vec<MaterialTextureBinding>, value: MaterialTextureBinding) {
if let Some(existing) = values.iter_mut().find(|entry| entry.name == value.name) {
*existing = value;
} else {
values.push(value);
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub enum ShaderPropertyType {
Bool,
@@ -42,8 +175,10 @@ pub struct ShaderPropertyDesc {
}
/// RON shader schema describing material inspector parameters.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[derive(Asset, TypePath, Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ShaderSchemaAsset {
#[serde(default = "default_surface_shader_schema_version")]
pub schema_version: u32,
pub label: String,
pub kind: MaterialShaderKind,
#[serde(default)]
@@ -56,6 +191,78 @@ pub struct ShaderSchemaAsset {
pub default_textures: Vec<MaterialTextureBinding>,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn legacy_material_defaults_to_current_schema_and_opaque() {
let parsed: MaterialAsset = ron::from_str(
r#"(label: "Legacy", material: (base_color: (r: 1.0, g: 1.0, b: 1.0, a: 1.0), metallic: 0.0, roughness: 0.5, base_color_texture: None, normal_map_texture: None, metallic_roughness_texture: None))"#,
)
.expect("legacy material should remain readable");
assert_eq!(parsed.schema_version, MATERIAL_ASSET_SCHEMA_VERSION);
assert_eq!(parsed.render_state.alpha_mode, MaterialAlphaMode::Opaque);
}
#[test]
fn material_instance_requires_an_explicit_base_ref() {
let instance = MaterialInstanceAsset {
schema_version: MATERIAL_INSTANCE_SCHEMA_VERSION,
label: "Red Variant".into(),
base: MaterialRef::new(EditorAssetRef::new(
"material-id",
"material:source",
"Base",
)),
parameters: Vec::new(),
textures: Vec::new(),
};
assert!(instance.base.is_resolved());
}
#[test]
fn material_instance_applies_standard_and_custom_overrides() {
let mut material = MaterialDesc::default();
let instance = MaterialInstanceAsset {
schema_version: MATERIAL_INSTANCE_SCHEMA_VERSION,
label: "Variant".into(),
base: MaterialRef::default(),
parameters: vec![
MaterialParameter {
name: "roughness".into(),
value: crate::MaterialParameterValue::Float(0.2),
},
MaterialParameter {
name: "edge_width".into(),
value: crate::MaterialParameterValue::Float(3.0),
},
],
textures: vec![MaterialTextureBinding {
name: "base_color_texture".into(),
texture: Some(
EditorAssetRef::new("texture", "texture:source", "Grid")
.with_source_path("assets/textures/grid.png"),
),
}],
};
instance.apply_to(&mut material);
assert_eq!(material.roughness, 0.2);
assert_eq!(
material.base_color_texture.as_deref(),
Some("assets/textures/grid.png")
);
assert!(material
.parameters
.iter()
.any(|value| value.name == "edge_width"));
}
}
impl ShaderSchemaAsset {
pub fn load_from_path(catalog_path: &str) -> Result<Self, String> {
let text = std::fs::read_to_string(catalog_path)