DEV Community: kentog751

The penny invariant: correctness guarantees in a game that teaches a child about money

kentog751 — Tue, 11 Aug 2026 02:58:17 +0000

There is a bug class that only exists in software for children. The generator produces a question, the question has no answer, and the player cannot tell. A six-year-old has no mental model of your round generator. They have a mental model of themselves. So they try coins, nothing works, and they arrive at the only explanation available to them, which is that they are bad at this. A game that shows a child an impossible question has failed at the only thing it was for, and it has failed invisibly, because nobody files that bug report.

I built a browser game called Coin Cafe where you serve customers and count out the coins. Eight stages, eight customers per stage, US denominations, about 12,000 lines of plain ES modules with no build step. Most of that is drawing. The part worth writing about is the 1,300 lines in money.js that make it structurally impossible to ask a question that cannot be answered.

Money is integer cents, and only integer cents

A money game is the worst possible place to discover floating point, not because the errors are large, but because the comparison you care about is exact equality against a number the child computed in their head.

export const CENTS = Object.freeze({
  penny: 1,
  nickel: 5,
  dime: 10,
  quarter: 25,
  dollar: 100,
});

That is the whole model. 47 means forty-seven cents. No dollars anywhere, no decimal strings, no toFixed round trips.

Try the alternative. A nickel and a penny on the mat for a 6 cent order, then three dimes and two pennies for a 32 cent order, both in dollars:

0.05 + 0.01                       =>  0.060000000000000005
0.10 + 0.10 + 0.10 + 0.01 + 0.01  =>  0.32000000000000006

Both are correct answers. Both fail total === target. The child is told they are wrong, on a screen designed to be gentle, for a reason that does not exist. You can paper over it with an epsilon, but that means picking a tolerance on a quantity that is exactly representable as an integer.

The rule is enforced at one seam. Denominations are always key strings, never values, and nothing converts a value back into a key. denomOf() throws rather than degrade:

if (typeof entry === 'number') {
  throw new Error(
    'money.denomOf: got the number ' + entry + ' where a denomination key was expected. ' +
    'Money is always stored as a key string like \'quarter\'; use CENTS[key] when you need ' +
    'its value. Nothing in Coin Cafe ever converts a value back into a key.'
  );
}

A loud crash at integration time is cheaper than a tray that silently totals zero. I shipped the silent version of this bug in an earlier game, where one module stored a colour key and another used it as a hex string. It survived weeks.

The penny invariant

Here is the guarantee, and it is one line of data rather than one line of logic. Every stage's coin tray contains a penny.

{
  index: 0,
  name: 'Morning Shift',
  mode: 'pay',
  coins: ['penny', 'nickel'],
  priceMin: 1,
  priceMax: 25,
  paid: 0,
  cap: 6,
},

That is stage 0. Stage 4 is ['penny', 'nickel', 'dime'], stage 7 is all five. All eight rows start with penny, including the three separate round shapes that stage 7 rolls between.

With a penny in the tray, every integer-cent target from 1 upward is buildable. No combination of stage settings, price ranges, menus or difficulty bands can produce a round with no answer, because that failure mode does not exist in the space. You cannot configure your way into it.

Compare the shape everyone reaches for first: generate a round, run a solver, reroll if the solver fails. That works until somebody widens a price range, or drops the penny from a stage to make it look cleaner, and a fraction of rounds start falling through the retry loop into whatever the fallback is. The loop hides that regression instead of surfacing it. A structural guarantee cannot be tuned into a bug by someone who was not thinking about solvability, because there is nothing to tune.

One related fact is worth stating out loud. Greedy decomposition, largest coin first, is optimal for every tray this game ships: I checked it against a dynamic-programming minimum for every amount from 1 to 175 cents across all four trays, and greedy matches on all 700. That is a property of these specific denomination sets, not of greedy algorithms, so re-check it if you add a denomination.

Generate and check, with the check as an assertion

The invariant makes bad rounds impossible. The verifier makes sure of it anyway.

verifyRound(spec) returns null for a sound round, or a plain English string naming what is wrong. It checks that every money field is an integer, that item prices sum to the total, that a change round's target really is paid minus price, and then it re-solves the round from scratch:

if (spec.tray.indexOf('penny') === -1) return 'tray has no penny, so solvability is not guaranteed';
...
const mc = minimalCoins(spec.target, spec.tray);
if (countCoins(mc) !== spec.target) {
  return 'target ' + spec.target + ' is not buildable from this tray';
}
if (mc.length !== spec.minCoins) return 'minCoins is ' + spec.minCoins + ' but the answer needs ' + mc.length;
if (mc.length > stage.cap) return 'needs ' + mc.length + ' coins, over stage ' + stage.index + ' cap of ' + stage.cap;

The important part is where it sits: the last line of the candidate builder, before the spec is handed back.

if (verifyRound(spec)) return null;
return spec;

null means the caller keeps looking. makeRound() tries 40 random draws inside the customer's difficulty band, then sweeps every candidate value in the band and then the whole stage range across every shape, and only then falls back to one of eight hardcoded known-good rounds. It cannot hang and it cannot hand back something unsound, because every path out of it goes through the same verifier.

I ran the shipped code over 64,000 generated rounds, every stage, every customer position: zero verifier failures, and the hardcoded fallback was reached zero times.

Difficulty that ramps inside the session, not just between stages

Eight customers per shift. If all eight draw uniformly from the stage's price range, the shift has no shape and customer one can be harder than customer eight. So the range is cut into thirds and each customer draws from their own third:

function bandFor(customerIndex, of) {
  const n = of > 0 ? of : SHIFT_LENGTH;
  const b = Math.floor((customerIndex * 3) / n);
  return b < 0 ? 0 : b > 2 ? 2 : b;
}

With eight customers that gives 3 / 3 / 2. In stage 0 the observed target ranges come out at 1 to 8, 9 to 16, and 17 to 25 cents. Prices also never repeat inside a shift: the chosen total is added to a used set inside makeRound() itself, so a caller cannot forget to do it.

The subtle part is which number the band applies to. For a pay round it is the price. For a change round it is the change:

function difficultyRange(shape) {
  if (shape.mode === 'change') {
    const lo = Math.max(1, shape.paid - shape.priceMax);
    const hi = Math.min(shape.paid - 1, shape.paid - shape.priceMin);
    return [lo, Math.max(lo, hi)];
  }
  return [shape.priceMin, shape.priceMax];
}

Band on the price in a change stage and the ramp inverts. A 3 cent item paid with a quarter means 22 cents of change, the hardest round in the stage, handed to customer number one. The child builds the change, so the change is what the difficulty is about.

The coin cap, and why 24 cents is a bad first question

Every stage carries a cap: the maximum number of coins the minimal answer may use. Stage 0 is 6.

Stage 0 offers pennies and nickels, prices 1 to 25 cents. Arithmetically, 24 cents is fine. Four nickels and four pennies. It is also a terrible first screen for a six-year-old, because eight taps of near-identical metal is a dexterity exercise rather than a counting one, and the child will lose count around the sixth penny and conclude that counting is the thing they are bad at.

The cap removes it. Of the 25 possible prices in stage 0, exactly three exceed six coins: 19 and 23 need seven, 24 needs eight. They are never generated. The cap is checked twice, in the candidate builder and again in the verifier, and the rule scales up: stage 2 caps at 9, and across 12,800 sampled stage 2 rounds the largest minimal answer observed was exactly 9.

Nobody notices the absence of a bad question. That is the point.

A wrong answer has to teach, not score

An incorrect serve does not shake the screen, does not deduct points and does not end the round. It opens a full-screen number line.

explain() in money.js writes every sentence on that screen. The renderer in numberline.js composes none of them, because two files writing copy is two voices. Each coin the child placed becomes a labelled hop along the line, re-sorted largest first, because that re-sort is the lesson. Every landing point prints its running total, so 0 · 25 · 35 · 40 · 41 is visible as a sequence. Under it sits the equation, 25 + 10 + 5 + 1 = 41¢, an amber band covering the distance still to travel, and one instruction:

headline = 'You are ' + fmt(gap) + ' short.';
gapLabel = fmt(gap) + ' to go';
const need = sortDesc(minimalCoins(gap, tray));
advice = 'Add ' + fmt(gap) + ' more. Try ' + coinPhrase(need) + '.';

If the child overshot, a subset sum over the coins actually on the mat finds the exact set to remove, so the advice becomes "Take off a nickel and two pennies", naming coins physically in front of them, rather than "try again". The words wrong, no, failed, incorrect and oops appear in no string this file produces. Being short is described as a distance to travel.

Two decisions follow. The button out of the screen is called Fix it, and it returns you to the same round with your coins exactly where you left them:

closeCheck() {
  if (this._phase !== 'checking') return false;
  this._phase = 'serving';
  return true;
}

The number line is worth nothing if you cannot immediately act on it. A new round would be a punishment dressed as a reset.

And that round can still be worth a star. Stars are 3 for a first-try minimal answer, 2 for a first-try correct answer, 1 for a correct answer after a check. Never 0 for a customer you served. Points work the same way: an incorrect serve drops the round from the 100 tier to the 50 tier, a forgone bonus rather than a deduction. Nothing in the scoring path subtracts. The self-check button, which opens the same number line before you serve, costs nothing at all, because self-checking is the behaviour you want and charging for it is a trap the child cannot see.

What I would do differently

The argument-order tolerance was a mistake. explain() accepts (mat, round) or (round, mat) and sniffs which is which; makeRound()'s options parameter accepts a Set, an array, or an object with several spellings. That was written to survive parallel work on modules meeting in the middle, and it works, but it is the exact opposite of what denomOf() does two hundred lines earlier. One seam throws loudly on a shape mismatch and the other quietly repairs it. The loud one has been worth more.

verifyRound() is exported and documented as an assertion seam, and nothing outside money.js calls it. There is no committed test file exercising it either. The 64,000-round sweep above is real and ran against the shipping code, but it lives in my shell history rather than in the repository, so the guarantee is currently enforced by a comment and my memory. That is the weakest link in everything described here.

The renderer also duplicates the model's normalisation. numberline.js carries its own coin parser, its own cents table and its own palette fallback, all defensive copies of things money.js and art.js already own. Defensive copies drift, and one of them already disagrees about whether a half dollar exists.

None of this is exotic. Pick an exact representation, encode the safety property in data rather than in a retry loop, and assert it on the way out. It matters more when the person who cannot detect the bug is six.

The rest of the set is at freegamesonline.com/games-for/teachers.

Kenneth Hartog builds and runs freegamesonline.com, where the originals are plain ES modules with no build step.

No build step, no bundler: 11 things that broke shipping Three.js into an iframe

kentog751 — Sat, 08 Aug 2026 00:33:15 +0000

The constraint I gave myself was stupid and I would do it again. Two 3D games, real ones with physics and shadows and a mascot, that have to load inside an iframe on somebody else's page, on whatever laptop a school district bought in 2019, with no build step, no bundler, and no framework.

So the shape is: one index.html, seven plain ES modules the browser loads directly, and a vendored copy of Three.js (r185, two files, about 740KB) sitting in lib/ next to them. I install it with npm install three --no-save and copy the build in, so Three never enters package.json and the host never builds it. <script type="module" src="/originals/petal-peaks/src/main.js"> and that is the entire toolchain.

Both games shipped. Everything below is a thing that broke on the way. Most are not in the docs, and about half only exist because the games run embedded rather than on a page I control.

1. Probe WebGL on a canvas you throw away

I want to pick renderer flags before I construct the renderer. Weak GPU means antialias off, powerPreference: 'default', a lower pixel ratio. To decide that, I have to look at the GL context first.

The obvious move is to grab a context off the real canvas, read WEBGL_debug_renderer_info, and hand the canvas to Three. That silently breaks everything. A canvas can only ever have one context. Once you call getContext('webgl2') with default attributes, that context is bound forever, and WebGLRenderer gets your default-attribute context back and quietly ignores every flag you just chose. No warning, no error. You find out because your Chromebook test frame looks identical before and after your "optimization."

So boot() probes on a canvas that never touches the DOM:

const probe = document.createElement('canvas');
probe.width = probe.height = 1;
const gl = probe.getContext('webgl2') || probe.getContext('webgl');
if (gl) {
  const lose = gl.getExtension('WEBGL_lose_context');
  if (lose) lose.loseContext();
}
if (!gl) { /* show a friendly "your browser has 3D turned off" card */ }

The loseContext() matters more than it looks. Browsers cap live WebGL contexts, and the deeper capability probe in perf.js burns a second one to test failIfMajorPerformanceCaveat, which is the cheapest reliable way to detect a software rasterizer. Hand them back immediately or your actual game canvas is the one that fails to get a context.

Only then does the real renderer get built, with the flags the probe earned:

const s = rendererSettingsFor(this.quality, w, h);
this.renderer = new THREE.WebGLRenderer({ canvas, ...s.context });
applyRendererSettings(this.renderer, this.quality, THREE, w, h);

2. Turn tone mapping off

Every Three.js tutorial from the last few years tells you to set ACESFilmicToneMapping. If your art comes out of Blender with physical materials, sure. Mine does not. My sky is a hand-written ShaderMaterial full of hex colours I picked by eye. ACES took a bright pink-and-blue kids' palette and turned it into grey mush. Not "slightly desaturated." Mush.

this.renderer.outputColorSpace = THREE.SRGBColorSpace;
this.renderer.toneMapping = THREE.NoToneMapping;

The other half of this is the trap that made me try ACES in the first place. A custom ShaderMaterial gets no output encoding from Three at all. Write gl_FragColor and it goes to the framebuffer raw, so every authored hex renders noticeably dark and your instinct is to reach for exposure to fix it. The actual fix is one line at the end of the fragment shader:

gl_FragColor = vec4(vCol, a);
#include <colorspace_fragment>

Include the colorspace chunk, deliberately do not include the tonemapping chunk, and the shader renders exactly the colours you typed. Both games run this way: Petal Peaks has the sky, glow, and light-shaft shaders, and every one of them ends with that include.

3. `gl_PointSize` is not pixels, it is whatever your shader says

I built a GPU particle system as one THREE.Points with a per-vertex aSize attribute, and filled aSize with numbers between 14 and 26, because in my head point size is pixels and 20px sparkles sounded right.

The first burst covered the whole screen with one white blob. Here is the vertex shader, doing exactly what I told it to:

vec4 mv = modelViewMatrix * vec4(position, 1.0);
gl_Position = projectionMatrix * mv;
float pop = smoothstep(0.0, 0.22, aLife);
gl_PointSize = aSize * uScale / max(-mv.z, 0.001) * pop;

with uniforms: { uScale: { value: window.innerHeight * 0.5 } }.

That divide by view depth makes aSize a world-space diameter, so the sprite shrinks with distance like everything else in the scene, which is what you want. It also means the pixel size is aSize * uScale / depth. The default embed is 640px tall, so uScale is 320. A particle 12 units from the camera with aSize = 20 gets 20 * 320 / 12, which is 533 pixels of screen. Roughly the whole viewport, per particle.

The real values are now fractions of a world unit, 0.26 to 0.42, and the file carries a shouty comment so I do not do it again. This is the one bug here where the code was correct and my mental model of the units was the only broken part.

4. A chase camera means your character is always backlit

This one is structural and I think it is the most useful thing here.

Petal Dash is an endless runner with a fixed camera behind the player. The camera sits at p.z - 6.4, the player runs toward +z. So the surface the camera sees, for the entire game, is the character's back. Add one directional light for the sun and, unless that sun sits exactly behind the camera, every polygon facing the lens faces away from the light. MeshLambertMaterial gives away-from-light surfaces ambient-only shading.

I did the obvious thing and added an AmbientLight fill. It did not help, and it cannot help, because ambient is flat: it raises every surface by the same constant, so the back of the character gets brighter but stays perfectly uniform. Uniform brightness with no gradient is what a grey silhouette looks like. I turned the ambient up until he was pale and still shapeless, then turned it back down.

const sun = new THREE.DirectionalLight(0xfff6e0, 1.15);
sun.position.set(6, 12, 6);
this.scene.add(sun);
this.scene.add(new THREE.HemisphereLight(0xbfe6ff, 0x8bd66a, 0.85));

HemisphereLight fixes it structurally rather than by tuning. It lights by how far a normal points up versus down, not by how far it points toward or away from a light direction. A vertical, camera-facing surface always sits in the middle of that gradient and always picks up some sky colour, so it cannot be left flat no matter where the camera is. Cool sky over warm ground bounce also keeps the shadow side coloured instead of grey, which is free art direction.

You can also fix it with a second directional light pointing the same way as the camera. I would not. The direction of a Three.js directional light is target.position - light.position, not "it shines outward from where I put it," and I got that backwards twice before switching approaches.

5. A flat plane renders as one flat colour, no matter how many polygons it has

Related, and it took me embarrassingly long to see. The runner's ground is a flat plane. Under one directional light a flat plane has a constant normal, therefore constant N·L, therefore one uniform fill across the largest surface in the frame. Subdividing does nothing. It is the loudest programmer-art tell there is.

The geometry has to stay flat because collision depends on it, so the shape gets baked into vertex colours at build time:

const patch = 0.5 + 0.5 * Math.sin(x * 0.55 + Math.sin(z * 0.31) * 1.3);
c.copy(base1).lerp(base2, patch);
c.multiplyScalar(0.9 + rand() * 0.2);

Broad low-frequency patches, per-vertex jitter, a worn path tint under each lane, a darker falloff at the outer edge for a contact-shadow read. The platformer does the same to its island tops with concentric rings inside the triangle fan, plus a warm lift on the sun-facing half computed from the sun's actual heading:

const sunF = (x * sunHX + z * sunHZ) * capSpan;
_capC.copy(capMid);
if (sunF > 0) _capC.lerp(capWarm, Math.min(1, sunF) * 0.5);
else _capC.lerp(capShade, Math.min(1, -sunF) * 0.26);

Costs about seven extra triangles per outline point, no extra draw call, and the surface is still perfectly flat for physics.

6. Additive light shafts need two fades, not one

Volumetric-looking light shafts are cheap: a cone with additive blending. Except a raw additive cone reads as a pasted-on white wedge with razor edges down both sides, which players read as a rendering glitch rather than as light.

Two independent fades are required and I only found the second one after the first one kept not being enough.

The far end fades via vertex alpha baked into the geometry, so the beam dissolves instead of stopping at a hard rim. Additive blending plus black vertices equals invisible, which makes this free.

The silhouette fades on view angle. Brightness through a real shaft is proportional to how much volume you are looking through, maximal dead centre and zero at the outline. That is |dot(N, view)|:

vec3 n = normalize(normalMatrix * normal);
vG = pow(abs(dot(n, normalize(-mv.xyz))), 1.35);

The abs is load-bearing because the material is DoubleSide. The same trick with max(0.0, dot(...)) turns the glow sphere around every pickup from a hard blob into something that stops stacking to solid white when a row of collectibles lines up in screen space.

7. `body { touch-action: none }` turns your iframe into a scroll trap

This is the one that made me feel worst, because it breaks other people's pages, not mine.

Every canvas game tutorial says put touch-action: none on the body so the browser stops trying to scroll and pinch while you play. On your own full-page game, fine. Inside an iframe on someone's blog, you have just eaten every touch that lands on your rectangle. A reader scrolling the article puts a thumb on your game and the page stops moving. They cannot get past it. They leave.

#scene, #touchControls { touch-action: none; }
body.playing { touch-action: none; overscroll-behavior: none; }

Scoped to the surfaces that actually need gestures, plus a .playing class the game only adds once a run has genuinely started. On the menu, the iframe is a well-behaved passenger and scrolls out of the way like an image.

8. Versioning the entry point does not version the graph

This one shipped broken to production and I did not notice for a day.

public/originals/** is served statically with a long edge and browser TTL, while the play page reads index.html through a route handler. After a fix deploy those two disagreed for real: production served the new index.html while the CDN and returning browsers served the old src/main.js. The bug fix in that deploy simply did not run for players. The tell that it was cache and not a bad build was fetching the exact same URL with a junk query string, which returned the new file immediately.

So I put a ?v= on the module URL, bumped it, deployed, and it was still broken for anyone who had visited before. Relative imports resolve against the module URL, but the query string does not propagate. import { Game } from './game.js' inside main.js?v=2 requests game.js with no version at all, hits the cache, and a returning visitor runs new main.js against old game.js. Half a release, which is the worst possible state.

Every relative import has to carry the key too:

import { Game, COLORS, SHAPE_LABEL } from './game.js?v=7';
import { GameAudio } from './audio.js?v=7';

Bump all of them together, or you have invented a distributed systems problem inside one browser tab.

9. The menu rendered an empty void, and reading the code would never have told me

The menus in both games are live dioramas: the character idles in the real world while the camera slowly orbits. In the runner, the world generator's update(dt, playerZ, speed) only runs during play, by design, so idling does not burn distance or spawn obstacles. And reset() clears everything.

Clear everything, then never generate. The menu was a character standing in fogged nothing.

this.track.reset();
this.track.update(0, 0, 0);
this.player.reset();

One forced call with zero speed builds a full lookahead buffer of ground and scenery without starting the run. What matters is how I found it: by opening a browser and checking scene.children.length and groundTiles.length live. Reading the code would never have caught it, because every function in the chain is individually correct. The bug is the omission, and omissions only show up at runtime.

10. Flush edge-triggered input at every state transition

Space is the jump key. Space is also the start key. Two separate keydown listeners see the same event: input.js queues a jump into a 0.12s buffer regardless of game state, and main.js, registered second so it runs second on that same event, reads it as "start the run."

The run then begins with a jump already sitting in the buffer, and the character hops on frame one of every keyboard-started run.

this.input.consumeJump();
this.input.consumeLaneDir();

Two lines at the top of the function that starts a run. The general rule: any input system with edge-triggered "queued until consumed" semantics needs an explicit flush at every state transition that could have been triggered by the same device. A fresh state does not imply fresh input.

11. `PCFSoftShadowMap` is gone

Small one to finish. In r185 it is deprecated, it warns on every single load, and it silently falls back:

PCFSoftShadowMap has been deprecated. Using PCFShadowMap instead.

My quality tiers name the shadow type as a string and index Three with it, so a tier is data rather than a branch:

if (THREE && THREE[s.shadowMapType] !== undefined) {
  renderer.shadowMap.type = THREE[s.shadowMapType];
}

Low tier gets BasicShadowMap and no shadows at all, mid and high get PCFShadowMap. The upside is that shadow.radius actually applies under PCF, so the soft edge you thought the "soft" map type was giving you is finally real.

What I would do differently

Vendoring Three and skipping the bundler was correct and I would do it again. The games are static files, they cache forever, there is no build to break, and I can open a file in a browser and hit reload. That beats tree-shaking a library I am already using most of.

Three things I got wrong. I should have put the cache key in the imports on day one, on every game, instead of learning it in production on one game and back-porting. The two 3D games still ship bare imports, purely because they have not needed a fix deploy since. That is a loaded gun.

I should have built the live-inspection habit earlier. Bugs 9 and 4 were both invisible to code review and obvious within thirty seconds of opening a console. I now assume anything about lighting, or about what is in the scene at a given moment, is unknowable from the source.

And I should have written down the units. Half the pain in bug 3 and all of it in bug 5 came from assuming a number meant pixels when it meant world units, or that polygon count buys you shading when it buys you nothing under a constant normal. Those notes now sit in capitals at the point of use, which has already saved me twice on the other hand-built games in the same repo.

Kenneth Hartog builds and runs freegamesonline.com, where the in-house games are hand-written and the 3D ones are Three.js with no build step.

DEV Community: kentog751

The penny invariant: correctness guarantees in a game that teaches a child about money

Money is integer cents, and only integer cents

The penny invariant

Generate and check, with the check as an assertion

Difficulty that ramps inside the session, not just between stages

The coin cap, and why 24 cents is a bad first question

A wrong answer has to teach, not score

What I would do differently

No build step, no bundler: 11 things that broke shipping Three.js into an iframe

1. Probe WebGL on a canvas you throw away

2. Turn tone mapping off

3. gl_PointSize is not pixels, it is whatever your shader says

4. A chase camera means your character is always backlit

5. A flat plane renders as one flat colour, no matter how many polygons it has

6. Additive light shafts need two fades, not one

7. body { touch-action: none } turns your iframe into a scroll trap

8. Versioning the entry point does not version the graph

9. The menu rendered an empty void, and reading the code would never have told me

10. Flush edge-triggered input at every state transition

11. PCFSoftShadowMap is gone

What I would do differently

3. `gl_PointSize` is not pixels, it is whatever your shader says

7. `body { touch-action: none }` turns your iframe into a scroll trap

11. `PCFSoftShadowMap` is gone