Non-Destructive Layer System

doc/docs/tips_technical.md

@@ -11,7 +11,7 @@ This list are for items that don't already have dedicated pages in the documenta
 | GPU Sculpting| [Pending](https://github.com/TokisanGames/Terrain3D/issues/174). Currently painting occurs on the CPU in C++. It's reasonably fast, but we have a soft limit of 200 on the brush size, as larger sizes lag.
 | Holes | Holes work for both visual and collision.
 | Jolt | [Godot-Jolt](https://github.com/godot-jolt/godot-jolt) was merged into Godot. Terrain3D works with both Godot and Jolt physics. Collision is generated where regions are defined.
-| Non-destructive layers | Used for things like river beds, roads or paths that follow a curve and tweak the terrain. It's [possible](https://github.com/TokisanGames/Terrain3D/issues/129) in the future.
+| Non-destructive layers | Supported via `Terrain3DData.set_map_layer()` (with optional `release_map_layer()` cleanup) so external generators can push fully baked textures into the layer stack without touching the base maps. Use deterministic `external_id` values per `(region, map_type)` to update an existing layer instead of spawning duplicates.
 | Object placement | The [instancer](instancer.md) supports placing foliage. Placing objects that shouldn't be in a MultiMeshInstance node is [out of scope](https://github.com/TokisanGames/Terrain3D/issues/47). See 3rd party tools below.
 | Streaming | There is no streaming built in to Godot. Region Streaming is [in progress](https://github.com/TokisanGames/Terrain3D/pull/675).
 | Roads | Look at [Godot Road Generator](https://github.com/TheDuckCow/godot-road-generator/).

project/addons/terrain_3d/csharp/Terrain3D.cs

@@ -8,6 +8,7 @@
 
 namespace TokisanGames;
 
+[Tool]
 public partial class Terrain3D : Node3D
 {
 
@@ -28,10 +29,9 @@ protected Terrain3D() { }
 	/// <returns>The existing or a new instance of the <see cref="Terrain3D"/> wrapper script attached to the supplied <paramref name="godotObject"/>.</returns>
 	public new static Terrain3D Bind(GodotObject godotObject)
 	{
-#if DEBUG
 		if (!IsInstanceValid(godotObject))
-			throw new InvalidOperationException("The supplied GodotObject instance is not valid.");
-#endif
+			return null;
+
 		if (godotObject is Terrain3D wrapperScriptInstance)
 			return wrapperScriptInstance;
 
@@ -150,15 +150,20 @@ public event AssetsChangedSignalHandler AssetsChangedSignal
 		public new static readonly StringName CollisionMode = "collision_mode";
 		public new static readonly StringName CollisionShapeSize = "collision_shape_size";
 		public new static readonly StringName CollisionRadius = "collision_radius";
+		public new static readonly StringName CollisionTarget = "collision_target";
 		public new static readonly StringName CollisionLayer = "collision_layer";
 		public new static readonly StringName CollisionMask = "collision_mask";
 		public new static readonly StringName CollisionPriority = "collision_priority";
 		public new static readonly StringName PhysicsMaterial = "physics_material";
-		public new static readonly StringName CollisionTarget = "collision_target";
+		public new static readonly StringName ClipmapTarget = "clipmap_target";
 		public new static readonly StringName MeshLods = "mesh_lods";
 		public new static readonly StringName MeshSize = "mesh_size";
 		public new static readonly StringName VertexSpacing = "vertex_spacing";
-		public new static readonly StringName ClipmapTarget = "clipmap_target";
+		public new static readonly StringName TessellationLevel = "tessellation_level";
+		public new static readonly StringName DisplacementScale = "displacement_scale";
+		public new static readonly StringName DisplacementSharpness = "displacement_sharpness";
+		public new static readonly StringName BufferShaderOverrideEnabled = "buffer_shader_override_enabled";
+		public new static readonly StringName BufferShaderOverride = "buffer_shader_override";
 		public new static readonly StringName RenderLayers = "render_layers";
 		public new static readonly StringName MouseLayer = "mouse_layer";
 		public new static readonly StringName CastShadows = "cast_shadows";
@@ -182,9 +187,12 @@ public event AssetsChangedSignalHandler AssetsChangedSignal
 		public new static readonly StringName ShowControlScale = "show_control_scale";
 		public new static readonly StringName ShowColormap = "show_colormap";
 		public new static readonly StringName ShowRoughmap = "show_roughmap";
+		public new static readonly StringName ShowDisplacementBuffer = "show_displacement_buffer";
+		public new static readonly StringName ShowTextureAlbedo = "show_texture_albedo";
 		public new static readonly StringName ShowTextureHeight = "show_texture_height";
 		public new static readonly StringName ShowTextureNormal = "show_texture_normal";
 		public new static readonly StringName ShowTextureRough = "show_texture_rough";
+		public new static readonly StringName ShowTextureAo = "show_texture_ao";
 	}
 
 	public new string Version
@@ -279,6 +287,12 @@ public event AssetsChangedSignalHandler AssetsChangedSignal
 		set => Set(GDExtensionPropertyName.CollisionRadius, value);
 	}
 
+	public new Node3D CollisionTarget
+	{
+		get => Get(GDExtensionPropertyName.CollisionTarget).As<Node3D>();
+		set => Set(GDExtensionPropertyName.CollisionTarget, value);
+	}
+
 	public new long CollisionLayer
 	{
 		get => Get(GDExtensionPropertyName.CollisionLayer).As<long>();
@@ -303,10 +317,10 @@ public event AssetsChangedSignalHandler AssetsChangedSignal
 		set => Set(GDExtensionPropertyName.PhysicsMaterial, value);
 	}
 
-	public new Node3D CollisionTarget
+	public new Node3D ClipmapTarget
 	{
-		get => Get(GDExtensionPropertyName.CollisionTarget).As<Node3D>();
-		set => Set(GDExtensionPropertyName.CollisionTarget, value);
+		get => Get(GDExtensionPropertyName.ClipmapTarget).As<Node3D>();
+		set => Set(GDExtensionPropertyName.ClipmapTarget, value);
 	}
 
 	public new long MeshLods
@@ -327,10 +341,34 @@ public event AssetsChangedSignalHandler AssetsChangedSignal
 		set => Set(GDExtensionPropertyName.VertexSpacing, value);
 	}
 
-	public new Node3D ClipmapTarget
+	public new long TessellationLevel
 	{
-		get => Get(GDExtensionPropertyName.ClipmapTarget).As<Node3D>();
-		set => Set(GDExtensionPropertyName.ClipmapTarget, value);
+		get => Get(GDExtensionPropertyName.TessellationLevel).As<long>();
+		set => Set(GDExtensionPropertyName.TessellationLevel, value);
+	}
+
+	public new double DisplacementScale
+	{
+		get => Get(GDExtensionPropertyName.DisplacementScale).As<double>();
+		set => Set(GDExtensionPropertyName.DisplacementScale, value);
+	}
+
+	public new double DisplacementSharpness
+	{
+		get => Get(GDExtensionPropertyName.DisplacementSharpness).As<double>();
+		set => Set(GDExtensionPropertyName.DisplacementSharpness, value);
+	}
+
+	public new bool BufferShaderOverrideEnabled
+	{
+		get => Get(GDExtensionPropertyName.BufferShaderOverrideEnabled).As<bool>();
+		set => Set(GDExtensionPropertyName.BufferShaderOverrideEnabled, value);
+	}
+
+	public new Shader BufferShaderOverride
+	{
+		get => Get(GDExtensionPropertyName.BufferShaderOverride).As<Shader>();
+		set => Set(GDExtensionPropertyName.BufferShaderOverride, value);
 	}
 
 	public new long RenderLayers
@@ -345,9 +383,9 @@ public event AssetsChangedSignalHandler AssetsChangedSignal
 		set => Set(GDExtensionPropertyName.MouseLayer, value);
 	}
 
-	public new Variant CastShadows
+	public new long CastShadows
 	{
-		get => Get(GDExtensionPropertyName.CastShadows).As<Variant>();
+		get => Get(GDExtensionPropertyName.CastShadows).As<long>();
 		set => Set(GDExtensionPropertyName.CastShadows, value);
 	}
 
@@ -471,6 +509,18 @@ public event AssetsChangedSignalHandler AssetsChangedSignal
 		set => Set(GDExtensionPropertyName.ShowRoughmap, value);
 	}
 
+	public new bool ShowDisplacementBuffer
+	{
+		get => Get(GDExtensionPropertyName.ShowDisplacementBuffer).As<bool>();
+		set => Set(GDExtensionPropertyName.ShowDisplacementBuffer, value);
+	}
+
+	public new bool ShowTextureAlbedo
+	{
+		get => Get(GDExtensionPropertyName.ShowTextureAlbedo).As<bool>();
+		set => Set(GDExtensionPropertyName.ShowTextureAlbedo, value);
+	}
+
 	public new bool ShowTextureHeight
 	{
 		get => Get(GDExtensionPropertyName.ShowTextureHeight).As<bool>();
@@ -489,6 +539,12 @@ public event AssetsChangedSignalHandler AssetsChangedSignal
 		set => Set(GDExtensionPropertyName.ShowTextureRough, value);
 	}
 
+	public new bool ShowTextureAo
+	{
+		get => Get(GDExtensionPropertyName.ShowTextureAo).As<bool>();
+		set => Set(GDExtensionPropertyName.ShowTextureAo, value);
+	}
+
 	public new static class GDExtensionMethodName
 	{
 		public new static readonly StringName SetEditor = "set_editor";

project/addons/terrain_3d/csharp/Terrain3DAssets.cs

@@ -8,6 +8,7 @@
 
 namespace TokisanGames;
 
+[Tool]
 public partial class Terrain3DAssets : Resource
 {
 
@@ -28,10 +29,9 @@ protected Terrain3DAssets() { }
 	/// <returns>The existing or a new instance of the <see cref="Terrain3DAssets"/> wrapper script attached to the supplied <paramref name="godotObject"/>.</returns>
 	public new static Terrain3DAssets Bind(GodotObject godotObject)
 	{
-#if DEBUG
 		if (!IsInstanceValid(godotObject))
-			throw new InvalidOperationException("The supplied GodotObject instance is not valid.");
-#endif
+			return null;
+
 		if (godotObject is Terrain3DAssets wrapperScriptInstance)
 			return wrapperScriptInstance;
 
@@ -148,10 +148,12 @@ public event TexturesChangedSignalHandler TexturesChangedSignal
 		public new static readonly StringName GetTextureColors = "get_texture_colors";
 		public new static readonly StringName GetTextureNormalDepths = "get_texture_normal_depths";
 		public new static readonly StringName GetTextureAoStrengths = "get_texture_ao_strengths";
+		public new static readonly StringName GetTextureAoLightAffects = "get_texture_ao_light_affects";
 		public new static readonly StringName GetTextureRoughnessMods = "get_texture_roughness_mods";
 		public new static readonly StringName GetTextureUvScales = "get_texture_uv_scales";
 		public new static readonly StringName GetTextureVerticalProjections = "get_texture_vertical_projections";
 		public new static readonly StringName GetTextureDetiles = "get_texture_detiles";
+		public new static readonly StringName GetTextureDisplacements = "get_texture_displacements";
 		public new static readonly StringName ClearTextures = "clear_textures";
 		public new static readonly StringName UpdateTextureList = "update_texture_list";
 		public new static readonly StringName SetMeshAsset = "set_mesh_asset";
@@ -186,6 +188,9 @@ public event TexturesChangedSignalHandler TexturesChangedSignal
 	public new float[] GetTextureAoStrengths() => 
 		Call(GDExtensionMethodName.GetTextureAoStrengths, []).As<float[]>();
 
+	public new float[] GetTextureAoLightAffects() => 
+		Call(GDExtensionMethodName.GetTextureAoLightAffects, []).As<float[]>();
+
 	public new float[] GetTextureRoughnessMods() => 
 		Call(GDExtensionMethodName.GetTextureRoughnessMods, []).As<float[]>();
 
@@ -198,6 +203,9 @@ public event TexturesChangedSignalHandler TexturesChangedSignal
 	public new Vector2[] GetTextureDetiles() => 
 		Call(GDExtensionMethodName.GetTextureDetiles, []).As<Vector2[]>();
 
+	public new Vector2[] GetTextureDisplacements() => 
+		Call(GDExtensionMethodName.GetTextureDisplacements, []).As<Vector2[]>();
+
 	public new void ClearTextures(bool update = false) => 
 		Call(GDExtensionMethodName.ClearTextures, [update]);
 

project/addons/terrain_3d/csharp/Terrain3DCollision.cs

@@ -8,6 +8,7 @@
 
 namespace TokisanGames;
 
+[Tool]
 public partial class Terrain3DCollision : GodotObject
 {
 
@@ -28,10 +29,9 @@ protected Terrain3DCollision() { }
 	/// <returns>The existing or a new instance of the <see cref="Terrain3DCollision"/> wrapper script attached to the supplied <paramref name="godotObject"/>.</returns>
 	public new static Terrain3DCollision Bind(GodotObject godotObject)
 	{
-#if DEBUG
 		if (!IsInstanceValid(godotObject))
-			throw new InvalidOperationException("The supplied GodotObject instance is not valid.");
-#endif
+			return null;
+
 		if (godotObject is Terrain3DCollision wrapperScriptInstance)
 			return wrapperScriptInstance;