Birdoggydog's Builds

Building rivers and waterfalls from a waterways table

Fri, 09 Oct 2026 08:00:00 -0700

I rebuilt Blobber’s island as a 10.24 km square by retuning the generator’s settings. Its rivers, lakes and waterfalls are now built from a table of 4 m curves that the generator writes. The stand-in Tower is a building, and every file of the project sits under one folder. The work is done by AI coding agents that I direct.

Retuning the generator for a 10 km square

The Wishbone, the island the game is set on, is a 10.24 km square with 47.8 square km of land. The first build was 16.4 km a side with 121.

The island I built first, the one I meant to build, and Skyrim's land as a square.

I’d read Skyrim’s 16 square miles as square km, so the first island had three Skyrims of land.

The island is one JSON file, tools/worldgen/islands/wishbone.json, with positions in units, 32 to a side. A variant is a block laid over the base file, and it can now hold a world block, so wishbone.small builds at its own size by name. A smaller size alone only shrinks the island (a unit goes from 512 m to 320 m), so the variant changes the land’s settings too:

Setting	16 km variant	10 km variant
`world.size_m`, `cell_m`	16,384 and 16	10,240 and 8
Grid, regions of 512 m	1,024 cells, 32 a side	1,280 cells, 20 a side
`tectonics.top_m`	950	430, between held summits
`base_uplift`	0.04	0.015
`range_sharpness`	2.3	3.0
`half_width` of the Long Arm, the Arch, the Thin Arm (units)	4.4, 3.4, 1.9	3.2, 2.2, 1.3
`erosion.hillslope_m2`	80,000	50,000
`floodplain.min_km2`, `reach_m`	0.35, 130	0.15, 90
`coast_plain_m`	500	400
`story.snow_line_m`	none	600 north, 520 south

Erosion alone now leaves ranges 430 m high. Four summits stand above them as held floors: tectonics.py writes a least height for each cell, and erosion may not cut below it. A summit is a horn with peak_m at the middle, faces falling at 47 degrees, and ridges along two compass bearings falling at 27 degrees with a level top 56 m wide to walk on. Below hold_above_m a scree skirt runs down at 39 degrees to the eroded ground. Erosion rescales the land so that its highest point is top_m, and it now measures only cells with no floor. The Cleaver is asked for at 1,065 m and stands at 1,061. The old island topped out at 936.

The summits read as drawn, not eroded: the faces are even and each ridge is a ramp.

The crimson is the meat. The biomes are stand-ins, and the map says so.

Snow follows the hand-drawn line. A stand-in climate counts a ridge as 50 m higher than it is, so snow runs along the ridges. Snow country went from 0.27 to 2.1 square km.

Writing the rivers out as a waterways table

The generator’s new last step writes tables/waterways.json: every reach of river as a curve with a point every 4 m, every lake as a polygon, and every fall with its place along its reach.

The table as the generator draws it. Most of the lines are creeks under 2 m wide.

Until now a river was a line of cell centres with one width for its stream order, and a lake was a set of cells. The water faults left the day before were put down to that.

The hydrology step already adds up the land draining through each cell, and a reach is the channel between two joins. The new step (tools/worldgen/waterways.py) puts a uniform Catmull-Rom spline through each reach’s points, samples it every 4 m and takes a running minimum of the height, so water never runs uphill. At each point:

discharge is 0.42 * (km2 * 60) ^ 0.69 cubic metres a second, from the land draining to that point (60 is area_scale: the island stands for a larger country)
width is 1.5 * Q ^ 0.7, held between 0.8 and 40 m
depth is 0.25 * Q ^ 0.4, held between 0.1 and 3 m

A reach into the sea gets one more point out on the water at height 0. A reach into a lake ends at the lake’s level. A lake’s outline is its cells’ outer edges traced, with every corner cut twice.

This is reach 304, a spring-fed creek, with its line cut to three points and the fields put in reading order. A point is x, y, height, width, depth and discharge, in metres from the map’s north-west corner:

{"id": 304, "order": 1, "kind": "creek", "length_m": 88.0,
 "from": {"kind": "spring", "at": [3588.0, 6868.0, 261.15]},
 "to": {"kind": "lake", "id": 1, "at": [3676.0, 6868.0, 5.49]},
 "line": [[3588.0, 6868.0, 261.15, 1.39, 0.24, 0.893],
 [3592.0, 6868.0, 259.11, 1.39, 0.24, 0.894],
 [3596.0, 6868.0, 257.04, 1.39, 0.24, 0.894]]}

A lake has level_m, area_ha, max_depth_m, outline, holes, inflows and outflow. A fall has lip and foot as points, drop_m, run_m, why (“a step in schist”) and along_m, the distance down its reach to the lip. The table also lists confluences and mouths. This island’s holds 383 reaches, 5 lakes and 26 falls.

Cutting beds and laying river sheets from the table

The terrain painter cuts every river’s bed into the heights and writes the water’s mesh data in the same pass, so the game fits nothing to the terrain while it runs.

world/experiments/wishbone/water_ways.py joins reaches into chains: at each confluence the wider inflow runs on and the others end there. A chain is resampled every 2 m. Each point gets a water surface (0.3 m under the table’s height, never rising), half the bed’s width, and a depth.

The terrain has a vertex every metre, and each vertex within 26 m of a chain takes its shape from the nearest point of that chain. Inside the bed the ground is set to an absolute height, the surface less the depth. The banks rise over 0.8 + 1.2 * depth metres to a lip 0.35 m above the water. Past the lip the ground may not stand above a line rising 0.6 m a metre (a cut) or below one falling 0.5 m a metre (a levee).

Each chain is then written as one ribbon, five vertices to a section: the middle line, an edge in each bank, and one between on each side. A section is 27 floats in rivers.sections.f32: the five positions, the across direction, and values for the shader. An index, rivers.json, cuts the ribbon into chunks of 64 sections (128 m) that share the section where they meet, so a river is one sheet from spring to mouth.

In the game, world/experiments/explore/river_sheets.gd builds a chunk as an ArrayMesh when the party is within 520 m and the terrain under it is loaded, and frees it beyond 660 m. It spends at most 3 ms a frame on this.

Why were the waterfalls striped?

A waterfall is now a soft fall into a ragged pool with mist, and a river runs into its lake with no gap.

My snapshot of a bad waterfall, and the same view after.

The stripes came from the ribbon’s length. A section’s distance along the stream went to the shader as UV.y, measured on the map. A face that drops 20 m in 2 m of map got 2 m of pattern, stretched tenfold down the drop. The length is now measured down the slope, and a point goes into every 2.5 m of drop wherever the surface falls more than 3 m between two points, so a face has vertices.

The speckle below every fall was in the game’s water shader (world/water.gdshader), which slid the pattern like this:

	float speed = flow_speed * (1.0 + 3.0 * steep);
	vec2 running = vec2(UV.x, UV.y - TIME * speed) * vec2(0.5, mix(0.26, 0.08, fall));

steep changes from vertex to vertex. Two points a metre apart are offset by TIME times the difference in their speeds, which grows every second. After a few minutes the pattern below a fall is packed into bars a pixel wide.

River sheets now have their own shader, river_sheet.gdshader, and UV.y holds seconds: how long the water has been running when it reaches that section. The painter works it out at 1.6 m a second on the flat and four times that straight down:

 true_run = np.hypot(np.diff(chain.s), np.diff(chain.w))
 pace = FLOW * (1.0 + 3.0 * 0.5 * (steep[:-1] + steep[1:]))
 packed[:, 20] = np.concatenate([[0.0], np.cumsum(true_run / pace)])

The shader subtracts the clock once, the same amount everywhere, and draws its noise in metres across and ago seconds along:

	// Seconds upstream of now, wrapped so the numbers stay small (the noise repeats unseen).
	float ago = UV.y - mod(TIME, 3600.0);

Fast water covers more metres in each second, so the pattern moves faster there and nothing shears.

Where a river met a lake, there was a bar of dry stones.

The dry bar was two outlines of one lake. The painter smooths each lake’s outline again, and the lake’s bed and water use that. The river’s ribbon still began at the table’s outlet point, which sits on the unsmoothed cells. Now a chain that starts or ends in a lake is carried 34 m in toward the lake’s middle, and a point-in-polygon test against the smoothed outline finds where it crosses the shore. The ribbon is whole to 2.5 m inside the shore and fades out over the next 7.5 m.

A tall fall is still a thin thread on a wide mountainside.

Photographing every fall and river mouth

A survey scene, water_joins.gd, pictures every lake inflow, lake outflow, sea mouth and fall on the island, so that I’m not the one finding faults by flying.

The first ten falls as the survey framed them.

For a join, the camera goes 40 m straight above the shore point. The script walks the stream’s line in 0.4 m steps from 16 m upstream to 10 m out into the still water. It projects each step into the picture with unproject_position and tests five pixels for blue or the pale white of fast water. A run of 1 m or more with no water is counted as dry.

For a fall, the eye stands downstream of the foot by 14 + 0.6 * drop metres and to one side by 6 + 0.15 * drop, and looks at a point 35% of the way from the foot to the lip.

By the survey’s count, lake outflows with a dry stretch went from 3 of 4 to 0 of 4.

Widening the Tower so it can hold a dungeon

The stand-in Tower is five eight-sided tiers, 500 m tall and 240 m across at the ground.

The wider Tower from five places, each with the same view at four times the size.

The first stand-in was a 70 m column. It couldn’t really be a dungeon, and from far away it was a sliver.

tower_stand_in.gd makes each tier from a CylinderMesh with radial_segments = 8. A tier’s radius at its foot is a share of the base’s (1.0, 0.86, 0.72, 0.58, 0.44), and it leans in to 0.9 of that at its top, so each tier stands back from the one below. At 240 m the ground floor is 4.1 hectares and the top one 0.6. F1 steps the width through 120, 180, 240 and 320 m, and F4 the height through 300, 500 and 700 m.

It had to move 244 m. A creek runs 83 m from the middle of the vale, so anything 180 m wide or more stood in it.

A second scene, tower_sight.gd, measures how much of it shows. From an eye 1.7 m over the ground it draws a line to each 5 m of the Tower’s height and tests it against the terrain every 15 m. From the landing across the inner sea, 6.2 km away, 490 m show, 19.6 pixels wide on a picture 1,280 wide. The column was 5.8. From the slipway on the starting island nothing shows at any size: that island’s own ridge is in the way. I haven’t picked the final size yet.

Moving everything into one folder

Every file of the project is under one workspace folder now, and nothing is written anywhere else.

Before and after.

No script holds a location. Each asks a helper, which walks up from its own file to the nearest folder holding Projects, Worktrees, Tools and Tmp. The rule is written in shell, Python and GDScript, one per language the tools use. This is tools/workspace.py, without the last-resort default it ends on:

_PARTS = ("Projects", "Worktrees", "Tools", "Tmp")
_HERE = os.path.dirname(os.path.abspath(__file__))


def _find_root() -> str:
 named = os.environ.get("GAMEDEV_WORKSPACE", "")
 if named:
 return named
 at = os.path.dirname(_HERE)
 while True:
 if all(os.path.isdir(os.path.join(at, part)) for part in _PARTS):
 return at
 up = os.path.dirname(at)
 if up == at:
 break
 at = up

A checker, tools/check_workspace.py, reads every text file git tracks and fails on a line that names another drive, the user profile or the system temp folder. A plain drive-letter pattern also matches the end of a string like "error:\n" (a letter, a colon, a backslash), so the pattern needs a lookahead that rejects n, t and r after the slash.

Git Bash’s /tmp is the user’s temp folder on the system drive, and bash writes here-documents there. The shell helper exports TMPDIR, TMP and TEMP pointing at Tmp/<Project>/scratch, and every wrapper calls it before starting Godot, Python or Blender.

The move is a PowerShell script with a -WhatIf mode. Its order:

Refuse if Godot, Blender or git is running, or a process runs from a folder to be moved.
Rename the tool folders and the main checkout. A rename on one drive happens whole or not at all.
Run git worktree repair: a worktree and the main repository each hold the other’s absolute path.
Move each worktree with git worktree move, and stop if its count of uncommitted files changed.
Copy the old temp folders off the system drive, check each file’s size, delete the originals.
Leave a directory junction at the old checkout. It comes off with cmd /c rmdir: a recursive delete follows it and empties the real checkout.

The script refused at the main checkout, because the session running it was a process inside that folder. I closed every session and ran it by hand.

Setting aside a trial of AI-generated models

I had an agent research an open-source image-to-3D workflow with nothing installed. It gives one fused mesh of about 500,000 triangles with no parts and no rig, and my pipeline builds a creature from named parts on a rig. I set it aside because of the potential licensing issues.

Next: one orc holding a sword that’s its own model.

Generating an island with stream-power erosion for Godot

Thu, 08 Oct 2026 20:00:00 -0700

Blobber has an island: 121 square km of land that a Python generator builds from one JSON file by uplift and stream-power erosion, with 973 river reaches that all drain to the sea. Godot streams it round the party as 512 m Terrain3D regions. I build the game by directing AI coding agents, and this is what they built on 8 October.

Laying out a knowledge base for world building

Three research agents wrote a knowledge base in parallel before any code, and the generator’s design comes from named pages in it.

It is a folder of Markdown outside the game’s repository, <workspace>/Tools/Blobber/kb_world/: 86 notes and 15 folder READMEs as it stands now, about 121,000 words. Fourteen numbered folders run from 00_policy through world generation, engine limits, ground textures, water and case studies of shipped games to 12_plan. INDEX.md maps a question to the file to start at, and an agent greps the rest.

Every file opens with the same front matter, here the erosion note’s:

source_authority: peer-reviewed papers (high); developers' write-ups and repositories (medium)
software: none (method notes); reference code in C++/OpenGL and Python
version: 1
domain: 01_worldgen/erosion
asset_class: terrain
target_engine: Godot 4.7
license: notes are the project's; code licences as listed
confidence: medium (methods high; costs at 64 km are extrapolations and marked so)

00_policy/README.md ranks sources (papers and official documentation high, blogs medium, forum posts low) and licences: MIT code may be ported into the game, a GPL tool may only be run as a separate program. A *.note.md is the research, each claim tied to a URL and its fetch date, or marked “from memory, not fetched”. A folder’s README.md is the conclusion: options in a table, a recommendation, and numbered work items with their dependencies.

A fourth agent read only the last section of each README and wrote 12_plan/PLAN.md, 547 lines in eight stages, with every number tagged measured, published, estimated or its own arithmetic.

01_worldgen/README.md compares seven ways to make the large shape of land and recommends authored uplift maps with stream-power erosion, in Python and NumPy as a build step beside the game. Its work items W1 to W5 are the next three sections.

Drawing the coast from control points and noise

The Wishbone’s coast is 34 points in tools/worldgen/islands/wishbone.json.

The coast after the noise: the signed distance field, pale inland and dark out to sea.

 "coast": [
 [4, 8], [6, 4.5], [10, 2.8], [15, 2.4], [20, 3.2], [24.5, 4.6], [27.8, 7.5], [29.6, 11.5],
 [30, 15], [28.6, 17.6], [28.8, 20.4], [29.6, 23], [28.4, 25.6], [25.8, 26.2], [24, 24.4],
 [24.6, 21.4], [25.6, 18.4], [24.8, 16], [23.6, 13.6], [21.4, 11.4], [18, 10.4], [15, 11],
 [13, 13.2], [12.6, 16.4], [13.8, 19.6], [14.4, 23], [13.6, 26.4], [11.6, 29.4], [8.6, 30.2],
 [6, 28.6], [4.4, 25.4], [3.4, 21.6], [2.4, 17.5], [2.6, 12.5]
 ],

Positions are in units, 32 to a side: a unit is 512 m of the 16,384 m square, one Terrain3D region. Every map is a 1,024 by 1,024 field at 16 m a cell.

A smooth closed curve through the points becomes a signed distance field, positive inland. The field is domain-warped: it is read at positions pushed by two 3-octave fBm fields, then a 5-octave fBm is added, 800 m of amplitude at a 3,400 m wavelength for the Wishbone. A smooth maximum joins on named necks the noise must not cut, and a smooth minimum cuts the straits and a harbor. Land is where the field is over zero.

The noise is gradient noise from an integer hash of lattice points, so a value depends only on seed and position, and two builds are byte for byte identical. Each step is a pure function that writes fields as raw little-endian .bin files with a JSON header, and runs again only when a hash of its inputs changes.

I had six outlines built this way and picked B.

Raising the land and eroding it with the stream power law

The land’s height comes from a map of how fast the ground rises, worn down by the rivers that form on it. Noise alone has no drainage.

Uplift, drawn from the block below. Red rises fastest. The red bar is the Sill, which the gorge cuts.

The uplift map is drawn from a tectonic story, data in the same file:

 "tectonics": {
 "note": "The inner sea is a rift that the sea has entered. The two arms are its shoulders, tilted up toward the water and falling away gently to the ocean; the Arch is its closed head, older and lower; the Plug's volcano stands on the rift's floor; the Hook is a low block dropped across a fault at the Wrist.",
 "top_m": 1150,
 "base_uplift": 0.065,
 "basement": "schist",
 "lowland": "mudstone",
 "lowland_below": 0.2,
 "valley_floor": "mudstone",
 "ranges": [
 {
 "name": "the Long Arm",
 "why": "the rift's western shoulder: steep to the inner sea, long slopes to the ocean, highest and coldest at its southern end",
 "spine": [[6.2, 11.8], [6.8, 13.4], [7.6, 18], [8.8, 23], [9.8, 27.4]],
 "uplift": 1.0,
 "along": [0.8, 1.0],
 "half_width": 4.4,
 "skew": -0.25,
 "core": "granite",
 "core_width": 0.28
 },

skew steepens one side of a range. Six rock types each carry a hardness and an angle of rest, from granite (2.4, 50 degrees) to mudstone (0.55, 30 degrees).

erosion.py solves the stream power law, dh/dt = u - K * A^0.5 * s: uplift u raises a cell and its river cuts it down by drainage area A and slope s. Each step sends every land cell’s water to the steepest of its eight neighbors, joins each pit to the sea through its lowest pass, and sums area down that tree. Then it solves heights from the sea upward:

def step(lv: Level, h: np.ndarray, k: float, dt: float, m: float, hillslope: float) -> np.ndarray:
 """One implicit step of uplift and stream-power erosion. Returns the new heights."""
 g = lv.grid
 N = g.N
 rt = Routing(g, h)
 area = rt.accumulate(np.append(np.full(N, lv.cell * lv.cell), 0.0))
 pull = (k / lv.hard[:N]) * (area[:N] + hillslope) ** m * dt / rt.length
 water = rt.level[:N] if rt.level is not None else np.full(N, -np.inf)
 base = h[:N] + lv.u[:N] * dt
 reach = lv.tan[:N] * rt.length
 near = rt.length < lv.cell * 1.5
 hn = h.copy()
 recv = rt.recv
 for d in range(1, rt.deepest + 1):
 nodes = rt.nodes_at(d)
 below = np.maximum(hn[recv[nodes]], water[nodes]) # a lake's surface is its bed's base level
 p = pull[nodes]
 b = base[nodes]
 v = (b + p * below) / (1.0 + p)
 v = np.where(near[nodes], np.minimum(v, below + reach[nodes]), v)
 hn[nodes] = v
 lv.hold(hn)
 relax(lv, hn, 1)
 return hn

A cell’s new height uses its receiver’s new height, already solved. That makes the step implicit, so it is stable at a time step of 40. The np.minimum line is talus: no cell stands over its receiver by more than its rock’s angle of rest.

It runs coarse to fine, each grid started from the last:

Grid	Steps	Land cells
64 m	150	29,523
32 m	40	118,185
16 m	14	471,426

K is rescaled during the run so the highest point lands on top_m. The valley, the gorge and the passes are held by fields the erosion obeys every step (a height cap, a height floor, kept lakes), and one command checks 18 constraints on the result.

The last pass is Priority-Flood (Barnes 2014). It fills every hollow with 2 mm of fall toward its outlet, then gives back as lakes the hollows of at least 3,000 square m and 1.5 m deep. The generator’s own notes put the erosion at about 11 seconds and the whole island at about a minute.

Streams run straight for hundreds of metres, because each cell has one receiver.

Routing rivers and finding lakes

Rivers, lakes, springs and waterfalls are read off the eroded heights. Nothing is drawn.

Every stream and lake of the tuned land, and its larger drainage basins.

A cell is a creek once 0.045 square km drains through it and a river at 0.45. Strahler order sets the width: 1.5, 3, 6, 12, 22 or 40 m. A reach is the channel between two joins, kept as a line of [x, y, bed height] from its head down. This is the first in tables/rivers.json:

 {
 "discharge_m3s": 2.011,
 "drains_km2": 0.1613,
 "drop_m": 2.19,
 "from": "join",
 "id": 0,
 "kind": "creek",
 "length_m": 48.0,
 "meander_m": 0.0,
 "order": 2,
 "points": [
 [
 7384.0,
 1592.0,
 2.19
 ],
 [
 7384.0,
 1576.0,
 1.5
 ],
 [
 7384.0,
 1560.0,
 0.87
 ]
 ],
 "to": "sea",
 "width_m": 3.0
 },

A lake is the cells under the level their hollow spills at. A waterfall candidate is a run of links at least 0.42 steep and 2.2 times their reach’s usual grade that drops 10 m. The tuned land has 90.5 km of river, 208.9 km of creek, 12 lakes and 612 springs.

Was the land flat enough to play on?

The first land wasn’t: 35% of it was under 10 degrees. A second, tuned for play, is 53%.

The first land. Green is under 10 degrees, yellow to 25, orange to 42, dark red can't be climbed.

The land tuned for play, same coast and same story.

play.py bands every cell by slope at the angles the game uses: the party slides on ground over 42 degrees. It then runs Dijkstra over a 32 m grid from the starter valley to eight named places, where a step costs its length over the speed the slope allows (9 m/s to 10 degrees, 5 by 25, 2 by 42). A test in Godot drives the party’s real body along those routes with the game’s own keys and counts how often it is slowed, stopped or slides.

	First land	Tuned for play
Easy, under 10 degrees	34.7%	52.8%
Hard going, 25 to 42	35.7%	19.6%
Impassable	10.1%	8.0%
Highest point	1,102 m	936 m
Gorge stopped the party (the agent’s test run)	14% of the time	never

The tuned land is a named variant, a block laid over the island file:

 "top_m": 950,
 "base_uplift": 0.04,
 "range_sharpness": 2.3,
 "coast_plain_m": 500,
 "floodplain": {"min_km2": 0.35, "reach_m": 130, "grade": 0.03, "max_fall": 0.09},
 "sea_cliffs": {"shelter_under": 0.62, "inland_m": 110, "share": 0.8, "min_m": 18},
 "valley_ragged": 0.4,
 "valley_roll_m": 12,
 "valley_bar_m": 20,
 "passes": [
 {"name": "the Saddle", "half_width": 1.2, "cut": 0.75},
 {"name": "the Arch Gap", "half_width": 1.2, "cut": 0.75},
 {"name": "the White Gap", "half_width": 1.1, "cut": 0.3}
 ],
 "erosion": {"hillslope_m2": 80000},

range_sharpness (1.6 before) narrows each range and leaves wider foothills. The stream power law only cuts, so its valleys are V-shaped: floodplain lowers the ground beside a river draining 0.35 square km or more to the river’s height plus a 3% rise.

Painting the ground from slope, wetness and aspect

A painter in Python picks the ground textures at every vertex from what the land is doing there.

The starting valley before and after the ground was painted by rule.

The first version stamped noise and covered the plain in same-sized brown blobs. Now paint.py works out causes, each a number per vertex at 1 m. Ridge or hollow is height against its mean 48 m round. Wet is exp(-hand / 1.5) times a ramp on the wetness index ln(flow / slope), where hand is height above the nearest drainage. Sunny is how far the slope faces the sun’s bearing.

A biome in biomes.json lists its grounds. The first lies everywhere. Each later one lies where its causes times their amounts, plus noise and a bias, pass a threshold: bare earth on the dry plain weighs ridge 1.2, sunny 0.8 and wet -1.0. Terrain3D blends two textures a vertex, so the painter keeps the strongest two and packs a 32-bit control word:

 base = np.minimum(first, second).astype(np.uint32)
 over = np.maximum(first, second).astype(np.uint32)
 blend = np.where(second > first, share, 1.0 - share)
 control = (base << 27) | (over << 22) | (np.round(blend * 255.0).astype(np.uint32) << 14)

Textures are stored pale and neutral and the terrain’s color map multiplies them, so one grass serves a dry plain and a wet valley. That keeps the count under Terrain3D’s 32 slots. Python can’t write Terrain3D’s region files. It writes raw float32 heights, uint32 control words and RGBA color, and a Godot script wraps each in an Image and saves a Terrain3DRegion. A 512 m region takes 1.16 s to paint and 45 ms to import.

Streaming the terrain round the party

Only the terrain near the party is in memory. The island is 576 regions of 512 m at a vertex a metre.

Terrain3D 1.0.2 loads every region in its data_directory as its node enters the scene tree. TerrainStream empties that property at run time, before the node enters, so the editor still loads and sculpts the whole terrain and the game starts with none. Then, every frame:

	for location in _wanted(point, load_distance):
		if not loaded.has(location) and not _loading.has(location):
			_loading[location] = available[location]
			ResourceLoader.load_threaded_request(available[location], "", false, ResourceLoader.CACHE_MODE_IGNORE)
	for location: Vector2i in _loading.keys():
		var path: String = _loading[location]
		var status := ResourceLoader.load_threaded_get_status(path)
		if status == ResourceLoader.THREAD_LOAD_IN_PROGRESS:
			continue
		_loading.erase(location)
		var region := ResourceLoader.load_threaded_get(path) as Terrain3DRegion
		if region != null and not loaded.has(location):
			_take_in(location, region)
			arrived.append(location)
	var dropped := _drop_far(point)
	if dropped or not arrived.is_empty():
		_tell(arrived)

A region loads on a thread when its nearest edge is within 512 m and is dropped beyond 704 m. _tell calls the plugin’s update_maps once a frame, 2 to 8 ms.

The plugin’s collision is off: its dynamic mode rebuilt everything within 256 m whenever a region came or went, 265 ms each time. The stream builds its own 64 m squares of HeightMapShape3D within 288 m, 1 ms of building a frame. Physics is Jolt, because holes in Terrain3D hang Godot’s built-in physics.

A bake writes one image of the whole world’s heights beside the regions. It answers height queries where nothing is loaded and feeds the map and the far ground: six square grids of 128 by 128 that follow the camera, 16 m between vertices in the first and double in each next, out to 32 km. One view_distance of 12 km sets the fog’s density to 3 over it and the camera’s far plane to 2.5 times it.

Placed things stream in 64 m chunks, built within 160 m and freed beyond 224 m. At the start only what is near is built: 0.3 s for an 8 km test world with 8,000 things. A save keeps only what the party changed, so a new game’s is 51 KB.

Why were the rivers dry at every join?

Every piece of river faded to nothing over 3.5 m at both ends, so two pieces met at a strip of dry bed.

Four snapshots and the same views after the fix. The third is still wrong.

river_stream.gd cuts each reach into pieces of 14 points. A piece becomes a WaterCourse, a Path3D whose script builds a sheet of water fitted to the bed, when it is within 420 m and its ground is loaded. It is freed beyond 640 m.

The agent fixing the water can’t see my screen, so F3 saves the frame and a JSON file beside it:

	"lake": {
		"level": 169.18,
		"metres": 576.2,
		"sheet": 159,
		"text": "lake sheet 159 at level 169.18 m, 576.2 m away"
	},
	"mode": "flying",
	"note": "",
	"number": 1,
	"over_ground": 1.11,
	"pace": "36 m/s",
	"pitch": -14.17,
	"position": [
		-2917.28,
		169.92,
		-2569.49
	],
	"region": [
		-6,
		-6
	],
	"reproduce": "tools/gd.sh shots world/experiments/explore/explore.tscn -- --at=-2917.28,169.92,-2569.49,33.63,-14.17 --hour=9.02 --shot=again.png",
	"river": {
		"has_water": true,
		"kind": "river",
		"metres": 13.5,
		"reach": 382,
		"text": "river reach 382, 12.0 m wide, 13.5 m away, water built",
		"width": 12.0
	},

Each of my 24 pictures came with a reach id and a command that retakes the view with no window. An agent sorted them into seven kinds of fault and fixed the causes:

Fault	Cause	Fix
Dry bar across a river	each piece faded at both ends	an end that meets more water doesn’t fade
Sheets crossing at a join	every stream ran to the join’s middle	the widest runs on, a tributary stops at its bank
River ends in a pan of stones	a spring starting at full width	its bed grows from nothing over about 30 m
Rectangular lakes	drawn as the generator’s 16 m cells	outline flood-filled on the painted ground at 4 m
Water wider than its bed	bed 0.5 m deep under 0.45 m of water	bed cut 0.75 to 1.8 m, banks sloped over 2 to 4 m

By the agent’s own count 12 of the 24 are fixed and 9 are better, and in a survey of 64 other spots dry stretches went from 31 to 4. Seams and stepped banks are left.

Why didn’t the river match the lake?

Left, the river lit from underneath. Right, wound the right way and set to the river's blue.

The river’s triangles were wound back to front. Godot turns a back face’s normal round, so the river was lit from underneath and came out darker than the lake under the same shader. The fix is the index order in water_course.gd:

			indices.append_array([first, first + 7, first + 1, first + 1, first + 7, first + 8])

Wound right, the river turned the lake’s pale cyan. I liked the wrong color, so all water is now the blue the river had.

Also done

One approved model now comes out in five themes by four states of decay: twenty barrels, then twenty orcs on the same 18 bones. The orcs were 59 MB because every texture was stored twice, in the .glb and in a copy Godot wrote out. They are 15 MB.
The island is three times the size I meant. I’d read Skyrim as 16 square km when it is about 16 square miles (37 to 41 square km), and the Wishbone’s land is 121.
Seven test areas of the island are painted, one with crimson meat ground.

Next is the island again in a 10.2 km square, about 47 square km of land.

Modeling and rigging an orc in Blender with Python scripts

Wed, 07 Oct 2026 20:00:00 -0700

Blobber’s walking monsters are an orc now: 2.04 m tall, 7,999 triangles, 18 bones, five clips. An agent built him by writing Python against Blender’s API and running Blender headless, with no modelling by hand and no MCP connector. The script is the source, and the .blend and .glb are rebuilt from it.

Building the body from a stick figure and a Skin modifier

The body starts as 20 points joined by edges, each point with a radius.

Top: the first orc. Bottom: the second, from a written brief with one arm huge and one withered.

Blender’s Skin modifier wraps a tube round every edge at the radius of its ends, and a Subdivision modifier at level 2 rounds it off. The points are a Python dictionary at the top of the generator, so the proportions are numbers: the right elbow has a radius of 0.165 m and the left 0.095 m. This is from tools/blender/SK_creature_orc/gen_orc.py:

me = bpy.data.meshes.new("skin")
me.from_pydata([P[n][0] for n in names], [(names.index(a), names.index(b)) for a, b in E], [])
stick = link(bpy.data.objects.new("skin", me))
stick.modifiers.new("Skin", "SKIN")
for i, n in enumerate(names):
 me.skin_vertices[0].data[i].radius = (P[n][1], P[n][1])
 me.skin_vertices[0].data[i].use_root = n == "pelvis"
stick.modifiers.new("Sub", "SUBSURF").levels = 2

Every vertex is then pushed along its normal by two scales of mathutils.noise, 2.2 cm and 0.7 cm, so nothing is a clean tube. Chest sacks, jowls, tusks and boils are separate UV spheres and cones sunk into the surface at body.closest_point_on_mesh(). The hip wrap is a copy of the body’s own faces, pushed out 2.5 cm with bmesh. Color is a vertex attribute, and its alpha marks flesh against cloth and metal.

The first orc’s skin looked like cracked mud because Voronoi cell edges were used as creases at full strength. The generator now mixes them in at 14% and adds a second Voronoi, stretched 3.6 times along the height, for folds that lie across the body.

Why did the feet and hands look wrong?

Feet are now solid wedges and each hand is a small stick figure of its own.

Each foot is one wedge with three toes on it. Each hand has three fingers and a thumb.

A Skin limb ends in a round cap close to its last vertex. The first legs ran on into the toes, so the toes floated past the cap and left a gap in front of the heel. Now the leg ends straight down under the ankle and the foot is overlapping spheres on the ground: a flattened one from heel to ball, one for the heel, and three toes sunk into the front edge.

The hands were loose balls with a thumb in the middle of the palm. Each is now skinned like the body: a root 20 cm up inside the forearm, three knuckles fanned across the palm, three joints a finger, and a thumb that leaves low on the index side. Each finger joint has a curl angle. 14, 26 and 22 degrees is the slack left hand. 72, 92 and 68 is the fist on the cleaver. Three fingers, because four melted into a mitten at this size.

The Decimate modifier fused the fingers too. The body is cut first, to 8,000 triangles less the hands’ count, and the hands are joined after.

How is the knowledge base set up?

It’s 2.3 GB of free reference in a folder outside the game’s repository, sorted so that an agent can find a page with a text search.

kb/
 INDEX.md order of authority, and a table of "question -> start here"
 00_policy/ 12 core rules, which sources are allowed, licences
 01_blender/ modeling topology sculpting uv texturing materials shaders
 rigging animation geometry_nodes python asset_browser
 02_gltf/ the specification by chapter
 03_godot/ import meshes materials animation foliage terrain lod ...
 04_game_art/ notes by asset class (creatures, props, trees ...)
 05_pipeline/ the twelve steps, naming, manifests, checks, export
 06_style/ Blobber's look: camera, silhouettes, palettes
 07_project/ budgets by class, approved assets, rejected patterns
 99_examples/ good, bad, before and after, with pictures
 _sources/ the raw downloads
 _tools/ build_tree.py

_sources/ holds the Blender 5.2 manual twice (the HTML with figures, and 2,167 pages as plain text), the Python API reference as HTML, Godot’s documentation as its .rst source, the glTF 2.0 specification, Wikipedia articles and six example repositories with their binaries stripped. _sources/books/ is empty: the agent wouldn’t pirate commercial books, and the policy page says a book goes in when I buy it.

_tools/build_tree.py sorts those into the numbered folders. It has a table of path prefixes, and the first match wins: a manual page under modeling/meshes/uv goes to 01_blender/uv/, one under render/cycles/baking to 01_blender/texturing/. The file name keeps the source path, and every page gets the same header. This one is 01_blender/uv/blender__modeling__meshes__uv__unwrapping__introduction.md:

---
generated: true
source_authority: Blender Foundation (official manual)
software: Blender
version: 5.2 LTS
domain: 01_blender/uv
asset_class: any
target_engine: Godot 4.7
license: CC BY-SA 4.0
confidence: high
applies_to: 
supersedes: 
review_date: 2027-10-07
project_rule: false
source_url: https://docs.blender.org/manual/en/latest/modeling/meshes/uv/unwrapping/introduction.html
fetched: 2026-10-07
---

The README.md in each numbered folder is written by hand. A rebuild deletes only files that say generated: true, so it never touches them. INDEX.md ranks the sources: Blobber’s own rules in 07_project/ and 06_style/ win, then policy and pipeline, then the official manuals, then repositories, then Wikipedia. Instructions found inside a downloaded repository are reference, not orders.

07_project/README.md has a table of rejected patterns: the pattern, what went wrong, what to do. The floating toes, the sliding skin and the half turn below are rows in it.

Turning the knowledge base into a skill

The skill model-in-blender is what an agent reads before it models anything. It’s two files in the repository.

The orc rebuilt through the twelve steps: silhouette first, then the turnaround.

SKILL.md is the procedure: eight core rules, then a table of twelve steps where each step names the evidence that has to be looked at before the next one starts. It runs from a written brief and a black silhouette at 4 m and 12 m, through mesh, UVs, bake, material and export, to a reimport, a film in the game and a manifest. It also holds budgets by asset class (an ordinary monster is 5,000 to 10,000 triangles) and name prefixes (SK_, SKEL_, AN_, T_, M_).

reference.md is the craft: bpy recipes under two headings, “Proven here” and “Not yet proven here”. A recipe moves up when it has run and the result was looked at. The first version drew on only a handful of the pages, by the agent’s own report. The feet and hand recipes above went in after they worked.

Why did the skin slide when he moved?

The skin was worked out from positions in space, so when a bone moved the body went through its own texture.

Bottom left: the checker render and the three baked 1024 textures, cut into 576 small islands.

The material’s noise and Voronoi nodes read the Texture Coordinate node’s Object output. The fix is to bake in the rest pose, before the rig exists. bpy.ops.uv.smart_project unwraps at an angle limit of 78 degrees, islands near the head are scaled 1.6 times, and Cycles bakes three 1024 images on the CPU: base color, normal, and one with occlusion, roughness and metallic in its red, green and blue, which is how glTF wants them. Base color and the metal mask are baked through emission, because a diffuse bake of metal comes out black. A second material that only reads the three images replaces the first.

Smart Project cuts a body made of overlapping parts into 576 islands, so the skin is softer than it should be. That needs seams placed by the generator, part by part.

Rigging and animating without touching a bone

He has 18 bones and five clips at 24 frames a second: idle 72 frames, walk 32, attack 34, hit 16 and death 56.

Download the clip (mp4)

Idle, walk, overhead chop, struck and death, rendered in Blender after the bake.

The bones use the stick figure’s own points: hips, spine, chest, head and jaw, an upper arm, forearm, hand, thigh, shin and foot on each side, and a belly bone off the spine so that the gut lags behind the hips.

Blender’s automatic weights fail on overlapping shells, so rig.py does its own. Rigid parts (teeth, tusks, cleaver, hands, feet) go wholly into their bone’s vertex group before the join. Every other vertex is weighted by distance to each bone’s segment, measured in that bone’s radius, so that a thick trunk outvotes a thin arm beside it:

 w = sorted(((min(1.0, r / max(seg_dist(v.co, h, t), 1e-4)) ** 5, n) for n, h, t, r in soft), reverse=True)[:3]
 tot = sum(x for x, _ in w)
 for x, n in w:
 if x / tot > 0.04:
 orc.vertex_groups[n].add([v.index], x / tot, "REPLACE")

A key is a frame, a dictionary such as {"chest": "X-14 Z-12"} and an offset for the hips. The turns are degrees about the model’s own axes, converted to the bone’s space as rest.inverted() @ q @ rest. The walk is a function of phase, sampled every 4 frames: the thigh gets -26 * cos(phase) - 2 degrees. Each action sits on its own NLA track named like AN_orc_walk-loop, and the exporter runs in NLA_TRACKS mode with export_optimize_animation_size=True, which drops tracks for bones a clip never moves.

Checking the exported file, not the Blender file

Three scripts check what was exported, and one checks the joins.

validate_glb.py is plain Python. It parses the .glb with struct and ran 22 checks on the orc: triangles against the budget, normals and UVs on every mesh, the lowest point on y = 0, height within 1% of the brief, skin weights that sum to one with at most four a vertex, no bone without influence, no unused track in any clip, both loops closing on their first pose, textures a power of two, opaque materials and the name prefixes. It writes manifest.json with every result. roundtrip.py imports the file into an empty Blender scene and compares counts with the manifest. A small Godot scene loads it and checks the skeleton, the texture slots and the loop flags.

join_check.py exists because the hands were held to the arms by nothing and no render showed it. Before the join it tags every vertex with its part. Then, at rest and at chosen frames of every clip, it builds a BVH tree for each part and counts vertices of one inside another by ray casting, and faces that cut through. A join is solid at 2 for a part under 60 vertices and 6 for a larger one, and every part needs a chain of solid joins back to the body.

Why did he walk into the game backwards?

In the first film from the game the orc walked in with his back to the party.

Blender models face -Y with Z up. The exporter’s export_yup turns that into Y up facing +Z, which is what glTF asks, and Monster.face() already turned +Z toward its target:

_model.rotation.y = atan2(to_point.x, to_point.z)

But the game was built round a bought alien model that faced -Z, so a constant MODEL_YAW_OFFSET_DEG := 180.0 was added to every monster and saved into every body and thrall. The orc faces +Z, and the half turn pointed his back at me. The test missed it because it checked which way the file faced. It now turns a monster toward three points with face() and wants the dot product of his front and the direction over 0.95.

The constant is gone, and save version 8 subtracts pi from each saved yaw. The rule went into a second skill, model-into-game: a model that faces the wrong way is fixed in its file, never in the game.

Why did an idle animation change who got hit?

Each monster starts its idle at a random offset so that a pack doesn’t breathe in step. That was a call to randf(), which draws from the same random stream as the combat rules. The tests seed that stream, so one extra draw per monster changed who got hit in a seeded fight and the fight log test failed. The offset now comes from the node’s instance id, in scripts/monster_anim.gd:

# A pack does not breathe, or flap, in step. The offset comes from which node this is, not
# from the game's dice: looks must never use up a roll that a rule was going to make.
_player.seek(float(get_instance_id() % 997) / 997.0 * _player.get_animation(idle).length, true)

Also done

A dead orc lies flat. A function in rig.py prints the highest point of each part at the last death frame: his wrists were 45 cm off the floor and his feet 65 cm. Now they’re at about 25 cm and 14 cm.
The flyers are a harpy, built on a shared kit that holds the steps above as functions. Its wing roots opened a gap when it flapped, and the join check had exempted wings as open sheets. They aren’t exempt now. Every new model has to use the kit.
The game stands in a streamed 2 km world scene on Terrain3D terrain, and moved to Jolt physics, because holes in the terrain hung under Godot’s default physics.
A private page for drawing dungeons on my phone, and an importer that turns a sheet into a playable dungeon.
Keys are individual items tied to the locks they open, with lock picking. A badly failed pick can jam the lock for good, but its key still opens it.
Dungeons have varied heights and widths, and the party can crouch.
The whole interface was re-themed as a rack of synthesizer modules.
Rivers, waterfalls and lakes as the game’s own water.
An 8 km world experiment, where the game never finished starting.

Running turn-based combat on a real-time clock in Godot

Tue, 06 Oct 2026 20:00:00 -0700

Blobber has a turn-based mode now, and it has no rules of its own: it stops the game’s one clock and steps it by hand. It was one of nine branches that landed by 10:27, built overnight and through the morning by AI agents working three at a time.

Running turn-based mode on the real-time clock

Enter switches a fight to turn-based. The clock stops while anyone in the party is ready to act, and a strip at the top shows who goes next.

The same fight in both modes. The strip at the top is the order, soonest first.

I wanted real time with a turn-based mode from the first message of the project, and I didn’t want a second set of combat rules to keep in step with the first.

The autoload GameClock (scripts/game_clock.gd) is the only clock. Its advance(game_seconds) adds to play_seconds and emits the signal advanced(game_seconds). Every gameplay timer counts down in a handler of that signal. A party member has cooldown_remaining. A monster has cooldown_remaining, spell_cooldown_remaining and cast_remaining. “Ready” means cooldown_remaining <= 0.0, and acting sets it back to the action’s recovery time. In real time the clock’s _process() calls advance(delta * time_scale) every frame.

TurnMode (scripts/turns/turn_mode.gd, a plain Node the level makes) sets GameClock.running = false and calls advance() itself, once per physics step. This is the whole decision, from its _physics_process():

	# How much game time this step is worth, never past the next thing due.
	var rate := 0.0
	if _party_moving():
		rate = MOVE_RATE
	elif acting() < 0:
		rate = playback_rate
	var step := minf(rate * delta, next_event_in())
	GameClock.stepped_rate = step / delta
	Projectile.flush_rate = playback_rate if step <= 0.0 else 0.0
	_step = step
	_everybody = everybody
	if step > 0.0:
		GameClock.advance(step)

The rate is 0 while a member is ready, so the game waits. It is MOVE_RATE (1.0) while a movement key is down or the party is in the air. Turning and looking are free. With nobody ready it is playback_rate, 3.0 game seconds a real second.

next_event_in() returns the smallest timer still running: a member’s recovery, a queued second hit, a hunting monster’s recovery or its spell wind-up. Cutting the step to that stops the clock exactly on a ready time, never past it.

Monsters don’t know the mode exists. They already scaled their movement by GameClock.rate(), which now reads:

func rate() -> float:
	return time_scale if running else stepped_rate

So whatever moves by rate() moves exactly as far as the step. Shots flew on real time before, and now use rate() in both modes. Traps sense only while rate() > 0. One exception: Projectile.flush_rate lets shots already in the air fly on while the clock is held, so each lands in the turn it was fired in.

The order inside one physics step is set with process_physics_priority. TurnMode runs at -100 (keys, then the clock), shots at -50, a small child node at -25 (members the step made ready act), then the party and monsters at 0.

acting() picks whose turn it is: the member who is up, ready, and has been ready longest (_due_at, the play_seconds when their recovery ended). F calls Party.attack(i) for that member, the same function hold-F runs for everyone in real time. Q waits: it sets their recovery to end 0.05 seconds after the next actor is ready. G lets every member act as they recover until each has gone once. The strip is order(): members who are up and monsters hunting the party, each with the game seconds until ready, sorted soonest first. TurnHud, a CanvasLayer, shows the first five.

At 3x a monster’s 4 second recovery takes about 1.3 real seconds. Whether that’s the right pace is still open on the work list. It’s a setting, gameplay/playback_rate.

Why did one test miss its shot 2 times in 60?

Every test now runs on seeded dice, takes at most one physics step per frame, and aims at its target. Nothing the player sees changed, so there’s no picture.

Every test scene extends tests/harness_base.gd, and its _ready() now runs this before the test:

func _make_repeatable() -> void:
	var dice := int(arg("seed", "1"))
	if arg("seed") != "":
		print("seed: ", dice)
	seed(dice)
	MonsterSize.rng.seed = dice
	WeaponRules.rng.seed = dice
	MonsterLoot.rng.seed = dice
	Afflictions.rng.seed = dice
	# Never more than one physics step to a frame. A frame that took a long time (a busy
	# machine) would otherwise be made up with up to eight steps at once, and the clock with
	# them: a wait of three frames could be anything from none to 0.4 s of play. This way a
	# slow machine runs the game slowly instead of in jumps. (Recording a film steps the game
	# at a fixed rate and is not affected.)
	Engine.max_physics_steps_per_frame = 1

seed() covers Godot’s global generator. Four rules roll on a RandomNumberGenerator of their own, kept as a static var rng, and each is seeded by name. Running a test with -- --seed=N gives it other dice, which finds a check that only passes on luck.

The failing check was “the party’s shot lands”, and three faults were stacked under it.

The test read the floor height as party.position.y after boot. The party wakes on a platform 0.8 m up, so every later placement left it standing in the air.
It called queue_free() on one monster and spawned the next on the same spot in the same frame. A freed node stays solid until the frame ends, and the new monster was pushed onto its head, about 1.6 m up. The fix is to wait two frames.
It turned the party toward the monster and set party.pitch = 0.0. Monster heights had been random since the day before (this type from 2.2 to 3.6 m), and a level shot from the air went over a short one. Both misses in 60 runs had a monster under 2.4 m.

Tests now aim with this helper, which tilts the view from the party’s eye height (1.6 m):

func aim_at(target: Vector3) -> void:
	face(target)
	var to := target - (party.global_position + Vector3.UP * party.eye_height)
	party.pitch = atan2(to.y, Vector2(to.x, to.z).length())

The quest builder had a real race. Every time it opens, _sweep() in scripts/builder/builder_model.gd deletes any other process’s scratch folder that has no stamp.txt. But _write_scratch() makes the directories first and writes the stamp after. Open the builder twice at once and one copy deletes the other’s folder. Eight copies of the builder tests at once failed 11 of 24 runs. The tests now build their folder to one side with the stamp already in it, then move it into place with DirAccess.rename_absolute(), so it never exists without a stamp. The builder itself still makes the folder first.

The agent on this ran the suite ten times in a row and three times with two copies at once: 608 scenario runs, 0 failures, by its own count. One failure it could never reproduce, so its cause is unknown.

Putting every key and button behind one input table

The game opens on a main menu now, and Esc or Start pauses it. There are settings, key rebinding, and a controller layout for every screen.

The box at the top right names each controller button the film pressed.

Rebinding and on-screen hints both need one place that knows what every key does. That is the autoload Controls (scripts/input/controls.gd), built round a constant table, ACTIONS, of 155 rows. A row is an id, its name on the rebinding screen, a context, the default keys and the default controller buttons:

	["jump", "Jump", WORLD, "Space,X", "Y"],
	["interact", "Use / talk", WORLD, "E", "A"],
	["attack", "Attack / act", WORLD, "F,mouse:1", "RT"],
	["next_spell", "Next readied spell", WORLD, "C", "X"],
	["next_caster", "Next caster", WORLD, "Shift+C", ""],

A binding is a string: key:Shift+C, mouse:1, pad:A, or pad:LX- for a stick direction. _register() turns each into an InputEventKey, InputEventJoypadButton or InputEventJoypadMotion and writes it into Godot’s InputMap under the action’s id, so Input.is_action_pressed() still works underneath. A stick counts as one press when it crosses 0.5. Only bindings that differ from the defaults are saved, in the bindings section of user://settings.cfg (a ConfigFile), never in a save.

The context says which actions are listened for at the same moment. The world and a screen never are, so R can be Rest in the world and Ready in the spell book. rebind() takes a binding away from any action that would clash and returns the losers for the screen to name.

Hints are templates. Controls.format("[{interact}] Open") gives [E] Open, or [A] Open once the last input came from a controller. Controls.live(label, template) keeps a weak reference to the label and refills it on every rebind or change of device.

A test keeps it that way. tests/controls.gd reads every game script outside scripts/input/ with a regular expression for KEY_, JOY_BUTTON_, Input.is_action_pressed and the like, and fails on any match that isn’t one of five listed exceptions.

A controller has too few buttons for this game. The D-pad opens four screens, and holding LB shows a wheel of eight actions, each fired as if its key had been pressed.

Nobody has held a controller to it. The film and the tests build controller events and feed them to the engine, from tests/pad_base.gd:

func _pad_button(button: JoyButton, pressed: bool) -> void:
	var event := InputEventJoypadButton.new()
	event.device = 0
	event.button_index = button
	event.pressed = pressed
	event.pressure = 1.0 if pressed else 0.0
	Input.parse_input_event(event)

Chaining two save migrations that both claimed version 4

Two branches each raised the save file from version 3 to 4: the one for learning spells one at a time, and the one for XP dropped on a party wipe. Landed, they are versions 4 and 5.

Spells are learned one at a time now. Unknown ones show as blanks.

A wipe leaves your unspent XP where you fell. Wipe again first and it is gone.

A save is user://saves/<slot>.json with a version and a dictionary of sections. SaveGame._read_file() refuses a file newer than FILE_VERSION and brings an older one forward one version at a time:

	while version < FILE_VERSION:
		if migrations.has(version):
			file = migrations[version].call(file)
		version += 1

migrations maps the version a file was written with to a function that takes the whole decoded file and returns it as the next version would have written it. A migration never asks the running game anything. The 3 to 4 one carries a frozen table of the spells each school had at version 3, and gives a member all of them so nobody loses their spell book.

Both branches were cut from version 3, so both added an entry under key 3. The merge moved the second to key 4 and set FILE_VERSION to 5. This is scripts/save/save_migrations.gd after it:

static func all() -> Dictionary:
	return {1: v1_items_get_ids, 2: v2_one_list_and_lore_by_type, 3: v3_spells_known_one_by_one,
			4: v4_keys_by_id}

The order was free here. One migration adds known_spells to each member in the party section. The other renames keys in the doors, chests, traps, keycards and monsters sections, from an id and a position (cell_door@-5.3,0.0,-38.5) to the id alone. A third branch made it version 6 the same morning.

Why did the run sit stopped for four hours?

One main session briefs the agents and lands what they finish. Each agent works on its own branch in its own git worktree. The main session only acts when an agent reports to it or I type.

At 2:05 the main session hit its usage limit. Two agents finished at 2:05 and 2:15, and nothing was running to land them. The limit reset at 2:50, but nothing sends the session its next message. I typed “Continue” at 6:21, so finished work waited 4 hours 16 minutes.

One agent had started a shell loop at 23:49 that read a test output file every ten seconds, waiting for one result line. The line was never written to that file. The agent finished and reported without it, and the loop ran for about seven hours with no time limit. It only slept and read a file, so it changed nothing. I found it, not the session.

A watchdog for this has to run outside the session, so a limit doesn’t stop it too. It needs to know which branches are finished and unlanded, and to put a time limit on every wait. None of that existed that night.

Also done

Items, chests, loot, recipes and prices left the code tables for JSON under content/ (content/items/weapons.json and eight more, stocks.json, loot.json, costs.json), read at start by ItemDb. A recorded baseline of every item, chest, loot roll, recipe and cost was identical before and after. Another branch was adding items to the tables this one deleted, so seven files conflicted in the merge.
Classes and XP cost curves are content files too, with a class editor.
Spells no longer take damage from the caster’s weapon. Staves carry a spell bonus of their own.
A spear in both hands does 1.25 times its damage.
Monsters chasing the party are still chasing it after a load.
I looked into an art pipeline and put it on hold.

Next: how dungeons and an overworld get made.

Auditing a day of agent work and building tooling from it

Mon, 05 Oct 2026 20:00:00 -0700

I measured where the first day of building Blobber went and turned the findings into tooling: one shell script that runs Godot, a base script that every test extends, a film recorder on top of Godot’s movie writer, and the files my agents read before they start. That evening eleven branches landed through it, built by three agents at a time.

Blobber is a first-person party RPG in Godot 4.7 that I started the evening before. I build it by directing AI coding agents: a main session I talk to, and background agents (workers) that each build one feature in their own git worktree.

Where did the first day’s effort go?

An agent read the transcripts of the main session and of the 15 workers run so far, and counted. These are its counts. I have not checked them.

What it counted	Number
Test scripts written from scratch, then deleted	61
Time spent running them	about 97 minutes
Of that, waiting 10.5 seconds for the game’s opening	about 23 minutes
Passing checks cited in reports, and kept	over 4,800, and 0
Test runs that hung for 300 to 400 seconds	4
Large shell heredocs that failed	15 of 17
Code read by workers before their first edit	2.0 MB, in 175 tool calls
Size of 14 briefs, and how much of it was the task	148 KB, and 62 KB
Merge conflicts in 24 merges	4

The biggest cost was the main session: one conversation of about 822K tokens, re-read on every turn. The fix is a fresh session after each landed feature, and that only works if everything the session knows is in files.

Running Godot through one script

tools/gd.sh is now the only way Godot gets run, by me or by an agent. These are four of its five modes, from the script’s header (movie is further down):

# tools/gd.sh import [-C dir] re-import (new class_name scripts, assets, after a merge)
# tools/gd.sh check [-C dir] import, then load the game for 90 frames
# tools/gd.sh run [-C dir] <scene> [-- a b] run a scene headless (logic tests)
# tools/gd.sh shots [-C dir] <scene> [-- a b] run a scene in a window (screenshots only)

-C dir picks the worktree, so the copy in the main checkout can run any worker’s branch.

Every mode goes through the same two functions in tools/gd.sh. The first runs the console build of Godot under GNU timeout and keeps the output and the exit code. The second decides whether the run failed:

godot() {
	local raw
	raw="$(timeout "$LIMIT" "$GODOT" --path "$dir" "$@" 2>&1)"
	code=$?
	out="$(printf '%s\n' "$raw" | filter)"
}

report() {
	local label="$1" failed=0
	[ -n "$out" ] && printf '%s\n' "$out"
	if [ "$code" -eq 124 ]; then
		echo "gd.sh: $label TIMED OUT after ${LIMIT}s (a script error in a harness leaves Godot waiting; look above)"
		failed=1
	elif [ "$code" -ne 0 ]; then
		echo "gd.sh: $label exited with code $code"
		failed=1
	fi
	if printf '%s\n' "$out" | grep -q "SCRIPT ERROR"; then
		echo "gd.sh: $label printed a SCRIPT ERROR"
		failed=1
	fi
	return $failed
}

A run fails three ways. timeout returns 124 when the limit passes (150 seconds unless GD_TIMEOUT says otherwise). The scene quits with a non-zero code. Or the text SCRIPT ERROR appears anywhere in the output, even from code the test wasn’t about. The timeout is there because a test script that fails to parse never reaches its own quit call, and Godot then waits forever.

import is --headless --import, printing only lines that hold ERROR, WARNING or an at: location. It has to run after a merge or after adding a script with a class_name, because until then the new class doesn’t resolve. check is the import and then --headless --quit-after 90. run is --headless <scene> -- <args>. shots is the same in a 1280x720 window, because a headless run draws nothing.

Godot prints the same harmless lines on every headless run, so filter drops them with awk before anything is judged. skip makes a dropped error take its indented at: line along:

filter() {
	awk '
		/^Godot Engine v/ || /^Vulkan / || /^OpenGL / || /^[[:space:]]*$/ { next }
		/^\[ *[0-9]+% \]/ || /^\[ DONE \]/ || /\[0m$/ && /(reimport|scan|first_scan|update_scripts|loading_editor)/ { next }
		/ObjectDB instances were leaked at exit/ ||
		/resources still in use at exit/ ||
		/Parameter "material" is null/ ||
		/BUG: Unreferenced static string/ ||
		/Pages in use exist at exit in PagedAllocator/ ||
		/A Thread object is being destroyed without its completion/ ||
		/Please call wait_to_finish\(\)/ { skip = 1; next }
		skip && /^[[:space:]]+at: / { next }
		{ skip = 0; print }
	'
}

Keeping the tests

Tests now stay in tests/. Each is a .tscn holding one Node with a script, and the script extends tests/harness_base.gd and overrides one function. This is most of tests/smoke.gd, the first kept test:

func scenario() -> void:
	await boot()
	check_eq(party.members.size(), 4, "a party of four")
	check(not party.groggy, "the party is not groggy once it has members")
	check(party.input_enabled, "the party can move")
	for member in party.members:
		check(member.is_alive(), "%s is alive" % member.name)
		check(member.action_damage(PartyMember.MELEE) > 0, "%s can hit" % member.name)
		check(not member.known_skills().is_empty(), "%s knows some skills" % member.name)
	check_eq(party.inventory.items.size(), 8, "the party starts with its eight rations and nothing else")
	check(get_tree().get_nodes_in_group("monsters").size() > 30, "the world has its monsters")

The base script’s _ready() awaits scenario() and then calls finish(), which prints checks: N passed, M failed and quits Godot with the number of failures as the exit code, capped at 100. gd.sh turns a non-zero exit into a failed run, so nothing parses test output.

boot() stands up the real game, the same scene the player gets:

func boot(with_intro := false) -> void:
	load(LEVEL_SCRIPT).skip_intro = not with_intro
	room = load(SCENE).instantiate()
	add_child(room)
	party = room.get_node("Party")
	if with_intro:
		await wait(6.5)
	else:
		await frames(3)

skip_intro is a static var on the level’s script, so it can be set before the scene exists. When it is set, the level’s _ready() skips the wake-up and calls a short function that powers the Meat Machine, marks it used, and builds the default party of four from the creation screen’s defaults. A test is ready after 3 frames. The old scripts waited 6.5 seconds for the opening and 4 more after confirming the party. The session reported a whole test run at about 1.7 seconds.

Input goes in the way a player’s does. key() builds an InputEventKey press and release and hands them to Input.parse_input_event(), so the game’s own handlers see them. hold() wraps Input.action_press() and Input.action_release() round a wait. A test can also call the game directly, as in monster.take_damage(n).

Logic is always judged headless, because a windowed run receives my real keyboard and mouse.

The suite is a loop, one Godot process per scene (from tests/README.md):

for scene in tests/*.tscn; do tools/gd.sh run "$scene" || echo "FAILED: $scene"; done

There was 1 scene with 19 checks in the afternoon and 37 scenes by the end of the day.

Filming a feature with Godot’s movie writer

Every feature the player can see or hear now gets a 20 to 60 second captioned film, and I get the film before I’m asked whether to merge.

The check sheet for the first film: 8 stills, evenly spaced, 2 across.

I wanted to see the game in action while I’m away from the machine. Until then I only got screenshots.

tools/gd.sh movie runs a scene with Godot’s movie writer turned on:

godot --resolution 1280x720 --write-movie "$avi" --fixed-fps 30 --disable-vsync "$scene" -- "$@"

With --fixed-fps 30 the engine steps the game by exactly one thirtieth of a second per recorded frame, no matter how long the frame takes to draw. A wait(6.0) in a scenario is 6 seconds of film on any machine.

A film scenario is a test with captions, kept in films/<feature>.gd so the film can be recorded again after a change. This is the first half of films/tour.gd:

func scenario() -> void:
	await boot()
	caption("The vat bay")
	await wait(1.0)
	await pan(360.0, 6.0)
	await hold(&"move_forward", 2.0)

	var yield_monster := monsters_named("Spoiled Yield")[0]
	var target := yield_monster.global_position + Vector3.UP
	place(Vector3(-3.0, party.position.y, -16.0))
	face(target)
	caption("The yard: every recovered member acts while attack is held")
	await hold(&"attack", 10.0)

caption() is a Label on a CanvasLayer at layer 100, in 24 px type with an 8 px black outline. pan() is a Tween on the party’s rotation_degrees:y. place() teleports the party and face() turns it to a point in the world.

The movie writer leaves an .avi. tools/movie.py encodes it to an .mp4 that plays on a phone, then deletes the .avi:

 command = [
 imageio_ffmpeg.get_ffmpeg_exe(), "-y", "-loglevel", "error", "-i", source,
 "-c:v", "libx264", "-preset", "medium", "-crf", "27", "-pix_fmt", "yuv420p",
 "-c:a", "aac", "-b:a", "96k", "-movflags", "+faststart", target,
 ]

There was no ffmpeg on the machine. The Python package imageio-ffmpeg carries one, and get_ffmpeg_exe() returns its path. The 38.8 second tour came out at 6.4 MB.

An agent can’t watch a video, so tools/frames.py makes the picture above. It reads the film’s length from ffmpeg, takes 8 frames at the middle of 8 equal slices, scales each to 640 px wide and pastes them 2 across with Pillow. Whoever makes a film reads that sheet and checks that each caption’s shot shows what the caption says. The first take of the tour spent ten seconds facing a wall, and the sheet caught it.

gd.sh first looked for movie.py under $dir, the worktree being filmed with -C. Fifteen minutes later I had that changed to $(dirname "$0"), the script’s own folder, so a worktree cut before the encoder existed can still be filmed.

Recording opens a real window, so anything I type at the machine can leak into the film.

Writing down what an agent needs before it starts

Every session and worker now starts from CLAUDE.md (63 lines when written) and docs/ARCHITECTURE.md (166 lines), so a brief is only the task.

CLAUDE.md opens by pointing at four files: the architecture map, WORKLIST.md (what is open), docs/DESIGN.md (what I have decided) and docs/HANDOFF.md (what is in flight, rewritten before a session ends). Then come the traps of the machine. The heredoc one reads “large heredocs fail here and \\ is silently collapsed to \”, and the rule is to create files with the Write tool.

A worker doesn’t commit, merge, push, switch branch or spawn agents, and leaves its work uncommitted in its worktree. It decides small open questions itself and lists them. It keeps a running note outside the repository (done, left to do, verified), so that a worker cut off by a usage limit is resumed from the note and not started again. And it reports in a fixed shape (from CLAUDE.md):

- Report in at most about 6 KB, under exactly these headings: **Built** (what the player
 gets, with numbers); **Decisions I made**; **Files** (added, changed); **Verified** (what
 was run, counts passed and failed); **Film** (the .mp4's full path and what it shows, in
 order); **Not verified**; **Needs the user's answer**;
 **Worklist** (items closed, changed or added).

The architecture map has a section per system (which script owns it, what other code calls) and a table for the files every feature touches. By the audit’s count all 4 merge conflicts were two branches adding lines at the same spot in one of those. Two rows:

| `party.gd` `BINDINGS` | One line per new key action, kept in the dictionary's order of appearance. New state: one commented `var` beside the related ones. New signal: beside the other signals. |
| `ai/monster_profile.gd` | One static function per monster type, added after the last. |

A brief now has four parts: where to work, my request word for word with what it means as a numbered list, the few files to read first, and which files the worker owns with what its test and its film must show.

Answering the work list from my phone

WORKLIST.md holds everything open in the game, one checkbox line per item, and the same items are on a private web page where I type answers under them.

The file has six sections, and the section gives the id its letter: Q a decision waiting on me, S a system not built, H a stub, N a placeholder number, R a rough edge, K housekeeping. Ids are never renumbered, because the page and the design record refer to an item by its id. This is one question before and after my answer:

- [ ] **Q4 Loading-zone markers.** The two zones (bay corridor, exit hall mouth) draw an amber floor patch and a "LOADING ZONE" label. Keep visible?

- [x] **Q4 Loading-zone markers.** The two zones (bay corridor, exit hall mouth) draw an amber floor patch and a "LOADING ZONE" label. Keep visible? Decided: no visible markers. To build: S25.
- [ ] **S25 Remove loading-zone markers.** Decided (Q4), not built: take out the amber floor patch and the "LOADING ZONE" label.

A question says what the game does today, so I can answer it without opening the game. An answer ticks the Q, goes into docs/DESIGN.md, and becomes a new S item if it needs building. The list had 91 items when it was written and 231 by the day’s last commit.

The page is a Claude artifact with a small database behind it: one row per item, with the same ids. The main session reads it at the start of a session and before every landing, looking for rows with an answer that aren’t marked done. It acts on each and marks it done with a note of what happened.

My first 27 answers settled 15 questions with no work and made 12 build items, which went to two workers. Each added new items to the list in its own worktree. Both worktrees were cut from the same commit, so both took the same next ids, and one set had to be renumbered before landing. The rule since then: workers don’t edit WORKLIST.md, docs/DESIGN.md or tests/README.md. They report the changes and the main session applies them at landing.

After 38 more answers I set a standing rule for the evening: no more than three workers at a time, merge what passes the kept tests on the merged result, and start nothing that depends on work that hasn’t landed. The queue is a list in docs/HANDOFF.md, each line a branch, its items, and what it waits for:

- `resistances`: S38, S39, S40. After `weapons` (same party and item files).
- `save`: S4. After wave 1 (it must cover the event log, kill facts, new item fields). Put
 serialisation in its own scripts so later workers add their state to it.
- `builder-2`: S41 NPC editor, S47 drafts and published. After `content-core`.
- `spells`: S9, spell book. After `resistances` (damage types) and `weapons`.

The three branches of the first wave each got a list of the files they own, so they could run at once. Eleven branches landed that evening.

Save and load, one of the eleven: F5 and F9, three slots.

Also done

tools/land.sh <branch> <message-file>: commits a worker’s worktree, merges it with git merge --no-ff, runs tools/gd.sh check on the result, and fast-forwards every other clean worktree.
A quest builder inside Godot, with forms generated from the content schema: 16 kinds of condition and 28 kinds of effect.
Character creation with point buy: 25 points, no stat above 25 or below 3.
Three tiers of chests, a flying monster, 26 skills and XP from kills.
Resting, which costs one food per party member, and surgery on organs, paid for in XP.
A town, a sunken dungeon, a camp and a tower outdoors.
The calendar runs at ten times play speed, so a full day and night takes 2 hours 24 minutes of play.
From the evening run: save and load, 24 spells in three schools, a minimap and a map with the player’s own notes, twelve damage types.

Building a first-person RPG prototype in Godot with agents

Sun, 04 Oct 2026 20:00:00 -0700

I started Blobber on Sunday evening with no code. By the end of the night it had 17 commits: stats that step up at breakpoints, one game clock that every cooldown counts on, shots swept as rays from the camera, and a dungeon built from a floor plan on a grid.

Blobber is a first-person party RPG in the style of Might and Magic VI, built in Godot 4.7. I build it by directing AI coding agents, and they write the GDScript. Everything below is the code as it stood at the end of that night.

Making stats step up at breakpoints

Every stat runs from 1 to 999 and turns into a bonus through one table. 10 is the baseline, each point below it is -1, and above it the bonus goes up by one at each breakpoint, to +50 at 999.

The stats pane shows each stat's bonus and the value where the bonus next goes up.

I wanted diminishing returns, so that 80% of the gains come from 20% of the range. I also wanted the gains to come in steps, so that a player can say “i won’t get to x until the next break point”.

The table is a PackedInt32Array of 51 entries in scripts/stats.gd, built the first time anything asks for it. Entry b is the lowest stat value that gives +b. The entries sit on a geometric curve from 10 to 999:

breakpoint(b) = 10 + 989 * (R^(b/50) - 1) / (R - 1)

R sets how fast the gaps widen, and the 80/20 rule fixes it. Put b = 40 in, and (R^0.8 - 1) / (R - 1) has to equal 0.2. That has no tidy solution, so the script finds ln(R) by bisection between 0 and 40, halving the range 80 times, then fills the table:

var low := 0.0 # ln(R)
var high := 40.0
for i in 80:
	var mid := (low + high) / 2.0
	var fraction := (exp(mid * PARETO_GAIN) - 1.0) / (exp(mid) - 1.0)
	if fraction > PARETO_RANGE:
		low = mid
	else:
		high = mid
var ratio := exp((low + high) / 2.0)

var span := MAX_STAT - BASELINE
_breakpoints.resize(MAX_BONUS + 1)
for b in MAX_BONUS + 1:
	var curve := BASELINE + span * (pow(ratio, float(b) / MAX_BONUS) - 1.0) / (ratio - 1.0)
	# Never more than +1 bonus per stat point.
	_breakpoints[b] = maxi(BASELINE + b, roundi(curve))

R comes out near 3,105, so each gap is about 17% wider than the one before. The maxi on the last line stops two breakpoints landing on one stat point, and it’s why the first 28 are one point apart, 11 to 38. After that the curve takes over: 43, 49, 56, 64, and on up to 208 for +40. 208 is 20% of the way from 10 to 999.

Stats.next_breakpoint(value) returns the next entry, which the pane prints as “next at 14”.

The formulas in scripts/party_member.gd work from bonuses, never from the stat. Each point of Tendons bonus is 4% more actions per second and 1.5% evasion. Each point of Fat bonus is 10 health and soaks 1.5% of every hit, up to 75%. Absorption was a flat amount at first, which made high-Fat characters nearly immune.

A character class is a “cut” of meat, and a cut is one dictionary of starting stats:

{
	"name": "Brisket", "blurb": "Dense and slow. Takes a long time to get through.",
	"muscle": 16, "tendons": 7, "fat": 18, "grey_matter": 8, "machine": 9, "caster": false,
},

Picking cuts for the party. Brisket's Tendons of 7 is a bonus of -3, so its 2.0 s melee cooldown shows as 2.24 s.

Counting every cooldown on one game clock

The game has one clock. Attack recovery, MP, monster respawns, trap cycles and the sun all count game seconds on it, and nothing keeps a timer of its own.

I wanted a day and night cycle with months and years, “and all of this should run off the clock”. The turn-based mode I plan can then move the same clock in jumps.

GameClock is an autoload (scripts/game_clock.gd) that holds one float, total_seconds: game seconds since midnight on 1 January, Year 1. In _process it adds delta * time_scale. The normal time_scale is 30, so a game minute passes every two real seconds. The calendar is integer division on that number, with 28-day months and a 336-day year.

Time only moves through advance():

func advance(game_seconds: float) -> void:
	if game_seconds <= 0.0:
		return
	var before := _whole_seconds()
	total_seconds += game_seconds
	var after := _whole_seconds()

	advanced.emit(game_seconds)
	if after / SECONDS_PER_MINUTE != before / SECONDS_PER_MINUTE:
		minute_changed.emit()
	if after / SECONDS_PER_HOUR != before / SECONDS_PER_HOUR:
		hour_changed.emit()
	if after / SECONDS_PER_DAY != before / SECONDS_PER_DAY:
		day_changed.emit()
	if after / SECONDS_PER_MONTH != before / SECONDS_PER_MONTH:
		month_changed.emit()
	if after / SECONDS_PER_YEAR != before / SECONDS_PER_YEAR:
		year_changed.emit()

It compares before and after, so a big jump fires each signal once. Skipping a month emits day_changed once, not 28 times.

Cooldowns are written in real seconds at the normal rate and converted once. GameClock.real_seconds(2.0) is 60 game seconds. A party member’s commit(action) stores that in cooldown_remaining. The party listens to advanced and calls each member’s tick(game_seconds), which subtracts.

Movement follows the clock too. GameClock.rate() is time_scale / 30, or 0 while the clock is stopped, and a monster multiplies its horizontal velocity by it before move_and_slide(). A laser grid has no timer at all. Its place in its on/off cycle is fposmod(GameClock.total_seconds / 30 + phase, on_time + off_time).

The sky (scripts/day_night_cycle.gd) reads GameClock.day_fraction every frame. The sun’s angle is (day_fraction - 0.25) * TAU, which puts sunrise at 6:00 and sunset at 18:00. That angle turns a DirectionalLight3D along an arc tilted 25 degrees. smoothstep on the sine of the angle blends the ProceduralSkyMaterial colors, the ambient light and the fog between day and night.

Aiming shots with the camera, not a target lock

Ranged attacks and spells fly to the point under the crosshair, and I aim them by turning and looking up or down.

The practice monster in the yard, with 1000 health and a small crosshair on the post beside it.

The first version locked onto the target for me. I didn’t like it: “Shots should fire straight in front of you.” So the lock came out.

Every physics tick, scripts/party.gd casts one ray from the camera along its forward axis for 20 m with intersect_ray, leaving out the party’s own body. Where it hits is aim_point, or the point 20 m out if it hits nothing. If the collider is a Monster, that monster is target.

Holding F calls attack() on every tick. Each living member whose cooldown has run out picks for themselves: the spell if they’re a caster with 10 MP, otherwise melee if target is within 4 m, otherwise a ranged shot. Melee calls target.take_damage() directly. The other two spawn a Projectile. The four members’ shots start spread across 0.9 m of the party’s front and each is pointed at aim_point, so they converge on the crosshair. They start up to 0.8 m ahead of the camera, because they filled the bottom of the screen on their first frame.

A Projectile is a Node3D with no collision shape. Before each move it sweeps a ray over the stretch it’s about to cover (scripts/projectile.gd):

func _physics_process(delta: float) -> void:
	var step := minf(speed * delta, max_distance - _travelled)
	var next := global_position + direction * step
	var query := PhysicsRayQueryParameters3D.create(global_position, next)
	var excluded := passes_through.duplicate()
	if shooter:
		excluded.append(shooter.get_rid())
	query.exclude = excluded
	var hit := get_world_3d().direct_space_state.intersect_ray(query)
	if not hit.is_empty():
		_impact(hit["position"], hit["collider"])
		return
	global_position = next
	_travelled += step
	if _travelled >= max_distance:
		queue_free()

Physics runs at 120 ticks a second and a party shot flies at 28 m/s, so each sweep is about 23 cm. The ray covers the whole step, so a shot can’t skip through a thin wall between two ticks. Whatever it touches first ends it, and takes the damage if it has a take_damage method.

Building the dungeon from a floor plan on a grid

The dungeon is nine rooms beyond the yard, with two loops and two ramps, opening onto a 200 m empty field. scripts/dungeon.gd builds all of it from a list of rectangles when the scene starts.

A laser grid in the gallery. Its beams are at 0.5, 1.1 and 1.7 m, on for 2.2 s and dark for 1.8 s.

The first room was built one hand-placed box at a time. The dungeon is generated so that walls, floors and roofs meet edge to edge, with no gaps and no overlapping faces.

The plan is 14 room rectangles and 12 doorways, in meters, each with a ceiling height and materials:

# 2. Gallery: long, narrow and tall. x -2..2, n 44..68.
_room(-2, 2, 44, 68, 6.0, Mat.PAINT, Mat.FLOOR)

Rasterize. The plan is drawn onto a grid of 0.5 m cells, 92 by 153. A PackedInt32Array records which rectangle owns each cell, or -1. The first rectangle to claim a cell keeps it.
Mark layers. An owned cell adds a floor slab below it and a roof slab above its ceiling. A doorway cell adds a hazard-striped band over the opening. An empty cell with an owned cell among its eight neighbors is wall, as tall as the tallest thing it touches. Each distinct (bottom, top, material) gets its own byte mask of the grid.
Merge. Each mask is covered greedily with as few boxes as possible:

func _emit_layer(mask: PackedByteArray, y0: float, y1: float, material: Material) -> void:
	for row in _rows:
		for column in _columns:
			if mask[row * _columns + column] == 0:
				continue
			var width := 1
			while column + width < _columns and mask[row * _columns + column + width] == 1:
				width += 1
			var depth := 1
			while row + depth < _rows and _row_is_set(mask, row + depth, column, width):
				depth += 1
			for r in range(row, row + depth):
				for c in range(column, column + width):
					mask[r * _columns + c] = 0
			var size := Vector3(width * CELL, y1 - y0, depth * CELL)
			var center := Vector3(
				GRID_X0 + column * CELL + size.x / 2,
				(y0 + y1) / 2,
				-(GRID_N0 + row * CELL + size.z / 2))
			_add_box(center, size, material)

Each box becomes a StaticBody3D holding a BoxMesh and a BoxShape3D of the same size. The materials are StandardMaterial3D with uv1_triplanar and uv1_world_triplanar on, so a texture lines up across every seam and no box needs UVs.

The party can’t step up a ledge, so the two 1.5 m height changes are ramps, 6 m and 8 m long. Each is a wedge built with SurfaceTool, with a ConvexPolygonShape3D of its six corners to walk on.

Eleven doors and fourteen traps sit on top, placed by world coordinates in scripts/dungeon/dungeon_content.gd. A trap has no Area3D. Every physics tick it turns the party’s position into its own local space with to_local() and compares numbers.

Splitting the work across git worktrees

For the first 99 minutes there was no version control. Then the project became a local git repository with no remote, with main in one folder and each branch checked out in a folder of its own beside it.

Five monster types built in one worktree while doors and traps were built in another. There is only one monster model, so they differ by tint and height.

I wanted to work on the map while features were being built. A git worktree folder is a whole Godot project that opens separately. Godot’s import cache, .godot/, is in .gitignore, so each folder imports the assets once and keeps its own cache. A .gitattributes line, * text=auto eol=lf, keeps line endings the way Godot writes them.

The bigger pieces each went to a background agent in its own worktree. An agent leaves its changes uncommitted. Nothing is merged into main until I say “merge”, and then the clean worktrees are fast-forwarded to the new main.

The first room, the opening’s story, the dialog and the interface wiring were all in one script, scripts/vat_bay.gd, so two branches would collide there. The rule was that each piece goes in a new script and touches existing files as little as it can. The dungeon’s whole footprint in vat_bay.gd was a doorway cut in the yard’s north wall and one line, add_child(Dungeon.new()).

Monster behaviour got the same shape. Monster is a CharacterBody3D that supplies verbs (move_toward_point, face, can_see, try_melee, try_ranged), and a behaviour is a small script in scripts/ai/ that only decides which verbs to call:

func fight(monster: Monster, party: Party) -> void:
	var distance := monster.distance_to(party)
	if distance > monster.melee_range * 0.7:
		monster.move_toward_point(party.global_position)
	else:
		monster.stop()
	monster.face(party.global_position)

	if distance <= monster.melee_range:
		monster.try_melee(party)
	elif _sees and distance <= monster.ranged_range:
		monster.try_ranged(party)

That’s the whole hybrid type (scripts/ai/hybrid_ai.gd). The five types share ChaseAI, a state machine with three states: idle, chase and return. A monster notices the party within 18 m in plain sight and gives up beyond 32 m, or after 8 s without sight. There’s no pathfinding, so a monster that hasn’t walked home in 45 s is put there.

The night had one merge conflict, where two branches each added a line at the same spot in scripts/party.gd. Both lines were kept. It also had one duplicate. My request for the monster agent reached the doors-and-traps agent too while that one was being resumed, and it started an agent of its own for the same job in a new worktree. The duplicate was stopped, but its worktree is still there.

Nothing was played by hand that night. Every check was a scripted run with simulated key presses and screenshots.

Also done

A setting. The brick test room became Culture Bay 7, a worn-down sci-fi meat plant where a party of four is grown at the Meat Machine.
An NPC I can talk to with E. A chat bubble by his head lists numbered options, grey until I’m within 3.5 m.
One shared party inventory on the I key. Everyone starts with a stock heart, lungs and liver that change nothing and are flagged requires_surgery, so unequip() refuses them.
Sound: 135 free clips from Kenney, plus ambience loops made by a Python script.