@wildshard/sdk 0.3.0 → 0.3.2

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.
Files changed (61) hide show
  1. package/GUIDE.md +10 -2
  2. package/docs/api/EXPORT-TIERS.md +7 -4
  3. package/lint/export-tiers.json +3 -0
  4. package/lint/host-callbacks.mjs +1 -1
  5. package/package.json +9 -5
  6. package/scripts/bake/template-skins.mjs +6 -3
  7. package/scripts/bake/template-warden.mjs +25 -0
  8. package/scripts/export-ci21-guests.mjs +89 -0
  9. package/scripts/scratch-sweep.mjs +3 -1
  10. package/src/cli/hero/hero.ts +45 -2
  11. package/src/sharddev/as/prelude.ts +67 -0
  12. package/src/sharddev/authorLint.ts +45 -0
  13. package/src/sharddev/bake/compileScript.ts +6 -0
  14. package/src/sharddev/bake/terrain.ts +11 -2
  15. package/src/sharddev/checkProject.ts +7 -18
  16. package/src/sharddev/engineMusic.ts +23 -0
  17. package/src/sharddev/materials.ts +7 -3
  18. package/src/sharddev/project.ts +5 -0
  19. package/src/sharddev/refusals.ts +1 -1
  20. package/src/sharddev/scene/author.ts +116 -11
  21. package/src/sharddev/scene/canvas.ts +2 -3
  22. package/src/sharddev/scene/description.ts +55 -2
  23. package/src/sharddev/scene/lower.ts +144 -29
  24. package/src/sharddev/scene/shard.ts +5 -2
  25. package/src/sharddev/scene/shardfile.ts +385 -72
  26. package/src/sharddev/watch/page.ts +116 -29
  27. package/src/sharddev/watch/pageEntry.ts +38 -2
  28. package/src/sharddev/watch/parity-baseline.json +22 -0
  29. package/src/sharddev/watch/parity.mjs +168 -0
  30. package/src/sharddev/watch/proof.mjs +129 -22
  31. package/src/sharddev/watch/protocol.ts +66 -8
  32. package/src/sharddev/watch/watch.ts +215 -51
  33. package/src/shards/_template/assets/3058c100bc477fd6fe8268f33b53756b8a2556e7e41c58b2216c703ca7b042c6 +1 -0
  34. package/src/shards/_template/assets/8a0440f392737a31cf0926a3c7dc011c320144972882945a5462c893e817d94a +0 -0
  35. package/src/shards/_template/behaviour/door.as +16 -26
  36. package/src/shards/_template/card/landscape.jpg +0 -0
  37. package/src/shards/_template/card/portrait.jpg +0 -0
  38. package/src/shards/_template/card/thumb.jpg +0 -0
  39. package/src/shards/_template/data/clientScripts.json +43 -43
  40. package/src/shards/_template/data/creatures.json +2 -2
  41. package/src/shards/_template/data/look.json +141 -13
  42. package/src/shards/_template/data/rows.json +20 -2
  43. package/src/shards/_template/data/skins.json +32 -0
  44. package/src/shards/_template/data/water.json +18 -0
  45. package/src/shards/_template/generators/product.ts +5 -1
  46. package/src/shards/_template/generators/warden.ts +273 -0
  47. package/src/shards/_template/generators/world.ts +52 -21
  48. package/src/shards/_template/hero.json +6 -6
  49. package/src/shards/authoring-slice/generators/shard.ts +9 -1
  50. package/src/shards/authoring-slice/generators/sky.ts +64 -0
  51. package/src/shards/authoring-slice/generators/template-sky.ts +27 -0
  52. package/src/shards/authoring-slice/generators/textures.ts +59 -0
  53. package/src/shards/authoring-slice/generators/world.ts +108 -5
  54. package/src/shards/mossgate/generators/shard.ts +6 -0
  55. package/src/shards/mossgate/generators/sky.ts +64 -0
  56. package/src/shards/mossgate/generators/textures.ts +249 -0
  57. package/src/shards/mossgate/generators/world.ts +998 -0
  58. package/src/shards/mossgate/shard.config.ts +7 -0
  59. package/scripts/shard-output-report.d.mts +0 -9
  60. package/scripts/shard-output-report.mjs +0 -85
  61. package/scripts/shard-platform-cli.mjs +0 -93
@@ -1,12 +1,15 @@
1
1
  import { Scope } from '@wildshard/engine/app/scope';
2
- import { DEV_HOOK_VERSION, DEV_SCENE_PATH, WATCH_SOCKET, WATCH_WIRE, decodeGeometry, type WatchPart, type WatchState } from './protocol';
2
+ import { DEV_HOOK_VERSION, DEV_SCENE_PATH, WATCH_SOCKET, WATCH_WIRE, budgetLines, decodeGeometry, type WatchBuild, type WatchPart, type WatchState } from './protocol';
3
3
 
4
4
  /**
5
5
  * SHARD-SOURCE AP5 (J347): the page script `wildshard watch` injects into the page it serves (`pageEntry.ts`, bundled at
6
6
  * start). It owns the page's half of watch: the socket, the fetches, a cache of decoded geometry and rasters, one scope
7
7
  * per part and the swap order, and drives engine's dev hook (`window.__wildshardDevHook`, five calls). Per revision:
8
8
  *
9
- * 1. the look's day keys, if they changed (`setLook`; a look the page can't take live reloads it)
9
+ * 1. the look's day keys, if they changed (`setLook`; a look the page can't take live reloads it), and the ground (AP18:
10
+ * `setGround`, the whole lattice; a page that can't take it reloads)
11
+ * 1b. the gameplay sections, if they changed (AP19: `restartGameplay`: the in-page server restarts its world on them and the
12
+ * quest views are built again; a page that can't reloads)
10
13
  * 2. every changed part is fetched and decoded first, so a slow fetch never leaves half a revision on screen
11
14
  * 3. each one swaps in (`addPart` or `replacePart`, then `swapColliders`), and only then its old scope goes
12
15
  * 4. parts no longer in the scene go (`removePart`, `swapColliders(name, [])`)
@@ -18,10 +21,16 @@ export interface DevHookLike {
18
21
  addPart: (name: string, part: unknown) => void;
19
22
  replacePart: (name: string, part: unknown) => void;
20
23
  removePart: (name: string) => void;
21
- setLook: (look: { readonly keys: readonly unknown[] }) => boolean;
24
+ setLook: (look: { readonly keys: readonly unknown[]; readonly look?: unknown }) => boolean;
22
25
  swapColliders: (name: string, boxes: readonly unknown[]) => void;
26
+ setGround: (ground: Uint8Array) => boolean;
27
+ /** v4 (AP19) */
28
+ restartGameplay: (gameplay: unknown) => Promise<DevRestartLike>;
23
29
  }
24
30
 
31
+ /** What engine's soft restart did (its `DevRestart`): the server's world restart and the page's quest views, in ms. */
32
+ export interface DevRestartLike { readonly ok: boolean; readonly serverMs: number; readonly questsMs: number | null; readonly reason?: string }
33
+
25
34
  export interface SocketLike { onmessage: ((event: { data: unknown }) => void) | null; onclose: (() => void) | null; close: () => void }
26
35
 
27
36
  export interface WatchPageEnv {
@@ -34,10 +43,14 @@ export interface WatchPageEnv {
34
43
  readonly frame: (run: () => void) => void;
35
44
  readonly wait: (ms: number, run: () => void) => void;
36
45
  readonly reload: () => void;
46
+ /** AP17: ask the watch server for a new shell (a look the page's hook refused live); the page reloads into it */
47
+ readonly reshell: () => void;
37
48
  readonly now: () => number;
38
49
  readonly log: (message: string) => void;
39
50
  /** the shell this page booted from (`window.__wsShell`, written into the page per shell); a state for another reloads */
40
51
  readonly shell?: () => number | null;
52
+ /** AP19, AP20: the page's watch panel: what the last revision did, and the last full build's budget table */
53
+ readonly overlay?: (lines: readonly string[]) => void;
41
54
  }
42
55
 
43
56
  export interface WatchPageReport {
@@ -45,6 +58,8 @@ export interface WatchPageReport {
45
58
  /** the last revision whose parts all landed, and the wall clock (ms) of the first frame after it */
46
59
  framedRevision: number;
47
60
  framedAt: number;
61
+ /** the wall clock (ms) of the last revision's steps: its state received, its parts fetched and decoded, swapped in */
62
+ readonly steps: { seen: number; sent: number; received: number; fetched: number; swapped: number };
48
63
  /** frames since the script started: it only grows, swap or no swap */
49
64
  frames: number;
50
65
  /** the page's own failure: a part the hook refused, a fetch, a message it couldn't read */
@@ -53,9 +68,20 @@ export interface WatchPageReport {
53
68
  serverError: string | null;
54
69
  /** every part swapped in, in order (`name@hash`) */
55
70
  readonly applied: string[];
71
+ /** AP17 to AP19: what the last revision changed on this page, joined with `and` (`look`, `ground`, `gameplay`, `parts`),
72
+ * `nothing`, or `reload` */
73
+ kind: string | null;
74
+ /** AP19: the last soft restart, as engine's hook answered it */
75
+ restart: DevRestartLike | null;
76
+ /** AP20: the last full build the watch server ran, and its budget table */
77
+ build: WatchBuild | null;
56
78
  }
57
79
 
58
80
  interface Held<T> { readonly value: T; users: number }
81
+
82
+ /** The panel's name for each kind of reload a revision ran (the plan's `wildshard watch` table). */
83
+ const RELOADS: Readonly<Record<string, string>> = { look: 'look data live', ground: 'ground and colliders swapped', parts: 'parts swapped', gameplay: 'simulation restarted (player kept)',
84
+ nothing: 'nothing changed', reload: 'full page reload' };
59
85
  interface LivePart { readonly hash: string; readonly scope: Scope }
60
86
 
61
87
  /** How long the script waits for the engine to boot and install its hook. */
@@ -63,15 +89,22 @@ const HOOK_WAIT_MS = 180_000;
63
89
 
64
90
  export function startWatchPage(env: WatchPageEnv): { readonly report: WatchPageReport; readonly stop: () => void } {
65
91
  const scope = new Scope('watch.page');
66
- const report: WatchPageReport = { revision: 0, framedRevision: 0, framedAt: 0, frames: 0, error: null, serverError: null, applied: [] };
92
+ const report: WatchPageReport = { revision: 0, framedRevision: 0, framedAt: 0, frames: 0, error: null, serverError: null, applied: [], kind: null, restart: null, build: null, steps: { seen: 0, sent: 0, received: 0, fetched: 0, swapped: 0 } };
67
93
  const parts = new Map<string, LivePart>(), geometries = new Map<string, Held<ReturnType<typeof decodeGeometry>>>(), textures = new Map<string, Held<Uint8Array>>();
68
- let hook: DevHookLike | null = null, shell: number | null = env.shell?.() ?? null, look: string | null = null, socket: SocketLike | null = null;
94
+ let hook: DevHookLike | null = null, shell: number | null = env.shell?.() ?? null, look: string | null = null, ground: string | null = null, gameplay: string | null = null, socket: SocketLike | null = null;
69
95
  let pendingFrame: number | null = null;
70
96
 
97
+ /** The watch panel: which reload the last revision ran and its time, then the build's table. */
98
+ const show = (): void => {
99
+ const took = report.framedAt > 0 && report.steps.seen > 0 ? ` in ${Math.max(0, report.framedAt - report.steps.seen)} ms` : '';
100
+ const named = (report.kind ?? 'starting').split(' and ').map((kind) => RELOADS[kind] ?? kind).join(' and ');
101
+ env.overlay?.([`watch: revision ${report.revision}, ${named}${report.kind === null || report.kind === 'nothing' || report.kind === 'reload' ? '' : took}`,
102
+ ...report.serverError === null ? [] : [`refused: ${report.serverError}`], ...report.build === null ? ['full build: once edits rest 5 s'] : budgetLines(report.build)]);
103
+ };
71
104
  const tick = (): void => {
72
105
  if (scope.disposed) return;
73
106
  report.frames++;
74
- if (pendingFrame !== null) { report.framedRevision = pendingFrame; report.framedAt = env.now(); pendingFrame = null; }
107
+ if (pendingFrame !== null) { report.framedRevision = pendingFrame; report.framedAt = env.now(); pendingFrame = null; show(); }
75
108
  env.frame(tick);
76
109
  };
77
110
  env.frame(tick);
@@ -91,28 +124,19 @@ export function startWatchPage(env: WatchPageEnv): { readonly report: WatchPageR
91
124
  return held.value;
92
125
  };
93
126
 
94
- const sync = async (state: WatchState, first: boolean): Promise<void> => {
95
- const live = hook;
96
- if (live === null) return;
97
- report.serverError = state.error;
98
- if (state.error !== null) env.log(`wildshard watch: ${state.error}`);
99
- if (state.look.hash !== look) {
100
- if (!live.setLook({ keys: state.look.keys })) {
101
- if (!first) { env.log('wildshard watch: this look change needs a reload'); env.reload(); return; }
102
- fail('the page\'s look can\'t take day keys live: look edits will reload the page');
103
- }
104
- look = state.look.hash;
105
- }
106
- // fetch and decode every changed part before any swaps in
107
- const changed = state.parts.filter((part) => parts.get(part.name)?.hash !== part.hash);
108
- const fetched = await Promise.all(changed.map(async ({ name }) => await (await get(`part/${encodeURIComponent(name)}`)).json() as WatchPart));
109
- const fresh = new Map<string, Promise<void>>();
110
- for (const part of fetched) {
111
- for (const key of part.geometries) if (!geometries.has(key) && !fresh.has(`g:${key}`)) fresh.set(`g:${key}`, (async () => { const bytes = await (await get(`geometry/${key}`)).arrayBuffer(); geometries.set(key, { value: decodeGeometry(key, bytes), users: 0 }); })());
112
- for (const t of part.textures) if (!textures.has(t.key) && !fresh.has(`t:${t.key}`)) fresh.set(`t:${t.key}`, (async () => { const bytes = await (await get(`texture/${t.key}`)).arrayBuffer(); textures.set(t.key, { value: new Uint8Array(bytes), users: 0 }); })());
113
- }
114
- await Promise.all(fresh.values());
115
- if (scope.disposed) return;
127
+ /**
128
+ * Ask the server for a new shell, which the page reloads into: once per revision, and never for a revision that carries the
129
+ * server's refusal (its shell build of that source failed too, so asking again would rebuild it in a loop).
130
+ */
131
+ let asked: string | null = null;
132
+ const reshell = (state: WatchState, why: string): void => {
133
+ report.kind = 'reload';
134
+ const key = `${state.shell}/${state.revision}`;
135
+ if (state.error !== null || asked === key) { env.log(`wildshard watch: ${why}; waiting for an edit the shell build takes`); return; }
136
+ asked = key; env.log(`wildshard watch: ${why}; reloading`); env.reshell();
137
+ };
138
+ /** Draw each fetched part through the hook; false when any failed (the hook keeps that part's old copy drawn). */
139
+ const place = (fetched: readonly WatchPart[], live: DevHookLike): boolean => {
116
140
  let landed = true;
117
141
  for (const part of fetched) {
118
142
  const owner = scope.child(`watch.part.${part.name}@${part.hash}`), old = parts.get(part.name);
@@ -134,14 +158,72 @@ export function startWatchPage(env: WatchPageEnv): { readonly report: WatchPageR
134
158
  try { live.swapColliders(part.name, part.colliders); }
135
159
  catch (cause) { landed = false; fail(`part ${part.name} colliders: ${cause instanceof Error ? cause.message : String(cause)}`); }
136
160
  }
161
+ return landed;
162
+ };
163
+ const sync = async (state: WatchState, first: boolean): Promise<void> => {
164
+ const live = hook;
165
+ if (live === null) return;
166
+ report.serverError = state.error;
167
+ if (state.error !== null) env.log(`wildshard watch: ${state.error}`);
168
+ const lookChanged = state.look.hash !== look;
169
+ if (lookChanged) {
170
+ if (!live.setLook({ keys: state.look.keys, look: state.look.look })) {
171
+ if (!first) { reshell(state, 'this look change needs a new shell'); return; }
172
+ fail('the page\'s look can\'t take this look live: look edits will reload the page');
173
+ }
174
+ look = state.look.hash;
175
+ }
176
+ // AP18: the ground the page holds is its shell's until one is set live
177
+ const groundChanged = state.ground.hash !== (ground ?? state.ground.shell);
178
+ if (groundChanged) {
179
+ const bytes = new Uint8Array(await (await get(`ground/${encodeURIComponent(state.ground.hash)}`)).arrayBuffer());
180
+ if (scope.disposed) return;
181
+ if (!live.setGround(bytes)) { reshell(state, 'the page can\'t take this ground live'); return; }
182
+ ground = state.ground.hash;
183
+ }
184
+ // AP19: a quest, encounter, spawn or script change restarts the in-page simulation (the player keeps their place)
185
+ const gameplayChanged = state.gameplay.hash !== (gameplay ?? state.gameplay.shell);
186
+ if (gameplayChanged) {
187
+ const rows = await (await get(`gameplay/${encodeURIComponent(state.gameplay.hash)}`)).json();
188
+ if (scope.disposed) return;
189
+ const done = await live.restartGameplay(rows);
190
+ report.restart = done;
191
+ if (scope.disposed) return;
192
+ if (!done.ok) { reshell(state, `the page can't restart its simulation on this revision${done.reason === undefined ? '' : ` (${done.reason})`}`); return; }
193
+ gameplay = state.gameplay.hash;
194
+ }
195
+ // fetch and decode every changed part before any swaps in
196
+ const changed = state.parts.filter((part) => parts.get(part.name)?.hash !== part.hash);
197
+ const fetched = await Promise.all(changed.map(async ({ name }) => await (await get(`part/${encodeURIComponent(name)}`)).json() as WatchPart));
198
+ const fresh = new Map<string, Promise<void>>();
199
+ for (const part of fetched) {
200
+ for (const key of part.geometries) if (!geometries.has(key) && !fresh.has(`g:${key}`)) fresh.set(`g:${key}`, (async () => { const bytes = await (await get(`geometry/${key}`)).arrayBuffer(); geometries.set(key, { value: decodeGeometry(key, bytes), users: 0 }); })());
201
+ for (const t of part.textures) if (!textures.has(t.key) && !fresh.has(`t:${t.key}`)) fresh.set(`t:${t.key}`, (async () => { const bytes = await (await get(`texture/${t.key}`)).arrayBuffer(); textures.set(t.key, { value: new Uint8Array(bytes), users: 0 }); })());
202
+ }
203
+ await Promise.all(fresh.values());
204
+ if (scope.disposed) return;
205
+ report.steps.fetched = env.now();
206
+ // the revision holds every asset it fetched until all its parts are placed: a part that fails lets its own holds go,
207
+ // and an asset it shares with a later part must not leave the cache on that (it would be "not fetched" there)
208
+ const revision = scope.child(`watch.revision.${state.revision}`);
209
+ for (const part of fetched) {
210
+ for (const key of part.geometries) if (geometries.has(key)) hold(geometries, key, revision);
211
+ for (const t of part.textures) if (textures.has(t.key)) hold(textures, t.key, revision);
212
+ }
213
+ let landed: boolean;
214
+ try { landed = place(fetched, live); } finally { revision.dispose(); }
137
215
  const names = new Set(state.parts.map((part) => part.name));
216
+ let removed = 0;
138
217
  for (const [name, part] of parts) {
139
218
  if (names.has(name)) continue;
219
+ removed++;
140
220
  live.removePart(name); live.swapColliders(name, []);
141
221
  parts.delete(name); part.scope.dispose();
142
222
  }
223
+ report.kind = [lookChanged ? 'look' : '', groundChanged ? 'ground' : '', gameplayChanged ? 'gameplay' : '', fetched.length > 0 || removed > 0 ? 'parts' : ''].filter((what) => what !== '').join(' and ') || 'nothing';
143
224
  report.revision = state.revision;
144
225
  // the timing counts a revision only once all its parts landed
226
+ report.steps.swapped = env.now();
145
227
  if (landed) pendingFrame = state.revision;
146
228
  };
147
229
 
@@ -156,12 +238,17 @@ export function startWatchPage(env: WatchPageEnv): { readonly report: WatchPageR
156
238
  running = false;
157
239
  };
158
240
  const receive = (data: unknown): void => {
241
+ report.steps.received = env.now();
159
242
  let state: WatchState;
160
243
  try { state = JSON.parse(String(data)) as WatchState; }
161
244
  catch { fail('the watch server sent a message this page can\'t read'); return; }
245
+ // AP20: a full build of a revision this page already holds changes only the panel
246
+ if (state.revision === report.revision && report.revision > 0 && state.shell === shell) { report.build = state.build; show(); return; }
247
+ report.build = state.build;
162
248
  if (state.wire !== WATCH_WIRE) { env.log(`wildshard watch: the server speaks wire ${state.wire}, this page ${WATCH_WIRE}; reloading`); env.reload(); return; }
163
- if (shell !== null && state.shell !== shell) { env.log('wildshard watch: the ground, spawn or grade changed; reloading'); env.reload(); return; }
249
+ if (shell !== null && state.shell !== shell) { env.log('wildshard watch: the spawn or a fixed look field changed; reloading'); env.reload(); return; }
164
250
  shell = state.shell; next = state;
251
+ report.steps.seen = state.seenAt; report.steps.sent = state.sentAt;
165
252
  if (!running) void drain();
166
253
  };
167
254
  const connect = (): void => {
@@ -1,23 +1,59 @@
1
1
  import { Scope } from '@wildshard/engine/app/scope';
2
2
  import { installBrowserScopeEnvironment } from '@wildshard/engine/app/view/scopeEnvironment';
3
3
  import { socketOf, startWatchPage, type DevHookLike, type WatchPageReport } from './page';
4
+ import { WATCH_RESHELL } from './protocol';
4
5
 
5
6
  // SHARD-SOURCE AP5: the browser entry `wildshard watch` bundles and injects into the page it serves (watch.ts `pageScript`).
6
7
  // It is its own bundle beside the engine's, so it installs its own copy of the browser scope environment (frames, timers).
7
8
  declare global { interface Window { __wildshardDevHook?: DevHookLike; __wsDevScene?: WatchPageReport; __wsShell?: number } }
8
9
 
9
10
  installBrowserScopeEnvironment();
11
+ /** AP19, AP20: the watch panel, top left over the game (the vitals sit bottom left): what the last edit did, and the last full build's budget table. */
12
+ let held: HTMLElement | null = null;
13
+ const panel = (): HTMLElement => {
14
+ if (held !== null) return held;
15
+ const node = document.createElement('pre');
16
+ node.id = 'wildshard-watch';
17
+ Object.assign(node.style, { position: 'fixed', left: '8px', top: '8px', zIndex: '2147483000', margin: '0', padding: '6px 8px', maxWidth: '46ch',
18
+ font: '11px/1.35 ui-monospace, Menlo, monospace', color: '#e8f0e0', background: 'rgba(12, 16, 12, 0.72)', borderRadius: '4px', pointerEvents: 'none', whiteSpace: 'pre-wrap' });
19
+ // oxlint-disable-next-line wildshard/no-raw-hud, wildshard/no-global-listener-patch -- sharddev's own dev panel beside the game, not a game HUD; the page lives as long as it does
20
+ document.body.append(node);
21
+ held = node;
22
+ return node;
23
+ };
24
+ /**
25
+ * Engine 0.1.21 and earlier give every `game.watchFrames` observer the one system id `harness.walk`. The dev hook's ground
26
+ * sweep takes it at boot, so the first part with a lamp or water threw "Duplicate system id" and never drew. Until the sdk
27
+ * pins an engine whose observers carry their own ids, the page gives each later observer its own (engine-quickfix fix,
28
+ * SHARD-SOURCE AP16). The engine's fields are read loosely: a client without them is left as it is.
29
+ */
30
+ interface ObserverGame { watchFrames?: unknown; levelScope?: { child?: unknown }; app?: { addSystem?: unknown } }
31
+ let observers = 0;
32
+ const ownObserverIds = (): void => {
33
+ const game = (window as unknown as { __wildshard?: { world?: { game?: ObserverGame } } }).__wildshard?.world?.game;
34
+ if (game === undefined || typeof game.levelScope?.child !== 'function' || typeof game.app?.addSystem !== 'function') return;
35
+ const levelScope = game.levelScope as { child: (name: string) => Scope }, app = game.app as { addSystem: (spec: { id: string; phase: 'update'; run: (dt: number) => void; core: boolean }, scope: Scope) => void };
36
+ game.watchFrames = (run: (dt: number) => void): (() => void) => {
37
+ const owner = levelScope.child('observer');
38
+ app.addSystem({ id: `harness.walk.watch.${String(observers++)}`, phase: 'update', run, core: false }, owner);
39
+ return () => { owner.dispose(); };
40
+ };
41
+ };
42
+ const entry = location.href;
10
43
  const timers = new Scope('watch.entry');
11
44
  const page = startWatchPage({
12
45
  origin: location.origin,
13
- hook: () => window.__wildshardDevHook,
46
+ hook: () => { const found = window.__wildshardDevHook; if (found !== undefined) ownObserverIds(); return found; },
14
47
  fetch: (url) => fetch(url, { cache: 'no-store' }),
15
48
  socket: (url) => socketOf(new WebSocket(url)),
16
49
  frame: (run) => { timers.raf(run); },
17
50
  wait: (ms, run) => { timers.timeout(ms, run); },
18
- reload: () => { location.reload(); },
51
+ // the address the page opened at (`?skipintro`): the engine rewrites it once it boots, and a plain reload would land on the title
52
+ reload: () => { location.replace(entry); },
53
+ reshell: () => { void fetch(`${location.origin}${WATCH_RESHELL}`, { method: 'POST' }).catch((cause: unknown) => { console.error('wildshard watch: reshell', cause); }); },
19
54
  now: () => Date.now(),
20
55
  log: (message) => { console.error(message); },
21
56
  shell: () => window.__wsShell ?? null,
57
+ overlay: (lines) => { panel().textContent = lines.join('\n'); },
22
58
  });
23
59
  window.__wsDevScene = page.report;
@@ -0,0 +1,22 @@
1
+ {
2
+ "note": "AP20: each camera's measured watch-against-build drift; parity.mjs --rebase writes it",
3
+ "source": "src/shards/authoring-slice",
4
+ "cameras": {
5
+ "hut-front": {
6
+ "mean": 2.313,
7
+ "share": 0.03784
8
+ },
9
+ "door-lamp": {
10
+ "mean": 4.26,
11
+ "share": 0.07746
12
+ },
13
+ "hut-back": {
14
+ "mean": 0.561,
15
+ "share": 0.00951
16
+ },
17
+ "pond": {
18
+ "mean": 3.499,
19
+ "share": 0.0484
20
+ }
21
+ }
22
+ }
@@ -0,0 +1,168 @@
1
+ // SHARD-SOURCE AP20: watch equals build. One scene source through both back ends, shot from the same fixed cameras:
2
+ //
3
+ // live `wildshard watch <source>`: the shell boots, then the page script draws every part through engine's dev hook
4
+ // build `wildshard dev <source>`: the full `wildshard build` (baked GLB tiles, the shardfile's look and terrain)
5
+ //
6
+ // Each camera's two frames are compared: the mean absolute difference per channel (out of 255) and the share of pixels off
7
+ // by more than 24 in any channel. The two back ends still differ where the shardfile back end lowers on purpose (a glowing
8
+ // material is the emissive family with no base colour, AP10's sorted transparency, AP11's billboards, AP28's lamps), so the
9
+ // guard is a ratchet: `parity-baseline.json` holds each camera's measured drift, and a camera over it by `MEAN` or `SHARE`
10
+ // is red. A fix that lowers the drift lowers the baseline (`--rebase`); nothing raises it unseen.
11
+ //
12
+ // node src/sharddev/watch/parity.mjs [--source <dir>] [--out <dir>] one comparison; exit 1 when red
13
+ // node src/sharddev/watch/parity.mjs --check sharddev's pre-push: the clean run must be green,
14
+ // and the live page with its roof colour halved (a
15
+ // planted material difference) must be red
16
+ // node src/sharddev/watch/parity.mjs --rebase write this run's drift as the baseline
17
+ //
18
+ // The page client is `$WILDSHARD_DEV_CLIENT` or the engine pin's devserver client (`wildshard dev`'s own). `--check` passes
19
+ // with one line saying why when that client has no dev hook this sdk drives (an engine pin from before hook v3). The servers
20
+ // and the browser are this script's: it ends them before it exits. Headless and muted.
21
+ // oxlint-disable-next-line import/no-nodejs-modules -- a node script: it runs `wildshard watch` and `wildshard dev` as children.
22
+ import { spawn } from 'node:child_process';
23
+ // oxlint-disable-next-line import/no-nodejs-modules -- it reads its baseline and writes the frames it shot.
24
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
25
+ // oxlint-disable-next-line import/no-nodejs-modules -- paths from the repo root.
26
+ import { join, resolve } from 'node:path';
27
+ // oxlint-disable-next-line import/no-nodejs-modules -- its flags.
28
+ import { parseArgs } from 'node:util';
29
+ import { chromium } from 'playwright';
30
+ import sharp from 'sharp';
31
+
32
+ const ROOT = resolve(import.meta.dirname, '../../..');
33
+ const { values } = parseArgs({ options: { source: { type: 'string' }, out: { type: 'string' }, check: { type: 'boolean' }, rebase: { type: 'boolean' } } });
34
+ const SOURCE = resolve(values.source ?? join(ROOT, 'src/shards/authoring-slice'));
35
+ const BASELINE = join(import.meta.dirname, 'parity-baseline.json');
36
+ // The slice's own cameras (Mossgate cleanroom scripts/cameras.json): [id, x, z, yaw, pitch]
37
+ const CAMERAS = [['hut-front', -3.9, -5.6, 0.03, -0.04], ['door-lamp', -4.6, -7.8, 0.03, 0.05], ['hut-back', -3.9, -10.4, 3.4, -0.05], ['pond', -10.4, 0.3, 1.571, -0.08]];
38
+ /** The eye's height (m): the cameras' 1.68 m over the slice's ground, which is flat at 0 by every camera. */
39
+ const EYE = 1.68;
40
+ /** Red over the baseline by these, at any camera. Two clean runs differ by under 0.002/255; the planted roof adds over 1/255. */
41
+ const MEAN = 0.25, SHARE = 0.005, OFF = 24;
42
+
43
+ /** Start `wildshard <command> <source> 0` and resolve its page URL; `stop` kills the child. */
44
+ function serve(command) {
45
+ const child = spawn(process.execPath, [join(ROOT, 'bin/wildshard.mjs'), command, SOURCE, '0'], { cwd: ROOT, stdio: ['ignore', 'pipe', 'pipe'] });
46
+ let log = '';
47
+ const url = new Promise((_resolve, _reject) => {
48
+ const read = (chunk) => {
49
+ log += String(chunk);
50
+ const found = /wildshard (?:watch|dev): (http:\/\/127\.0\.0\.1:\d+\/)/u.exec(log);
51
+ if (found !== null) _resolve(found[1]);
52
+ };
53
+ child.stdout.on('data', read); child.stderr.on('data', read);
54
+ child.on('exit', (code) => { _reject(new Error(`wildshard ${command} ended (${code}) before it served:\n${log.slice(-2000)}`)); });
55
+ });
56
+ return { url, stop: () => { if (child.exitCode === null) child.kill('SIGTERM'); } };
57
+ }
58
+
59
+ /** Each camera's frame, once the page stands still there; then, for each of `after`, the same after it runs in the page. */
60
+ async function shoot(browser, url, live, after = []) {
61
+ const page = await browser.newPage({ viewport: { width: 960, height: 540 } });
62
+ try {
63
+ await page.addInitScript({ content: 'window.__wildshardHarness=Object.assign(window.__wildshardHarness??{},{seed:357});' });
64
+ await page.goto(`${url}?skipintro`);
65
+ await page.waitForFunction((watched) => window.__wildshard?.world?.player !== undefined && (!watched || (window.__wsDevScene?.framedRevision ?? 0) > 0),
66
+ live, { timeout: 180_000, polling: 500 });
67
+ await page.evaluate(() => {
68
+ const w = window.__wildshard.world, camera = w.game.camera;
69
+ if (w.animals) w.animals.calm = true;
70
+ // the camera leaves the player (whose body stands where colliders put it, which this test does not compare): each
71
+ // frame it is set to the shot's eye, one field of view, no viewmodel
72
+ w.freeCamera = true;
73
+ w.game.onLate(() => {
74
+ const eye = window.__ap20Eye;
75
+ for (const child of camera.children) child.visible = false;
76
+ if (Math.abs(camera.fov - 72) > 0.01) { camera.fov = 72; camera.updateProjectionMatrix(); }
77
+ if (eye !== undefined) { camera.position.set(eye[0], eye[1], eye[2]); camera.rotation.set(eye[4], eye[3], 0, 'YXZ'); camera.updateMatrixWorld(true); }
78
+ }, 'ap20.camera');
79
+ });
80
+ // the watch panel's timings and build table change from run to run: they are not the scene
81
+ await page.addStyleTag({ content: '#wildshard-watch { display: none !important; }' });
82
+ const sets = [];
83
+ for (const change of [null, ...after]) {
84
+ if (change !== null) await page.evaluate(change);
85
+ const frames = [];
86
+ for (const [id, x, z, yaw, pitch] of CAMERAS) {
87
+ await page.evaluate((eye) => { window.__ap20Eye = eye; }, [x, EYE, z, yaw, pitch]);
88
+ await page.waitForTimeout(2500);
89
+ frames.push({ id, png: await page.screenshot() });
90
+ }
91
+ sets.push(frames);
92
+ }
93
+ return sets;
94
+ } finally { await page.close(); }
95
+ }
96
+
97
+ /** The planted difference: the live page's roof colour halved (page code, passed as text). */
98
+ const PLANT = `window.__wildshard.world.game.rootScene.getObjectByName('devScene')?.traverse((o) => { if (o.material?.name === 'roof') o.material.color.multiplyScalar(0.5); })`;
99
+
100
+ /** Two PNG frames compared, pixel by pixel. */
101
+ async function compare(a, b) {
102
+ const [p, q] = await Promise.all([a, b].map(async (png) => (await sharp(png).removeAlpha().raw().toBuffer())));
103
+ let sum = 0, offPixels = 0;
104
+ for (let i = 0; i < p.length; i += 3) {
105
+ let worst = 0;
106
+ for (let k = 0; k < 3; k++) { const d = Math.abs(p[i + k] - q[i + k]); sum += d; if (d > worst) worst = d; }
107
+ if (worst > OFF) offPixels++;
108
+ }
109
+ return { mean: Number((sum / p.length).toFixed(3)), share: Number((offPixels / (p.length / 3)).toFixed(5)) };
110
+ }
111
+
112
+ /** Both back ends, every camera: the clean comparison, and with `plant` the planted one too. */
113
+ async function run(plant, out) {
114
+ const live = serve('watch'), built = serve('dev');
115
+ const browser = await chromium.launch({ headless: true, args: ['--use-mock-keychain', '--password-store=basic', '--mute-audio', '--use-angle=metal', '--ignore-gpu-blocklist'] });
116
+ try {
117
+ const [liveUrl, builtUrl] = await Promise.all([live.url, built.url]);
118
+ const watched = await shoot(browser, liveUrl, true, plant ? [PLANT] : []), [baked] = await shoot(browser, builtUrl, false);
119
+ const baseline = readBaseline(), results = [];
120
+ for (const [n, frames] of watched.entries()) {
121
+ const rows = [];
122
+ for (const [i, frame] of frames.entries()) {
123
+ const score = await compare(frame.png, baked[i].png), base = baseline[frame.id] ?? { mean: 0, share: 0 };
124
+ rows.push({ id: frame.id, ...score, red: score.mean > base.mean + MEAN || score.share > base.share + SHARE });
125
+ if (out !== undefined) {
126
+ writeFileSync(join(out, `${n > 0 ? 'planted-' : ''}${frame.id}-watch.png`), frame.png);
127
+ if (n === 0) writeFileSync(join(out, `${frame.id}-build.png`), baked[i].png);
128
+ }
129
+ }
130
+ results.push({ rows, red: rows.some((row) => row.red) });
131
+ }
132
+ return results;
133
+ } finally { await browser.close(); live.stop(); built.stop(); }
134
+ }
135
+
136
+ function readBaseline() {
137
+ try { return JSON.parse(readFileSync(BASELINE, 'utf8')).cameras ?? {}; } catch { return {}; }
138
+ }
139
+
140
+ const line = (label, result) => `${label}: ${result.red ? 'RED' : 'green'} ${result.rows.map((row) => `${row.id} ${row.mean}/255 ${(row.share * 100).toFixed(2)}%${row.red ? ' (over its baseline)' : ''}`).join(', ')}`;
141
+ const out = values.out === undefined ? undefined : resolve(values.out);
142
+ if (out !== undefined) mkdirSync(out, { recursive: true });
143
+
144
+ async function main() {
145
+ let results;
146
+ try { results = await run(values.check === true, out); }
147
+ catch (cause) {
148
+ // an engine pin from before this sdk's dev hook serves no page watch can drive, and a machine with no client (offline, no
149
+ // release asset) or no browser has nothing to compare: the check says so and passes. Only a comparison goes red.
150
+ const message = cause instanceof Error ? cause.message : String(cause);
151
+ if (values.check !== true || !/dev hook|dev client|engine release .* has no|fetch failed|browserType\.launch/u.test(message)) throw cause;
152
+ console.info(`watch equals build: skipped, ${/(this engine client[^\n]*|the page's dev hook[^\n]*)/u.exec(message)?.[1] ?? message.split('\n')[0]}`);
153
+ return;
154
+ }
155
+ const [clean, planted] = results;
156
+ console.info(line('watch equals build', clean));
157
+ if (out !== undefined) writeFileSync(join(out, 'parity.json'), `${JSON.stringify(results, null, 2)}\n`);
158
+ if (values.rebase === true) {
159
+ writeFileSync(BASELINE, `${JSON.stringify({ note: 'AP20: each camera\'s measured watch-against-build drift; parity.mjs --rebase writes it', source: 'src/shards/authoring-slice',
160
+ cameras: Object.fromEntries(clean.rows.map((row) => [row.id, { mean: row.mean, share: row.share }])) }, null, 2)}\n`);
161
+ console.info(`wrote ${BASELINE}`);
162
+ } else if (clean.red) { console.error('watch equals build: the two back ends drifted past the baseline (parity.mjs --out <dir> writes the frames)'); process.exitCode = 1; }
163
+ if (planted !== undefined) {
164
+ console.info(line('planted roof difference', planted));
165
+ if (!planted.red) { console.error('watch equals build: a planted material difference went unseen'); process.exitCode = 1; }
166
+ }
167
+ }
168
+ await main();