Previous post: What Shape Cuts Drag? Breeding the Teardrop Next post: Grounded Doc Chat

Ray Casting in the Browser With Learned Maps

A zero-dependency Canvas ray caster. Maps come from a small learned chunk builder by default, with a hand-built builder as fallback.

Overview

This page draws a 3D view from a flat grid. It casts one ray per screen column and finds the first wall. This is the Wolfenstein 3D approach from 1992. It gave a strong 3D feel on slow machines.

I first built this in C with SDL2 (wolfenstein3D). This version runs in the browser with plain code and no libraries. It adds endless maps.

The map has two builders, picked by data-generator:

  • classic: a hand-built maze plus rooms. This is the reference and the calmer map.
  • nn: a small learned builder that fills a chunk cell by cell from left and upper context plus a code. This is the default.

The learned builder is the point of the page. It is small and trained. It runs in the browser. The hand-built builder is the map it learned to copy.

Note on use: blog pages show text only. The live map runs on the project card on the home page. The card uses the default builder.

Hand-Built Builder

Each 32 × 32 chunk starts as wall. The builder carves a spine, then grows a maze outward to a target fill. Then it carves one or more rooms that touch the maze. The same function makes training data for the learned builder.

The code aims for linked maps: rooms must touch floor, and chunks line up by grid. There is no proof object in the repo. Treat “linked” as a build goal with checks, not a formal proof.

The chunk builder is a pure function: generateChunkClassic(cx, cy, seed). Same seed gives same chunk.

Learned Builder

The builder fills cells in read order. Each step looks at left and upper cells plus a 32-number code. Because each step picks a firm wall or floor, the chunk stays sharp. Single-shot decoders blur. Step-by-step picks do not.

The code shapes the chunk:

  • code[0] picks a style (maze, dungeon, rooms, dense)
  • code[1] shifts wall fill
  • code[2] scales room size

Draws use a per-chunk seeded random source. Same seed gives same chunk.

Shape

Layer Shape Role
Masked conv 5 × 5, 1 → 8 Sees left and upper only
Masked conv 3 × 3, 8 → 8 Sees left, upper, and center
Head 1 × 1 → sigmoid Wall chance per cell
Code 32 numbers Added into each layer bias

About 1.3k weights in total. The weight file is about 2.6 KB on disk with its wrapper. A chunk takes 1024 small steps. Chunks cache and drop like the hand-built path.

Training

Forward, backward, Adam, and data code are hand-written in TypeScript with no libraries. Gradients match finite checks in tests.

  • Data: chunks from the hand-built builder across many seeds, plus 4 rotations. Held-out seeds check fit. Training uses style variants, not one fixed style.
  • Loss: per-cell cross-entropy with teacher forcing. Floor cells count 1.5×.
  • Search: Adam up to 80 rounds with early stop on held-out loss. One frozen run reaches about 82% per-cell teacher accuracy; treat it as one run, not a fixed law.
  • Clean-up: each chunk gets edge midpoints carved, then loose floor joins by short corridors. A fill gate of 12–55% floor falls back to the hand-built chunk on rare bad draws.

npm run train:raycaster retrains on your machine.

Honest Limits

The builder is small on purpose. A learned draw can still come out bad. The fill gate catches those. The hand-built map stays more even. That is expected. The point is a trained map builder that fits in kilobytes and ships with no ML runtime.

The build uses many tuned numbers: corridor bend, room tries, fill clamps, style scales. “No tuning” would be false.

How Drawing Works

Each ray steps grid by grid to the first wall. This step method cannot skip thin walls. Fixed-step marching can.

For each column x:

r→=d→+p→⋅cx

Here d→ is view direction, p→ is the view plane, and cx=2x/W−1.

Step sizes to cross one grid line:

Δx=|1rx|,Δy=|1ry|

The walk follows the nearer side each step. On a hit the depth used is wall-perpendicular, which removes fish-eye:

d⟂={sx−Δxvertical hitsy−Δyhorizontal hit

Wall height on screen:

hwall=Hd⟂

Near walls stand tall. Far walls shrink. Side hits draw 30% darker for fake light.

The view also draws sky and ground fills, a small top map, and shade by distance. Far draw stops at 64 tiles. Idle frames skip redraw when nothing changed.

Build Facts

Item Value
View size 640 × 400
View angle 60°
Rays 640, one per column
Map Endless 32 × 32 chunks
Learned shape 5 × 5 + 3 × 3 masked convs, ~1.3k weights
Weight file ~2.6 KB, packed with the widget chunk
Hand-built shape Maze growth + rooms, seeded
Walk speed 3.0 tiles/s, scaled by frame time
Turn speed 2.5 rad/s, scaled by frame time
Body radius 0.2 tiles, 4-corner check with slide

Canvas 2D draws one bar per column. At 640 bars this stays fast with no shaders. The canvas runs at 640 × 400 and scales up with hard pixels for the old sharp look.

Load is lazy at the site level. The widget loader watches scroll and starts the widget near view. Weights ship inside the widget chunk, not as a separate fetch. Display pixels scale with device pixels up to a cap. Move math caps frame gaps at 50 ms so tab switches do not jump.

Spawn clears a 3 × 3 floor patch and links to the nearest midpoint.

Hit checks use four corners of a 0.2-tile body. X and Y resolve apart so the player slides along walls.

Controls

Key Move
W / ↑ Walk ahead
S / ↓ Walk back
A / ← Turn left
D / → Turn right

A and D turn. They do not side-step. Arrow keys stop page scroll only while the map runs.

References