Road view (top-down)

What it does

A source describes the ground as cross-sections: at each distance along the road, the spans across it and the surface of each, such as grass, shoulder, carriageway, median, water, bridge deck, ice or a puddle. It can add placed features (boathouses, bridge rails, signs, posts) and painted markings (lane lines and dashes). The view samples the source in rows, merges identical rows into runs, and draws each run as one tiled sprite whose texture is anchored to the world, so neighbouring sprites continue the pattern and a moving sprite never slides its texture.

Every sprite has a stable key, so it always shows the same ground and moves exactly with the camera, interpolating smoothly between steps. Chunks are cached until the source says it has changed, evicted once they are behind the view, and hidden sprites are pooled. A camera jump, such as a respawn, can cut the interpolation with one flag.

You do not need art to start. The view paints its own surface textures (grain, speckle, grass, flowing water, ice, snow, sand, gravel, planks, stripes and checks) and roadside art (trees, bushes, pines, rocks, cacti, houses, barns, boathouses, buoys, lamps and more), or uses your atlas frames instead. Scenery is scattered deterministically on a world grid and kept only where its whole footprint fits on the surfaces you name, so trees never stand in the river.

Features

• Ground as data — spans, features and markings from any source, with a revision to say when it changes.
• No seams — world-anchored tiled sprites with stable keys, so forks, merges, narrowing and widening scroll cleanly.
• Painted surfaces — twelve patterns from grain to flowing water, or your own atlas frame, per surface.
• Built-in roadside art — seventeen kinds, from trees and cacti to boathouses, bridge rails, buoys and lamps.
• Deterministic scatter — scenery placed on a world grid where its footprint, plus clearance, fits.
• Regional looks — lookAt switches a surface to a region's version, so one road changes palette as it goes.
• Day to night — setLight tints the whole view toward a night colour.
• Any direction — scroll up, down, left or right, or draw a static map.
• Static circuits — polygonSource rasterises filled polygons into the same spans.
• Headless planning — rows, runs, mapping and scatter are pure helpers you can test without a screen.

Good for

• Vertical scrolling road games with combat, in the style of Spy Hunter, with river and bridge sections.
• Top-down chases and patrols — a road that forks, narrows and crosses water under a car the game draws.
• Top-down circuit racers in the style of Super Sprint — tarmac, kerbs, sand traps and a pit lane as polygons.
• Boat races and river runs — water spans between banks, with buoys as course markers and flow on the water.
• Horizontal scrollers on a road, with the axis turned to scroll left or right.
• Any game with its ground as data that wants it drawn cheaply in 2D sprites.

Make it yours

Everything is set per create() call. The source supplies the ground; surfaces gives each surface a colour, pattern, detail, density, tile size, flow or atlas frame; background fills where no span covers; scenery rules say which kinds grow on which surfaces, how far apart and how often; axis maps the road to the screen; scale, viewport, rowHeight and resolution set the size and the sharpness of diagonals. The game draws its own vehicles over the view, using toScreen to place them.

Two very different uses: a vertical road that forks around medians, crosses a bridge over a flowing river and turns to night, with trees scattered on the grass and dashed lines that keep their place; and a static top-down circuit, its tarmac ring, kerbs and sand traps rasterised from polygons and drawn with axis: 'down' as a fixed map.

A quick look

A road with painted surfaces and scenery, drawn every step and lit for night:

const view = game.roadViewTopdown.create({
  source, background: 'grass', axis: 'up', scale: 2, viewport: { width: 480, height: 480 },
  surfaces: { road: { colour: '#2c2c30', pattern: 'grain' }, water: { colour: '#1a46a8', pattern: 'water', flow: 30 } },
  scenery: [{ on: 'grass', kinds: [{ art: { paint: 'tree' }, width: 24, length: 22 }], spacing: 30, chance: 0.6 }],
});
game.step('draw', dt => view.draw({ u: cameraX, v: distance, y: 344 }, { time: clock, snap: respawned }));
view.setLight(night, '#1a2a5a');

Works with

• road-data — a ready source for any road file through its top-down source.
• road-combat — its course is the source for a scrolling combat road.
• track-racer — rasterise a circuit's surfaces with polygonSource and draw them as a static map.
• particles-2d — tyre smoke and splashes over the ground.
• typography — the HUD.
• road-view-pseudo3d — for a behind-the-car pseudo-3D road instead.

Good to know

• Edges are drawn as rows, so a diagonal edge is a staircase of rowHeight world units; a smaller row height is smoother but costs more sprites.
• A source that changes ground already drawn must bump its revision.
• Day and night is a tint of the view's sprites; headlights and other lights are the game's own sprites.
• Nothing is painted in headless runs: the frames are registered without pixels.
• The view draws the ground only; vehicles, enemies and effects are the game's.