magnus919_agent-skills/ascii-city-engine/references/engine-architecture.md

Engine Architecture

Coordinate and world model

Use a right-handed local coordinate system in meters: x east, y north, z up. The terrain is a regular grid with origin (ox, oy), spacing r, and elevations H[row][col]. Bilinear interpolation defines the ground:

terrain(x, y) -> z | null
u=(x-ox)/r; v=(y-oy)/r
z=(1-fu)(1-fv)H[j][i] + fu(1-fv)H[j][i+1]
  + (1-fu)fvH[j+1][i] + fu*fvH[j+1][i+1]

Return null when outside the grid or any interpolation corner is null. A null cell is darkness and is not walkable.

A building record contains:

{id, footprint:[[x,y],...], base_elev_m, height_m, color,
 provenance:{source, url?, license?, retrieved?, confidence:0..1}}

The closed footprint is solid from base_elev_m to base_elev_m + height_m. The camera is {x,y,heading_rad,fov_rad,eye_height_m}; derive its vertical coordinates from terrain rather than storing an independent flying z.

Pedestrian physics

At the accepted position:

feet_z = terrain(x, y)
eye_z  = feet_z + eye_height_m

For proposed horizontal movement from p0 to p1:

z0 = terrain(p0.x,p0.y); z1 = terrain(p1.x,p1.y)
if z1 is null: reject
height_delta = abs(z1-z0)
horizontal = hypot(p1.x-p0.x,p1.y-p0.y)
slope = height_delta / max(horizontal, 1e-9)
if height_delta > max_step_m or slope > max_slope: reject
if player circle at p1 touches/intersects any building footprint: reject
otherwise accept; feet_z=z1

Use max_step_m=0.45, max_slope=0.35, and player radius 0.30 m as starting values. Point-in-polygon plus minimum point-to-edge distance detects circle/polygon intersection. Treat equality as collision. If a diagonal proposal fails, test its x-only and y-only components separately to slide along walls without crossing them.

Raycast-to-ASCII-grid pipeline

Render a fixed grid such as 100 columns by 36 rows on Canvas 2D. Each screen column casts a horizontal ray at angle

ray_angle = heading - FOV/2 + (column+0.5)/columns * FOV
ray(t) = camera_xy + t * [cos(ray_angle), sin(ray_angle)]

March t from a near plane to max_distance (for example, 150 m) in increments no larger than half the terrain resolution. At each sample:

1. Evaluate terrain. Null means no ground sample.
2. Test whether the point lies in a building footprint. The first solid hit supplies wall distance, top elevation, stable color, and building ID.
3. Project vertical values using corrected distance d=t*cos(ray_angle-heading) to avoid fish-eye distortion: screen_y = horizon - focal_px*(world_z-eye_z)/max(d,epsilon) where focal_px=(columns/2)/tan(FOV/2).
4. Fill the visible wall interval and terrain below it into character-grid cells only when nearer than that cell's depth buffer.
5. If the ray reaches maximum distance without geometry, explicitly reset the column to sky/darkness; never reuse a previous frame.

Pseudocode:

clear(chars=' ', fg=sky, depth=infinity)
for sx in columns:
  ray = make_ray(sx)
  for t in march(near,max_distance,step):
    sample terrain and solids
    project visible span
    for sy in span: if corrected_distance < depth[sy][sx]: write cell
    if opaque building covers remaining span: break
paint character grid to Canvas 2D

Glyph density, brightness, and color

Map normalized distance q=clamp(d/max_distance,0,1) to a concrete near-to-far density ladder:

q < .12: '@'
q < .25: '%'
q < .42: '#'
q < .60: '+'
q < .78: ':'
otherwise: '.'

Scale foreground brightness with brightness=0.25+0.75*(1-q)^1.4; terrain can use .,:;+=xX#@ according to both distance and local slope. Glyph cell dimensions stay fixed; apparent size changes through projected vertical span, while density and brightness fall with distance.

For stable building color, honor a valid pack-provided color. Otherwise hash the UTF-8 building ID with FNV-1a, select hue hash % 360, and use fixed saturation/lightness such as hsl(hue 65% 58%). Recompute deterministically or cache by ID; never pick random colors per frame. Adjacent equal colors are acceptable.

Dynamic cars or pedestrians may be depth-tested billboard ASCII sprites anchored at terrain(x,y). They are optional and do not alter static collision.

Street furniture, signs, and surface cues

A dense pack adds three enrichment layers, all depth-tested against the same buffer:

• Props (street furniture). Each prop renders as a one-cell billboard at terrain(x,y) plus a small height offset, using the documented per-kind glyph (traffic_signal=T, tree=t, bus_stop=B, bench=b, bollard=o, fire_hydrant=f, crossing==, street_lamp=i; fallback ?) and a per-kind color faded by distance. Props are spatially indexed (a grid keyed on the terrain resolution) so the per-ray-sample lookup stays near-constant; do not linear-scan the whole prop list per ray.
• Signs (street-name text). Each sign is a perspective-projected text billboard rendered as an overlay pass after the raycast loop. Project the world anchor to a screen column from its angle relative to heading, place the row from terrain(x,y) plus a sign height, truncate the text deterministically with distance, and write characters left-to-right through the depth buffer. Text always comes from a recorded source name, never generated.
• Surface material and lighting. Road surfaces may carry surface and lit. Map material to a ground glyph (for example asphalt ., concrete :, paving ;, cobble ,) and brighten lit roads slightly at night-style falloff, so the ground plane reads as pavement rather than void. Marked crosswalks (crossing:markings or crossing props) render as a distinct ground band at their recorded location.

The scaffold's HUD surfaces two wayfinding aids computed from the same data: the named street the player is standing on (nearest named surface within tolerance) and the name/address of the building the player faces within a proximity threshold. Both read from pack records, never hardcoded strings.

Reference scaffold

../assets/ascii-city-engine.html is a single dependency-free file. It reads the pack's manifest.json for the spawn coordinate and first world tile (falling back to world/tile-0.json), builds terrain, footprint, prop, sign, and surface indices, applies the movement rules above, and renders colored characters on Canvas 2D. Serve the repository root over HTTP because browsers commonly block fetch from file:// URLs.