Everyone’s Retro 3D Is a PlayStation

This is the first thing to get right, because it is the thing almost every “retro 3D” shader gets wrong, and because getting it wrong makes everything downstream look like the wrong decade.

Volthaven implemented snapping first — like everyone does. Then it measured a Level 1 yaw pan and counted how many times a vertex moved backwards against the direction of the camera:

The removal had to happen in two shaders. The ticket named one file. The identical block also sat in the water material, and patching only the one named would have fixed 1 material and skipped 335. That is a lesson about tickets as much as about rasterisers.

Source

35,791lines across 81 files

Tests

359cases · 10,365 lines

Test ratio

1.20lines of test per line of game

Sectors

5each with one boss

Soundtrack

22,563 B15 pieces, 0 B of bundle

Render target

426×240short axis pinned

The rail is the whole architecture

A level is not a mesh you walk on. It is a curve. A single scalar railT describes how far along the track the player is, and world position is derived from it by sampling the curve. Gaps are ranges of railT with no floor. The camera follows the curve rather than the player. Everything — enemies, checkpoints, the flood, boss arenas — is placed by a position along that one parameter.

This is why the whole game fits in 35,791 lines. It is also why one arithmetic error in a curve length can make an entire level unreachable, which happens in Module 12.

The five abilities, as the code actually enforces them

Arc Strike       J          cost  0   ·  8-frame cooldown  ·  12 dmg  ·  reach 2.5 h x 2.0 v
Surge Dash       K          cost 15   ·  deducted  ·  12.0 rail units  ·  15 frames i-frames
Overcharge Slam  Down + J   cost 30   ·  deducted once  ·  40 dmg  ·  radius 4.0
Arc Tether       L          cost  0   ·  gated on charge >= 20 and NEVER DEDUCTED
Discharge Nova   I          cost 50   ·  deducted  ·  30 dmg  ·  radius 12

The slam has two deduction sites and charges you once

Worth walking through, because reading the source carelessly makes it look like a double charge and it is not:

1188   if (!isGrounded && wantsSlam)      charge -= 30    the direct path
1192   else if (isGrounded && wantsSlam)  NO DEDUCTION    sets vy, isGrounded=false,
                                                          slamBufferTimer=20 — it is a hop
1231   else if (slamBufferTimer > 0 ...)  charge -= 30    fires at the apex of that hop

airborne slam   -> 1188 only   = 30
grounded slam   -> 1192 hop (free), then 1231 at the apex   = 30

Either route costs 30 once. The hop is free and the buffered branch spends it.

Most N64 titles ran at 320×240. A few used a 640×480 high-resolution mode, usually with the expansion pak. The pixels you remember are 320×240 stretched to a television.

Volthaven does not hardcode 320×240, and the reason is worth stealing:

constructor   target created at 320 x 240
resize()      overwrites it — only the SHORT axis stays 240

    16:9 window   ->  426 x 240
    4:3  window   ->  320 x 240
    portrait      ->  240 x 520

Hardcode 320×240 on a 16:9 display and you must either letterbox or stretch. Stretching gives you non-square pixels, which reads as a bad emulator rather than as a console. Pinning the short axis keeps every pixel square at every aspect ratio, and the cost is that a widescreen player sees more of the level than a 1998 player would.

The upscale is one CSS property, and it is the property that does the most visible work in the entire codebase:

imageRendering: 'pixelated'

The default browser behaviour when scaling a canvas up is bilinear smoothing. That turns a crisp 426×240 image into a blurry mess and undoes every other technique on this page. pixelated makes each source pixel a hard square.

Quantisation happens once, at the end, in the blit shader. Not per material — if you quantise per material you get different banding on overlapping surfaces and the illusion falls apart at every intersection.

c.r = floor(c.r * 31.0 + 0.5) / 31.0;   // 5 bits — 32 levels
c.g = floor(c.g * 63.0 + 0.5) / 63.0;   // 6 bits — 64 levels
c.b = floor(c.b * 31.0 + 0.5) / 31.0;   // 5 bits — 32 levels

Those multipliers are 5-6-5. So the implementation matches the comments, and both are the wrong console’s format. Green gets 64 levels where the hardware gave it 32.

Find the other three

Colour is not the only place this codebase says one thing and does another. Three rounds below, each a real inspection from the render layer. Every listed line is real, and in each round exactly one is not doing what it appears to do.

  0   8   2  10
 12   4  14   6
  3  11   1   9
 15   7  13   5        / 16.0  ->  offset added before floor()

The detail almost everyone gets wrong

The matrix is indexed by the source texel, not by gl_FragCoord.

Index by screen position and the dither pattern is fixed to the display. Move the camera and every surface appears to swim through a stationary checkerboard — the pattern crawls. Index by the texel and the pattern is attached to the surface, so it moves with the geometry the way a real texture would.

The project verified the result the only way that means anything: it counted 4×4 screen blocks that were not uniform after quantisation, and got 0 of 76,800. Every block on screen resolves to a single quantised value, which is what tells you the grid survived the whole pipeline intact.

The baker evaluates a five-term model per vertex — not a single dot product. The terms give you something that reads as lit rather than merely shaded, and because it costs nothing at runtime you can afford to be generous with geometry.

That last point is the real payoff. Volthaven's levels carry a great deal of decor — pillars, gantries, kerbs, lamps — and none of it costs anything to light. On hardware with a real-time lighting budget you would have to choose. Here the choice is made once, at build time, and the budget at runtime is zero.

Unlit basic material N64 material + bake + fog

Unlit Lit

Four kilobytes means a 16-bit texture of roughly 32×64 in one load, and four-bit 64×64 textures were common. Volthaven generates its textures procedurally at 64×64 in JavaScript rather than shipping image files, which keeps the constraint explicit and the bundle empty.

Filtering is the second wrong-console mistake

This one is nearly as common as vertex snapping, and it comes from the same instinct: retro means pixels, so make the texels sharp.

The N64 applied three-point filtering and mipmapping. Its textures looked blurry. The pixelation you remember is the framebuffer being upscaled — it is not the texture. Sharp nearest-neighbour texels on a low-poly model is a PlayStation and PC look.

far-field shimmer      11.7x lower with trilinear filtering + mipmaps

why: a 64x64 texture on a distant surface samples far apart in UV space;
     without mipmaps consecutive frames grab unrelated texels and the
     surface boils. Mipmaps pre-average; trilinear blends between levels.

Two techniques in this class pull in opposite directions and both are correct: nearest-neighbour on the final blit, so the framebuffer grid survives to the display, and trilinear on the textures, so surfaces do not boil. Getting these the wrong way round is the most common way to build something that looks retro in a screenshot and wrong in motion.

N64 or PlayStation?

Six techniques below. Some belong to the machine this game is imitating. Some belong to a different one, or to the television it was plugged into. Call each before you reveal it.

3 layered fog bands        near / mid / far, each with its own colour and curve
sky dome                   so the far plane never shows as an edge
near / far plane           0.1 / 100 — the far plane is LOCKED
arithmetic pop guard       geometry fades to fog before it crosses the plane

The far plane stays fixed and the fog adapts to it, rather than the other way round. That ordering matters: a moving far plane changes your depth-buffer precision as you play, and z-fighting that appears only in some rooms is among the least pleasant bugs to chase.

With near at 0.1 and far at 100, the depth buffer has a workable distribution. Push near down to 0.01 to stop clipping something close to the camera and you spend precision you cannot get back — distant coplanar surfaces start flickering. The near plane is a budget, not a convenience.

That trade is the whole lesson. A soft glow spends screen area to say “something happened.” A hard shape with real contrast says it in less room and reads instantly at 240 lines, which is the resolution the player is actually looking at.

The art programme, measured

Every art ticket in this project had to prove its effect with a rendered pixel or a timed frame. Seven of those measurements are below. Judge each one: does the number actually support the claim it was filed under?

Delta time is the modern default and it is usually right. It keeps a game feeling the same on a 60 Hz laptop and a 144 Hz monitor. It also makes your game a floating-point simulation whose outcome depends on the exact frame times of the machine it ran on.

Frame counting gives you the opposite trade:

ARC_STRIKE_COOLDOWN_FRAMES = 8       an integer, not 133 milliseconds
boss phase durations                 240f, 600f, 120f — exact, reproducible
telegraph windows                    counted, so a test can assert them exactly

BUYS   a headless test can run 3,000 frames and get the same result every time
COSTS  the game is tied to its tick rate; a different rate is a different game

The payoff shows up in Module 12. A test suite that can drive thousands of deterministic frames is what makes it possible to say “the player was within horizontal reach for 44 frames and vertical reach for 1,966, and within both simultaneously for zero” — a sentence that is meaningless if every run produces different numbers.

The N64 is the interesting case here. It had no dedicated sound chip at all. Audio ran on the Reality Signal Processor as a microcode task, competing directly with graphics for the same silicon. Every voice you played was frame time you did not spend rendering. That is the constraint the design is answering.

Instruments

11synthesised in JS

Sample rate

22,050Hz, 4-bit quantised

Packed

22,563 B0 B of bundle

Voices

24quietest-then-oldest stealing

Pieces

15all 32 beats

Effects

23also sequencer tracks

The loop is bit-exact, not crossfaded

This is the best idea in the audio system and it generalises far beyond games.

Most looping audio is faded: play to the end, crossfade into the start, hope nobody notices. Volthaven inverts the problem. It picks the loop length first, then constrains every partial in every instrument to an integer multiple of rate / L. Every sine component therefore completes a whole number of cycles across the loop, so the final sample joins the first at a zero crossing by construction. There is no seam to hide.

Attacks are built the same way — the identical additive summation, run at negative frame indices — so the attack transient is part of one continuous function rather than an envelope spliced onto the front.

The sound effects are music

All 23 effects are sequencer tracks on the same instrument bank, on dedicated channels, authored in milliseconds at a fixed 120 BPM so that changing the music tempo cannot drag them. One synthesis path, one voice pool, one bus. Nothing in the game plays a sample file.

Trace the chain

Below is the actual signal path from a synthesised instrument to your speakers. Click any highlighted line to see what it does and what breaks if it is missing.

Silhouette first, everything else second

The same discipline applies to the ordinary enemies, and the numbers there are more extreme:

The cone is the instructive one. Measured by perimeter squared over area, it scored 31.6 from the front and 31.5 in profile — nearly identical, because a cone of revolution looks the same from every angle. After redesign the same enemy measures 609.0 front and 707.7 in profile. An enemy that reads identically from all sides gives the player no information about which way it is facing, which at this resolution is most of what they have to go on.

The five fights, in one table

One · The flood nobody could outrun

water rise    0.25      units per frame   (original)
player climb  0.0135    units per frame   (maximum, measured)

              18.5x faster than the fastest possible ascent

after         0.01681   units per frame

Level 3 was unwinnable at any skill level for the entire history of the project. Not hard — impossible. No amount of play could produce a win, and nothing crashed, logged, or failed. It took a headless bot running the level deterministically and a test that asserted completion to surface it.

Two · The boss nobody could hit

Aeros finished ten consecutive naive campaign runs on 550 of 550 HP. Never scratched.

frames the player was within HORIZONTAL melee reach      44
frames the player was within VERTICAL melee reach     1,966
frames within BOTH at the same time                       0

Each axis looked fine on its own. Either measurement alone would have closed the ticket. The bug only exists in the intersection, which is exactly the shape of defect a human playtester reports as “the boss feels weird” and cannot localise.

Three · The enemy that followed you into the wrong fight

deaths caused where it stood                     0
damage dealt after following the player into
the Ascendant's arena                          555   (5x the boss itself)

deleting that ONE spawn:   Level 5 completion   3/10  ->  10/10

Zero deaths where it was placed. It was not a hard enemy. It was an enemy in the wrong place at the wrong time, and it was doing five times the damage of the final boss during the final boss fight.

0  jump      bottom face
1  slam      right face
2  strike    left face
3  nova      top face

On a Nintendo layout, A is on the right and B is on the bottom. Measured on a real 8BitDo SN30 Pro:

The control that proved it was labelling, not code

The same prompts and the same probe, run on a DualSense: every face button landed correctly. PlayStation labels are positional, so they agree with the index order. Only the pad whose labels differ came out rotated — and only on the four buttons whose labels differ. Shoulders, Start and the D-pad matched on both.

The guard is the lesson

The fix touched only the words. Input.GAMEPAD_BUTTONS is byte-for-byte unchanged and a test asserts that, because a correct table is exactly what a label-shaped fix is most likely to damage. A per-vendor position-to-glyph table supplies the prompts.

The remapping design that dissolved a risk instead of testing it

The mapping !== 'standard' branch is untestable without hardware that reports a non-standard mapping — a branch whose first real execution would be on a stranger’s machine. The resolution was not to test it. It was to remove the need for it.

A capture flow asks the player to press the button they want and records whatever index the pad reports. It never consults mapping. There is no layout guess to be wrong, so there is no fallback branch to leave untested.

Two traps came out of building it, and both are the same trap:

• Re-arm is not immediate. The first version re-baselined the axis detector on the very next frame after a hit, so a stick springing back read as a fresh input and one press recorded two bindings. Require every button released and every axis within ~0.25 of its sampled rest pose.
• reset() must not re-sample the rest pose. A remap flow calls it immediately after recording — exactly when the stick is mid-spring-back — which takes a displaced axis as the new zero. That is the same bug rebuilt inside its own fix.

Two findings fall straight out of that table. Vibration must be guarded per-pad, not once globally — one session can see both. And the 18-button DualSense is two past the 17-index standard, so anything iterating buttons.length against a fixed table reads off the end.

title screen      found first, fixed
boss health bar   a genuinely discontinuous case — correctly fixed with a breakpoint
pause panel       needed 1,082 px in a 639 px viewport. 7 of 18 buttons unreachable
game over         clips below a 282 px viewport
victory           clips below ~329 px    <- an iPhone SE in landscape is 320 px tall
ErrorBoundary     clips below 192 px     <- renders error.message, an unbounded string

The pause panel is the one worth telling. Measured on the live build with a pad attached: plate top at −221, bottom at 861. Clipped 221 px off the top and 222 px off the bottom — the symmetric signature that tells you it is centring rather than simply being too tall.

The remedy is not a breakpoint

container   justify-start   overflow-y-auto
plate       my-auto         shrink-0

Auto margins absorb positive free space and resolve to zero when it is negative, so the panel centres while it fits and pins to the top the moment it does not. shrink-0 is load-bearing and easy to omit — without it a column flex item shrinks vertically and squashes instead of overflowing.

The acceptance test that was wrong first

Its first version asserted bottom <= viewportHeight for every button. That is the right assertion for a container that cannot scroll and the wrong one for a fix whose entire point is that it scrolls — a 1,102 px panel cannot fit in 240 px and is not supposed to. It reported 33 failures on a build whose clipping was already gone. Rewritten to assert reachability: scroll to the control, then measure.

The structural guard, and what it admits it cannot see

A test walks every absolute inset-0 overlay and fails any that is a flex column centring content with no overflow-y-auto. Three things make it more than decoration:

it parses rather than greps   GameUI.tsx documents this defect inside JSX comments using the
                              very class names under test, so a naive scan reads the postmortem
                              as markup

vacuity guard                 fails if it finds zero overlays — a rename must fail loudly
                              rather than pass by looking at an empty list

a built-in control            a ten-overlay fixture asserting exactly three are flagged, so the
                              detector is proven able to say NO on every run

And it states its own limits: it reads class names off disk, has no DOM, and cannot know that the pause plate needed 1,082 px. It asserts the weaker structural claim, which is the right one to assert.

Tap targets, and why they were unaffordable until the layout was fixed

BEFORE   RESUME 38 px · QUIT 38 · MUTE 27 · twelve pad controls 24–27
         only 2 of 18 cleared 44 px
AFTER    18 of 18

Twelve controls at 44 px adds roughly 230 px to a panel that already could not fit and could not scroll. The accessibility fix was gated on the layout fix — you could not have done it first.

rung      before      after     saved
 800     138,692     82,192    -40.7%
 960     190,362    109,450    -42.5%
1200     284,006    156,022    -45.1%
1600     438,706    248,790    -43.3%

RGB planes: byte-identical to what shipped before.

The measurement that nearly threw it away

Composited over the game’s own background, alpha_q70 shows 31.75% of pixels differing by more than 2/255, worst case 86. On its own that reads as unacceptable and the change gets reverted.

The control says otherwise:

The 30% and the maximum of 86 were already in the shipped file, from the lossy encode and the downscale. alpha_q70 adds +0.17 to the mean and does not move the maximum at all.

Two method notes that made the comparison honest. The shipped encoder settings were recovered first — q82 / alpha_q100 / m6 reproduces all four files byte-for-byte — which is what makes every later comparison like-for-like. And the result was inspected in two places: the densest soft-alpha window and the worst-error window, which are not the same crop.

Per 1,000 players

4.38¢new players, cold

Per 1,000,000

$45.25egress + compute

Free tier covers

2,741players / month

First load

0.3735MiB weighted mean

The number that governed the model for four revisions was wrong

“Which logo rung the modal player fetches” was CALCULATED through three revisions, on the reasoning that a phone at 393 CSS px times a device pixel ratio of 3 picks the 1200w rung. Then it was measured from Cloud Run logs, n = 349 over 7 days of launch traffic:

rung      fetches    share
 800w         258    73.9%
1600w          83    23.8%
1200w           5     1.4%
 960w           3     0.9%

The distribution is bimodal — 74% at the floor, 24% at the ceiling, almost nothing between. That is desktop at DPR 1 and retina, not a spread of phones. The model had been 8.4% pessimistic, and the intuition that phones are the expensive case did not survive contact with the logs.

The lever that was never there

“Standard Tier gives 200 GiB free against Premium’s 1 GiB” was carried as the largest open opportunity for three revisions. It is impossible, verified four independent ways:

ELIGIBILITY   Standard is scoped to resources using regional external IPs.
              Zero hits for Cloud Run or serverless in the tiers overview.
PRICING       Cloud Run pricing states outbound transfer USES Premium. Declarative.
NO SURFACE    no --network-tier flag on any gcloud run command, no networkTier API field
BILLING       the Standard egress SKU group is 42 SKUs, every one Compute Engine

And the framing was wrong even conditionally: Standard is reachable only behind an external load balancer at roughly $18.25/month plus $0.008/GiB, which at 200 GiB is a wash against simply paying Premium.

The cost nobody was tracking is larger than the one everybody was

700 files · 182 images · ~36.4 GiB  ->  ~$3.86 / month

more than the egress cost of serving 83,000 players
four-fifths of it sits in a region the game does not deploy to

An instrument that encodes an assumption launders that assumption into data

A viewport probe hardcoded a 705 px requirement derived at desktop width, then printed a verdict against it on every device. The dimensions were genuinely measured. The verdict was arithmetic against a constant that does not transfer — and the whole readout was labelled MEASURED.

A metric with a noise floor above the effect size cannot disprove the effect

Checking animation frames for stalls by counting pixels that differed at all found none — because on dithered art the dither perturbs nearly every pixel regardless of motion. By magnitude, the stalls were 17 and 5 changed pixels against a median of 23,088. The first measurement did not refute the defect. It could not see it.

Confirm a failure with a second method before believing it

A build gate reported FAILED on a working fix because it asserted bottom:2rem against a Tailwind v4 build that emits calc(var(--spacing) * 8). Separately, images read as never-loading with the element 200 px inside the viewport — that was scrollIntoView() not driving the compositor. What settled it was that the pre-existing images failed identically, which ruled out the new markup.

A known-good control is cheaper than a debugging session

The DualSense that proved the gamepad bug was labelling. The alpha_q100 baseline that saved 43% of the logo payload. The ten-overlay fixture that proves the structural guard can still say no. Every one of the failures above was resolved by a control, not by analysis.

Say what a green tick measures

The overlay guard ships with a written statement of what it cannot see. The remapping panel’s test asserts the payload contains no transport claim. The cost model labels every figure MEASURED, CALCULATED or NOT VERIFIED, and names what would settle the unverified ones.

Judge six measurements

Six from the material above. Three are sound. Three are the kind that read as rigorous and settle nothing. Call each before you reveal it.

Play Volthaven 64