The whole game is one HTML file of 155,830 bytes (53,801 gzipped). It holds the engine, three levels, synthesised music and 135 Tang poems, and makes no network request. This post is about the engine: the board, move generation, the rules that trip people up, and how the opponent thinks without freezing the page. The snippets are copied from the game's TypeScript source; the rules engine and search are about 1,050 non-blank lines.

Just enough rules

Xiangqi is played on the points of a 9 by 10 grid, with a river across the middle and a 3 by 3 palace on each side. Each side has a general and two advisors (both stay in the palace), two elephants (two points diagonally, never across the river), two horses, two chariots, two cannons and five soldiers. Four rules matter for the code:

• A horse moves one point straight, then one diagonally outward, and is blocked if the first point is occupied. An elephant is blocked by a piece on the point between ("the eye").
• A cannon moves like a chariot but captures only by jumping exactly one piece, the screen.
• The two generals may never face each other on an open file.
• A side with no legal move has lost, whether or not it is in check. Stalemate is a loss, not a draw.

The board: 90 numbers and some precomputed tables

A position is an Int8Array(90), point rank * 9 + file, rank 0 being Black's back rank. A piece is one byte, type | (colour + 1) << 3, so Red pieces are 9 to 15 and Black pieces 17 to 23, and "is this mine?" is one AND against 8 << side. A move is from | to << 7 in one integer.

All the geometry is worked out once at load time in tables.ts: for every point, where a general, advisor or soldier can step, and four rays for the sliding pieces. The horse and elephant tables store pairs, the target and the point that must be empty ([to, leg, to, leg, ...]), and the elephant table has the river built in. Move generation then does no geometry, and the blocked horse or elephant is one comparison, if (b[st[i + 1]!] !== 0) continue;, commented "the eye, or the leg, is blocked".

The cannon is two loops over the same ray. The first walks empty points as quiet moves. The second starts after the first piece it meets (the screen) and looks for the next piece beyond it:

        case CANNON: {
          const rays = RAYS[s]!;
          for (let d = 0; d < 4; d++) {
            const ray = rays[d]!, len = ray.length;
            let i = 0;
            for (; i < len; i++) { const t = ray[i]!; if (b[t] !== 0) break; if (!capsOnly) out[at++] = s | (t << 7); }
            for (i++; i < len; i++) { const t = ray[i]!, q = b[t]!; if (q !== 0) { if (q & opp) out[at++] = s | (t << 7); break; } }   // over exactly one piece
          }
          break;
        }

The generator is pseudo-legal: it does not ask whether the mover's general is left attacked. Legality is checked by making the move and asking inCheck.

The flying general is a chariot

This is the decision I would copy first. Instead of a separate "generals facing" test, inCheck treats the enemy general as a chariot that only attacks along the file. It looks outward from the general being tested: the points a soldier or horse could attack from (each horse point paired with the leg that must be empty), then the four rays. The first piece on a ray is a chariot or a facing general. The second, behind a screen, is a cannon:

  inCheck(c: Color): boolean {
    const b = this.board, k = this.kings[c]!, o = c ^ 1, base = (o + 1) << 3;
    const pawn = base | PAWN, horse = base | HORSE, rook = base | ROOK, cannon = base | CANNON, king = base | KING;
    const pf = PAWN_FROM[o]![k]!;
    for (let i = 0; i < pf.length; i++) if (b[pf[i]!] === pawn) return true;
    const hf = HORSE_FROM[k]!;
    for (let i = 0; i < hf.length; i += 2) if (b[hf[i]!] === horse && b[hf[i + 1]!] === 0) return true;
    const rays = RAYS[k]!;
    for (let d = 0; d < 4; d++) {
      const ray = rays[d]!, len = ray.length;
      let i = 0;
      while (i < len && b[ray[i]!] === 0) i++;
      if (i >= len) continue;
      const p = b[ray[i]!]!;
      if (p === rook || (p === king && d < 2)) return true;
      i++;
      while (i < len && b[ray[i]!] === 0) i++;
      if (i < len && b[ray[i]!] === cannon) return true;
    }
    return false;
  }

d < 2 means up or down the file. A move that opens the file between the generals leaves the mover "in check" and is rejected by the same code that rejects any other move into check.

The generator is tested by perft from the opening position (44, 1,920, 79,666 and 3,290,240 positions at one to four plies) and against a second generator in the tests, "written slowly and plainly from the rules and sharing no code with src/sim", on every position of 60 random games: over 4,000 positions and 100 checks.

Make and unmake, with a history the rules can read

make() updates everything incrementally: the board, the general's square, a 64-bit Zobrist hash kept as two 32-bit halves (hashL, hashH), and the evaluation. It also pushes onto parallel typed-array stacks: the move, what it captured, whether it gave check, and the hash before it. unmake() restores the hash from the stack. Those stacks do double duty: repetition and perpetual check are read straight from them, in the search and in the game alike.

Repetition and perpetual check: what is actually implemented

The rules of a whole game sit in Match.judge(), called after every move:

  private judge(): void {
    const pos = this.pos, side = pos.side;
    if (!pos.hasLegalMove()) { this.end(other(side), pos.inCheck(side) ? 'checkmate' : 'stalemate'); return; }
    const c = this.cycle();
    if (c.count >= 3) {
      if (c.selfAll && !c.oppAll) this.end(other(side), 'perpetual');
      else if (c.oppAll && !c.selfAll) this.end(side, 'perpetual');
      else this.end(-1, 'repetition');
      return;
    }
    if (pos.attackers(0) === 0 && pos.attackers(1) === 0) { this.end(-1, 'material'); return; }
    if (this.quietPlies() >= MOVE_LIMIT) this.end(-1, 'moveLimit');
  }

cycle() walks back through the hash stack, but only to the last capture, since a position cannot recur across one. It counts earlier occurrences of the current position with the same side to move, then checks whether each side gave check with every one of its moves since the first occurrence. On the third occurrence, a side that checked every time while the other did not loses; anything else is a draw. A game is also drawn after 120 plies without a capture (MOVE_LIMIT, sixty moves each), or when neither side has a chariot, cannon, horse or soldier left, the pieces that can cross the river.

Be clear about what this is not. The tournament rules for xiangqi repetition also forbid perpetual chasing, endlessly attacking an unprotected piece without check, and have detailed cases for mixed check-and-chase cycles. This engine implements perpetual check only; a perpetual chase is ruled a draw by repetition. That is a simplification for a game against the computer, and it is the first thing I would add for a rules-strict implementation.

Inside the tree, repStatus() reads the same stacks, and a single repeat is enough, as usual in engines. if (self && !opp) return -BAN + ply; scores a line where the side to move has checked forever as lost, and a plain repeat is worth CONTEMPT = 20 below zero for the engine's side. These path-dependent scores are never stored in the transposition table. Before any search, the opponent also drops every root move that forfeits() says would lose on the spot. The player gets the same protection: such a move is refused with "Perpetual check is forbidden. Choose another move." whenever another move exists, and a warning appears after the second occurrence (perpetualRisk()).

The search

search.ts is conventional: iterative deepening, alpha-beta with a principal variation (null-window searches after the first move), a transposition table, null-move pruning, late-move reductions, check extensions and a quiescence search over captures.

• Transposition table: 2^18 entries in six parallel typed arrays, about 3.7 MB, indexed by the low hash half, verified against both halves, always replaced.
• Move ordering: hash move, then captures by most valuable victim and least valuable attacker, then two killers per ply, then a from * 90 + to history table that grows by depth * depth on a cutoff. Moves are picked one at a time, not sorted.
• Null move: the pass is searched at depth - 3, only when not in check and only for a side with enough pieces (rooks * 2 + cannons + horses >= 2), because zugzwang is common in thin xiangqi endings.
• Late-move reductions: quiet, non-checking moves after the fourth lose 1 ply (2 after the fourteenth at depth 5 or more) and are searched again at full depth if they surprise.
• Mate and stalemate: a node with no legal move returns -MATE + ply. There is no separate stalemate case, because the rule makes both a loss.

The evaluation is the weakest part. It is material plus piece-square tables, plus 3 for having the move: a soldier before the river is worth 100, a horse about 430, a cannon about 450, a chariot about 920. There is no mobility, no king safety beyond the general's table, and no idea of a hanging piece outside the quiescence search. I would add a cheap mobility and attacked-piece term next, kept only if it wins against the current version.

Three levels from one search

The levels are not different engines. They are numbers in difficulty.ts:

Hard's 14 plies are a ceiling: the search also stops at 1.2 million positions, at 4 seconds, and starts no new iteration once half the node budget is spent. I did not measure the depth it usually reaches. For the first 8 plies of a game from the usual start, Hard searches 5 plies and strays up to 14, so that no two games open alike.

"May stray" is the interesting part. For Easy, Medium and Hard's opening, scoreAll() scores every root move within the margin of the best, and the move is drawn with weights that fall off exponentially with the gap. A weaker level plays plausible second-best moves, not random ones:

  if (margin > 0) {
    const scored = s.scoreAll(m.pos, limits, margin, list);
    let best = -Infinity;
    let top = scored[0]!;
    for (const x of scored) if (x.score > best) { best = x.score; top = x; }
    // a game that is decided is not strayed in: the quickest win, or the longest defence
    if (best > WIN || best < -WIN) return { move: top.move, score: top.score, depth, nodes: s.nodes, kind: 'best' };
    const w = scored.map((x) => Math.exp(-(best - x.score) / Math.max(1, margin / 2)));
    let r = rng.next() * w.reduce((a, b) => a + b, 0), pick = scored[scored.length - 1]!;
    for (let i = 0; i < scored.length; i++) { r -= w[i]!; if (r <= 0) { pick = scored[i]!; break; } }
    return { move: pick.move, score: pick.score, depth, nodes: s.nodes, kind: 'margin' };
  }

Once a forced mate is found, the level stops straying. The gaps were measured in self-play: a ladder of in-between levels played matches, and the scores became Elo differences, recorded as Medium about +1,389 and Hard about +2,086 above Easy (120 games). The source itself calls them rough, because neighbouring steps won 19 games of 20. Randomness is seeded (mulberry32), and a test checks that a seed replays the same game with the time limit off.

One weakness is plain: Easy's 12% random move is rolled before the search. On roughly one move in eight Easy plays a random legal move without looking, so it can miss a mate in one (the mate-in-one test sets blunder: 0). I would make the random move skip forced wins.

Off the main thread, in a single file

A one-file game has no worker.js to load. The game starts its own script a second time as a Web Worker:

if (typeof document === 'undefined') {
  runWorker(self as unknown as Parameters<typeof runWorker>[0]);
} else {
  const source = (document.currentScript as HTMLScriptElement | null)?.textContent ?? null;

The page passes that text to Engine, which wraps it in a Blob, makes an object URL and starts new Worker(url), so no second file is needed. Each request carries the starting FEN and the full move list, not just the current position. The worker replays the game, so it knows every repetition, and its transposition table survives from move to move. If no worker can be made, the search runs on the page after two animation frames, capped at 450 ms and 150,000 positions: weaker than Hard, but the board stays responsive. Leaving a game terminates a busy worker and starts a fresh one.

Take-backs need almost nothing from the engine: one pops two plies (yours and the reply) with the same unmake(), at most three times a game, only on your turn. The next request sends the shorter move list.

What I would copy

1. Treat the facing generals as a chariot along the file inside inCheck, and the rule costs nothing extra.
2. Keep one history stack per position (move, capture, gave-check, hash before) and read repetition and perpetual check from it, in the search and in the game alike.
3. Weaken by margin, not by noise. Score the moves near the best and draw from them with exponential weights.
4. Test the generator against a second, naive one as well as perft.

And what I would change: a chase rule, a richer evaluation, and an Easy level whose random moves never throw away a mate.

CHINESE CHESS runs in any modern browser: free, no ads, no purchases, no sign-up. The other games are on the Ant Games home page.

"Supposed to" is the hard part. You can't get there by feel with a hundred heroes and a thousand skills, so the numbers come from simulation. This post is how that works, with real snippets from the game's repository and numbers I re-measured while writing it.

A disclosure first: the game and its balance tooling were made with AI agents, on Ant Games' production line (the project was handed to the line as a finished base; agents audited and keep working on it). The game itself is fully in Chinese inside (title 同阶英雄竞技场); its page on our site is in English and Chinese: English, 中文. Everything below is plain JavaScript you can read in the repo's tools/ folder.

The idea: one budget, one dial

Every hero is built from the same role template (a tank has 1200 HP and 78 ATK, an assassin 700 HP and 128 ATK) and ten skills whose power is priced by a points budget (js/core/budget.js, where 1.0 is one basic attack). Authoring by budget gets you into the right neighbourhood, but not the right house.

So each hero gets exactly one balancing number, a dial. It is not a grade and the player never sees or changes it. It multiplies HP, ATK and DEF, and also the stat-independent numbers in the kit (shield size, heal percent, buff values), so one number moves everything the hero does:

HA.retune = function () {
  for (var n = 0; n < HA.HEROES.length; n++) {
    var h = HA.HEROES[n], t = HA.TUNING && HA.TUNING[h.id], f = (t && t.mult) || 1;
    var slots = dialled[h.id] || (dialled[h.id] = dialSlots(h));
    for (var i = 0; i < slots.length; i++) {
      var s = slots[i], sign = s.v < 0 ? -1 : 1;
      var v = Math.round(Math.abs(s.v) * f / s.q) * s.q;   // authored value, scaled, snapped to its step
      v = Math.min(s.max, Math.max(s.min, v));            // never past the stat's own limits
      s.o[s.k] = sign * Math.round(v * 1000) / 1000;
    }
  }
};

Every call starts from the authored numbers, so the tuner can call it thousands of times with different dials. Because skill text in the game is generated from those numbers, the tooltip always says what the retuned skill really does.

Step 1: make "a fair test" precise

"Win rate" depends entirely on who the hero fights alongside. The tuner uses a sampler of random but sensible teams: a front line, usually a support, and no more than two of any back-line role.

plan.push(rng() < 0.8 ? 'tank' : 'fighter');
plan.push(rng() < 0.7 ? (plan[0] === 'tank' ? 'fighter' : 'tank') : null);
let needSupport = rng() < 0.75;
// ...fill the rest from ['assassin','mage','ranger','support'], at most 2 of any

Two such teams fight with every hero on its standard build, and each hero's wins are credited to every hero on the winning team. Battles are fully deterministic given a seed (a small mulberry-style generator, HA.makeRng), so every number below can be reproduced.

Step 2: pick the build before you tune the power

A hero brings 6 of its 10 skills (4 actions, 2 passives), so "the hero" is really a family of builds. If you tune power against a bad build you'll boost a hero to compensate for a mistake. So the tool first finds each hero's standard build by greedy search plus single swaps, scored in 1,200 fixed scenarios (random allies, random foes, fixed seeds):

// greedy from nothing: which skill helps most next?
for (let step = 0; step < H.LOADOUT_SIZE; step++) { /* try every legal slot, keep the best */ }
// then single swaps until none helps (greedy picks can block a better pair)
for (let round = 0; round < 5; round++) { /* swap one skill; stop when the gain is under 0.002 */ }

The score of a scenario is half win/loss and half the HP fraction left, which is much less noisy than win/loss alone. The search also records each skill's value: what you lose by dropping it.

Step 3: tune the dials by feedback

The core loop is almost embarrassingly simple. Measure every hero's win rate, then nudge its dial against the error:

for (const id of ids) mult[id] *= Math.exp(-gain * (m.wr[id] - 0.5));
normalise();   // keep the geometric mean of all dials at 1, bounded to 0.45..2.0

The exponential keeps dials positive and symmetric; normalise() stops the whole roster drifting stronger together. The tool runs a few coarse passes, re-finds builds, then fine passes: 120,000 battles per pass across worker processes (the header comment quotes about 30,000 battles a second on a 32-thread machine).

Step 4: equal win rate isn't enough

This is the part I think is worth stealing. If every hero wins 50% of random teams, you can still have a game where nobody picks half of them. A hero can be average in random teams and useless in the best teams, or be in every winning team. So the tuner measures a second thing: for every hero, search for the best team that contains it (start from winners of an open self-play league, swap the hero into each seat, mutate, keep the best) and play those hundred teams against the league's best. That number is top. Each meta round then combines three readings into one dial update:

mult[id] *= Math.exp(-g * (G_TOP * (vS[i] - target)       // best team with this hero vs the league
                         + G_PICK * overPicked(uS[i])      // how many top line-ups field it
                         + G_RATE * (m.wr[id] - 0.5)));    // random-team win rate

with G_RATE = 0.6, G_TOP = 0.5, G_PICK = 0.06. A hero that is strong only next to certain partners ends up with a lower dial: weak alone, strong in its combo. The best team found for each hero then joins the league, so line-ups the league never reached by itself get their chance to take over. The full run is 30 meta rounds; the shipped table records 35.2 million battles.

What it produced

The output is a generated file, js/data/tuning.js, one line per hero (this is the real first row):

wisp: { mult: 1.144, wr: 0.529, top: 0.758, order: ['p3','u2','p2','a3','a1','a2','p1','a4','u1','p4'], val: { ... } },

I re-measured it with the game's own sampler and the real engine, 400,000 battles each way, one process (scripts/article3-measure.cjs in our SEO folder; about three minutes each):

The dials that did it run from 0.638 to 1.416. The stored top values range from 60.9% to 86.1%: even the weakest hero's best team beats the league's best teams 60.9% of the time here, and no hero's best team falls under 45%.

Where it falls short

I'd rather tell you than have you find it. Three honest limits, all from our own audit (docs/audits/balance.md, 400,000 battles, written by an Opus-class agent that was told to mend nothing):

• "Equal" means a band of about plus or minus 6 points, not 50.0%. Twelve heroes sit outside 45-55%; none is outside 40-60. The audit noted the tool could narrow this with a higher G_RATE or more passes. We have not.
• Balancing heroes did not balance the ladder. The rating numbers shown on the rival ladder (library line-ups) are on the wrong scale between 1400 and 2600: 400 points apart wins about 57%, where the rating formula says 91%. Fixing the hero dials never touched that, because it's a different mechanism (how rivals get rated).
• Combos add nothing at equal rating (50.0% in 200 matched pairs). They are already priced into the rating, so tuning combos up on that reading would have been a mistake.

One thing it cleared: with the same line-ups on both sides, side A won 50.3% over 50,000 battles.

What I would reuse

1. One dial per entity, applied everywhere the entity's numbers live. Scaling only HP and ATK misses shields, heals and buffs.
2. Fix the builds first. Otherwise the dial absorbs a bad build.
3. Feedback in log space with a normaliser. Ten lines, and a few passes settle it.
4. Measure two things: random-team win rate and best-team strength. The second one is what keeps a hero from being fair on paper and pointless in practice.
5. Write the audit that contradicts you. Ours caught the rating scale, which the hero numbers could never have shown.

To see the result, the game is free and runs in one page: EQUAL HEROES ARENA (中文页面), or the Ant Games home page for the other games. The interface is in Chinese.

This post covers the techniques we actually use, with snippets trimmed from the audio code of three of our games: JETSUN (plain JavaScript), STAR AGAINST THE DARK and SALLY PORT (TypeScript). It is not a Web Audio tutorial; it assumes you know what an OscillatorNode is.

1. A tiny kit of voice helpers

Almost every sound effect is built from the same few blocks. JETSUN wraps them in four functions: a swept oscillator, filtered noise, two-operator FM and a "musical note". The workhorse:

// percussive envelope: attack, decay to -30 dB over `dur`, 20 ms release
function perc(a, param, t, att, dur, vol) {
  a.env(param, t, [[0, 0.0001], [att, vol], [dur, vol * 0.03], [dur + 0.02, 0.0001]]);
}

function tone(a, t, out, type, f0, f1, dur, vol = 1, att = 0.002) {
  const g = a.gain(0, out);
  perc(a, g.gain, t, att, dur, vol);
  const o = a.osc(type, f0, t, dur, g);
  if (f1 !== f0) a.env(o.frequency, t, [[0, f0], [dur, f1]]);  // pitch sweep
  return o;
}

Two details matter. Envelopes ramp to 0.0001, never to 0, because exponential ramps cannot reach zero. And every helper takes the start time t explicitly instead of using "now", so a recipe can be placed anywhere on the audio clock. a.osc() creates the oscillator, starts it and schedules its stop, so nothing leaks.

A rapid-fire machine gun is then a swept square wave plus a short noise burst:

defineSound('p.vulcan', {
  vol: 0.3, minGap: 0.045,
  play(a, t, out, o) {
    const p = (o.pitch || 1) * R(0.96, 1.04);       // random pitch per shot
    tone(a, t, a.filter('lowpass', 2600, 0.7, out), 'square', 430 * p, 120 * p, 0.07, 0.8, 0.001);
    hiss(a, t, out, 'bandpass', 3200, 1400, 0.035, 0.5, 0.9, 0.001);
  },
});

The pitch jitter stops repeated shots from sounding like one sample on loop, and minGap stops a sound from stacking up when it is triggered every frame.

FM is just as short. The modulator's gain is the modulation depth, and it decays with the note, so the timbre goes from bright to dull the way a struck bell or a zap does:

const c = a.osc(type, fc, t, dur, g);                  // carrier
const depth = a.gain(fc * ratio * index);
a.env(depth.gain, t, [[0, fc * ratio * index], [dur, 1]]);
a.osc('sine', fc * ratio, t, dur, depth);              // modulator
depth.connect(c.frequency);                            // audio-rate frequency modulation

2. One shared noise buffer

Noise is everywhere: explosions, hi-hats, wind, shots. Instead of a buffer per sound, create two seconds of white noise once and share it:

const nb = ctx.createBuffer(1, ctx.sampleRate * 2, ctx.sampleRate), nd = nb.getChannelData(0);
for (let i = 0; i < nd.length; i++) nd[i] = Math.random() * 2 - 1;

Each voice plays that buffer through its own filter. For endless wind or engine loops set loop = true and start at a random offset (s.start(t, Math.random())) so two loops never line up in phase. SALLY PORT does the same but fills its buffer from a seeded PRNG (new Rng(99)), so the noise is identical on every run, which matters for section 7.

3. A reverb with no impulse-response file

A convolution reverb normally needs a recorded impulse response. You can generate one: noise multiplied by a decay curve is a perfectly decent small hall.

const len = Math.floor(ctx.sampleRate * 2.2), ir = ctx.createBuffer(2, len, ctx.sampleRate);
for (let ch = 0; ch < 2; ch++) {
  const d = ir.getChannelData(ch);
  for (let i = 0; i < len; i++) d[i] = (Math.random() * 2 - 1) * Math.pow(1 - i / len, 2.6);
}
reverb = ctx.createConvolver(); reverb.buffer = ir;

Independent noise per channel gives a wide stereo tail for free. Each sound declares how much it sends (reverb: 0.3 for the railgun, nothing for the machine gun) and the engine wires a send gain to the shared convolver.

4. A music sequencer that schedules ahead on the audio clock

setInterval is far too jittery to time notes. The standard answer is a look-ahead scheduler: a timer wakes up often, and each time schedules every note that falls inside the next fraction of a second, using exact AudioContext times. JETSUN's music kit does this:

tick(now) {  // called ~40 times a second
  if (this.t < now - 0.1) while (this.t < now + 0.02) this._next(); // stalled: skip along the grid, no burst
  while (this.t < now + LOOK) { this._play(this.t); this._next(); } // LOOK = 0.25 s
}
_play(t) {
  if (this.step & 1) t += this.swing;                  // swing the off-beat sixteenths
  for (const layer of this.layers) { /* play this step's event if the layer is on */ }
}

The "stalled" line matters. If a tab was in the background and the timer was throttled, this.t is far in the past, and a naive loop would fire hundreds of notes at once. Skipping along the grid without playing keeps the music in time.

Our tracks are data, not audio. A JETSUN tune is a string notation per bar plus a layer table:

const HOOK = "3 - - 5 8 - - - | 7 - - 6 5 - - - | 6 - - 8 3' - 9 - | ...";
bpm: 108, key: 50, scale: 'major',
layers: {
  kick:  { inst: 'drum', kit: 'kick', vol: 0.7, at: 0.38, pat: 'X.....x.X.......' },
  snare: { inst: 'drum', kit: 'snare', vol: 0.42, at: 0.42, pat: '....X.......X...' },
  lead:  { inst: 'lead', vol: 0.27, wave: 'sawtooth', wave2: 'square', det: 6, vib: 7, at: 0.33 },
}

Notes are scale degrees, not frequencies, so a track changes key by changing one number. The at field is the intensity at which a layer comes in: the game calls setIntensity(0..1) and the arrangement thickens (pad and bells when calm, drums and lead as danger rises) without restarting the track.

5. Custom waveforms with createPeriodicWave

The four built-in oscillator types are limiting for pads. STAR AGAINST THE DARK builds its own from harmonic recipes: amplitude falling as 1 / h^power is soft for a high power and bright for a low one, and dropping the even harmonics gives a hollow, reedy tone.

const wave = (n: number, power: number, oddOnly: boolean): PeriodicWave => {
  const re = new Float32Array(n + 1), im = new Float32Array(n + 1);
  for (let h = 1; h <= n; h++) im[h] = oddOnly && h % 2 === 0 ? 0.12 / Math.pow(h, power) : 1 / Math.pow(h, power);
  return ctx.createPeriodicWave(re, im);
};
this.waves = [wave(10, 1.7, false), wave(14, 1.35, false), wave(15, 1.25, true), wave(20, 1.1, false)];
// later: oscillator.setPeriodicWave(this.waves[st.wave]);

Four recipes from soft to bright, and the music state picks one. No sample files, a handful of lines.

6. The master chain: limiter, then a soft clip

With dozens of voices the output clips unless you plan for it. STAR AGAINST THE DARK ends its chain with a compressor used as a limiter, a trim gain and a WaveShaper soft clip:

master.connect(limiter).connect(trim).connect(clip).connect(out);
out.connect(ctx.destination);

Two notes from that file. First, a DynamicsCompressorNode applies automatic makeup gain, so the trim value is computed from the compressor's settings rather than guessed. Second, a Blink quirk noted in the code: the compressor starts fully closed and only opens while it is being fed, so the first sound after start-up lost its attack. The fix is to feed it an inaudible 20 Hz tone for a moment:

const warm = ctx.createOscillator();
warm.frequency.value = 20;
const warmGain = ctx.createGain();
warmGain.gain.value = 1e-5;
warm.connect(warmGain).connect(limiter);
warm.start(); warm.stop(ctx.currentTime + WARMUP);

SALLY PORT and JETSUN use a simpler master (a compressor into the destination). Separate buses for music and effects, each with its own volume and a mute, are what make a game's settings screen work. SALLY PORT also has a duck gain on the music bus, eased with setTargetAtTime(on ? 0.3 : 1, t, 0.15), so music drops while a menu is open.

7. Test it offline, render it deterministically

Because the graph is built on a plain BaseAudioContext, the same code runs on an OfflineAudioContext. STAR AGAINST THE DARK has an audio checker that renders each sound and each music state to a buffer with four output channels: the final output, and the mix just before the limiter, so you can see what the limiter did.

const ctx = new OfflineAudioContext({ numberOfChannels: 4, length, sampleRate: 48000 });
const core = new AudioCore(ctx, { seed, sink });   // the same graph the realtime engine builds

Two ingredients make this useful: a seeded PRNG (the file uses mulberry32) in place of Math.random(), so a render is reproducible, and measurement of the result (peak, loudness, what the limiter removed), so a sound that is too quiet or clipping fails a check instead of waiting for a player to notice.

8. Tie the visuals to the audio clock

SALLY PORT has one more trick worth stealing. Its beat() method returns 1 on each beat, falling to 0 before the next, computed from ctx.currentTime rather than a frame counter:

const ph = (ctx.currentTime - this.beatT) / this.beatDur;

Anything on screen that pulses (a light, a bar, a camera nudge) reads it and stays in time with what you hear, even if the frame rate stutters.

Practical notes

• Unlock on a user gesture. Create or resume the context on the first pointerdown or keydown. JETSUN does both, and suspends the context when document.hidden.
• Seed anything you want to test. Use a seeded PRNG for sound design that has to be reproducible.
• Disconnect what you create. We track live sources and disconnect them when they end.
• Rate-limit every sound. A per-sound minimum gap costs one comparison and saves your mix.

The trade-off is real: code-made audio costs design time, and it will not sound like a recorded orchestra. What it gives you is a game that is one file, loads instantly, runs offline, and whose music can respond to play in ways a fixed recording cannot.

To hear the results, JETSUN and STAR AGAINST THE DARK are playable in the browser, and the rest are on the Ant Games home page. The site and each game's page are available in English and Simplified Chinese. Questions about any of the techniques above are welcome in the comments.

The contract

From the production guide every game on the site is built to:

• One self-contained page. dist/index.html holds everything. It makes no network request of any kind: no CDN, no web font, no analytics, no fetch. It runs from a double-click (file://).
• No asset files beside the page. Models, textures, sprites, icons, sound effects and music are generated by code. Fonts are system font stacks.
• TypeScript, strict. Sources are bundled with esbuild into the single page. The only runtime dependency allowed is three, and only for a 3D game.
• A deterministic, headless simulation. Game logic lives apart from rendering: fixed timestep, all randomness from a seeded generator, no DOM, no clock, no Math.random(). The same seed and inputs give the same game in the browser and in Node.
• No alert, confirm or prompt, and saves are versioned JSON under a per-game localStorage prefix; a save that does not parse is replaced, never trusted.
• Languages: The site and every game page are in English and Chinese; Equal Heroes Arena is fully in Chinese, and the others are in English for now.

And on the business side: no ads, no purchases, no sign-up, nothing imitating selling.

Why a single file

A page with no outside requests can't break because a CDN moved, can't leak the player's visit to a third party, and can be archived, emailed or opened offline. It also forces honesty about size: our built SALLY PORT page is 822,010 bytes and HAIRS BREADTH's is 734,817 bytes, with all code, graphics and audio inside.

Graphics: WebGL2

JETSUN, a side-scrolling shoot-'em-up in full 3D, uses three.js on WebGL2 with an HDR render target, MSAA, bloom, a custom post pass and ACES tone mapping, with procedural lofted models and detail maps. Its game.json says it plainly: "Every model, texture, effect, sound and note of music is generated in code." Other games bring their own renderer rather than a library; the guide's rule is to borrow machinery (WebGL helpers, batching, bloom chain, input, save plumbing) but never a game's identity.

Where code is bad at something, such as rigs and baked light, the project allows Blender as an offline tool. Its output is baked into the page as data, so the single-file, no-requests rule still holds.

Audio: synthesised, not sampled

Every effect is synthesised, and music comes from a step sequencer rather than audio files. SALLY PORT, a gate-defence game with 50 levels and 50 bosses, lists "62 sound effects and no asset files" and a distinct music track for each of its five places. Each game has separate volumes and mute.

A deterministic simulation pays for itself

Because the simulation is seeded and headless, the same code runs in Node for tests and bot balance runs, and a seeded daily run comes almost for free: HAIRS BREADTH, a three-lane runner through a jungle temple, ships The Escape (five zones, with an ending), Endless and a seeded Daily Run.

What we would tell you

Constraints that look like limits (no network, no files, no clock) mostly turned into free testability and portability. The cost is real: everything, from sound to models, becomes code you maintain.

You can try the result at antgames.ai, where games are free, without ads or purchases.