feat(world): triplanar seabed shader with procedural normal maps and detail shading

Rock is normal-mapped triplanar in world space at two scales, sand carries an
oriented ripple normal map on the xz plane, and a grain map drives detail
occlusion, albedo mottling and roughness. The three maps are seamless,
seeded, mipmapped textures built synchronously by SeabedDetailTextures, so
no asset is needed and builds are deterministic. The mesh has no tangents:
perturbed normals are computed in world space and written to NORMAL.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

game/world/sites/bathymetric_terrain_actor.gd

@@ -2,14 +2,17 @@ class_name BathymetricTerrainActor
 extends StaticBody3D
 
 const TerrainHeightField = preload("res://game/domain/sites/terrain_height_field.gd")
+const SeabedDetailTextures = preload("res://game/world/sites/seabed_detail_textures.gd")
 const TERRAIN_SHADER = preload("res://game/world/sites/seabed_terrain.gdshader")
 
 const TILE_CELLS := 64
 const VISIBILITY_RANGE_END_M := 420.0
 const VISIBILITY_RANGE_MARGIN_M := 60.0
+const DETAIL_TEXTURE_SEED := 4102
 
 var _field: TerrainHeightField
 var _material: ShaderMaterial
+var _detail_textures: SeabedDetailTextures
 var _tiles_root: Node3D
 var _collision: CollisionShape3D
 
@@ -19,8 +22,13 @@ func configure(field: TerrainHeightField) -> String:
 		return "terrain field is missing"
 	_clear()
 	_field = field
+	if _detail_textures == null:
+		_detail_textures = SeabedDetailTextures.build(DETAIL_TEXTURE_SEED)
 	_material = ShaderMaterial.new()
 	_material.shader = TERRAIN_SHADER
+	_material.set_shader_parameter(&"sand_normal_map", _detail_textures.sand_normal)
+	_material.set_shader_parameter(&"rock_normal_map", _detail_textures.rock_normal)
+	_material.set_shader_parameter(&"rock_grain_map", _detail_textures.rock_grain)
 	_build_tiles()
 	_build_collision()
 	return ""
@@ -30,6 +38,10 @@ func height_field() -> TerrainHeightField:
 	return _field
 
 
+func terrain_material() -> ShaderMaterial:
+	return _material
+
+
 func tile_count() -> int:
 	return 0 if _tiles_root == null else _tiles_root.get_child_count()
 

game/world/sites/seabed_detail_textures.gd

@@ -0,0 +1,73 @@
+class_name SeabedDetailTextures
+extends RefCounted
+
+## Procedural, seamless detail maps for the seabed shader, built synchronously from
+## seeded noise so no texture asset is needed and every build is identical:
+## an oriented sand ripple normal map, a rock normal map and the rock grain map
+## (height, also read as occlusion and albedo mottling).
+
+const TEXTURE_SIZE := 256
+const RIPPLES_PER_TILE := 2.0
+const RIPPLE_WARP := 0.22
+const ROCK_BUMP_SCALE := 6.0
+const SAND_BUMP_SCALE := 3.0
+
+var sand_normal: ImageTexture
+var rock_normal: ImageTexture
+var rock_grain: ImageTexture
+
+
+static func build(seed: int) -> SeabedDetailTextures:
+	var result := SeabedDetailTextures.new()
+	var rock_height := _rock_height_image(seed)
+	result.rock_grain = _texture_from(rock_height)
+	var rock_bumps := rock_height.duplicate() as Image
+	rock_bumps.bump_map_to_normal_map(ROCK_BUMP_SCALE)
+	result.rock_normal = _texture_from(rock_bumps)
+	var sand_height := _sand_height_image(seed + 1)
+	sand_height.bump_map_to_normal_map(SAND_BUMP_SCALE)
+	result.sand_normal = _texture_from(sand_height)
+	return result
+
+
+## Ridged fractal noise: sharp crests and pits, seamless across the tile.
+static func _rock_height_image(seed: int) -> Image:
+	var noise := FastNoiseLite.new()
+	noise.noise_type = FastNoiseLite.TYPE_SIMPLEX_SMOOTH
+	noise.seed = seed
+	noise.frequency = 0.012
+	noise.fractal_type = FastNoiseLite.FRACTAL_RIDGED
+	noise.fractal_octaves = 5
+	return noise.get_seamless_image(TEXTURE_SIZE, TEXTURE_SIZE, false, false, 0.1, true)
+
+
+## Ripples across the tile's v axis, warped and grained by noise. Asymmetric profile
+## (gentle stoss side, steep lee side) as on a swell-built sand bed.
+static func _sand_height_image(seed: int) -> Image:
+	var warp := FastNoiseLite.new()
+	warp.noise_type = FastNoiseLite.TYPE_SIMPLEX_SMOOTH
+	warp.seed = seed
+	warp.frequency = 0.02
+	warp.fractal_octaves = 2
+	var warp_image := warp.get_seamless_image(TEXTURE_SIZE, TEXTURE_SIZE, false, false, 0.1, true)
+	var grain := FastNoiseLite.new()
+	grain.noise_type = FastNoiseLite.TYPE_SIMPLEX_SMOOTH
+	grain.seed = seed + 7
+	grain.frequency = 0.15
+	grain.fractal_octaves = 3
+	var grain_image := grain.get_seamless_image(TEXTURE_SIZE, TEXTURE_SIZE, false, false, 0.1, true)
+	var image := Image.create(TEXTURE_SIZE, TEXTURE_SIZE, false, Image.FORMAT_L8)
+	for y in TEXTURE_SIZE:
+		for x in TEXTURE_SIZE:
+			var phase := (float(y) / float(TEXTURE_SIZE)) * RIPPLES_PER_TILE
+			phase += (warp_image.get_pixel(x, y).r - 0.5) * RIPPLE_WARP
+			var fraction := phase - floorf(phase)
+			var crest := fraction / 0.7 if fraction < 0.7 else (1.0 - fraction) / 0.3
+			var height := crest * 0.8 + grain_image.get_pixel(x, y).r * 0.2
+			image.set_pixel(x, y, Color(height, height, height))
+	return image
+
+
+static func _texture_from(image: Image) -> ImageTexture:
+	image.generate_mipmaps()
+	return ImageTexture.create_from_image(image)

game/world/sites/seabed_terrain.gdshader

@@ -1,6 +1,13 @@
 shader_type spatial;
 render_mode depth_draw_opaque;
 
+// Sand / rock split by slope, matching the sonar material rule (sand under 20 deg,
+// rock over 40 deg). Rock is normal-mapped triplanar in world space so cliffs and
+// ledges keep their detail; sand carries an oriented ripple normal map on the xz plane.
+// The mesh has no tangents: perturbed normals are built in world space and written
+// to NORMAL in view space. Detail shading comes from the normal maps, a grain map
+// used as ambient occlusion in the pits, and albedo mottling.
+
 uniform vec3 sand_color : source_color = vec3(0.50, 0.46, 0.34);
 uniform vec3 rock_color : source_color = vec3(0.21, 0.20, 0.18);
 uniform vec3 deep_tint : source_color = vec3(0.04, 0.09, 0.15);
@@ -8,8 +15,19 @@ uniform float sand_slope_cosine = 0.9397; // cos(20 deg)
 uniform float rock_slope_cosine = 0.7660; // cos(40 deg)
 uniform float depth_tint_start_m = 20.0;
 uniform float depth_tint_end_m = 90.0;
-uniform float ripple_wavelength_m = 1.6;
-uniform float ripple_contrast = 0.12;
+
+uniform sampler2D sand_normal_map : hint_normal, repeat_enable, filter_linear_mipmap;
+uniform sampler2D rock_normal_map : hint_normal, repeat_enable, filter_linear_mipmap;
+uniform sampler2D rock_grain_map : hint_default_white, repeat_enable, filter_linear_mipmap;
+uniform float sand_tile_m = 3.2;
+uniform float rock_tile_m = 7.0;
+uniform float rock_grain_tile_m = 1.7;
+uniform float sand_normal_strength = 1.0;
+uniform float rock_normal_strength = 1.1;
+uniform float rock_grain_normal_strength = 0.45;
+uniform float grain_ao_strength = 0.5;
+uniform float grain_albedo_contrast = 0.45;
+uniform vec2 ripple_direction = vec2(0.8, 0.6);
 
 varying vec3 world_position;
 varying vec3 world_normal;
@@ -19,17 +37,75 @@ void vertex() {
 	world_normal = normalize((MODEL_MATRIX * vec4(NORMAL, 0.0)).xyz);
 }
 
+vec3 unpack_normal(vec4 sample) {
+	return sample.xyz * 2.0 - 1.0;
+}
+
+// Triplanar normal perturbation (UDN blend): each plane's tangent-space xy is added
+// onto the world normal along that plane's axes, weighted by how much the surface
+// faces the plane.
+vec3 triplanar_normal(sampler2D map, vec3 position, vec3 normal, float strength) {
+	vec3 weights = pow(abs(normal), vec3(4.0));
+	weights /= weights.x + weights.y + weights.z;
+	vec3 tx = unpack_normal(texture(map, position.zy));
+	vec3 ty = unpack_normal(texture(map, position.xz));
+	vec3 tz = unpack_normal(texture(map, position.xy));
+	vec3 perturbation = (
+		vec3(0.0, tx.y, tx.x) * weights.x
+		+ vec3(ty.x, 0.0, ty.y) * weights.y
+		+ vec3(tz.x, tz.y, 0.0) * weights.z
+	) * strength;
+	return normalize(normal + perturbation);
+}
+
+float triplanar_grain(sampler2D map, vec3 position, vec3 normal) {
+	vec3 weights = pow(abs(normal), vec3(4.0));
+	weights /= weights.x + weights.y + weights.z;
+	return texture(map, position.zy).r * weights.x
+		+ texture(map, position.xz).r * weights.y
+		+ texture(map, position.xy).r * weights.z;
+}
+
 void fragment() {
-	float up = clamp(world_normal.y, 0.0, 1.0);
+	vec3 n = normalize(world_normal);
+	float up = clamp(n.y, 0.0, 1.0);
 	float rockness = 1.0 - smoothstep(rock_slope_cosine, sand_slope_cosine, up);
-	vec3 albedo = mix(sand_color, rock_color, rockness);
-	float phase = (world_position.x * 0.8 + world_position.z * 0.6) * TAU / ripple_wavelength_m;
-	float ripple = sin(phase) * ripple_contrast * (1.0 - rockness);
-	albedo *= 1.0 + ripple;
+
+	// Sand: ripple normal map rotated to the swell direction, on the xz plane.
+	vec2 ripple_axis = normalize(ripple_direction);
+	vec2 sand_uv = vec2(
+		dot(world_position.xz, ripple_axis),
+		dot(world_position.xz, vec2(-ripple_axis.y, ripple_axis.x))
+	) / sand_tile_m;
+	vec3 sand_tangent = unpack_normal(texture(sand_normal_map, sand_uv));
+	vec3 sand_perturbation = (
+		vec3(ripple_axis.x, 0.0, ripple_axis.y) * sand_tangent.x
+		+ vec3(-ripple_axis.y, 0.0, ripple_axis.x) * sand_tangent.y
+	) * sand_normal_strength;
+	vec3 sand_normal = normalize(n + sand_perturbation);
+
+	// Rock: coarse triplanar normal map plus fine grain, both in world space.
+	vec3 rock_normal = triplanar_normal(rock_normal_map, world_position / rock_tile_m, n, rock_normal_strength);
+	rock_normal = triplanar_normal(rock_normal_map, world_position / rock_grain_tile_m, rock_normal, rock_grain_normal_strength);
+	float grain = triplanar_grain(rock_grain_map, world_position / rock_grain_tile_m, n);
+
+	vec3 shading_normal = normalize(mix(sand_normal, rock_normal, rockness));
+	NORMAL = normalize((VIEW_MATRIX * vec4(shading_normal, 0.0)).xyz);
+
+	// Albedo: mottled rock, lightly grained sand, both tinted with depth.
+	vec3 rock_albedo = rock_color * (1.0 + (grain - 0.5) * 2.0 * grain_albedo_contrast);
+	vec3 sand_albedo = sand_color * (1.0 + (grain - 0.5) * 0.3);
+	vec3 albedo = mix(sand_albedo, rock_albedo, rockness);
 	float depth_m = -world_position.y;
 	float tint = smoothstep(depth_tint_start_m, depth_tint_end_m, depth_m);
 	albedo = mix(albedo, deep_tint, tint * 0.6);
 	ALBEDO = albedo;
-	ROUGHNESS = mix(0.95, 0.82, rockness);
+
+	// Detail shading: pits of the grain map and ripple troughs read as occlusion.
+	float rock_ao = mix(1.0, 0.45 + 0.55 * grain, grain_ao_strength);
+	float sand_ao = mix(1.0, 0.8 + 0.2 * clamp(sand_tangent.z, 0.0, 1.0), grain_ao_strength * 0.6);
+	AO = mix(sand_ao, rock_ao, rockness);
+	AO_LIGHT_AFFECT = 0.35;
+	ROUGHNESS = mix(0.95, 0.78 + 0.12 * grain, rockness);
 	METALLIC = 0.0;
 }