@typeonce/ritmo-devtools 0.13.0 → 0.15.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 +312 -0
- package/README.md +336 -58
- package/dist/Desync.d.ts +49 -0
- package/dist/Desync.d.ts.map +1 -0
- package/dist/Desync.js +51 -0
- package/dist/Desync.js.map +1 -0
- package/dist/Determinism.d.ts +17 -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 +63 -31
- package/dist/Format.js.map +1 -1
- package/dist/Fuzz.d.ts +268 -0
- package/dist/Fuzz.d.ts.map +1 -0
- package/dist/Fuzz.js +355 -0
- package/dist/Fuzz.js.map +1 -0
- package/dist/Invariant.d.ts +6 -2
- package/dist/Invariant.d.ts.map +1 -1
- package/dist/Invariant.js.map +1 -1
- package/dist/Lint.d.ts +9 -3
- 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 +193 -0
- package/dist/PlaywrightEngine.js.map +1 -0
- package/dist/Replay.d.ts +43 -34
- package/dist/Replay.d.ts.map +1 -1
- package/dist/Replay.js +27 -33
- package/dist/Replay.js.map +1 -1
- package/dist/Session.d.ts +214 -17
- package/dist/Session.d.ts.map +1 -1
- package/dist/Session.js +563 -57
- package/dist/Session.js.map +1 -1
- package/dist/Verify.d.ts +147 -0
- package/dist/Verify.d.ts.map +1 -0
- package/dist/Verify.js +151 -0
- package/dist/Verify.js.map +1 -0
- package/dist/cli.js +136 -8
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +4 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -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/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 +100 -0
- package/src/Determinism.ts +46 -11
- package/src/Format.ts +99 -34
- package/src/Fuzz.ts +544 -0
- package/src/Invariant.ts +6 -2
- package/src/Lint.ts +9 -3
- package/src/PlaywrightEngine.ts +229 -0
- package/src/Replay.ts +98 -74
- package/src/Session.ts +806 -72
- package/src/Verify.ts +273 -0
- package/src/cli.ts +131 -8
- package/src/index.ts +4 -2
- package/src/internal/dependencyScan.ts +356 -0
- package/src/internal/fuzzNetwork.ts +130 -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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,317 @@
|
|
|
1
1
|
# @typeonce/ritmo-devtools
|
|
2
2
|
|
|
3
|
+
## 0.15.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 4c867ef: **Browser input replays and fuzzes through the one descriptor the page reads.** A game that declared its input service as the whole `Controls` merge (or a device) could not be opened from a replay or fuzzed: `playback.source(...)` hands back a plain `snapshot()` source, which has no `rebind` or `dispose`. Declare the service as `InputCapture.SourceOf<...>` the merge, device, or pool (its `snapshot()` only, still marked as draining, so systems keep reading the captured resource). The live merge provides it in the page, scripted devices in tests, `playback.source(ControlsInput)` in a replay, and `Fuzz.input` in the fuzzer; the page keeps the merge to rebind and dispose it.
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
const ControlsInput =
|
|
11
|
+
Descriptor.Service<
|
|
12
|
+
InputCapture.SourceOf<ReturnType<typeof makeControls>>
|
|
13
|
+
>()("Game/Controls");
|
|
14
|
+
const devices = { keyboard: Keyboard.idle(keys), gamepad: Gamepad.idle(pad) };
|
|
15
|
+
const Fuzzed = Fuzz.input(ControlsInput, {
|
|
16
|
+
generate: (random) => Actions.random(random, devices),
|
|
17
|
+
neutral: Actions.idle(devices),
|
|
18
|
+
});
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- `Controls.actions(...).random(random, devices)` draws a merged snapshot a real merge could report: each button idle, held, just pressed, tapped, or just released, and each vector zero, one of eight directions, or a tilt shorter than 1. Device data stays as given, every action is available, and no device is last used.
|
|
22
|
+
- `Controls.players(...).random(random, frame, { devices, seats })` draws a pool's snapshot with the listed slots seated from frame 1 (reporting `event: "joined"` there, with idle input, as `pool.seat` in setup does) and their input drawn after. A pool is one source carrying every slot, because one `snapshot()` drains every pooled device and decides joins across them.
|
|
23
|
+
- `Replay.Playback.source` and `Fuzz.input` take any `snapshot()`-only source service, including ones that mark `snapshot()` with `System.Consumes` (`InputCapture.SourceOf`, `Netcode.Source`). A service declared as the whole device is a compile error naming the fix: "has more than snapshot(), so a replay cannot provide it". `Replay.SourceData<Value>` names the data a source returns.
|
|
24
|
+
|
|
25
|
+
- 45458dc: **A stream of the relation edges a target's despawn dropped.** When the target of a `Descriptor.Relation` despawns, the runtime removes every edge to it. A system now reads those edges once, with the same rules as `readRelationFailures`: each reader sees what was dropped since its own previous run, a reader gated by `when` drops what was published meanwhile, one under `pauseWhen` reads it later, a reader that fell behind by more than `Runtime.streamCapacity` records sees `lagged() === true`, and checkpoints rewind it.
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
const DropTargets = Game.System(
|
|
29
|
+
"Game/DropTargets",
|
|
30
|
+
{
|
|
31
|
+
droppedRelations: { lost: Game.System.readDroppedRelations(Targeting) },
|
|
32
|
+
commands: Game.System.commands(Game.System.inserts(Idle)),
|
|
33
|
+
},
|
|
34
|
+
({ droppedRelations, commands }) => {
|
|
35
|
+
for (const { source } of droppedRelations.lost.all())
|
|
36
|
+
commands.insert(source, [Idle, {}]);
|
|
37
|
+
}
|
|
38
|
+
);
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- Records are `Relation.Relation.Dropped`: `{ relation, source, target }` as entity ids. Only a target's despawn records an edge: `commands.unrelate`, relating the source elsewhere, and the source's own despawn record nothing. A `Descriptor.Hierarchy` records nothing, since its children despawn with their parent.
|
|
42
|
+
- Inspectors can read `droppedRelations` too.
|
|
43
|
+
- Debug traces carry a `relationDropped` effect on the despawn that dropped the edge, and devtools journals it as `Game/Targeting from e7 to e12 dropped: e12 despawned`. `describe()` lists a system's `droppedRelations` (`reads dropped relations: ...` in devtools), and `streams()` reports the `droppedRelation` streams.
|
|
44
|
+
- **Breaking for code that switches over debug types:** `Debug.Effect` has a new `relationDropped` kind, `Debug.StreamStatus["kind"]` and `Debug.MissedRead["kind"]` have a new `droppedRelation` kind, and `Debug.SystemDescription` has a new `droppedRelations` field. Add the case to an exhaustive `switch`, and the field to a hand-built `SystemDescription`.
|
|
45
|
+
|
|
46
|
+
- c75daff: **Breaking: `Ops` and `Random` moved from `@typeonce/ritmo-math` into `@typeonce/ritmo`.** Determinism belongs to the runtime: every simulation needs same-bits math and a seeded generator, with or without the 2D helpers. The modules are unchanged; only the import path moves, and `@typeonce/ritmo-math` no longer exports them. The `Ops` header now states that its list is closed: the 22 functions engines may approximate and `**`; everything else on `Math` is already exact. `@typeonce/ritmo-devtools` and `@typeonce/ritmo-netcode` no longer depend on `@typeonce/ritmo-math`.
|
|
47
|
+
|
|
48
|
+
```diff
|
|
49
|
+
- import { Ops, Random } from "@typeonce/ritmo-math"
|
|
50
|
+
+ import { Ops, Random } from "@typeonce/ritmo"
|
|
51
|
+
- import * as Random from "@typeonce/ritmo-math/Random"
|
|
52
|
+
+ import * as Random from "@typeonce/ritmo/Random"
|
|
53
|
+
- import * as Ops from "@typeonce/ritmo-math/Ops"
|
|
54
|
+
+ import * as Ops from "@typeonce/ritmo/Ops"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`oxlint --fix` with `ritmo/use-ops-for-math` adds the new import where a `Math` call is rewritten; other imports need the path changed by hand.
|
|
58
|
+
|
|
59
|
+
- c20f20b: **Descriptor metadata: a field's unit, range, and hint next to its schema.** Every component and resource constructor (`Component`, `ConstructedComponent`, `TransientComponent`, `Resource`, `ConstructedResource`, `TransientResource`) takes an optional `meta` option keyed by the value's top-level fields. Each field gets `unit?: string`, `range?: readonly [min, max]` (number fields only), and `hint?: string` (one sentence an agent reads).
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
const Health = Descriptor.ConstructedComponent(z.object({ hp: z.number() }))(
|
|
63
|
+
"Game/Health",
|
|
64
|
+
{
|
|
65
|
+
meta: {
|
|
66
|
+
hp: {
|
|
67
|
+
unit: "points",
|
|
68
|
+
range: [0, 100],
|
|
69
|
+
hint: "Hit points left; 0 despawns the entity.",
|
|
70
|
+
},
|
|
71
|
+
},
|
|
72
|
+
}
|
|
73
|
+
);
|
|
74
|
+
const Tuning = Descriptor.Resource<{ speed: number }>()("Game/Tuning", {
|
|
75
|
+
meta: { speed: { unit: "px/s", range: [0, 400] } },
|
|
76
|
+
});
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
- A key that is not a field of the value does not compile (`not a field of this value`, with the value's fields under `fields`); `range` on a non-number field does not compile (`` `range` is only for number fields``); a key other than `unit`, `range`, or `hint` does not compile. A malformed option from an unchecked caller throws, naming the descriptor.
|
|
80
|
+
- Metadata never replaces validation: the schema still decides what is valid, and snapshots do not save it. It is checked once at the constructor, frozen, and listed by `runtime.debug.describe()` as `meta` on every `ComponentDescription` and `ResourceDescription` (`{}` when none).
|
|
81
|
+
- Resource constructors now take an options argument (`ResourceOptions`); `ComponentOptions` gains `meta`. New types: `FieldMeta`, `MetaField`, `CheckedMeta`, `CheckedOptions`, `MetaInput`.
|
|
82
|
+
- Devtools: `session.report()` raises an `out-of-range` warning for every write (system writes, resources, spawns, inserts) of a number outside its declared range: `e1 Game/Health.hp written as 120, declared range [0, 100] by Game/Heal at frame 42`. The scan runs only in debug sessions; production runtimes never read the metadata.
|
|
83
|
+
- Devtools: `session.describe()` lists each field's metadata under its component or resource; `Format.fieldMeta(field, meta)` prints one field's line. The monitor's Entity tab shows units next to values and each field's unit, range, and hint in the value's tooltip.
|
|
84
|
+
|
|
85
|
+
- c8320b4: **Entity labels in devtools output.** `Session.make(runtime, { ..., labels: Labels })` takes a `Game.Inspector` returning a `ReadonlyMap<number, string>` (entity id to label), and every entity in the session's text prints as `player e12` instead of `e12`: journal and `why` lines, `dump`, report warnings, and invariant messages (write entities as `e${id}` in the message). Labels are evaluated after every frame of a `run`, so a line shows the label its entity had at the end of that frame, and a despawned entity keeps its last label. They run only in the debug session: the runtime and production builds do not change.
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
const Labels = Game.Inspector(
|
|
89
|
+
"labels",
|
|
90
|
+
{
|
|
91
|
+
queries: {
|
|
92
|
+
players: Game.Query({
|
|
93
|
+
selection: { position: Game.Query.read(Position) },
|
|
94
|
+
with: [Player],
|
|
95
|
+
}),
|
|
96
|
+
},
|
|
97
|
+
},
|
|
98
|
+
({ queries }) =>
|
|
99
|
+
new Map(
|
|
100
|
+
queries.players
|
|
101
|
+
.each()
|
|
102
|
+
.map((match) => [match.entity.id, "player"] as const)
|
|
103
|
+
)
|
|
104
|
+
);
|
|
105
|
+
const session = Session.make(runtime, {
|
|
106
|
+
hostClock,
|
|
107
|
+
schedules: { update },
|
|
108
|
+
labels: Labels,
|
|
109
|
+
});
|
|
110
|
+
session.why(12, Position); // "player e12 Game/Position is now {x:4}; ..."
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- An inspector returning anything else does not compile (`labels must return a ReadonlyMap<number, string> from entity id to label`); one reading a resource, service, or machine the runtime does not provide names it under `__fixLabelsRequirements__`, like invariants.
|
|
114
|
+
- `Replay.session(make, file, { labels })` and `Determinism.check(make, { ..., labels })` take the same inspector. A determinism difference inside an entity now carries `entity` (its id) and `label`.
|
|
115
|
+
- `Desync.compare(mine, theirs, { labels: runtime.inspect(Labels) })` names entities with the labels it is given. `Difference` gains `entity`.
|
|
116
|
+
- `Format.entity(id, labels)` is the one way devtools prints an entity; `Format.lines` and `Format.dump` take labels, and `Format.Line` gains `label`.
|
|
117
|
+
- A `run` whose labels inspector throws stops with `reason: "labels-threw"`.
|
|
118
|
+
- **Breaking: `Desync.compare` text prints entities as `e12` (`player e12` with labels), not `entity 12`.** `Difference.path` is unchanged; match on it, or on the new `entity`, instead of the text.
|
|
119
|
+
- **Breaking: `Determinism.check`'s factory returns the whole debug runtime** (`inspect`, `services`, `resourceValues`, `machineValues` as well as `debug` and `tryTick`), so `labels` is checked against its provisions. Return the `Game.Runtime.make(...).value` itself rather than an object picking `debug` and `tryTick`.
|
|
120
|
+
- **Breaking: `Session.Stop` has a new `labels-threw` reason.** An exhaustive `switch` on `stop.reason` adds the case.
|
|
121
|
+
|
|
122
|
+
- 14fbe8f: **`Fuzz.run` finds a bug before anyone plays into it, and shrinks it to a replay.** It builds a fresh simulation per run with the same `make(playback)` factory `Replay.session` opens replays with, feeds each fuzzed `snapshot()` source a value drawn from a seeded `Random` (from `@typeonce/ritmo`) every frame, and ticks the schedule in a `Session` until an invariant breaks, a system fails, or something throws. The failing timeline is then shrunk by delta debugging (ranges of frames dropped, then each value moved toward the input's `neutral`), re-running the simulation for every candidate, and returned as a `Found` error carrying the shrunk `Replay.ReplayFile`, the run's seed, the failing frame, and the shrink statistics; `Flaky`, `InvalidOptions`, and `Unreplayable` are the other failures. Declare an input with `Fuzz.input(Source, { generate: (random, frame) => value, neutral })`; the value is typed as the source's. `Replay.session(make, file, { invariants })` now checks invariants on every replayed tick, so the shrunk replay plays to the same violation and becomes the regression test. `Replay.Target` gains optional type parameters for the schedules and provisions, so the invariants are checked against the runtime at compile time.
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
const found = Fuzz.run(make, {
|
|
126
|
+
schedule: "update",
|
|
127
|
+
setup: "setup",
|
|
128
|
+
inputs: [Fuzz.input(PadInput, { generate, neutral: { key: 0 } })],
|
|
129
|
+
invariants: [Alive],
|
|
130
|
+
frames: 3000,
|
|
131
|
+
seed: 7,
|
|
132
|
+
});
|
|
133
|
+
if (!found.ok && found.error._tag === "Found") sink.save(found.error.replay);
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
- 7722666: **`Fuzz.run` fuzzes a rollback game over a faulty network with an optional `network`.** Declare every seat's input with `Fuzz.seats(Seats, { codec, count, idle, generate: (random, frame, seat) => input })` and pass `network: { seed, latencyMS, jitterMS, loss, step }`: each seat plays on its own peer (a fresh `make(playback)`, whose `playback.source(Seats)` is that peer's `seats.source`), joined by a seeded `MemoryNetworkLink` and driven by `Netcode.rollback` sessions, with invariants checked on every peer. A desync or any other session failure is the new `SessionFailed` violation (`seat`, and the `Netcode.SessionError`), and shrinking shrinks the input timeline one seat at a time with the network seed fixed. Over a network, a schedule that cannot be rewound or a runtime that cannot save does not compile, as for `Netcode.rollback`. Devtools now depends on `@typeonce/ritmo-netcode`.
|
|
137
|
+
|
|
138
|
+
`Fuzz.Violation` gains `SessionFailed`: a `switch` over it that must be exhaustive needs the new case:
|
|
139
|
+
|
|
140
|
+
```diff
|
|
141
|
+
case "Defect": return ...
|
|
142
|
+
+ case "SessionFailed": return `seat ${violation.seat}: ${violation.error._tag}`
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
- a9159bc: **Breaking: the live browser monitor is removed.** `Monitor` (`Monitor.attach`, `Monitor.Collector`, `recentSystem`, `recentSchedule`, and their types) is gone, with no replacement export: debugging is headless and text-first, and the package no longer needs the `DOM` lib. Record the browser session as a replay and debug it with a `Session`:
|
|
146
|
+
|
|
147
|
+
```diff
|
|
148
|
+
- Monitor.attach(runtime, { schedules, host: window, replay: recorder })
|
|
149
|
+
+ const recorder = Replay.recorder(runtime, { schedule: simulate, name: "simulate", keep: 30, step: STEP, sink: ReplayViteSink.make({ fetch: (url, init) => fetch(url, init) }), hostClock: BrowserHostClock.make(window), saveOn: { failure: true } })
|
|
150
|
+
+ // In Node: Replay.session(make, file.value) or Session.make(runtime, { hostClock: HostClock.test(), schedules }), then why / journal / report.
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
To find an entity without clicking it, give the session a `labels` inspector and filter `session.dump({ with: [Player] })`.
|
|
154
|
+
|
|
155
|
+
- 01959dd: Step one frame a system at a time.
|
|
156
|
+
|
|
157
|
+
- `session.step(name)` begins one frame of a named schedule and returns a `SteppedFrame`: `until(System)` runs the steps before that system and stops there, `next()` runs exactly one step (a system or a marker), `check()` asks the invariants mid-frame, and `finish()` runs the rest and returns the same `RunResult` as `run(name, { frames: 1 })`, with labels and invariants evaluated at the end of the frame. `until` takes the system value, and only a system the schedule runs as a step compiles. `journal`, `why`, and `dump` show the partial frame.
|
|
158
|
+
- Core: `runtime.debug.beginFrame(schedule)` returns a `Debug.FrameCursor` (`next()`, `remaining()`) for the frame `tryTick(schedule)` would run, with the same commits, markers, reader cursors, and trace and host events. While a frame is open, `tick`, `tryTick`, `send`, `snapshot`, `checksum`, `restore`, `checkpoint`, `rewind`, and another `beginFrame` throw; `session.run` and `session.step` throw until `finish()`.
|
|
159
|
+
- `Format.step` prints one schedule step.
|
|
160
|
+
- `Session.Session` takes a third type parameter, the record of schedules, which `Session.make` infers.
|
|
161
|
+
|
|
162
|
+
- 89cc400: Add `ritmo-devtools verify <entry> <replay> --engines node,chromium,webkit,firefox`: plays a replay in Node (twice, and against its recording) and in real browser engines, and prints the first tick whose world differs with every value that differs there. Exit code 1 on a difference or an engine that did not run, 2 on a usage error; `--json` for JSON. `<entry>` exports `replayTarget`, the `make(playback)` factory `Replay.session` takes.
|
|
163
|
+
|
|
164
|
+
The same check from code is the new `Verify` module (`Verify.acrossEngines(make, file, { engines })`, returning `Verified` or `ReplayInvalid` / `NotVerified` with one `Agreed`, `Diverged`, `EngineMissing`, or `EngineFailed` outcome per engine), and the new `PlaywrightEngine` module (Node host) runs Chromium, WebKit, and Firefox headless. `playwright` and `vite` are optional peer dependencies, needed only for browser engines; `--engines node` needs neither.
|
|
165
|
+
|
|
166
|
+
- c75daff: **Breaking: `Replay.verify` is removed.** `Verify.acrossEngines(make, file)` is the one replay check: with no engines it plays the replay twice in this process and against the recording, as `Replay.verify` did; with engines it also runs browsers. It is async and fails with `NotVerified` (each outcome names the engine, tick, and values) instead of returning `deterministic: false`.
|
|
167
|
+
|
|
168
|
+
```diff
|
|
169
|
+
- const same = Replay.verify(make, file)
|
|
170
|
+
- expect(same.ok && same.value.data.deterministic).toBe(true)
|
|
171
|
+
+ const same = await Verify.acrossEngines(make, file)
|
|
172
|
+
+ expect(same.ok).toBe(true) // same.error.text says where it differs
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
**`ritmo-devtools scan <entry>` lists the determinism risks in dependencies.** oxlint skips `node_modules`, so a library the simulation calls can still use `Math.sin`. The scan resolves every file the simulation entry imports, `node_modules` included (with rolldown, which Vite 8 already brings), and runs `ritmo/use-ops-for-math`, `ritmo/use-clock-for-time`, and `ritmo/use-random-for-randomness` over them with the game's own oxlint. It prints the findings per package with `file:line:column`, or JSON with `--json`, and always exits 0 when it ran: it is a hint. `oxlint` and `rolldown` are optional peer dependencies.
|
|
176
|
+
|
|
177
|
+
```sh
|
|
178
|
+
ritmo-devtools scan src/simulation/index.ts
|
|
179
|
+
# fake-physics (2 findings)
|
|
180
|
+
# node_modules/fake-physics/index.js:4:17 ritmo/use-ops-for-math Math.sin
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
- 233b93f: **`why` follows the reads behind a value.** `session.why(entity, Component, { depth })` and `session.whyResource(Resource, { depth })` indent, under each change, what the writing system declared it reads and the latest traced fact that could have produced the value it saw: an event's sends since the system's previous run and their sender, the latest change of a component of the same entity (read in the query that wrote it), of a resource, or of a machine. Each `depth` step goes one system further back; `depth: 1`, the default, prints exactly what it printed before.
|
|
184
|
+
|
|
185
|
+
```ts
|
|
186
|
+
session.why(12, Health, { depth: 3 });
|
|
187
|
+
// f181 update Game/ApplyDamage write e12 Game/Health 70 -> 40
|
|
188
|
+
// read Game/Damage [{amount:30}] (declared), emitted by Game/Hitscan at f181
|
|
189
|
+
// read resource Game/Aim {target:12} (declared), written by Game/AimAtNewest at f180
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
- The trace records writes, not reads, so every such line ends in `(declared)`: a possible cause, not an observed read. A query over other entities prints only how many entities match it now (`read Game/Position of 14 matching entities now (declared; the trace does not say which it read)`).
|
|
193
|
+
- A system already in the chain prints `(cycle: not followed)`. `limit` also caps the reads under each line.
|
|
194
|
+
- `Session.WhyOptions` is the options type. `Format.Line` gains `depth` (0 for every journal line), `Format.LineKind` gains `read`, and `Format.line` prints a line with `depth` above 0 as its text, indented.
|
|
195
|
+
|
|
196
|
+
### Patch Changes
|
|
197
|
+
|
|
198
|
+
- d01a735: **Zod schemas work with Ritmo: the schema back to the saved form is under `"~encode"`, not `encode`.** Zod (from 4.1) gives every schema an `encode()` method, which Ritmo read as its encode schema: `Descriptor.ConstructedComponent(z.object(...))` did not compile, and with a cast `runtime.snapshot()` threw `Cannot read properties of undefined (reading 'validate')`. The key now starts with `~`, like Standard Schema's own `~standard`, so no library's methods collide with it. A Zod, Valibot, or ArkType schema of plain data passes as it is; Ritmo's tests now save and load a schema of each, and of Effect, through JSON.
|
|
199
|
+
|
|
200
|
+
- **Breaking: a codec carries its encode schema as `"~encode"`.** The Effect helper from the skill's `playbooks/effect.md` (or a hand-written codec) renames the key:
|
|
201
|
+
|
|
202
|
+
```diff
|
|
203
|
+
return {
|
|
204
|
+
"~standard": Schema.toStandardSchemaV1(json)["~standard"],
|
|
205
|
+
- encode: Schema.toStandardSchemaV1(Schema.flip(json))
|
|
206
|
+
+ "~encode": Schema.toStandardSchemaV1(Schema.flip(json))
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
A transforming schema without it fails with `give it a ~encode schema back to the saved form`.
|
|
211
|
+
|
|
212
|
+
- **Values that transform** (a `Date`, a `Map`) save through a `"~encode"` from any library. Zod's comes from the new `playbooks/zod.md` helper, built on Zod's own `safeEncode`: `Descriptor.ConstructedComponent(codec(z.codec(z.iso.datetime(), z.date(), { decode, encode })))`. With Valibot, ArkType, or any other Standard Schema library, write the reverse schema by hand:
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
const Born = Descriptor.ConstructedComponent({
|
|
216
|
+
"~standard": v.pipe(
|
|
217
|
+
v.string(),
|
|
218
|
+
v.isoTimestamp(),
|
|
219
|
+
v.transform((text) => new Date(text))
|
|
220
|
+
)["~standard"],
|
|
221
|
+
"~encode": v.pipe(
|
|
222
|
+
v.date(),
|
|
223
|
+
v.transform((date) => date.toISOString())
|
|
224
|
+
),
|
|
225
|
+
})("Game/Born");
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
- **Handles and deadlines inside a game's schema** are built from their guards with a schema that narrows to the guard's type: `z.unknown().refine(Entity.isHandle(Root))` in Zod, `v.pipe(v.unknown(), v.guard(...))` in Valibot, `type("unknown").narrow(...)` in ArkType, `Schema.declare(...)` in Effect. The docs said `z.custom(guard)`, which types the value as `unknown`.
|
|
229
|
+
|
|
230
|
+
- Updated dependencies [3a195b7]
|
|
231
|
+
- Updated dependencies [d01a735]
|
|
232
|
+
- Updated dependencies [45458dc]
|
|
233
|
+
- Updated dependencies [c75daff]
|
|
234
|
+
- Updated dependencies [b77b17d]
|
|
235
|
+
- Updated dependencies [c20f20b]
|
|
236
|
+
- Updated dependencies [01959dd]
|
|
237
|
+
- Updated dependencies [637fa1f]
|
|
238
|
+
- Updated dependencies [44e9b42]
|
|
239
|
+
- Updated dependencies [6b0d73e]
|
|
240
|
+
- Updated dependencies [7722666]
|
|
241
|
+
- @typeonce/ritmo@0.15.0
|
|
242
|
+
- @typeonce/ritmo-netcode@0.15.0
|
|
243
|
+
|
|
244
|
+
## 0.14.0
|
|
245
|
+
|
|
246
|
+
### Minor Changes
|
|
247
|
+
|
|
248
|
+
- 70d054e: **Rewind a runtime in memory, for rollback netcode and client prediction.** `runtime.checkpoint(simulate)` marks the world between ticks, and `runtime.rewind(checkpoint)` puts it back exactly: ticking `simulate` again gives the same results, bit for bit, as a runtime that never rewound (entity ids, values and their change ticks, relations, scopes, resources, machines, queued commands, unread events, and the read positions of `simulate`'s systems). See the `Checkpoint` module, and the skill's new `playbooks/netcode.md`.
|
|
249
|
+
|
|
250
|
+
```ts
|
|
251
|
+
const history = new Map<number, Checkpoint.Checkpoint<typeof Root>>();
|
|
252
|
+
history.set(tick, runtime.checkpoint(simulate));
|
|
253
|
+
runtime.tick(simulate);
|
|
254
|
+
|
|
255
|
+
// Real input for an earlier tick differs from the guess: go back and run again.
|
|
256
|
+
const rewound = runtime.rewind(history.get(wrongTick)!);
|
|
257
|
+
if (!rewound.ok) resync(rewound.error); // Released: older than the window
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
- Taking a checkpoint copies only resources, machines, and queues; the first change to a page of values, an entity, a relation, or a scope after it keeps what it replaced. The runtime keeps the last `checkpoints` (a new option of `Game.Runtime.make`, `Checkpoint.defaultWindow` = 16 by default); an older one, one newer than a checkpoint rewound to, and every one taken before a `restore` fail with `Released`. A checkpoint of another runtime fails with `OtherRuntime`.
|
|
261
|
+
- A schedule that would not rewind does not compile, and the error (`__fixCheckpoint__`) names the fix: a service that is neither an input source (`snapshot()`) nor plain data, a system with `local` state (in its state transitions too), or a schedule widened to a schedule type.
|
|
262
|
+
- Systems and inspectors outside the rewound schedule, like renderers, see a rewind as ordinary changes. An entity the rewind took away and the ticks after it brought back under the same id is seen as changed, never as despawned and spawned again, so `RenderSync` keeps its node.
|
|
263
|
+
- **`runtime.checksum()`**: a fingerprint of what `snapshot()` saves, as 16 hex digits, that does not depend on how the world was built (component order, object key order). Peers compare it to catch a desync; gated like `snapshot`, and returns a `Result`.
|
|
264
|
+
- `Schedule.Source<Data>` and `Schedule.IsPlain<T>`: the input-source shape and the plain-data check that replays and checkpoints share. `Schedule.SystemsIn` is exported.
|
|
265
|
+
|
|
266
|
+
**Devtools:**
|
|
267
|
+
|
|
268
|
+
- **Breaking: `Replay.Source` and `Replay.IsPlain` moved to core**, as `Schedule.Source` and `Schedule.IsPlain`.
|
|
269
|
+
|
|
270
|
+
```diff
|
|
271
|
+
-const Controls = Descriptor.Service<Replay.Source<Input>>()("Game/Controls")
|
|
272
|
+
+import type * as Schedule from "@typeonce/ritmo/Schedule"
|
|
273
|
+
+const Controls = Descriptor.Service<Schedule.Source<Input>>()("Game/Controls")
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
- **Breaking: replay checkpoint hashes are `runtime.checksum()`.** Replays recorded with an earlier version report every checkpoint as diverged; record them again. A runtime passed to `Replay.recorder` or `Replay.session` needs `checksum`, which every runtime with `snapshot` has.
|
|
277
|
+
|
|
278
|
+
**Lint:** `handle-tick-result` also reports a dropped `runtime.rewind(...)` result: a released checkpoint changes nothing, and the ticks meant to run again would run on top of the present.
|
|
279
|
+
|
|
280
|
+
- dbfbd9d: **New package: `@typeonce/ritmo-netcode`, online multiplayer.** A session per peer exchanges inputs over a `NetworkLink` and ticks the simulation with every seat's input: `Netcode.rollback` runs at once on guesses and rolls back with the runtime's checkpoints when real input contradicts one; `Netcode.lockstep` waits for every seat. Seat 0 starts the match and every resync from one save that every peer restores at the same tick; `session.rate` slows the peer that runs ahead; peers compare checksums of confirmed ticks, and a mismatch stops the session with `Desynced` until `resync()`.
|
|
281
|
+
|
|
282
|
+
```ts
|
|
283
|
+
const seats = Netcode.seats(PlayerInput, { count: 2, idle }) // the simulation's input source
|
|
284
|
+
const session = Netcode.rollback(runtime, { simulate, seats: seats.value, seat, links: [WebSocketNetworkLink.make(socket)], hostClock, step })
|
|
285
|
+
FixedLoop.start({ ..., rate: session.value.rate, update: session.value.update({ input: readInput, onHalted: report }) })
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
- Transports: `WebSocketNetworkLink.make(socket)` (a relay; the browser's, Node's, Deno's, or Bun's WebSocket), `WebRtcNetworkLink.make(channel)` (between peers), `MemoryNetworkLink.make(...)` (seeded latency, jitter, and loss, for headless tests), or any `{ send, receive, status }`.
|
|
289
|
+
- What does not compile: a rollback simulation that cannot be rewound, one whose requirements the runtime does not provide, and a runtime that cannot save. What fails at construction, as a typed `Result`: a seat out of range, seats another session took or the runtime does not provide, and a `maxRollback` beyond the checkpoints the runtime keeps.
|
|
290
|
+
- The skill's `playbooks/netcode.md` now drives the package instead of a hand-written loop.
|
|
291
|
+
|
|
292
|
+
**Core:**
|
|
293
|
+
|
|
294
|
+
- `FixedLoop.start` takes `rate`, read once per frame, within `FixedLoop.rateRange` (0.9 to 1.1): how fast host time runs into the accumulator, for a networked session's pacing. A value outside the range stops the loop with an `InvalidRate` failure, a new member of `FixedLoop.Failure`.
|
|
295
|
+
- **`runtime.restore` sets the next entity id to the save's**, where it used to keep the higher of the save's and the runtime's own. The same save restored in two runtimes now allocates the same ids afterwards, whatever each held before; peers of a networked game need it. A handle kept from before a restore may now name an entity spawned after it: drop handles across a restore, as their ids could already name restored entities.
|
|
296
|
+
|
|
297
|
+
**Lint:** `keep-simulation-headless` reports `WebSocket`, `RTCPeerConnection`, and `RTCDataChannel` with their own message: online play runs the simulation under a netcode session, and remote input goes through `Netcode.seats`, never `runtime.send(...)`.
|
|
298
|
+
|
|
299
|
+
**Devtools:** `Desync.compare(mine, theirs)` lists every difference between two saves of a tick, entities by id and values by path: the report for a `Desynced` session made with `keepSnapshots: true`.
|
|
300
|
+
|
|
301
|
+
### Patch Changes
|
|
302
|
+
|
|
303
|
+
- 01681a3: **The `ritmo-devtools lint` docs put the entry beside the simulation** (`src/lint.ts`), loading the render and audio schedules inside `lintTarget`. With the entry inside the simulation, `describe` made the simulation import host code, which a game's own import rules forbid. The CLI already treated the entry as host code; the docs now say so.
|
|
304
|
+
- Updated dependencies [c3719a5]
|
|
305
|
+
- Updated dependencies [70d054e]
|
|
306
|
+
- Updated dependencies [adb4066]
|
|
307
|
+
- Updated dependencies [97e95fb]
|
|
308
|
+
- Updated dependencies [dbfbd9d]
|
|
309
|
+
- Updated dependencies [343660e]
|
|
310
|
+
- Updated dependencies [d24258e]
|
|
311
|
+
- Updated dependencies [cfe332a]
|
|
312
|
+
- Updated dependencies [8aa1e85]
|
|
313
|
+
- @typeonce/ritmo@0.14.0
|
|
314
|
+
|
|
3
315
|
## 0.13.0
|
|
4
316
|
|
|
5
317
|
### Minor Changes
|