Compare commits

...
Author SHA1 Message Date
Rbanh d1a56f77cc Add terrain material layer painting
CI / Format, lint, test, build (push) Waiting to run
2026-07-12 21:00:13 -04:00
Rbanh 293811aecd Add terrain sculpt stroke tools
CI / Format, lint, test, build (push) Waiting to run
2026-07-12 19:50:47 -04:00
Rbanh ed21bcc52d Add chunked terrain authoring foundation
CI / Format, lint, test, build (push) Waiting to run
2026-07-12 18:43:42 -04:00
Rbanh 577d8dcb27 Refresh production readiness matrix
CI / Format, lint, test, build (push) Waiting to run
2026-07-12 18:10:03 -04:00
42 changed files with 3607 additions and 48 deletions

No files matched your search

@@ -15,9 +15,10 @@ owner requests it again.
1. Keep one evidence matrix under `docs/editor/evaluations/production-readiness/`; historical H1-H6
notes remain context only.
2. Close implementation blockers before nominating a candidate: collaborative safety `#49`, the
remaining Material/drag-drop contract in `#16`, `#18`, and `#51`, terrain `#22`-`#24`, physics
placement/diagnostics `#25`-`#26`, and their regression fixtures.
2. Close implementation blockers before nominating a candidate: the deformed Solari geometry
boundary in `#51`, terrain `#22`-`#24`, physics placement/diagnostics `#25`-`#26`, and their
regression fixtures. Collaborative safety `#49`, Material Library/targeted drops `#16`/`#18`,
and native-dialog responsiveness `#52` are accepted and integrated.
3. Complete the representative regression project, mutation-invariant coverage, performance budgets,
and first-hour workflow tracked by `#32`-`#36`.
4. Nominate one exact commit, validate it from a clean checkout, and record source/headless results.
@@ -0,0 +1,46 @@
# Terrain Authoring Foundation
Working implementation plan for Gitea
[`#22`](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/22).
This establishes the persistent and hydrated terrain contract required by sculpting `#23`, layer
painting `#24`, physics placement `#25`, and the regression pack `#32`.
## Authored Contract
- Add reflected `TerrainDesc` authoring data with a version, square height-grid resolution, inline
finite heights, horizontal sample spacing, vertical scale, chunk quad size, optional shared
Material/Material Instance reference, collider generation, and shadow flags.
- V1 stores the compact height grid in the scene so save/recovery/history/prefab behavior is exact.
A later external heightmap asset migration must be explicit and versioned rather than silently
changing ownership.
- Validate resolution, exact sample count, finite values, positive scale, and chunk bounds before
hydration or publication.
## Hydration
- Partition the grid into deterministic non-overlapping quad chunks with shared boundary samples.
- Generate triangle-list meshes with normals, UVs, U32 indices, and tangents; each generated child
carries owner/chunk coordinates and remains runtime-only.
- Use the authored shared material when resolvable and an explicit terrain fallback otherwise.
- Optionally attach `ColliderConstructor::TrimeshFromMesh` per chunk.
- Rebuild only the owning terrain's generated chunks when descriptor/material/active state changes;
disabling/removing terrain cleans every generated child.
## Editor Integration
- Register Terrain as a stable authoring component and ActorKind with conflicts against primitive,
brush, static renderer, and skinned renderer geometry sources.
- Add an inspector for resolution, world scale, chunk size, collider/shadow state, material summary,
validation, and a guarded flat-grid resize action. All mutations are one typed history step.
- Include terrain bounds in selection framing and generated chunks in authored-parent picking.
- Expose Add Terrain through the existing component shelf; no new permanent toolbar is added.
## Verification
- Tests cover descriptor validation, deterministic chunk coverage/mesh topology, hydration and
cleanup, generated-child stripping, serialization, and history round-trip.
- Source-only workspace format/check/strict-Clippy/tests and level validation run. Packaged tests
remain deferred by project-owner direction.
- Live native-Wayland acceptance creates or loads a terrain actor, verifies chunk rendering and
selection/inspection, changes scale/chunking, exercises undo/redo, and inspects a saved scene to
confirm generated chunks are absent.
@@ -0,0 +1,28 @@
# Terrain Material Layers And Weight Painting (#24)
## Scope
- Persist up to four shared Material/Material Instance references on each `TerrainDesc`.
- Store normalized RGBA8 layer weights per height sample with an implicit channel-zero default.
- Blend layer albedo, normal, metallic, and roughness in the project-owned raster material path.
- Assign, clear, reorder, and tile layers from the Terrain inspector.
- Paint or erase one selected layer from the existing horizontal viewport toolbar.
- Preserve one reflected history transaction per completed pointer stroke and exact cancel restore.
## Implementation
1. Extend the backward-compatible terrain schema with four layer descriptors and compact weights.
2. Emit normalized weights as terrain chunk vertex colors and attach a runtime-only material binding.
3. Build a terrain-specific `ExtendedMaterial` in `blacksite_surface`; keep invalid references on the visible fallback path with diagnostics.
4. Add inspector layer controls and a mutually exclusive modal paint operator beside Sculpt.
5. Cover serialization, validation, blend transport, paint normalization, cancel, undo, and redo.
6. Update ADR 0040, terrain workflow docs, the implementation checklist, and live evidence.
## Acceptance
- Two or more project materials visibly blend on one terrain.
- Layer weights remain exactly normalized and survive scene save/load.
- Live paint preview follows the sampled terrain surface.
- Escape/right-click restores exact pre-stroke weights; release creates one undo entry.
- Missing or invalid material references remain visible as fallback and produce clear diagnostics.
- Formatting, workspace check/clippy/tests, level validation, and live native-Wayland QA pass.
@@ -0,0 +1,25 @@
# Terrain Sculpt Tools (#23)
## Scope
- Add a modal terrain sculpt operator for raise, lower, flatten, smooth, and deterministic noise.
- Keep activation and brush settings in the existing horizontal viewport toolbar.
- Track a terrain-local cursor hit and render a world-space brush footprint preview.
- Apply live stroke previews while preserving one history entry per completed stroke.
- Restore the exact pre-stroke height grid on Escape or right-click.
## Implementation
1. Add pure heightfield sampling, ray-hit, falloff, and brush-dab functions with focused tests.
2. Add editor-only terrain sculpt state and viewport input/preview systems.
3. Commit strokes through the reflected component transaction after restoring the pre-stroke snapshot.
4. Add compact terrain controls to the existing viewport toolbar and update operator hints.
5. Document controls and validation evidence in the terrain editor guide and root checklist.
## Acceptance
- All five modes visibly modify terrain.
- The brush ring follows the actual terrain surface.
- Escape and right-click cancel without dirtying history.
- Mouse release creates exactly one undoable transaction regardless of dab count.
- Formatting, editor/shared checks, focused tests, and live editor QA pass.
+6
View File
@@ -170,6 +170,9 @@ deep-stale variants.
| Prefab Instance inspector | Inspect/recover source health, Apply/Revert overrides by scope, Apply overrides to source, create a variant, **Unpack Layer**, or recursively **Convert to Local** |
| Inspector component card | Collapse with caret, toggle active with status dot, or use triple-dot menu for reset/copy/paste/move/remove actions |
| Inspector footer → Add Component | Expands an inline search shelf for registered authoring, rendering, physics, gameplay, and volume components with descriptions, availability hints, and undo |
| Inspector footer → Add Component → Terrain | Add a height-grid terrain actor; configure grid scale/chunking/collision in its component card and use Resize Flat only for deliberate grid replacement |
| Selected Terrain → viewport mountains tool | Sculpt Raise/Lower/Flatten/Smooth/Noise strokes with a terrain-following footprint; release commits one undo step, while Escape/right-click restores the pre-stroke grid |
| Terrain card → Material Layers; selected Terrain → viewport paint tool | Assign up to four shared materials, then Paint/Erase normalized layer weights with live blended preview; release commits one undo step and Escape/right-click restores the pre-stroke map |
| Audio Source / Listener inspector | Assign and audition clips; edit gain, pitch, loop/autoplay, spatial blend, attenuation, bus, listener priority, and ear gap |
| Edit → Project Settings… | Edit `assets/project.ron` rendering, audio buses, physics, and input |
@@ -398,6 +401,9 @@ crates/
- [x] Filtered hierarchy, inspector, viewport, toolbar, asset browser, and status panels
- [x] Delete, duplicate, rename, and structural/material undo-redo
- [x] Native Bevy scene New/Open/Save/Save As with dirty title tracking
- [x] First-class height-grid Terrain actor with deterministic generated render/collider chunks, reflected history, validation, and a committed showcase fixture ([ADR 0039](docs/adr/0039-inline-height-grid-terrain-foundation.md), [terrain guide](docs/editor/terrain.md), [Gitea #22](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/22))
- [x] Modal terrain Raise/Lower/Flatten/Smooth/Noise sculpting with a terrain-following footprint, deterministic noise, safe cancel restore, and one undo transaction per stroke ([terrain guide](docs/editor/terrain.md), [Gitea #23](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/23))
- [x] Four shared terrain Material/Material Instance layers with compact normalized sample weights, blended raster hydration, drag/browse assignment, Paint/Erase preview, exact cancel, and one undo transaction per stroke ([ADR 0040](docs/adr/0040-terrain-material-layer-weights.md), [terrain guide](docs/editor/terrain.md), [Gitea #24](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/24))
- [x] Non-blocking native file/folder/confirmation broker across scene, asset, prefab, composition, collaboration, and Project Browser workflows ([ADR 0038](docs/adr/0038-non-blocking-native-dialog-broker.md), [workflow guide](docs/editor/native-dialogs.md), [Gitea #52](https://git.spacetrainclubhouse.com/Falling-Metal-Interactive/Blacksite/issues/52))
- [x] Asset import, static mesh/prefab placement, texture assignment, and selection export
- [x] PIE player-only snapshot/restore (authored `LevelObject` edits persist on stop)
+18
View File
@@ -269,6 +269,24 @@
),
dependencies: [],
),
(
id: ("1b25d451-7b54-41d6-af00-d2e6950f502d"),
path: "assets/levels/terrain_authoring_showcase.scn.ron",
label: "terrain_authoring_showcase.scn",
kind_tag: "Level",
import_settings: (
scale: 1.0,
generate_collider: true,
lod0_only: true,
placement_mode: StaticAsset,
hierarchy_mode: SingleActor,
material_policy: SourceMaterials,
static_mesh_manifest_path: None,
animation_manifest_path: None,
default_animation_clip_id: None,
),
dependencies: [],
),
(
id: ("dc13ce01-c7ce-43c5-974c-0e659ae49ab9"),
path: "assets/levels/editor_scene 2.scn.ron",
@@ -0,0 +1,87 @@
(schema_version: 4, resources: {}, entities: {
1: (components: {
"bevy_ecs::name::Name": "Terrain Showcase",
"bevy_transform::components::transform::Transform": (
translation: (0.0, 0.0, 0.0),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("terrain-showcase-main"),
"shared::components::ActorKind": Terrain,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (0),
"shared::components::LevelObject": (),
"shared::components::TerrainDesc": (
schema_version: 1,
resolution: 5,
heights: [
0.00, 0.00, 0.05, 0.00, 0.00,
0.00, 0.15, 0.30, 0.10, 0.00,
0.05, 0.35, 0.80, 0.25, 0.05,
0.00, 0.20, 0.40, 0.15, 0.00,
0.00, 0.00, 0.05, 0.00, 0.00,
],
sample_spacing: 2.0,
height_scale: 3.0,
chunk_quads: 2,
base_material: Some((
asset_id: "cc2769da-c9a5-4cb3-866a-cc81d0688ee2",
sub_asset_id: "material:instance",
label: "surface_tint_instance",
source_path: Some("assets/materials/surface_tint_instance.ron"),
)),
material_layers: [
(
material: Some((
asset_id: "a57f2891-8536-47b8-b476-01c08b36ac43",
sub_asset_id: "material:source",
label: "Concrete",
source_path: Some("assets/materials/concrete.ron"),
)),
uv_scale: 6.0,
),
(
material: Some((
asset_id: "d6cb4151-7124-4237-aaf9-f7f8abd5fb76",
sub_asset_id: "material:source",
label: "Surface Tint",
source_path: Some("assets/materials/surface_tint.ron"),
)),
uv_scale: 10.0,
),
],
material_weights: [
(255, 0, 0, 0), (255, 0, 0, 0), (224, 31, 0, 0), (255, 0, 0, 0), (255, 0, 0, 0),
(255, 0, 0, 0), (192, 63, 0, 0), (128, 127, 0, 0), (192, 63, 0, 0), (255, 0, 0, 0),
(224, 31, 0, 0), (128, 127, 0, 0), (0, 255, 0, 0), (128, 127, 0, 0), (224, 31, 0, 0),
(255, 0, 0, 0), (192, 63, 0, 0), (128, 127, 0, 0), (192, 63, 0, 0), (255, 0, 0, 0),
(255, 0, 0, 0), (255, 0, 0, 0), (224, 31, 0, 0), (255, 0, 0, 0), (255, 0, 0, 0),
],
generate_colliders: true,
cast_shadows: true,
receive_shadows: true,
),
}),
2: (components: {
"bevy_ecs::name::Name": "Terrain Sun",
"bevy_transform::components::transform::Transform": (
translation: (0.0, 8.0, 0.0),
rotation: (-0.3826834, 0.0, 0.0, 0.9238795),
scale: (1.0, 1.0, 1.0),
),
"shared::components::ActorId": ("terrain-showcase-sun"),
"shared::components::ActorKind": Light,
"shared::components::EditorVisibility": (visible: true),
"shared::components::HierarchySiblingIndex": (1),
"shared::components::LevelObject": (),
"shared::components::LightDesc": (
kind: Directional,
color: (r: 1.0, g: 0.95, b: 0.85, a: 1.0),
intensity: 100000.0,
range: 0.0,
shadows: true,
inner_angle_deg: 25.0,
outer_angle_deg: 35.0,
),
}),
})
+116
View File
@@ -0,0 +1,116 @@
#import bevy_pbr::{
pbr_fragment::pbr_input_from_standard_material,
pbr_functions::{alpha_discard, calculate_tbn_mikktspace},
}
#ifdef PREPASS_PIPELINE
#import bevy_pbr::{
prepass_io::{VertexOutput, FragmentOutput},
pbr_deferred_functions::deferred_output,
}
#else
#import bevy_pbr::{
forward_io::{VertexOutput, FragmentOutput},
pbr_functions::{apply_pbr_lighting, main_pass_post_lighting_processing},
}
#endif
struct TerrainLayerUniform {
base_colors: array<vec4<f32>, 4>,
properties: array<vec4<f32>, 4>,
uv_scales: vec4<f32>,
base_texture_enabled: vec4<f32>,
}
@group(#{MATERIAL_BIND_GROUP}) @binding(100) var<uniform> terrain_layers: TerrainLayerUniform;
@group(#{MATERIAL_BIND_GROUP}) @binding(101) var base_color0: texture_2d<f32>;
@group(#{MATERIAL_BIND_GROUP}) @binding(102) var base_sampler0: sampler;
@group(#{MATERIAL_BIND_GROUP}) @binding(103) var normal0: texture_2d<f32>;
@group(#{MATERIAL_BIND_GROUP}) @binding(104) var normal_sampler0: sampler;
@group(#{MATERIAL_BIND_GROUP}) @binding(105) var base_color1: texture_2d<f32>;
@group(#{MATERIAL_BIND_GROUP}) @binding(106) var base_sampler1: sampler;
@group(#{MATERIAL_BIND_GROUP}) @binding(107) var normal1: texture_2d<f32>;
@group(#{MATERIAL_BIND_GROUP}) @binding(108) var normal_sampler1: sampler;
@group(#{MATERIAL_BIND_GROUP}) @binding(109) var base_color2: texture_2d<f32>;
@group(#{MATERIAL_BIND_GROUP}) @binding(110) var base_sampler2: sampler;
@group(#{MATERIAL_BIND_GROUP}) @binding(111) var normal2: texture_2d<f32>;
@group(#{MATERIAL_BIND_GROUP}) @binding(112) var normal_sampler2: sampler;
@group(#{MATERIAL_BIND_GROUP}) @binding(113) var base_color3: texture_2d<f32>;
@group(#{MATERIAL_BIND_GROUP}) @binding(114) var base_sampler3: sampler;
@group(#{MATERIAL_BIND_GROUP}) @binding(115) var normal3: texture_2d<f32>;
@group(#{MATERIAL_BIND_GROUP}) @binding(116) var normal_sampler3: sampler;
fn layer_base(index: u32, uv: vec2<f32>) -> vec4<f32> {
if index == 0u { return textureSample(base_color0, base_sampler0, uv); }
if index == 1u { return textureSample(base_color1, base_sampler1, uv); }
if index == 2u { return textureSample(base_color2, base_sampler2, uv); }
return textureSample(base_color3, base_sampler3, uv);
}
fn layer_normal(index: u32, uv: vec2<f32>) -> vec3<f32> {
var sample = vec3<f32>(0.5, 0.5, 1.0);
if index == 0u { sample = textureSample(normal0, normal_sampler0, uv).xyz; }
if index == 1u { sample = textureSample(normal1, normal_sampler1, uv).xyz; }
if index == 2u { sample = textureSample(normal2, normal_sampler2, uv).xyz; }
if index == 3u { sample = textureSample(normal3, normal_sampler3, uv).xyz; }
return normalize(sample * 2.0 - 1.0);
}
@fragment
fn fragment(in: VertexOutput, @builtin(front_facing) is_front: bool) -> FragmentOutput {
var pbr_input = pbr_input_from_standard_material(in, is_front);
#ifdef VERTEX_UVS_A
let uv = in.uv;
#else
let uv = vec2<f32>(0.0);
#endif
#ifdef VERTEX_COLORS
var weights = max(in.color, vec4<f32>(0.0));
#else
var weights = vec4<f32>(1.0, 0.0, 0.0, 0.0);
#endif
let enabled = vec4<f32>(
terrain_layers.properties[0].w,
terrain_layers.properties[1].w,
terrain_layers.properties[2].w,
terrain_layers.properties[3].w,
);
weights *= enabled;
let total = dot(weights, vec4<f32>(1.0));
weights = select(vec4<f32>(1.0, 0.0, 0.0, 0.0), weights / total, total > 0.0001);
var color = vec4<f32>(0.0);
var normal_ts = vec3<f32>(0.0);
var metallic = 0.0;
var roughness = 0.0;
for (var index = 0u; index < 4u; index += 1u) {
let weight = weights[index];
let layer_uv = uv * terrain_layers.uv_scales[index];
let base_sample = mix(
vec4<f32>(1.0),
layer_base(index, layer_uv),
terrain_layers.base_texture_enabled[index],
);
color += base_sample * terrain_layers.base_colors[index] * weight;
let normal_enabled = terrain_layers.properties[index].z;
normal_ts += mix(vec3<f32>(0.0, 0.0, 1.0), layer_normal(index, layer_uv), normal_enabled) * weight;
metallic += terrain_layers.properties[index].x * weight;
roughness += terrain_layers.properties[index].y * weight;
}
pbr_input.material.base_color = alpha_discard(pbr_input.material, color);
pbr_input.material.metallic = clamp(metallic, 0.0, 1.0);
pbr_input.material.perceptual_roughness = clamp(roughness, 0.001, 1.0);
#ifdef VERTEX_TANGENTS
let tbn = calculate_tbn_mikktspace(pbr_input.world_normal, in.world_tangent);
let n = normalize(normal_ts);
pbr_input.N = normalize(n.x * tbn[0] + n.y * tbn[1] + n.z * tbn[2]);
#endif
#ifdef PREPASS_PIPELINE
return deferred_output(in, pbr_input);
#else
var out: FragmentOutput;
out.color = apply_pbr_lighting(pbr_input);
out.color = main_pass_post_lighting_processing(pbr_input, out.color);
return out;
#endif
}
+307 -8
View File
@@ -17,15 +17,92 @@ use bevy::render::render_resource::{
};
use bevy::shader::{Shader, ShaderRef};
use shared::{
asset_server_path, material_from_desc, HydratedRendererMaterialBinding, MaterialAsset,
MaterialInstanceAsset, MaterialParameterValue, MaterialRef, ShaderPropertyType,
ShaderSchemaAsset, MATERIAL_INSTANCE_SCHEMA_VERSION,
asset_server_path, material_from_desc, HydratedRendererMaterialBinding,
HydratedTerrainMaterialBinding, MaterialAsset, MaterialDesc, MaterialInstanceAsset,
MaterialParameterValue, MaterialRef, ShaderPropertyType, ShaderSchemaAsset,
TerrainMaterialLayer, MATERIAL_INSTANCE_SCHEMA_VERSION, TERRAIN_MATERIAL_LAYER_LIMIT,
};
pub const SURFACE_ABI_VERSION: u32 = 1;
pub const SURFACE_PARAMETER_LANES: usize = 16;
pub const SURFACE_TEXTURE_SLOTS: usize = 8;
pub const DEFAULT_SURFACE_SHADER_PATH: &str = "shaders/blacksite_surface.wgsl";
pub const TERRAIN_LAYER_SHADER_PATH: &str = "shaders/terrain_layers.wgsl";
#[derive(ShaderType, Reflect, Debug, Clone, Copy, PartialEq)]
pub struct TerrainLayerUniform {
pub base_colors: [Vec4; TERRAIN_MATERIAL_LAYER_LIMIT],
/// Metallic, perceptual roughness, normal-map enabled, layer enabled.
pub properties: [Vec4; TERRAIN_MATERIAL_LAYER_LIMIT],
pub uv_scales: Vec4,
pub base_texture_enabled: Vec4,
}
impl Default for TerrainLayerUniform {
fn default() -> Self {
Self {
base_colors: [Vec4::ONE; TERRAIN_MATERIAL_LAYER_LIMIT],
properties: [Vec4::new(0.0, 0.9, 0.0, 0.0); TERRAIN_MATERIAL_LAYER_LIMIT],
uv_scales: Vec4::splat(8.0),
base_texture_enabled: Vec4::ZERO,
}
}
}
#[derive(Asset, AsBindGroup, Reflect, Debug, Clone, Default)]
pub struct TerrainLayerExtension {
#[uniform(100)]
pub uniform: TerrainLayerUniform,
#[texture(101)]
#[sampler(102)]
pub base_color0: Option<Handle<Image>>,
#[texture(103)]
#[sampler(104)]
pub normal0: Option<Handle<Image>>,
#[texture(105)]
#[sampler(106)]
pub base_color1: Option<Handle<Image>>,
#[texture(107)]
#[sampler(108)]
pub normal1: Option<Handle<Image>>,
#[texture(109)]
#[sampler(110)]
pub base_color2: Option<Handle<Image>>,
#[texture(111)]
#[sampler(112)]
pub normal2: Option<Handle<Image>>,
#[texture(113)]
#[sampler(114)]
pub base_color3: Option<Handle<Image>>,
#[texture(115)]
#[sampler(116)]
pub normal3: Option<Handle<Image>>,
}
impl MaterialExtension for TerrainLayerExtension {
fn fragment_shader() -> ShaderRef {
TERRAIN_LAYER_SHADER_PATH.into()
}
fn deferred_fragment_shader() -> ShaderRef {
TERRAIN_LAYER_SHADER_PATH.into()
}
}
pub type TerrainLayerMaterial = ExtendedMaterial<StandardMaterial, TerrainLayerExtension>;
#[derive(Debug, Clone)]
struct TerrainLayerCacheEntry {
layers: Vec<TerrainMaterialLayer>,
handle: Handle<TerrainLayerMaterial>,
revision: u64,
}
#[derive(Resource, Default)]
struct TerrainLayerMaterialCache(HashMap<Entity, TerrainLayerCacheEntry>);
type TerrainMaterialBindings<'w, 's> =
Query<'w, 's, (Entity, &'static HydratedTerrainMaterialBinding)>;
#[derive(ShaderType, Reflect, Debug, Clone, Copy, PartialEq)]
pub struct SurfaceUniform {
@@ -121,10 +198,6 @@ impl MaterialExtension for SurfaceExtension {
DEFAULT_SURFACE_SHADER_PATH.into()
}
fn prepass_fragment_shader() -> ShaderRef {
DEFAULT_SURFACE_SHADER_PATH.into()
}
fn specialize(
_pipeline: &MaterialExtensionPipeline,
descriptor: &mut RenderPipelineDescriptor,
@@ -179,10 +252,180 @@ pub struct SurfaceMaterialPlugin;
impl Plugin for SurfaceMaterialPlugin {
fn build(&self, app: &mut App) {
app.add_plugins(MaterialPlugin::<SurfaceMaterial>::default())
.add_plugins(MaterialPlugin::<TerrainLayerMaterial>::default())
.init_resource::<SurfaceMaterialCache>()
.init_resource::<TerrainLayerMaterialCache>()
.init_resource::<SurfaceDiagnostics>()
.init_resource::<SurfaceEvaluatorRegistry>()
.add_systems(Update, sync_surface_material_bindings);
.add_systems(
Update,
(
sync_surface_material_bindings,
sync_terrain_layer_material_bindings,
),
);
}
}
fn sync_terrain_layer_material_bindings(
mut commands: Commands,
asset_server: Res<AssetServer>,
mut materials: ResMut<Assets<TerrainLayerMaterial>>,
mut cache: ResMut<TerrainLayerMaterialCache>,
mut diagnostics: ResMut<SurfaceDiagnostics>,
bindings: TerrainMaterialBindings,
) {
for (entity, binding) in &bindings {
if binding.layers.is_empty() {
continue;
}
let revision = terrain_layer_revision(&binding.layers);
let cached = cache
.0
.get(&binding.owner)
.filter(|entry| entry.layers == binding.layers && entry.revision == revision)
.map(|entry| entry.handle.clone());
let handle = cached.unwrap_or_else(|| {
let material =
build_terrain_layer_material(&asset_server, &binding.layers, &mut diagnostics.0);
let handle = cache
.0
.get(&binding.owner)
.map(|entry| entry.handle.clone())
.filter(|handle| {
materials
.get_mut(handle)
.map(|mut slot| {
*slot = material.clone();
})
.is_some()
})
.unwrap_or_else(|| materials.add(material));
cache.0.insert(
binding.owner,
TerrainLayerCacheEntry {
layers: binding.layers.clone(),
handle: handle.clone(),
revision,
},
);
handle
});
commands
.entity(entity)
.remove::<MeshMaterial3d<StandardMaterial>>()
.insert(MeshMaterial3d(handle));
}
}
fn terrain_layer_revision(layers: &[TerrainMaterialLayer]) -> u64 {
let mut dependencies = layers
.iter()
.filter_map(|layer| layer.material.as_ref())
.filter_map(|reference| reference.source_path.as_deref())
.flat_map(|path| material_dependency_paths(path).unwrap_or_else(|_| vec![path.to_string()]))
.collect::<Vec<_>>();
dependencies.sort();
dependencies.dedup();
dependency_revision(&dependencies)
}
fn build_terrain_layer_material(
asset_server: &AssetServer,
layers: &[TerrainMaterialLayer],
diagnostics: &mut Vec<String>,
) -> TerrainLayerMaterial {
let mut extension = TerrainLayerExtension::default();
for (index, layer) in layers.iter().take(TERRAIN_MATERIAL_LAYER_LIMIT).enumerate() {
extension.uniform.uv_scales[index] = layer.uv_scale;
let desc = resolve_terrain_layer(layer, index, diagnostics);
let color = desc.base_color.to_color().to_linear();
extension.uniform.base_colors[index] =
Vec4::new(color.red, color.green, color.blue, color.alpha);
extension.uniform.properties[index] = Vec4::new(
desc.metallic,
desc.roughness,
f32::from(desc.normal_map_texture.is_some()),
1.0,
);
extension.uniform.base_texture_enabled[index] =
f32::from(desc.base_color_texture.is_some());
let base_color = desc
.base_color_texture
.as_deref()
.map(|path| asset_server.load(asset_server_path(path)));
let normal = desc
.normal_map_texture
.as_deref()
.map(|path| asset_server.load(asset_server_path(path)));
match index {
0 => {
extension.base_color0 = base_color;
extension.normal0 = normal;
}
1 => {
extension.base_color1 = base_color;
extension.normal1 = normal;
}
2 => {
extension.base_color2 = base_color;
extension.normal2 = normal;
}
3 => {
extension.base_color3 = base_color;
extension.normal3 = normal;
}
_ => {}
}
}
TerrainLayerMaterial {
base: StandardMaterial {
base_color: Color::WHITE,
perceptual_roughness: 1.0,
..default()
},
extension,
}
}
fn resolve_terrain_layer(
layer: &TerrainMaterialLayer,
index: usize,
diagnostics: &mut Vec<String>,
) -> MaterialDesc {
let Some(reference) = layer.material.as_ref() else {
diagnostics.push(format!(
"terrain material layer {} is unassigned; using visible fallback",
index + 1
));
return terrain_layer_fallback();
};
let Some(path) = reference.source_path.as_deref() else {
diagnostics.push(format!(
"terrain material layer {} ({}) has no loadable source path; using visible fallback",
index + 1,
reference.label
));
return terrain_layer_fallback();
};
match shared::load_resolved_material_from_path(path) {
Ok((desc, _)) => desc,
Err(error) => {
diagnostics.push(format!(
"terrain material layer {} ({}) could not resolve: {error}; using visible fallback",
index + 1,
reference.label
));
terrain_layer_fallback()
}
}
}
fn terrain_layer_fallback() -> MaterialDesc {
MaterialDesc {
base_color: shared::ColorDesc::srgb(0.24, 0.29, 0.25),
roughness: 0.92,
..Default::default()
}
}
@@ -759,4 +1002,60 @@ mod tests {
assert_eq!(SURFACE_TEXTURE_SLOTS, 8);
assert_eq!(std::mem::size_of::<SurfaceUniform>(), 400);
}
#[test]
fn material_extensions_leave_non_deferred_prepasses_to_standard_material() {
assert!(matches!(
<SurfaceExtension as MaterialExtension>::prepass_fragment_shader(),
ShaderRef::Default
));
assert!(matches!(
<TerrainLayerExtension as MaterialExtension>::prepass_fragment_shader(),
ShaderRef::Default
));
}
#[test]
fn terrain_layer_builder_packs_project_material_values() {
let mut app = App::new();
app.add_plugins((MinimalPlugins, AssetPlugin::default()));
let asset_server = app.world().resource::<AssetServer>();
let materials_root =
std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../assets/materials");
let layers = [
TerrainMaterialLayer {
material: Some(
shared::EditorAssetRef::new("concrete", "material:source", "Concrete")
.with_source_path(
materials_root.join("concrete.ron").display().to_string(),
),
),
uv_scale: 6.0,
},
TerrainMaterialLayer {
material: Some(
shared::EditorAssetRef::new("tint", "material:source", "Surface Tint")
.with_source_path(
materials_root
.join("surface_tint.ron")
.display()
.to_string(),
),
),
uv_scale: 10.0,
},
];
let mut diagnostics = Vec::new();
let material = build_terrain_layer_material(asset_server, &layers, &mut diagnostics);
assert!(diagnostics.is_empty(), "{diagnostics:?}");
assert_eq!(material.extension.uniform.uv_scales.x, 6.0);
assert_eq!(material.extension.uniform.uv_scales.y, 10.0);
assert_eq!(material.extension.uniform.properties[0].w, 1.0);
assert_eq!(material.extension.uniform.properties[1].w, 1.0);
assert_ne!(
material.extension.uniform.base_colors[0],
material.extension.uniform.base_colors[1]
);
}
}
+12 -20
View File
@@ -1415,16 +1415,13 @@ pub fn apply_reflected_component(
let reflected = TypedReflectDeserializer::new(registration, &type_registry)
.deserialize(&mut deserializer)
.map_err(|error| error.to_string())?;
let exists = reflect_component.reflect(world.entity(entity)).is_some();
if exists {
reflect_component.apply(world.entity_mut(entity), reflected.as_ref());
} else {
reflect_component.insert(
&mut world.entity_mut(entity),
reflected.as_ref(),
&type_registry,
);
}
// Reflected `apply` merges list fields and cannot restore a shorter snapshot.
// Inserting the captured concrete component replaces the value atomically.
reflect_component.insert(
&mut world.entity_mut(entity),
reflected.as_ref(),
&type_registry,
);
}
None => reflect_component.remove(&mut world.entity_mut(entity)),
}
@@ -1451,16 +1448,11 @@ pub fn apply_reflected_default(
.data::<ReflectDefault>()
.ok_or_else(|| format!("component `{type_path}` has no reflected Default"))?
.default();
let exists = reflect_component.reflect(world.entity(entity)).is_some();
if exists {
reflect_component.apply(world.entity_mut(entity), default.as_ref());
} else {
reflect_component.insert(
&mut world.entity_mut(entity),
default.as_ref(),
&type_registry,
);
}
reflect_component.insert(
&mut world.entity_mut(entity),
default.as_ref(),
&type_registry,
);
Ok(())
})
}
+6
View File
@@ -43,6 +43,8 @@ pub use viewport::render_view;
pub use viewport::rendering_diagnostics;
pub use viewport::selection;
pub use viewport::selection_outline;
pub use viewport::terrain_paint;
pub use viewport::terrain_sculpt;
pub use viewport::visualizers;
use bevy::app::PluginGroupBuilder;
@@ -79,6 +81,8 @@ use selection_outline::SelectionOutlinePlugin;
use session::EditorSessionPlugin;
use settings_ui::SettingsUiPlugin;
use state::EditorStatePlugin;
use terrain_paint::TerrainPaintPlugin;
use terrain_sculpt::TerrainSculptPlugin;
use ui::EditorUiPlugin;
use viewport::ViewportPlugin;
use visualizers::EditorVisualizersPlugin;
@@ -109,6 +113,8 @@ impl PluginGroup for EditorPluginGroup {
.add(BrushCsgPlugin)
.add(BrushEditPlugin)
.add(BrushToolPlugin)
.add(TerrainSculptPlugin)
.add(TerrainPaintPlugin)
.add(EditorCameraPlugin)
.add(AudioPreviewPlugin)
.add(ActorIconsPlugin)
+3
View File
@@ -1113,6 +1113,9 @@ fn format_actor_validation(err: ActorValidationError) -> String {
ActorValidationError::InvalidBrushGeometry(message) => {
format!("Save failed: invalid brush geometry: {message}")
}
ActorValidationError::InvalidTerrain(message) => {
format!("Save failed: invalid terrain: {message}")
}
ActorValidationError::StaticMeshMissingPrimitive => {
"Save failed: StaticMesh actor requires Primitive or StaticMeshRenderer with a mesh slot"
.into()
@@ -112,6 +112,7 @@ pub fn draw_actor_inspector(world: &mut World, ui: &mut egui::Ui, entity: Entity
ActorKind::StaticMesh
| ActorKind::SkinnedMesh
| ActorKind::Brush
| ActorKind::Terrain
| ActorKind::ImportedModel
| ActorKind::Light
| ActorKind::Empty
@@ -143,6 +144,7 @@ fn actor_icon(kind: ActorKind) -> egui_phosphor_icons::Icon {
ActorKind::StaticMesh
| ActorKind::SkinnedMesh
| ActorKind::Brush
| ActorKind::Terrain
| ActorKind::ImportedModel => icons::CUBE,
ActorKind::Light => icons::LIGHTBULB,
ActorKind::PrefabAnchor => icons::PACKAGE,
@@ -373,6 +373,27 @@ impl Default for EditorComponentRegistry {
],
hydration_effect: "Hydrates into generated brush mesh children.",
},
EditorComponentDescriptor {
id: shared::AUTHORING_COMPONENT_TERRAIN,
type_name: "shared::components::TerrainDesc",
display_name: "Terrain",
category: EditorComponentCategory::Authoring,
addable: true,
removable: true,
reorderable: true,
hidden: false,
icon: icons::MOUNTAINS.as_str(),
description: "Creates chunked height-grid terrain with optional collision.",
search_terms: &["terrain", "landscape", "heightmap", "ground", "chunk"],
recommended: &[],
conflicts_with: &[
"shared::components::Primitive",
"shared::components::BrushDesc",
"shared::components::StaticMeshRenderer",
"shared::animation::SkinnedMeshRenderer",
],
hydration_effect: "Hydrates into generated render and collider chunks.",
},
EditorComponentDescriptor {
id: shared::AUTHORING_COMPONENT_MATERIAL,
type_name: "shared::components::MaterialDesc",
+2
View File
@@ -205,6 +205,7 @@ fn actor_kind_sort_key(world: &World, entity: Entity) -> u8 {
.map(|kind| match kind {
ActorKind::Empty => 0,
ActorKind::Brush
| ActorKind::Terrain
| ActorKind::StaticMesh
| ActorKind::SkinnedMesh
| ActorKind::ImportedModel => 1,
@@ -468,6 +469,7 @@ pub fn actor_kind_icon(kind: ActorKind) -> &'static str {
match kind {
ActorKind::Empty => icons::FOLDER.as_str(),
ActorKind::Brush => icons::CUBE.as_str(),
ActorKind::Terrain => icons::MOUNTAINS.as_str(),
ActorKind::StaticMesh => icons::CUBE.as_str(),
ActorKind::SkinnedMesh => icons::PERSON_SIMPLE_RUN.as_str(),
ActorKind::ImportedModel => icons::CUBE_TRANSPARENT.as_str(),
+324 -4
View File
@@ -16,8 +16,8 @@ use shared::{
MaterialParameterValue, MaterialRef, MaterialShaderKind, NavigationArea, NavigationBounds,
NavigationLink, NavigationObstacle, ObjectiveMarker, PhysicsBody, PlayerSpawn,
PostProcessVolumeDesc, PrefabInstance, Primitive, PrimitiveShape, ProjectSun, RigidBodyDesc,
SkinnedMeshRenderer, StaticMeshRenderer, StaticMeshRendererEntry, TeamSpawn, TriggerVolume,
WeaponSpawn, AUTHORING_DIRECTIONAL_LUX_MAX, AUTHORING_POINT_SPOT_LUMENS_MAX,
SkinnedMeshRenderer, StaticMeshRenderer, StaticMeshRendererEntry, TeamSpawn, TerrainDesc,
TriggerVolume, WeaponSpawn, AUTHORING_DIRECTIONAL_LUX_MAX, AUTHORING_POINT_SPOT_LUMENS_MAX,
COMPONENT_ANIMATION_CONTROLLER_DESC, COMPONENT_AUDIO_LISTENER_DESC,
COMPONENT_AUDIO_SOURCE_DESC, COMPONENT_BRUSH_DESC, COMPONENT_COLLIDER_DESC,
COMPONENT_LIGHT_DESC, COMPONENT_MATERIAL_DESC, COMPONENT_NAVIGATION_AREA,
@@ -25,8 +25,8 @@ use shared::{
COMPONENT_OBJECTIVE_MARKER, COMPONENT_PHYSICS_BODY, COMPONENT_PLAYER_SPAWN,
COMPONENT_POST_PROCESS_VOLUME, COMPONENT_PREFAB_INSTANCE, COMPONENT_PRIMITIVE,
COMPONENT_PROJECT_SUN, COMPONENT_RIGID_BODY_DESC, COMPONENT_SKINNED_MESH_RENDERER,
COMPONENT_STATIC_MESH_RENDERER, COMPONENT_TEAM_SPAWN, COMPONENT_TRIGGER_VOLUME,
COMPONENT_WEAPON_SPAWN,
COMPONENT_STATIC_MESH_RENDERER, COMPONENT_TEAM_SPAWN, COMPONENT_TERRAIN_DESC,
COMPONENT_TRIGGER_VOLUME, COMPONENT_WEAPON_SPAWN,
};
use crate::history::{
@@ -1110,6 +1110,7 @@ fn draw_authoring_component_by_type(
COMPONENT_STATIC_MESH_RENDERER => static_mesh_renderer_ui(world, ui, entity),
COMPONENT_SKINNED_MESH_RENDERER => skinned_mesh_renderer_ui(world, ui, entity),
COMPONENT_BRUSH_DESC => brush_editor_ui(world, ui, entity),
COMPONENT_TERRAIN_DESC => terrain_editor_ui(world, ui, entity),
COMPONENT_PRIMITIVE => primitive_editor_ui(world, ui, entity),
COMPONENT_MATERIAL_DESC => material_editor_ui(world, ui, entity),
COMPONENT_LIGHT_DESC => light_editor_ui(world, ui, entity),
@@ -3494,6 +3495,325 @@ fn brush_editor_ui(world: &mut World, ui: &mut egui::Ui, entity: Entity) {
}
}
fn terrain_editor_ui(world: &mut World, ui: &mut egui::Ui, entity: Entity) {
let material_candidates = brush_face_material_ref_candidates(world);
let dragging_selection = world
.get_resource::<EditorAssets>()
.and_then(|assets| assets.dragging_selection().cloned());
let material_drop_candidate = dragging_selection.as_ref().and_then(|selection| {
asset_ref_candidate_from_selection(world, selection, AssetRefCandidateKind::Material)
});
let Some(mut terrain) = world.get::<TerrainDesc>(entity).cloned() else {
return;
};
let original = terrain.clone();
let mut changed = false;
let mut requested_resolution = terrain.resolution;
let mut remove_layer = None;
let mut swap_layers = None;
let mut locate_layer = None;
let mut accepted_drop = false;
let card = component_card_context(
world,
entity,
ComponentCardOptions::removable(COMPONENT_TERRAIN_DESC, "Terrain", icons::MOUNTAINS),
);
let card_response = component_card(ui, &card, |ui| {
property_row(ui, "Grid", |ui| {
ui.horizontal(|ui| {
ui.add(
egui::DragValue::new(&mut requested_resolution)
.range(2..=1025)
.suffix(" samples"),
);
if ui
.add_enabled(
requested_resolution != terrain.resolution,
egui::Button::new("Resize Flat"),
)
.on_hover_text("Replaces the current height grid with a flat grid")
.clicked()
{
let replacement = TerrainDesc::flat(requested_resolution);
terrain.resolution = replacement.resolution;
terrain.heights = replacement.heights;
terrain.material_weights.clear();
terrain.chunk_quads = terrain.chunk_quads.min(terrain.resolution - 1).max(1);
changed = true;
}
});
});
property_row(ui, "Sample Spacing", |ui| {
changed |= ui
.add(
egui::DragValue::new(&mut terrain.sample_spacing)
.range(0.01..=1000.0)
.speed(0.1)
.suffix(" m"),
)
.changed();
});
property_row(ui, "Height Scale", |ui| {
changed |= ui
.add(
egui::DragValue::new(&mut terrain.height_scale)
.range(0.01..=10000.0)
.speed(0.1)
.suffix(" m"),
)
.changed();
});
property_row(ui, "Chunk Size", |ui| {
changed |= ui
.add(
egui::DragValue::new(&mut terrain.chunk_quads)
.range(1..=terrain.resolution.saturating_sub(1))
.suffix(" quads"),
)
.changed();
});
property_row(ui, "Collision", |ui| {
changed |= ui
.checkbox(&mut terrain.generate_colliders, "Generate")
.changed();
});
property_row(ui, "Shadows", |ui| {
ui.horizontal_wrapped(|ui| {
changed |= ui.checkbox(&mut terrain.cast_shadows, "Cast").changed();
changed |= ui
.checkbox(&mut terrain.receive_shadows, "Receive")
.changed();
});
});
ui.add_space(6.0);
ui.separator();
ui.horizontal(|ui| {
ui.label(egui::RichText::new("Material Layers").strong());
ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
if ui
.add_enabled(
terrain.material_layers.len() < shared::TERRAIN_MATERIAL_LAYER_LIMIT,
egui::Button::new(phosphor_icon(icons::PLUS, 16.0)),
)
.on_hover_text("Add a terrain blend channel")
.clicked()
{
let material = if terrain.material_layers.is_empty() {
terrain.base_material.take()
} else {
None
};
terrain.material_layers.push(shared::TerrainMaterialLayer {
material,
..Default::default()
});
changed = true;
}
});
});
if terrain.material_layers.is_empty() {
ui.label(
egui::RichText::new(
terrain
.base_material
.as_ref()
.map(|material| format!("Legacy base: {}", material.label))
.unwrap_or_else(|| "No layers assigned; visible terrain fallback".into()),
)
.color(TEXT_DIM)
.small(),
);
}
for index in 0..terrain.material_layers.len() {
ui.add_space(4.0);
ui.horizontal(|ui| {
ui.label(
egui::RichText::new(format!("Layer {}", index + 1))
.strong()
.color(if index == 0 {
SELECTION_BG_MUTED
} else {
TEXT_DIM
}),
);
ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
if icon_button_small(ui, icons::TRASH, "Remove layer").clicked() {
remove_layer = Some(index);
}
if ui
.add_enabled(
index + 1 < terrain.material_layers.len(),
egui::Button::new(phosphor_icon(icons::ARROW_DOWN, 15.0)).frame(false),
)
.on_hover_text("Move layer down")
.clicked()
{
swap_layers = Some((index, index + 1));
}
if ui
.add_enabled(
index > 0,
egui::Button::new(phosphor_icon(icons::ARROW_UP, 15.0)).frame(false),
)
.on_hover_text("Move layer up")
.clicked()
{
swap_layers = Some((index, index - 1));
}
});
});
let response = asset_selector_row(
ui,
"Material",
icons::PALETTE,
terrain.material_layers[index].material.as_ref(),
None,
true,
&material_candidates,
material_drop_candidate.as_ref(),
);
if let Some(selected) = response.selected {
terrain.material_layers[index].material = Some(selected);
changed = true;
}
if response.clear {
terrain.material_layers[index].material = None;
changed = true;
}
if response.locate {
locate_layer = Some(index);
}
accepted_drop |= response.accepted_drop;
property_row(ui, "UV Tiling", |ui| {
changed |= ui
.add(
egui::DragValue::new(&mut terrain.material_layers[index].uv_scale)
.range(0.01..=1024.0)
.speed(0.1)
.suffix("×"),
)
.changed();
});
if !terrain.material_weights.is_empty() {
let covered = terrain
.material_weights
.iter()
.filter(|weights| weights[index] > 0)
.count();
ui.label(
egui::RichText::new(format!(
"{} / {} samples carry this layer",
covered,
terrain.material_weights.len()
))
.color(TEXT_DIM)
.small(),
);
}
}
match terrain.validate() {
Ok(()) => {
ui.label(
egui::RichText::new(format!(
"{} heights • {}×{} chunks",
terrain.heights.len(),
(terrain.resolution - 1).div_ceil(terrain.chunk_quads),
(terrain.resolution - 1).div_ceil(terrain.chunk_quads)
))
.color(super::theme::SUCCESS),
);
}
Err(error) => {
ui.label(egui::RichText::new(error).color(super::theme::ERROR));
}
}
});
apply_component_card_response(world, entity, card_response);
if let Some(index) = remove_layer {
remove_terrain_material_layer(&mut terrain, index);
changed = true;
}
if let Some((a, b)) = swap_layers {
terrain.material_layers.swap(a, b);
for weights in &mut terrain.material_weights {
weights.swap(a, b);
}
changed = true;
}
if let Some(index) = locate_layer {
locate_asset_ref(
world,
terrain
.material_layers
.get(index)
.and_then(|layer| layer.material.as_ref()),
&material_candidates,
);
}
if accepted_drop {
clear_asset_drag(world);
}
if changed && terrain != original {
let _ = reflected_component_transaction(
world,
entity,
"Edit Terrain",
shared::AUTHORING_COMPONENT_TERRAIN,
COMPONENT_TERRAIN_DESC,
move |world, entity| {
world.entity_mut(entity).insert(terrain);
Ok(())
},
);
}
}
fn remove_terrain_material_layer(terrain: &mut TerrainDesc, index: usize) {
if index >= terrain.material_layers.len() {
return;
}
terrain.material_layers.remove(index);
if terrain.material_layers.is_empty() {
terrain.material_weights.clear();
return;
}
for weights in &mut terrain.material_weights {
for channel in index..3 {
weights[channel] = weights[channel + 1];
}
weights[3] = 0;
normalize_terrain_weights(weights, terrain.material_layers.len());
}
}
fn normalize_terrain_weights(weights: &mut [u8; 4], layer_count: usize) {
for weight in weights.iter_mut().skip(layer_count) {
*weight = 0;
}
let sum: u16 = weights
.iter()
.take(layer_count)
.copied()
.map(u16::from)
.sum();
if sum == 0 {
*weights = [255, 0, 0, 0];
return;
}
let source = *weights;
let mut assigned = 0_u16;
for index in 0..layer_count {
weights[index] = ((u16::from(source[index]) * 255) / sum) as u8;
assigned += u16::from(weights[index]);
}
let largest = (0..layer_count)
.max_by_key(|index| source[*index])
.unwrap_or(0);
weights[largest] = weights[largest].saturating_add((255 - assigned) as u8);
}
fn brush_validation_ui(ui: &mut egui::Ui, brush: &BrushDesc) {
let report = validate_brush(brush);
if report.diagnostics.is_empty() {
+291 -1
View File
@@ -20,6 +20,8 @@ use crate::state::PlayPossession;
use crate::viewport::actor_icons::ActorIconSettings;
use crate::viewport::brush_edit::{BrushEditMode, BrushElementSelection};
use crate::viewport::brush_tool::{BrushToolPhase, BrushToolState};
use crate::viewport::terrain_paint::{TerrainPaintMode, TerrainPaintState};
use crate::viewport::terrain_sculpt::{TerrainSculptMode, TerrainSculptState};
use crate::viewport::{
material_drop::is_surface_asset_selection, snap_translation, viewport_ground_position,
EditorViewportMode, MaterialDropState, ViewportDisplayMode, ViewportSettings,
@@ -41,6 +43,7 @@ use super::widgets::{
pub struct ViewportUiState {
pub options_open: bool,
pub shortcuts_open: bool,
pub toolbar_rect: Option<egui::Rect>,
}
const VIEWPORT_TOOLTIP: &str = "RMB + WASD/QE: fly | MMB: pan | Scroll: dolly\nW/E/R: gizmo | X: world/local | F: focus | G: game view | Ctrl+G: grid\nTab: cycle overlapping picks | Play/Pause/Stop: main toolbar (F5 / F6)";
@@ -146,6 +149,8 @@ pub fn viewport_tab_ui(
scene_view_overlay_toolbar(world, ui.ctx(), rect);
scene_view_selection_hud(world, ui.ctx(), rect, selected_entities);
scene_view_brush_draw_hints(world, ui.ctx(), rect);
scene_view_terrain_sculpt_hints(world, ui.ctx(), rect);
scene_view_terrain_paint_hints(world, ui.ctx(), rect);
scene_view_render_badge(world, ui.ctx(), rect);
scene_view_brush_mode_badge(world, ui.ctx(), rect);
scene_view_volume_hud(world, ui.ctx(), rect);
@@ -304,6 +309,94 @@ fn scene_view_brush_draw_hints(world: &World, ctx: &egui::Context, scene_rect: e
});
}
fn scene_view_terrain_sculpt_hints(world: &World, ctx: &egui::Context, scene_rect: egui::Rect) {
let Some(tool) = world.get_resource::<TerrainSculptState>() else {
return;
};
if !tool.active {
return;
}
egui::Area::new(egui::Id::new("scene_view_terrain_sculpt_hints"))
.fixed_pos(scene_rect.left_top() + egui::vec2(8.0, 52.0))
.interactable(false)
.show(ctx, |ui| {
overlay_chip_frame().show(ui, |ui| {
ui.horizontal(|ui| {
ui.label(
egui::RichText::new(format!("Terrain {}", tool.mode.label()))
.color(SELECTION)
.strong(),
);
ui.label(
egui::RichText::new(format!("R {:.1}m", tool.radius))
.color(TEXT_DIM)
.monospace()
.small(),
);
ui.label(
egui::RichText::new(format!("S {:.2}m", tool.strength))
.color(SUCCESS)
.monospace()
.small(),
);
});
ui.add_space(4.0);
ui.horizontal_wrapped(|ui| {
key_hint(ui, "LMB Drag", "Sculpt");
key_hint(ui, "Esc", "Cancel stroke / close");
key_hint(ui, "RMB", "Cancel stroke / close");
key_hint(ui, "Ctrl+Z", "Undo stroke");
});
});
});
}
fn scene_view_terrain_paint_hints(world: &World, ctx: &egui::Context, scene_rect: egui::Rect) {
let Some(tool) = world.get_resource::<TerrainPaintState>() else {
return;
};
if !tool.active {
return;
}
egui::Area::new(egui::Id::new("scene_view_terrain_paint_hints"))
.fixed_pos(scene_rect.left_top() + egui::vec2(8.0, 52.0))
.interactable(false)
.show(ctx, |ui| {
overlay_chip_frame().show(ui, |ui| {
ui.horizontal(|ui| {
ui.label(
egui::RichText::new(format!(
"Terrain {} • Layer {}",
tool.mode.label(),
tool.active_layer + 1
))
.color(SELECTION)
.strong(),
);
ui.label(
egui::RichText::new(format!("R {:.1}m", tool.radius))
.color(TEXT_DIM)
.monospace()
.small(),
);
ui.label(
egui::RichText::new(format!("S {:.0}%", tool.strength * 100.0))
.color(SUCCESS)
.monospace()
.small(),
);
});
ui.add_space(4.0);
ui.horizontal_wrapped(|ui| {
key_hint(ui, "LMB Drag", tool.mode.label());
key_hint(ui, "Esc", "Cancel stroke / close");
key_hint(ui, "RMB", "Cancel stroke / close");
key_hint(ui, "Ctrl+Z", "Undo stroke");
});
});
});
}
fn key_hint(ui: &mut egui::Ui, key: &str, label: &str) {
ui.horizontal(|ui| {
ui.label(
@@ -492,8 +585,30 @@ fn scene_view_volume_hud(world: &World, ctx: &egui::Context, scene_rect: egui::R
fn scene_view_overlay_toolbar(world: &mut World, ctx: &egui::Context, scene_rect: egui::Rect) {
let mut options_open = world.resource::<ViewportUiState>().options_open;
let mut shortcuts_open = world.resource::<ViewportUiState>().shortcuts_open;
let terrain_selected = world
.resource::<crate::selection::SelectedEntity>()
.0
.filter(|entity| world.get::<shared::TerrainDesc>(*entity).is_some());
let terrain_layer_labels = terrain_selected
.and_then(|entity| world.get::<shared::TerrainDesc>(entity))
.map(|terrain| {
terrain
.material_layers
.iter()
.enumerate()
.map(|(index, layer)| {
layer
.material
.as_ref()
.map(|material| material.label.clone())
.filter(|label| !label.trim().is_empty())
.unwrap_or_else(|| format!("Layer {}", index + 1))
})
.collect::<Vec<_>>()
})
.unwrap_or_default();
egui::Area::new(egui::Id::new("scene_view_toolbar"))
let toolbar_response = egui::Area::new(egui::Id::new("scene_view_toolbar"))
.fixed_pos(scene_rect.left_top() + egui::vec2(6.0, 6.0))
.interactable(true)
.show(ctx, |ui| {
@@ -622,6 +737,174 @@ fn scene_view_overlay_toolbar(world: &mut World, ctx: &egui::Context, scene_rect
}
}
let sculpt_active = world.resource::<TerrainSculptState>().active;
let paint_active = world.resource::<TerrainPaintState>().active;
if terrain_selected.is_some() || sculpt_active || paint_active {
ui.separator();
let stroking = world.resource::<TerrainSculptState>().is_stroking();
let sculpt_button_clicked = tool_button_accent(
ui,
icons::MOUNTAINS,
sculpt_active,
if sculpt_active {
"Close terrain sculpt tool"
} else {
"Sculpt selected terrain"
},
)
.clicked();
if sculpt_button_clicked {
world.resource_mut::<ViewportClick>().0 = None;
}
if sculpt_button_clicked && !stroking {
let state = &mut *world.resource_mut::<TerrainSculptState>();
if state.active {
state.stop();
} else if let Some(entity) = terrain_selected {
state.start(entity);
}
let active = state.active;
if active {
world.resource_mut::<TerrainPaintState>().stop();
world.resource_mut::<BrushToolState>().cancel();
world
.resource_mut::<crate::operators::ActiveOperator>()
.status = Some(crate::operators::OperatorStatus {
id: "terrain.sculpt".to_string(),
label: "Terrain Sculpt".to_string(),
phase: crate::operators::OperatorPhase::Preview,
hint: "LMB drag sculpts; Esc or RMB cancels".to_string(),
warnings: Vec::new(),
});
}
}
if sculpt_active {
let mut mode = world.resource::<TerrainSculptState>().mode;
for candidate in [
TerrainSculptMode::Raise,
TerrainSculptMode::Lower,
TerrainSculptMode::Flatten,
TerrainSculptMode::Smooth,
TerrainSculptMode::Noise,
] {
ui.selectable_value(&mut mode, candidate, candidate.label())
.on_hover_text(format!("{} terrain", candidate.label()));
}
let mut radius = world.resource::<TerrainSculptState>().radius;
let mut strength = world.resource::<TerrainSculptState>().strength;
ui.add(
egui::DragValue::new(&mut radius)
.range(0.25..=128.0)
.speed(0.1)
.prefix("R ")
.suffix(" m"),
)
.on_hover_text("Brush radius");
ui.add(
egui::DragValue::new(&mut strength)
.range(0.01..=20.0)
.speed(0.05)
.prefix("S ")
.suffix(" m"),
)
.on_hover_text("Height strength per dab");
let mut state = world.resource_mut::<TerrainSculptState>();
state.mode = mode;
state.radius = radius;
state.strength = strength;
state.clamp_settings();
}
let paint_stroking = world.resource::<TerrainPaintState>().is_stroking();
let can_paint = terrain_layer_labels.len() >= 2 || paint_active;
let paint_button_clicked = ui
.add_enabled(
can_paint,
egui::Button::new(phosphor_icon(icons::PAINT_BRUSH, 16.0))
.selected(paint_active),
)
.on_hover_text(if can_paint {
if paint_active {
"Close terrain material paint tool"
} else {
"Paint selected terrain material layers"
}
} else {
"Assign at least two terrain material layers first"
})
.clicked();
if paint_button_clicked {
world.resource_mut::<ViewportClick>().0 = None;
}
if paint_button_clicked && !paint_stroking {
let layer_count = terrain_layer_labels.len();
let state = &mut *world.resource_mut::<TerrainPaintState>();
if state.active {
state.stop();
} else if let Some(entity) = terrain_selected {
state.start(entity, layer_count);
}
let active = state.active;
if active {
world.resource_mut::<TerrainSculptState>().stop();
world.resource_mut::<BrushToolState>().cancel();
world
.resource_mut::<crate::operators::ActiveOperator>()
.status = Some(crate::operators::OperatorStatus {
id: "terrain.paint".into(),
label: "Terrain Paint".into(),
phase: crate::operators::OperatorPhase::Preview,
hint: "LMB drag paints weights; Esc or RMB cancels".into(),
warnings: Vec::new(),
});
}
}
if paint_active {
let mut mode = world.resource::<TerrainPaintState>().mode;
ui.selectable_value(&mut mode, TerrainPaintMode::Paint, "Paint")
.on_hover_text("Increase the selected layer weight");
ui.selectable_value(&mut mode, TerrainPaintMode::Erase, "Erase")
.on_hover_text("Reduce the selected layer weight");
let mut active_layer =
world.resource::<TerrainPaintState>().active_layer;
egui::ComboBox::from_id_salt("terrain_paint_layer")
.selected_text(
terrain_layer_labels
.get(active_layer)
.cloned()
.unwrap_or_else(|| "Layer".into()),
)
.show_ui(ui, |ui| {
for (index, label) in terrain_layer_labels.iter().enumerate() {
ui.selectable_value(&mut active_layer, index, label);
}
});
let mut radius = world.resource::<TerrainPaintState>().radius;
let mut strength = world.resource::<TerrainPaintState>().strength;
ui.add(
egui::DragValue::new(&mut radius)
.range(0.25..=128.0)
.speed(0.1)
.prefix("R ")
.suffix(" m"),
)
.on_hover_text("Brush radius");
ui.add(
egui::DragValue::new(&mut strength)
.range(0.01..=1.0)
.speed(0.02)
.prefix("S "),
)
.on_hover_text("Weight strength per dab");
let mut state = world.resource_mut::<TerrainPaintState>();
state.mode = mode;
state.active_layer = active_layer;
state.radius = radius;
state.strength = strength;
state.clamp_settings();
}
}
let clean_game_view = world.resource::<ViewportDisplayMode>().clean_game_view;
if tool_button(
ui,
@@ -649,6 +932,13 @@ fn scene_view_overlay_toolbar(world: &mut World, ctx: &egui::Context, scene_rect
});
});
let toolbar_clicked = toolbar_response.response.contains_pointer()
&& ctx.input(|input| input.pointer.button_clicked(egui::PointerButton::Primary));
if toolbar_clicked {
world.resource_mut::<ViewportClick>().0 = None;
}
world.resource_mut::<ViewportUiState>().toolbar_rect = Some(toolbar_response.response.rect);
if options_open {
scene_options_popover(world, ctx, scene_rect, &mut options_open);
}
@@ -631,6 +631,10 @@ fn icon_for_actor_components(components: ActorIconComponents) -> ActorIconSpec {
image: ActorIconImage::Mesh,
category: ActorIconCategory::Mesh,
},
ActorKind::Terrain => ActorIconSpec {
image: ActorIconImage::Mesh,
category: ActorIconCategory::Mesh,
},
ActorKind::StaticMesh => {
if components.has_primitive || components.has_static_mesh_renderer {
ActorIconSpec {
+4
View File
@@ -12,6 +12,8 @@ pub mod render_view;
pub mod rendering_diagnostics;
pub mod selection;
pub mod selection_outline;
pub mod terrain_paint;
pub mod terrain_sculpt;
pub mod viewport_mode;
pub mod visualizers;
@@ -24,4 +26,6 @@ pub use brush_edit::{BrushEditMode, BrushEditPlugin, BrushElementSelection};
pub use brush_tool::{BrushToolPlugin, BrushToolState};
pub use material_drop::{MaterialDropFeedback, MaterialDropPlugin, MaterialDropState};
pub use panel::*;
pub use terrain_paint::{TerrainPaintMode, TerrainPaintPlugin, TerrainPaintState};
pub use terrain_sculpt::{TerrainSculptMode, TerrainSculptPlugin, TerrainSculptState};
pub use viewport_mode::EditorViewportMode;
+85 -1
View File
@@ -14,6 +14,7 @@ use crate::ui::helpers::ensure_player_spawn_for_edit;
use crate::ui::hierarchy_ops::is_entity_locked;
use crate::ui::hierarchy_state::HierarchyPanelState;
use crate::ui::UiState;
use crate::ui::ViewportUiState;
use crate::viewport::actor_icons::ActorIconProxy;
use crate::viewport::brush_edit::{BrushEditMode, BrushElementGizmo};
use crate::viewport::brush_tool::BrushToolState;
@@ -23,6 +24,8 @@ use bevy_egui::egui;
use crate::viewport::material_drop::{MaterialDropSet, MaterialDropState};
use crate::viewport::scene_view_ray;
use crate::viewport::terrain_paint::TerrainPaintState;
use crate::viewport::terrain_sculpt::TerrainSculptState;
#[derive(Resource, Default, Debug, Clone, Copy)]
pub struct SelectedEntity(pub Option<Entity>);
@@ -49,6 +52,9 @@ struct PickTargetQueries<'w, 's> {
parents: Query<'w, 's, &'static ChildOf>,
editor_only: Query<'w, 's, (), With<EditorOnly>>,
material_drop: Option<Res<'w, MaterialDropState>>,
terrain_sculpt: Res<'w, TerrainSculptState>,
terrain_paint: Res<'w, TerrainPaintState>,
viewport_ui: Res<'w, ViewportUiState>,
}
impl Plugin for EditorSelectionPlugin {
@@ -113,6 +119,21 @@ fn handle_pick_events(
gizmo_targets: Query<&GizmoTarget>,
hierarchy: Option<Res<HierarchyPanelState>>,
) -> Result {
if ui_state.viewport_pointer_pos.is_some_and(|pointer| {
pick_targets
.viewport_ui
.toolbar_rect
.is_some_and(|rect| rect.contains(pointer))
}) {
viewport_click.0 = None;
for _ in click_events.read() {}
return Ok(());
}
if pick_targets.terrain_sculpt.active || pick_targets.terrain_paint.active {
viewport_click.0 = None;
for _ in click_events.read() {}
return Ok(());
}
if pick_targets
.material_drop
.as_deref()
@@ -220,6 +241,10 @@ fn handle_pick_events(
Ok(())
}
#[expect(
clippy::too_many_arguments,
reason = "selection cycling reads independent viewport input ownership resources"
)]
fn cycle_overlapping_viewport_pick(
mut ui_state: ResMut<UiState>,
mut selected: ResMut<SelectedEntity>,
@@ -228,7 +253,12 @@ fn cycle_overlapping_viewport_pick(
buttons: Res<ButtonInput<MouseButton>>,
display: Res<ViewportDisplayMode>,
material_drop: Option<Res<MaterialDropState>>,
terrain_sculpt: Res<TerrainSculptState>,
terrain_paint: Res<TerrainPaintState>,
) -> Result {
if terrain_sculpt.active || terrain_paint.active {
return Ok(());
}
if material_drop
.as_deref()
.is_some_and(MaterialDropState::captures_viewport_input)
@@ -415,13 +445,19 @@ fn sync_gizmo_targets(
hierarchy: Option<Res<HierarchyPanelState>>,
display: Res<ViewportDisplayMode>,
brush_mode: Res<BrushEditMode>,
terrain_sculpt: Res<TerrainSculptState>,
terrain_paint: Res<TerrainPaintState>,
) {
ui_state
.selected_entities
.retain(|entity| transforms.contains(entity) && !editor_only.contains(entity));
selected.0 = ui_state.selected_entities.as_slice().first().copied();
if display.clean_game_view || brush_mode.is_element_mode() {
if display.clean_game_view
|| brush_mode.is_element_mode()
|| terrain_sculpt.active
|| terrain_paint.active
{
for (entity, brush_element_gizmo) in &targets {
if brush_element_gizmo.is_none() {
commands.entity(entity).remove::<GizmoTarget>();
@@ -474,6 +510,8 @@ mod tests {
.init_resource::<SelectedEntity>()
.init_resource::<ViewportDisplayMode>()
.init_resource::<BrushEditMode>()
.init_resource::<TerrainSculptState>()
.init_resource::<TerrainPaintState>()
.add_systems(Update, sync_gizmo_targets);
app.update();
@@ -488,4 +526,50 @@ mod tests {
assert!(app.world().get::<GizmoTarget>(first).is_some());
assert!(app.world().get::<GizmoTarget>(second).is_none());
}
#[test]
fn terrain_sculpt_owns_pointer_without_transform_gizmo() {
let mut app = App::new();
let terrain = app
.world_mut()
.spawn((LevelObject, Transform::default(), GizmoTarget::default()))
.id();
let mut ui_state = UiState::default_layout();
ui_state.selected_entities.select_replace(terrain);
let mut sculpt = TerrainSculptState::default();
sculpt.start(terrain);
app.insert_resource(ui_state)
.insert_resource(sculpt)
.init_resource::<SelectedEntity>()
.init_resource::<ViewportDisplayMode>()
.init_resource::<BrushEditMode>()
.init_resource::<TerrainPaintState>()
.add_systems(Update, sync_gizmo_targets);
app.update();
assert!(app.world().get::<GizmoTarget>(terrain).is_none());
}
#[test]
fn terrain_paint_owns_pointer_without_transform_gizmo() {
let mut app = App::new();
let terrain = app
.world_mut()
.spawn((LevelObject, Transform::default(), GizmoTarget::default()))
.id();
let mut ui_state = UiState::default_layout();
ui_state.selected_entities.select_replace(terrain);
let mut paint = TerrainPaintState::default();
paint.start(terrain, 2);
app.insert_resource(ui_state)
.insert_resource(paint)
.init_resource::<SelectedEntity>()
.init_resource::<ViewportDisplayMode>()
.init_resource::<BrushEditMode>()
.init_resource::<TerrainSculptState>()
.add_systems(Update, sync_gizmo_targets);
app.update();
assert!(app.world().get::<GizmoTarget>(terrain).is_none());
}
}
+531
View File
@@ -0,0 +1,531 @@
//! Modal terrain material-weight painting with exact cancel and grouped history.
use bevy::prelude::*;
use bevy_egui::EguiContexts;
use shared::{TerrainDesc, AUTHORING_COMPONENT_TERRAIN, COMPONENT_TERRAIN_DESC};
use super::terrain_sculpt::{active_scene_ray, smooth_falloff, terrain_ray_hit, TerrainHit};
use crate::camera::EditorCamera;
use crate::history::reflected_component_transaction;
use crate::operators::{ActiveOperator, OperatorPhase, OperatorStatus};
use crate::scene_io::SceneIo;
use crate::selection::{SelectedEntity, ViewportClick};
use crate::state::scene_tools_active;
use crate::ui::UiState;
use crate::viewport::ViewportDisplayMode;
const MIN_RADIUS: f32 = 0.25;
const MAX_RADIUS: f32 = 128.0;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TerrainPaintMode {
#[default]
Paint,
Erase,
}
impl TerrainPaintMode {
pub fn label(self) -> &'static str {
match self {
Self::Paint => "Paint",
Self::Erase => "Erase",
}
}
}
#[derive(Debug, Clone)]
struct TerrainPaintStroke {
entity: Entity,
original: TerrainDesc,
last_local: Vec3,
}
#[derive(Resource, Debug, Clone)]
pub struct TerrainPaintState {
pub active: bool,
pub mode: TerrainPaintMode,
pub active_layer: usize,
pub radius: f32,
pub strength: f32,
hover: Option<TerrainHit>,
stroke: Option<TerrainPaintStroke>,
target: Option<Entity>,
}
impl Default for TerrainPaintState {
fn default() -> Self {
Self {
active: false,
mode: TerrainPaintMode::Paint,
active_layer: 1,
radius: 4.0,
strength: 0.35,
hover: None,
stroke: None,
target: None,
}
}
}
impl TerrainPaintState {
pub fn start(&mut self, target: Entity, layer_count: usize) {
self.active = true;
self.target = Some(target);
self.active_layer = self.active_layer.min(layer_count.saturating_sub(1));
}
pub fn stop(&mut self) {
self.active = false;
self.hover = None;
self.target = None;
}
pub fn is_stroking(&self) -> bool {
self.stroke.is_some()
}
pub fn clamp_settings(&mut self) {
self.radius = self.radius.clamp(MIN_RADIUS, MAX_RADIUS);
self.strength = self.strength.clamp(0.01, 1.0);
}
}
pub struct TerrainPaintPlugin;
impl Plugin for TerrainPaintPlugin {
fn build(&self, app: &mut App) {
app.init_resource::<TerrainPaintState>().add_systems(
Update,
(terrain_paint_input, draw_terrain_paint_preview)
.chain()
.run_if(scene_tools_active),
);
}
}
#[allow(clippy::too_many_arguments)]
fn terrain_paint_input(
mut commands: Commands,
mut state: ResMut<TerrainPaintState>,
mut selected: ResMut<SelectedEntity>,
keys: Res<ButtonInput<KeyCode>>,
buttons: Res<ButtonInput<MouseButton>>,
mut contexts: EguiContexts,
ui_state: Res<UiState>,
display: Res<ViewportDisplayMode>,
cameras: Query<(&Camera, &GlobalTransform), With<EditorCamera>>,
mut terrains: Query<(&GlobalTransform, &mut TerrainDesc)>,
mut viewport_click: ResMut<ViewportClick>,
mut scene_io: ResMut<SceneIo>,
mut active_operator: ResMut<ActiveOperator>,
) -> Result {
if !state.active {
return Ok(());
}
viewport_click.0 = None;
state.clamp_settings();
let Some(entity) = state.target.or(selected.0) else {
cancel_stroke(&mut state, &mut terrains);
state.stop();
return Ok(());
};
if selected.0 != Some(entity) {
selected.0 = Some(entity);
}
if display.clean_game_view {
cancel_stroke(&mut state, &mut terrains);
state.stop();
return Ok(());
}
let ctx = contexts.ctx_mut()?;
let cancel_requested =
keys.just_pressed(KeyCode::Escape) || buttons.just_pressed(MouseButton::Right);
if cancel_requested {
if state.is_stroking() {
cancel_stroke(&mut state, &mut terrains);
scene_io.status = "Terrain paint stroke canceled".into();
set_status(
&mut active_operator,
OperatorPhase::Canceled,
"Weights restored",
);
} else {
state.stop();
scene_io.status = "Terrain paint tool closed".into();
set_status(&mut active_operator, OperatorPhase::Canceled, "Tool closed");
}
return Ok(());
}
let Ok((global, mut terrain)) = terrains.get_mut(entity) else {
state.stroke = None;
state.stop();
return Ok(());
};
let layer_count = terrain.material_layers.len();
if layer_count == 0 {
state.stop();
scene_io.status = "Add a terrain material layer before painting".into();
return Ok(());
}
state.active_layer = state.active_layer.min(layer_count - 1);
state.hover = ui_state
.viewport_pointer_pos
.and_then(|pointer| active_scene_ray(&cameras, pointer, ui_state.viewport_rect))
.and_then(|ray| terrain_ray_hit(entity, &terrain, global, ray));
if buttons.just_pressed(MouseButton::Left) && !ctx.egui_wants_pointer_input() {
if let Some(hit) = state.hover.filter(|hit| hit.entity == entity) {
let original = terrain.clone();
terrain.ensure_material_weights();
apply_weight_dab(
&mut terrain,
hit.local,
state.radius,
state.strength,
state.active_layer,
state.mode,
);
state.stroke = Some(TerrainPaintStroke {
entity,
original,
last_local: hit.local,
});
set_status(
&mut active_operator,
OperatorPhase::Preview,
format!(
"{} layer {} in progress",
state.mode.label(),
state.active_layer + 1
),
);
}
} else if buttons.pressed(MouseButton::Left) {
let radius = state.radius;
let strength = state.strength;
let layer = state.active_layer;
let mode = state.mode;
if let (Some(hit), Some(stroke)) = (state.hover, state.stroke.as_mut()) {
if hit.entity == stroke.entity {
let step = (radius * 0.2).max(terrain.sample_spacing * 0.25);
let delta = hit.local - stroke.last_local;
let distance = Vec2::new(delta.x, delta.z).length();
if distance >= step {
let count = (distance / step).floor() as usize;
for index in 1..=count {
let point = stroke.last_local + delta * (index as f32 / count as f32);
apply_weight_dab(&mut terrain, point, radius, strength, layer, mode);
}
stroke.last_local = hit.local;
}
}
}
}
if buttons.just_released(MouseButton::Left) {
if let Some(stroke) = state.stroke.take() {
let final_terrain = terrain.clone();
let mode = state.mode;
commands.queue(move |world: &mut World| {
if let Err(error) = commit_paint_stroke(world, stroke, final_terrain) {
world.resource_mut::<SceneIo>().status =
format!("Terrain paint commit failed: {error}");
}
});
scene_io.status = format!("{} terrain material weights committed", mode.label());
set_status(
&mut active_operator,
OperatorPhase::Committed,
format!("{} weights; Ctrl+Z to undo", mode.label()),
);
}
}
Ok(())
}
fn commit_paint_stroke(
world: &mut World,
stroke: TerrainPaintStroke,
final_terrain: TerrainDesc,
) -> Result<(), String> {
if let Ok(mut actor) = world.get_entity_mut(stroke.entity) {
actor.insert(stroke.original);
}
reflected_component_transaction(
world,
stroke.entity,
"Paint Terrain Material",
AUTHORING_COMPONENT_TERRAIN,
COMPONENT_TERRAIN_DESC,
move |world, entity| {
world.entity_mut(entity).insert(final_terrain);
Ok(())
},
)
}
fn cancel_stroke(
state: &mut TerrainPaintState,
terrains: &mut Query<(&GlobalTransform, &mut TerrainDesc)>,
) {
let Some(stroke) = state.stroke.take() else {
return;
};
if let Ok((_, mut terrain)) = terrains.get_mut(stroke.entity) {
*terrain = stroke.original;
}
}
fn set_status(active: &mut ActiveOperator, phase: OperatorPhase, hint: impl Into<String>) {
active.status = Some(OperatorStatus {
id: "terrain.paint".into(),
label: "Terrain Paint".into(),
phase,
hint: hint.into(),
warnings: Vec::new(),
});
}
fn apply_weight_dab(
terrain: &mut TerrainDesc,
center: Vec3,
radius: f32,
strength: f32,
active_layer: usize,
mode: TerrainPaintMode,
) {
terrain.ensure_material_weights();
let layer_count = terrain.material_layers.len().clamp(1, 4);
if active_layer >= layer_count {
return;
}
let radius = radius.max(MIN_RADIUS);
let half_extent = (terrain.resolution - 1) as f32 * terrain.sample_spacing * 0.5;
for z in 0..terrain.resolution {
for x in 0..terrain.resolution {
let sample = Vec2::new(
x as f32 * terrain.sample_spacing - half_extent,
z as f32 * terrain.sample_spacing - half_extent,
);
let distance = sample.distance(Vec2::new(center.x, center.z));
if distance > radius {
continue;
}
let amount = strength.clamp(0.0, 1.0) * smooth_falloff(distance / radius);
let index = (z * terrain.resolution + x) as usize;
terrain.material_weights[index] = adjust_weights(
terrain.material_weights[index],
active_layer,
layer_count,
amount,
mode,
);
}
}
}
fn adjust_weights(
weights: [u8; 4],
active_layer: usize,
layer_count: usize,
amount: f32,
mode: TerrainPaintMode,
) -> [u8; 4] {
let mut values = weights.map(|value| f32::from(value) / 255.0);
for value in values.iter_mut().skip(layer_count) {
*value = 0.0;
}
let current = values[active_layer];
let target = match mode {
TerrainPaintMode::Paint => current + (1.0 - current) * amount,
TerrainPaintMode::Erase => current * (1.0 - amount),
};
let other_sum: f32 = values
.iter()
.take(layer_count)
.enumerate()
.filter(|(index, _)| *index != active_layer)
.map(|(_, value)| *value)
.sum();
if other_sum <= f32::EPSILON {
if layer_count == 1 {
values[active_layer] = 1.0;
} else {
values.fill(0.0);
values[active_layer] = target;
let fallback = if active_layer == 0 { 1 } else { 0 };
values[fallback] = 1.0 - target;
}
} else {
let scale = (1.0 - target) / other_sum;
for (index, value) in values.iter_mut().take(layer_count).enumerate() {
if index != active_layer {
*value *= scale;
}
}
values[active_layer] = target;
}
quantize_weights(values, layer_count)
}
fn quantize_weights(values: [f32; 4], layer_count: usize) -> [u8; 4] {
let mut result = [0_u8; 4];
let mut fractions = [(0_usize, 0.0_f32); 4];
let mut assigned = 0_u16;
for index in 0..layer_count {
let scaled = values[index].clamp(0.0, 1.0) * 255.0;
let floor = scaled.floor() as u8;
result[index] = floor;
assigned += u16::from(floor);
fractions[index] = (index, scaled - f32::from(floor));
}
fractions[..layer_count].sort_by(|a, b| b.1.total_cmp(&a.1));
for offset in 0..usize::from(255_u16 - assigned) {
result[fractions[offset % layer_count].0] += 1;
}
result
}
fn draw_terrain_paint_preview(state: Res<TerrainPaintState>, mut gizmos: Gizmos) {
if !state.active {
return;
}
let Some(hit) = state.hover else {
return;
};
let color = match state.mode {
TerrainPaintMode::Paint => Color::srgba(0.22, 0.78, 1.0, 0.95),
TerrainPaintMode::Erase => Color::srgba(1.0, 0.64, 0.22, 0.95),
};
let rotation = hit.world_rotation * Quat::from_rotation_x(std::f32::consts::FRAC_PI_2);
gizmos
.circle(
Isometry3d::new(hit.world + Vec3::Y * 0.035, rotation),
state.radius,
color,
)
.resolution(48);
gizmos.sphere(
Isometry3d::from_translation(hit.world + Vec3::Y * 0.04),
0.06,
color,
);
}
#[cfg(test)]
mod tests {
use super::*;
use crate::history::{apply_command_redo, apply_command_undo, EditorHistory};
use shared::{ActorKind, LevelObject};
#[test]
fn paint_and_erase_keep_weights_exactly_normalized() {
let painted = adjust_weights([255, 0, 0, 0], 1, 2, 0.5, TerrainPaintMode::Paint);
assert_eq!(painted.iter().copied().map(u16::from).sum::<u16>(), 255);
assert!(painted[1] > 0);
let erased = adjust_weights(painted, 1, 2, 1.0, TerrainPaintMode::Erase);
assert_eq!(erased, [255, 0, 0, 0]);
}
#[test]
fn dab_only_changes_samples_inside_footprint() {
let mut terrain = TerrainDesc::flat(5);
terrain.material_layers = vec![Default::default(), Default::default()];
apply_weight_dab(
&mut terrain,
Vec3::ZERO,
1.1,
1.0,
1,
TerrainPaintMode::Paint,
);
assert!(terrain.material_weights[12][1] > 0);
assert_eq!(terrain.material_weights[0], [255, 0, 0, 0]);
assert!(terrain.validate().is_ok());
}
#[test]
fn many_dabs_commit_as_one_undoable_paint_stroke() {
let mut app = App::new();
app.register_type::<ActorKind>()
.register_type::<TerrainDesc>()
.register_type::<shared::TerrainMaterialLayer>()
.register_type::<shared::EditorAssetRef>();
let world = app.world_mut();
world.init_resource::<EditorHistory>();
world.init_resource::<SceneIo>();
let mut original = TerrainDesc::flat(9);
original.material_layers = vec![Default::default(), Default::default()];
let entity = world
.spawn((LevelObject, ActorKind::Terrain, original.clone()))
.id();
let mut final_terrain = original.clone();
for x in [-2.0, 0.0, 2.0] {
apply_weight_dab(
&mut final_terrain,
Vec3::new(x, 0.0, 0.0),
2.5,
0.5,
1,
TerrainPaintMode::Paint,
);
}
world.entity_mut(entity).insert(final_terrain.clone());
commit_paint_stroke(
world,
TerrainPaintStroke {
entity,
original: original.clone(),
last_local: Vec3::ZERO,
},
final_terrain.clone(),
)
.unwrap();
assert_eq!(world.resource::<EditorHistory>().undo_depth(), 1);
assert_eq!(world.get::<TerrainDesc>(entity), Some(&final_terrain));
apply_command_undo(world);
assert_eq!(world.get::<TerrainDesc>(entity), Some(&original));
apply_command_redo(world);
assert_eq!(world.get::<TerrainDesc>(entity), Some(&final_terrain));
}
#[test]
fn cancel_restores_implicit_pre_stroke_weights() {
fn cancel_once(
mut state: ResMut<TerrainPaintState>,
mut terrains: Query<(&GlobalTransform, &mut TerrainDesc)>,
) {
cancel_stroke(&mut state, &mut terrains);
}
let mut app = App::new();
let mut original = TerrainDesc::flat(5);
original.material_layers = vec![Default::default(), Default::default()];
let mut preview = original.clone();
apply_weight_dab(
&mut preview,
Vec3::ZERO,
3.0,
0.8,
1,
TerrainPaintMode::Paint,
);
let entity = app
.world_mut()
.spawn((GlobalTransform::default(), preview))
.id();
let mut state = TerrainPaintState::default();
state.start(entity, 2);
state.stroke = Some(TerrainPaintStroke {
entity,
original: original.clone(),
last_local: Vec3::ZERO,
});
app.insert_resource(state).add_systems(Update, cancel_once);
app.update();
assert_eq!(app.world().get::<TerrainDesc>(entity), Some(&original));
assert!(!app.world().resource::<TerrainPaintState>().is_stroking());
}
}
@@ -0,0 +1,741 @@
//! Modal terrain height sculpting with one history transaction per pointer stroke.
use bevy::prelude::*;
use bevy_egui::EguiContexts;
use shared::{TerrainDesc, AUTHORING_COMPONENT_TERRAIN, COMPONENT_TERRAIN_DESC};
use crate::camera::EditorCamera;
use crate::history::reflected_component_transaction;
use crate::operators::{ActiveOperator, OperatorPhase, OperatorStatus};
use crate::scene_io::SceneIo;
use crate::selection::{SelectedEntity, ViewportClick};
use crate::state::scene_tools_active;
use crate::ui::UiState;
use crate::viewport::{scene_view_ray, ViewportDisplayMode};
const MIN_RADIUS: f32 = 0.25;
const MAX_RADIUS: f32 = 128.0;
const MIN_STRENGTH: f32 = 0.01;
const MAX_STRENGTH: f32 = 20.0;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TerrainSculptMode {
#[default]
Raise,
Lower,
Flatten,
Smooth,
Noise,
}
impl TerrainSculptMode {
pub fn label(self) -> &'static str {
match self {
Self::Raise => "Raise",
Self::Lower => "Lower",
Self::Flatten => "Flatten",
Self::Smooth => "Smooth",
Self::Noise => "Noise",
}
}
}
#[derive(Debug, Clone, Copy)]
pub(super) struct TerrainHit {
pub(super) entity: Entity,
pub(super) local: Vec3,
pub(super) world: Vec3,
pub(super) world_rotation: Quat,
}
#[derive(Debug, Clone)]
struct TerrainStroke {
entity: Entity,
original: TerrainDesc,
last_local: Vec3,
flatten_height: f32,
seed: u32,
}
#[derive(Resource, Debug, Clone)]
pub struct TerrainSculptState {
pub active: bool,
pub mode: TerrainSculptMode,
pub radius: f32,
/// Approximate world-space height delta per dab.
pub strength: f32,
hover: Option<TerrainHit>,
stroke: Option<TerrainStroke>,
target: Option<Entity>,
next_seed: u32,
}
impl Default for TerrainSculptState {
fn default() -> Self {
Self {
active: false,
mode: TerrainSculptMode::Raise,
radius: 4.0,
strength: 0.35,
hover: None,
stroke: None,
target: None,
next_seed: 1,
}
}
}
impl TerrainSculptState {
pub fn start(&mut self, target: Entity) {
self.active = true;
self.target = Some(target);
}
pub fn stop(&mut self) {
self.active = false;
self.hover = None;
self.target = None;
}
pub fn is_stroking(&self) -> bool {
self.stroke.is_some()
}
pub fn clamp_settings(&mut self) {
self.radius = self.radius.clamp(MIN_RADIUS, MAX_RADIUS);
self.strength = self.strength.clamp(MIN_STRENGTH, MAX_STRENGTH);
}
}
pub struct TerrainSculptPlugin;
impl Plugin for TerrainSculptPlugin {
fn build(&self, app: &mut App) {
app.init_resource::<TerrainSculptState>().add_systems(
Update,
(terrain_sculpt_input, draw_terrain_sculpt_preview)
.chain()
.run_if(scene_tools_active),
);
}
}
#[allow(clippy::too_many_arguments)]
fn terrain_sculpt_input(
mut commands: Commands,
mut state: ResMut<TerrainSculptState>,
mut selected: ResMut<SelectedEntity>,
keys: Res<ButtonInput<KeyCode>>,
buttons: Res<ButtonInput<MouseButton>>,
mut contexts: EguiContexts,
ui_state: Res<UiState>,
display: Res<ViewportDisplayMode>,
cameras: Query<(&Camera, &GlobalTransform), With<EditorCamera>>,
mut terrains: Query<(&GlobalTransform, &mut TerrainDesc)>,
mut viewport_click: ResMut<ViewportClick>,
mut scene_io: ResMut<SceneIo>,
mut active_operator: ResMut<ActiveOperator>,
) -> Result {
if !state.active {
return Ok(());
}
viewport_click.0 = None;
state.clamp_settings();
let Some(entity) = state.target.or(selected.0) else {
cancel_stroke(&mut state, &mut terrains);
state.stop();
return Ok(());
};
if selected.0 != Some(entity) {
selected.0 = Some(entity);
}
if display.clean_game_view {
cancel_stroke(&mut state, &mut terrains);
state.stop();
return Ok(());
}
let ctx = contexts.ctx_mut()?;
let pointer_over_ui = ctx.egui_wants_pointer_input();
let cancel_requested =
keys.just_pressed(KeyCode::Escape) || buttons.just_pressed(MouseButton::Right);
if cancel_requested {
if state.is_stroking() {
cancel_stroke(&mut state, &mut terrains);
scene_io.status = "Terrain sculpt stroke canceled".to_string();
set_status(
&mut active_operator,
OperatorPhase::Canceled,
"Stroke canceled; terrain restored",
);
} else {
state.stop();
scene_io.status = "Terrain sculpt tool closed".to_string();
set_status(&mut active_operator, OperatorPhase::Canceled, "Tool closed");
}
return Ok(());
}
let Ok((global, mut terrain)) = terrains.get_mut(entity) else {
state.stroke = None;
state.stop();
return Ok(());
};
let hit = ui_state
.viewport_pointer_pos
.and_then(|pointer| active_scene_ray(&cameras, pointer, ui_state.viewport_rect))
.and_then(|ray| terrain_ray_hit(entity, &terrain, global, ray));
state.hover = hit;
if buttons.just_pressed(MouseButton::Left) && !pointer_over_ui {
if let Some(hit) = state.hover.filter(|hit| hit.entity == entity) {
let flatten_height =
sample_height_bilinear(&terrain, hit.local.x, hit.local.z).unwrap_or_default();
let seed = state.next_seed;
state.next_seed = state.next_seed.wrapping_add(1).max(1);
state.stroke = Some(TerrainStroke {
entity,
original: terrain.clone(),
last_local: hit.local,
flatten_height,
seed,
});
apply_dab(
&mut terrain,
hit.local,
state.radius,
state.strength,
state.mode,
flatten_height,
seed,
);
set_status(
&mut active_operator,
OperatorPhase::Preview,
format!("{} stroke in progress", state.mode.label()),
);
}
} else if buttons.pressed(MouseButton::Left) {
let radius = state.radius;
let strength = state.strength;
let mode = state.mode;
if let (Some(hit), Some(stroke)) = (state.hover, state.stroke.as_mut()) {
if hit.entity == stroke.entity {
let step = (radius * 0.2).max(terrain.sample_spacing * 0.25);
let delta = hit.local - stroke.last_local;
let distance = Vec2::new(delta.x, delta.z).length();
if distance >= step {
let count = (distance / step).floor() as usize;
for index in 1..=count {
let point = stroke.last_local + delta * (index as f32 / count as f32);
apply_dab(
&mut terrain,
point,
radius,
strength,
mode,
stroke.flatten_height,
stroke.seed,
);
}
stroke.last_local = hit.local;
}
}
}
}
if buttons.just_released(MouseButton::Left) {
if let Some(stroke) = state.stroke.take() {
let final_terrain = terrain.clone();
let label = sculpt_history_label(state.mode);
let mode_label = state.mode.label();
commands.queue(move |world: &mut World| {
let result = commit_terrain_stroke(world, stroke, final_terrain, label);
if let Err(error) = result {
world.resource_mut::<SceneIo>().status =
format!("Terrain sculpt commit failed: {error}");
}
});
scene_io.status = format!("{mode_label} terrain stroke committed");
set_status(
&mut active_operator,
OperatorPhase::Committed,
format!("{mode_label} stroke; Ctrl+Z to undo"),
);
}
}
Ok(())
}
fn commit_terrain_stroke(
world: &mut World,
stroke: TerrainStroke,
final_terrain: TerrainDesc,
label: &'static str,
) -> Result<(), String> {
if let Ok(mut actor) = world.get_entity_mut(stroke.entity) {
actor.insert(stroke.original);
}
reflected_component_transaction(
world,
stroke.entity,
label,
AUTHORING_COMPONENT_TERRAIN,
COMPONENT_TERRAIN_DESC,
move |world, entity| {
world.entity_mut(entity).insert(final_terrain);
Ok(())
},
)
}
fn cancel_stroke(
state: &mut TerrainSculptState,
terrains: &mut Query<(&GlobalTransform, &mut TerrainDesc)>,
) {
let Some(stroke) = state.stroke.take() else {
return;
};
if let Ok((_, mut terrain)) = terrains.get_mut(stroke.entity) {
*terrain = stroke.original;
}
}
fn set_status(active: &mut ActiveOperator, phase: OperatorPhase, hint: impl Into<String>) {
active.status = Some(OperatorStatus {
id: "terrain.sculpt".to_string(),
label: "Terrain Sculpt".to_string(),
phase,
hint: hint.into(),
warnings: Vec::new(),
});
}
fn sculpt_history_label(mode: TerrainSculptMode) -> &'static str {
match mode {
TerrainSculptMode::Raise => "Raise Terrain",
TerrainSculptMode::Lower => "Lower Terrain",
TerrainSculptMode::Flatten => "Flatten Terrain",
TerrainSculptMode::Smooth => "Smooth Terrain",
TerrainSculptMode::Noise => "Noise Terrain",
}
}
pub(super) fn active_scene_ray(
cameras: &Query<(&Camera, &GlobalTransform), With<EditorCamera>>,
pointer: bevy_egui::egui::Pos2,
scene_rect: bevy_egui::egui::Rect,
) -> Option<Ray3d> {
let (camera, transform) = cameras
.iter()
.find(|(camera, _)| camera.is_active)
.or_else(|| cameras.iter().next())?;
scene_view_ray(camera, transform, pointer, scene_rect)
}
pub(super) fn terrain_ray_hit(
entity: Entity,
terrain: &TerrainDesc,
global: &GlobalTransform,
ray: Ray3d,
) -> Option<TerrainHit> {
let world_from_local = global.affine();
let local_from_world = world_from_local.inverse();
let origin = local_from_world.transform_point3(ray.origin);
let direction = local_from_world.transform_vector3(ray.direction.as_vec3());
let local = ray_heightfield_intersection(terrain, origin, direction)?;
Some(TerrainHit {
entity,
local,
world: world_from_local.transform_point3(local),
world_rotation: global.rotation(),
})
}
fn ray_heightfield_intersection(
terrain: &TerrainDesc,
origin: Vec3,
direction: Vec3,
) -> Option<Vec3> {
if terrain.validate().is_err() || direction.length_squared() <= f32::EPSILON {
return None;
}
let horizontal_speed = Vec2::new(direction.x, direction.z).length();
if horizontal_speed <= 1.0e-6 {
if direction.y.abs() <= 1.0e-6 {
return None;
}
let height = sample_height_bilinear(terrain, origin.x, origin.z)?;
let t = (height - origin.y) / direction.y;
return (t >= 0.0).then_some(origin + direction * t);
}
let half_extent = (terrain.resolution - 1) as f32 * terrain.sample_spacing * 0.5;
let (mut start, mut end) = (0.0_f32, f32::INFINITY);
for (origin_axis, direction_axis) in [(origin.x, direction.x), (origin.z, direction.z)] {
if direction_axis.abs() <= 1.0e-6 {
if origin_axis < -half_extent || origin_axis > half_extent {
return None;
}
continue;
}
let a = (-half_extent - origin_axis) / direction_axis;
let b = (half_extent - origin_axis) / direction_axis;
start = start.max(a.min(b));
end = end.min(a.max(b));
}
if end < start || end < 0.0 {
return None;
}
start = start.max(0.0);
let span = (end - start).max(0.0);
let steps = ((span * horizontal_speed) / (terrain.sample_spacing * 0.4))
.ceil()
.clamp(1.0, 8192.0) as usize;
let surface_delta = |t: f32| {
let point = origin + direction * t;
sample_height_bilinear(terrain, point.x, point.z).map(|height| point.y - height)
};
let mut previous_t = start;
let mut previous = surface_delta(start)?;
if previous.abs() <= 1.0e-4 {
return Some(origin + direction * start);
}
for step in 1..=steps {
let t = start + span * (step as f32 / steps as f32);
let current = surface_delta(t)?;
if current.signum() != previous.signum() || current.abs() <= 1.0e-4 {
let (mut low, mut high) = (previous_t, t);
let low_sign = previous.signum();
for _ in 0..14 {
let middle = (low + high) * 0.5;
let delta = surface_delta(middle)?;
if delta.signum() == low_sign {
low = middle;
} else {
high = middle;
}
}
let hit_t = (low + high) * 0.5;
return Some(origin + direction * hit_t);
}
previous_t = t;
previous = current;
}
None
}
fn sample_height_bilinear(terrain: &TerrainDesc, local_x: f32, local_z: f32) -> Option<f32> {
let half_extent = (terrain.resolution - 1) as f32 * terrain.sample_spacing * 0.5;
let x = (local_x + half_extent) / terrain.sample_spacing;
let z = (local_z + half_extent) / terrain.sample_spacing;
let max = (terrain.resolution - 1) as f32;
if x < 0.0 || z < 0.0 || x > max || z > max {
return None;
}
let x0 = x.floor() as u32;
let z0 = z.floor() as u32;
let x1 = (x0 + 1).min(terrain.resolution - 1);
let z1 = (z0 + 1).min(terrain.resolution - 1);
let sample = |sx: u32, sz: u32| {
terrain.heights[(sz * terrain.resolution + sx) as usize] * terrain.height_scale
};
let top = sample(x0, z0).lerp(sample(x1, z0), x - x0 as f32);
let bottom = sample(x0, z1).lerp(sample(x1, z1), x - x0 as f32);
Some(top.lerp(bottom, z - z0 as f32))
}
fn apply_dab(
terrain: &mut TerrainDesc,
center: Vec3,
radius: f32,
strength: f32,
mode: TerrainSculptMode,
flatten_height: f32,
seed: u32,
) {
let radius = radius.max(MIN_RADIUS);
let resolution = terrain.resolution;
let half_extent = (resolution - 1) as f32 * terrain.sample_spacing * 0.5;
let source = terrain.heights.clone();
let normalized_strength = strength / terrain.height_scale.max(0.01);
for z in 0..resolution {
for x in 0..resolution {
let sample_position = Vec2::new(
x as f32 * terrain.sample_spacing - half_extent,
z as f32 * terrain.sample_spacing - half_extent,
);
let distance = sample_position.distance(Vec2::new(center.x, center.z));
if distance > radius {
continue;
}
let falloff = smooth_falloff(distance / radius);
let index = (z * resolution + x) as usize;
let current = source[index];
let next = match mode {
TerrainSculptMode::Raise => current + normalized_strength * falloff,
TerrainSculptMode::Lower => current - normalized_strength * falloff,
TerrainSculptMode::Flatten => {
let target = flatten_height / terrain.height_scale.max(0.01);
current.lerp(target, (normalized_strength * falloff).clamp(0.0, 1.0))
}
TerrainSculptMode::Smooth => {
let average = neighbor_average(&source, resolution, x, z);
current.lerp(average, (normalized_strength * falloff).clamp(0.0, 1.0))
}
TerrainSculptMode::Noise => {
current + signed_noise(x, z, seed) * normalized_strength * falloff
}
};
terrain.heights[index] = next;
}
}
}
pub(super) fn smooth_falloff(normalized_distance: f32) -> f32 {
let t = (1.0 - normalized_distance).clamp(0.0, 1.0);
t * t * (3.0 - 2.0 * t)
}
fn neighbor_average(heights: &[f32], resolution: u32, x: u32, z: u32) -> f32 {
let mut sum = 0.0;
let mut count = 0;
for dz in -1_i32..=1 {
for dx in -1_i32..=1 {
let sx = x as i32 + dx;
let sz = z as i32 + dz;
if sx >= 0 && sz >= 0 && sx < resolution as i32 && sz < resolution as i32 {
sum += heights[(sz as u32 * resolution + sx as u32) as usize];
count += 1;
}
}
}
sum / count as f32
}
fn signed_noise(x: u32, z: u32, seed: u32) -> f32 {
let mut value = x
.wrapping_mul(0x9e37_79b9)
.wrapping_add(z.wrapping_mul(0x85eb_ca6b))
.wrapping_add(seed.wrapping_mul(0xc2b2_ae35));
value ^= value >> 16;
value = value.wrapping_mul(0x7feb_352d);
value ^= value >> 15;
value = value.wrapping_mul(0x846c_a68b);
value ^= value >> 16;
(value as f32 / u32::MAX as f32) * 2.0 - 1.0
}
fn draw_terrain_sculpt_preview(state: Res<TerrainSculptState>, mut gizmos: Gizmos) {
if !state.active {
return;
}
let Some(hit) = state.hover else {
return;
};
let color = match state.mode {
TerrainSculptMode::Raise => Color::srgba(0.30, 0.92, 0.58, 0.95),
TerrainSculptMode::Lower => Color::srgba(0.96, 0.36, 0.32, 0.95),
TerrainSculptMode::Flatten => Color::srgba(0.32, 0.72, 1.0, 0.95),
TerrainSculptMode::Smooth => Color::srgba(0.72, 0.56, 1.0, 0.95),
TerrainSculptMode::Noise => Color::srgba(1.0, 0.76, 0.28, 0.95),
};
let rotation = hit.world_rotation * Quat::from_rotation_x(std::f32::consts::FRAC_PI_2);
gizmos
.circle(
Isometry3d::new(hit.world + Vec3::Y * 0.03, rotation),
state.radius,
color,
)
.resolution(48);
gizmos.sphere(
Isometry3d::from_translation(hit.world + Vec3::Y * 0.035),
0.06,
color,
);
}
#[cfg(test)]
mod tests {
use super::*;
use crate::history::{apply_command_redo, apply_command_undo, EditorHistory};
use shared::{ActorKind, LevelObject};
fn sample(terrain: &TerrainDesc, x: u32, z: u32) -> f32 {
terrain.heights[(z * terrain.resolution + x) as usize]
}
#[test]
fn vertical_ray_hits_heightfield_surface() {
let mut terrain = TerrainDesc::flat(3);
terrain.height_scale = 2.0;
terrain.heights[4] = 1.0;
let hit = ray_heightfield_intersection(&terrain, Vec3::new(0.0, 5.0, 0.0), Vec3::NEG_Y)
.expect("ray should hit center sample");
assert!((hit.y - 2.0).abs() < 0.001);
}
#[test]
fn raise_and_lower_only_touch_brush_footprint() {
let mut terrain = TerrainDesc::flat(5);
apply_dab(
&mut terrain,
Vec3::ZERO,
1.1,
1.0,
TerrainSculptMode::Raise,
0.0,
1,
);
assert!(sample(&terrain, 2, 2) > 0.0);
assert_eq!(sample(&terrain, 0, 0), 0.0);
let raised = sample(&terrain, 2, 2);
apply_dab(
&mut terrain,
Vec3::ZERO,
1.1,
1.0,
TerrainSculptMode::Lower,
0.0,
1,
);
assert!(sample(&terrain, 2, 2) < raised);
}
#[test]
fn flatten_and_smooth_converge_toward_targets() {
let mut terrain = TerrainDesc::flat(3);
terrain.height_scale = 1.0;
terrain.heights[4] = 4.0;
apply_dab(
&mut terrain,
Vec3::ZERO,
2.0,
1.0,
TerrainSculptMode::Smooth,
0.0,
2,
);
assert!(sample(&terrain, 1, 1) < 4.0);
apply_dab(
&mut terrain,
Vec3::ZERO,
2.0,
0.5,
TerrainSculptMode::Flatten,
2.0,
2,
);
assert!(sample(&terrain, 1, 1) > 0.0);
}
#[test]
fn noise_is_deterministic_for_stroke_seed() {
let mut first = TerrainDesc::flat(5);
let mut second = first.clone();
for terrain in [&mut first, &mut second] {
apply_dab(
terrain,
Vec3::ZERO,
3.0,
0.4,
TerrainSculptMode::Noise,
0.0,
42,
);
}
assert_eq!(first.heights, second.heights);
assert!(first.heights.iter().any(|height| *height != 0.0));
}
#[test]
fn many_dabs_commit_as_one_undoable_stroke() {
let mut app = App::new();
app.register_type::<ActorKind>()
.register_type::<TerrainDesc>();
let world = app.world_mut();
world.init_resource::<EditorHistory>();
world.init_resource::<SceneIo>();
let original = TerrainDesc::flat(9);
let entity = world
.spawn((LevelObject, ActorKind::Terrain, original.clone()))
.id();
let mut final_terrain = original.clone();
for x in [-2.0, 0.0, 2.0] {
apply_dab(
&mut final_terrain,
Vec3::new(x, 0.0, 0.0),
2.5,
0.4,
TerrainSculptMode::Raise,
0.0,
7,
);
}
world.entity_mut(entity).insert(final_terrain.clone());
commit_terrain_stroke(
world,
TerrainStroke {
entity,
original: original.clone(),
last_local: Vec3::ZERO,
flatten_height: 0.0,
seed: 7,
},
final_terrain.clone(),
"Raise Terrain",
)
.unwrap();
assert_eq!(world.resource::<EditorHistory>().undo_depth(), 1);
assert_eq!(world.get::<TerrainDesc>(entity), Some(&final_terrain));
apply_command_undo(world);
assert_eq!(world.get::<TerrainDesc>(entity), Some(&original));
apply_command_redo(world);
assert_eq!(world.get::<TerrainDesc>(entity), Some(&final_terrain));
}
#[test]
fn cancel_restores_exact_pre_stroke_descriptor() {
fn cancel_once(
mut state: ResMut<TerrainSculptState>,
mut terrains: Query<(&GlobalTransform, &mut TerrainDesc)>,
) {
cancel_stroke(&mut state, &mut terrains);
}
let mut app = App::new();
let original = TerrainDesc::flat(5);
let mut preview = original.clone();
apply_dab(
&mut preview,
Vec3::ZERO,
3.0,
0.8,
TerrainSculptMode::Raise,
0.0,
11,
);
let entity = app
.world_mut()
.spawn((GlobalTransform::default(), preview))
.id();
let mut state = TerrainSculptState::default();
state.start(entity);
state.stroke = Some(TerrainStroke {
entity,
original: original.clone(),
last_local: Vec3::ZERO,
flatten_height: 0.0,
seed: 11,
});
app.insert_resource(state).add_systems(Update, cancel_once);
app.update();
assert_eq!(app.world().get::<TerrainDesc>(entity), Some(&original));
assert!(!app.world().resource::<TerrainSculptState>().is_stroking());
}
}
+1
View File
@@ -175,6 +175,7 @@ fn actor_kind_ron(kind: ActorKind) -> &'static str {
match kind {
ActorKind::Empty => "Empty",
ActorKind::Brush => "Brush",
ActorKind::Terrain => "Terrain",
ActorKind::StaticMesh => "StaticMesh",
ActorKind::SkinnedMesh => "SkinnedMesh",
ActorKind::ImportedModel => "ImportedModel",
+18 -1
View File
@@ -11,7 +11,7 @@ use crate::{
ActorKind, AnimationControllerDesc, AudioListenerDesc, AudioSourceDesc, BrushDesc, LevelObject,
LightDesc, ModelRef, NavigationArea, NavigationBounds, NavigationLink, NavigationObstacle,
ObjectiveMarker, PlayerSpawn, PostProcessVolumeDesc, PrefabInstance, PrefabRef, Primitive,
SkinnedMeshRenderer, StaticMeshRenderer, TeamSpawn, TriggerVolume, WeaponSpawn,
SkinnedMeshRenderer, StaticMeshRenderer, TeamSpawn, TerrainDesc, TriggerVolume, WeaponSpawn,
AUDIO_CLIP_SUB_ASSET_ID,
};
@@ -31,6 +31,9 @@ pub fn infer_actor_kind(entity: EntityRef<'_>) -> Option<ActorKind> {
if entity.get::<BrushDesc>().is_some() {
return Some(ActorKind::Brush);
}
if entity.get::<TerrainDesc>().is_some() {
return Some(ActorKind::Terrain);
}
if entity.get::<Primitive>().is_some() || entity.get::<StaticMeshRenderer>().is_some() {
return Some(ActorKind::StaticMesh);
}
@@ -84,6 +87,7 @@ pub enum ActorValidationError {
BrushHasLight,
BrushHasModelRef,
InvalidBrushGeometry(String),
InvalidTerrain(String),
StaticMeshMissingPrimitive,
StaticMeshHasLight,
StaticMeshHasModelRef,
@@ -166,6 +170,7 @@ pub fn validate_actor(entity: EntityRef<'_>) -> Result<(), ActorValidationError>
}
let geometry_source_count = usize::from(entity.get::<Primitive>().is_some())
+ usize::from(entity.get::<BrushDesc>().is_some())
+ usize::from(entity.get::<TerrainDesc>().is_some())
+ usize::from(entity.get::<StaticMeshRenderer>().is_some())
+ usize::from(entity.get::<SkinnedMeshRenderer>().is_some())
+ usize::from(entity.get::<ModelRef>().is_some());
@@ -186,6 +191,11 @@ pub fn validate_actor(entity: EntityRef<'_>) -> Result<(), ActorValidationError>
return Err(ActorValidationError::InvalidBrushGeometry(message));
}
}
if let Some(terrain) = entity.get::<TerrainDesc>() {
terrain
.validate()
.map_err(ActorValidationError::InvalidTerrain)?;
}
if let Some(renderer) = entity.get::<SkinnedMeshRenderer>() {
if renderer.path.trim().is_empty() {
return Err(ActorValidationError::SkinnedMeshInvalidRenderer);
@@ -218,6 +228,13 @@ pub fn validate_actor(entity: EntityRef<'_>) -> Result<(), ActorValidationError>
}
let _ = brush;
}
ActorKind::Terrain => {
if entity.get::<TerrainDesc>().is_none() {
return Err(ActorValidationError::InvalidTerrain(
"terrain actor is missing TerrainDesc".into(),
));
}
}
ActorKind::StaticMesh => {
let has_static_mesh_renderer = entity
.get::<StaticMeshRenderer>()
+226
View File
@@ -290,6 +290,7 @@ pub fn inspector_component_active(order: Option<&InspectorOrder>, type_name: &st
// 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_TERRAIN: &str = "render.terrain";
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";
@@ -318,6 +319,7 @@ 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_TERRAIN | COMPONENT_TERRAIN_DESC => Some(AUTHORING_COMPONENT_TERRAIN),
AUTHORING_COMPONENT_STATIC_MESH_RENDERER | COMPONENT_STATIC_MESH_RENDERER => {
Some(AUTHORING_COMPONENT_STATIC_MESH_RENDERER)
}
@@ -386,6 +388,7 @@ pub fn authoring_component_key(key: &str) -> &str {
pub const COMPONENT_PRIMITIVE: &str = "shared::components::Primitive";
pub const COMPONENT_BRUSH_DESC: &str = "shared::components::BrushDesc";
pub const COMPONENT_TERRAIN_DESC: &str = "shared::components::TerrainDesc";
pub const COMPONENT_STATIC_MESH_RENDERER: &str = "shared::components::StaticMeshRenderer";
pub const COMPONENT_MATERIAL_DESC: &str = "shared::components::MaterialDesc";
pub const COMPONENT_MATERIAL_OVERRIDE: &str = "shared::components::MaterialOverride";
@@ -852,6 +855,228 @@ impl BrushDesc {
}
}
pub const TERRAIN_SCHEMA_VERSION: u32 = 1;
pub const TERRAIN_MATERIAL_LAYER_LIMIT: usize = 4;
fn default_terrain_layer_uv_scale() -> f32 {
8.0
}
/// One shared project material assigned to a terrain blend channel.
#[derive(Reflect, Debug, Clone, PartialEq, Serialize, Deserialize)]
#[reflect(Default, Debug, PartialEq, Serialize, Deserialize)]
pub struct TerrainMaterialLayer {
#[serde(default)]
pub material: Option<EditorAssetRef>,
#[serde(default = "default_terrain_layer_uv_scale")]
pub uv_scale: f32,
}
impl Default for TerrainMaterialLayer {
fn default() -> Self {
Self {
material: None,
uv_scale: default_terrain_layer_uv_scale(),
}
}
}
/// Persistent height-grid terrain authoring data. Hydration partitions the grid into generated
/// render/collider chunks; saved scenes retain only this descriptor.
#[derive(Component, Reflect, Debug, Clone, PartialEq, Serialize, Deserialize)]
#[reflect(Component, Default, Debug, PartialEq, Serialize, Deserialize)]
pub struct TerrainDesc {
#[serde(default = "default_terrain_schema_version")]
pub schema_version: u32,
#[serde(default = "default_terrain_resolution")]
pub resolution: u32,
#[serde(default = "default_terrain_heights")]
pub heights: Vec<f32>,
#[serde(default = "default_terrain_sample_spacing")]
pub sample_spacing: f32,
#[serde(default = "default_terrain_height_scale")]
pub height_scale: f32,
#[serde(default = "default_terrain_chunk_quads")]
pub chunk_quads: u32,
#[serde(default)]
pub base_material: Option<EditorAssetRef>,
/// Up to four project Material/Material Instance assignments. Empty retains the legacy
/// `base_material` path and an empty weight map means 100% channel zero.
#[serde(default)]
pub material_layers: Vec<TerrainMaterialLayer>,
/// RGBA8 weights per height sample. Channels correspond to `material_layers`.
#[serde(default)]
pub material_weights: Vec<[u8; TERRAIN_MATERIAL_LAYER_LIMIT]>,
#[serde(default = "default_true")]
pub generate_colliders: bool,
#[serde(default = "default_true")]
pub cast_shadows: bool,
#[serde(default = "default_true")]
pub receive_shadows: bool,
}
impl Default for TerrainDesc {
fn default() -> Self {
Self {
schema_version: TERRAIN_SCHEMA_VERSION,
resolution: default_terrain_resolution(),
heights: default_terrain_heights(),
sample_spacing: default_terrain_sample_spacing(),
height_scale: default_terrain_height_scale(),
chunk_quads: default_terrain_chunk_quads(),
base_material: None,
material_layers: Vec::new(),
material_weights: Vec::new(),
generate_colliders: true,
cast_shadows: true,
receive_shadows: true,
}
}
}
impl TerrainDesc {
pub fn flat(resolution: u32) -> Self {
let resolution = resolution.max(2);
Self {
resolution,
heights: vec![0.0; resolution as usize * resolution as usize],
chunk_quads: (resolution - 1).min(default_terrain_chunk_quads()),
..Default::default()
}
}
pub fn validate(&self) -> Result<(), String> {
if self.schema_version != TERRAIN_SCHEMA_VERSION {
return Err(format!(
"terrain schema {} is unsupported; expected {}",
self.schema_version, TERRAIN_SCHEMA_VERSION
));
}
if !(2..=1025).contains(&self.resolution) {
return Err("terrain resolution must be between 2 and 1025 samples".into());
}
let expected = self.resolution as usize * self.resolution as usize;
if self.heights.len() != expected {
return Err(format!(
"terrain resolution {} requires {expected} height samples, found {}",
self.resolution,
self.heights.len()
));
}
if self.heights.iter().any(|height| !height.is_finite()) {
return Err("terrain height samples must all be finite".into());
}
if self.material_layers.len() > TERRAIN_MATERIAL_LAYER_LIMIT {
return Err(format!(
"terrain supports at most {TERRAIN_MATERIAL_LAYER_LIMIT} material layers"
));
}
for (index, layer) in self.material_layers.iter().enumerate() {
if !layer.uv_scale.is_finite() || layer.uv_scale <= 0.0 {
return Err(format!(
"terrain material layer {} UV scale must be finite and positive",
index + 1
));
}
}
if !self.material_weights.is_empty() {
if self.material_weights.len() != expected {
return Err(format!(
"terrain resolution {} requires {expected} material weights, found {}",
self.resolution,
self.material_weights.len()
));
}
if self
.material_weights
.iter()
.any(|weights| weights.iter().copied().map(u16::from).sum::<u16>() != 255)
{
return Err("terrain material weights must sum to 255 at every sample".into());
}
let active_channels = self.material_layers.len().max(1);
if self.material_weights.iter().any(|weights| {
weights
.iter()
.skip(active_channels)
.any(|weight| *weight != 0)
}) {
return Err("terrain material weights use an unassigned layer channel".into());
}
}
if !self.sample_spacing.is_finite() || self.sample_spacing <= 0.0 {
return Err("terrain sample spacing must be finite and positive".into());
}
if !self.height_scale.is_finite() || self.height_scale <= 0.0 {
return Err("terrain height scale must be finite and positive".into());
}
if self.chunk_quads == 0 || self.chunk_quads > self.resolution - 1 {
return Err(format!(
"terrain chunk size must be between 1 and {} quads",
self.resolution - 1
));
}
Ok(())
}
/// Material channels used by hydration, including the legacy base-material fallback.
pub fn effective_material_layers(&self) -> Vec<TerrainMaterialLayer> {
if !self.material_layers.is_empty() {
return self.material_layers.clone();
}
self.base_material
.clone()
.map(|material| TerrainMaterialLayer {
material: Some(material),
..Default::default()
})
.into_iter()
.collect()
}
/// Material weights for one sample, normalized for vertex transport.
pub fn normalized_material_weights(&self, sample_index: usize) -> [f32; 4] {
let weights = self
.material_weights
.get(sample_index)
.copied()
.unwrap_or([255, 0, 0, 0]);
weights.map(|weight| f32::from(weight) / 255.0)
}
/// Materializes the implicit channel-zero map before an editor paint operation.
pub fn ensure_material_weights(&mut self) {
let expected = self.resolution as usize * self.resolution as usize;
if self.material_weights.len() != expected {
self.material_weights = vec![[255, 0, 0, 0]; expected];
}
}
}
fn default_terrain_schema_version() -> u32 {
TERRAIN_SCHEMA_VERSION
}
fn default_terrain_resolution() -> u32 {
33
}
fn default_terrain_heights() -> Vec<f32> {
vec![0.0; default_terrain_resolution() as usize * default_terrain_resolution() as usize]
}
fn default_terrain_sample_spacing() -> f32 {
1.0
}
fn default_terrain_height_scale() -> f32 {
10.0
}
fn default_terrain_chunk_quads() -> u32 {
16
}
impl Default for BrushDesc {
fn default() -> Self {
Self::cuboid(Vec3::ONE)
@@ -1392,6 +1617,7 @@ impl Default for EditorVisibility {
pub enum ActorKind {
Empty,
Brush,
Terrain,
StaticMesh,
SkinnedMesh,
ImportedModel,
+5
View File
@@ -10,6 +10,7 @@ mod primitives;
mod skinned_meshes;
mod static_meshes;
pub mod strip;
mod terrain;
mod visibility;
pub use lights::cascade_config_from_rendering;
@@ -37,6 +38,8 @@ use static_meshes::{
hydrate_static_mesh_renderers, spawn_static_mesh_parts, HydratedStaticMeshPart,
StaticMeshArtifactCache,
};
pub use terrain::HydratedTerrainChunk;
use terrain::{cleanup_removed_terrain, hydrate_terrain};
use visibility::{
ensure_level_object_visibility_hierarchy, init_editor_visibility_on_spawn,
sync_editor_visibility, visibility_from_editor,
@@ -73,6 +76,7 @@ impl Plugin for HydrationPlugin {
(
hydrate_primitives,
hydrate_brushes,
hydrate_terrain,
hydrate_materials,
hydrate_lights,
reconcile_missing_runtime_lights,
@@ -83,6 +87,7 @@ impl Plugin for HydrationPlugin {
hydrate_models,
hydrate_prefabs,
hydrate_physics,
cleanup_removed_terrain,
)
.chain()
.in_set(HydrationSet::Content),
+372
View File
@@ -0,0 +1,372 @@
//! Chunked render and collider hydration for authored height-grid terrain.
use avian3d::prelude::ColliderConstructor;
use bevy::asset::RenderAssetUsages;
use bevy::light::{NotShadowCaster, NotShadowReceiver};
use bevy::mesh::{Indices, PrimitiveTopology};
use bevy::prelude::*;
use crate::{
authoring_component_active, load_resolved_material_from_path, AuthoringComponentStates,
HydratedTerrainMaterialBinding, InspectorOrder, LevelObject, RaytracingExcluded, TerrainDesc,
COMPONENT_TERRAIN_DESC,
};
use super::materials::material_from_desc;
#[derive(Component, Reflect, Debug, Clone, Copy, PartialEq, Eq)]
#[reflect(Component, Default, Debug)]
pub struct HydratedTerrainChunk {
pub owner: Entity,
pub chunk_x: u32,
pub chunk_z: u32,
}
impl Default for HydratedTerrainChunk {
fn default() -> Self {
Self {
owner: Entity::PLACEHOLDER,
chunk_x: 0,
chunk_z: 0,
}
}
}
#[allow(clippy::type_complexity)]
pub fn hydrate_terrain(
mut commands: Commands,
asset_server: Res<AssetServer>,
mut meshes: ResMut<Assets<Mesh>>,
mut materials: ResMut<Assets<StandardMaterial>>,
terrains: Query<
(
Entity,
&TerrainDesc,
Option<&AuthoringComponentStates>,
Option<&InspectorOrder>,
),
(
With<LevelObject>,
Or<(
Added<TerrainDesc>,
Changed<TerrainDesc>,
Changed<AuthoringComponentStates>,
Changed<InspectorOrder>,
)>,
),
>,
children: Query<&Children>,
chunks: Query<(), With<HydratedTerrainChunk>>,
) {
for (entity, terrain, states, order) in &terrains {
despawn_terrain_chunks(&mut commands, entity, &children, &chunks);
if authoring_component_active(states, order, COMPONENT_TERRAIN_DESC) {
spawn_terrain_chunks(
&mut commands,
&asset_server,
&mut meshes,
&mut materials,
entity,
terrain,
);
}
}
}
pub fn cleanup_removed_terrain(
mut commands: Commands,
mut removed: RemovedComponents<TerrainDesc>,
children: Query<&Children>,
chunks: Query<(), With<HydratedTerrainChunk>>,
) {
for entity in removed.read() {
despawn_terrain_chunks(&mut commands, entity, &children, &chunks);
}
}
pub fn spawn_terrain_chunks(
commands: &mut Commands,
asset_server: &AssetServer,
meshes: &mut Assets<Mesh>,
materials: &mut Assets<StandardMaterial>,
owner: Entity,
terrain: &TerrainDesc,
) {
if let Err(error) = terrain.validate() {
warn!("Terrain hydration skipped invalid actor {owner:?}: {error}");
return;
}
let effective_layers = terrain.effective_material_layers();
let material = effective_layers
.first()
.and_then(|layer| layer.material.as_ref())
.and_then(|reference| reference.source_path.as_deref())
.and_then(|path| match load_resolved_material_from_path(path) {
Ok((desc, _)) => Some(material_from_desc(asset_server, &desc)),
Err(error) => {
warn!("Terrain {owner:?} material could not resolve: {error}");
None
}
})
.unwrap_or_else(|| StandardMaterial {
base_color: Color::srgb(0.24, 0.29, 0.25),
perceptual_roughness: 0.92,
..default()
});
let material = materials.add(material);
let quad_count = terrain.resolution - 1;
let chunks_per_axis = quad_count.div_ceil(terrain.chunk_quads);
for chunk_z in 0..chunks_per_axis {
for chunk_x in 0..chunks_per_axis {
let start_x = chunk_x * terrain.chunk_quads;
let start_z = chunk_z * terrain.chunk_quads;
let end_x = (start_x + terrain.chunk_quads).min(quad_count);
let end_z = (start_z + terrain.chunk_quads).min(quad_count);
let Some(mesh) = terrain_chunk_mesh(terrain, start_x, start_z, end_x, end_z) else {
continue;
};
let mesh = meshes.add(mesh);
let mut chunk = commands.spawn((
HydratedTerrainChunk {
owner,
chunk_x,
chunk_z,
},
Name::new(format!("Terrain Chunk {chunk_x},{chunk_z}")),
Mesh3d(mesh),
MeshMaterial3d(material.clone()),
HydratedTerrainMaterialBinding {
owner,
layers: terrain.effective_material_layers(),
},
Transform::default(),
Visibility::Visible,
RaytracingExcluded,
ChildOf(owner),
));
if terrain.generate_colliders {
chunk.insert(ColliderConstructor::TrimeshFromMesh);
}
if !terrain.cast_shadows {
chunk.insert(NotShadowCaster);
}
if !terrain.receive_shadows {
chunk.insert(NotShadowReceiver);
}
}
}
}
fn despawn_terrain_chunks(
commands: &mut Commands,
entity: Entity,
children: &Query<&Children>,
chunks: &Query<(), With<HydratedTerrainChunk>>,
) {
let Ok(children) = children.get(entity) else {
return;
};
for child in children.iter() {
if chunks.get(child).is_ok() {
commands.entity(child).despawn();
}
}
}
pub fn terrain_chunk_mesh(
terrain: &TerrainDesc,
start_x: u32,
start_z: u32,
end_x: u32,
end_z: u32,
) -> Option<Mesh> {
if start_x >= end_x
|| start_z >= end_z
|| end_x >= terrain.resolution
|| end_z >= terrain.resolution
{
return None;
}
let width = end_x - start_x + 1;
let depth = end_z - start_z + 1;
let mut positions = Vec::with_capacity((width * depth) as usize);
let mut normals = Vec::with_capacity((width * depth) as usize);
let mut uvs = Vec::with_capacity((width * depth) as usize);
let mut colors = Vec::with_capacity((width * depth) as usize);
let quad_count = (terrain.resolution - 1) as f32;
let half_extent = quad_count * terrain.sample_spacing * 0.5;
let sample = |x: u32, z: u32| {
terrain.heights[(z * terrain.resolution + x) as usize] * terrain.height_scale
};
for z in start_z..=end_z {
for x in start_x..=end_x {
let left = sample(x.saturating_sub(1), z);
let right = sample((x + 1).min(terrain.resolution - 1), z);
let down = sample(x, z.saturating_sub(1));
let up = sample(x, (z + 1).min(terrain.resolution - 1));
let normal = Vec3::new(left - right, 2.0 * terrain.sample_spacing, down - up)
.normalize_or_zero();
positions.push([
x as f32 * terrain.sample_spacing - half_extent,
sample(x, z),
z as f32 * terrain.sample_spacing - half_extent,
]);
normals.push(normal.to_array());
uvs.push([x as f32 / quad_count, z as f32 / quad_count]);
colors.push(terrain.normalized_material_weights((z * terrain.resolution + x) as usize));
}
}
let mut indices = Vec::with_capacity(((width - 1) * (depth - 1) * 6) as usize);
for z in 0..depth - 1 {
for x in 0..width - 1 {
let a = z * width + x;
let b = a + 1;
let c = a + width;
let d = c + 1;
indices.extend_from_slice(&[a, c, b, b, c, d]);
}
}
let mut mesh = Mesh::new(
PrimitiveTopology::TriangleList,
RenderAssetUsages::default(),
);
mesh.insert_attribute(Mesh::ATTRIBUTE_POSITION, positions);
mesh.insert_attribute(Mesh::ATTRIBUTE_NORMAL, normals);
mesh.insert_attribute(Mesh::ATTRIBUTE_UV_0, uvs);
mesh.insert_attribute(Mesh::ATTRIBUTE_COLOR, colors);
mesh.insert_indices(Indices::U32(indices));
if let Err(error) = mesh.generate_tangents() {
warn!("Terrain chunk tangent generation failed: {error:?}");
}
Some(mesh)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::ActorKind;
#[test]
fn chunk_mesh_has_expected_topology() {
let terrain = TerrainDesc::flat(5);
let mesh = terrain_chunk_mesh(&terrain, 0, 0, 4, 4).unwrap();
assert_eq!(mesh.count_vertices(), 25);
assert_eq!(mesh.indices().unwrap().len(), 96);
}
#[test]
fn descriptor_rejects_mismatched_and_non_finite_heights() {
let mut terrain = TerrainDesc::flat(3);
terrain.heights.pop();
assert!(terrain.validate().unwrap_err().contains("requires 9"));
terrain.heights.push(f32::NAN);
assert!(terrain.validate().unwrap_err().contains("finite"));
}
#[test]
fn descriptor_round_trips_through_ron() {
let mut terrain = TerrainDesc::flat(5);
terrain.heights[12] = 0.75;
terrain.sample_spacing = 2.0;
terrain.material_layers = vec![
crate::TerrainMaterialLayer {
material: Some(crate::EditorAssetRef::new(
"ground",
"material:source",
"Ground",
)),
uv_scale: 6.0,
},
crate::TerrainMaterialLayer {
material: Some(crate::EditorAssetRef::new(
"rock",
"material:source",
"Rock",
)),
uv_scale: 12.0,
},
];
terrain.ensure_material_weights();
terrain.material_weights[12] = [64, 191, 0, 0];
let text = ron::to_string(&terrain).unwrap();
let restored: TerrainDesc = ron::from_str(&text).unwrap();
assert_eq!(restored, terrain);
assert!(restored.validate().is_ok());
}
#[test]
fn chunk_mesh_transports_normalized_material_weights_as_vertex_colors() {
let mut terrain = TerrainDesc::flat(3);
terrain.ensure_material_weights();
terrain.material_weights[4] = [64, 191, 0, 0];
let mesh = terrain_chunk_mesh(&terrain, 0, 0, 2, 2).unwrap();
let Some(bevy::mesh::VertexAttributeValues::Float32x4(colors)) =
mesh.attribute(Mesh::ATTRIBUTE_COLOR)
else {
panic!("terrain chunks should carry RGBA layer weights");
};
assert_eq!(colors.len(), 9);
assert!((colors[4][0] - 64.0 / 255.0).abs() < 0.0001);
assert!((colors[4][1] - 191.0 / 255.0).abs() < 0.0001);
}
#[test]
fn descriptor_rejects_non_normalized_material_weights() {
let mut terrain = TerrainDesc::flat(3);
terrain.material_weights = vec![[128, 128, 0, 0]; 9];
assert!(terrain.validate().unwrap_err().contains("sum to 255"));
terrain.material_weights = vec![[127, 0, 128, 0]; 9];
assert!(terrain
.validate()
.unwrap_err()
.contains("unassigned layer channel"));
}
#[test]
fn hydration_generates_runtime_only_chunks_and_cleans_up() {
let mut app = App::new();
app.add_plugins((MinimalPlugins, AssetPlugin::default()))
.init_asset::<Mesh>()
.init_asset::<StandardMaterial>()
.add_systems(Update, (hydrate_terrain, cleanup_removed_terrain).chain());
let owner = app
.world_mut()
.spawn((
LevelObject,
ActorKind::Terrain,
TerrainDesc {
resolution: 5,
heights: vec![0.0; 25],
chunk_quads: 2,
..Default::default()
},
Transform::default(),
))
.id();
app.update();
app.update();
let children = app.world().get::<Children>(owner).unwrap();
assert_eq!(children.len(), 4);
for child in children.iter() {
assert!(app.world().get::<HydratedTerrainChunk>(child).is_some());
assert!(app.world().get::<LevelObject>(child).is_none());
assert!(app.world().get::<Mesh3d>(child).is_some());
assert!(app.world().get::<ColliderConstructor>(child).is_some());
}
app.world_mut().entity_mut(owner).remove::<TerrainDesc>();
app.update();
app.update();
assert!(app
.world()
.get::<Children>(owner)
.is_none_or(Children::is_empty));
}
}
+4 -1
View File
@@ -22,7 +22,8 @@ pub use components::*;
pub use hydration::{
cascade_config_from_rendering, flush_level_object_hydration, material_from_desc,
strip_hydrated, strip_hydrated_entity, HydratedModelRoot, HydratedPrefabMember,
HydratedPrefabReady, HydratedSkinnedMeshRoot, HydrationPlugin, PrefabHydrationBlocked,
HydratedPrefabReady, HydratedSkinnedMeshRoot, HydratedTerrainChunk, HydrationPlugin,
PrefabHydrationBlocked,
};
pub use material_asset::{
load_resolved_material_from_path, MaterialAlphaMode, MaterialAsset, MaterialInstanceAsset,
@@ -112,6 +113,8 @@ impl Plugin for SharedTypesPlugin {
.register_type::<Primitive>()
.register_type::<PrimitiveShape>()
.register_type::<BrushDesc>()
.register_type::<TerrainDesc>()
.register_type::<TerrainMaterialLayer>()
.register_type::<BrushKind>()
.register_type::<BrushPlaneDesc>()
.register_type::<BrushFaceDesc>()
+21 -1
View File
@@ -3,7 +3,10 @@
use bevy::prelude::*;
use serde::{Deserialize, Serialize};
use crate::{ComponentInstanceId, EditorAssetRef, MaterialParameter, MaterialTextureBinding};
use crate::{
ComponentInstanceId, EditorAssetRef, MaterialParameter, MaterialTextureBinding,
TerrainMaterialLayer,
};
/// A stable reference to a project material, material instance, or imported material subasset.
///
@@ -112,6 +115,23 @@ pub struct HydratedRendererMaterialBinding {
pub effective_material: Option<MaterialRef>,
}
/// Runtime ownership marker consumed by the project terrain-layer renderer.
#[derive(Component, Reflect, Debug, Clone, PartialEq)]
#[reflect(Component, Default, Debug, PartialEq)]
pub struct HydratedTerrainMaterialBinding {
pub owner: Entity,
pub layers: Vec<TerrainMaterialLayer>,
}
impl Default for HydratedTerrainMaterialBinding {
fn default() -> Self {
Self {
owner: Entity::PLACEHOLDER,
layers: Vec::new(),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
+7 -1
View File
@@ -53,13 +53,15 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
| [0036](adr/0036-surface-abi-and-solari-parity.md) | Constrained Surface ABI v1, raster/Solari evaluator parity, and deformed-geometry boundary |
| [0037](adr/0037-collaborative-authored-file-safety.md) | Exact authored-file revisions, observational Git status, and optional ownership providers |
| [0038](adr/0038-non-blocking-native-dialog-broker.md) | Worker-owned native waits with one-shot main-thread workflow completion |
| [0039](adr/0039-inline-height-grid-terrain-foundation.md) | Inline authored height grids with deterministic runtime-only chunk hydration |
| [0040](adr/0040-terrain-material-layer-weights.md) | Four-channel terrain material layers, compact normalized weights, and raster transport |
## Editor framework
| Document | Purpose |
|----------|---------|
| [editor/release-notes.md](editor/release-notes.md) | Editor framework 1.0 baseline |
| [editor/evaluations/](editor/evaluations/) | Horizon gate sign-offs (R1–R6) |
| [editor/evaluations/](editor/evaluations/) | Acceptance records, screenshots, and Gitea evidence-publishing policy |
| [editor/architecture.md](editor/architecture.md) | Viewport / PIE / settings data flow |
| [editor/visual-language.md](editor/visual-language.md) | Editor chrome, viewport, selection, gizmo, and visualizer language |
| [editor/roadmap.md](editor/roadmap.md) | Phased editor roadmap and status |
@@ -79,7 +81,10 @@ Immutable-style log of significant decisions. Add a new numbered ADR when changi
| [editor/material-system.md](editor/material-system.md) | Shared material assets and instances, renderer-slot assignment, Surface evaluators, migration, and diagnostics |
| [editor/collaborative-file-safety.md](editor/collaborative-file-safety.md) | Guarded authored writes, compact Git/read-only status, conflict recovery, and ownership providers |
| [editor/native-dialogs.md](editor/native-dialogs.md) | Non-blocking native dialog acquisition and main-thread result application |
| [editor/terrain.md](editor/terrain.md) | Terrain schema, inspector workflow, chunk hydration, collision, and follow-on boundaries |
| [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation |
| [editor/evaluations/terrain-sculpt-tools/](editor/evaluations/terrain-sculpt-tools/) | Live screenshot and acceptance results for modal terrain sculpt tools |
| [editor/evaluations/terrain-material-layers/](editor/evaluations/terrain-material-layers/) | Live screenshot and acceptance results for terrain material assignment, blending, painting, and history |
| [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity |
| [editor/evaluations/production-readiness/](editor/evaluations/production-readiness/) | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements |
@@ -103,6 +108,7 @@ Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans
| `source_control_collaboration_safety_*.plan.md` | Exact authored-file guards, observational Git status, conflict recovery, and provider contract |
| `production_readiness_acceptance_*.plan.md` | Release-candidate evidence matrix, blocker sequence, clean-checkout checks, soak, budgets, and independent sign-off |
| `material_library_and_targeted_drop_*.plan.md` | Dedicated Material Library, exact viewport slot/primitive/brush targeting, hover preview, cancel, and grouped history |
| `terrain_material_layers_*.plan.md` | Terrain shared-material layers, normalized weights, blended hydration, and modal painting |
## Crate responsibilities (quick reference)
@@ -0,0 +1,38 @@
# ADR 0039: Inline Height-Grid Terrain Foundation
## Status
Accepted
## Context
Terrain sculpting, material painting, physics placement, recovery, and prefab workflows need one
stable owner for height data. Generated meshes and colliders cannot be authoritative because they
are runtime artifacts, while introducing an external binary heightmap before editing semantics exist
would add file-move, revision, import, and multi-document transaction complexity prematurely.
## Decision
`TerrainDesc` schema v1 stores a bounded square grid of normalized finite `f32` heights directly in
the authored scene component. It also stores sample spacing, height scale, chunk quad size, an
optional shared base Material/Material Instance reference, collider generation, and shadow flags.
Hydration deterministically partitions grid quads into generated children. Boundary samples are
duplicated between neighboring render chunks so each chunk has complete normals and independent
triangle geometry. Chunk meshes/colliders are never `LevelObject` entities and are therefore absent
from saved scenes, recovery documents, prefabs, and history snapshots.
Resolution changes are explicit destructive flat-grid replacements in the foundation inspector.
Sculpt tools mutate the existing grid through grouped history transactions. A future external
heightmap representation requires an explicit schema migration and authored-file ownership ADR; it
must not silently rewrite an inline terrain during normal load.
## Consequences
- Scene, prefab, undo, recovery, collaboration, and validation use one exact terrain document.
- V1 grids are bounded to 1025×1025 samples to prevent accidental unbounded scene payloads.
- Large production terrains may eventually need tiled external storage and streaming.
- Foundation chunks remain raster-only in Solari until terrain layer materials have an exact Surface
evaluator in `#24`; explicit exclusion is preferred to a black or mismatched ray-traced proxy.
- Layer weights and sculpt strokes extend this descriptor contract in `#23`/`#24`; generated chunks
remain disposable regardless of the editing representation.
@@ -0,0 +1,36 @@
# ADR 0040: Terrain Material Layers And Weight Transport
## Status
Accepted
## Context
Terrain needs multiple shared project materials, editable weight painting, deterministic persistence,
and raster behavior that remains consistent between the editor and game. Duplicating full material
descriptors into scenes would break the shared Material/Material Instance contract. Storing floating
point weights would also create avoidable scene churn and normalization drift.
## Decision
`TerrainDesc` stores at most four `TerrainMaterialLayer` entries referencing shared assets and one
RGBA8 weight tuple per height sample. Every explicit tuple sums to 255; an absent weight array means
full channel-zero coverage for backward compatibility. Generated terrain chunks transport normalized
weights through `Mesh::ATTRIBUTE_COLOR`.
`shared` owns persistence, validation, chunk generation, and a runtime-only terrain material binding.
`blacksite_surface` owns the terrain-specific `ExtendedMaterial` and blends each resolved layer's
albedo, tangent-space normal, metallic, and roughness inputs. Invalid or unavailable references leave
the existing visible terrain fallback in place and emit diagnostics. Terrain remains excluded from
Solari geometry until a matching ray-tracing evaluator exists.
Editor paint strokes materialize the implicit default map only when needed. Each pointer stroke is a
single reflected `TerrainDesc` transaction; cancel restores the exact original descriptor.
## Consequences
- Four channels give fixed shader bindings, compact deterministic scenes, and simple normalization.
- Adding more than four simultaneous layers requires a deliberate schema and renderer revision.
- Weight resolution follows the height grid; independent high-resolution splat maps remain future work.
- Terrain raster rendering gains project-material texture parity while Solari terrain parity remains an
explicit later milestone rather than using a semantically different proxy.
+6
View File
@@ -25,10 +25,15 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
| [material-system.md](material-system.md) | Shared Material/Material Instance assets, static/skinned renderer slots, Surface ABI, Solari scope, and migration |
| [collaborative-file-safety.md](collaborative-file-safety.md) | Exact authored-file revisions, Git/read-only status, conflict recovery, and optional ownership providers |
| [native-dialogs.md](native-dialogs.md) | Non-blocking file/folder/confirmation acquisition and main-thread result application |
| [terrain.md](terrain.md) | Inline height-grid terrain, chunk hydration, collision, inspector workflow, and fixtures |
| [evaluations/](evaluations/) | Acceptance evidence records and native Gitea attachment publishing policy |
| [evaluations/material-renderer-foundation/](evaluations/material-renderer-foundation/) | Live screenshots and verification record for the renderer/material/component foundation |
| [evaluations/material-library-targeted-drop/](evaluations/material-library-targeted-drop/) | Live screenshot and verification record for the docked Material Library and exact reversible surface drops |
| [evaluations/collaborative-file-safety/](evaluations/collaborative-file-safety/) | Live screenshot and verification record for source-control status and guarded external-change recovery |
| [evaluations/native-dialog-responsiveness/](evaluations/native-dialog-responsiveness/) | Live native-Wayland screenshot and verification record for non-blocking picker responsiveness |
| [evaluations/terrain-foundation/](evaluations/terrain-foundation/) | Live screenshot and verification record for height-grid terrain schema and chunk hydration |
| [evaluations/terrain-sculpt-tools/](evaluations/terrain-sculpt-tools/) | Live screenshot and verification record for modal sculpt controls, footprint, and stroke history |
| [evaluations/terrain-material-layers/](evaluations/terrain-material-layers/) | Live screenshot and verification record for blended layers, assignment, painting, and history |
| [evaluations/navigation-authoring/](evaluations/navigation-authoring/) | Live screenshots and verification record for navigation authoring and runtime parity |
| [evaluations/production-readiness/](evaluations/production-readiness/) | Current #50 release-candidate matrix and required clean-checkout, soak, performance, limitation, and independent-signoff evidence |
@@ -38,6 +43,7 @@ Docs for the in-process egui editor (`crates/editor/`). Update this index when a
|-------------|----------------|-----|
| `lib.rs` / `EditorPluginGroup` | Ordered plugin bundle, lib/bin split | ADR 0008, architecture.md |
| `shared::components::BrushDesc` / `shared::hydration::brushes` | Persisted brush authoring data and generated runtime mesh hydration | brushes.md, ADR 0021 |
| `shared::components::TerrainDesc` / `shared::hydration::terrain` / `blacksite_surface` | Persisted height/layer grids, generated chunks, and raster blending | terrain.md, ADR 0039, ADR 0040 |
| `scene/` | Level I/O, tabs, composition materialization, schema, viewport render-target setup | architecture.md, multi-scene-composition.md, ADR 0026 |
| `viewport/` | Camera, selection, gizmos, render views | architecture.md |
| `play/` | PIE session, editor mode state | architecture.md |
+15
View File
@@ -0,0 +1,15 @@
# Editor Evaluation Evidence
Each subdirectory keeps the canonical, versioned acceptance record for an editor feature. Screenshots
remain in the repository beside that record and are intentionally stored through Git LFS.
## Publishing To Gitea
Do not embed a repository `/raw/branch/...` or `/raw/commit/...` PNG URL in an issue or pull-request
comment. Gitea can serve the LFS pointer document at that URL, which renders as text instead of an
image. Upload the PNG to the relevant issue as a native attachment and use the returned
`/attachments/<uuid>` URL for the Markdown image. Keep the repository evaluation link next to the
attachment so the evidence remains traceable to its committed source.
Native attachments are presentation copies. The committed evaluation directory remains the source of
truth and should retain the original image and verification notes.
@@ -1,6 +1,6 @@
# Production-Readiness Acceptance Matrix
**Matrix version:** 0.1
**Matrix version:** 0.2
**Last audit:** 2026-07-12
@@ -30,20 +30,20 @@ another commit, a dirty worktree, or an older package do not transfer to the can
| ID | Requirement | State | Current evidence and gap |
|----|-------------|-------|--------------------------|
| G1 | Project create/open/resume, scene authoring, autosave/recovery, hierarchy, prefab, and asset integrity pass | Partial | Project/recovery/session/multi-scene/prefab implementations are documented in [project launcher](../../project-launcher.md), [session recovery](../../session-recovery.md), [multi-scene composition](../../multi-scene-composition.md), and [prefab authoring](../../prefab-authoring.md). Candidate-specific end-to-end reruns and the open asset-integrity work remain. |
| G2 | Brush, material, terrain, physics placement, animation, audio, navigation, PIE, and build/package samples pass | Fail | Animation, audio, navigation, and build foundations are implemented. Material/drag-drop tickets `#16`, `#18`, and `#51` remain open; terrain `#22`-`#24` and physics placement `#25` are not complete; brush acceptance `#37` remains open. Packaged testing is owner-deferred. |
| G1 | Project create/open/resume, scene authoring, autosave/recovery, hierarchy, prefab, and asset integrity pass | Partial | Project/recovery/session/multi-scene/prefab implementations are documented in [project launcher](../../project-launcher.md), [session recovery](../../session-recovery.md), [multi-scene composition](../../multi-scene-composition.md), and [prefab authoring](../../prefab-authoring.md). Collaborative file safety `#49` and non-blocking native dialogs `#52` passed live acceptance. Candidate-specific end-to-end reruns remain. |
| G2 | Brush, material, terrain, physics placement, animation, audio, navigation, PIE, and build/package samples pass | Fail | Animation, audio, navigation, Material Library, targeted material drops, and build foundations are implemented. Renderer foundation `#51` remains open on deformed Solari geometry; terrain `#22`-`#24`, physics placement `#25`, and brush acceptance `#37` remain incomplete. Packaged testing is owner-deferred. |
| G3 | Undo/redo/cancel invariants and helper cleanup cover every production mutation path | Partial | The reusable harness and current tool coverage are documented in [operator regression testing](../../operator-regression-testing.md). Gitea `#33` remains open for terrain-stroke and physics-settle fixtures after those tools exist. |
| G4 | Representative project completes an eight-hour soak without unbounded memory/target growth or unrecoverable failure | Missing | No candidate soak log, resource timeline, failure ledger, or target-growth measurement exists. |
| G5 | Cold start, scene open/save, asset refresh, common manipulation, and package-build budgets are documented and measured | Missing | Gitea `#34` is open; no ratified budgets or candidate measurement record exists. |
| G6 | Headless content validation and CI are green from a clean checkout | Missing | [CI configuration](../../../../.github/workflows/ci.yml) exists and local source/headless checks have passed during feature work, but no clean-checkout candidate run is linked. The current Gitea server does not expose an Actions run endpoint for this repository. |
| G7 | First-hour UX and recovery QA are signed off by someone other than the implementer | External | No independent sign-off exists. Gitea `#36` remains open; historical H1-H6 implementation-pass notes do not count. |
| G8 | Known limitations have severity/workaround and no P0 blocker remains | Fail | Limitations are distributed across feature docs rather than one candidate ledger. Open P0 work includes `#16`, `#18`, `#32`, `#33`, `#35`, and `#51`; `#50` cannot close while a gate-relevant P0 remains. |
| G8 | Known limitations have severity/workaround and no P0 blocker remains | Fail | Limitations are distributed across feature docs rather than one candidate ledger. Open P0 work includes `#32`, `#33`, and `#51`; `#50` cannot close while a gate-relevant P0 remains. Roadmap audit `#35`, Material Library `#16`, targeted drops `#18`, collaborative safety `#49`, and dialog responsiveness `#52` are closed. |
## Deliverables
| ID | Deliverable | State | Evidence or next action |
|----|-------------|-------|-------------------------|
| D1 | Versioned acceptance matrix under `docs/editor/evaluations/` | Pass | This file, version 0.1. |
| D1 | Versioned acceptance matrix under `docs/editor/evaluations/` | Pass | This file, version 0.2. |
| D2 | Release-candidate representative project and reproducible validation commands | Missing | Expand the committed project/regression pack through `#32`, including terrain and physics-placement samples, then nominate an exact commit. |
| D3 | Signed milestone comment linking evidence, limitations, and exact commit | Missing | Post only after G1-G8 pass; no candidate exists yet. |
@@ -56,7 +56,7 @@ another commit, a dirty worktree, or an older package do not transfer to the can
| Hierarchy parenting and prefab structure | Implemented | Not rerun |
| Multi-scene composition | Implemented | Not rerun |
| Brush blockout/edit/CSG | Implemented foundation; `#37` open | Not signed off |
| Material catalog and assignment | Partial; `#16`, `#18`, `#51` open | Blocked |
| Material catalog and assignment | Material Library and exact targeted drops accepted; `#51` open only on deformed Solari geometry | Not rerun as one candidate |
| Terrain authoring | `#22`-`#24` open | Blocked |
| Physics placement | `#25` open | Blocked |
| Animation | Implemented | Not rerun |
@@ -64,7 +64,8 @@ another commit, a dirty worktree, or an older package do not transfer to the can
| Navigation | Implemented | Not rerun |
| PIE | Implemented | Not rerun |
| Build/package/runtime | Implemented foundation | Deferred by owner |
| Collaborative file safety | Local source/headless acceptance; `#49` open | Awaiting publication and live visual QA |
| Collaborative file safety | Implemented; `#49` closed with live external-change acceptance | Not rerun as one candidate |
| Native file/folder dialogs | Implemented; `#52` closed with live 12-second compositor-responsiveness hold | Not rerun as one candidate |
## Candidate Validation Commands
@@ -0,0 +1,42 @@
# Terrain Foundation Evaluation
Date: 2026-07-12
Branch: `codex/terrain-foundation`
Gitea issue: `#22`
This record captures acceptance for the persistent height-grid terrain schema and deterministic
runtime chunk hydration. The permanent workflow lives in the [terrain guide](../../terrain.md).
## Live Editor Evidence
The native Wayland debug editor loaded the committed
`assets/levels/terrain_authoring_showcase.scn.ron` fixture. The screenshot uses Forward rendering to
isolate mesh/material/light correctness while foundation terrain remains explicitly excluded from
Solari until exact terrain layer/Surface parity lands in `#24`.
![Asymmetric shared-material terrain hill generated from four runtime chunks](terrain-showcase-forward.png)
The 5×5 authored grid renders as the expected asymmetric hill, resolves the committed shared
Material Instance, and is split into four 2×2-quad chunks with generated trimesh colliders. The
authored scene contains no `HydratedTerrainChunk`, `Mesh3d`, or collider-constructor components.
## Acceptance Results
| Area | Result | Evidence |
|------|--------|----------|
| Schema and serialization | Pass | Versioned bounded descriptor, exact height count, finite-value and scale/chunk validation, RON round-trip test |
| Chunk hydration | Pass | Deterministic four-chunk runtime fixture; topology test verifies 25 vertices and 96 indices for a 4×4-quad mesh |
| Runtime-only ownership | Pass | Hydration test verifies children have mesh/collider/owner markers but no `LevelObject`, then verifies removal cleanup |
| Actor/editor integration | Pass | First-class Terrain kind, registry descriptor, hierarchy/viewport icon, reflected Add Component and inspector transaction path |
| Material behavior | Pass with boundary | Shared Material/Instance source resolves for raster; missing source uses visible fallback; Solari submission is explicitly excluded pending `#24` |
| Project validation | Pass | 60 level dependencies, existing 5 non-blocking findings, 0 blocking errors |
| Packaged acceptance | Deferred | Explicitly deferred by project-owner direction; no packaged result is claimed here |
## Automated Verification
| Command/suite | Result |
|---------------|--------|
| Focused terrain descriptor/topology/hydration tests | 4 passed |
| Editor component registry reflection contract | Pass |
| `cargo check --workspace --all-targets` | Pass |
| `cargo validate-levels --project .` | 60 dependencies, 5 findings, 0 blockers |
@@ -0,0 +1,36 @@
# Terrain Material Layers Acceptance
## Evidence
![Terrain layer paint stroke](terrain-material-paint-stroke.png)
The native Wayland editor is shown with the deterministic terrain showcase selected, two shared
material layers visible in the Inspector, Paint active in the existing horizontal viewport toolbar,
and the cyan terrain-following brush footprint over the blended PBR surface.
## Live Acceptance
- `Concrete` and `Surface Tint` blend continuously across all four generated chunks.
- Layer assignment, clear, reorder, remove, UV tiling, and per-layer sample coverage are visible in
the Terrain card without nesting a second panel.
- Paint and Erase share the existing horizontal toolbar with layer, radius, and strength controls.
- A Paint drag changed layer-two coverage from 13/25 to 16/25 samples and produced exactly one
`Undo: Paint Terrain Material` history entry.
- Ctrl+Z restored 13/25 samples; Ctrl+Y restored 16/25 samples.
- The cyan footprint followed the actual sampled terrain surface and the transform gizmo remained
absent while Paint owned viewport input.
- Forward PBR and the project `blacksite_surface` terrain extension compiled without GPU pipeline
errors. The invalid deferred-only prepass override found during QA was removed from both project
material extensions.
## Automated Coverage
- Terrain layer/weight RON round-trip and structural validation.
- RGBA8 normalization rejection and normalized vertex-color transport.
- Paint/Erase normalization and brush-footprint isolation.
- Multi-dab single-transaction undo/redo.
- Exact restoration of an implicit pre-stroke weight map on cancel.
Packaged build tests remain intentionally skipped per current project direction. Source workspace
format/check/clippy/tests, project validation, navigation bake validation, and diff hygiene are the
required gate for this ticket.
@@ -0,0 +1,31 @@
# Terrain Sculpt Tools Acceptance
Issue: Gitea `#23`
Scope: native Wayland debug editor; packaged acceptance remains deferred by project-owner direction.
## Live Evidence
![Raise stroke with terrain-following footprint and horizontal sculpt controls](terrain-sculpt-raise-stroke.png)
The committed terrain showcase was selected in Forward rendering. Enabling the mountains tool kept
the actor selected, removed the transform gizmo, expanded Raise/Lower/Flatten/Smooth/Noise plus
radius/strength controls inside the existing horizontal viewport toolbar, and displayed the modal
cancel/undo hints. A dragged Raise stroke visibly changed the generated terrain while the footprint
tracked the sampled surface. Release produced exactly `Undo: Raise Terrain`; no transform `Move`
history entry was created.
Escape/right-click restoration, deterministic brush math, exact vertical-ray sampling, multi-dab
stroke grouping, and sculpt-time gizmo exclusion are covered by focused tests. The live pass also
exposed and corrected toolbar click-through into raw mesh picking before this evidence was captured.
## Source Verification
- `cargo fmt --all -- --check`
- `cargo check -p editor --all-targets`
- `cargo clippy -p editor --all-targets -- -D warnings`
- six focused terrain-sculpt/input-ownership tests
- `git diff --check`
The canonical fixture remains `assets/levels/terrain_authoring_showcase.scn.ron`; no QA-only scene or
project setting is retained.
+69
View File
@@ -0,0 +1,69 @@
# Terrain Authoring
Terrain is a first-class authored actor backed by `TerrainDesc`. Add it from the Inspector's
**Add Component** shelf by searching for Terrain. It conflicts with other geometry sources on the
same actor: Primitive, Brush, Static Mesh Renderer, and Skinned Mesh Renderer.
## Foundation Workflow
The Terrain card exposes grid resolution, sample spacing, height scale, chunk size, generated
collision, shadows, base material status, and validation. **Resize Flat** deliberately replaces the
height array with a flat grid; normal numeric edits retain all height samples. Every accepted edit is
one reflected history transaction and rebuilds only that terrain's generated chunks.
## Sculpt Workflow
Select a terrain actor and enable the mountains button in the existing horizontal viewport toolbar.
Choose **Raise**, **Lower**, **Flatten**, **Smooth**, or **Noise**, then LMB-drag across the terrain.
The radius and strength controls use world meters; the colored footprint follows the sampled terrain
surface and identifies the active mode.
Each drag is one stroke and one undo entry, regardless of how many interpolated dabs it contains.
Escape or right-click restores the exact pre-stroke height grid; when no stroke is active, either input
closes the sculpt tool. Flatten captures the height under the initial press. Smooth samples a stable
copy of the current neighborhood per dab, and Noise uses a deterministic per-stroke seed so authored
results remain reproducible.
## Material Layers And Paint Workflow
The Terrain card owns up to four shared Material or Material Instance layers. Use the plus icon to
add a channel, then browse or drag a material into its selector. Each layer exposes independent UV
tiling and can be reordered or removed; channel weights move with the layer. The first added layer
adopts a legacy Base Material assignment so existing terrain converts without visual loss.
With at least two layers assigned, select the paint-brush button beside Sculpt in the existing
horizontal viewport toolbar. Choose **Paint** or **Erase**, select the target layer, then LMB-drag.
Paint increases the selected channel while proportionally reducing the others; Erase redistributes
weight to the remaining channels. Every sample stays normalized to 255, the terrain-following cyan
or amber footprint previews the brush, and release records one undo entry. Escape or right-click
restores the exact pre-stroke weights or closes the idle tool.
`assets/levels/terrain_authoring_showcase.scn.ron` is the deterministic foundation fixture. Its 5×5
grid forms an asymmetric hill split into four 2×2-quad chunks. It validates chunk boundaries,
normals, selection through generated children, collider generation, inspector state, and save
stripping without requiring external assets.
## Data And Hydration
- Heights are finite normalized values multiplied by Height Scale at hydration time.
- Up to four Material/Material Instance references remain shared assets rather than copied material
descriptors. RGBA8 weights are stored per height sample; an absent array means full layer zero.
- Generated chunk vertex colors carry normalized weights into the `blacksite_surface` terrain
material, which blends layer base color/texture, normal, metallic, and roughness inputs.
- Sample Spacing controls X/Z distance and the grid remains centered on the actor origin.
- Chunk Size is measured in quads. Neighboring chunks share boundary samples but not runtime mesh
assets, allowing later stroke updates to rebuild only affected chunks.
- Missing, unassigned, or invalid layer references produce a clear diagnostic and visible terrain
fallback rather than missing geometry.
- Generated `HydratedTerrainChunk` children own mesh, optional trimesh collider, and shadow state.
They are runtime-only and never serialized as authored actors.
- Foundation chunks are explicitly excluded from Solari submission and remain raster-visible while
Auto/Solari is active. Raster material-layer parity is shipped; matching Solari terrain evaluation
remains explicit future work, and the editor never substitutes a semantically different proxy.
The terrain foundation is recorded in [ADR 0039](../adr/0039-inline-height-grid-terrain-foundation.md),
and layer weight persistence/render transport in
[ADR 0040](../adr/0040-terrain-material-layer-weights.md).
Live native-Wayland evidence and focused verification are recorded in the
[terrain foundation evaluation](evaluations/terrain-foundation/).