[godot] Add SpineSprite3D lighting and shadows

Add opt-in generated lighting, atlas normal maps, PBR controls, and alpha-tested shadow modes for native 3D sprites.

Author: badlogic

CHANGELOG.md

@@ -316,6 +316,7 @@
   - Added `SpineSlotNode3D` for bone following, explicit 3D geometry insertion between Spine batches, and slot material overrides, plus batching statistics and renderer benchmarks.
   - Added `SpineSprite3D.camera_relative_depth`, `depth_write_enabled`, `alpha_cutoff`, `get_aabb()`, and `get_depth_shader_code()`, with a custom-shader guide and interactive front/back depth example for module and GDExtension.
   - Added explicit single-camera slot-anchor following through `SpineSlotNode3D.depth_camera`, with fixed-depth fallback and diagnostics for invalid cameras and multi-view/physics limitations.
+  - Added opt-in generated lighting, atlas normal maps, PBR controls, and texture-alpha-tested shadow modes to `SpineSprite3D`, with lazy shadow-only instances and an interactive Raptor lighting example.
   - Added `SpineAnimationTrack` support for `SpineSprite3D` and Godot 4 GDExtension, including AnimationPlayer playback/editor scrubbing for both 2D and 3D sprites and a shared timeline example.
   - Added an interactive 2D/3D benchmark example with configurable character counts, animation/pause controls, CPU timing and renderer statistics for module and GDExtension.
   - Added tint black (two-color tinting) for Godot 4.3+ module and GDExtension runtimes, with animated coin examples and custom shader color attributes. See [#3169](https://github.com/EsotericSoftware/spine-runtimes/issues/3169).
@@ -327,6 +328,7 @@
   - Added `SpineTrackEntry.get_additive()` / `set_additive()` for additive blending per track entry.
 
 - **Bug fixes**
+  - Fixed invalid `SpineSprite3D` preview animation names dereferencing a null track entry.
   - Fixed callback-time `time_scale` changes affecting animation and skeleton/physics advances one update late after controller extraction.
   - Fixed unrelated scene-tree mutations resetting `SpineSlotNode3D` insertion sorting and revealing inactive-bone children on manual or paused sprites; unchanged descendants retain ownership during transfers.
   - Fixed newly allocated `SpineSprite3D` batch instances rendering while hidden, including pool growth and inherited visibility.

spine-godot/DEPTH_RENDERING.md

@@ -9,6 +9,8 @@ sprite.camera_relative_depth = true
 sprite.depth_write_enabled = true
 sprite.slot_depth_offset = 0.001
 sprite.alpha_cutoff = 0.001
+sprite.lighting_enabled = false
+sprite.shadow_casting = SpineSprite3D.SHADOW_CASTING_OFF
 ```
 
 The generated materials are unlit and double-sided by default. Each attachment gets a small local Z offset according to its position in the **applied Spine draw order**. From behind, the vertex shader flips that offset, putting later attachments nearer the camera again. Attachment, triangle and batch submission order do not reverse. This preserves the authored layering from both sides, rather than revealing the back of a physical stack. It does not turn planar artwork into a volumetric character.
@@ -32,16 +34,71 @@ These depth-write settings control **generated materials**. Custom materials ret
 
 The regression covers default `pixel_size = 0.01` with a `0.001` gap, and a larger 48-unit-wide fixture viewed from 60 units away with a `0.01` gap. On the tested Compatibility backend, the latter needed more than `0.001` once vertex displacement was active. Tune spacing and camera clipping ranges for your scene. Larger gaps make the layered construction more visible and increase the position jump when the camera crosses edge-on.
 
-Alpha fades and soft atlas edges also deserve testing: fragments disappear at the cutoff, and surviving translucent fragments can occlude later geometry behind them. This is not order-independent transparency. Lighting and shadow support are separate from this depth policy; generated Spine materials currently cast no shadows.
+Alpha fades and soft atlas edges also deserve testing: fragments disappear at the cutoff, and surviving translucent fragments can occlude later geometry behind them. This is not order-independent transparency.
+
+## Generated lighting, normal maps, and shadows
+
+Lighting is opt-in so existing scenes keep their authored unlit appearance:
+
+```gdscript
+sprite.lighting_enabled = true
+sprite.normal_map_enabled = true
+sprite.normal_map_flip_y = true
+sprite.normal_scale = 1.0
+sprite.specular = 0.25
+sprite.roughness = 0.65
+sprite.metallic = 0.0
+```
+
+Generated lit materials use the attachment plane's normal when no normal map exists. The runtime supplies standard mesh normals and UV-derived tangents, so atlas pages with imported normal maps can use Godot's compressed tangent-space normal-map path. Normal-map loading is not a separate 3D path: configure the atlas importer's existing normal-map prefix (for example, `n` resolves `n_raptor.png`) and `SpineAtlasResource` supplies the matching page texture. `normal_map_flip_y` defaults on for the convention used by the bundled Raptor asset; disable it for maps authored with the opposite Y convention. Example19 starts the high-contrast Raptor map at `normal_scale = 0.25`; tune strength for each asset and light rig. Animated normal/PBR controls are uniforms and do not rebuild mesh buffers or duplicate warmed materials.
+
+Generated shadow casting is also opt-in:
+
+```gdscript
+sprite.shadow_casting = SpineSprite3D.SHADOW_CASTING_DOUBLE_SIDED
+sprite.shadow_alpha_cutoff = 0.3
+```
+
+Modes are **Off**, **On**, **Double-Sided**, and **Shadows Only**. Generated shadows use dedicated shadows-only RenderingServer instances and alpha-tested materials. They share the visible batch meshes and are allocated lazily on first use; turning shadows off hides and retains the warmed pool. `shadow_alpha_cutoff` is independent of visible `alpha_cutoff`, includes skeleton/slot/attachment tint alpha, and can be animated without creating a material for each value. Lighting does not need to be enabled for a generated material to cast shadows.
+
+`camera_relative_depth` still operates per rendering camera for visible generated shaders. A shadow map has the light's view, so test extreme slot spacing, culling, and lights crossing the planar character in your scene. The alpha-tested shadow is a planar silhouette, not volumetric self-shadowing.
 
 ## Custom Spine materials
 
 No user shader source is rewritten. Every cached `ShaderMaterial` pass receives these reserved uniforms from the sprite:
 
 - `spine_texture`: current atlas-page texture.
 - `spine_premultiplied_alpha`: the atlas page's PMA flag.
+- `spine_normal_texture`: current atlas-page normal map, when one was imported.
+- `spine_has_normal_texture`: whether the current page has a normal map.
 - `spine_camera_relative_depth`: the sprite's camera-relative-depth flag.
-- `spine_alpha_cutoff`: the sprite's alpha cutoff.
+- `spine_alpha_cutoff`: the sprite's visible alpha cutoff.
+- `spine_normal_map_enabled`, `spine_normal_map_flip_y`, and `spine_normal_scale`.
+- `spine_specular`, `spine_roughness`, and `spine_metallic`.
+
+Custom shaders receive light tint in `CUSTOM0`, dark tint in `CUSTOM1`, and standard mesh `NORMAL`/`TANGENT` attributes. They remain authored contracts: the runtime never inserts lighting, normal-map, blending, culling, depth, or shadow code into their source. Custom batches cast directly according to `shadow_casting`, so the shader's authored alpha/scissor and culling behavior controls its shadow pass; `shadow_alpha_cutoff` is only for generated shadow materials.
+
+Use Godot's normal-map outputs in a custom lit shader:
+
+```glsl
+uniform sampler2D spine_normal_texture : hint_normal, repeat_disable;
+uniform bool spine_has_normal_texture = false;
+uniform bool spine_normal_map_enabled = true;
+uniform bool spine_normal_map_flip_y = true;
+uniform float spine_normal_scale = 1.0;
+
+void fragment() {
+    // Set ALBEDO and ALPHA first.
+    if (spine_normal_map_enabled && spine_has_normal_texture) {
+        vec3 mapped_normal = texture(spine_normal_texture, UV).rgb;
+        if (spine_normal_map_flip_y) mapped_normal.g = 1.0 - mapped_normal.g;
+        NORMAL_MAP = mapped_normal;
+        NORMAL_MAP_DEPTH = spine_normal_scale;
+    }
+}
+```
+
+Do not manually rely on the sampled blue channel: Godot may import normal maps with two-channel compression and reconstruct Z internally when `NORMAL_MAP` is used. `NORMAL_MAP_DEPTH = 0.0` restores the flat normal.
 
 Template values for reserved uniforms do not override the sprite. Other uniforms remain template-owned. Reassign a template after changing its parameters to refresh cached copies. Every visible custom pass, including `next_pass`, needs to implement the policy if it should match the generated geometry. A pass that ignores it retains physical vertex positions and can hide or detach facial details from the back. Non-shader next passes do not acquire custom vertex logic automatically.
 
@@ -132,3 +189,5 @@ Native mesh culling bounds and `sprite.get_aabb()` include both possible depth d
 Editor click/box picking conservatively includes attachment triangles at both possible depth positions. It may select a triangle at the currently unused position, especially with exaggerated spacing. It does not follow texture alpha, arbitrary custom shader deformation, or gameplay collision shapes.
 
 Run `examples/18-depth-offset-orbit/depth-offset-orbit.tscn` in either Godot 4 example project. It uses the native sprite properties and generated materials. Compare the front/back toggle, then use **Exaggerate gap**, **Marker follows flip**, and **Face shader ignores flip** to inspect the child/custom-material contracts. The default gap can be restored with **Gap 0.001**.
+
+Run `examples/19-3d-lighting/3d-lighting.tscn` to inspect generated lighting, the Raptor atlas normal map, moving omni-light response, normal strength/Y convention, and texture-alpha shadows on opaque ground.

spine-godot/example-v4-extension/examples/15-spine-sprite-3d/spine-sprite-3d.tscn

@@ -60,6 +60,8 @@ skeleton_data_res = ExtResource("2")
 pixel_size = 0.007
 render_priority = -48
 cull_mode = 1
+lighting_enabled = true
+shadow_casting = 2
 preview_skin = "Default"
 preview_animation = "walk"
 preview_frame = true
@@ -77,6 +79,8 @@ rotation = Vector3(0, -0.32, 0)
 skeleton_data_res = ExtResource("2")
 pixel_size = 0.007
 render_priority = 48
+lighting_enabled = true
+shadow_casting = 2
 preview_skin = "Default"
 preview_animation = "hoverboard"
 preview_frame = true
@@ -87,6 +91,8 @@ position = Vector3(0, 1.5, 0.25)
 skeleton_data_res = ExtResource("3")
 pixel_size = 0.004
 slot_depth_offset = 0.0002
+lighting_enabled = true
+shadow_casting = 2
 preview_skin = "Default"
 preview_animation = "animation"
 preview_frame = true
@@ -98,5 +104,5 @@ offset_top = 20.0
 offset_right = 1128.0
 offset_bottom = 76.0
 theme_override_font_sizes/font_size = 20
-text = "Native SpineSprite3D — batched geometry, tint black, and a lit 3D sphere inserted at the hand slot\nThe light affects the sphere, orange box, and ground; generated Spine materials are unlit and cast no shadows."
+text = "Native SpineSprite3D — batched geometry, tint black, lighting, and alpha-cutout shadows\nGodot lights affect Spine and inserted 3D geometry; Spineboy uses flat normals."
 horizontal_alignment = 1

spine-godot/example-v4-extension/examples/19-3d-lighting/3d-lighting.gd

@@ -0,0 +1,96 @@
+extends Node3D
+
+@onready var raptor: SpineSprite3D = $Raptor
+@onready var light: OmniLight3D = $OmniLight3D
+var auto_light: CheckButton
+var lighting: CheckButton
+var normal_map: CheckButton
+var flip_normal_y: CheckButton
+var shadows: CheckButton
+var normal_scale: HSlider
+var shadow_cutoff: HSlider
+var status: Label
+var light_angle := 0.0
+
+func _ready():
+	$Camera3D.look_at(Vector3(0, 0.4, 0))
+	var animation_state := raptor.get_animation_state()
+	if animation_state != null:
+		animation_state.set_animation("walk", true, 0)
+	create_controls()
+	update_status()
+
+func _process(delta: float):
+	if auto_light != null and auto_light.button_pressed:
+		light_angle = fposmod(light_angle + delta * 35.0, 360.0)
+		var radians := deg_to_rad(light_angle)
+		light.position = Vector3(cos(radians) * 3.5, 2.5 + sin(radians * 0.5), 4.0)
+		update_status()
+
+func create_controls():
+	var panel := PanelContainer.new()
+	panel.set_anchors_and_offsets_preset(Control.PRESET_TOP_WIDE)
+	$UI.add_child(panel)
+	var margin := MarginContainer.new()
+	for side in ["left", "top", "right", "bottom"]:
+		margin.add_theme_constant_override("margin_" + side, 12)
+	panel.add_child(margin)
+	var rows := VBoxContainer.new()
+	margin.add_child(rows)
+	var title := Label.new()
+	title.text = "SpineSprite3D — generated lighting, atlas normal maps, and shadows"
+	title.add_theme_font_size_override("font_size", 22)
+	rows.add_child(title)
+	var controls := HFlowContainer.new()
+	rows.add_child(controls)
+	auto_light = add_toggle(controls, "Move light", true)
+	lighting = add_toggle(controls, "Lighting", raptor.lighting_enabled)
+	normal_map = add_toggle(controls, "Normal map", raptor.normal_map_enabled)
+	flip_normal_y = add_toggle(controls, "Flip normal Y", raptor.normal_map_flip_y)
+	shadows = add_toggle(controls, "Shadows", raptor.shadow_casting != SpineSprite3D.SHADOW_CASTING_OFF)
+	var normal_scale_label := Label.new()
+	normal_scale_label.text = "Normal strength"
+	controls.add_child(normal_scale_label)
+	normal_scale = HSlider.new()
+	normal_scale.custom_minimum_size.x = 90
+	normal_scale.min_value = 0
+	normal_scale.max_value = 3
+	normal_scale.step = 0.05
+	normal_scale.value = raptor.normal_scale
+	controls.add_child(normal_scale)
+	var shadow_cutoff_label := Label.new()
+	shadow_cutoff_label.text = "Shadow cutoff"
+	controls.add_child(shadow_cutoff_label)
+	shadow_cutoff = HSlider.new()
+	shadow_cutoff.custom_minimum_size.x = 90
+	shadow_cutoff.min_value = 0
+	shadow_cutoff.max_value = 1
+	shadow_cutoff.step = 0.01
+	shadow_cutoff.value = raptor.shadow_alpha_cutoff
+	controls.add_child(shadow_cutoff)
+	status = Label.new()
+	rows.add_child(status)
+	var note := Label.new()
+	note.text = "Normal map: assets/raptor/n_raptor.png (loaded by the atlas importer). The opaque ground receives the texture-alpha shadow."
+	rows.add_child(note)
+	lighting.toggled.connect(func(enabled): raptor.lighting_enabled = enabled; update_status())
+	normal_map.toggled.connect(func(enabled): raptor.normal_map_enabled = enabled; update_status())
+	flip_normal_y.toggled.connect(func(enabled): raptor.normal_map_flip_y = enabled; update_status())
+	shadows.toggled.connect(func(enabled):
+		raptor.shadow_casting = SpineSprite3D.SHADOW_CASTING_DOUBLE_SIDED if enabled else SpineSprite3D.SHADOW_CASTING_OFF
+		update_status())
+	normal_scale.value_changed.connect(func(value): raptor.normal_scale = value; update_status())
+	shadow_cutoff.value_changed.connect(func(value): raptor.shadow_alpha_cutoff = value; update_status())
+
+func add_toggle(parent: Control, text: String, enabled: bool) -> CheckButton:
+	var button := CheckButton.new()
+	button.text = text
+	button.button_pressed = enabled
+	parent.add_child(button)
+	return button
+
+func update_status():
+	if status == null:
+		return
+	status.text = "Normal strength %.2f | shadow cutoff %.2f | light (%.1f, %.1f, %.1f)" % [
+		raptor.normal_scale, raptor.shadow_alpha_cutoff, light.position.x, light.position.y, light.position.z]

spine-godot/example-v4-extension/examples/19-3d-lighting/3d-lighting.tscn

@@ -0,0 +1,58 @@
+[gd_scene load_steps=6 format=3]
+
+[ext_resource type="Script" path="res://examples/19-3d-lighting/3d-lighting.gd" id="1"]
+[ext_resource type="SpineSkeletonDataResource" path="res://assets/raptor/raptor-data.tres" id="2"]
+
+[sub_resource type="Environment" id="Environment"]
+background_mode = 1
+background_color = Color(0.08, 0.095, 0.12, 1)
+ambient_light_source = 3
+ambient_light_color = Color(0.25, 0.3, 0.4, 1)
+ambient_light_energy = 0.25
+
+[sub_resource type="StandardMaterial3D" id="GroundMaterial"]
+albedo_color = Color(0.12, 0.16, 0.22, 1)
+roughness = 0.9
+
+[sub_resource type="PlaneMesh" id="Ground"]
+material = SubResource("GroundMaterial")
+size = Vector2(14, 12)
+
+[node name="SpineSprite3DLighting" type="Node3D"]
+script = ExtResource("1")
+
+[node name="WorldEnvironment" type="WorldEnvironment" parent="."]
+environment = SubResource("Environment")
+
+[node name="Camera3D" type="Camera3D" parent="."]
+position = Vector3(0, 2.5, 10)
+current = true
+
+[node name="Raptor" type="SpineSprite3D" parent="."]
+position = Vector3(0, -1.35, 0)
+skeleton_data_res = ExtResource("2")
+pixel_size = 0.006
+lighting_enabled = true
+normal_map_enabled = true
+normal_map_flip_y = true
+normal_scale = 0.25
+specular = 0.25
+roughness = 0.65
+shadow_casting = 2
+shadow_alpha_cutoff = 0.3
+preview_skin = "Default"
+preview_animation = "walk"
+preview_frame = true
+preview_time = 0.2
+
+[node name="Ground" type="MeshInstance3D" parent="."]
+position = Vector3(0, -1.5, -1)
+mesh = SubResource("Ground")
+
+[node name="OmniLight3D" type="OmniLight3D" parent="."]
+position = Vector3(3.5, 2.5, 4)
+light_energy = 5.0
+omni_range = 20.0
+shadow_enabled = true
+
+[node name="UI" type="CanvasLayer" parent="."]

spine-godot/example-v4/examples/15-spine-sprite-3d/spine-sprite-3d.tscn

@@ -60,6 +60,8 @@ skeleton_data_res = ExtResource("2")
 pixel_size = 0.007
 render_priority = -48
 cull_mode = 1
+lighting_enabled = true
+shadow_casting = 2
 preview_skin = "Default"
 preview_animation = "walk"
 preview_frame = true
@@ -77,6 +79,8 @@ rotation = Vector3(0, -0.32, 0)
 skeleton_data_res = ExtResource("2")
 pixel_size = 0.007
 render_priority = 48
+lighting_enabled = true
+shadow_casting = 2
 preview_skin = "Default"
 preview_animation = "hoverboard"
 preview_frame = true
@@ -87,6 +91,8 @@ position = Vector3(0, 1.5, 0.25)
 skeleton_data_res = ExtResource("3")
 pixel_size = 0.004
 slot_depth_offset = 0.0002
+lighting_enabled = true
+shadow_casting = 2
 preview_skin = "Default"
 preview_animation = "animation"
 preview_frame = true
@@ -98,5 +104,5 @@ offset_top = 20.0
 offset_right = 1128.0
 offset_bottom = 76.0
 theme_override_font_sizes/font_size = 20
-text = "Native SpineSprite3D — batched geometry, tint black, and a lit 3D sphere inserted at the hand slot\nThe light affects the sphere, orange box, and ground; generated Spine materials are unlit and cast no shadows."
+text = "Native SpineSprite3D — batched geometry, tint black, lighting, and alpha-cutout shadows\nGodot lights affect Spine and inserted 3D geometry; Spineboy uses flat normals."
 horizontal_alignment = 1