@typeonce/ritmo-devtools 0.14.0 → 0.16.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/CHANGELOG.md +283 -0
- package/README.md +303 -55
- package/dist/Desync.d.ts +23 -3
- package/dist/Desync.d.ts.map +1 -1
- package/dist/Desync.js +17 -15
- package/dist/Desync.js.map +1 -1
- package/dist/Determinism.d.ts +20 -6
- package/dist/Determinism.d.ts.map +1 -1
- package/dist/Determinism.js +11 -3
- package/dist/Determinism.js.map +1 -1
- package/dist/Format.d.ts +43 -8
- package/dist/Format.d.ts.map +1 -1
- package/dist/Format.js +66 -31
- package/dist/Format.js.map +1 -1
- package/dist/Fuzz.d.ts +275 -0
- package/dist/Fuzz.d.ts.map +1 -0
- package/dist/Fuzz.js +362 -0
- package/dist/Fuzz.js.map +1 -0
- package/dist/Invariant.d.ts +9 -2
- package/dist/Invariant.d.ts.map +1 -1
- package/dist/Invariant.js.map +1 -1
- package/dist/Lint.d.ts +11 -5
- package/dist/Lint.d.ts.map +1 -1
- package/dist/Lint.js.map +1 -1
- package/dist/PlaywrightEngine.d.ts +29 -0
- package/dist/PlaywrightEngine.d.ts.map +1 -0
- package/dist/PlaywrightEngine.js +196 -0
- package/dist/PlaywrightEngine.js.map +1 -0
- package/dist/Replay.d.ts +47 -23
- package/dist/Replay.d.ts.map +1 -1
- package/dist/Replay.js +26 -30
- package/dist/Replay.js.map +1 -1
- package/dist/ReplayNodeSink.d.ts.map +1 -1
- package/dist/ReplayNodeSink.js +4 -1
- package/dist/ReplayNodeSink.js.map +1 -1
- package/dist/ReplayVitePlugin.d.ts +1 -0
- package/dist/ReplayVitePlugin.d.ts.map +1 -1
- package/dist/ReplayVitePlugin.js.map +1 -1
- package/dist/Session.d.ts +224 -18
- package/dist/Session.d.ts.map +1 -1
- package/dist/Session.js +571 -58
- package/dist/Session.js.map +1 -1
- package/dist/Verify.d.ts +150 -0
- package/dist/Verify.d.ts.map +1 -0
- package/dist/Verify.js +154 -0
- package/dist/Verify.js.map +1 -0
- package/dist/cli.js +157 -16
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -2
- package/dist/index.js.map +1 -1
- package/dist/internal/dependencyScan.d.ts +44 -0
- package/dist/internal/dependencyScan.d.ts.map +1 -0
- package/dist/internal/dependencyScan.js +313 -0
- package/dist/internal/dependencyScan.js.map +1 -0
- package/dist/internal/fuzzNetwork.d.ts +56 -0
- package/dist/internal/fuzzNetwork.d.ts.map +1 -0
- package/dist/internal/fuzzNetwork.js +96 -0
- package/dist/internal/fuzzNetwork.js.map +1 -0
- package/dist/internal/simulationCoverage.d.ts.map +1 -1
- package/dist/internal/simulationCoverage.js +2 -1
- package/dist/internal/simulationCoverage.js.map +1 -1
- package/dist/internal/skillLink.d.ts +14 -0
- package/dist/internal/skillLink.d.ts.map +1 -0
- package/dist/internal/skillLink.js +46 -0
- package/dist/internal/skillLink.js.map +1 -0
- package/dist/internal/values.d.ts +9 -1
- package/dist/internal/values.d.ts.map +1 -1
- package/dist/internal/values.js +11 -1
- package/dist/internal/values.js.map +1 -1
- package/dist/internal/verifyRunner.d.ts +19 -0
- package/dist/internal/verifyRunner.d.ts.map +1 -0
- package/dist/internal/verifyRunner.js +47 -0
- package/dist/internal/verifyRunner.js.map +1 -0
- package/dist/internal/version.d.ts +1 -1
- package/dist/internal/version.js +1 -1
- package/package.json +28 -3
- package/src/Desync.ts +40 -17
- package/src/Determinism.ts +49 -11
- package/src/Format.ts +101 -34
- package/src/Fuzz.ts +551 -0
- package/src/Invariant.ts +9 -2
- package/src/Lint.ts +11 -5
- package/src/PlaywrightEngine.ts +232 -0
- package/src/Replay.ts +100 -47
- package/src/ReplayNodeSink.ts +4 -1
- package/src/ReplayVitePlugin.ts +1 -0
- package/src/Session.ts +816 -73
- package/src/Verify.ts +276 -0
- package/src/cli.ts +150 -15
- package/src/index.ts +3 -2
- package/src/internal/dependencyScan.ts +356 -0
- package/src/internal/fuzzNetwork.ts +130 -0
- package/src/internal/simulationCoverage.ts +2 -1
- package/src/internal/skillLink.ts +53 -0
- package/src/internal/values.ts +20 -1
- package/src/internal/verifyRunner.ts +46 -0
- package/src/internal/version.ts +1 -1
- package/dist/Monitor.d.ts +0 -101
- package/dist/Monitor.d.ts.map +0 -1
- package/dist/Monitor.js +0 -602
- package/dist/Monitor.js.map +0 -1
- package/dist/internal/monitor.d.ts +0 -126
- package/dist/internal/monitor.d.ts.map +0 -1
- package/dist/internal/monitor.js +0 -279
- package/dist/internal/monitor.js.map +0 -1
- package/src/Monitor.ts +0 -713
- package/src/internal/monitor.ts +0 -370
package/README.md
CHANGED
|
@@ -1,23 +1,8 @@
|
|
|
1
1
|
# `@typeonce/ritmo-devtools`
|
|
2
2
|
|
|
3
|
-
`Determinism.check` compares the same scripted simulation twice, including
|
|
4
|
-
transient components that snapshots omit:
|
|
5
|
-
|
|
6
|
-
```ts
|
|
7
|
-
const result = Determinism.check(({ hostClock }) => makeSimulation(hostClock), {
|
|
8
|
-
schedule: "update", frames: 1800, hostClock: HostClock.test()
|
|
9
|
-
})
|
|
10
|
-
if (!result.ok) throw new Error(JSON.stringify(result))
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
The factory returns `{ runtime, schedules }`, with a fresh debug runtime on
|
|
14
|
-
every call. A difference reports its frame, value path, and the first system
|
|
15
|
-
or schedule marker found by a diagnostic rerun. This checks the supplied
|
|
16
|
-
inputs on the current JavaScript engine.
|
|
17
|
-
|
|
18
3
|
Debug sessions for `ritmo` runtimes: run schedules headless, keep a trace
|
|
19
|
-
history, and ask what happened as text. Built for coding agents
|
|
20
|
-
|
|
4
|
+
history, and ask what happened as text. Built for coding agents: every
|
|
5
|
+
answer is text and data, and nothing draws in the page.
|
|
21
6
|
|
|
22
7
|
```sh
|
|
23
8
|
pnpm add -D @typeonce/ritmo-devtools
|
|
@@ -37,9 +22,11 @@ const runtime = Game.Runtime.make({
|
|
|
37
22
|
services,
|
|
38
23
|
debug: import.meta.env.DEV ? { hostClock: BrowserHostClock.make(window) } : undefined
|
|
39
24
|
}).value
|
|
40
|
-
if (runtime.debug !== undefined) Monitor.attach({ debug: runtime.debug }, { schedules, host: window })
|
|
41
25
|
```
|
|
42
26
|
|
|
27
|
+
In the browser, record a replay (see [Replays](#replays)) and debug it
|
|
28
|
+
headless with a `Session`.
|
|
29
|
+
|
|
43
30
|
## The debugging loop
|
|
44
31
|
|
|
45
32
|
1. **Get a headless runtime.** Keep the game's simulation (schema, systems,
|
|
@@ -61,15 +48,27 @@ if (runtime.debug !== undefined) Monitor.attach({ debug: runtime.debug }, { sche
|
|
|
61
48
|
3. **Reproduce.** Script the input with `Keyboard.scripted(bindings, timeline)`
|
|
62
49
|
(or replay a recorded browser session), add an invariant that encodes the
|
|
63
50
|
bug (`Invariant.fromInspector(Game.Inspector(...))`, returning a message
|
|
64
|
-
when violated), and `session.run("update", { frames: 600 })`.
|
|
51
|
+
when violated), and `session.run("update", { frames: 600 })`. Give the
|
|
52
|
+
session `labels` for the entities the bug is about, so every line says
|
|
53
|
+
`player e12` instead of `e12`. The run stops at the
|
|
65
54
|
first frame the invariant fails, a system fails, or a system throws.
|
|
66
55
|
4. **Explain.** `session.why(entity, Component)` and
|
|
67
56
|
`session.whyResource(Resource)` show the latest changes and which system
|
|
68
57
|
made them; `why` also names the systems whose declared `spawns` could
|
|
69
|
-
have spawned the entity.
|
|
58
|
+
have spawned the entity. When the writer only passed on a wrong input,
|
|
59
|
+
raise `depth` to follow what it declared it reads, one system further
|
|
60
|
+
back per step. `session.journal({ frames: [from, to], entity })`
|
|
70
61
|
shows everything that touched an entity around the failure.
|
|
71
62
|
`session.report()` lists warnings the trace collected and the current
|
|
72
63
|
entity counts per component. `run()` prints the warnings it raised.
|
|
64
|
+
When the wrong value appears within one frame, between two systems,
|
|
65
|
+
step that frame: run up to the frame before it, then
|
|
66
|
+
`const frame = session.step("update")`, `frame.until(ApplyDamage)` stops
|
|
67
|
+
before that system, `session.dump(...)` / `why` / `journal` show the
|
|
68
|
+
world and the partial frame, `frame.next()` runs one step (a system or
|
|
69
|
+
a marker), and `frame.finish()` runs the rest and reports the frame as
|
|
70
|
+
`run` does, invariants included. `frame.check()` asks the invariants
|
|
71
|
+
mid-frame, where one may legitimately fail until a later marker applies.
|
|
73
72
|
5. **Fix and keep it.** Rerun the same script, then turn it into a test next
|
|
74
73
|
to the game so the bug stays fixed.
|
|
75
74
|
|
|
@@ -100,12 +99,18 @@ const HealthNeverNegative = Invariant.fromInspector(Game.Inspector("health >= 0"
|
|
|
100
99
|
const health = queries.player.each().map((match) => match.data.health.get())
|
|
101
100
|
return health.some((value) => value < 0) ? `health ${health.join(", ")}` : undefined
|
|
102
101
|
}))
|
|
102
|
+
// Labels name entities in every line: `player e12` instead of `e12`. An
|
|
103
|
+
// inspector returning entity id -> label; any other return does not compile.
|
|
104
|
+
const Labels = Game.Inspector("labels", {
|
|
105
|
+
queries: { players: Game.Query({ selection: { player: Game.Query.read(Player) } }) }
|
|
106
|
+
}, ({ queries }) => new Map(queries.players.each().map((match) => [match.entity.id, "player"] as const)))
|
|
103
107
|
|
|
104
108
|
const session = Session.make(runtime, {
|
|
105
109
|
hostClock, // times run(); the runtime's clock
|
|
106
110
|
schedules: { setup, update }, // names used by run() and in traces
|
|
107
111
|
describe: { render }, // described and linted, never run (needs a renderer)
|
|
108
112
|
invariants: [HealthNeverNegative], // checked after every frame of every run
|
|
113
|
+
labels: Labels, // evaluated after every frame; despawned entities keep theirs
|
|
109
114
|
history: 600 // frames kept for journal/why
|
|
110
115
|
})
|
|
111
116
|
|
|
@@ -115,14 +120,23 @@ run.data.ok // true when completed or `until` retu
|
|
|
115
120
|
run.data.stop // { reason: "completed" | "until" | "failure" | "defect"
|
|
116
121
|
// | "invariant" | "missingRequirements" | "tickOrder", frame, ... }
|
|
117
122
|
|
|
123
|
+
const frame = session.step("update") // one frame, a step at a time; refuses run/tick until finished
|
|
124
|
+
frame.until(ApplyDamage) // runs the steps before the system value; Result: reached, or
|
|
125
|
+
// { reason: "failure" | "defect" | "frameEnded" | "notAhead" | ... }
|
|
126
|
+
session.dump({ entities: [12] }) // the world between two systems (journal and why show the partial frame)
|
|
127
|
+
frame.next() // exactly one step: a system or a marker
|
|
128
|
+
frame.check() // invariants now (may fail mid-frame); Result
|
|
129
|
+
frame.finish() // the rest of the frame, reported like run(name): labels, invariants
|
|
130
|
+
|
|
118
131
|
session.describe() // schema, schedules, access, lints
|
|
119
132
|
session.dump({ with: [Player], limit: 5 })// entities, resources, machines, pending commands
|
|
120
133
|
session.why(12, Position) // latest changes to e12 Position
|
|
134
|
+
session.why(12, Health, { depth: 3 }) // and, under each, the declared reads behind it, two levels back
|
|
121
135
|
session.whyResource(Score) // latest changes to a resource
|
|
122
136
|
session.journal({ frames: [180, 185], entity: 12, kinds: ["write", "effect"] })
|
|
123
137
|
session.journal({ system: "Game/Move", last: 10, verbose: true })
|
|
124
138
|
session.system("Game/Move") // declared access, stats, recent lines
|
|
125
|
-
session.streams() // event/transition/relation-failure retention
|
|
139
|
+
session.streams() // event/transition/relation-failure/dropped-relation retention
|
|
126
140
|
session.report() // per-system timing and warnings
|
|
127
141
|
```
|
|
128
142
|
|
|
@@ -141,7 +155,10 @@ f186 update - transition Game/Flow Playing -> Paused applied
|
|
|
141
155
|
- `f185`: frame number, counting every `tick`/`tryTick` call from 1, setup
|
|
142
156
|
included. Keyboard timeline frames count input snapshots from 0 instead, so
|
|
143
157
|
with one setup frame, timeline frame `n` is read in session frame `n + 2`.
|
|
144
|
-
`e12`: entity 12
|
|
158
|
+
`e12`: entity 12; `player e12` when the session's `labels` name it (the
|
|
159
|
+
label it had at the end of that line's frame). `&e12`: a stored handle to
|
|
160
|
+
entity 12. Write entities as `e${id}` in invariant messages and the run
|
|
161
|
+
summary labels them too.
|
|
145
162
|
- The schedule path shows nesting, for example `update > onEnter(Game/Flow=Paused)`.
|
|
146
163
|
- `write`: a component a system's write query changed to a different value
|
|
147
164
|
(writing back an equal value is not recorded). `resource`,
|
|
@@ -149,7 +166,9 @@ f186 update - transition Game/Flow Playing -> Paused applied
|
|
|
149
166
|
values. Failed systems show `(rolled back)`.
|
|
150
167
|
- `queued ...` then `applyDeferred: ...`: a command queued by a system, then
|
|
151
168
|
its structural effect when a marker applied it. The system named on the
|
|
152
|
-
effect line is the one that queued it.
|
|
169
|
+
effect line is the one that queued it. A despawn also lists each edge it
|
|
170
|
+
dropped: `Game/Targeting from e7 to e12 dropped: e12 despawned` (what
|
|
171
|
+
`Game.System.readDroppedRelations` delivers).
|
|
153
172
|
- `skipped: <condition> is false`: a run condition held the system back;
|
|
154
173
|
`discarded N Event` means messages published meanwhile are lost to it.
|
|
155
174
|
- `missed ...`: the system could not see entries dropped before it ran.
|
|
@@ -158,37 +177,32 @@ f186 update - transition Game/Flow Playing -> Paused applied
|
|
|
158
177
|
- Large objects print only their changed paths:
|
|
159
178
|
`~ up.held: false -> true, left.held: false -> true`.
|
|
160
179
|
|
|
161
|
-
|
|
180
|
+
`why` and `whyResource` with `depth` above 1 indent, under each change,
|
|
181
|
+
what the writing system declared it reads, with the latest traced fact that
|
|
182
|
+
could have produced it; each `depth` step goes one system further back:
|
|
162
183
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
pick: (event) => entityUnderPointer(event), // optional: "Pick on screen"
|
|
173
|
-
locate: (entity) => clientPositionOf(entity) // optional: ring on the selected entity
|
|
174
|
-
})
|
|
184
|
+
```
|
|
185
|
+
e12 Game/Health is now 40; last 1 changes (oldest first):
|
|
186
|
+
could have spawned it: Game/SpawnEnemy
|
|
187
|
+
indented: what each writing system declared it reads, and the latest fact that could have produced it (declared: possible causes, not observed reads)
|
|
188
|
+
f181 update Game/ApplyDamage write e12 Game/Health 70 -> 40
|
|
189
|
+
read Game/Damage [{amount:30}] (declared), emitted by Game/Hitscan at f181
|
|
190
|
+
read Game/Position of 14 matching entities now (declared; the trace does not say which it read)
|
|
191
|
+
read resource Game/Aim {target:12} (declared), written by Game/AimAtNewest at f180
|
|
192
|
+
read e12 Game/Armor 5 (declared), spawned by Game/SpawnEnemy at f3
|
|
175
193
|
```
|
|
176
194
|
|
|
177
|
-
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
Timings include tracing overhead, so compare systems with each other rather
|
|
190
|
-
than with a run where the monitor is closed. `Monitor.Collector` is the same
|
|
191
|
-
data without DOM, for a custom UI.
|
|
195
|
+
- The trace records writes, not reads, so every indented line is a
|
|
196
|
+
possible cause, marked `(declared)`, not a read that was observed.
|
|
197
|
+
- An event read lists what was published to it since the system's previous
|
|
198
|
+
run, and by whom (`runtime.send` for the host). A component in the query
|
|
199
|
+
that wrote the value is read on the same entity: its latest change before
|
|
200
|
+
the run. A resource or machine: its latest change or transition.
|
|
201
|
+
- A query over other entities says only how many match now: the trace does
|
|
202
|
+
not say which one the system used. Use `journal` to narrow it down.
|
|
203
|
+
- A system already in the chain prints `(cycle: not followed)`; `limit`
|
|
204
|
+
caps the reads under each line (`…+N more declared reads`). In `.data`,
|
|
205
|
+
these lines have `kind: "read"` and `depth` 1 or more.
|
|
192
206
|
|
|
193
207
|
## Report warnings
|
|
194
208
|
|
|
@@ -202,6 +216,7 @@ data without DOM, for a custom UI.
|
|
|
202
216
|
| `system-failed` | A system returned an expected failure or threw. |
|
|
203
217
|
| `ignored-failure` | A `tick` / `tryTick` result failed and nobody read its `ok` before the next tick (or the session's `report()`): the failure went unnoticed and later systems did not run. `run` stops on it with `reason: "ignored-failure"`. |
|
|
204
218
|
| `non-finite-value` | A system wrote NaN or an infinity into a component, resource, event, or spawned entity. The message names the entity and path; `why()` shows the history. |
|
|
219
|
+
| `out-of-range` | A system wrote a number outside the `range` its descriptor declares for that field (`meta: { hp: { range: [0, 100] } }`), in a write, a resource, or a spawned or inserted component. One count per write; the message names the entity, field, value, range, system, and first frame. The range is advisory: the schema decides what is valid. |
|
|
205
220
|
| `population-growing` | A component's count rose through every quarter of a run of 60+ frames: its lowest count in each quarter was higher than in the quarter before. Bursts that are cleaned up do not trigger it; entities that are never despawned do. `run()` returns the counts in `growing`. |
|
|
206
221
|
|
|
207
222
|
The report also starts with the static lints from `describe()`.
|
|
@@ -231,6 +246,11 @@ export const lintTarget = async () => {
|
|
|
231
246
|
}
|
|
232
247
|
```
|
|
233
248
|
|
|
249
|
+
A debug script that needs the same runtime and host schedules (a
|
|
250
|
+
`scripts/debug.ts` that builds a `Session`) imports `lintTarget` and calls
|
|
251
|
+
it, instead of repeating the wiring: `const { runtime, schedules } = await
|
|
252
|
+
lintTarget()`.
|
|
253
|
+
|
|
234
254
|
When nothing needs describing, the simulation's own entry module can export
|
|
235
255
|
`lintTarget` instead.
|
|
236
256
|
|
|
@@ -248,11 +268,33 @@ skipped and does not fail. The check needs Node 22.15 or later.
|
|
|
248
268
|
| Code | Meaning |
|
|
249
269
|
|---|---|
|
|
250
270
|
| `uncovered-simulation-module` | The simulation loads this file, but no simulation override in `.oxlintrc.json` covers it, so oxlint never checks it for platform, time, randomness, or math calls. Add it to the override's `files`, or stop importing values from it. Exits with 1. |
|
|
271
|
+
| `skill-not-linked` | Neither `.agents/skills/ritmo` nor `.claude/skills/ritmo` links the skill in `node_modules/@typeonce/ritmo/skills/ritmo`, so the game's agent does not read the playbooks for this Ritmo version. Link it (`SETUP.md` step 2). A note: the exit code is unchanged. |
|
|
272
|
+
| `skill-copied` | The folder holds a copy of the skill (or links somewhere else), which goes stale on the next upgrade. Replace it with the link. A note: the exit code is unchanged. |
|
|
251
273
|
|
|
252
274
|
The trace shows what systems wrote, not what they read. When a system writes
|
|
253
275
|
a wrong value from correct inputs, the journal narrows the bug to that
|
|
254
276
|
system (it runs, in order, and writes this value) and the rest is its code.
|
|
255
277
|
|
|
278
|
+
## Determinism
|
|
279
|
+
|
|
280
|
+
`Determinism.check` compares the same scripted simulation twice, including
|
|
281
|
+
transient components that snapshots omit:
|
|
282
|
+
|
|
283
|
+
```ts
|
|
284
|
+
const result = Determinism.check(({ hostClock }) => makeSimulation(hostClock), {
|
|
285
|
+
schedule: "update", frames: 1800, hostClock: HostClock.test()
|
|
286
|
+
})
|
|
287
|
+
if (!result.ok) throw new Error(JSON.stringify(result))
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
The factory returns `{ runtime, schedules }`, with a fresh debug runtime on
|
|
291
|
+
every call. A difference reports its frame, value path, and the first system
|
|
292
|
+
or schedule marker found by a diagnostic rerun; inside an entity, it names
|
|
293
|
+
the entity (`entity`) and, given `labels` (the session's labels inspector),
|
|
294
|
+
its `label`. This checks the supplied inputs on the current JavaScript
|
|
295
|
+
engine; [Verify across engines](#verify-across-engines) plays a replay in
|
|
296
|
+
Node and real browsers.
|
|
297
|
+
|
|
256
298
|
## Desyncs
|
|
257
299
|
|
|
258
300
|
Peers of a networked game (`@typeonce/ritmo-netcode`) compare checksums of
|
|
@@ -262,15 +304,20 @@ carries its own. `Desync.compare` lists what differs, entities by id and
|
|
|
262
304
|
values by path, in a stable order:
|
|
263
305
|
|
|
264
306
|
```ts
|
|
265
|
-
console.log(Desync.compare(mine.snapshot, theirs.snapshot))
|
|
307
|
+
console.log(Desync.compare(mine.snapshot, theirs.snapshot, { labels: runtime.inspect(Labels) }))
|
|
266
308
|
// 2 differences (mine -> theirs):
|
|
267
|
-
//
|
|
309
|
+
// player e12 Game/Position.x: 40 -> 41
|
|
268
310
|
// resource Game/Rng: 1730 -> 2210
|
|
269
311
|
```
|
|
270
312
|
|
|
271
313
|
The first difference is where to look: rerun the match headless and ask a
|
|
272
314
|
`Session` `why` that value changed.
|
|
273
315
|
|
|
316
|
+
A `Netcode.syncTest` made with `keepSnapshots: true` fails with
|
|
317
|
+
`RewindDiffers` carrying the world before and after a rewind:
|
|
318
|
+
`Desync.compare(error.snapshots.expected, error.snapshots.actual)` names
|
|
319
|
+
what the rewind did not put back.
|
|
320
|
+
|
|
274
321
|
## Replays
|
|
275
322
|
|
|
276
323
|
A replay is the last seconds of a play session as a file: a debug artifact
|
|
@@ -285,7 +332,7 @@ const recorder = Replay.recorder(runtime, {
|
|
|
285
332
|
hostClock: BrowserHostClock.make(window), // for savedAt
|
|
286
333
|
saveOn: { failure: true, invariants: [DeadAreGone] } // saves by itself
|
|
287
334
|
})
|
|
288
|
-
|
|
335
|
+
recorder.save("player stuck") // on demand, e.g. from a dev-only key
|
|
289
336
|
|
|
290
337
|
// vite.config.ts: writes posted replays to .replays/<time>.json and logs them.
|
|
291
338
|
plugins: [ReplayVitePlugin.plugin()]
|
|
@@ -312,13 +359,214 @@ const file = Replay.parse(JSON.parse(readFileSync(".replays/....json", "utf8")))
|
|
|
312
359
|
const replay = file.ok ? Replay.session(make, file.value) : file
|
|
313
360
|
replay.value.play() // run the ticks; reports checkpoint divergence
|
|
314
361
|
replay.value.session.why(12, Position) // a normal Session over the replayed frames
|
|
315
|
-
Replay.
|
|
362
|
+
Replay.session(make, file.value, { labels: Labels }) // names entities, as in Session.make
|
|
363
|
+
await Verify.acrossEngines(make, file.value) // replays twice here and against the recording
|
|
316
364
|
Replay.extract(make, file.value, { from: 1400, to: 1412 }) // a small replay for a test
|
|
317
365
|
```
|
|
318
366
|
|
|
367
|
+
`Replay.session(make, file, { invariants })` checks invariants after every
|
|
368
|
+
replayed tick, so `play()` stops where one breaks, as a `Session` run does.
|
|
369
|
+
|
|
370
|
+
`playback.source(descriptor)` takes any `snapshot()`-only source service:
|
|
371
|
+
`Schedule.Source<T>`, `Netcode.Source<T>`, or browser input declared as
|
|
372
|
+
`InputCapture.SourceOf<...>` (a device, a `Controls` merge, or a pool; see
|
|
373
|
+
[the browser README](https://github.com/typeonce-dev/ritmo/blob/main/packages/browser/README.md)).
|
|
374
|
+
A service declared as the whole device, with `rebind` and `dispose`, is a
|
|
375
|
+
compile error naming that fix: a replay can only stand in for its
|
|
376
|
+
`snapshot()`, so the page keeps the device to rebind it.
|
|
377
|
+
|
|
319
378
|
A replay recorded with another schema fails with "replay recorded with an
|
|
320
379
|
older schema".
|
|
321
380
|
|
|
381
|
+
## Verify across engines
|
|
382
|
+
|
|
383
|
+
`Verify.acrossEngines` is the one replay check. With no engines it plays
|
|
384
|
+
the replay twice in this process and against the recording, the check a
|
|
385
|
+
test runs; `ritmo-devtools verify` plays the same replay in Node and in real
|
|
386
|
+
browser engines and reports the first tick whose world differs, with every
|
|
387
|
+
value that differs there. Run it before
|
|
388
|
+
trusting a lockstep or rollback match across browsers, and in CI on a
|
|
389
|
+
committed replay of the game:
|
|
390
|
+
|
|
391
|
+
```sh
|
|
392
|
+
ritmo-devtools verify src/replay-target.ts replays/boss-fight.json --engines node,chromium,webkit,firefox
|
|
393
|
+
# NOT verified: 1800 ticks of simulate
|
|
394
|
+
# node: agrees with a second node run and the recording over 1800 ticks
|
|
395
|
+
# chromium: agrees with node over 1800 ticks
|
|
396
|
+
# tick 1412: webkit differs from node in e41 Game/Position.x (40.000000000000014 -> 40)
|
|
397
|
+
# 1 difference (node -> webkit):
|
|
398
|
+
# e41 Game/Position.x: 40.000000000000014 -> 40
|
|
399
|
+
# firefox: not installed (the firefox browser is not downloaded): npx playwright install firefox
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
`<entry>` exports `replayTarget`, the `make(playback)` factory
|
|
403
|
+
`Replay.session` takes (above). It must load in a browser too: keep Node
|
|
404
|
+
built-ins out of it.
|
|
405
|
+
|
|
406
|
+
```ts
|
|
407
|
+
// src/replay-target.ts
|
|
408
|
+
export const replayTarget = (playback: Replay.Playback) => {
|
|
409
|
+
const hostClock = HostClock.test()
|
|
410
|
+
return { runtime: makeRuntime({ input: playback.source(Input), debug: { hostClock } }), schedules: { simulate }, hostClock }
|
|
411
|
+
}
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
- Node always runs, as the reference: twice (a difference is
|
|
415
|
+
nondeterminism here) and against the recording's checkpoints (a
|
|
416
|
+
difference is a code change since recording, or the recording engine).
|
|
417
|
+
`--engines node`, the default, needs no other dependency.
|
|
418
|
+
- Browser engines run headless through Playwright, with the entry served by
|
|
419
|
+
a bare Vite dev server (the game's `vite.config` is not read). Install
|
|
420
|
+
them where the check runs: `npm install --save-dev playwright vite` and
|
|
421
|
+
`npx playwright install chromium webkit firefox`. An engine that is not
|
|
422
|
+
installed is printed with its install command and fails the check.
|
|
423
|
+
- Exit codes: 0 every engine agrees, 1 one differs or did not run, 2 usage
|
|
424
|
+
error (arguments, a file that is not a replay, an entry without
|
|
425
|
+
`replayTarget`). `--json` prints the result as JSON.
|
|
426
|
+
|
|
427
|
+
The same check from code, for a game's own test (leave out `engines` to
|
|
428
|
+
check this process alone):
|
|
429
|
+
|
|
430
|
+
```ts
|
|
431
|
+
import { Verify } from "@typeonce/ritmo-devtools"
|
|
432
|
+
import * as PlaywrightEngine from "@typeonce/ritmo-devtools/PlaywrightEngine"
|
|
433
|
+
|
|
434
|
+
const browsers = PlaywrightEngine.make({ entry: "src/replay-target.ts", browsers: ["chromium", "webkit", "firefox"] })
|
|
435
|
+
const verified = await Verify.acrossEngines(replayTarget, file, { engines: browsers.engines })
|
|
436
|
+
await browsers.close()
|
|
437
|
+
if (!verified.ok && verified.error._tag === "NotVerified") {
|
|
438
|
+
for (const outcome of verified.error.outcomes) if (outcome._tag === "Diverged") console.log(outcome.tick, outcome.differences)
|
|
439
|
+
}
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
The error side is `ReplayInvalid` (the replay does not open here) or
|
|
443
|
+
`NotVerified`, one outcome per engine: `Agreed`, `Diverged` (`tick`,
|
|
444
|
+
`against`, `differences`), `EngineMissing` (`install`), or `EngineFailed`.
|
|
445
|
+
For another host (a webview, a console), run `Verify.trace` and
|
|
446
|
+
`Verify.snapshotAt` there and wrap them as a `Verify.Engine`.
|
|
447
|
+
|
|
448
|
+
## Scan dependencies
|
|
449
|
+
|
|
450
|
+
oxlint skips `node_modules`, so a dependency the simulation calls can still
|
|
451
|
+
use `Math.sin`, `Date.now`, or `Math.random`. `ritmo-devtools scan <entry>`
|
|
452
|
+
resolves every file the simulation entry imports, `node_modules` included,
|
|
453
|
+
and runs `ritmo/use-ops-for-math`, `ritmo/use-clock-for-time`, and
|
|
454
|
+
`ritmo/use-random-for-randomness` over them, grouped by package:
|
|
455
|
+
|
|
456
|
+
```sh
|
|
457
|
+
ritmo-devtools scan src/simulation/index.ts
|
|
458
|
+
# fake-physics (2 findings)
|
|
459
|
+
# node_modules/fake-physics/index.js:4:17 ritmo/use-ops-for-math Math.sin
|
|
460
|
+
# node_modules/fake-physics/index.js:6:32 ritmo/use-random-for-randomness Math.random
|
|
461
|
+
#
|
|
462
|
+
# scanned 4 files in 2 packages imported by src/simulation/index.ts: 2 findings in 1 package
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
- A finding is a hint, not a verdict: code the simulation never calls is
|
|
466
|
+
fine. For a dependency it calls, vendor it into the game's source and run
|
|
467
|
+
`oxlint --fix`, or replace it. A clean scan does not prove the run is
|
|
468
|
+
deterministic: confirm with `ritmo-devtools verify` or `Netcode.syncTest`.
|
|
469
|
+
- It uses the game's `oxlint` and `@typeonce/oxlint-plugin-ritmo`, and
|
|
470
|
+
`rolldown` to resolve imports the way a build does (Vite 8 includes it;
|
|
471
|
+
otherwise `npm install --save-dev rolldown`). A missing tool is printed
|
|
472
|
+
with its install command.
|
|
473
|
+
- Exit codes: 0 whenever the scan ran, with or without findings, 2 usage
|
|
474
|
+
error (arguments, an unreadable entry, an import that does not resolve, a
|
|
475
|
+
missing tool). `--json` prints
|
|
476
|
+
`{ entry, files, packages: [{ name, files, findings: [{ file, line, column, rule, snippet }] }] }`.
|
|
477
|
+
|
|
478
|
+
## Fuzzing
|
|
479
|
+
|
|
480
|
+
`Fuzz.run` finds a bug before anyone plays into it: seeded random input,
|
|
481
|
+
run headless against the game's invariants, until an invariant breaks, a
|
|
482
|
+
system fails, or something throws. It then shrinks the failing input to the
|
|
483
|
+
few frames that still fail the same way, and returns them as a replay file.
|
|
484
|
+
|
|
485
|
+
```ts
|
|
486
|
+
import { Fuzz, Replay } from "@typeonce/ritmo-devtools"
|
|
487
|
+
import * as ReplayNodeSink from "@typeonce/ritmo-devtools/ReplayNodeSink"
|
|
488
|
+
|
|
489
|
+
// One fuzzed snapshot() source: a value of its type for each frame, and the idle value.
|
|
490
|
+
const Pads = Fuzz.input(PadInput, {
|
|
491
|
+
generate: (random, frame) => ({ key: random.integer(0, 5), aim: random.range(-1, 1) }),
|
|
492
|
+
neutral: { key: 0, aim: 0 }
|
|
493
|
+
})
|
|
494
|
+
// `make` is the replay factory (above): it builds the game on playback.source(PadInput).
|
|
495
|
+
const found = Fuzz.run(make, {
|
|
496
|
+
schedule: "update", setup: "setup", // setup is ticked once first, every input neutral
|
|
497
|
+
inputs: [Pads], invariants: [HealthNeverNegative],
|
|
498
|
+
frames: 3000, runs: 10, seed: 7 // run i draws from seed 7 + i
|
|
499
|
+
})
|
|
500
|
+
if (!found.ok && found.error._tag === "Found") {
|
|
501
|
+
ReplayNodeSink.make({ directory: ".replays" }).save(found.error.replay)
|
|
502
|
+
console.log(found.error.violation) // InvariantViolated | SystemFailed | Defect
|
|
503
|
+
console.log(found.error.shrink) // { attempts, steps, fromFrames: 1412, toFrames: 4 }
|
|
504
|
+
}
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
- A browser game fuzzes through the same descriptor its page and replays
|
|
508
|
+
read: `Fuzz.input(ControlsInput, { generate: (random) =>
|
|
509
|
+
Actions.random(random, devices), neutral: Actions.idle(devices) })` draws
|
|
510
|
+
merged input a real merge could report (button states, vectors of length
|
|
511
|
+
at most 1); `Players.random(random, frame, { devices, seats })` does it
|
|
512
|
+
for a local multiplayer pool.
|
|
513
|
+
- `random` is a seeded `Random` from `@typeonce/ritmo`; the same seed
|
|
514
|
+
draws the same input, so a found bug's `seed` with `runs: 1` finds it
|
|
515
|
+
again. Every source `make` asks `playback.source` for must be a fuzzed
|
|
516
|
+
input; give plain-data services (rules, config) directly.
|
|
517
|
+
- Shrinking drops ranges of frames, then moves each remaining value to
|
|
518
|
+
`neutral` (whole, then one field at a time), re-running the simulation for
|
|
519
|
+
every candidate. `shrinkAttempts` (500) bounds it.
|
|
520
|
+
- The error side is `Found` (with the shrunk `replay`, `seed`, `frame`, and
|
|
521
|
+
`reproduces`: whether `Replay.session` replays it to the same violation),
|
|
522
|
+
`Flaky` (the same input did not fail again: run `Determinism.check`),
|
|
523
|
+
`InvalidOptions`, or `Unreplayable` (the world after setup cannot be saved).
|
|
524
|
+
|
|
525
|
+
The shrunk replay is the regression test:
|
|
526
|
+
|
|
527
|
+
```ts
|
|
528
|
+
const file = Replay.parse(JSON.parse(readFileSync(".replays/....json", "utf8")))
|
|
529
|
+
const opened = file.ok ? Replay.session(make, file.value, { invariants: [HealthNeverNegative] }) : file
|
|
530
|
+
expect(opened.ok && opened.value.play().data.run.stop.reason).toBe("completed") // fails until the fix
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
### Over a network
|
|
534
|
+
|
|
535
|
+
The same `Fuzz.run` fuzzes a rollback game over a faulty network. Give it one
|
|
536
|
+
`Fuzz.seats` input (every seat's input per frame) and `network`: each seat
|
|
537
|
+
plays on its own peer, a fresh `make(playback)`, joined by a seeded
|
|
538
|
+
`MemoryNetworkLink` and driven by a `Netcode.rollback` session from
|
|
539
|
+
[`@typeonce/ritmo-netcode`](https://github.com/typeonce-dev/ritmo/blob/main/packages/netcode/README.md).
|
|
540
|
+
|
|
541
|
+
```ts
|
|
542
|
+
// The seats service the simulation captures; make provides it with playback.source(Seats).
|
|
543
|
+
const Players = Fuzz.seats(Seats, {
|
|
544
|
+
codec: PlayerInput, count: 2, idle: { dx: 0, fire: false }, // as given to Netcode.seats
|
|
545
|
+
generate: (random, frame, seat) => ({ dx: random.integer(-1, 2), fire: random.next() < 0.2 })
|
|
546
|
+
})
|
|
547
|
+
const found = Fuzz.run(make, {
|
|
548
|
+
schedule: "simulate", setup: "setup", inputs: [Players], invariants: [HealthNeverNegative],
|
|
549
|
+
frames: 600, seed: 7,
|
|
550
|
+
network: { seed: 3, latencyMS: 60, jitterMS: 40, loss: 0.1, step } // faults repeat for the same seed
|
|
551
|
+
})
|
|
552
|
+
if (!found.ok && found.error._tag === "Found" && found.error.violation._tag === "SessionFailed") {
|
|
553
|
+
console.log(found.error.violation.seat, found.error.violation.error) // Desynced, with this peer's save of the tick
|
|
554
|
+
}
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
- A session failure (`Desynced`, `TickFailed`, `CheckpointLost`, or the
|
|
558
|
+
session ending) is a `SessionFailed` violation; invariants are checked on
|
|
559
|
+
every peer after each frame. `settle` idle frames (120) follow the fuzzed
|
|
560
|
+
ones so late input and checksums arrive; checksums are compared every 10
|
|
561
|
+
ticks unless `checksumEvery` says otherwise.
|
|
562
|
+
- Shrinking keeps the network seed and shrinks the input timeline, one seat
|
|
563
|
+
at a time. The `replay` plays the shrunk timeline on one runtime (step it
|
|
564
|
+
to see each tick); `reproduces` is `false` for a desync, which needs two
|
|
565
|
+
peers: find it again with the same `seed`, `runs: 1`, and `network`.
|
|
566
|
+
- A `simulate` that cannot be rewound, or a runtime that cannot save, does
|
|
567
|
+
not compile, as for `Netcode.rollback`. Run `Netcode.syncTest` first: it
|
|
568
|
+
finds state a rewind cannot put back on one peer, faster.
|
|
569
|
+
|
|
322
570
|
## Recording a browser session
|
|
323
571
|
|
|
324
572
|
```ts
|
package/dist/Desync.d.ts
CHANGED
|
@@ -5,31 +5,51 @@
|
|
|
5
5
|
* A `Netcode` session made with `keepSnapshots: true` fails with `Desynced`
|
|
6
6
|
* carrying this peer's save of the tick whose checksums differ; the other
|
|
7
7
|
* peer's session carries its own. `compare(mine, theirs)` lists every
|
|
8
|
-
* difference, entities by id and values by path, so an agent can see which
|
|
8
|
+
* difference, entities by id (and label, given `labels`) and values by path, so an agent can see which
|
|
9
9
|
* component or resource went apart first, then find the system that wrote
|
|
10
10
|
* it with a `Session`'s `why` on a headless rerun.
|
|
11
|
+
* The same goes for the two saves a `Netcode.syncTest`'s `RewindDiffers`
|
|
12
|
+
* carries (`keepSnapshots: true`): the first run's and the one after a rewind.
|
|
11
13
|
*
|
|
12
14
|
* @module Desync
|
|
13
15
|
* @docGroup devtools
|
|
14
16
|
*
|
|
15
17
|
* @example
|
|
16
18
|
* ```ts
|
|
19
|
+
* declare const sessions: readonly [Netcode.Session<{ dx: number }, unknown>, Netcode.Session<{ dx: number }, unknown>]
|
|
20
|
+
* declare const input: { dx: number }
|
|
21
|
+
* const Labels = Game.Inspector("labels", {
|
|
22
|
+
* queries: { players: Game.Query({ selection: { position: Game.Query.read(Position) }, with: [Player] }) }
|
|
23
|
+
* }, ({ queries }) => new Map(queries.players.each().map((match) => [match.entity.id, "player"] as const)))
|
|
24
|
+
* // ---cut---
|
|
17
25
|
* const left = sessions[0].advance(input)
|
|
18
26
|
* const right = sessions[1].advance(input)
|
|
19
27
|
* if (!left.ok && left.error._tag === "Desynced" && !right.ok && right.error._tag === "Desynced") {
|
|
20
|
-
* console.log(Desync.compare(left.error.snapshot!, right.error.snapshot
|
|
28
|
+
* console.log(Desync.compare(left.error.snapshot!, right.error.snapshot!, { labels: runtime.inspect(Labels) }))
|
|
21
29
|
* }
|
|
22
30
|
* ```
|
|
23
31
|
*/
|
|
24
32
|
import type * as Snapshot from "@typeonce/ritmo/Snapshot";
|
|
33
|
+
import * as Format from "./Format.ts";
|
|
25
34
|
import * as Rendered from "./Rendered.ts";
|
|
26
35
|
/** One value that differs: where, and each side's (`undefined`: absent on that side). */
|
|
27
36
|
export interface Difference {
|
|
28
37
|
/** `nextEntity`, `entity 12`, `entity 12 Game/Position.x`, `resource Game/Score`, `machine Game/Round`, `relation Game/ChildOf`, or `scope Game/Wave`. */
|
|
29
38
|
readonly path: string;
|
|
39
|
+
/** The entity the difference is in, when it is in one. */
|
|
40
|
+
readonly entity: number | undefined;
|
|
30
41
|
readonly mine: unknown;
|
|
31
42
|
readonly theirs: unknown;
|
|
32
43
|
}
|
|
44
|
+
/** How `compare` prints. */
|
|
45
|
+
export interface CompareOptions {
|
|
46
|
+
/**
|
|
47
|
+
* Names entities in the text (`player e12 Game/Position.x`): the map the
|
|
48
|
+
* session's `labels` inspector returns, read with `runtime.inspect(Labels)`
|
|
49
|
+
* on either peer. Without it entities print as `e12`.
|
|
50
|
+
*/
|
|
51
|
+
readonly labels?: Format.Labels;
|
|
52
|
+
}
|
|
33
53
|
/** Every difference between two saves, in a stable order: the next id, entities by id, then resources, machines, relations, and scopes by name. */
|
|
34
|
-
export declare const compare: (mine: Snapshot.WorldSnapshot, theirs: Snapshot.WorldSnapshot) => Rendered.Rendered<ReadonlyArray<Difference>>;
|
|
54
|
+
export declare const compare: (mine: Snapshot.WorldSnapshot, theirs: Snapshot.WorldSnapshot, options?: CompareOptions) => Rendered.Rendered<ReadonlyArray<Difference>>;
|
|
35
55
|
//# sourceMappingURL=Desync.d.ts.map
|
package/dist/Desync.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Desync.d.ts","sourceRoot":"","sources":["../src/Desync.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"Desync.d.ts","sourceRoot":"","sources":["../src/Desync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,KAAK,QAAQ,MAAM,0BAA0B,CAAA;AAEzD,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AAEzC,yFAAyF;AACzF,MAAM,WAAW,UAAU;IACzB,0JAA0J;IAC1J,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AA4BD,4BAA4B;AAC5B,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,CAAA;CAChC;AAED,mJAAmJ;AACnJ,eAAO,MAAM,OAAO,SAAU,QAAQ,CAAC,aAAa,UAAU,QAAQ,CAAC,aAAa,YAAW,cAAc,KAAQ,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,UAAU,CAAC,CAsB/J,CAAA"}
|
package/dist/Desync.js
CHANGED
|
@@ -2,48 +2,50 @@ import * as Format from "./Format.js";
|
|
|
2
2
|
import * as Rendered from "./Rendered.js";
|
|
3
3
|
const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
4
4
|
/** The leaves where two values differ, under `path`. */
|
|
5
|
-
const differences = (path, mine, theirs, into) => {
|
|
5
|
+
const differences = (path, entity, mine, theirs, into) => {
|
|
6
6
|
if (Format.sameValue(mine, theirs))
|
|
7
7
|
return;
|
|
8
8
|
if (isRecord(mine) && isRecord(theirs)) {
|
|
9
9
|
for (const key of [...new Set([...Object.keys(mine), ...Object.keys(theirs)])].sort()) {
|
|
10
|
-
differences(`${path}.${key}`, mine[key], theirs[key], into);
|
|
10
|
+
differences(`${path}.${key}`, entity, mine[key], theirs[key], into);
|
|
11
11
|
}
|
|
12
12
|
return;
|
|
13
13
|
}
|
|
14
14
|
if (Array.isArray(mine) && Array.isArray(theirs) && mine.length === theirs.length) {
|
|
15
|
-
mine.forEach((item, index) => differences(`${path}[${index}]`, item, theirs[index], into));
|
|
15
|
+
mine.forEach((item, index) => differences(`${path}[${index}]`, entity, item, theirs[index], into));
|
|
16
16
|
return;
|
|
17
17
|
}
|
|
18
|
-
into.push({ path, mine, theirs });
|
|
18
|
+
into.push({ path, entity, mine, theirs });
|
|
19
19
|
};
|
|
20
20
|
/** Each named entry of two records, compared under `kind name`. */
|
|
21
|
-
const byName = (kind, mine, theirs, into) => {
|
|
21
|
+
const byName = (kind, entity, mine, theirs, into) => {
|
|
22
22
|
for (const name of [...new Set([...Object.keys(mine), ...Object.keys(theirs)])].sort()) {
|
|
23
|
-
differences(`${kind} ${name}`, mine[name], theirs[name], into);
|
|
23
|
+
differences(`${kind} ${name}`, entity, mine[name], theirs[name], into);
|
|
24
24
|
}
|
|
25
25
|
};
|
|
26
26
|
/** Every difference between two saves, in a stable order: the next id, entities by id, then resources, machines, relations, and scopes by name. */
|
|
27
|
-
export const compare = (mine, theirs) => {
|
|
27
|
+
export const compare = (mine, theirs, options = {}) => {
|
|
28
28
|
const found = [];
|
|
29
|
-
differences("nextEntity", mine.nextEntity, theirs.nextEntity, found);
|
|
29
|
+
differences("nextEntity", undefined, mine.nextEntity, theirs.nextEntity, found);
|
|
30
30
|
const mineById = new Map(mine.entities.map((entity) => [entity.id, entity.components]));
|
|
31
31
|
const theirsById = new Map(theirs.entities.map((entity) => [entity.id, entity.components]));
|
|
32
32
|
for (const id of [...new Set([...mineById.keys(), ...theirsById.keys()])].sort((a, b) => a - b)) {
|
|
33
33
|
const left = mineById.get(id);
|
|
34
34
|
const right = theirsById.get(id);
|
|
35
35
|
if (left === undefined || right === undefined)
|
|
36
|
-
found.push({ path: `entity ${id}`, mine: left, theirs: right });
|
|
36
|
+
found.push({ path: `entity ${id}`, entity: id, mine: left, theirs: right });
|
|
37
37
|
else
|
|
38
|
-
byName(`entity ${id}`, left, right, found);
|
|
38
|
+
byName(`entity ${id}`, id, left, right, found);
|
|
39
39
|
}
|
|
40
|
-
byName("resource", mine.resources, theirs.resources, found);
|
|
41
|
-
byName("machine", mine.machines, theirs.machines, found);
|
|
42
|
-
byName("relation", mine.relations, theirs.relations, found);
|
|
43
|
-
byName("scope", mine.scopes, theirs.scopes, found);
|
|
40
|
+
byName("resource", undefined, mine.resources, theirs.resources, found);
|
|
41
|
+
byName("machine", undefined, mine.machines, theirs.machines, found);
|
|
42
|
+
byName("relation", undefined, mine.relations, theirs.relations, found);
|
|
43
|
+
byName("scope", undefined, mine.scopes, theirs.scopes, found);
|
|
44
|
+
// `entity 12 ...` prints as `player e12 ...`, like every entity in devtools text.
|
|
45
|
+
const where = ({ path, entity }) => entity === undefined ? path : `${Format.entity(entity, options.labels)}${path.slice(`entity ${entity}`.length)}`;
|
|
44
46
|
const text = found.length === 0
|
|
45
47
|
? "The saves are equal."
|
|
46
|
-
: [`${found.length} difference${found.length === 1 ? "" : "s"} (mine -> theirs):`, ...found.map((
|
|
48
|
+
: [`${found.length} difference${found.length === 1 ? "" : "s"} (mine -> theirs):`, ...found.map((difference) => ` ${where(difference)}: ${Format.value(difference.mine)} -> ${Format.value(difference.theirs)}`)].join("\n");
|
|
47
49
|
return Rendered.make(found, text);
|
|
48
50
|
};
|
|
49
51
|
//# sourceMappingURL=Desync.js.map
|