@wildshard/sdk 0.2.13 → 0.3.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/GUIDE.md +16 -11
- package/bin/wildshard.mjs +2 -1
- package/docs/api/EXPORT-TIERS.md +12 -3
- package/lint/export-tiers.json +9 -0
- package/package.json +17 -5
- package/scripts/build-shardfiles.mjs +7 -2
- package/scripts/prepare-product.mjs +2 -2
- package/scripts/scratch-sweep.mjs +180 -0
- package/scripts/wildshard.mjs +1 -1
- package/skills/wildshard-mockup-to-model/SKILL.md +5 -3
- package/skills/wildshard-upgrade/SKILL.md +4 -4
- package/src/cli/help.ts +9 -5
- package/src/cli/upload/validate.ts +7 -5
- package/src/sharddev/assets.ts +1 -1
- package/src/sharddev/bake/compactGlb.ts +1 -1
- package/src/sharddev/bake/glbCompression.ts +1 -1
- package/src/sharddev/bake/gltfSource.ts +1 -1
- package/src/sharddev/bake/placeholders.ts +1 -1
- package/src/sharddev/bake/terrain.ts +1 -1
- package/src/sharddev/blobBytes.ts +1 -1
- package/src/sharddev/blobs.ts +2 -2
- package/src/sharddev/cli.ts +17 -4
- package/src/sharddev/formatJsonSchema.ts +1 -1
- package/src/sharddev/materialGraphFiles.ts +1 -1
- package/src/sharddev/newProject.ts +18 -10
- package/src/sharddev/outputProduct.ts +2 -2
- package/src/sharddev/productOutput.ts +2 -2
- package/src/sharddev/project.ts +1 -1
- package/src/sharddev/projectMap.ts +1 -1
- package/src/sharddev/refusals.ts +4 -2
- package/src/sharddev/reportCard.ts +1 -1
- package/src/sharddev/scene/author.ts +79 -0
- package/src/sharddev/scene/canvas.ts +213 -0
- package/src/sharddev/scene/description.ts +170 -0
- package/src/sharddev/scene/hash.ts +23 -0
- package/src/sharddev/scene/lower.ts +226 -0
- package/src/sharddev/scene/shard.ts +38 -0
- package/src/sharddev/scene/shardfile.ts +328 -0
- package/src/sharddev/threeGate.mjs +14 -0
- package/src/sharddev/threePin.mjs +40 -0
- package/src/sharddev/watch/page.ts +197 -0
- package/src/sharddev/watch/pageEntry.ts +23 -0
- package/src/sharddev/watch/proof.mjs +92 -0
- package/src/sharddev/watch/protocol.ts +108 -0
- package/src/sharddev/watch/socket.ts +57 -0
- package/src/sharddev/watch/watch.ts +209 -0
- package/src/shards/authoring-slice/generators/shard.ts +6 -0
- package/src/shards/authoring-slice/generators/textures.ts +173 -0
- package/src/shards/authoring-slice/generators/world.ts +415 -0
- package/src/shards/authoring-slice/shard.config.ts +7 -0
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// SHARD-SOURCE AP6 (and AP7's shots): drive a running `wildshard watch` (or `dev`) page in headless Chromium.
|
|
3
|
+
//
|
|
4
|
+
// node src/sharddev/watch/proof.mjs --url http://127.0.0.1:<port>/ --out <dir> [--shots] [--time <file> --runs 10]
|
|
5
|
+
//
|
|
6
|
+
// --shots three cleanroom cameras (Mossgate `scripts/cameras.json`: hut front, hut back, pond) to <out>/<id>.png
|
|
7
|
+
// --time edits the roof colour in <file> `runs` times and times each write to the first frame the page draws with the
|
|
8
|
+
// new colour (the dev scene host's `framedAt`, same machine clock); it checks the page never reloaded, the frame
|
|
9
|
+
// loop never stopped and the player never moved, and writes <out>/timing.json. The file is restored after.
|
|
10
|
+
import { chromium } from 'playwright';
|
|
11
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- a node script: it writes the shots and the timing beside the source edit.
|
|
12
|
+
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
13
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- a node script resolves its output folder.
|
|
14
|
+
import { join, resolve } from 'node:path';
|
|
15
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- a node script reads its flags.
|
|
16
|
+
import { parseArgs } from 'node:util';
|
|
17
|
+
|
|
18
|
+
const { values } = parseArgs({ options: { url: { type: 'string' }, out: { type: 'string' }, shots: { type: 'boolean' }, time: { type: 'string' }, runs: { type: 'string' }, prefix: { type: 'string' } } });
|
|
19
|
+
if (values.url === undefined || values.out === undefined) throw new Error('usage: proof.mjs --url <page> --out <dir> [--shots] [--time <file> --runs N]');
|
|
20
|
+
const OUT = resolve(values.out), RUNS = Number(values.runs ?? 10), PREFIX = values.prefix ?? '';
|
|
21
|
+
mkdirSync(OUT, { recursive: true });
|
|
22
|
+
// Mossgate cleanroom scripts/cameras.json: [x, z, yaw, pitch], eye 1.68 m, vertical FOV 72
|
|
23
|
+
const CAMERAS = [['03-hut-front', -3.9, -5.6, 0.03, -0.04], ['05-door-lamp', -4.6, -7.8, 0.03, 0.05], ['04-hut-back', -3.9, -10.4, 3.4, -0.05], ['08-pond', -10.4, 0.3, 1.571, -0.08]];
|
|
24
|
+
const ROOF = /shingle: new THREE\.MeshStandardMaterial\(\{ name: 'roof', (?:color: 0x[0-9a-f]{6}, )?map: tex\.shingle, roughness: 0\.95 \}\),/u;
|
|
25
|
+
|
|
26
|
+
const browser = await chromium.launch({ headless: true, args: ['--use-mock-keychain', '--password-store=basic', '--mute-audio', '--use-angle=metal', '--ignore-gpu-blocklist'] });
|
|
27
|
+
const result = {};
|
|
28
|
+
try {
|
|
29
|
+
const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
|
|
30
|
+
// engine's probe controls (pose) answer only a harness-pinned page (engine scripts/debug-settings.mjs harnessPins)
|
|
31
|
+
await page.addInitScript({ content: 'window.__wildshardHarness=Object.assign(window.__wildshardHarness??{},{seed:357});' });
|
|
32
|
+
page.on('pageerror', (error) => { console.error(`page error: ${error.message}`); });
|
|
33
|
+
await page.goto(`${values.url}?skipintro`);
|
|
34
|
+
await page.waitForFunction(() => window.__wildshard?.world?.player !== undefined, undefined, { timeout: 180_000, polling: 500 });
|
|
35
|
+
const watched = await page.waitForFunction(() => (window.__wsDevScene?.framedRevision ?? 0) > 0, undefined, { timeout: 30_000, polling: 250 }).then(() => true, () => false);
|
|
36
|
+
console.info(`page ready (${watched ? 'dev scene host live' : 'no dev scene host: a baked shard'})`);
|
|
37
|
+
await page.evaluate(() => {
|
|
38
|
+
const w = window.__wildshard.world;
|
|
39
|
+
if (w.animals) w.animals.calm = true;
|
|
40
|
+
w.game.onLate(() => { for (const child of w.game.camera.children) child.visible = false; if (Math.abs(w.game.camera.fov - 72) > 0.01) { w.game.camera.fov = 72; w.game.camera.updateProjectionMatrix(); } }, 'ap6.fov');
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
if (values.shots === true) {
|
|
44
|
+
for (const [id, x, z, yaw, pitch] of CAMERAS) {
|
|
45
|
+
await page.evaluate(async (pose) => { await window.__wildshard.pose(pose); }, { x, z, yaw, pitch });
|
|
46
|
+
await page.waitForTimeout(2500);
|
|
47
|
+
await page.screenshot({ path: join(OUT, `${PREFIX}${id}.png`) });
|
|
48
|
+
console.info(`shot ${PREFIX}${id}`);
|
|
49
|
+
}
|
|
50
|
+
// the page's own frame clock, counted for 5 s (page code, passed as text: it runs in the browser, not here)
|
|
51
|
+
result.fps = await page.evaluate(`new Promise((done) => { const w = window.__wildshard.world, t0 = Date.now(); let n = 0; const stop = w.game.watchFrames(() => { n++; if (Date.now() - t0 >= 5000) { stop(); done(Math.round(n / ((Date.now() - t0) / 1000))); } }); })`);
|
|
52
|
+
console.info(`fps ${result.fps} (headless, 1280x720, 5 s at the last camera)`);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
if (values.time !== undefined) {
|
|
56
|
+
if (!watched) throw new Error('--time needs a `wildshard watch` page');
|
|
57
|
+
const file = resolve(values.time), original = readFileSync(file, 'utf8');
|
|
58
|
+
if (!ROOF.test(original)) throw new Error(`--time: ${file} has no roof material line to edit`);
|
|
59
|
+
await page.evaluate(async (pose) => { await window.__wildshard.pose(pose); window.__ap6Marker = 'same page'; }, { x: CAMERAS[0][1], z: CAMERAS[0][2], yaw: CAMERAS[0][3], pitch: CAMERAS[0][4] });
|
|
60
|
+
await page.waitForTimeout(2000);
|
|
61
|
+
const roofHex = () => { let hex = null; window.__wildshard.world.game.rootScene.getObjectByName('devScene')?.traverse((o) => { if (o.material?.name === 'roof') hex = o.material.color.getHexString(); }); return hex; };
|
|
62
|
+
const runs = [];
|
|
63
|
+
try {
|
|
64
|
+
for (let i = 0; i < RUNS; i++) {
|
|
65
|
+
const colour = ((0x40 + i * 17) << 16 | (0x90 - i * 7) << 8 | (0x30 + i * 13)).toString(16).padStart(6, '0');
|
|
66
|
+
const before = await page.evaluate(() => ({ revision: window.__wsDevScene.framedRevision, frames: window.__wsDevScene.frames, at: window.__wildshard.world.player.position.toArray() }));
|
|
67
|
+
const written = Date.now();
|
|
68
|
+
writeFileSync(file, original.replace(ROOF, `shingle: new THREE.MeshStandardMaterial({ name: 'roof', color: 0x${colour}, map: tex.shingle, roughness: 0.95 }),`));
|
|
69
|
+
const handle = await page.waitForFunction(([revision, hex, read]) => {
|
|
70
|
+
const report = window.__wsDevScene;
|
|
71
|
+
if (report.framedRevision <= revision) return false;
|
|
72
|
+
// eslint-disable-next-line no-new-func -- the roof reader is passed in as text
|
|
73
|
+
return new Function(`return (${read})()`)() === hex ? report.framedAt : false;
|
|
74
|
+
}, [before.revision, colour, roofHex.toString()], { timeout: 30_000, polling: 'raf' });
|
|
75
|
+
const framedAt = await handle.jsonValue();
|
|
76
|
+
const after = await page.evaluate(() => ({ frames: window.__wsDevScene.frames, at: window.__wildshard.world.player.position.toArray(), marker: window.__ap6Marker }));
|
|
77
|
+
const moved = Math.hypot(...after.at.map((v, k) => v - before.at[k]));
|
|
78
|
+
runs.push({ colour, ms: framedAt - written, frames: after.frames - before.frames, moved: Number(moved.toFixed(4)), reloaded: after.marker !== 'same page' });
|
|
79
|
+
console.info(`edit ${i + 1}: #${colour} on screen in ${framedAt - written} ms`);
|
|
80
|
+
await page.waitForTimeout(400);
|
|
81
|
+
}
|
|
82
|
+
} finally { writeFileSync(file, original); }
|
|
83
|
+
const sorted = runs.map((r) => r.ms).sort((a, b) => a - b), median = (sorted[4] + sorted[5]) / 2;
|
|
84
|
+
result.timing = { runs, median, min: sorted[0], max: sorted.at(-1), reloads: runs.filter((r) => r.reloaded).length, maxMoved: Math.max(...runs.map((r) => r.moved)), frameLoopStopped: runs.some((r) => r.frames <= 0) };
|
|
85
|
+
await page.waitForTimeout(3000);
|
|
86
|
+
await page.screenshot({ path: join(OUT, `${PREFIX}timing-last.png`) });
|
|
87
|
+
console.info(`median ${median} ms (min ${sorted[0]}, max ${sorted.at(-1)}), reloads ${result.timing.reloads}, player moved ≤ ${result.timing.maxMoved} m`);
|
|
88
|
+
}
|
|
89
|
+
} finally {
|
|
90
|
+
await browser.close();
|
|
91
|
+
writeFileSync(join(OUT, `${PREFIX}proof.json`), `${JSON.stringify(result, null, 2)}\n`);
|
|
92
|
+
}
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
import type { SceneGeometry, ScenePart, ShardScene } from '../scene/description';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* SHARD-SOURCE AP5 (J347): the `wildshard watch` protocol, all of it sharddev's. The watch server pushes one `WatchState`
|
|
5
|
+
* per revision over a WebSocket; the page script (`page.ts`, injected into the page `watch` serves) fetches the parts whose
|
|
6
|
+
* hash changed, and only the geometry and rasters it lacks, then drives engine's dev hook. Engine knows none of this: it
|
|
7
|
+
* holds only the hook (`src/client/game/devScene/hook.ts`), whose version is `DEV_HOOK_VERSION` below.
|
|
8
|
+
*
|
|
9
|
+
* WS /__wildshard_scene/socket one `WatchState` (JSON) per revision, the first on connect
|
|
10
|
+
* GET /__wildshard_scene/part/<name> one `WatchPart` (JSON)
|
|
11
|
+
* GET /__wildshard_scene/geometry/<key> one geometry (`encodeGeometry`), immutable by key
|
|
12
|
+
* GET /__wildshard_scene/texture/<key> one RGBA8 raster, row 0 at v = 0, immutable by key
|
|
13
|
+
*/
|
|
14
|
+
export const DEV_SCENE_PATH = '/__wildshard_scene/';
|
|
15
|
+
export const WATCH_SOCKET = '/__wildshard_scene/socket';
|
|
16
|
+
/** The protocol between the watch server and its own page script: they ship together, so a mismatch is a stale page. */
|
|
17
|
+
export const WATCH_WIRE = 2;
|
|
18
|
+
/** The engine dev hook version this sdk drives: engine's `DEV_HOOK_VERSION`, named in a devserver client's build flags. */
|
|
19
|
+
export const DEV_HOOK_VERSION = 1;
|
|
20
|
+
|
|
21
|
+
export interface WatchState {
|
|
22
|
+
readonly wire: number;
|
|
23
|
+
/** the shell the page booted from: a new one (a ground, spawn or grade change) means the page reloads */
|
|
24
|
+
readonly shell: number;
|
|
25
|
+
readonly revision: number;
|
|
26
|
+
/** every part and its content hash; a part missing here is gone */
|
|
27
|
+
readonly parts: readonly { readonly name: string; readonly hash: string }[];
|
|
28
|
+
/** the look's day keys (sky, fog, sun, ambient), set live through the hook's `setLook` */
|
|
29
|
+
readonly look: { readonly hash: string; readonly keys: readonly unknown[] };
|
|
30
|
+
/** the last compile's refusal; the page keeps what it has */
|
|
31
|
+
readonly error: string | null;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** One part as the page fetches it: the hook's `DevPart` with geometry and rasters by key, and its colliders. */
|
|
35
|
+
export interface WatchPart {
|
|
36
|
+
readonly name: string;
|
|
37
|
+
readonly hash: string;
|
|
38
|
+
readonly materials: readonly unknown[];
|
|
39
|
+
readonly textures: readonly { readonly key: string; readonly width: number; readonly height: number; readonly colourSpace: 'srgb' | 'linear' }[];
|
|
40
|
+
readonly geometries: readonly string[];
|
|
41
|
+
readonly draws: readonly { readonly geometry: string; readonly material: string; readonly matrix: readonly number[]; readonly castShadow: boolean; readonly receiveShadow: boolean;
|
|
42
|
+
readonly instances: { readonly count: number; readonly matrices: readonly number[]; readonly colours: readonly number[] | null } | null }[];
|
|
43
|
+
readonly sprites: readonly unknown[];
|
|
44
|
+
readonly lamps: readonly unknown[];
|
|
45
|
+
readonly water: readonly unknown[];
|
|
46
|
+
readonly colliders: readonly { readonly centre: readonly number[]; readonly half: readonly number[]; readonly rotation: readonly number[] }[];
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** One part as the page's `WatchPart` JSON. Lamps and water are the shardfile's own rows (`lampRows`, `waterRows`). */
|
|
50
|
+
export function encodePart(scene: ShardScene, part: ScenePart, rows: { lamps: readonly unknown[]; water: readonly unknown[] }): WatchPart {
|
|
51
|
+
const material = (key: string): unknown => { const row = scene.materials[key]; if (row === undefined) throw new Error(`watch: part ${part.name} names material ${key} the scene lacks`); return row; };
|
|
52
|
+
return {
|
|
53
|
+
name: part.name, hash: part.hash,
|
|
54
|
+
materials: part.materials.map(material),
|
|
55
|
+
textures: part.textures.map((key) => { const t = scene.textures[key]; if (t === undefined) throw new Error(`watch: part ${part.name} names texture ${key} the scene lacks`); return { key, width: t.width, height: t.height, colourSpace: t.colourSpace }; }),
|
|
56
|
+
geometries: part.geometries,
|
|
57
|
+
draws: part.draws.map((d) => ({ geometry: d.geometry, material: d.material, matrix: d.matrix, castShadow: d.castShadow, receiveShadow: d.receiveShadow,
|
|
58
|
+
instances: d.instances === null ? null : { count: d.instances.count, matrices: Array.from(d.instances.matrices), colours: d.instances.colours === null ? null : Array.from(d.instances.colours) } })),
|
|
59
|
+
sprites: part.sprites.map((s) => ({ material: s.material, position: s.position, scale: s.scale, center: s.center })),
|
|
60
|
+
lamps: rows.lamps, water: rows.water,
|
|
61
|
+
colliders: part.colliders.map((c) => ({ centre: c.centre, half: c.half, rotation: c.rotation })),
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Five little-endian u32 element counts (position, normal, uv, colour, index), then each array in that order. */
|
|
66
|
+
export function encodeGeometry(geometry: SceneGeometry): Uint8Array {
|
|
67
|
+
const arrays = [geometry.position, geometry.normal, geometry.uv, geometry.colour, geometry.index];
|
|
68
|
+
const counts = arrays.map((a) => a?.length ?? 0), bytes = new Uint8Array(20 + counts.reduce((n, c) => n + c * 4, 0)), view = new DataView(bytes.buffer);
|
|
69
|
+
counts.forEach((count, i) => { view.setUint32(i * 4, count, true); });
|
|
70
|
+
let offset = 20;
|
|
71
|
+
for (const array of arrays) {
|
|
72
|
+
if (array === null) continue;
|
|
73
|
+
bytes.set(new Uint8Array(array.buffer, array.byteOffset, array.byteLength), offset);
|
|
74
|
+
offset += array.byteLength;
|
|
75
|
+
}
|
|
76
|
+
return bytes;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** `encodeGeometry`'s inverse (the page script's). */
|
|
80
|
+
export function decodeGeometry(key: string, bytes: ArrayBuffer): { key: string; position: Float32Array; normal: Float32Array; uv: Float32Array | null; colour: Float32Array | null; index: Uint32Array | null } {
|
|
81
|
+
const header = new DataView(bytes, 0, 20), [positions = 0, normals = 0, uvs = 0, colours = 0, indices = 0] = [0, 1, 2, 3, 4].map((i) => header.getUint32(i * 4, true));
|
|
82
|
+
let offset = 20;
|
|
83
|
+
const take = (count: number): Float32Array => { const out = new Float32Array(bytes.slice(offset, offset + count * 4)); offset += count * 4; return out; };
|
|
84
|
+
const position = take(positions), normal = take(normals), uv = uvs > 0 ? take(uvs) : null, colour = colours > 0 ? take(colours) : null;
|
|
85
|
+
const index = indices > 0 ? new Uint32Array(bytes.slice(offset, offset + indices * 4)) : null;
|
|
86
|
+
if (offset + indices * 4 !== bytes.byteLength) throw new Error(`watch: geometry ${key} is ${bytes.byteLength} bytes, its header says ${offset + indices * 4}`);
|
|
87
|
+
return { key, position, normal, uv, colour, index };
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* The shard a watched page boots from: the scene's ground, look, sun, sky and spawn, with every part's draws, sprites,
|
|
92
|
+
* lamps, colliders and water left to the page script, which swaps them live through the dev hook.
|
|
93
|
+
*/
|
|
94
|
+
export function liveShell(scene: ShardScene): ShardScene {
|
|
95
|
+
return { ...scene, parts: scene.parts.map((part) => ({ ...part, draws: [], sprites: [], colliders: [], water: [], lights: part.lights.filter((l) => l.kind !== 'point'), materials: [], textures: [], geometries: [] })) };
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* The devserver client's dev hook version, from its `build-flags.json` (`devHook`, engine's app build writes it), against
|
|
100
|
+
* this sdk's: null when they agree, else why `watch` can't drive that page.
|
|
101
|
+
*/
|
|
102
|
+
export function hookMismatch(flags: unknown): string | null {
|
|
103
|
+
const version = typeof flags === 'object' && flags !== null && 'devHook' in flags ? flags.devHook : undefined;
|
|
104
|
+
if (version === DEV_HOOK_VERSION) return null;
|
|
105
|
+
return version === undefined
|
|
106
|
+
? `this engine client has no dev hook (its build flags name no devHook); wildshard watch needs engine's dev hook v${DEV_HOOK_VERSION}: move the sdk's engine pin to an engine with it, or set WILDSHARD_DEV_CLIENT to a devserver build of one`
|
|
107
|
+
: `this engine client's dev hook is v${String(version)}, this sdk drives v${DEV_HOOK_VERSION}: move the sdk and its engine pin together`;
|
|
108
|
+
}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- The handshake's accept key is a SHA-1 of the client's key.
|
|
2
|
+
import { createHash } from 'node:crypto';
|
|
3
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- The watch server upgrades its own HTTP requests.
|
|
4
|
+
import type { IncomingMessage } from 'node:http';
|
|
5
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- An upgraded request hands over its raw socket.
|
|
6
|
+
import type { Duplex } from 'node:stream';
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* SHARD-SOURCE AP5: the watch server's WebSocket, server to page only (RFC 6455, text frames out; the page sends nothing
|
|
10
|
+
* but a close or a pong). The page script is the only client, on 127.0.0.1, so this is the handshake, one frame writer and
|
|
11
|
+
* a reader that answers a close and a ping: no extensions, no fragmentation, no dependency.
|
|
12
|
+
*/
|
|
13
|
+
export interface WatchSocket { send: (text: string) => void; close: () => void; readonly closed: () => boolean }
|
|
14
|
+
|
|
15
|
+
const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
|
|
16
|
+
|
|
17
|
+
function frame(opcode: number, payload: Buffer): Buffer {
|
|
18
|
+
const length = payload.length, head = length < 126 ? Buffer.alloc(2) : length < 65_536 ? Buffer.alloc(4) : Buffer.alloc(10);
|
|
19
|
+
head[0] = 0x80 | opcode;
|
|
20
|
+
if (length < 126) head[1] = length;
|
|
21
|
+
else if (length < 65_536) { head[1] = 126; head.writeUInt16BE(length, 2); }
|
|
22
|
+
else { head[1] = 127; head.writeBigUInt64BE(BigInt(length), 2); }
|
|
23
|
+
return Buffer.concat([head, payload]);
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Answer an upgrade request; null (and a 400) when it isn't a WebSocket handshake. */
|
|
27
|
+
export function acceptSocket(request: IncomingMessage, socket: Duplex, onClose: () => void): WatchSocket | null {
|
|
28
|
+
const key = request.headers['sec-websocket-key'];
|
|
29
|
+
if (typeof key !== 'string' || request.headers.upgrade?.toLowerCase() !== 'websocket') { socket.end('HTTP/1.1 400 Bad Request\r\n\r\n'); return null; }
|
|
30
|
+
const accept = createHash('sha1').update(`${key}${GUID}`).digest('base64');
|
|
31
|
+
socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
|
|
32
|
+
let closed = false, pending = Buffer.alloc(0);
|
|
33
|
+
const end = (): void => { if (closed) return; closed = true; socket.end(); onClose(); };
|
|
34
|
+
socket.on('data', (chunk: Buffer) => {
|
|
35
|
+
pending = Buffer.concat([pending, chunk]);
|
|
36
|
+
while (pending.length >= 2) {
|
|
37
|
+
const opcode = (pending[0] ?? 0) & 0x0f, masked = ((pending[1] ?? 0) & 0x80) !== 0;
|
|
38
|
+
let length = (pending[1] ?? 0) & 0x7f, offset = 2;
|
|
39
|
+
if (length === 126) { if (pending.length < 4) return; length = pending.readUInt16BE(2); offset = 4; }
|
|
40
|
+
else if (length === 127) { if (pending.length < 10) return; length = Number(pending.readBigUInt64BE(2)); offset = 10; }
|
|
41
|
+
const mask = masked ? pending.subarray(offset, offset + 4) : null; if (masked) offset += 4;
|
|
42
|
+
if (pending.length < offset + length) return;
|
|
43
|
+
const payload = Buffer.from(pending.subarray(offset, offset + length));
|
|
44
|
+
if (mask !== null) for (let i = 0; i < payload.length; i++) payload[i] = (payload[i] ?? 0) ^ (mask[i % 4] ?? 0);
|
|
45
|
+
pending = pending.subarray(offset + length);
|
|
46
|
+
if (opcode === 0x8) { if (!closed) socket.write(frame(0x8, Buffer.alloc(0))); end(); return; }
|
|
47
|
+
if (opcode === 0x9 && !closed) socket.write(frame(0xa, payload));
|
|
48
|
+
}
|
|
49
|
+
});
|
|
50
|
+
socket.on('close', end);
|
|
51
|
+
socket.on('error', () => { end(); socket.destroy(); });
|
|
52
|
+
return {
|
|
53
|
+
send: (text) => { if (!closed) socket.write(frame(0x1, Buffer.from(text, 'utf8'))); },
|
|
54
|
+
close: () => { if (!closed) socket.write(frame(0x8, Buffer.alloc(0))); end(); },
|
|
55
|
+
closed: () => closed,
|
|
56
|
+
};
|
|
57
|
+
}
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- The author tool serves the watched product and the scene stream.
|
|
2
|
+
import { createServer } from 'node:http';
|
|
3
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- Author changes are watched; the product is a private disposable build.
|
|
4
|
+
import { createReadStream, existsSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
|
|
5
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- Own temporary build directory.
|
|
6
|
+
import { tmpdir } from 'node:os';
|
|
7
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- Resolve static requests inside the product directory.
|
|
8
|
+
import { extname, join, resolve, sep } from 'node:path';
|
|
9
|
+
import { build } from 'vite';
|
|
10
|
+
import { diagnosticNow } from '@wildshard/engine/core/clock';
|
|
11
|
+
import { Scope } from '@wildshard/engine/app/scope';
|
|
12
|
+
import { SDK_ROOT } from '../agentFiles';
|
|
13
|
+
import { buildProject } from '../project';
|
|
14
|
+
import { projectSourceStamp } from '../dev';
|
|
15
|
+
import { executeBundle } from '../executeBundle';
|
|
16
|
+
import type { ShardScene } from '../scene/description';
|
|
17
|
+
import { hashOf } from '../scene/hash';
|
|
18
|
+
import { lampRows, sceneLook, waterRows } from '../scene/shardfile';
|
|
19
|
+
import { DEV_SCENE_PATH, WATCH_SOCKET, WATCH_WIRE, encodeGeometry, encodePart, hookMismatch, liveShell, type WatchState } from './protocol';
|
|
20
|
+
import { acceptSocket, type WatchSocket } from './socket';
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* SHARD-SOURCE AP5 and AP6 (J347): `wildshard watch <source> [port]`. The page boots once from a live shell (the ground,
|
|
24
|
+
* look and spawn; `liveShell`) with the watch page script injected (`page.ts`), then every source edit runs here, in this
|
|
25
|
+
* long-lived process, with no product rebuild:
|
|
26
|
+
*
|
|
27
|
+
* bundle `shard.config.ts` (one rolldown pass, ~0.15 s), import it, call the scene shard's `describe()`
|
|
28
|
+
* diff each part's content hash, and the look's day keys, against the last revision; only changed parts are
|
|
29
|
+
* re-encoded (per-part cache)
|
|
30
|
+
* push one `WatchState` on the WebSocket; the page script fetches the changed parts, and only the geometry and
|
|
31
|
+
* rasters it lacks, and drives engine's dev hook
|
|
32
|
+
*
|
|
33
|
+
* A sky, fog, sun colour or ambient edit goes live (the look's day keys). A ground, spawn, grade or sun direction edit
|
|
34
|
+
* can't in M1 (AP17's fast path): it rebuilds the shell and the page reloads, as `dev` does. `wildshard dev` is unchanged.
|
|
35
|
+
*/
|
|
36
|
+
export interface WatchProject { url: string; close: () => Promise<void> }
|
|
37
|
+
|
|
38
|
+
const MIME: Record<string, string> = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.wasm': 'application/wasm', '.svg': 'image/svg+xml', '.png': 'image/png', '.woff2': 'font/woff2', '.ktx2': 'image/ktx2' };
|
|
39
|
+
const ignored = new Set(['node_modules', '.git', 'dist', 'public', '.worktrees', 'tmp']);
|
|
40
|
+
|
|
41
|
+
/** The scene shard `shard.config.ts` exports (its default or `generate`), read fresh from source. */
|
|
42
|
+
async function describeSource(source: string): Promise<{ scene: ShardScene; bundleMs: number; describeMs: number }> {
|
|
43
|
+
const started = diagnosticNow();
|
|
44
|
+
const result = await build({ configFile: false, logLevel: 'silent', build: { write: false, minify: false, lib: { entry: resolve(source, 'shard.config.ts'), formats: ['es'], fileName: 'config' }, rolldownOptions: { external: [/^node:/u], output: { codeSplitting: false } } } });
|
|
45
|
+
const built = Array.isArray(result) ? result[0] : result;
|
|
46
|
+
const chunk = built !== undefined && 'output' in built ? built.output.find((out) => out.type === 'chunk') : undefined;
|
|
47
|
+
if (chunk === undefined || chunk.type !== 'chunk') throw new Error('watch: shard.config.ts did not bundle to one module');
|
|
48
|
+
const loaded = await executeBundle(chunk.code, source) as Record<string, unknown>;
|
|
49
|
+
const bundled = diagnosticNow();
|
|
50
|
+
const shard = [loaded['default'], loaded['generate']].find((value): value is { describe: () => ShardScene } => typeof value === 'function' && 'describe' in value && typeof value.describe === 'function');
|
|
51
|
+
if (shard === undefined) throw new Error('watch: shard.config.ts exports no scene shard (defineShard from @wildshard/sdk/scene/shard)');
|
|
52
|
+
const scene = shard.describe();
|
|
53
|
+
return { scene, bundleMs: Math.round(bundled - started), describeMs: Math.round(diagnosticNow() - bundled) };
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** The shell's look, as the shardfile back end writes it for the live shell: its day keys go live, the rest is the shell's. */
|
|
57
|
+
const shellLook = (scene: ShardScene): ReturnType<typeof sceneLook> => sceneLook(scene, liveShell(scene).parts.flatMap((p) => p.lights), {});
|
|
58
|
+
|
|
59
|
+
/** What a page boots from: a ground, spawn or look change other than its day keys needs a new shell. */
|
|
60
|
+
const shellKey = (scene: ShardScene): string => {
|
|
61
|
+
const { keys: _keys, ...look } = shellLook(scene);
|
|
62
|
+
// engine's live look keeps its fog kind: linear against exponential needs a new shell
|
|
63
|
+
return hashOf((hash) => hash.json({ look, linearFog: scene.look.fog?.kind === 'linear', ground: scene.ground?.hash ?? null, spawn: scene.spawn, identity: scene.identity }));
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
/** The page script, bundled once per process from `pageEntry.ts` into one classic script for the page's body. */
|
|
67
|
+
export async function pageScript(): Promise<string> {
|
|
68
|
+
// from the sdk's root: the author CLI is one bundle whose import.meta.dirname is src/sharddev (scripts/wildshard.mjs)
|
|
69
|
+
const entry = resolve(SDK_ROOT, 'src/sharddev/watch/pageEntry.ts');
|
|
70
|
+
const result = await build({ configFile: false, logLevel: 'silent', build: { write: false, minify: true, lib: { entry, formats: ['iife'], name: 'wildshardWatch', fileName: 'watch' }, rolldownOptions: { output: { codeSplitting: false } } } });
|
|
71
|
+
const built = Array.isArray(result) ? result[0] : result;
|
|
72
|
+
const chunk = built !== undefined && 'output' in built ? built.output.find((out) => out.type === 'chunk') : undefined;
|
|
73
|
+
if (chunk === undefined || chunk.type !== 'chunk') throw new Error('watch: the page script did not bundle to one module');
|
|
74
|
+
return `<script>${chunk.code.replaceAll(/<\/script/giu, '<\\/script')}</script>`;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Refuse a devserver client whose dev hook this sdk can't drive (its `build-flags.json`, written by engine's app build). */
|
|
78
|
+
function assertHook(client: string): void {
|
|
79
|
+
const file = join(client, 'build-flags.json');
|
|
80
|
+
const problem = hookMismatch(existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) as unknown : null);
|
|
81
|
+
if (problem !== null) throw new Error(`wildshard watch: ${problem}`);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export async function watchProject(project: string, options: { port?: number; client?: string | null; log?: (line: string) => void } = {}): Promise<WatchProject> {
|
|
85
|
+
if (typeof options.client === 'string') assertHook(options.client);
|
|
86
|
+
const source = resolve(project), scratch = realpathSync(mkdtempSync(join(tmpdir(), 'wildshard-watch-'))), log = options.log ?? ((line: string): void => { console.info(line); });
|
|
87
|
+
let product = '', shardRoot = '', shell = 0, shellHash = '', revision = 0, error: string | null = null, stopped = false, script = '';
|
|
88
|
+
let parts: { name: string; hash: string }[] = [], look: WatchState['look'] = { hash: '', keys: [] };
|
|
89
|
+
const encodedParts = new Map<string, Uint8Array>(), geometries = new Map<string, Uint8Array>(), textures = new Map<string, Uint8Array>();
|
|
90
|
+
const clients = new Set<WatchSocket>();
|
|
91
|
+
const state = (): string => JSON.stringify({ wire: WATCH_WIRE, shell, revision, parts, look, error } satisfies WatchState);
|
|
92
|
+
const announce = (): void => { const message = state(); for (const client of clients) client.send(message); };
|
|
93
|
+
|
|
94
|
+
const buildShell = async (): Promise<void> => {
|
|
95
|
+
const target = join(scratch, `shell-${shell + 1}`);
|
|
96
|
+
const before = process.env['WILDSHARD_SCENE_LIVE'];
|
|
97
|
+
process.env['WILDSHARD_SCENE_LIVE'] = '1';
|
|
98
|
+
try {
|
|
99
|
+
const built = await buildProject(source, target, { devserver: true, ...(options.client === undefined ? {} : { client: options.client }) });
|
|
100
|
+
const page = join(target, 'index.html');
|
|
101
|
+
script ||= await pageScript();
|
|
102
|
+
// the shell's number first: the page script reloads on a state for another shell, even on its first message
|
|
103
|
+
const tags = `<script>window.__wsShell=${shell + 1}</script>${script}</body>`;
|
|
104
|
+
if (existsSync(page)) writeFileSync(page, readFileSync(page, 'utf8').replace('</body>', () => tags));
|
|
105
|
+
if (product !== '') rmSync(product, { recursive: true, force: true });
|
|
106
|
+
product = target; shardRoot = `/shardfiles/${built.identity.slug}/`; shell++;
|
|
107
|
+
} finally { if (before === undefined) delete process.env['WILDSHARD_SCENE_LIVE']; else process.env['WILDSHARD_SCENE_LIVE'] = before; }
|
|
108
|
+
};
|
|
109
|
+
|
|
110
|
+
const compile = async (): Promise<void> => {
|
|
111
|
+
const started = diagnosticNow();
|
|
112
|
+
let described: Awaited<ReturnType<typeof describeSource>>;
|
|
113
|
+
try { described = await describeSource(source); }
|
|
114
|
+
catch (cause) { error = cause instanceof Error ? cause.message : String(cause); log(`wildshard watch: ${error}`); revision++; announce(); return; }
|
|
115
|
+
const { scene } = described, key = shellKey(scene);
|
|
116
|
+
if (key !== shellHash) {
|
|
117
|
+
if (shellHash !== '') log('wildshard watch: the ground, spawn or grade changed; rebuilding the shell (the page reloads)');
|
|
118
|
+
// the first shell's failure is the command's; a later one is the page's error, and the old shell keeps serving
|
|
119
|
+
if (shellHash === '') await buildShell();
|
|
120
|
+
else try { await buildShell(); } catch (cause) { error = cause instanceof Error ? cause.message : String(cause); log(`wildshard watch: ${error}`); revision++; announce(); return; }
|
|
121
|
+
shellHash = key;
|
|
122
|
+
}
|
|
123
|
+
const changed = scene.parts.filter((part) => parts.find((live) => live.name === part.name)?.hash !== part.hash).map((part) => part.name);
|
|
124
|
+
for (const part of scene.parts) {
|
|
125
|
+
if (encodedParts.has(part.hash)) continue;
|
|
126
|
+
encodedParts.set(part.hash, new TextEncoder().encode(JSON.stringify(encodePart(scene, part, { lamps: lampRows(part.lights), water: waterRows(part) }))));
|
|
127
|
+
for (const g of part.geometries) { const geometry = scene.geometries[g]; if (!geometries.has(g) && geometry !== undefined) geometries.set(g, encodeGeometry(geometry)); }
|
|
128
|
+
for (const t of part.textures) { const texture = scene.textures[t]; if (!textures.has(t) && texture !== undefined) textures.set(t, texture.rgba); }
|
|
129
|
+
}
|
|
130
|
+
const next = scene.parts.map((part) => ({ name: part.name, hash: part.hash }));
|
|
131
|
+
const { keys } = shellLook(scene), lookHash = hashOf((hash) => hash.json(keys));
|
|
132
|
+
const same = error === null && lookHash === look.hash && next.length === parts.length && next.every((part, i) => part.name === parts[i]?.name && part.hash === parts[i]?.hash);
|
|
133
|
+
error = null;
|
|
134
|
+
if (same) return;
|
|
135
|
+
const lookChanged = look.hash !== '' && lookHash !== look.hash;
|
|
136
|
+
parts = next; look = { hash: lookHash, keys }; revision++;
|
|
137
|
+
announce();
|
|
138
|
+
const what = [...changed.length === 0 ? [] : [`changed ${changed.join(', ')}`], ...lookChanged ? ['the look'] : []];
|
|
139
|
+
log(`wildshard watch: revision ${revision}, ${what.length === 0 ? 'parts removed' : what.join(' and ')} in ${Math.round(diagnosticNow() - started)} ms (bundle ${described.bundleMs} ms, describe ${described.describeMs} ms)`);
|
|
140
|
+
};
|
|
141
|
+
|
|
142
|
+
try { await compile(); } catch (cause) { rmSync(scratch, { recursive: true, force: true }); throw cause; }
|
|
143
|
+
if (product === '') { rmSync(scratch, { recursive: true, force: true }); throw new Error(`wildshard watch: ${error ?? 'no shell was built'}`); }
|
|
144
|
+
|
|
145
|
+
const server = createServer((request, response) => {
|
|
146
|
+
response.setHeader('Cache-Control', 'no-store');
|
|
147
|
+
try {
|
|
148
|
+
const path = decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname);
|
|
149
|
+
if (path.startsWith(DEV_SCENE_PATH)) {
|
|
150
|
+
const rest = path.slice(DEV_SCENE_PATH.length), [kind = '', name = ''] = rest.split(/\/(.*)/su);
|
|
151
|
+
const hash = kind === 'part' ? parts.find((part) => part.name === name)?.hash : undefined;
|
|
152
|
+
const body = kind === 'part' ? (hash === undefined ? undefined : encodedParts.get(hash)) : kind === 'geometry' ? geometries.get(name) : kind === 'texture' ? textures.get(name) : undefined;
|
|
153
|
+
if (body === undefined) { response.writeHead(404); response.end(); return; }
|
|
154
|
+
response.setHeader('Content-Type', kind === 'part' ? 'application/json' : 'application/octet-stream');
|
|
155
|
+
response.end(body); return;
|
|
156
|
+
}
|
|
157
|
+
if (request.method !== 'GET' && request.method !== 'HEAD') { response.writeHead(405); response.end(); return; }
|
|
158
|
+
const served = shardRoot !== '' && path.startsWith(shardRoot) ? path.slice(shardRoot.length - 1) : path;
|
|
159
|
+
const file = resolve(product, served === '/' ? 'index.html' : served.slice(1));
|
|
160
|
+
if (!file.startsWith(`${product}${sep}`) || !existsSync(file) || !statSync(file).isFile() || !realpathSync(file).startsWith(`${product}${sep}`)) { response.writeHead(404); response.end(); return; }
|
|
161
|
+
response.setHeader('Content-Type', MIME[extname(file)] ?? 'application/octet-stream');
|
|
162
|
+
if (request.method === 'HEAD') response.end(); else createReadStream(file).on('error', () => { response.destroy(); }).pipe(response);
|
|
163
|
+
} catch { response.writeHead(400); response.end(); }
|
|
164
|
+
});
|
|
165
|
+
server.on('upgrade', (request, socket) => {
|
|
166
|
+
if (stopped) { socket.destroy(); return; }
|
|
167
|
+
if (new URL(request.url ?? '/', 'http://localhost').pathname !== WATCH_SOCKET) { socket.end('HTTP/1.1 404 Not Found\r\n\r\n'); return; }
|
|
168
|
+
// a browser page from anywhere else may not read the scene stream (a Node client sends no Origin)
|
|
169
|
+
const origin = request.headers.origin, address = server.address(), port = address !== null && typeof address === 'object' ? address.port : 0;
|
|
170
|
+
if (origin !== undefined && origin !== `http://127.0.0.1:${String(port)}` && origin !== `http://localhost:${String(port)}`) { socket.end('HTTP/1.1 403 Forbidden\r\n\r\n'); return; }
|
|
171
|
+
const client: WatchSocket | null = acceptSocket(request, socket, () => { if (client !== null) clients.delete(client); });
|
|
172
|
+
if (client === null) return;
|
|
173
|
+
clients.add(client); client.send(state());
|
|
174
|
+
});
|
|
175
|
+
await new Promise<void>((_resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, '127.0.0.1', _resolve); });
|
|
176
|
+
|
|
177
|
+
// Edits: a native watch per top-level folder (and the root), plus a 250 ms stamp poll for what native events miss.
|
|
178
|
+
let observed = projectSourceStamp(source), work = Promise.resolve(), pending = false;
|
|
179
|
+
const reconcile = (): void => {
|
|
180
|
+
if (stopped || pending) return;
|
|
181
|
+
const next = projectSourceStamp(source);
|
|
182
|
+
if (next === observed) return;
|
|
183
|
+
observed = next; pending = true;
|
|
184
|
+
const run = async (): Promise<void> => {
|
|
185
|
+
pending = false;
|
|
186
|
+
try { if (!stopped) await compile(); } catch (cause) { log(`wildshard watch: ${cause instanceof Error ? cause.message : String(cause)}`); }
|
|
187
|
+
};
|
|
188
|
+
work = work.then(run);
|
|
189
|
+
};
|
|
190
|
+
const onChange = (prefix: string) => (_event: string, filename: string | null): void => {
|
|
191
|
+
if (`${prefix}${filename ?? ''}`.split(/[\\/]/u).some((part) => ignored.has(part))) return;
|
|
192
|
+
reconcile();
|
|
193
|
+
};
|
|
194
|
+
const watchers = [watch(source, onChange('')), ...readdirSync(source, { withFileTypes: true })
|
|
195
|
+
.filter((entry) => entry.isDirectory() && !ignored.has(entry.name))
|
|
196
|
+
.map((entry) => watch(join(source, entry.name), { recursive: true }, onChange(`${entry.name}/`)))];
|
|
197
|
+
const scope = new Scope('sdk.watch');
|
|
198
|
+
scope.interval(250, reconcile);
|
|
199
|
+
const address = server.address(); if (address === null || typeof address === 'string') throw new Error('No watch server address');
|
|
200
|
+
return { url: `http://127.0.0.1:${address.port}/`, close: async () => {
|
|
201
|
+
if (stopped) return;
|
|
202
|
+
stopped = true; scope.dispose();
|
|
203
|
+
for (const client of clients) client.close();
|
|
204
|
+
await new Promise<void>((_resolve) => { server.close(() => { _resolve(); }); server.closeAllConnections(); });
|
|
205
|
+
await work;
|
|
206
|
+
for (const watcher of watchers) watcher.close();
|
|
207
|
+
rmSync(scratch, { recursive: true, force: true });
|
|
208
|
+
} };
|
|
209
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
// AUTHORING-PARITY AP7: the slice is one scene module. `wildshard build` runs this as the shard's generator (the
|
|
2
|
+
// shardfile back end); `wildshard watch` calls its describe() and streams the parts to a running page.
|
|
3
|
+
import { defineShard } from '@wildshard/sdk/scene/shard';
|
|
4
|
+
import { buildSlice } from './world';
|
|
5
|
+
|
|
6
|
+
export const slice = defineShard({ slug: 'authoring-slice', name: 'Authoring Slice', author: 'Wildshard', revision: 1, seed: 357 }, buildSlice);
|