@wildshard/sdk 0.2.13 → 0.3.1

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 (88) hide show
  1. package/GUIDE.md +26 -13
  2. package/bin/wildshard.mjs +2 -1
  3. package/docs/api/EXPORT-TIERS.md +16 -4
  4. package/lint/export-tiers.json +12 -0
  5. package/lint/host-callbacks.mjs +1 -1
  6. package/package.json +22 -6
  7. package/scripts/bake/template-skins.mjs +6 -3
  8. package/scripts/bake/template-warden.mjs +25 -0
  9. package/scripts/build-shardfiles.mjs +7 -2
  10. package/scripts/export-ci21-guests.mjs +89 -0
  11. package/scripts/prepare-product.mjs +2 -2
  12. package/scripts/scratch-sweep.mjs +182 -0
  13. package/scripts/wildshard.mjs +1 -1
  14. package/skills/wildshard-mockup-to-model/SKILL.md +5 -3
  15. package/skills/wildshard-upgrade/SKILL.md +4 -4
  16. package/src/cli/help.ts +9 -5
  17. package/src/cli/upload/validate.ts +7 -5
  18. package/src/sharddev/as/prelude.ts +67 -0
  19. package/src/sharddev/assets.ts +1 -1
  20. package/src/sharddev/authorLint.ts +45 -0
  21. package/src/sharddev/bake/compactGlb.ts +1 -1
  22. package/src/sharddev/bake/compileScript.ts +6 -0
  23. package/src/sharddev/bake/glbCompression.ts +1 -1
  24. package/src/sharddev/bake/gltfSource.ts +1 -1
  25. package/src/sharddev/bake/placeholders.ts +1 -1
  26. package/src/sharddev/bake/terrain.ts +12 -3
  27. package/src/sharddev/blobBytes.ts +1 -1
  28. package/src/sharddev/blobs.ts +2 -2
  29. package/src/sharddev/checkProject.ts +7 -18
  30. package/src/sharddev/cli.ts +17 -4
  31. package/src/sharddev/engineMusic.ts +23 -0
  32. package/src/sharddev/formatJsonSchema.ts +1 -1
  33. package/src/sharddev/materialGraphFiles.ts +1 -1
  34. package/src/sharddev/materials.ts +7 -3
  35. package/src/sharddev/newProject.ts +18 -10
  36. package/src/sharddev/outputProduct.ts +2 -2
  37. package/src/sharddev/productOutput.ts +2 -2
  38. package/src/sharddev/project.ts +6 -1
  39. package/src/sharddev/projectMap.ts +1 -1
  40. package/src/sharddev/refusals.ts +5 -3
  41. package/src/sharddev/reportCard.ts +1 -1
  42. package/src/sharddev/scene/author.ts +184 -0
  43. package/src/sharddev/scene/canvas.ts +212 -0
  44. package/src/sharddev/scene/description.ts +223 -0
  45. package/src/sharddev/scene/hash.ts +23 -0
  46. package/src/sharddev/scene/lower.ts +341 -0
  47. package/src/sharddev/scene/shard.ts +41 -0
  48. package/src/sharddev/scene/shardfile.ts +621 -0
  49. package/src/sharddev/threeGate.mjs +14 -0
  50. package/src/sharddev/threePin.mjs +40 -0
  51. package/src/sharddev/watch/page.ts +284 -0
  52. package/src/sharddev/watch/pageEntry.ts +59 -0
  53. package/src/sharddev/watch/parity-baseline.json +22 -0
  54. package/src/sharddev/watch/parity.mjs +168 -0
  55. package/src/sharddev/watch/proof.mjs +199 -0
  56. package/src/sharddev/watch/protocol.ts +166 -0
  57. package/src/sharddev/watch/socket.ts +57 -0
  58. package/src/sharddev/watch/watch.ts +373 -0
  59. package/src/shards/_template/assets/3058c100bc477fd6fe8268f33b53756b8a2556e7e41c58b2216c703ca7b042c6 +1 -0
  60. package/src/shards/_template/assets/8a0440f392737a31cf0926a3c7dc011c320144972882945a5462c893e817d94a +0 -0
  61. package/src/shards/_template/behaviour/door.as +16 -26
  62. package/src/shards/_template/card/landscape.jpg +0 -0
  63. package/src/shards/_template/card/portrait.jpg +0 -0
  64. package/src/shards/_template/card/thumb.jpg +0 -0
  65. package/src/shards/_template/data/clientScripts.json +43 -43
  66. package/src/shards/_template/data/creatures.json +2 -2
  67. package/src/shards/_template/data/look.json +141 -13
  68. package/src/shards/_template/data/rows.json +20 -2
  69. package/src/shards/_template/data/skins.json +32 -0
  70. package/src/shards/_template/data/water.json +18 -0
  71. package/src/shards/_template/generators/product.ts +5 -1
  72. package/src/shards/_template/generators/warden.ts +273 -0
  73. package/src/shards/_template/generators/world.ts +52 -21
  74. package/src/shards/_template/hero.json +6 -6
  75. package/src/shards/authoring-slice/generators/shard.ts +14 -0
  76. package/src/shards/authoring-slice/generators/sky.ts +64 -0
  77. package/src/shards/authoring-slice/generators/template-sky.ts +27 -0
  78. package/src/shards/authoring-slice/generators/textures.ts +232 -0
  79. package/src/shards/authoring-slice/generators/world.ts +518 -0
  80. package/src/shards/authoring-slice/shard.config.ts +7 -0
  81. package/src/shards/mossgate/generators/shard.ts +6 -0
  82. package/src/shards/mossgate/generators/sky.ts +64 -0
  83. package/src/shards/mossgate/generators/textures.ts +249 -0
  84. package/src/shards/mossgate/generators/world.ts +998 -0
  85. package/src/shards/mossgate/shard.config.ts +7 -0
  86. package/scripts/shard-output-report.d.mts +0 -9
  87. package/scripts/shard-output-report.mjs +0 -85
  88. package/scripts/shard-platform-cli.mjs +0 -93
@@ -0,0 +1,14 @@
1
+ // SA8: the first import of bin/wildshard.mjs. It refuses a run whose `three` is not the sdk's pin (threePin.mjs), except help and --version.
2
+ import { threeRefusal } from './threePin.mjs';
3
+
4
+ // Help and --version print without it: the refusal sends authors to --version for the pinned chain.
5
+ const args = process.argv.slice(2);
6
+ const passes = args[0] === 'help' || args[0] === '--version' || args.some(arg => arg === '--help' || arg === '-h');
7
+ if (!passes) {
8
+ const refusal = threeRefusal(new URL('../../package.json', import.meta.url));
9
+ if (refusal !== undefined) {
10
+ process.stderr.write(`wildshard: ${refusal}\n`);
11
+ // oxlint-disable-next-line unicorn/no-process-exit -- Stop before any other module loads; a throw would print a stack to authors.
12
+ process.exit(1);
13
+ }
14
+ }
@@ -0,0 +1,40 @@
1
+ // SHARD-AUTHORING SA8 (J317): `three` is a peer of the sdk, pinned exact. Every `wildshard` (and `sharddev`) run checks,
2
+ // before anything else loads (threeGate.mjs), that the `three` this sdk would import is the version it pins, and refuses
3
+ // naming both. Engine still lists its own `three` until it takes it as a peer too, so the copy engine resolves is checked
4
+ // as well: two copies at different versions would otherwise pass. Plain JS with Node built-ins only: bin/wildshard.mjs
5
+ // imports it first, ahead of the type-stripping hook.
6
+ // oxlint-disable-next-line import/no-nodejs-modules -- Read the sdk, engine and three package.json files, as Node finds them.
7
+ import { existsSync, readFileSync, realpathSync } from 'node:fs';
8
+ // oxlint-disable-next-line import/no-nodejs-modules -- The node_modules folders Node resolves a package from.
9
+ import { createRequire } from 'node:module';
10
+ // oxlint-disable-next-line import/no-nodejs-modules -- Join a node_modules folder and a package.json.
11
+ import { join } from 'node:path';
12
+ // oxlint-disable-next-line import/no-nodejs-modules -- Resolve from a package.json's real path.
13
+ import { pathToFileURL } from 'node:url';
14
+
15
+ const FIX = (pin) => `fix: pnpm add three@${pin} --save-exact (GUIDE.md#three-version)`;
16
+
17
+ /** The package.json of `name` as Node would find it from the file at `from` (a URL), at its real path, if any. */
18
+ function found(from, name) {
19
+ const folders = createRequire(from).resolve.paths(name) ?? [];
20
+ const file = folders.map(folder => join(folder, name, 'package.json')).find(candidate => existsSync(candidate));
21
+ return file === undefined ? undefined : realpathSync(file);
22
+ }
23
+
24
+ /** The refusal for the `three` an sdk at `sdkPackageUrl` (its package.json's URL) resolves, or that the engine it
25
+ * resolves resolves, or undefined when both are the pinned one. The lookup walks the folders Node's resolver would. */
26
+ export function threeRefusal(sdkPackageUrl) {
27
+ const sdk = JSON.parse(readFileSync(new URL(sdkPackageUrl), 'utf8'));
28
+ const pin = sdk.peerDependencies?.three;
29
+ if (typeof pin !== 'string') return undefined;
30
+ const name = `${sdk.name ?? '@wildshard/sdk'} ${sdk.version ?? ''}`.trim();
31
+ const own = found(sdkPackageUrl, 'three');
32
+ if (own === undefined) return `[three-version] three is not installed, and ${name} needs three ${pin} exactly. ${FIX(pin)}`;
33
+ const installed = JSON.parse(readFileSync(own, 'utf8')).version;
34
+ if (installed !== pin) return `[three-version] three ${installed} is installed, but ${name} needs three ${pin} exactly. ${FIX(pin)}`;
35
+ const engine = found(sdkPackageUrl, '@wildshard/engine');
36
+ const engines = engine === undefined ? undefined : found(pathToFileURL(engine), 'three');
37
+ const second = engines === undefined ? undefined : JSON.parse(readFileSync(engines, 'utf8')).version;
38
+ return second === undefined || second === pin ? undefined
39
+ : `[three-version] @wildshard/engine loads three ${second}, but ${name} needs three ${pin} exactly. ${FIX(pin)}`;
40
+ }
@@ -0,0 +1,284 @@
1
+ import { Scope } from '@wildshard/engine/app/scope';
2
+ import { DEV_HOOK_VERSION, DEV_SCENE_PATH, WATCH_SOCKET, WATCH_WIRE, budgetLines, decodeGeometry, type WatchBuild, type WatchPart, type WatchState } from './protocol';
3
+
4
+ /**
5
+ * SHARD-SOURCE AP5 (J347): the page script `wildshard watch` injects into the page it serves (`pageEntry.ts`, bundled at
6
+ * start). It owns the page's half of watch: the socket, the fetches, a cache of decoded geometry and rasters, one scope
7
+ * per part and the swap order, and drives engine's dev hook (`window.__wildshardDevHook`, five calls). Per revision:
8
+ *
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)
13
+ * 2. every changed part is fetched and decoded first, so a slow fetch never leaves half a revision on screen
14
+ * 3. each one swaps in (`addPart` or `replacePart`, then `swapColliders`), and only then its old scope goes
15
+ * 4. parts no longer in the scene go (`removePart`, `swapColliders(name, [])`)
16
+ *
17
+ * `window.__wsDevScene` reports what landed and the first frame after it, for `proof.mjs`'s timing.
18
+ */
19
+ export interface DevHookLike {
20
+ readonly version: number;
21
+ addPart: (name: string, part: unknown) => void;
22
+ replacePart: (name: string, part: unknown) => void;
23
+ removePart: (name: string) => void;
24
+ setLook: (look: { readonly keys: readonly unknown[]; readonly look?: unknown }) => boolean;
25
+ swapColliders: (name: string, boxes: readonly unknown[]) => void;
26
+ setGround: (ground: Uint8Array) => boolean;
27
+ /** v4 (AP19) */
28
+ restartGameplay: (gameplay: unknown) => Promise<DevRestartLike>;
29
+ }
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
+
34
+ export interface SocketLike { onmessage: ((event: { data: unknown }) => void) | null; onclose: (() => void) | null; close: () => void }
35
+
36
+ export interface WatchPageEnv {
37
+ /** the watch server's origin, `http://127.0.0.1:<port>` */
38
+ readonly origin: string;
39
+ readonly hook: () => DevHookLike | undefined;
40
+ readonly fetch: (url: string) => Promise<{ ok: boolean; status: number; json: () => Promise<unknown>; arrayBuffer: () => Promise<ArrayBuffer> }>;
41
+ readonly socket: (url: string) => SocketLike;
42
+ /** the page's next frame (`requestAnimationFrame`) */
43
+ readonly frame: (run: () => void) => void;
44
+ readonly wait: (ms: number, run: () => void) => void;
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;
48
+ readonly now: () => number;
49
+ readonly log: (message: string) => void;
50
+ /** the shell this page booted from (`window.__wsShell`, written into the page per shell); a state for another reloads */
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;
54
+ }
55
+
56
+ export interface WatchPageReport {
57
+ revision: number;
58
+ /** the last revision whose parts all landed, and the wall clock (ms) of the first frame after it */
59
+ framedRevision: number;
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 };
63
+ /** frames since the script started: it only grows, swap or no swap */
64
+ frames: number;
65
+ /** the page's own failure: a part the hook refused, a fetch, a message it couldn't read */
66
+ error: string | null;
67
+ /** the watch server's: the source failed to bundle or describe (the page keeps the last good revision) */
68
+ serverError: string | null;
69
+ /** every part swapped in, in order (`name@hash`) */
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;
78
+ }
79
+
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' };
85
+ interface LivePart { readonly hash: string; readonly scope: Scope }
86
+
87
+ /** How long the script waits for the engine to boot and install its hook. */
88
+ const HOOK_WAIT_MS = 180_000;
89
+
90
+ export function startWatchPage(env: WatchPageEnv): { readonly report: WatchPageReport; readonly stop: () => void } {
91
+ const scope = new Scope('watch.page');
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 } };
93
+ const parts = new Map<string, LivePart>(), geometries = new Map<string, Held<ReturnType<typeof decodeGeometry>>>(), textures = new Map<string, Held<Uint8Array>>();
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;
95
+ let pendingFrame: number | null = null;
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
+ };
104
+ const tick = (): void => {
105
+ if (scope.disposed) return;
106
+ report.frames++;
107
+ if (pendingFrame !== null) { report.framedRevision = pendingFrame; report.framedAt = env.now(); pendingFrame = null; show(); }
108
+ env.frame(tick);
109
+ };
110
+ env.frame(tick);
111
+
112
+ const fail = (message: string): void => { report.error = message; env.log(`wildshard watch: ${message}`); };
113
+ const get = async (path: string): Promise<{ json: () => Promise<unknown>; arrayBuffer: () => Promise<ArrayBuffer> }> => {
114
+ const response = await env.fetch(`${env.origin}${DEV_SCENE_PATH}${path}`);
115
+ if (!response.ok) throw new Error(`${path} answered ${response.status}`);
116
+ return response;
117
+ };
118
+ /** Take one use of a cached asset for `owner`; it is let go when `owner` is disposed. */
119
+ const hold = <T>(map: Map<string, Held<T>>, key: string, owner: Scope): T => {
120
+ const held = map.get(key);
121
+ if (held === undefined) throw new Error(`asset ${key} was not fetched`);
122
+ held.users++;
123
+ owner.onDispose(() => { if (--held.users === 0) map.delete(key); });
124
+ return held.value;
125
+ };
126
+
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 => {
140
+ let landed = true;
141
+ for (const part of fetched) {
142
+ const owner = scope.child(`watch.part.${part.name}@${part.hash}`), old = parts.get(part.name);
143
+ try {
144
+ const devPart = { materials: part.materials, sprites: part.sprites, lamps: part.lamps, water: part.water, draws: part.draws,
145
+ geometries: part.geometries.map((key) => hold(geometries, key, owner)),
146
+ textures: part.textures.map((t) => ({ ...t, rgba: hold(textures, t.key, owner) })) };
147
+ if (old === undefined) live.addPart(part.name, devPart); else live.replacePart(part.name, devPart);
148
+ } catch (cause) {
149
+ // the hook keeps the old part drawn; this revision's copy lets its assets go
150
+ owner.dispose(); landed = false;
151
+ fail(`part ${part.name}: ${cause instanceof Error ? cause.message : String(cause)}`);
152
+ continue;
153
+ }
154
+ // the new part is drawn: record it before anything else can throw, so the next revision replaces it
155
+ parts.set(part.name, { hash: part.hash, scope: owner });
156
+ report.applied.push(`${part.name}@${part.hash}`);
157
+ old?.scope.dispose();
158
+ try { live.swapColliders(part.name, part.colliders); }
159
+ catch (cause) { landed = false; fail(`part ${part.name} colliders: ${cause instanceof Error ? cause.message : String(cause)}`); }
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(); }
215
+ const names = new Set(state.parts.map((part) => part.name));
216
+ let removed = 0;
217
+ for (const [name, part] of parts) {
218
+ if (names.has(name)) continue;
219
+ removed++;
220
+ live.removePart(name); live.swapColliders(name, []);
221
+ parts.delete(name); part.scope.dispose();
222
+ }
223
+ report.kind = [lookChanged ? 'look' : '', groundChanged ? 'ground' : '', gameplayChanged ? 'gameplay' : '', fetched.length > 0 || removed > 0 ? 'parts' : ''].filter((what) => what !== '').join(' and ') || 'nothing';
224
+ report.revision = state.revision;
225
+ // the timing counts a revision only once all its parts landed
226
+ report.steps.swapped = env.now();
227
+ if (landed) pendingFrame = state.revision;
228
+ };
229
+
230
+ // one sync at a time; a revision announced while one runs waits, and only the newest one runs
231
+ let running = false, next: WatchState | null = null, synced = 0;
232
+ const drain = async (): Promise<void> => {
233
+ running = true;
234
+ while (next !== null && !scope.disposed) {
235
+ const state = next; next = null;
236
+ try { await sync(state, synced++ === 0); } catch (cause) { fail(cause instanceof Error ? cause.message : String(cause)); }
237
+ }
238
+ running = false;
239
+ };
240
+ const receive = (data: unknown): void => {
241
+ report.steps.received = env.now();
242
+ let state: WatchState;
243
+ try { state = JSON.parse(String(data)) as WatchState; }
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;
248
+ if (state.wire !== WATCH_WIRE) { env.log(`wildshard watch: the server speaks wire ${state.wire}, this page ${WATCH_WIRE}; 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; }
250
+ shell = state.shell; next = state;
251
+ report.steps.seen = state.seenAt; report.steps.sent = state.sentAt;
252
+ if (!running) void drain();
253
+ };
254
+ const connect = (): void => {
255
+ if (scope.disposed) return;
256
+ const opened = env.socket(`${env.origin.replace(/^http/u, 'ws')}${WATCH_SOCKET}`);
257
+ socket = opened;
258
+ opened.onmessage = (event) => { receive(event.data); };
259
+ opened.onclose = () => { if (socket === opened && !scope.disposed) env.wait(1000, connect); };
260
+ };
261
+
262
+ const started = env.now();
263
+ const find = (): void => {
264
+ if (scope.disposed) return;
265
+ const found = env.hook();
266
+ if (found === undefined) {
267
+ if (env.now() - started > HOOK_WAIT_MS) { fail('the page never installed engine\'s dev hook: is this a devserver client?'); return; }
268
+ env.wait(250, find); return;
269
+ }
270
+ if (found.version !== DEV_HOOK_VERSION) { fail(`the page's dev hook is v${found.version}, this sdk drives v${DEV_HOOK_VERSION}: move the sdk and its engine pin together`); return; }
271
+ hook = found;
272
+ connect();
273
+ };
274
+ find();
275
+ return { report, stop: () => { scope.dispose(); const open = socket; socket = null; open?.close(); } };
276
+ }
277
+
278
+ /** A platform WebSocket as the page script's `SocketLike` (the browser's, or Node's in a test). */
279
+ export function socketOf(open: WebSocket): SocketLike {
280
+ const socket: SocketLike = { onmessage: null, onclose: null, close: () => { open.close(); } };
281
+ open.onmessage = (event) => { socket.onmessage?.({ data: event.data }); };
282
+ open.onclose = () => { socket.onclose?.(); };
283
+ return socket;
284
+ }
@@ -0,0 +1,59 @@
1
+ import { Scope } from '@wildshard/engine/app/scope';
2
+ import { installBrowserScopeEnvironment } from '@wildshard/engine/app/view/scopeEnvironment';
3
+ import { socketOf, startWatchPage, type DevHookLike, type WatchPageReport } from './page';
4
+ import { WATCH_RESHELL } from './protocol';
5
+
6
+ // SHARD-SOURCE AP5: the browser entry `wildshard watch` bundles and injects into the page it serves (watch.ts `pageScript`).
7
+ // It is its own bundle beside the engine's, so it installs its own copy of the browser scope environment (frames, timers).
8
+ declare global { interface Window { __wildshardDevHook?: DevHookLike; __wsDevScene?: WatchPageReport; __wsShell?: number } }
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;
43
+ const timers = new Scope('watch.entry');
44
+ const page = startWatchPage({
45
+ origin: location.origin,
46
+ hook: () => { const found = window.__wildshardDevHook; if (found !== undefined) ownObserverIds(); return found; },
47
+ fetch: (url) => fetch(url, { cache: 'no-store' }),
48
+ socket: (url) => socketOf(new WebSocket(url)),
49
+ frame: (run) => { timers.raf(run); },
50
+ wait: (ms, run) => { timers.timeout(ms, run); },
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); }); },
54
+ now: () => Date.now(),
55
+ log: (message) => { console.error(message); },
56
+ shell: () => window.__wsShell ?? null,
57
+ overlay: (lines) => { panel().textContent = lines.join('\n'); },
58
+ });
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.268,
19
+ "share": 0.04278
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();