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:
1 parent
0553a85220
commit
0798aa5d57
169 files changed
+27098
-3469
No files matched your search
@@ -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(), ¶meter.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)
|
||||
|
||||
Reference in new issue
Block a user