The Legend of Taos — Technical Deep Dive

A top-down action-adventure in the spirit of the original Zelda, built entirely on the Taos Engine's render graph — using a single custom 2D pass.

Taos Engine is a deferred + HDR 3D WebGPU engine: G-buffers, cascaded shadows, PBR materials, the works. None of that is useful for a flat pixel-art game. But the engine's render graph is — it gives us virtual resources, pooled physical GPU objects, automatic barriers, and a clean per-frame execute hook.

So this sample keeps the engine and its render graph, but the graph contains exactly one pass: a 2D sprite batcher that clears the backbuffer and blits a stream of textured quads. Everything you see — tiles, the hero, enemies, the boss, items, the HUD — is one of those quads, sampled from a single procedurally-generated atlas texture.

The result is the smallest possible "2D mode" for a 3D engine: no materials, no lighting, no depth buffer, no scene graph traversal of meshes. Just clear → batch → draw.

Engine frame
 ├─ beforeFrame ……… game.update(dt)          // simulate
 ├─ feature.addPasses … game.draw(batch)       // queue quads + add the 1 pass
 ├─ graph.compile()
 └─ graph.execute() …… SpriteBatchPass         // upload vertex buffer, 1 draw call

3.1 The pass#

SpriteBatchPass extends Pass<{ backbuffer }, void>. Its addToGraph declares a single write to the backbuffer as a cleared color attachment, then registers an execute callback:

graph.addPass(this.name, 'render', (b) => {
  b.write(deps.backbuffer, 'attachment', {
    loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 1],
  });
  b.setExecute((pctx) => {
    // upload the CPU vertex staging, then one draw of quadCount * 6 verts
    this._device.queue.writeBuffer(this._vbuf, 0, data.buffer, 0, bytes);
    const enc = pctx.renderPassEncoder!;
    enc.setPipeline(this._pipeline);
    enc.setBindGroup(0, this._bindGroup);
    enc.setVertexBuffer(0, this._vbuf, 0, bytes);
    enc.draw(quads * 6);
  });
});

The clear (black) doubles as the letterbox fill — anything outside the scaled virtual screen stays black. The graph builds the GPURenderPassDescriptor from the attachment declaration; the pass never touches it directly.

3.2 The virtual screen and CPU-side NDC transform#

The game thinks in a fixed 256×240 "virtual screen" (NES-ish), regardless of window size. On each begin(), the renderer computes an integer scale that fits that into the device-pixel canvas and centers it:

const scale = Math.max(1, Math.floor(Math.min(canvasW / 256, canvasH / 240)));
this._offX = Math.floor((canvasW - 256 * scale) * 0.5);
this._offY = Math.floor((canvasH - 240 * scale) * 0.5);

Because the batch is rebuilt from scratch every frame, there is no transform uniform and no matrix in the shader. Each quad is transformed virtual-px → device-px → NDC directly in JS as it is pushed:

const px0 = x * scale + offX;          // virtual → device px
const nx0 = (px0 / canvasW) * 2 - 1;   // device px → NDC
const ny0 = 1 - (py0 / canvasH) * 2;   // (y flipped: virtual y is down)

The vertex shader is therefore a pass-through; the fragment shader samples the atlas (nearest filtering, set on the sampler — this is what keeps the pixels crisp) and multiplies by a per-vertex color used for tinting (hit-flash, invuln-flicker) and solid rects (HUD panel, screen flash):

@fragment fn fs(in: VSOut) -> @location(0) vec4<f32> {
  let c = textureSample(atlasTex, atlasSamp, in.uv) * in.color;
  if (c.a < 0.01) { discard; }
  return c;
}

3.3 Batching#

Vertices are 8 floats (pos.xy, uv.xy, rgba), 6 per quad (two triangles, no index buffer). They accumulate in a growable Float32Array; the GPU vertex buffer is created once and only reallocated if a frame exceeds its capacity. A whole frame — tiles, sprites, HUD — is a single draw call. Standard alpha blending is enabled so transparent sprite pixels composite over the tiles.

3.4 The feature#

SpriteFeature is the RenderFeature. Its async setup() builds the atlas (the engine awaits feature setup before the first frame). Its addPasses(frame) runs once per graph build — i.e. every frame — and does three things in order:

this.renderer.begin(ctx.width, ctx.height); // reset batch + compute scale
this._draw(this.renderer);                  // the game queues all its quads
this._pass.addToGraph(frame.graph, { backbuffer: frame.backbuffer });

this._draw is just game.draw. Since addPasses runs after beforeFrame (where the game simulates), the quads always reflect the current frame's state.

No external images. Everything is drawn at runtime into one 256×256 RGBA8 buffer and uploaded with queue.writeTexture. Two techniques:

Char-grid templates for things that need a deliberate silhouette — the hero (4 facings × 2 walk frames), sword, enemies, items, and a digit font. Each pixel is one character indexed into a shared PAL palette; ./space are transparent:

tmpl('hero_down_a', [
  '......XXXX......',
  '.....XggggX.....',   // green cap
  '....XgSSSSgX....',   // face
  '....XSXSSXSX....',   // eyes
  '...XSGgggGSX....',   // arms + tunic
  // …
]);

Procedural drawing for things that read fine as patterns — tiles (grass noise, brick courses, water dashes) and the boss (concentric discs for the big eye). This is far more compact than a 16×16 template per tile. The Zia sun (the treasure, replacing the Triforce) is drawn this way: a gold disc with a red core and four cardinal ray bundles (two long inner rays + two shorter outer), matching the New Mexico Zia symbol.

Sprites are packed with a simple shelf packer (alloc(w, h) advances a cursor, wrapping to a new shelf row when full), and each name records its texel rect in lookup[name]. SpriteRenderer.drawSprite('octorok_a', x, y) looks up that rect, optionally flips/​tints, and pushes a quad.

The virtual screen splits into a 64px HUD at the top and a 256×176 playfield below. The playfield is a 16×11 grid of 16px tiles. Entity positions live in playfield space (origin at the playfield's top-left); drawing adds the HUD offset.

VIRTUAL_W 256
┌───────────────────────────┐
│ HUD  (rupees, key, item, ♥)│ 64px
├───────────────────────────┤
│                           │
│   playfield 16×11 tiles   │ 176px   (COLS×ROWS, TILE=16)
│                           │
└───────────────────────────┘  VIRTUAL_H 240

Rooms are built, not hand-typed#

Authoring full 16×11 ASCII screens by hand is error-prone, so rooms.ts builds each room from a spec: fill the interior with the base tile (. grass / f floor), draw a border (T trees / W walls), carve doors into the edges that have a neighbor, then stamp feature tiles on top:

{
  id: 'd_mid', kind: 'dungeon',
  edges: {
    down: { to: 'd_entry' }, up: { to: 'd_key' },
    left: { to: 'd_block' }, right: { to: 'd_boss', lock: true },
  },
  features: [ /* statues, enemy markers… */ ],
}

Tile semantics live in a TILES table (sprite + default solid). Some tiles are dynamic and flip at runtime: a locked door L becomes passable once its doorId is in the unlocked set; a shutter S becomes floor when the room's puzzle is solved. Enemy/item/player markers (1 octorok, 2 moblin, 9 boss, k key, i item, P start, …) are extracted into entities at room-load and replaced with floor.

The full level: two overworld screens, a cave into a six-room dungeon (d_entry → d_mid hub → d_key, d_block, d_boss).

6.1 Movement and collision#

The hero moves in continuous pixels, not on a grid. Collision is a swept AABB vs. the tile grid, resolved one axis at a time (moveBody): move on X, scan the tiles spanned by the box's leading edge, snap out on a hit; repeat on Y using the already-resolved X. The collision box ({ox:3, oy:6, w:10, h:9}) is smaller than the 16×16 sprite — the classic feel where your "feet" decide collision, so you can tuck under overhangs and slip through doorways.

moveBody takes a solid(tx, ty) predicate, so the same routine serves the hero (playerSolid — respects unlocked doors, open shutters, blocks), projectiles, and enemies (enemySolid — keeps them on floor/grass and inside the room).

6.2 Combat#

Pressing attack freezes the hero for the swing and spawns a short-lived sword hitbox in the facing direction (swordHitbox()), active only in the first part of the swing. Overlap tests against enemies apply damage with a brief per-enemy i-frame so one swing is one hit. At full health the White Sword fires a beam projectile — exactly the original's reward for staying topped up.

Taking a hit applies knockback (velocity away from the source, decayed in updatePlayer) plus ~1s of invulnerability (rendered as a flicker). Health is tracked in half-hearts and drawn as full/half/empty heart sprites.

6.3 Enemies and the boss#

• Octorok — cardinal wander, periodically fires a rock in its facing dir.
• Moblin — tougher cardinal wander, contact damage only.
• Keese — fast, erratic free-flight that bounces off walls.
• Boss — drifts horizontally with a vertical bob, bounces off the inner walls, and fires a 3-way fireball spread aimed at the hero. Its 32×32 sprite has two frames (eye narrow / wide). On death it drops the Zia sun and flashes the screen.

6.4 Projectiles, pickups, drops#

Projectiles carry a friendly flag: friendly beams hit enemies, enemy rocks and fireballs hit the hero; all die on walls. Pickups (key, rupee, heart, item, Zia sun) are AABB-collected. Slain enemies sometimes drop a heart or rupee.

6.5 The three "progression gates"#

These are what make it a dungeon and not just rooms:

1. The key is hidden until the room is cleared. In d_key the key spawns into a gated list, not the live pickups. revealGatedIfCleared() promotes it (with a sparkle + flash) only once room.enemies.length === 0.

2. The block puzzle. d_block's White Sword sits in a chamber sealed by a full-height shutter wall (col 5, rows 1–9 — fully enclosed, no way around). Pushing the movable block onto the floor switch (checkBlockSwitch) converts every S tile in the room to floor, opening the chamber. Block pushing is intentional: you must lean into a block for ~0.35s before it slides one tile, and only if the destination is clear.

3. The locked door + small key. The d_mid → d_boss edge is a locked door. Walking into it with a key (tryUnlockAhead) consumes the key and records the door's shared doorId in the unlocked set, so both rooms treat it as open thereafter.

6.6 Screen transitions#

When the hero's center crosses a playfield edge that has a neighbor, the game enters a transition state for 0.5s. Both rooms are drawn offset and slid across the playfield (the HUD stays put), and the hero rides in with the incoming room — the NES "screen scroll" between rooms. Caves and stairs are instant cuts instead (checkTriggers).

Persistence is global, not per-room snapshot: unlocked doors stay open, takenPickups don't respawn, the boss stays dead — but ordinary enemies refill on re-entry, exactly like the original.

input.ts folds three sources into one tiny action set (up/down/left/right/attack/item/start):

• Keyboard — arrows/WASD, Z/Space (sword), Enter/R (start). Edge presses are latched on keydown so a fast tap is never missed.
• Gamepad — sampled each tick in poll(): left stick (with deadzone) or d-pad for movement, face buttons for sword/item, Start/Select for start. Edge presses come from diffing this frame's button set against last frame's.
• Touch — on-screen buttons call setTouch(action, isDown).

down(a) is true if any source holds the action; pressed(a) is the latched edge for the frame, cleared by endFrame(). Movement reads down; one-shot actions (attack, start) read pressed.

Lazy touch UI. touch_controls.ts does not build the overlay just because the device reports touch support (a touchscreen laptop driven by mouse/keyboard shouldn't get a d-pad over the game). Instead it registers one-shot touchstart / pointerdown(type=touch) listeners and builds the DOM + CSS only on the first real touch, then removes the listeners. The controls support multi-touch (move + attack at once) and diagonals (two d-pad buttons).

A few small things make a 2D game cooperate with a 3D engine:

• Dummy camera. The engine's frame loop short-circuits if there is no active camera, so the entry adds one orthographic Camera. Nothing in the 2D pass reads it; it just satisfies the gate.
• Sim in beforeFrame, draw in addPasses. This ordering guarantees the batch reflects the just-simulated state. The graph is rebuilt every frame (cheap — one pass), so addPasses runs every frame and re-queues all quads.
• Async atlas in feature setup. Returning a promise from setup lets the engine await texture creation before the first frame.
• DOM for big text. The in-canvas HUD draws hearts/keys/rupees/digits as sprites, but the large centered messages (title, item-get, game-over, win) are a DOM overlay — robust regardless of letterbox scaling, and no need for a full text layout system in the batcher.

The hot path allocates almost nothing per frame: the vertex staging array and GPU buffer are reused, sprite rects are looked up by name, and a full frame is a single draw. The atlas is built once. The render graph is rebuilt each frame but that is a handful of JS objects for one pass. At 256×240 internal resolution the GPU is essentially idle — this would run on anything with WebGPU.

• More dungeon floors — the room builder + doorId model scale to a grid of levels; add a level field and a stairs-between-floors transition.
• Items with verbs — the item action and HUD item-box are already wired; add a bow (reuse the projectile system) or a boomerang.
• Animation polish — add attack-pose hero frames, enemy death animations beyond the sparkle, and a damage-number/​combo layer.
• Audio — the engine ships an AudioEngine (spatial SFX, music, buses); a few sword/hit/pickup cues and a looping track would go a long way.

The whole thing is ~1.5k lines across seven files, and the only engine surface it touches is Pass / RenderFeature / RenderGraph. That's the takeaway: the render graph is general enough that "2D game" is just another pass.