PIXELPUNK JOURNAL / CHAPTER 06
Editorial evidence captured 23 September 2026.
These are historical project notes. Status and next-step instructions in these excerpts belong to their original development session.
Performance and test results quoted here are from those sessions, not tests performed by the journal build.

========================================================================
docs/forum-post-technical.md | original lines 31–55
========================================================================
- `--verify` drives the real editing handlers through a scripted session and checks the document after each step.
- `--benchmark` builds a dense town and reports frame times and draw calls.
- `--drag=<script>` is the newest: it replays handle drags, wall strokes, terrain strokes, slider scrubs, undo and redo through the editor's own input handlers and records, per step, the handler time, the following frame's wall-clock time (so deferred work can't hide), the release rebuild, and a hash of the resulting scene state so replays are provably identical. `--filmstrip=<ms list>` grabs frames at listed times after an edit.

Twelve fixed facade views are also kept as an audit set from the earlier work on facades at scale.

## What the last week has been about: feel

The engine reached the point where the geometry was right but the *hand* was wrong. Three problems in particular:

1. **Drags were laggy.** Every handle step rebuilt the inspector, the handle meshes and validated the whole scene. A height drag on a Harbour house cost about 25 ms per step at the median, and the release rebuilt a six-house cluster in one 145 ms frame.
2. **Everything popped.** Placing a house showed a finished house on the next frame.
3. **The editor said no.** Put a house past the edge and you got a red ghost and a refusal; ask for a bridge with mismatched ends and you got a message.

The harness above was built first, so the rest could be measured rather than felt. Then:

- **Direct manipulation.** Drags validate only the affected neighbourhood, freehand walls and neon drag live, sliders preview live and commit once on release, and the camera left the undo history. Harbour height drag went from 25.5 ms to 14.9 ms median (p95 25 ms, so the 16 ms p95 target is not met yet, and the remaining cost centres are recorded rather than the measurement softened). Placed parts stay selected; click-drag moves, Alt-drag duplicates; magnets snap to edges, ridges, wall ends and 0.5 m alignments with a visible guide line; roofs can be shaped by hand with a curve knob and ridge-end knobs; walls take their corners from stroke speed.
- **Build animations.** A per-vertex `CUSTOM0` channel carries a spawn time and stagger order, so walls reveal upward course by course with a toothed brick edge, roofs pop with a small squash, removal sinks over a quarter second, and only *new* geometry animates: a resize grows just the new storey. Settled builds carry no animation data at all and are byte-identical to a static build, which the tests check. Undo and redo replay at 2.5× speed. As a side effect the release rebuild is now spread through the animation instead of blocking one frame: Harbour release 200 → 34 ms, the dense fixture 2,153 → 291 ms.
- **Adapt instead of refuse.** Placement now goes through a candidate-and-score mechanism with the candidates as data: a house past the edge slides inside, a handle drag clamps continuously to the nearest valid size, a connection picks bridge, walkway, stairs or ladder from its rise over run, and what used to be a red refusal is a teal ghost and a one-line hint. Existing scenes must draw exactly as before, and the six-view diff enforces that.

## What's next

The remaining work, in order: terrain chemistry (stepping stones, terrain-conforming steps, soft path edges, shores, gates and arches in freehand walls); bridges that read the ground and towers as first-class parts with cut shells; a composition library so generated starter scenes have a focal point and breathing room; clutter and foliage that respond to what's around them; procedural ambient sound and a layered score; a live time-of-day slider with dusk and dawn, smoke and height fog; creatures (ducks, pigeons, sparrows, a cat, fireflies and moths, runtime-only, 30 at most, with a 0.5 ms frame budget); four demonstration starters; and finally a softer daylight look and a camera profile as non-default options.

Every stage leaves the same evidence: test logs, before/after captures, a handoff entry with the numbers, and the six journey views re-captured. The engine is 17,500 lines of GDScript across 33 scripts; the tests are another 8,500. If people are interested I can go deeper on the cluster wall generation, the light pool, or the drag harness in a follow-up.

========================================================================
scripts/edit_history.gd | original lines 1–40
========================================================================
extends RefCounted
class_name EditHistory

const LIMIT = 64
var past: Array = []
var future: Array = []
var pending: Dictionary = {}

func begin(state: DioramaState) -> void:
	# History records the scene, not the point of view (DioramaState.history_snapshot): moving the
	# camera makes no undo step, and undoing an edit does not throw the view back (A1a).
	if pending.is_empty(): pending = state.history_snapshot()

func commit(state: DioramaState, label: String) -> bool:
	if pending.is_empty(): return false
	var before = pending
	pending = {}
	var after = state.history_snapshot()
	if before == after: return false
	past.append({"before": before, "after": after, "label": label})
	if past.size() > LIMIT: past.pop_front()
	future.clear()
	return true

func cancel(state: DioramaState) -> void:
	if not pending.is_empty(): state.restore(pending)
	pending = {}

func undo(state: DioramaState) -> String:
	if past.is_empty(): return "Nothing to undo"
	var command = past.pop_back()
	future.append(command)
	state.restore(command.before)
	return "Undid " + command.label

func redo(state: DioramaState) -> String:
	if future.is_empty(): return "Nothing to redo"
	var command = future.pop_back()
	past.append(command)
	state.restore(command.after)

========================================================================
scripts/build_anim.gd | original lines 1–53
========================================================================
extends RefCounted
class_name BuildAnim

# Package A2, watch it being built. The schedule every instanced brick and tile is built on, and
# the curve each piece grows along. The shader half is the vertex stage of shaders/surface.gdshader,
# which reads a piece's (start, duration) out of its MultiMesh custom data and the clock out of the
# `build_time` uniform; tests/test_build_anim.gd holds the two halves together.
#
# Order, coarse to fine (plan rule 2): the massing has the first slot, then openings, roofs and
# trims, and only then the pieces, course by course up the cluster: a piece's delay is its height
# above the lowest piece of its cluster, at RISE seconds a metre, which sends bricks up each wall a
# course at a time and, because the eave is above the wall, tiles row by row from the eave to the
# ridge in the same sweep. A seeded jitter breaks up the rhythm; its spread is under one course
# and under one row of tiles, so it never changes the order. The jitter keys on the piece's own
# position, so the same wall always builds with the same rhythm (rule 2, deterministic replays).
#
# Part a animates every piece of a rebuilt cluster; part b keys pieces by position so only new
# geometry animates, and part c makes undo and redo replay faster and settles the captures.
#
# Part b, the cluster meshes. Every piece a generator appends (a box, a face, a loft section) is
# keyed by its material and where it stands (piece_key), and each full build is diffed against the
# tops the same cluster recorded last time (diff): a piece with its old key and top is settled and
# carries a zero gate; a new piece reveals upward from its own bottom; a piece that has grown
# reveals from its old top. One line sweeps up the cluster from the lowest animating piece at
# SWEEP metres a second, with an edge toothed by the masonry grid (tooth); roofs pop about their
# bottom when the line reaches them, trims a little after. The per-vertex (start, duration, y0,
# mode) goes into CUSTOM0 (shaders/build_anim.gdshaderinc reads it). Bricks and tiles are keyed by
# their origin the same way (schedule_new), so a raise animates only the new courses. Removal
# sinks and shrinks the old mesh for REMOVE seconds (WorldView.dying), props scale in and trees
# sway (prop_transform), and lamps flicker on from their MultiMesh custom data.

const KINDS = ["brick","tile"]
# Every material whose shader reads the build clock: told the time once a frame while animating.
const MATERIALS = ["brick","tile","wood","metal","stone","stone_uv","plaster","plaster_uv","window","window_cyan","window_pink","pink","cyan","warm","pool","plain","interior","glass"]
# The reveal line climbs at the pace the bricks do (1/RISE), so the bricks trail it by BRICKS_START.
const SWEEP = 6.25
# The reveal runs on past a piece's top by this, so the last teeth clear it.
const TOOTH = 0.68
# A roof pops (grows about its bottom on the piece curve) over this, a trim this much later.
const POP = 0.30
const TRIM_LAG = 0.10
# A removed cluster sinks this far and shrinks to nothing over REMOVE seconds.
const REMOVE = 0.25
const SINK = 0.35
# A prop grows over GROW seconds; a tree then sways for SWAY seconds more.
const GROW = 0.35
const SWAY = 1.2
const SWAY_ANGLE = 0.06
# A lamp flickers for this long after it is placed.
const FLICKER = 0.7
# Piece modes: the fourth float of CUSTOM0 and the phase a generator sets on the batch.
const MODE_REVEAL = 0
const MODE_POP = 1