Public: anyone can read this; the crew can change it.

Migrated from github.com/amirmushichge/pixel-plays

Snail Race rules: a tested `snail-race/race.js` where you pace a snail down a garden lane against three rivals, spending slime for bursts, from plain data #224

Parked opened this
Closed without merging

torque/pixel-plays:torque/202-snail-race-rules-a-tested-snail-race-rac → main 3 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
32 files changed +276 −2
.bash_profile added
No content changes.
.bashrc added
No content changes.
.claude/agents added
No content changes.
.claude/commands added
No content changes.
.claude/hooks added
No content changes.
.claude/launch.json added
No content changes.
.claude/loop.md added
No content changes.
.claude/output-styles added
No content changes.
.claude/routines added
No content changes.
.claude/scheduled_tasks.json added
No content changes.
.claude/settings.json added
No content changes.
.claude/settings.local.json added
No content changes.
.claude/skills added
No content changes.
.claude/workflows added
No content changes.
.gitconfig added
No content changes.
.gitmodules added
No content changes.
.idea added
No content changes.
.mcp.json added
No content changes.
.profile added
No content changes.
.ripgreprc added
No content changes.
.vscode added
No content changes.
.zprofile added
No content changes.
.zshrc added
No content changes.
forge.json +1 −1
@@ -2,6 +2,6 @@
22 "app": {
33 "run": "bun serve.mjs",
44 "health": "/",
5 "test": "bun test"
5 "test": "bun run-tests.mjs"
66 }
77 }
playtest.test.mjs → playtest.suite.mjs renamed +7 −1
@@ -24,13 +24,18 @@ function gesture(g, r) {
2424 // bring the untouched twin to the same frame as the played copy
2525 function sync(idle, played) { idle.step(played.frames - idle.frames); expect(idle.frames).toBe(played.frames); }
2626
27 // The games are played in PARTS files (playtest1..4.test.mjs) so run-tests.mjs runs them side by side:
28 // one file would play every game in turn and outgrow the deploy's time limit as the catalogue grows.
29 export const PARTS = 4;
30
31 export function playtests(part) {
2732 test('every game has a scripted round, and every script has a game', () => {
2833 expect(Object.keys(ROUNDS).sort()).toEqual(GAMES);
2934 });
3035
3136 test('the games folder is not empty', () => { expect(GAMES.length).toBeGreaterThanOrEqual(19); });
3237
33 for (const id of GAMES) {
38 for (const id of GAMES.filter((_, i) => i % PARTS === part)) {
3439 test(`${id}: boots, paints a picture and says what to do`, () => {
3540 const g = boot(id);
3641 g.run(2);
@@ -87,3 +92,4 @@ for (const id of GAMES) {
8792 expect(idle.text()).not.toMatch(ROUNDS[id].outcome);
8893 }, ROUNDS[id].budget ?? 120_000); // a timed round (wood-split's 60 s) is played twice in the engine's software renderer
8994 }
95 }
playtest1.test.mjs added +2
@@ -0,0 +1,2 @@
1 import { playtests } from './playtest.suite.mjs';
2 playtests(0);
playtest2.test.mjs added +2
@@ -0,0 +1,2 @@
1 import { playtests } from './playtest.suite.mjs';
2 playtests(1);
playtest3.test.mjs added +2
@@ -0,0 +1,2 @@
1 import { playtests } from './playtest.suite.mjs';
2 playtests(2);
playtest4.test.mjs added +2
@@ -0,0 +1,2 @@
1 import { playtests } from './playtest.suite.mjs';
2 playtests(3);
run-tests.mjs added +20
@@ -0,0 +1,20 @@
1 // Runs the suite as concurrent `bun test` processes: the playtest parts and everything else side by side.
2 // One process played every game in turn and outgrew the deploy's time limit as the catalogue grew.
3 // (`bun test --parallel` is not used: it loads each file in a worker, where serve.test.mjs cannot import serve.mjs.)
4 import { readdirSync } from 'node:fs';
5
6 const root = import.meta.dir;
7 const tests = [...readdirSync(root).filter(f => f.endsWith('.test.mjs')),
8 ...readdirSync(root, { withFileTypes: true }).filter(d => d.isDirectory() && !d.name.startsWith('.') && d.name !== 'node_modules')
9 .flatMap(d => readdirSync(`${root}/${d.name}`).filter(f => f.endsWith('.test.mjs')).map(f => `${d.name}/${f}`))].sort();
10 const isPlaytest = f => /^playtest\d\.test\.mjs$/.test(f);
11 const groups = [...tests.filter(isPlaytest).map(f => [f]), tests.filter(f => !isPlaytest(f))];
12
13 const codes = await Promise.all(groups.map(async files => {
14 const p = Bun.spawn(['bun', 'test', ...files], { cwd: root, stdout: 'pipe', stderr: 'pipe' });
15 const [out, err] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
16 const code = await p.exited;
17 console.log(`== ${files.length === 1 ? files[0] : files.length + ' files'} (exit ${code})\n${out}${err}`);
18 return code;
19 }));
20 process.exit(codes.some(c => c !== 0) ? 1 : 0);
snail-race/race.js added +142
@@ -0,0 +1,142 @@
1 'use strict';
2 // The Snail Race rules: four snails race down a garden lane; you press in rhythm to keep your snail moving and spend
3 // slime on bursts, while three seeded rivals keep their own pace. Plain data in, plain data out, no DOM, no timers,
4 // no Math.random: the rivals come from the seed. A refused action returns the very same state and says why.
5 //
6 // Units: metres, seconds, metres per second, slime in units. The beat is a click every BEAT seconds from t = 0; a step
7 // is on the beat when it lands within WINDOW seconds of the nearest click. Distances integrate speed with the
8 // trapezoid rule, d += (v0 + v1) / 2 * dt, exact for the piecewise-linear speed of your snail.
9 (function (root) {
10 const LANE = 30; // m, start line to finish line
11 const BEAT = 0.6; // s between beats
12 const WINDOW = 0.12; // s either side of a beat that counts as on the beat
13 const FLOOR = 0.4; // m/s, the slowest your snail goes
14 const CAP = 1.6; // m/s, the fastest your snail goes without a burst
15 const START_SPEED = 0.8; // m/s at the gun
16 const GAIN = 0.2; // m/s added by an on-beat step
17 const LOSS = 0.3; // m/s taken by an off-beat step
18 const DRAG = 0.1; // m/s^2, how fast speed fades back toward FLOOR with no steps
19 const SLIME = 100; // slime supply, which is also the most you can hold
20 const BURST_COST = 40; // slime spent by one burst
21 const BURST_BOOST = 0.9; // m/s added on top of your speed while a burst lasts
22 const BURST_TIME = 1.5; // s a burst lasts (a second burst restarts it)
23 const REFILL = 8; // slime returned by an on-beat step
24 const RIVALS = 3;
25 const MAX_DT = 0.1; // s, the longest step tick takes (longer is clamped)
26 const WIN = 1; // the place that is the win line
27
28 const finite = v => (Number.isFinite(v) ? v : 0);
29 // a repeatable number in [0, 1) for this seed and slot
30 function noise(seed, n) {
31 let h = (Math.imul(finite(seed) | 0, 374761393) + Math.imul(n | 0, 668265263)) | 0;
32 h = Math.imul(h ^ (h >>> 13), 1274126177);
33 return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
34 }
35 const lerp = (a, b, t) => a + (b - a) * t;
36 const round = v => Math.round(v * 1e6) / 1e6;
37 const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
38
39 // A rival's pace curve: speed(t) = base + swing * sin(2 pi t / period + phase), always above 0.
40 function rivals(seed) {
41 const out = [];
42 for (let i = 0; i < RIVALS; i++) {
43 out.push({
44 id: 'r' + (i + 1),
45 base: round(lerp(0.9, 1.25, noise(seed, 3 * i + 1))),
46 swing: round(lerp(0.1, 0.35, noise(seed, 3 * i + 2))),
47 period: round(lerp(4, 9, noise(seed, 3 * i + 3))),
48 phase: round(lerp(0, 2 * Math.PI, noise(seed, 3 * i + 11))),
49 });
50 }
51 return out;
52 }
53 const pace = (r, t) => r.base + r.swing * Math.sin((2 * Math.PI * t) / r.period + r.phase);
54
55 const place = (s, id) => s.places.indexOf(id) + 1;
56 function refresh(s) {
57 if (s.status === 'playing') {
58 const ahead = s.snails.filter(n => n.d > s.snails[0].d).length;
59 s.line = `Place ${ahead + 1} of ${RIVALS + 1}, ${round(Math.max(0, LANE - s.snails[0].d))} m to go`;
60 } else {
61 const p = place(s, 'you');
62 s.line = s.status === 'won' ? `You won in ${s.time} s: a win (first place needed)`
63 : `You came ${p} in ${s.time} s: a loss (first place needed)`;
64 }
65 return s;
66 }
67 const copy = s => Object.assign({}, s, { snails: s.snails.map(n => Object.assign({}, n)), places: s.places.slice() });
68 const refuse = (state, why) => ({ ok: false, why, state });
69
70 function start(seed = 1) {
71 seed = finite(seed) >>> 0;
72 const snails = [{ id: 'you', d: 0, v: START_SPEED, done: null }]
73 .concat(rivals(seed).map(r => Object.assign({ d: 0, v: round(pace(r, 0)), done: null }, r)));
74 return refresh({ seed, t: 0, snails, slime: SLIME, burstLeft: 0, places: [], time: 0, status: 'playing', why: '', line: '' });
75 }
76
77 // Your step at time state.t. On the beat: faster by GAIN up to CAP, and REFILL slime up to SLIME. Off the beat:
78 // slower by LOSS down to FLOOR.
79 function step(state) {
80 if (state.status !== 'playing') return refuse(state, 'The race is over');
81 if (state.snails[0].done !== null) return refuse(state, 'You have crossed the line');
82 const s = copy(state);
83 const off = Math.abs(s.t - Math.round(s.t / BEAT) * BEAT);
84 const onBeat = off <= WINDOW + 1e-9;
85 const me = s.snails[0];
86 me.v = round(onBeat ? Math.min(CAP, me.v + GAIN) : Math.max(FLOOR, me.v - LOSS));
87 if (onBeat) s.slime = Math.min(SLIME, s.slime + REFILL);
88 return { ok: true, onBeat, state: refresh(s) };
89 }
90
91 // Spend BURST_COST slime for BURST_BOOST m/s over BURST_TIME seconds; refused when slime is short.
92 function burst(state) {
93 if (state.status !== 'playing') return refuse(state, 'The race is over');
94 if (state.snails[0].done !== null) return refuse(state, 'You have crossed the line');
95 if (state.slime < BURST_COST) return refuse(state, `Not enough slime: ${BURST_COST} needed, ${state.slime} held`);
96 const s = copy(state);
97 s.slime -= BURST_COST;
98 s.burstLeft = BURST_TIME;
99 return { ok: true, state: refresh(s) };
100 }
101
102 // Advance every snail by dt seconds (clamped to MAX_DT). A snail that reaches LANE is stamped with the moment it did
103 // (linear within the tick) and stays on the line. When all four are across, the places are fixed.
104 function tick(state, dt) {
105 if (state.status !== 'playing') return state;
106 dt = Number.isFinite(dt) ? Math.min(MAX_DT, Math.max(0, dt)) : 0;
107 const s = copy(state);
108 const boost = Math.min(dt, s.burstLeft);
109 const me = s.snails[0];
110 for (const n of s.snails) {
111 if (n.done !== null) continue;
112 let v1, avg;
113 if (n.id === 'you') {
114 v1 = Math.max(FLOOR, n.v - DRAG * dt);
115 avg = (n.v + v1) / 2;
116 // the boost rides on top for the first `boost` seconds of the tick
117 const extra = (BURST_BOOST * boost) / (dt || 1);
118 avg += extra;
119 } else {
120 v1 = pace(n, s.t + dt);
121 avg = (pace(n, s.t) + v1) / 2;
122 }
123 const reach = n.d + avg * dt;
124 if (reach >= LANE) n.done = round(s.t + (avg > 0 ? (LANE - n.d) / avg : dt));
125 n.d = round(Math.min(LANE, reach));
126 n.v = round(v1);
127 }
128 s.burstLeft = round(Math.max(0, s.burstLeft - dt));
129 s.t = round(s.t + dt);
130 if (s.snails.every(n => n.done !== null)) {
131 const order = s.snails.map((n, i) => ({ id: n.id, done: n.done, i }));
132 order.sort((a, b) => a.done - b.done || a.i - b.i);
133 s.places = order.map(o => o.id);
134 s.time = me.done;
135 s.status = place(s, 'you') === WIN ? 'won' : 'lost';
136 }
137 return refresh(s);
138 }
139
140 const api = { LANE, BEAT, WINDOW, FLOOR, CAP, START_SPEED, GAIN, LOSS, DRAG, SLIME, BURST_COST, BURST_BOOST, BURST_TIME, REFILL, RIVALS, MAX_DT, WIN, start, step, burst, tick, pace };
141 if (typeof module !== 'undefined') module.exports = api; else root.SnailRace = api;
142 })(typeof window !== 'undefined' ? window : globalThis);
snail-race/race.test.mjs added +98
@@ -0,0 +1,98 @@
1 import { test, expect } from 'bun:test';
2 import * as R from './race.js';
3 const { LANE, BEAT, WINDOW, FLOOR, CAP, GAIN, LOSS, SLIME, BURST_COST, BURST_BOOST, REFILL, start, step, burst, tick } = R;
4
5 const at = (s, t) => Object.assign(s, { t });
6 const finish = (s, max = 20000) => { for (let i = 0; i < max && s.status === 'playing'; i++) s = tick(s, 0.1); return s; };
7
8 test('the same seed gives the same rivals, other seeds differ, and their pace stays positive', () => {
9 expect(start(7).snails).toEqual(start(7).snails);
10 expect(start(7).snails).not.toEqual(start(8).snails);
11 const s = start(7);
12 expect(s.snails).toHaveLength(4);
13 expect(s.snails[0].id).toBe('you');
14 expect(s.slime).toBe(SLIME);
15 expect(R.LANE).toBe(30);
16 for (const r of s.snails.slice(1)) for (let t = 0; t < 60; t += 0.5) expect(R.pace(r, t)).toBeGreaterThan(0.4);
17 });
18
19 test('a tick moves every snail by its speed, and a rival moves by its pace curve', () => {
20 const s = start(3);
21 const n = tick(s, 0.1);
22 expect(n.t).toBeCloseTo(0.1, 9);
23 for (const sn of n.snails) expect(sn.d).toBeGreaterThan(0);
24 // hand calculation: your speed 0.8 fades by DRAG * dt = 0.01, so the trapezoid mean is 0.795 m/s, 0.0795 m in 0.1 s
25 expect(n.snails[0].d).toBeCloseTo(0.0795, 6);
26 expect(tick(s, NaN)).toEqual(s);
27 });
28
29 test('an on-beat step raises speed, an off-beat step lowers it, both held between floor and cap', () => {
30 let s = at(start(1), BEAT * 2 + WINDOW - 0.01);
31 let r = step(s);
32 expect(r.onBeat).toBe(true);
33 expect(r.state.snails[0].v).toBeCloseTo(0.8 + GAIN, 9);
34 s = at(start(1), BEAT / 2);
35 r = step(s);
36 expect(r.onBeat).toBe(false);
37 expect(r.state.snails[0].v).toBeCloseTo(0.8 - LOSS, 9);
38 expect(step(at(start(1), BEAT + WINDOW + 0.02)).onBeat).toBe(false);
39 // many on-beat steps stop at the cap, many off-beat steps stop at the floor
40 let up = at(start(1), BEAT * 3);
41 for (let i = 0; i < 20; i++) up = step(up).state;
42 expect(up.snails[0].v).toBe(CAP);
43 let down = at(start(1), BEAT / 2);
44 for (let i = 0; i < 20; i++) down = step(down).state;
45 expect(down.snails[0].v).toBe(FLOOR);
46 });
47
48 test('a burst spends slime for a speed boost and is refused when slime is short', () => {
49 const s = start(1);
50 const r = burst(s);
51 expect(r.ok).toBe(true);
52 expect(r.state.slime).toBe(SLIME - BURST_COST);
53 const plain = tick(s, 0.1).snails[0].d;
54 const boosted = tick(r.state, 0.1).snails[0].d;
55 expect(boosted - plain).toBeCloseTo(BURST_BOOST * 0.1, 6);
56 const poor = Object.assign(start(1), { slime: BURST_COST - 1 });
57 const no = burst(poor);
58 expect(no.ok).toBe(false);
59 expect(no.state).toBe(poor);
60 expect(no.why).toContain('slime');
61 // the boost ends after BURST_TIME
62 let b = r.state;
63 for (let i = 0; i < 20; i++) b = tick(b, 0.1);
64 expect(b.burstLeft).toBe(0);
65 });
66
67 test('an on-beat step refills slime up to the supply, an off-beat step does not', () => {
68 const spent = burst(start(1)).state;
69 const on = step(at(spent, BEAT)).state;
70 expect(on.slime).toBe(SLIME - BURST_COST + REFILL);
71 expect(step(at(spent, BEAT / 2)).state.slime).toBe(SLIME - BURST_COST);
72 expect(step(at(start(1), BEAT)).state.slime).toBe(SLIME);
73 });
74
75 test('the race ends when all four cross: places in order, your time, win line and loss line', () => {
76 let s = start(5);
77 expect(s.status).toBe('playing');
78 s = finish(s);
79 expect(s.places).toHaveLength(4);
80 expect(new Set(s.places).size).toBe(4);
81 const done = Object.fromEntries(s.snails.map(n => [n.id, n.done]));
82 for (let i = 1; i < 4; i++) expect(done[s.places[i]]).toBeGreaterThanOrEqual(done[s.places[i - 1]]);
83 expect(s.time).toBe(done.you);
84 // standing still-ish at the floor, you lose
85 expect(s.status).toBe('lost');
86 expect(s.places[0]).not.toBe('you');
87 expect(s.line).toContain('a loss');
88 expect(tick(s, 0.1)).toBe(s);
89 expect(step(s).ok).toBe(false);
90 // a lead of LANE metres at the start wins
91 const w = start(5);
92 w.snails[0].d = LANE - 0.05;
93 const won = finish(w);
94 expect(won.status).toBe('won');
95 expect(won.places[0]).toBe('you');
96 expect(won.line).toContain('a win');
97 expect(won.snails.every(n => n.d === LANE)).toBe(true);
98 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs