Map-making — tile maps on the Deckline

How to represent, author, generate, render, and scroll tile maps on the KN-86 — large worlds you pan a viewport across, built from a palette of terrain glyphs.

Source / lineage: APX Mapmaker (Stephen W. Hall, 1982) — a tool for authoring large, fine-scrolled, multiscreen tile maps from a palette of redefined characters (“map elements”). It’s the authoring side of the Eastern Front (1941) scrolling-tile-map lineage; its own bibliography cites De Re Atari and two books in influences/synthesis-atari-graphics.md. The technique ports almost 1:1 onto KN-86’s cell grid + the shipped soft-glyph plane.

Authority / neighbours: ADR-0052 (soft-glyph tiles), world-engine.md (generated maps), animation.md (moving surfaces), screen-design-rules.md (Rows 0/74 are firmware-owned). Build task: GWP-672.

---

1. The model: a map is a grid of tile codes, bigger than the screen

A map is a 2D grid of tile codes stored row-major as a byte array — tiles[y*width + x]. Each code names one map element (water, forest, hill, road, wall, node…). KN-86’s cell grid is already exactly this shape, so a map is just a grid that is larger than the visible content area (Rows 1–73, 128 cols), and the screen is a viewport onto it. Mapmaker maps run up to 128 wide × 255 tall (capped ~4–8 KB of cells); the same envelope is reasonable here.

The viewport moves; the map holds still. Everything below is in service of: pick the tile vocabulary, fill the grid, scroll a window across it.

2. Tiles = the glyph palette

The tile vocabulary is a set of glyphs. On KN-86 that means the soft-glyph plane (ADR-0052 — mutable 8×8 slots) plus the static Code-Page (box-drawing, the ░▒▓█ shade ramp, icons). Mapmaker’s lesson is that a map is only as good as its tile set, and the craft is in the tile design:

• Seamless / edge-matching terrain. A redefined glyph can fill the whole 8×8 (run edge-to-edge), so forests and water tile without gaps. Design connecting terrain so edges meet at common positions — every river tile terminates at the same point on each side, so adjacent river tiles join (a Wang-tile discipline). Give each terrain ≥2 variants for irregularity; coastline wants ~4 for an authentic, non-repeating look.
• Field vs ground. A tile can be a shape drawn on the background (field), or the background showing through an outlined fill (ground). Field/ground reversal is a composition lever — most tiles are “field,” but a ground pass can read as a stunning inverse.
• Monochrome → dither, not colour. Mapmaker leans on 4 colour registers + background to distinguish terrain. KN-86 is single-foreground amber, so terrain is distinguished by glyph shape + dither density (denser dither = “darker”/deeper terrain) — the monochrome analog of the colour map (see animation.md §dither and influences/synthesis-atari-graphics.md “mono → dither”). A legend, not a palette.
• Budget the palette. Mapmaker caps at 64 shapes and warns against too many one-off tiles. Here, the soft-glyph plane is 16 live slots; combine with Code-Page shades/box glyphs for the rest. Reuse aggressively; a small, well-chosen tile set reads better than a sprawling one.

3. Viewport + fine scroll

The viewport is a window of (≤128 × ≤73) cells onto the larger map. Scrolling moves the window — fine (smooth, sub-cell pixel offset) until it crosses a cell boundary, then a coarse step reloads the newly exposed row/column. Clamp the window to the map bounds (no scrolling past the edges). Mapmaker’s SCROLL is a vertical-blank routine doing exactly this (fine-scroll registers + LMS reload); on KN-86 the equivalent is a render-side camera offset, ridden on the idle-timer/frame loop. Fine scrolling is the book-1 thread in influences/synthesis-atari-graphics.md §2.

Map surfaces draw in Rows 1–73 only (Row 0 status / Row 74 action are firmware-owned — screen-design-rules.md). For map overlays — routes, borders, a reticle, “as-the-crow-flies” lines — the render/half-block-line primitive (Bresenham over the 128×150 half-block canvas) is already in the runtime; use it rather than hand-rolling line drawing.

4. The .map data format

Keep it a compact byte blob (a cart data asset, or the World Engine’s output). Mapmaker’s file is [width][height][5 colour-register bytes][tile grid]. The KN-86 analog drops colour and adds a legend reference:

width   : u8        (cells, 22..128)
height  : u8        (cells, 13..255; width*height bounded)
legend  : ref       (tile-code -> {glyph, terrain semantics, dither, passable?})
tiles   : u8[w*h]   (row-major tile codes)
[meta]  : name, origin/seed, spawn points, region tags…

The legend is the important addition: it binds each tile code to its glyph, its terrain meaning, its dither level, and gameplay attributes (passable, cover, cost). That’s what lets the same grid drive both rendering and mechanics (pathing, line-of-sight, collision = “is the next cell passable?“).

5. Two paths to a map: authored vs generated

Both produce the same .map model — they differ only in who fills the grid.

• Authored. Hand-placed tiles via a Mapmaker-style editor (cursor + tile palette + scroll). Build this as a workbench/web tool or an on-deck editor; the glyph/sprite-editor thread (from the Atari synthesis) is the tile-design half of it. Good for set-piece maps with intent.
• Generated. The World Engine (world-engine.md) procedurally fills the grid — “random within form” (a bounded skeleton with randomised detail): cellular-automata caves, noise terrain, BSP rooms, drunkard’s-walk corridors, graph→topology. A seed makes it reproducible; the same seed → the same world. This is the path that fits the deck’s offline-first, seeded-coherent world model.

Most Deckline maps will be generated (World-Engine-backed) with optional authored set-pieces stamped in.

6. Applications on the Deckline

• World-Engine world surface — pan a generated world (the spatial face of a mission’s world; world-engine.md).
• Network topology map — the cyberpunk-native case: nodes/links/subnets as terrain (the RIPSAW / bzbx lineage; “an on-glass tick reveals a host”).
• Dungeon / overworld — explorable gameplay maps (experience-tier, ADR-0047).
• Region / star map — mission-board geography; pick a contract by place.
• Minimap / radar overlay — a compressed map inset using the shade ramp + render/half-block-line.

7. What to build (→ GWP-672)

The map system, in dependency order:

1. .map format + loader (§4) — the byte model + legend.
2. Tile-map viewport renderer — blit a window of the grid using soft-glyph/Code-Page tiles; clamp to Rows 1–73.
3. Fine-scroll camera (§3) — sub-cell offset + coarse reload + bounds clamp.
4. Starter terrain legend — an edge-matching tile set (≥2 variants/terrain), the KN-86 ALLPRPS.SET equivalent.
5. One concrete map surface — recommend a World-Engine world view or a network-topology map; record on-glass.
6. (Later) an authoring editor.

Dependencies already in place: soft-glyph plane (shipped, ADR-0052), render/half-block-line (in runtime), the World Engine (for generated maps). The new work is the format, the viewport renderer, and the scroll camera.

8. How agents should use this guide

• Adding any map / world surface? Use this model — a grid of tile codes + a legend + a fine-scroll viewport — not a bespoke per-cart scheme.
• Tiles are soft-glyphs + Code-Page; design edge-matching terrain with variants; encode depth as dither density, never colour.
• Don’t hand-roll line drawing for overlays — render/half-block-line exists.
• Generated maps go through the World Engine (“random within form” + a seed); authored maps use the editor path. Same .map output.
• Maps draw in Rows 1–73; keep the firmware chrome clear.