Generates the world in square tiles that can be streamed in any order. Give it a latitude and longitude and it builds the tile containing that point. Settlements (villages, towns, cities up to 4000 houses) are placed from the map and can span several tiles. Main roads run town to town and lanes cross the country between them, and a dense railway network joins the settlements. The rest is mostly farmland with hedgerow fields, farms, copses and orchards, broken by tracts of woodland and rough, unused land. A settlement has a centre with a high street, a church and (for towns and cities) a market square on the main road, then a Victorian terrace core, a garden-suburb ring and ribbon semis along the radials, a station it grew round, and its industry: a gasworks in every town, mills and works in the industrial towns, works and trading estates on the outskirts. Out in the country, away from the houses, are collieries, quarries, brickworks, gravel pits, sawmills and each town's sewage works. Output is a PNG plan in aerial-photo colours and a JSON layout per tile, meant for Unreal (PCG / Blueprint) or Blender.

No roundabouts anywhere, and culs-de-sac just end: both are post-1930 things.

uv run towngen.py --grid 20 --detail 3

That is the standard example: the 20 × 20 tiles (39.6 km square) round the default location, stitched into one overview, plus a readable 3 × 3 detail (5.94 km) round the centre tile. The default location (52.1169, −1.3393) is tile (5, 6). With world seed 1 it holds the core of a city of about 2,100 houses, built tighter than most (density 1.53, see Settlements), that spreads across the corner of four tiles.

uv run towngen.py --lat 52.117 --lon -1.3685

One tile: its JSON and a PNG.

Every run takes the next build number from out/build.txt and puts it in every file name, so runs never overwrite each other and can be compared side by side: out/grid_<i>_<j>_<N>x<N>_s<seed>_b0001.png, out/detail_<i>_<j>_<M>x<M>_s<seed>_b0001.png, out/tile_<i>_<j>_s<seed>_b0001.json (and .png) for one tile. The run prints every file with its full path.

A grid run hands the tiles to worker processes in 2 × 2 blocks (neighbours share a worker's cache of settlements). Each worker generates a tile, draws it at the overview scale and sends back the picture, what crosses each of its four edges (edge_signature) and what it placed (tile_report); the main process stitches the pictures and does the checks from those, so no worker needs another's tiles. It prints the cities and towns inside the grid, how many of the buildings, gates, stiles and stations that belong wholly inside it were placed (each exactly once), the railway length, and the seam check, e.g. seams: {"edges": 760, "road_crossings": ..., "mismatches": []}.

Farmland tiles take under a second. A tile that touches a settlement also generates the whole settlement once (cached for its neighbours in the same worker): a few seconds for a town, more for a city, because the fit may generate up to four times. No system Python is needed: uv manages the interpreter and the dependencies (numpy, shapely, matplotlib) from pyproject.toml.

Generation has three levels. Each one is a pure function of the world seed and the map, so any tile can be built on its own, in any order, and still match its neighbours.

latlon_to_world projects lat/lon to metres east/north of WORLD_ORIGIN (equirectangular for now; swap in the map's own projection, e.g. British National Grid, as long as the game uses the same one). The World class works things out on demand around whatever a tile asks for, and caches them, since neighbouring tiles ask for the same things.

The graph rules are local: whether two nodes are joined depends only on nodes within the road's length of them. That bounds what a tile has to look at. The hash is plain splitmix64 on uint64, so the engine can reproduce the world bit-for-bit.

A settlement is generated once, in its own box, by World.town. The world roads ending there arrive as ports where they cross the box edge. Inside, the main road runs through the centre between the two most nearly opposite ports (main roads before lanes), and the other ports join it as radials. A lane into a town is built up like a main road. Each road runs straight for PORT_LEAD in from the box edge, along the same line as the world road outside, so the two meet exactly. Then come the districts, high street and so on below. Land between the houses that is big enough to farm (or touches the box edge) is handed back to the tiles; the rest (lots, roads, greens, parks, allotments, churchyard) is the settlement's footprint. Where its roads run through the land handed back, the settlement draws roadside hedges the same way the holdings do, so a hedged main road stays hedged up to the first houses.

The railway's chord through the box is a fixed corridor. Right after the main roads, the settlement puts its station on the chord, sliding it along from the point nearest the centre until it is clear of them (STATION_LAYOUTS):

Platforms are 80 m (village) to 230 m (city) long. Loops and bays leave the running line on leads: reverse curves of two RAIL_LEAD_RADIUS (100 m) arcs, so a terminus's run goes on 100 m past its platforms to make room for them. The station building with its canopy stands on the town side with a forecourt and an approach road. There's a signal box, and a footbridge when there are platforms on both sides. No goods yard: goods sidings will come with industry. Main roads may bridge the tracks past the platform ends; only if no spot along the chord fits is the layout made smaller. After that, every other street keeps clear of the railway and station, and lots stay off them. Main roads cross the chord on a bridge; lanes and streets cross at level crossings.

The towns were there before the railway, and grew round their stations: the station quarter (STATION_QUARTER, 150 m round a village station to 380 m in a city) is built up like a town centre. Station Road runs along the line on the town side past the forecourt, out to the main roads either way, and a second street runs along the far side off a main road that bridges the line, so both sides are built up. Along the main roads and these streets near the station the frontage is the station mix (STATION_MIX): shops, pubs, a hotel, warehouses and terraces; side streets grow off them as in the core.

A settlement's industry comes from the world (World.town_works, a stand-in for map data) and is placed right after the station, before the other streets, which keep off it:

Every works is reached by road. One that wants a siding goes alongside the railway, with a lead off the running line on a reverse curve onto its loading tracks (the others branch off the first the same way), at the first spot where a street can be brought round to its front (or in at an end) without crossing the line; otherwise it fronts a main road, with a drive in through a gap between its buildings (or up to the gate in its fence), and, if it wants rail and the line is within 300 m over open ground, a siding from the line in along its back. Each kind has its own plan (works_plan), in its own frame with the loading tracks along the back: buildings with their heights and roof form (pitched, sawtooth north lights, flat, round for gasholders and filter beds), and areas for yards, pits stepping down in benches, clay pits, flooded workings, spoil tips and sludge beds.

Settlements differ in how tightly they are built: the map gives each its own density (region_info): about a third of the towns and cities are dense (1.5–1.9, smaller and packed tighter for the same houses), the rest 0.85–1.2. --density multiplies it.

Footpaths reach the settlement at its box edge like roads do, and it takes each one on to the church (to the high street if it has none), ending at the church wall. Before any lots are placed, the path gets a 3 m corridor through the built-up area that lots are cut back from, so it passes between the houses (a ginnel) rather than through their gardens. Where the corridor turns out to border only farmland, it goes back to the fields, and the path crosses them with stiles like any other. The world adds the stiles for the settlement's part from its path, the field hedges in its box and its roadside hedges, skipping anything in the town itself.

From the house count the generator picks a kind and splits the houses between districts (village: no core; town: 30 % core; city: 45 % core), turns each share into an area with a measured gross density, and gets the district radii. The district boundary is perturbed by angle so it is not a circle. After generating, the dwellings are counted and the radii re-fitted (secant on log count vs log radius, best of up to four runs, at most RS_MAX) to land within about 10 % of the target.

Tile (i, j) covers [i·S, (i+1)·S) × [j·S, (j+1)·S). World.tile gathers the world roads crossing it and cuts them out of the boxes of the settlements they end at (the settlement routes them there). It takes the slices of the settlements whose boxes overlap it: lots, greens, roads and road polygons are clipped to the tile. Buildings, garages, sheds, cars, trees and the church go to the tile that holds their centre, so each exists exactly once even when it straddles a seam. The land left over (the tile less road polygons and settlement footprints) gets the world's field pattern: every field, hedgerow, copse, orchard, farm track and footpath reaching the tile is clipped to that land (so footpaths break at the roads they cross). Hedges get a gap of GATE_GAP either side of each gate, STILE_GAP either side of each stile and TRACK_GAP either side of each farm track, cut from world positions so a gap spanning a seam is the same on both sides. A track through a copse cuts a ride through it, and hedges stop at the wood's edge. Farmsteads, gates, stiles and pitches go to the tile holding their centre. The tile scatters its own trees over its own land (in fields, in copses, along hedges but clear of gates and stiles and with no more than a fringe of crown over a road or track), so they need no coordination.

Everything that crosses a seam matches: roads, pavements, lots, fields (by id), hedgerows, woods, farm tracks, footpaths, railway land and track. Railway lines are drawn whole on every tile they cross, towns included (towns are built round them). Stations, station buildings and rail crossings go to the tile holding them.

The high street is the stretch of main road within R_hs of the centre: continuous shop frontages right on the pavement with deep plans and yards behind, a pub or two and civic buildings, mixed with cottages in a village. A church with a tower sits in a churchyard beside the main road; towns and cities also get a market square, a paved rectangle off the main road that the frontage walker wraps shops around.

Every candidate road keeps a minimum clearance from existing roads outside a disk around its junctions, which spaces parallel roads about two garden depths apart.

The kerb outline (carriageway + pavement, unioned) is walked as rings with the land on the right. Lots are chopped off in runs whose typology comes from the district style of that spot, or from the high-street mix near the centre. Each lot is the strip between the kerb and an offset curve depth metres out, clipped against roads and earlier lots; corners where the kerb turns sharply right (junction inner corners) are skipped. A building footprint is fitted inside each lot; lots where none fits are dropped. Then driveways, garages, sheds, outriggers and garden trees per style.

Small leftovers inside the town are green (dense trees, so back-to-back garden gaps become tree corridors), alley (Victorian back lanes), village_green, churchyard, and for larger enclosed pieces park (perimeter trees, a pitch if it fits) or allotments (strips of plots with tiny sheds). Everything else is handed back to the tiles, which lay the world's farmland over it (see World and Tiles above).

All tunables are in Params (per style, overridden in STYLES) and the constants at the top of towngen.py; the town plan numbers are in Town.plan_layout.

One file per tile. Units: metres, tile-local (origin at the tile's SW corner), +y north (plan view); the tile sits at meta.tile.world_offset_m. Angles in degrees, CCW from +x. For Unreal: cm = m * 100, UE.X = x, UE.Y = -y, yaw = -rot_deg.

Houses in the same run share a type and roof colour; a terrace or shop run is one contiguous block, a semi run a mirrored pair sharing the party wall. Ids of settlement content (S3_4.h120, S3_4.l88, ...) are global, so the same object can be recognised from any tile.

• Rivers and canals, and the mills, wharves and gravel workings that go with them.
• Pit villages by the collieries; wagons in the sidings.
• Railways shaped by terrain (embankments, cuttings, viaducts), once heights are in.
• Ribbon service roads, a village pond, a school on the recreation ground.
• Unreal import: spawn roads as splines, buildings and trees as HISM instances from the JSON (PCG or a Blueprint/C++ importer).
• Real map data in region_info (population, land use) instead of the hashed stand-in.
• Footpaths between neighbouring villages, and a lych gate where a path enters the churchyard.