ressort-top-down-world

name

ressort-top-down-world

description

Build a top-down (overhead) world on the machin-ressort engine — an irregular city or map generated offline into a tile grid, flood-field routing, lane-holding traffic, and the handling model that makes a top-down vehicle feel like a vehicle. Use when the camera looks straight down rather than from the side, when a map needs generating rather than authoring, or when anything in the world has to find its way somewhere.

The world seen from above

A side-scroller's world is a heightfield and a parallax stack. A top-down world is a plan: a grid of cells, most of them solid, with the playable space cut through them. Almost everything below follows from that one difference, and most of it was learned twice before it was written down.

The engine parts are engine/25_grid.src (grid, flood routing, sight lines, file format) and engine/65_bake.src (the full-circle sprite bake).

Rule 1 — generate the plan OFFLINE, into a file

The first version of our city was a function: which cell you stood on was arithmetic on a fixed block grid. That is elegant, costs nothing to store, and produces a town where every block is the same square and every junction is the same junction — a street plan a player has seen in full after ten seconds.

Generate it once, write it out, load it back:

./bin/game gen --seed 7 --out city.jsonl     # a separate program
./bin/game --city city.jsonl                 # play it

The payoff is not file size, it is that the plan becomes data you can look at: diffed between seeds, hand-edited, regenerated, replaced wholesale, and re-skinned without touching the code that draws it. grid_encode/grid_decode do it as one header line and one run-length row per line — 168² cells is 14 kB. Keep a fallback that generates at startup when handed no file, or the game has a bootstrapping problem the first time someone clones it.

Rule 2 — irregular means SUBDIVISION, not jitter

Do not build a grid and then perturb it; cut the map up instead. Take the whole rectangle, put a street across it somewhere that is not the middle, and do the same to both halves until the pieces are block-sized.

Because a cut only ever spans the piece it divides, streets do not line up across the map. That single property is what gives you T-junctions, streets that run for three blocks and stop, and a block twice the size of its neighbour — none of which you have to ask for.

Then dress each leaf: a pavement ring, buildings in lots divided by a one-cell alley, a notch out of a corner, and every so often a park or a yard instead of buildings. Two dozen lines, and it is the difference between a plan and a grid.

Assert the irregularity, or it will quietly regress to a grid: walk several scanlines, collect the gaps between streets, and require more than a couple of distinct values.

Rule 3 — one integer per cell, and passability is a BITMASK

Store the cell's kind and its decoration in one integer — TL_BLDG + tone rather than two parallel arrays. Then the engine's Grid is a view over the same array rather than a copy, and the file format falls out for free.

Order the values so that everything from the first solid kind upward is solid. Passability is then a bitmask over cell values, and one map serves every kind of mover without a second copy:

MASK_DRIVE = 1        // roads only
MASK_WALK  = 7        // roads, pavements, parks

The trap this creates, which you will hit: once a cell carries a tone, cell == TL_BLDG() matches only tone zero. One place in our generator still compared a raw cell to a kind and five sixths of the kerbs silently stopped being generated — the pavement count fell 4% and nothing else complained. Ask for the kind through an accessor everywhere, and assert both halves: that buildings do carry tones, and that a cell's kind never leaks one.

Rule 4 — routing is a FLOOD, not a heuristic

Anything that has to get somewhere floods outward from the destination, breadth-first, once; every reachable cell gets its distance, and everything heading there reads the cell under it and walks downhill.

f := flow_build(city_grid(c), tx, ty, MASK_DRIVE())
ax, ay, ok := flow_aim(f, city_grid(c), x, y, TILE(), 5)   // 5 cells ahead

We wrote the other thing twice — travel along the street you are on until you are level with the target, then turn. On a regular grid it is optimal and free. On an irregular plan it is a guess, and it fails by pressing into a dead end it cannot see round, forever. It also fails invisibly: a stopped vehicle looks like a stopped vehicle, and two rounds of screenshots found nothing. One --trace line a second found it immediately.

One flood is about a frame of drawing and is shared by everything with the same destination — which is what makes it affordable for a crowd. Rebuild only when the destination changes cell; police chasing a player need one rebuild per cell the player crosses, not per tick.

Aim several cells downhill rather than at the next one, or the mover twitches instead of steering. Off the network entirely (shunted onto a kerb), flow_aim heads for the nearest cell that is on it — without that, anything pushed off the road is stuck for good.

Rule 5 — traffic holds a lane it has to MEASURE

With irregular streets there is no block size to take a modulo of, so a lane centre cannot be computed — it has to be found. Scan out along one axis for the nearest road cell, widen to the whole contiguous run, take its middle, and offset to one side so oncoming traffic passes instead of colliding.

city_road_x originally returned the block's own carriageway. On the far pavement the nearest road is the next block's, so everything self-driving was steered through the building between them. Nearest, always — and assert it: the middle of a street must itself be a street.

The same measurement tells you which way a street runs (compare the run length in x against y), which is what a mover needs to decide whether it may travel along the road it is standing on.

Rule 6 — a top-down vehicle goes where it POINTS

Three numbers, and all three were wrong in our first cut.

Grip. Velocity leans toward the nose at a rate, rather than snapping to it: v += (fwd·(v·fwd) - v) · clamp(GRIP·dt). Snap it and the car is on rails — no drift, no handbrake turn, every corner identical. Omit it and it is a spaceship. This one blend is most of what "feels like driving" means.

Steering must fade at BOTH ends. It has to build from a standstill, or a parked car pirouettes and is a tank; and it has to fall away with speed, or the fast vehicles are unsteerable at exactly the speed you most want to steer them.

Drag is for coasting only. A linear drag term makes the real top speed power/drag, approached exponentially — see ressort-side-scroll-world, where the same trap cost a saloon two thirds of its rated speed.

Braking acts against travel, not against the nose, or braking mid-slide accelerates you sideways. Move one axis at a time against the map so a glancing hit slides along a wall instead of stopping dead.

Rule 7 — the crowd needs separating, and the pedestrians need a cooldown

Once the streets are busy enough to look alive, two things start looking broken.

Vehicles interpenetrate. A circle test is enough — a box test on a rotated sprite wants the separating-axis theorem and nobody can tell at this size. Push apart by mass ratio so the bus shoves and the sports car gets shoved, and scale the damage of a shunt well below a wall impact: at full rate a truck clipping you at 30 m/s removes half a car, and every mission vehicle dies in traffic.

Pedestrians spin. Ours turned 90° on every blocked tick — 5400°/s, which reads as a figure drilling into the pavement. Turn at most a few times a second, toward a direction that is actually free (try left, then right, then back), and stop re-aiming a fleeing one when the player is standing on top of it: "away from you" flips every tick at zero distance, and a figure that reverses at 60 Hz reads as two figures.

Rule 8 — density is per YARD, not per magic number

Population as a fraction of the map: cars = len(road_cells)/42, people = len(pavement_cells)/13. A city twice the size then needs no retuning, and a screen shows the same number of things wherever you are. Ours was a constant, and tripling the map turned a busy street into an empty one with no code change to blame.

What to assert without a window

• every open cell can reach every other (an unreachable street is an unfinishable objective)
• following the gradient from the far corner arrives
• an aim point is on the network, and far enough ahead to steer at
• the middle of a street is a street
• no two cells of the same block have the same size gap on every scanline
• spawns land on ground the thing spawned can actually occupy
• a written plan reads back cell for cell
• a blocked pedestrian turns a handful of times a second, not sixty

Then render it and look, because numbers can be right while the render is wrong. The lane markings were absent for a week: the code asked whether a cell's centre was the centre line, which is never true on a road of even width.