summer-engine 4.3.0 → 4.6.0

package/library/skills/painted-25d-world/_building-blocks/blockout_builder.gd

@@ -0,0 +1,149 @@
+extends Node3D
+## Builds a location's blockout from a JSON spec, so the same file drives the engine and the engine-free
+## wireframe preview over the concept (preview.py). Put this node as the location's `Painted` child.
+## Spec: {"objects": [{"name", "kind", "color", "solid", ...}]}, metres, y up:
+##   box    pos (centre), size [x, y, z], yaw / rot_x / rot_z (degrees), scale
+##   prism  pos, size (a PrismMesh: the ridge along z), yaw / rot_x / rot_z
+##   cyl    pos (base centre), r_bot, r_top, height
+##   sphere pos (centre), radius, sy (vertical squash)
+##   poly   points [[x, z], ...], top, depth: flat ground or a quay, extruded down, two-sided collision
+##   wall   segments [[[x, z], [x, z]], ...], height: invisible blockers along water and ledges (leave gaps at
+##          pier roots and doorways)
+## Each solid object gets a StaticBody3D with a matching shape; every mesh gets one flat colour from COLORS that
+## tells the painter what it is (the paint-over prompt repeats them as a colour key). Name door and step slabs
+## "..._door" / "..._steps": painted_location.gd hides them in the game. A gable roof is two parts: a
+## wall-coloured prism for the gable plus two thin slanted roof slabs with overhang; a single roof-coloured prism
+## makes the painter paint roof on the gable wall.
+
+@export_file("*.json") var spec := "res://painted/blockout.json"
+
+## Colour key: red tile roof, yellow thatch, dark blue slate, cream plaster, grey stone, brown wood and doors,
+## green grass and leaves, pink flower beds, orange lamps and fruit, light brown cobbles and dirt, blue water.
+const COLORS := {
+	"tile": Color(0.78, 0.25, 0.18), "thatch": Color(0.88, 0.72, 0.32), "slate": Color(0.22, 0.26, 0.42),
+	"plaster": Color(0.93, 0.88, 0.76), "stone": Color(0.55, 0.55, 0.55), "rock": Color(0.42, 0.4, 0.44),
+	"wood": Color(0.5, 0.33, 0.18), "door": Color(0.42, 0.26, 0.14), "crate": Color(0.66, 0.48, 0.28),
+	"grass": Color(0.36, 0.62, 0.25), "leaf": Color(0.2, 0.55, 0.2), "bush": Color(0.3, 0.55, 0.22),
+	"bark": Color(0.35, 0.22, 0.12), "flower": Color(0.95, 0.55, 0.75), "lamp": Color(1.0, 0.65, 0.2),
+	"cobble": Color(0.72, 0.6, 0.45), "dirt": Color(0.72, 0.56, 0.38), "water": Color(0.1, 0.35, 0.5),
+	"canvas": Color(0.9, 0.3, 0.3), "iron": Color(0.15, 0.15, 0.17), "glass": Color(0.35, 0.5, 0.75),
+	"floor": Color(0.6, 0.42, 0.25), "rug": Color(0.6, 0.15, 0.2), "fire": Color(1.0, 0.5, 0.1),
+	"white": Color(0.97, 0.97, 0.97),
+}
+
+func _ready() -> void:
+	var data: Dictionary = JSON.parse_string(FileAccess.get_file_as_string(spec))
+	for o in data.objects:
+		if o.kind == "wall":
+			_walls(o)
+		else:
+			_build(o)
+
+## Invisible collision only: keeps the player out of the water and on the piers.
+func _walls(o: Dictionary) -> void:
+	var body := StaticBody3D.new()
+	body.name = o.name
+	for seg in o.segments:
+		var a := Vector3(seg[0][0], 0, seg[0][1])
+		var b := Vector3(seg[1][0], 0, seg[1][1])
+		var cs := CollisionShape3D.new()
+		var s := BoxShape3D.new()
+		s.size = Vector3(a.distance_to(b) + 0.1, o.height, 0.2)
+		cs.shape = s
+		cs.position = (a + b) / 2.0 + Vector3(0, o.height / 2.0, 0)
+		cs.rotation.y = atan2(-(b.z - a.z), b.x - a.x)
+		body.add_child(cs)
+	add_child(body)
+
+func _build(o: Dictionary) -> void:
+	var mesh: Mesh
+	var shape: Shape3D
+	var offset := Vector3.ZERO
+	match o.kind:
+		"box":
+			var b := BoxMesh.new()
+			b.size = _v(o.size)
+			mesh = b
+			var s := BoxShape3D.new()
+			s.size = b.size
+			shape = s
+		"prism":
+			var p := PrismMesh.new()
+			p.size = _v(o.size)
+			mesh = p
+			shape = p.create_convex_shape()
+		"cyl":
+			var c := CylinderMesh.new()
+			c.top_radius = o.r_top
+			c.bottom_radius = o.r_bot
+			c.height = o.height
+			c.radial_segments = 24
+			mesh = c
+			offset.y = o.height / 2.0
+			var s := CylinderShape3D.new()
+			s.radius = maxf(o.r_top, o.r_bot)
+			s.height = o.height
+			shape = s
+		"sphere":
+			var sp := SphereMesh.new()
+			sp.radius = o.radius
+			sp.height = o.radius * 2.0
+			mesh = sp
+			var s := SphereShape3D.new()
+			s.radius = o.radius
+			shape = s
+		"poly":
+			mesh = _extrude(o.points, o.top, o.depth)
+			shape = mesh.create_trimesh_shape()
+			(shape as ConcavePolygonShape3D).backface_collision = true
+	var mi := MeshInstance3D.new()
+	mi.name = o.name
+	mi.mesh = mesh
+	var mat := StandardMaterial3D.new()
+	mat.albedo_color = COLORS.get(o.color, Color.MAGENTA)
+	mat.cull_mode = BaseMaterial3D.CULL_DISABLED
+	mi.material_override = mat
+	var holder: Node3D = mi
+	if o.get("solid", false):
+		var body := StaticBody3D.new()
+		body.name = o.name + "Body"
+		var cs := CollisionShape3D.new()
+		cs.shape = shape
+		body.add_child(cs)
+		body.add_child(mi)
+		holder = body
+	if o.kind != "poly":
+		holder.position = _v(o.pos) + offset
+		holder.rotation_degrees = Vector3(o.get("rot_x", 0.0), o.get("yaw", 0.0), o.get("rot_z", 0.0))
+		if o.kind == "sphere" and o.has("sy"):
+			mi.scale = Vector3(1, o.sy, 1)
+		if o.has("scale"):
+			holder.scale = _v(o.scale)
+	add_child(holder)
+
+## A flat polygon (x, z points) extruded from top down by depth, with side walls.
+func _extrude(points: Array, top: float, depth: float) -> ArrayMesh:
+	var pts := PackedVector2Array()
+	for p in points:
+		pts.append(Vector2(p[0], p[1]))
+	var st := SurfaceTool.new()
+	st.begin(Mesh.PRIMITIVE_TRIANGLES)
+	var tri := Geometry2D.triangulate_polygon(pts)
+	for i in range(0, tri.size(), 3):
+		for k in [0, 2, 1]:
+			var p := pts[tri[i + k]]
+			st.add_vertex(Vector3(p.x, top, p.y))
+	for i in pts.size():
+		var a := pts[i]
+		var b := pts[(i + 1) % pts.size()]
+		var a0 := Vector3(a.x, top, a.y)
+		var b0 := Vector3(b.x, top, b.y)
+		var a1 := a0 - Vector3(0, depth, 0)
+		var b1 := b0 - Vector3(0, depth, 0)
+		for v in [a0, b0, b1, a0, b1, a1]:
+			st.add_vertex(v)
+	st.generate_normals()
+	return st.commit()
+
+func _v(a: Array) -> Vector3:
+	return Vector3(a[0], a[1], a[2])

package/library/skills/painted-25d-world/_building-blocks/capture_paint_view.gd

@@ -0,0 +1,32 @@
+extends Node
+## Renders a location's plain, lit blockout through its PaintCamera into a PNG of an exact size, then quits.
+## Make a scene with only this node, set `level` (the world scene) and `camera_path`, and play it. The PNG is the
+## structure image for the paint-over. Keep size at the painting's aspect (16:9). Needs a rendering run (the
+## editor's play, or a windowed run); a --headless run renders nothing.
+
+@export var level: PackedScene
+@export var size := Vector2i(2048, 1152)
+@export var out_path := "res://painted/blockout.png"
+## The location's paint camera inside `level`.
+@export var camera_path := "Village/PaintCamera"
+
+func _ready() -> void:
+	var vp := SubViewport.new()
+	vp.size = size
+	vp.render_target_update_mode = SubViewport.UPDATE_ALWAYS
+	vp.own_world_3d = true
+	add_child(vp)
+	var lvl := level.instantiate()
+	# no painting: painted_world.gd then shows the plain blockout, lit, through the paint camera
+	for node in lvl.find_children("*", "Node3D", true, false):
+		if "paint" in node:
+			node.paint = null
+	vp.add_child(lvl)
+	await get_tree().process_frame
+	(lvl.get_node(camera_path) as Camera3D).make_current()
+	for i in 4:
+		await RenderingServer.frame_post_draw
+	var img := vp.get_texture().get_image()
+	img.save_png(out_path)
+	print("PAINT_VIEW_SAVED ", ProjectSettings.globalize_path(out_path), " ", img.get_size())
+	get_tree().quit()

package/library/skills/painted-25d-world/_building-blocks/paint_projection.gdshader

@@ -0,0 +1,23 @@
+// Projects one painted picture onto every mesh that uses this material, from the fixed paint camera.
+// UV = where the surface point sits in the paint camera's orthographic frame, so no mesh needs UVs.
+// Unshaded: the painting already holds all the light. Keep the scene tonemap Linear, exposure 1.
+shader_type spatial;
+render_mode unshaded, cull_disabled, shadows_disabled;
+
+uniform sampler2D paint : source_color, filter_linear_mipmap_anisotropic, repeat_disable;
+uniform vec3 paint_origin;      // PaintCamera.global_position
+uniform vec3 paint_right;       // PaintCamera.global_basis.x
+uniform vec3 paint_up;          // PaintCamera.global_basis.y
+uniform vec2 paint_size;        // frame width, height in metres (Camera3D.size with KEEP_WIDTH, height = width * H / W)
+
+varying vec3 world_pos;
+
+void vertex() {
+	world_pos = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
+}
+
+void fragment() {
+	vec3 d = world_pos - paint_origin;
+	vec2 uv = vec2(dot(d, paint_right) / paint_size.x + 0.5, 0.5 - dot(d, paint_up) / paint_size.y);
+	ALBEDO = texture(paint, uv).rgb;
+}

package/library/skills/painted-25d-world/_building-blocks/paintcam_check.gd

@@ -0,0 +1,25 @@
+extends Node
+## Verify the projection: renders the painted world through a location's PaintCamera and saves the PNG. It must
+## match the painting (compare them, or overlay). `summer_screenshot` of the scene cannot do this when the blockout
+## is built by a script: scene renders do not run scripts. Make a scene with only this node and play it.
+
+@export var level: PackedScene
+@export var camera_path := "Village/PaintCamera"
+@export var size := Vector2i(2048, 1152)
+@export var out_path := "res://painted/paintcam_check.png"
+
+func _ready() -> void:
+	var vp := SubViewport.new()
+	vp.size = size
+	vp.render_target_update_mode = SubViewport.UPDATE_ALWAYS
+	vp.own_world_3d = true
+	add_child(vp)
+	var lvl := level.instantiate()
+	vp.add_child(lvl)
+	await get_tree().process_frame
+	(lvl.get_node(camera_path) as Camera3D).make_current()
+	for i in 6:
+		await RenderingServer.frame_post_draw
+	vp.get_texture().get_image().save_png(out_path)
+	print("PAINTCAM_SAVED ", ProjectSettings.globalize_path(out_path))
+	get_tree().quit()

package/library/skills/painted-25d-world/_building-blocks/painted_door.gd

@@ -0,0 +1,17 @@
+extends Area3D
+## A door between painted locations. When the player walks in, the world moves them into `to` at `spawn`.
+## Put `spawn` (a Marker3D) inside the target room or outside the target door, clear of that room's own door
+## trigger, or the player bounces straight back.
+
+@export var to: NodePath
+@export var spawn: NodePath
+
+func _ready() -> void:
+	body_entered.connect(_on_body_entered)
+
+func _on_body_entered(body: Node) -> void:
+	var world := get_parent()
+	while world != null and not world.has_method("go"):
+		world = world.get_parent()
+	if world != null and body == world.player:
+		world.go(get_node(to), (get_node(spawn) as Node3D).global_position)

package/library/skills/painted-25d-world/_building-blocks/painted_location.gd

@@ -0,0 +1,56 @@
+extends Node3D
+## One painted frame: a PaintCamera, the blockout under Painted, and the paint-over projected onto it from
+## that camera. With no `paint` set it shows the plain blockout (play it and capture that frame for the paint-over).
+## Children: PaintCamera (Camera3D, orthographic, KEEP_WIDTH), Painted (Node3D with every block).
+
+const PROJECTION := preload("res://painted/paint_projection.gdshader")
+
+## The paint-over for this frame (4K, imported lossless).
+@export var paint: Texture2D
+## Rooms: frame the whole painting like a stage. Outdoors: follow the player.
+@export var frame_whole := false
+
+@onready var paint_cam: Camera3D = $PaintCamera
+var paint_size := Vector2.ZERO
+## Average colour along the painting's border: the clear colour while the player is here.
+var edge_color := Color(0.1, 0.1, 0.1)
+
+func _ready() -> void:
+	if paint == null:
+		return
+	paint_size = Vector2(paint_cam.size, paint_cam.size * paint.get_height() / float(paint.get_width()))
+	var mat := ShaderMaterial.new()
+	mat.shader = PROJECTION
+	mat.set_shader_parameter("paint", paint)
+	mat.set_shader_parameter("paint_origin", paint_cam.global_position)
+	mat.set_shader_parameter("paint_right", paint_cam.global_basis.x)
+	mat.set_shader_parameter("paint_up", paint_cam.global_basis.y)
+	mat.set_shader_parameter("paint_size", paint_size)
+	for mi in $Painted.find_children("*", "MeshInstance3D", true, false):
+		# door slabs and steps stick out of the walls in the blockout; the painting already shows them
+		if mi.name.containsn("door") or mi.name.containsn("steps"):
+			mi.visible = false
+			continue
+		(mi as MeshInstance3D).material_override = mat
+		(mi as MeshInstance3D).cast_shadow = GeometryInstance3D.SHADOW_CASTING_SETTING_OFF
+	edge_color = _edge_color()
+
+## Where p sits in this frame's picture plane, in metres from the frame centre.
+func plane(p: Vector3) -> Vector2:
+	var d := p - paint_cam.global_position
+	return Vector2(d.dot(paint_cam.global_basis.x), d.dot(paint_cam.global_basis.y))
+
+func _edge_color() -> Color:
+	var img := paint.get_image()
+	if img == null:
+		return edge_color
+	if img.is_compressed():
+		img.decompress()
+	var w := img.get_width() - 1
+	var h := img.get_height() - 1
+	var sum := Color(0, 0, 0, 0)
+	for i in 32:
+		var t := i / 31.0
+		for p in [Vector2i(int(t * w), 0), Vector2i(int(t * w), h), Vector2i(0, int(t * h)), Vector2i(w, int(t * h))]:
+			sum += img.get_pixelv(p)
+	return Color(sum.r / 128.0, sum.g / 128.0, sum.b / 128.0)

package/library/skills/painted-25d-world/_building-blocks/painted_player.gd

@@ -0,0 +1,125 @@
+extends CharacterBody3D
+## Sprite character on a capsule. Input moves in screen directions: up = away from the camera on the ground.
+## The sprite is a vertical Y-billboard, stretched by 1 / cos(camera pitch) so it reads at full height from the
+## tilted camera. Eight facings picked by 45 degree sectors; a missing diagonal falls back to its side row.
+## The gait depends on the game type. Cozy, exploration and RPG games walk by default (about 1.8 m/s, walk cycle)
+## and run on Shift (about 4 m/s, run cycle); action games may run by default (move_speed about 4.2). The cycle is
+## chosen by speed (run cycle from `run_cycle_from`), and speed_scale = speed / the cycle's natural speed, so the
+## feet never slide. Never play the run cycle for the default gait of a cozy game.
+## Sheet: one row per animation (idle_down, walk_up_left, run_right, ...), fixed cell size. The json beside it:
+## {"cell_w", "cell_h", "frames", "rows", "fps": {"idle": 6, "walk": 10, "run": 14}, "height_m": 1.8,
+##  "stride_m": {"walk": 0.94, "run": 1.68}, "cycles_per_s": {"walk": 1.25, "run": 1.75}}
+## (stride_m = metres per cycle at height_m).
+
+const DIRS := ["right", "up_right", "up", "up_left", "left", "down_left", "down", "down_right"]
+
+@export var sheet: Texture2D
+@export_file("*.json") var sheet_json := ""
+## About door height / 1.15: 2.15 m next to 2.5 m doors.
+@export var height_m := 2.15
+## m/s, the default gait. Cozy / exploration / RPG: 1.8 (walk cycle). Action: about 4.2 (run cycle).
+@export var move_speed := 1.8
+## m/s while Shift is held (run cycle). Cozy: 4.0. Action: up to 1.8x the run cycle's natural speed.
+@export var sprint_speed := 4.0
+## m/s from which the run cycle plays instead of the walk cycle.
+@export var run_cycle_from := 3.0
+## Tests and agents drive the character with this instead of keys (x = screen right, y = screen up):
+## length up to 1 is the default gait, above 1 sprints.
+var input_override := Vector2.ZERO
+var cam_basis := Basis()
+var sprite: AnimatedSprite3D
+var facing := "down"
+var meta: Dictionary
+
+func _ready() -> void:
+	meta = JSON.parse_string(FileAccess.get_file_as_string(sheet_json))
+	var shape := CollisionShape3D.new()
+	var cap := CapsuleShape3D.new()
+	cap.radius = 0.4
+	cap.height = height_m - 0.2
+	shape.shape = cap
+	shape.position.y = cap.height / 2.0
+	add_child(shape)
+	sprite = AnimatedSprite3D.new()
+	sprite.sprite_frames = _frames()
+	sprite.billboard = BaseMaterial3D.BILLBOARD_FIXED_Y
+	sprite.shaded = false
+	sprite.alpha_cut = SpriteBase3D.ALPHA_CUT_DISCARD   # writes depth, so painted walls hide the character
+	add_child(sprite)
+
+## Called by the world with the paint camera's basis.
+func setup(view_basis: Basis) -> void:
+	cam_basis = view_basis
+	var pitch := asin(clampf(-view_basis.z.y, -1.0, 1.0))
+	var h := height_m / cos(pitch)
+	sprite.pixel_size = h / float(meta.cell_h)
+	sprite.position.y = h / 2.0
+	_play("idle", 0.0)
+
+func _frames() -> SpriteFrames:
+	var sf := SpriteFrames.new()
+	sf.remove_animation("default")
+	for r in meta.rows.size():
+		var anim: String = meta.rows[r]
+		sf.add_animation(anim)
+		sf.set_animation_speed(anim, _fps(anim.get_slice("_", 0)))
+		for c in int(meta.frames):
+			var at := AtlasTexture.new()
+			at.atlas = sheet
+			at.region = Rect2(c * meta.cell_w, r * meta.cell_h, meta.cell_w, meta.cell_h)
+			sf.add_frame(anim, at)
+	return sf
+
+## fps in the json: one number, or a dictionary by kind ("walk").
+func _fps(kind: String) -> float:
+	var fps = meta.get("fps", 8.0)
+	if fps is Dictionary:
+		return float(fps.get(kind, 8.0))
+	return float(fps)
+
+## Ground speed (m/s) at which this kind's cycle keeps the feet still: stride (scaled to this height) x cycles/s.
+## Without measurements: the generated cycles' typical values (walk 0.57, run 1.63 body heights per second).
+func natural_speed(kind: String) -> float:
+	var stride = meta.get("stride_m", {}).get(kind)
+	if stride == null:
+		return height_m * (1.63 if kind == "run" else 0.57)
+	var cycles = meta.get("cycles_per_s", {}).get(kind, _fps(kind) / float(meta.frames))
+	return float(stride) * height_m / float(meta.get("height_m", height_m)) * float(cycles)
+
+## The cycle for a ground speed: the walk cycle below `run_cycle_from`, the run cycle from there.
+func cycle_for(speed: float) -> String:
+	if not sprite.sprite_frames.has_animation("run_down") or speed < run_cycle_from:
+		return "walk"
+	return "run"
+
+func _play(kind: String, speed: float) -> void:
+	var side := "left" if facing.ends_with("left") else ("right" if facing.ends_with("right") else facing)
+	for anim in [kind + "_" + facing, kind + "_" + side, kind + "_down"]:
+		if sprite.sprite_frames.has_animation(anim):
+			sprite.play(anim)
+			break
+	sprite.speed_scale = 1.0 if kind == "idle" else clampf(speed / natural_speed(kind), 0.25, 4.0)
+
+func _physics_process(delta: float) -> void:
+	var v := input_override
+	var speed := move_speed
+	if v != Vector2.ZERO:
+		speed = sprint_speed if v.length() > 1.05 else move_speed
+	else:
+		v = Input.get_vector("ui_left", "ui_right", "ui_down", "ui_up")
+		if Input.is_key_pressed(KEY_SHIFT):
+			speed = sprint_speed
+	if v.length() < 0.1:
+		speed = 0.0
+	var right := Vector3(cam_basis.x.x, 0, cam_basis.x.z).normalized()
+	var far := Vector3(-cam_basis.z.x, 0, -cam_basis.z.z).normalized()
+	var dir := (right * v.x + far * v.y).normalized()
+	velocity.x = dir.x * speed
+	velocity.z = dir.z * speed
+	velocity.y = 0.0 if is_on_floor() else velocity.y - 20.0 * delta
+	move_and_slide()
+	if speed > 0.0:
+		facing = DIRS[wrapi(roundi(v.angle() / (PI / 4.0)), 0, 8)]
+		_play(cycle_for(speed), speed)
+	else:
+		_play("idle", 0.0)

package/library/skills/painted-25d-world/_building-blocks/painted_world.gd

@@ -0,0 +1,111 @@
+extends Node3D
+## Painted 2.5D world: painted locations (painted_location.gd: Village, Cottage, ...), one player, one game camera.
+## The game camera keeps the paint direction and only moves, so surfaces hidden in a painting stay hidden.
+## Outdoors it shows about `view_width` metres and is clamped inside the painting with the REAL viewport aspect;
+## rooms are framed whole. The clear colour is the current painting's edge colour.
+## Proof shots from the real game window: run with `-- --shots=<dir>`; the player walks and runs through
+## `shot_plan`, each step saves a JPG, then the game quits. Add your door walks to shot_plan.
+
+@export var player_path: NodePath
+@export var start_location: NodePath
+## Metres across the screen outdoors: about 16 m, 7-8 hero heights.
+@export var view_width := 16.0
+## [name, screen input (x right, y up; length > 1 runs), seconds, "follow" or "full"]
+@export var shot_plan: Array = [
+	["start", Vector2.ZERO, 0.6, "follow"],
+	["walk", Vector2(-1, 1).normalized(), 1.6, "follow"],
+	["run", Vector2(-1.8, -0.6), 0.9, "follow"],
+	["full_frame", Vector2.ZERO, 0.4, "full"],
+]
+
+@onready var game_cam: Camera3D = $GameCamera
+@onready var player: CharacterBody3D = get_node(player_path)
+var location: Node3D
+var full_view := false
+
+func _ready() -> void:
+	location = get_node(start_location)
+	if location.paint == null:
+		_capture_mode()
+		return
+	game_cam.projection = Camera3D.PROJECTION_ORTHOGONAL
+	game_cam.keep_aspect = Camera3D.KEEP_WIDTH
+	game_cam.far = location.paint_cam.far
+	game_cam.make_current()
+	_enter(location)
+	if player.has_method("setup"):
+		player.setup(location.paint_cam.global_basis)
+	for arg in OS.get_cmdline_user_args():
+		if arg.begins_with("--shots="):
+			_take_shots.call_deferred(arg.trim_prefix("--shots="))
+
+## No painting yet: show the plain blockout through the paint camera, lit so its faces read for the painter
+## (the painted game itself stays unshaded). Play it and capture the frame for the paint-over.
+func _capture_mode() -> void:
+	location.paint_cam.make_current()
+	set_physics_process(false)
+	if player.has_method("setup"):
+		player.setup(location.paint_cam.global_basis)
+	var sun := DirectionalLight3D.new()
+	sun.rotation_degrees = Vector3(-50, 20, 0)
+	sun.light_energy = 1.2
+	add_child(sun)
+	var env := WorldEnvironment.new()
+	env.environment = Environment.new()
+	env.environment.background_mode = Environment.BG_COLOR
+	env.environment.background_color = Color(0.1, 0.1, 0.12)
+	env.environment.ambient_light_source = Environment.AMBIENT_SOURCE_COLOR
+	env.environment.ambient_light_color = Color.WHITE
+	env.environment.ambient_light_energy = 0.55
+	add_child(env)
+
+## Doors call this: move the player into another painted location.
+func go(to: Node3D, spawn: Vector3) -> void:
+	location = to
+	player.global_position = spawn
+	player.velocity = Vector3.ZERO
+	_enter(to)
+
+func _enter(loc: Node3D) -> void:
+	game_cam.global_basis = loc.paint_cam.global_basis
+	RenderingServer.set_default_clear_color(loc.edge_color)
+	_physics_process(0.0)
+
+## Viewport height / width. The editor's game view and phones are not 16:9.
+func _aspect() -> float:
+	var vp := get_viewport().get_visible_rect().size
+	return vp.y / vp.x if vp.x > 0 else 9.0 / 16.0
+
+func _physics_process(_delta: float) -> void:
+	var size: Vector2 = location.paint_size
+	var aspect := _aspect()
+	var fit := minf(size.x, size.y / aspect)   # the widest view that stays inside the painting
+	var cam_basis: Basis = location.paint_cam.global_basis
+	if location.frame_whole or full_view:
+		game_cam.size = fit
+		game_cam.global_position = location.paint_cam.global_position
+		return
+	# keep the player inside the painting (move along the ground, not through the air)
+	var half := size / 2.0 - Vector2(1.0, 2.0)
+	var c: Vector2 = location.plane(player.global_position)
+	var clamped := c.clamp(-half, half)
+	if clamped != c:
+		var fwd := -cam_basis.z
+		var far := Vector3(fwd.x, 0, fwd.z).normalized()
+		player.global_position += cam_basis.x * (clamped.x - c.x) + far * (clamped.y - c.y) / far.dot(cam_basis.y)
+	game_cam.size = minf(view_width, fit)
+	var view := Vector2(game_cam.size, game_cam.size * aspect)
+	var t: Vector2 = location.plane(player.global_position + Vector3(0, 1, 0)).clamp(-(size - view) / 2.0, (size - view) / 2.0)
+	game_cam.global_position = location.paint_cam.global_position + cam_basis.x * t.x + cam_basis.y * t.y
+
+func _take_shots(dir: String) -> void:
+	DirAccess.make_dir_recursive_absolute(dir)
+	for step in shot_plan:
+		full_view = step[3] == "full"
+		player.input_override = step[1]
+		await get_tree().create_timer(step[2]).timeout
+		await RenderingServer.frame_post_draw
+		get_viewport().get_texture().get_image().save_jpg(dir.path_join(str(step[0]) + ".jpg"), 0.92)
+	player.input_override = Vector2.ZERO
+	full_view = false
+	get_tree().quit()

package/library/skills/painted-25d-world/_building-blocks/tools/cam.py

@@ -0,0 +1,57 @@
+"""Paint camera math without the engine: concept pixels <-> world positions.
+Matches a Godot PaintCamera with rotation_degrees (-ELEV, AZIM, 0), orthographic, KEEP_WIDTH, centred on C.
+Settings (environment): PAINT_W frame width in metres (40), PAINT_ELEV degrees down (30), PAINT_AZIM (45),
+PAINT_C frame centre "x,y,z" (0,0,0), PAINT_IMG image size "2048,1152".
+usage: python3 cam.py <height_m> <px,py> [<px,py> ...]   world point on the plane y = height under each pixel
+       (bottom corners of walls at height 0 give a footprint; read a ridge at the eave height to place a roof)"""
+import math
+import os
+
+W = float(os.environ.get("PAINT_W", "40"))
+IMG = tuple(int(v) for v in os.environ.get("PAINT_IMG", "2048,1152").split(","))
+H = W * IMG[1] / IMG[0]
+C = tuple(float(v) for v in os.environ.get("PAINT_C", "0,0,0").split(","))
+PITCH = math.radians(-float(os.environ.get("PAINT_ELEV", "30")))
+YAW = math.radians(float(os.environ.get("PAINT_AZIM", "45")))
+
+
+def ry(v, a):
+    x, y, z = v
+    return (x * math.cos(a) + z * math.sin(a), y, -x * math.sin(a) + z * math.cos(a))
+
+
+def rx(v, a):
+    x, y, z = v
+    return (x, y * math.cos(a) - z * math.sin(a), y * math.sin(a) + z * math.cos(a))
+
+
+RIGHT = ry(rx((1, 0, 0), PITCH), YAW)
+UP = ry(rx((0, 1, 0), PITCH), YAW)
+FWD = ry(rx((0, 0, -1), PITCH), YAW)
+
+
+def dot(a, b):
+    return sum(i * j for i, j in zip(a, b))
+
+
+def to_px(w):
+    """World point -> pixel in the painting."""
+    d = tuple(w[i] - C[i] for i in range(3))
+    return ((dot(d, RIGHT) / W + 0.5) * IMG[0], (0.5 - dot(d, UP) / H) * IMG[1])
+
+
+def to_ground(px, py, h=0.0):
+    """Pixel -> the world point on the plane y = h that the pixel shows."""
+    a = (px / IMG[0] - 0.5) * W
+    b = (0.5 - py / IMG[1]) * H
+    p0 = tuple(C[i] + a * RIGHT[i] + b * UP[i] for i in range(3))
+    t = (h - p0[1]) / FWD[1]
+    return tuple(round(p0[i] + t * FWD[i], 2) for i in range(3))
+
+
+if __name__ == "__main__":
+    import sys
+    h = float(sys.argv[1])
+    for s in sys.argv[2:]:
+        x, y = map(float, s.split(","))
+        print(s, "->", to_ground(x, y, h))