@journey-to-code/physics 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mikey Nichols
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,158 @@
1
- # Temporary Holding Version
1
+ # @journey-to-code/physics
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A small, deterministic 2D physics core for turn-based ball games: mini golf first, then billiards,
4
+ Carrom and bowling. Discs roll on a flat table, bounce off walls, bumpers and each other, slow
5
+ down, drop into holes, roll off ledges and go through pipes. No dependencies.
6
+
7
+ The games stay turn-based. A move is a shot (`{ body, angle, power }`, all whole numbers). The
8
+ server's engine plays the shot to rest and stores the resting table; every browser runs the same
9
+ shot from the same table to animate it; practice games run it locally; a restarted room replays
10
+ its shots. All of that only works if **the same world and shot give bit-identical results on every
11
+ JavaScript engine**, and that is what this package is built around.
12
+
13
+ ## The determinism rules
14
+
15
+ | | |
16
+ | --- | --- |
17
+ | **May be used** | `+ - * /`, comparisons, `Math.sqrt`, `Math.abs`, `Math.round`. IEEE-754 and the language specify these exactly, so every engine gives the same bits. |
18
+ | **May not be used** | `Math.sin`, `cos`, `tan`, `atan2`, `pow`, `exp`, `log`, `hypot` and the rest, and the `**` operator. The language lets engines approximate them, and they do differ in the last digit. Also `Math.random`, `Date`, `performance`. |
19
+
20
+ - **Numbers** are ordinary doubles while a shot is moving and **whole numbers at rest**. Doubles
21
+ restricted to the exact operations are as reproducible as integers and need no overflow care or
22
+ hand-written fixed-point square roots; rounding at rest keeps stored tables small and exact and
23
+ starts every shot from the same integers.
24
+ - **Angles** are whole hundredths of a degree (0 to 35999). `direction(angle)` turns one into a
25
+ unit vector with a fixed polynomial (a Taylor series on the first eighth of the circle, Horner
26
+ form, coefficients as exact divisions) after folding the angle with integer arithmetic. The
27
+ compass points come out exact and the result is within a few last-place digits of the true sine
28
+ and cosine. An aiming screen is free to use `Math.atan2` on a pointer position: what it sends
29
+ is the rounded whole-number angle.
30
+ - **The step is fixed** and belongs to the world (`tickRate`), not to a clock or a frame rate.
31
+ - **Order is fixed**: bodies, walls, pockets, tunnels and regions are visited in the order the world
32
+ lists them, and when two contacts fall at the same instant the first one found is taken. Nothing
33
+ depends on object key order.
34
+ - Keep numeric literals short (17 significant digits at most); longer ones may be parsed
35
+ differently between engines.
36
+
37
+ The tests hold the line: recorded shots are compared exactly (`test/fixtures.json`), a spy fails
38
+ the suite if a forbidden function is called during a shot, and the source is scanned for them.
39
+ Six hundred seeded shots were also run under both V8 (Node) and JavaScriptCore (Bun) and hashed to
40
+ the same digest.
41
+
42
+ **`PHYSICS_VERSION`** must be bumped by any change that could move where something comes to rest
43
+ (the fixtures will fail when that happens). A room restored by replaying shots lands on the same
44
+ table only under the same physics, so a game that replays its log should either keep the resting
45
+ tables in its state or refuse to replay across versions.
46
+
47
+ | Version | What changed |
48
+ | --- | --- |
49
+ | 1 | Discs, walls, pockets, regions. |
50
+ | 2 | Tunnels, one-way walls (ledges) and bumpers that kick. Nothing a version 1 world could say plays differently (the version 1 fixtures are unchanged), but a world can now say things version 1 would not understand, so a recorded shot names the version that played it. |
51
+
52
+ ## The world
53
+
54
+ A table is plain JSON-serialisable data (`World` in `src/types.ts`); `validateWorld` lists what is
55
+ wrong with one in plain words. Lengths are whole numbers in a unit the game picks (the examples use
56
+ 0.1 mm), speeds are units/s, accelerations units/s².
57
+
58
+ ```ts
59
+ {
60
+ bounds: { x, y, w, h }, // a ball whose centre leaves this is out ("bounds")
61
+ tickRate: 120, // steps per second
62
+ maxTicks: 3600, // a shot is stopped after this many steps
63
+ friction: 5000, // how fast a ball slows on open ground
64
+ restSpeed: 100, // slower than this, on ground that can hold it, a ball stops
65
+ restitution: 0.9, // ball on ball (a body may carry its own; the lower one wins)
66
+ wallRestitution: 0.6, // ball on wall, for walls that don't say
67
+ maxShotSpeed: 40000, // what power 1000 means
68
+ bodies: [{ id, x, y, r, mass?, fixed?, restitution?, kick? }],
69
+ walls: [{ id, points: [[x, y], ...], closed?, restitution?, oneWay? }],
70
+ pockets: [{ id, x, y, r, maxSpeed? }],
71
+ regions: [{ id, shape: { points } | { x, y, r }, friction?, slope?: [ax, ay], out? }],
72
+ tunnels: [{ id, x, y, r, maxSpeed?, to: [x, y], angle, speed, ticks? }], // may be left out
73
+ }
74
+ ```
75
+
76
+ - **Bodies** are discs. Different masses and radii collide correctly (a Carrom striker, a bowling
77
+ ball); `fixed` ones never move (bumpers, pegs). A body with `kick` is a bumper that pushes back:
78
+ whatever touches it leaves at no less than that speed along the line between the two centres,
79
+ however softly it arrived, so nothing ever comes to rest against one. After a shot a body may carry `pocketed: <pocket
80
+ id>` or `out: <region id | "bounds">`; such a body takes no part until the game puts it back by
81
+ clearing the field and setting `x`, `y`.
82
+ - **Walls** are chains of straight pieces with no thickness, solid from both sides; `closed` makes
83
+ a polygon. Corners and ends behave as points a ball rolls round, so there are no seams to snag on.
84
+ A `oneWay` wall is a **ledge**: walking along its points in the order listed (with y down the
85
+ screen), a ball on the left rolls straight through and a ball on the right is stopped. A ball
86
+ that has dropped off cannot get back up, even if a slope pushes it against the riser. End a
87
+ ledge on ordinary walls: its own end points stop only what the ledge itself would stop.
88
+ - **Pockets** take a ball whose centre is over them. With `maxSpeed`, a faster ball skips across
89
+ (a `skip` event) and drops only if it is slow enough while still over the hole: a golf cup.
90
+ Without it the hole takes anything: a pool pocket.
91
+ - **Tunnels** are pipes. A ball whose centre comes over the mouth (a circle) goes in, at any speed
92
+ or, with `maxSpeed`, only at that speed or slower (a faster ball carries on over it, and goes in
93
+ after all if it is turned back and slows down while still over the mouth). It is off the table
94
+ for `ticks` steps, then comes out at `to` rolling at `speed` in the direction `angle` (hundredths
95
+ of a degree, like a shot), whatever it went in at. A mouth is found on the way like a wall is, so
96
+ it cannot be jumped. A shot is not over while a ball is inside; if `maxTicks` runs out first the
97
+ ball is set down at `to`. Keep `to` a ball's radius clear of walls and outside the mouth.
98
+ - **Regions** act on a ball whose centre is inside. The last listed one with `friction` sets the
99
+ friction (sand, rough); every `slope` adds a steady pull; `out` (water) removes the ball. Regions
100
+ and the bounds are checked at the end of each step, so make water wider than a ball travels in
101
+ one step at full power.
102
+
103
+ `POOL_TABLE`, `GOLF_HOLE` and `GARDEN_HOLE` (a ledge, a pipe and a bumper) are worked examples,
104
+ used by the tests.
105
+
106
+ ## Using it
107
+
108
+ ```ts
109
+ simulate(world: World, shot?: Shot): SimResult // play to rest in one call
110
+ frames(world: World, shot?: Shot): Generator<Frame, SimResult, void> // one step at a time
111
+ start(world: World, shot?: Shot): Run // the same by hand:
112
+ step(run: Run): Frame // one step
113
+ result(run: Run): SimResult // once run.done
114
+ validateWorld(world: unknown): string[]
115
+ validateShot(world: World, shot: unknown): string[]
116
+ direction(angle: number): [x: number, y: number]
117
+ ```
118
+
119
+ **A game engine** applies a move with `simulate`. It is pure: the world passed in is never
120
+ changed. `start` (and so `simulate`) throws a `PhysicsError` on a bad world or shot, so a shot from
121
+ a browser can be passed straight in.
122
+
123
+ ```ts
124
+ const { world, events, firstContact, capped } = simulate(state.table, { body: "cue", angle, power });
125
+ // Pool: no firstContact, or the wrong ball first, or the cue ball in events as "pocket": a foul.
126
+ // Golf: a stroke; an "out" event is a penalty and the ball goes back; "pocket" finishes the hole.
127
+ ```
128
+
129
+ Events are `hit` (two bodies), `wall`, `pocket`, `skip`, `out`, `tunnel` (a ball went in), `emerge`
130
+ (it came out) and `capped`, each with the `tick` it happened in and the ids of what was involved;
131
+ `hit` and `wall` carry the closing `speed` for choosing a sound. Things that stay touching report
132
+ once. They say what happened and when, never how to show it: a canvas and a 3D scene can both be
133
+ driven from them.
134
+
135
+ **A canvas** draws the same shot with `frames` (or `start`/`step` from an animation loop), taking
136
+ `world.tickRate / 60` steps per screen frame and playing each frame's `events` as they come. The
137
+ stepped run is the same code taking the same steps, so its last frame is exactly the table the
138
+ server stored. A frame's body that is inside a tunnel is not `live` and carries `in: <tunnel id>`.
139
+
140
+ **Bounded.** Each step finds the earliest moment anything touches anything and moves no further,
141
+ so nothing passes through a wall or another ball at any speed. A shot ends when everything has been
142
+ still for a few steps, or at `maxTicks`: then everything is stopped where it is, `capped` is true
143
+ and a `capped` event is the last one.
144
+
145
+ ## Not here yet
146
+
147
+ - **Spin.** `Shot.spin` and `Body.spin` are reserved and must be absent or zero; the validator
148
+ refuses anything else, so no recorded shot can change meaning when spin arrives. Collisions have
149
+ no friction along the line of contact (no throw, no english off a cushion).
150
+ - **Contacts at the same instant are settled one after another**, in the world's order. A dead
151
+ straight break into a tight rack is therefore not mirror-symmetric: the lower-numbered side
152
+ takes more of it. Billiards will want this looked at (a joint solve for simultaneous contacts,
153
+ and a version bump) before it ships.
154
+ - A ball skimming over a cup is not pulled towards it; it either drops or doesn't.
155
+ - **Height.** The table is flat. A ledge is a wall that works one way and a slope is a steady pull;
156
+ neither knows how high anything is, and a ball never leaves the ground. A game that wants to
157
+ draw heights keeps them beside the world, as mini golf's holes do.
158
+ - Rolling and sliding are one friction number; there is no separate sliding phase.
@@ -0,0 +1,26 @@
1
+ import type { World } from "./types.js";
2
+ /**
3
+ * A nine-foot pool table with the balls racked for a break. The cloth is the rectangle from
4
+ * (0, 0) to (25400, 12700); the six cushions stop short of the corners and the middle of the long
5
+ * sides, and a pocket sits in each gap. Each pocket's circle covers every path a ball's centre can
6
+ * take through its gap, so a ball that gets past the cushion ends always drops, and a ball rolling
7
+ * along the rail past a side pocket does not.
8
+ */
9
+ export declare const POOL_TABLE: World;
10
+ /**
11
+ * A mini golf hole, 1.2 m by 4 m, walled all round. The tee is near the bottom (large y) and the
12
+ * cup near the top. Between them the green climbs a hill that pulls the ball back towards the
13
+ * tee, so a timid putt rolls back down. A block stands to the left of the tee, there is a pond on
14
+ * the left beyond the hill and a patch of sand on the right. The cup takes a ball rolling at up
15
+ * to 1.5 m/s; anything faster skips over it.
16
+ */
17
+ export declare const GOLF_HOLE: World;
18
+ /**
19
+ * A second mini golf hole, for the three things the first one hasn't got. The green is 1.2 m by
20
+ * 3 m with the tee at the bottom. Across the middle runs a ledge: the top half is a terrace, and a
21
+ * ball can roll down off it but not back up. The only way up is the pipe, whose mouth is on the
22
+ * left of the lower half; it takes a ball at any speed up to 3 m/s and, a quarter of a second
23
+ * later, rolls it out onto the terrace, a putt away from the cup. A toadstool by the cup is a
24
+ * bumper: it knocks away anything that touches it.
25
+ */
26
+ export declare const GARDEN_HOLE: World;
@@ -0,0 +1,112 @@
1
+ /**
2
+ * A nine-foot pool table with the balls racked for a break. The cloth is the rectangle from
3
+ * (0, 0) to (25400, 12700); the six cushions stop short of the corners and the middle of the long
4
+ * sides, and a pocket sits in each gap. Each pocket's circle covers every path a ball's centre can
5
+ * take through its gap, so a ball that gets past the cushion ends always drops, and a ball rolling
6
+ * along the rail past a side pocket does not.
7
+ */
8
+ export const POOL_TABLE = {
9
+ bounds: { x: -1500, y: -1500, w: 28400, h: 15700 },
10
+ tickRate: 120,
11
+ maxTicks: 7200,
12
+ friction: 2000,
13
+ restSpeed: 50,
14
+ restitution: 0.95,
15
+ wallRestitution: 0.75,
16
+ maxShotSpeed: 80000,
17
+ bodies: [
18
+ { id: "cue", x: 6350, y: 6350, r: 286 },
19
+ // The rack: apex on the foot spot, rows 496 apart (286 × √3, rounded up so nothing overlaps).
20
+ { id: "1", x: 19050, y: 6350, r: 286 },
21
+ { id: "2", x: 19546, y: 6064, r: 286 },
22
+ { id: "3", x: 19546, y: 6636, r: 286 },
23
+ { id: "4", x: 20042, y: 5778, r: 286 },
24
+ { id: "8", x: 20042, y: 6350, r: 286 },
25
+ { id: "5", x: 20042, y: 6922, r: 286 },
26
+ { id: "6", x: 20538, y: 5492, r: 286 },
27
+ { id: "7", x: 20538, y: 6064, r: 286 },
28
+ { id: "9", x: 20538, y: 6636, r: 286 },
29
+ { id: "10", x: 20538, y: 7208, r: 286 },
30
+ { id: "11", x: 21034, y: 5206, r: 286 },
31
+ { id: "12", x: 21034, y: 5778, r: 286 },
32
+ { id: "13", x: 21034, y: 6350, r: 286 },
33
+ { id: "14", x: 21034, y: 6922, r: 286 },
34
+ { id: "15", x: 21034, y: 7494, r: 286 },
35
+ ],
36
+ walls: [
37
+ { id: "top-left", points: [[820, 0], [12050, 0]] },
38
+ { id: "top-right", points: [[13350, 0], [24580, 0]] },
39
+ { id: "right", points: [[25400, 820], [25400, 11880]] },
40
+ { id: "bottom-right", points: [[24580, 12700], [13350, 12700]] },
41
+ { id: "bottom-left", points: [[12050, 12700], [820, 12700]] },
42
+ { id: "left", points: [[0, 11880], [0, 820]] },
43
+ ],
44
+ pockets: [
45
+ { id: "top-left", x: 0, y: 0, r: 660 },
46
+ { id: "top", x: 12700, y: -300, r: 480 },
47
+ { id: "top-right", x: 25400, y: 0, r: 660 },
48
+ { id: "bottom-right", x: 25400, y: 12700, r: 660 },
49
+ { id: "bottom", x: 12700, y: 13000, r: 480 },
50
+ { id: "bottom-left", x: 0, y: 12700, r: 660 },
51
+ ],
52
+ regions: [],
53
+ };
54
+ /**
55
+ * A mini golf hole, 1.2 m by 4 m, walled all round. The tee is near the bottom (large y) and the
56
+ * cup near the top. Between them the green climbs a hill that pulls the ball back towards the
57
+ * tee, so a timid putt rolls back down. A block stands to the left of the tee, there is a pond on
58
+ * the left beyond the hill and a patch of sand on the right. The cup takes a ball rolling at up
59
+ * to 1.5 m/s; anything faster skips over it.
60
+ */
61
+ export const GOLF_HOLE = {
62
+ bounds: { x: -500, y: -500, w: 13000, h: 41000 },
63
+ tickRate: 120,
64
+ maxTicks: 3600,
65
+ friction: 5000,
66
+ restSpeed: 100,
67
+ restitution: 0.9,
68
+ wallRestitution: 0.6,
69
+ maxShotSpeed: 40000,
70
+ bodies: [{ id: "ball", x: 6000, y: 36000, r: 213 }],
71
+ walls: [
72
+ { id: "edge", closed: true, points: [[0, 0], [12000, 0], [12000, 40000], [0, 40000]] },
73
+ { id: "block", closed: true, restitution: 0.5, points: [[2500, 28000], [4500, 28000], [4500, 30000], [2500, 30000]] },
74
+ ],
75
+ pockets: [{ id: "cup", x: 6000, y: 5000, r: 540, maxSpeed: 15000 }],
76
+ regions: [
77
+ { id: "hill", shape: { points: [[0, 16000], [12000, 16000], [12000, 24000], [0, 24000]] }, slope: [0, 7000] },
78
+ { id: "sand", shape: { x: 9000, y: 10000, r: 1800 }, friction: 30000 },
79
+ { id: "pond", shape: { points: [[0, 11000], [3500, 11000], [3500, 14000], [0, 14000]] }, out: true },
80
+ ],
81
+ };
82
+ /**
83
+ * A second mini golf hole, for the three things the first one hasn't got. The green is 1.2 m by
84
+ * 3 m with the tee at the bottom. Across the middle runs a ledge: the top half is a terrace, and a
85
+ * ball can roll down off it but not back up. The only way up is the pipe, whose mouth is on the
86
+ * left of the lower half; it takes a ball at any speed up to 3 m/s and, a quarter of a second
87
+ * later, rolls it out onto the terrace, a putt away from the cup. A toadstool by the cup is a
88
+ * bumper: it knocks away anything that touches it.
89
+ */
90
+ export const GARDEN_HOLE = {
91
+ bounds: { x: -500, y: -500, w: 13000, h: 31000 },
92
+ tickRate: 120,
93
+ maxTicks: 3600,
94
+ friction: 5000,
95
+ restSpeed: 100,
96
+ restitution: 0.9,
97
+ wallRestitution: 0.6,
98
+ maxShotSpeed: 40000,
99
+ bodies: [
100
+ { id: "ball", x: 6000, y: 27000, r: 213 },
101
+ { id: "toadstool", x: 8200, y: 6000, r: 400, fixed: true, kick: 9000 },
102
+ ],
103
+ walls: [
104
+ { id: "edge", closed: true, points: [[0, 0], [12000, 0], [12000, 30000], [0, 30000]] },
105
+ // Listed left to right, so the terrace (smaller y) is on its left: down is free, up is shut.
106
+ { id: "ledge", oneWay: true, points: [[0, 15000], [12000, 15000]] },
107
+ ],
108
+ pockets: [{ id: "cup", x: 6000, y: 5000, r: 540, maxSpeed: 15000 }],
109
+ regions: [],
110
+ tunnels: [{ id: "pipe", x: 2000, y: 20000, r: 500, maxSpeed: 30000, to: [3000, 12000], angle: 31500, speed: 6000, ticks: 30 }],
111
+ };
112
+ //# sourceMappingURL=examples.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"examples.js","sourceRoot":"","sources":["../src/examples.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,5 @@
1
+ export * from "./types.js";
2
+ export * from "./trig.js";
3
+ export * from "./validate.js";
4
+ export * from "./sim.js";
5
+ export * from "./examples.js";
package/dist/index.js ADDED
@@ -0,0 +1,6 @@
1
+ export * from "./types.js";
2
+ export * from "./trig.js";
3
+ export * from "./validate.js";
4
+ export * from "./sim.js";
5
+ export * from "./examples.js";
6
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC"}
package/dist/sim.d.ts ADDED
@@ -0,0 +1,34 @@
1
+ import type { Frame, Shot, SimResult, World } from "./types.js";
2
+ /**
3
+ * Bump this whenever a change could alter where anything comes to rest. A room restored by
4
+ * replaying its shots only lands on the same table if the physics is the same physics.
5
+ */
6
+ export declare const PHYSICS_VERSION = 2;
7
+ /**
8
+ * A shot in progress. `start` makes one and `step` moves it on; it is the one thing in this
9
+ * package that changes in place, and it belongs to whoever started it. Treat everything but `tick`
10
+ * and `done` as private.
11
+ */
12
+ export interface Run {
13
+ readonly tick: number;
14
+ readonly done: boolean;
15
+ }
16
+ /**
17
+ * Sets a shot going. The world is checked first and never changed. Without a shot, the bodies
18
+ * move with whatever `vx`, `vy` the world gives them.
19
+ */
20
+ export declare function start(world: World, shot?: Shot): Run;
21
+ /** Moves a run on by one step and says where everything is and what happened in that step. */
22
+ export declare function step(run: Run): Frame;
23
+ /** The outcome of a run that has come to rest. */
24
+ export declare function result(run: Run): SimResult;
25
+ /**
26
+ * Plays a shot to rest in one call: what a game engine uses to apply a move. Pure: the same world
27
+ * and shot always give the same result, and the world passed in is not changed.
28
+ */
29
+ export declare function simulate(world: World, shot?: Shot): SimResult;
30
+ /**
31
+ * The same shot one step at a time: what a canvas uses to draw it. Yields a frame per step and
32
+ * returns the same result `simulate` gives, because it is the same code taking the same steps.
33
+ */
34
+ export declare function frames(world: World, shot?: Shot): Generator<Frame, SimResult, void>;