1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
//! Material system for surface appearance.
//!
//! Materials define how surfaces look when rendered using PBR (Physically Based Rendering):
//!
//! - [`Material`]: PBR material definition following glTF conventions
//! - [`MaterialRef`]: Component referencing a material by name
//! - [`MaterialRegistry`]: Resource storing all named materials
//! - [`AlphaMode`]: Transparency handling mode (Opaque, Mask, Blend)
//!
//! Supports metallic-roughness workflow, normal mapping, emissive surfaces,
//! transmission/refraction (glTF extensions), and specular overrides.
//!
//! # Creating a Simple Material
//!
//! Materials are registered by name and applied to entities via [`MaterialRef`]:
//!
//! ```ignore
//! // Create and register a material
//! let material = Material {
//! base_color: [1.0, 0.2, 0.2, 1.0], // Red
//! roughness: 0.3,
//! metallic: 0.8,
//! ..Default::default()
//! };
//!
//! material_registry_insert(
//! &mut world.resources.assets.material_registry,
//! "red_metal".to_string(),
//! material,
//! );
//! if let Some(&index) =
//! world.resources.assets.material_registry.registry.name_to_index.get("red_metal")
//! {
//! registry_add_reference(&mut world.resources.assets.material_registry.registry, index);
//! }
//!
//! // Apply to an entity
//! world.core.set_material_ref(entity, MaterialRef::new("red_metal"));
//! ```
//!
//! # Material Registration Pattern
//!
//! Materials use reference counting. After inserting, add a reference so the
//! material survives, and it is cleaned up when no entities reference it:
//!
//! ```ignore
//! // Full registration pattern
//! material_registry_insert(
//! &mut world.resources.assets.material_registry,
//! "my_material".to_string(),
//! material,
//! );
//! if let Some(&index) =
//! world.resources.assets.material_registry.registry.name_to_index.get("my_material")
//! {
//! registry_add_reference(&mut world.resources.assets.material_registry.registry, index);
//! }
//! ```
//!
//! # Textured Materials
//!
//! For materials with textures, load textures first and reference by path:
//!
//! ```ignore
//! // Load textures into the cache
//! texture_cache_add_reference(&mut world.resources.texture_cache, "assets/brick_albedo.png");
//! texture_cache_add_reference(&mut world.resources.texture_cache, "assets/brick_normal.png");
//!
//! // Create material with texture paths
//! let material = Material {
//! base_color: [1.0, 1.0, 1.0, 1.0],
//! base_texture: Some("assets/brick_albedo.png".to_string()),
//! normal_texture: Some("assets/brick_normal.png".to_string()),
//! roughness: 0.8,
//! metallic: 0.0,
//! ..Default::default()
//! };
//!
//! material_registry_insert(
//! &mut world.resources.assets.material_registry,
//! "brick".to_string(),
//! material,
//! );
//! if let Some(&index) =
//! world.resources.assets.material_registry.registry.name_to_index.get("brick")
//! {
//! registry_add_reference(&mut world.resources.assets.material_registry.registry, index);
//! }
//! ```
//!
//! # Emissive Materials (for Bloom)
//!
//! ```ignore
//! let glow_material = Material {
//! base_color: [0.0, 0.5, 1.0, 1.0],
//! emissive_factor: [0.0, 0.5, 1.0], // Same as base for glow
//! emissive_strength: 5.0, // Bloom intensity multiplier
//! unlit: true, // Skip lighting
//! ..Default::default()
//! };
//! ```
//!
//! # Transparent Materials
//!
//! ```ignore
//! // Alpha mask (foliage, fences)
//! let foliage = Material {
//! alpha_mode: AlphaMode::Mask,
//! alpha_cutoff: 0.5, // Pixels below this alpha are discarded
//! double_sided: true,
//! ..Default::default()
//! };
//!
//! // Alpha blend (glass)
//! let glass = Material {
//! alpha_mode: AlphaMode::Blend,
//! base_color: [1.0, 1.0, 1.0, 0.3], // 30% opacity
//! transmission_factor: 0.9, // Refractive
//! ior: 1.5, // Glass IOR
//! ..Default::default()
//! };
//! ```
//!
//! # Material Properties
//!
//! | Property | Range | Description |
//! |----------|-------|-------------|
//! | `base_color` | [0-1, 0-1, 0-1, 0-1] | RGBA albedo color |
//! | `roughness` | 0-1 | 0 = mirror, 1 = diffuse |
//! | `metallic` | 0-1 | 0 = dielectric, 1 = metal |
//! | `normal_scale` | 0-2+ | Normal map intensity |
//! | `emissive_factor` | [0+, 0+, 0+] | Glow color (for bloom) |
//! | `emissive_strength` | 0-100+ | Bloom multiplier |
//! | `transmission_factor` | 0-1 | Refraction amount |
//! | `ior` | 1.0-2.5 | Index of refraction |
//!
//! [`Material`]: components::Material
//! [`MaterialRef`]: components::MaterialRef
//! [`MaterialRegistry`]: resources::MaterialRegistry
//! [`AlphaMode`]: components::AlphaMode
pub use *;
pub use *;
pub use *;