@wildshard/sdk 0.3.0 → 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 (60) 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/sharddev/as/prelude.ts +67 -0
  11. package/src/sharddev/authorLint.ts +45 -0
  12. package/src/sharddev/bake/compileScript.ts +6 -0
  13. package/src/sharddev/bake/terrain.ts +11 -2
  14. package/src/sharddev/checkProject.ts +7 -18
  15. package/src/sharddev/engineMusic.ts +23 -0
  16. package/src/sharddev/materials.ts +7 -3
  17. package/src/sharddev/project.ts +5 -0
  18. package/src/sharddev/refusals.ts +1 -1
  19. package/src/sharddev/scene/author.ts +116 -11
  20. package/src/sharddev/scene/canvas.ts +2 -3
  21. package/src/sharddev/scene/description.ts +55 -2
  22. package/src/sharddev/scene/lower.ts +144 -29
  23. package/src/sharddev/scene/shard.ts +5 -2
  24. package/src/sharddev/scene/shardfile.ts +365 -72
  25. package/src/sharddev/watch/page.ts +116 -29
  26. package/src/sharddev/watch/pageEntry.ts +38 -2
  27. package/src/sharddev/watch/parity-baseline.json +22 -0
  28. package/src/sharddev/watch/parity.mjs +168 -0
  29. package/src/sharddev/watch/proof.mjs +129 -22
  30. package/src/sharddev/watch/protocol.ts +66 -8
  31. package/src/sharddev/watch/watch.ts +215 -51
  32. package/src/shards/_template/assets/3058c100bc477fd6fe8268f33b53756b8a2556e7e41c58b2216c703ca7b042c6 +1 -0
  33. package/src/shards/_template/assets/8a0440f392737a31cf0926a3c7dc011c320144972882945a5462c893e817d94a +0 -0
  34. package/src/shards/_template/behaviour/door.as +16 -26
  35. package/src/shards/_template/card/landscape.jpg +0 -0
  36. package/src/shards/_template/card/portrait.jpg +0 -0
  37. package/src/shards/_template/card/thumb.jpg +0 -0
  38. package/src/shards/_template/data/clientScripts.json +43 -43
  39. package/src/shards/_template/data/creatures.json +2 -2
  40. package/src/shards/_template/data/look.json +141 -13
  41. package/src/shards/_template/data/rows.json +20 -2
  42. package/src/shards/_template/data/skins.json +32 -0
  43. package/src/shards/_template/data/water.json +18 -0
  44. package/src/shards/_template/generators/product.ts +5 -1
  45. package/src/shards/_template/generators/warden.ts +273 -0
  46. package/src/shards/_template/generators/world.ts +52 -21
  47. package/src/shards/_template/hero.json +6 -6
  48. package/src/shards/authoring-slice/generators/shard.ts +9 -1
  49. package/src/shards/authoring-slice/generators/sky.ts +64 -0
  50. package/src/shards/authoring-slice/generators/template-sky.ts +27 -0
  51. package/src/shards/authoring-slice/generators/textures.ts +59 -0
  52. package/src/shards/authoring-slice/generators/world.ts +108 -5
  53. package/src/shards/mossgate/generators/shard.ts +6 -0
  54. package/src/shards/mossgate/generators/sky.ts +64 -0
  55. package/src/shards/mossgate/generators/textures.ts +249 -0
  56. package/src/shards/mossgate/generators/world.ts +998 -0
  57. package/src/shards/mossgate/shard.config.ts +7 -0
  58. package/scripts/shard-output-report.d.mts +0 -9
  59. package/scripts/shard-output-report.mjs +0 -85
  60. package/scripts/shard-platform-cli.mjs +0 -93
package/GUIDE.md CHANGED
@@ -200,6 +200,13 @@ Blender files (`.blend`), mockups and other working files never ship: keep them
200
200
  runs in the game is data, or Wasm compiled from `behaviour/`. `shard.config.ts` and `generators/` run only at build
201
201
  time; lint refuses runtime code there (section 6).
202
202
 
203
+ **Behaviour scripts read and write by name.** A `behaviour/` script imports the sdk's prelude, `./wildshard`, which
204
+ build supplies: `shared(i)` and `player(i)` read state fields in their declared order, `eventCount()` and
205
+ `eventType(i)` read the call's events, and `setShared(id, value)`, `setPlayer`, `setField`, `emit`, `spawn` and
206
+ `moveTo` write its commands (four a call). Start `on_tick` with `begin()`, and re-export the ABI from it:
207
+ `export { abi_version, init, in_ptr, in_cap, out_ptr, out_cap, out_count } from './wildshard';`. The Template's
208
+ `behaviour/door.as` is the example. A script with its own addresses still builds.
209
+
203
210
  **Repo layout (J317).** A repo with one shard keeps its shard source at `src/` (`src/shard.config.ts`,
204
211
  `src/data/`, ...); a repo with several keeps `src/shards/<slug>/`. Commands take the repo (`.`) and find the shard
205
212
  source at `src/`, or at the one `src/shards/<slug>/` a repo holds; in a repo with several, name the shard source
@@ -727,11 +734,12 @@ message says which.
727
734
  ### Lint
728
735
 
729
736
  `check` lints the shard source with the sdk's rules. Each wildshard lint rule keeps a shard to data and build-time
730
- code; its printed fix says what to change.
737
+ code; its printed fix says what to change. In a shard repo it runs the repo's own `.oxlintrc.author.json` from the repo
738
+ root, as the repo's `pnpm lint` does (with its `lint/ratchet.json`); a repo without one skips lint and says so.
731
739
 
732
740
  #### lint-not-run
733
741
 
734
- The linter that ships with the sdk did not run. Reinstall the sdk.
742
+ The linter did not run: the repo's oxlint, or the one that ships with the sdk. Reinstall (`pnpm install`).
735
743
 
736
744
  #### lint-refused
737
745
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  <!-- generated by scripts/export-tiers.mjs from package.json exports and lint/export-tiers.json: do not edit -->
4
4
 
5
- 173 exports. A shard project imports from contract, rows, scripts and the bake kit; internal may change in any release. A new export needs a row in `lint/export-tiers.json` (`test/export-tiers.test.ts` fails without one); then run `node scripts/export-tiers.mjs`.
5
+ 176 exports. A shard project imports from contract, rows, scripts and the bake kit; internal may change in any release. A new export needs a row in `lint/export-tiers.json` (`test/export-tiers.test.ts` fails without one); then run `node scripts/export-tiers.mjs`.
6
6
 
7
7
  ## contract (28)
8
8
 
@@ -81,7 +81,7 @@ Content rows: typed helpers that write a section of the shardfile (species, ques
81
81
  | `@wildshard/sdk/weapons/thrownProfile` | rows | `./src/sharddev/weapons/thrownProfile.ts` |
82
82
  | `@wildshard/sdk/worldScenes` | rows | `./src/sharddev/worldScenes.ts` |
83
83
 
84
- ## scripts (17)
84
+ ## scripts (18)
85
85
 
86
86
  Scripts: the decision and client script compilers, their AssemblyScript helpers and the director ABI.
87
87
 
@@ -89,6 +89,7 @@ Scripts: the decision and client script compilers, their AssemblyScript helpers
89
89
  |---|---|---|
90
90
  | `@wildshard/sdk/as/groupBankV2` | scripts | `./src/sharddev/as/groupBankV2.ts` |
91
91
  | `@wildshard/sdk/as/groupStepV2` | scripts | `./src/sharddev/as/groupStepV2.ts` |
92
+ | `@wildshard/sdk/as/prelude` | scripts | `./src/sharddev/as/prelude.ts` |
92
93
  | `@wildshard/sdk/as/ws` | scripts | `./src/sharddev/as/ws.ts` |
93
94
  | `@wildshard/sdk/as/wsV2` | scripts | `./src/sharddev/as/wsV2.ts` |
94
95
  | `@wildshard/sdk/buildBehaviour` | scripts | `./src/sharddev/buildBehaviour.ts` |
@@ -105,7 +106,7 @@ Scripts: the decision and client script compilers, their AssemblyScript helpers
105
106
  | `@wildshard/sdk/directorAbi` | scripts | `./src/sharddev/directorAbi.ts` |
106
107
  | `@wildshard/sdk/returnProjectionV2` | scripts | `./src/sharddev/returnProjectionV2.ts` |
107
108
 
108
- ## bake kit (85)
109
+ ## bake kit (86)
109
110
 
110
111
  The bake kit: build-time geometry, texture, map and commons helpers; nothing here runs in the game.
111
112
 
@@ -162,6 +163,7 @@ The bake kit: build-time geometry, texture, map and commons helpers; nothing her
162
163
  | `@wildshard/sdk/bake/signPlacements` | bake kit | `./src/sharddev/bake/signPlacements.ts` |
163
164
  | `@wildshard/sdk/bake/simplifier` | bake kit | `./src/sharddev/bake/simplifier.ts` |
164
165
  | `@wildshard/sdk/bake/skinned` | bake kit | `./src/sharddev/bake/skinned.ts` |
166
+ | `@wildshard/sdk/bake/slabChunks` | bake kit | `./src/sharddev/bake/slabChunks.ts` |
165
167
  | `@wildshard/sdk/bake/slabs` | bake kit | `./src/sharddev/bake/slabs.ts` |
166
168
  | `@wildshard/sdk/bake/sourceMetadata` | bake kit | `./src/sharddev/bake/sourceMetadata.ts` |
167
169
  | `@wildshard/sdk/bake/species` | bake kit | `./src/sharddev/bake/species.ts` |
@@ -197,7 +199,7 @@ The bake kit: build-time geometry, texture, map and commons helpers; nothing her
197
199
  | `@wildshard/sdk/scene/shardfile` | bake kit | `./src/sharddev/scene/shardfile.ts` |
198
200
  | `@wildshard/sdk/watch/protocol` | bake kit | `./src/sharddev/watch/protocol.ts` |
199
201
 
200
- ## internal (8)
202
+ ## internal (9)
201
203
 
202
204
  Internal: exported for sharddev's own tools and tests; a shard project must not import it, and it may change in any release.
203
205
 
@@ -209,5 +211,6 @@ Internal: exported for sharddev's own tools and tests; a shard project must not
209
211
  | `@wildshard/sdk/scripts/*` | internal | `./scripts/*` |
210
212
  | `@wildshard/sdk/sourceReader` | internal | `./src/sharddev/sourceReader.ts` |
211
213
  | `@wildshard/sdk/test/compileDualScriptV2` | internal | `./src/sharddev/test/compileDualScriptV2.ts` |
214
+ | `@wildshard/sdk/test/scriptScenario` | internal | `./src/sharddev/test/scriptScenario.ts` |
212
215
  | `@wildshard/sdk/watch/page` | internal | `./src/sharddev/watch/page.ts` |
213
216
  | `@wildshard/sdk/watch/watch` | internal | `./src/sharddev/watch/watch.ts` |
@@ -147,6 +147,7 @@
147
147
  "./blobBytes": "contract",
148
148
  "./schemaValidation": "contract",
149
149
  "./outputProduct": "contract",
150
+ "./as/prelude": "scripts",
150
151
  "./as/ws": "scripts",
151
152
  "./as/wsV2": "scripts",
152
153
  "./decisionScriptBindings": "scripts",
@@ -172,6 +173,7 @@
172
173
  "./bake/nativeInteractionFacts": "bake kit",
173
174
  "./bake/geometryError": "bake kit",
174
175
  "./bake/slabs": "bake kit",
176
+ "./bake/slabChunks": "bake kit",
175
177
  "./bake/wholePieceJoin": "bake kit",
176
178
  "./configBoundary": "internal",
177
179
  "./executeBundle": "internal",
@@ -180,6 +182,7 @@
180
182
  "./commons/courseProgram": "bake kit",
181
183
  "./commons/scripts/course.as": "scripts",
182
184
  "./commons/bake/portableMath": "bake kit",
185
+ "./test/scriptScenario": "internal",
183
186
  "./scripts/*": "internal"
184
187
  }
185
188
  }
@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs';
3
3
  import { relative, resolve } from 'node:path';
4
4
  import ts from '@typescript/typescript6';
5
5
  import { hostPlayFile } from './host-files.mjs';
6
- import { formatSource } from '../scripts/format-package.mjs';
6
+ import { formatSource } from '@wildshard/engine/scripts/format-package.mjs';
7
7
 
8
8
  const projects = new Map();
9
9
  const localPath = (root, file) => relative(root, file).replaceAll('\\', '/');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wildshard/sdk",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "The author's toolbox: the `wildshard` CLI that bakes shard source into a shardfile, the author SDK, the local dev server (engine client against engine server), the explorers, arena and drafts tool.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -63,7 +63,8 @@
63
63
  "agents:sync": "node scripts/agent-sync.mjs",
64
64
  "md:wrap": "node kit/scripts/md-wrap.mjs",
65
65
  "test:hooks": "node --test '.githooks/*.test.mjs'",
66
- "check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm test && pnpm check:asks && pnpm check:agents && pnpm check:agent-sync && pnpm test:agent-hooks && pnpm check:parity && node --check scripts/chromium-keychain-check.mjs && node --test test/tooling/chrome-keychain.test.mjs test/tooling/worktree-guard.test.mjs",
66
+ "check": "pnpm typecheck && pnpm lint && pnpm format:check && pnpm test && pnpm check:watch-build && pnpm check:asks && pnpm check:agents && pnpm check:agent-sync && pnpm test:agent-hooks && pnpm check:parity && node --check scripts/chromium-keychain-check.mjs && node --test test/tooling/chrome-keychain.test.mjs test/tooling/worktree-guard.test.mjs",
67
+ "check:watch-build": "node src/sharddev/watch/parity.mjs --check",
67
68
  "typecheck:kit": "tsc -p src/tsconfig.json && tsc -p src/web/tsconfig.json",
68
69
  "typecheck:author": "tsc -p tsconfig.author.json",
69
70
  "lint:author": "WILDSHARD_RATCHET_FILE=lint/ratchet.json oxlint -c .oxlintrc.author.json --deny-warnings src/sharddev src/commons src/shards",
@@ -83,8 +84,8 @@
83
84
  "@types/three": "0.186.0",
84
85
  "@typescript/typescript6": "6.0.2",
85
86
  "@valibot/to-json-schema": "1.8.0",
86
- "@wildshard/engine": "0.1.19",
87
- "@wildshard/format": "npm:@wildshard/shard-format@0.5.3",
87
+ "@wildshard/engine": "0.1.21",
88
+ "@wildshard/format": "npm:@wildshard/shard-format@0.5.7",
88
89
  "ajv": "6.15.0",
89
90
  "assemblyscript": "0.28.20",
90
91
  "binaryen": "132.0.0",
@@ -201,7 +202,7 @@
201
202
  "overrides": {
202
203
  "binaryen": "npm:@pre-bundled/binaryen@132.0.0-patch-1",
203
204
  "assemblyscript>binaryen": "npm:@pre-bundled/binaryen@131.0.0-nightly.20260721-patch-1",
204
- "@wildshard/format": "npm:@wildshard/shard-format@0.5.3"
205
+ "@wildshard/format": "npm:@wildshard/shard-format@0.5.7"
205
206
  }
206
207
  },
207
208
  "exports": {
@@ -298,7 +299,9 @@
298
299
  "./species/clips": "./src/sharddev/species/clips.ts",
299
300
  "./compileScript": "./src/sharddev/bake/compileScript.ts",
300
301
  "./compileScriptV2": "./src/sharddev/bake/compileScriptV2.ts",
302
+ "./bake/slabChunks": "./src/sharddev/bake/slabChunks.ts",
301
303
  "./test/compileDualScriptV2": "./src/sharddev/test/compileDualScriptV2.ts",
304
+ "./test/scriptScenario": "./src/sharddev/test/scriptScenario.ts",
302
305
  "./buildBehaviour": "./src/sharddev/buildBehaviour.ts",
303
306
  "./scene": "./src/sharddev/scene.ts",
304
307
  "./scene/shard": "./src/sharddev/scene/shard.ts",
@@ -344,6 +347,7 @@
344
347
  "./blobBytes": "./src/sharddev/blobBytes.ts",
345
348
  "./schemaValidation": "./src/sharddev/schemaValidation.ts",
346
349
  "./outputProduct": "./src/sharddev/outputProduct.ts",
350
+ "./as/prelude": "./src/sharddev/as/prelude.ts",
347
351
  "./as/ws": "./src/sharddev/as/ws.ts",
348
352
  "./as/wsV2": "./src/sharddev/as/wsV2.ts",
349
353
  "./decisionScriptBindings": "./src/sharddev/decisionScriptBindings.ts",
@@ -3,7 +3,7 @@
3
3
  // (public/assets/baked/skin-fixture, made by scripts/bake/skins.mjs) into the template's content-addressed assets: each
4
4
  // GLB, plus one `json` skin file ({ row, binding }) that depends on it, and writes data/skins.json for shard.config.ts.
5
5
  // P1-S1: it lives in scripts/, beside the fixture's own producer, since that fixture stays when the template moves out.
6
- import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
6
+ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
7
7
  import { createHash } from 'node:crypto';
8
8
  import { resolve } from 'node:path';
9
9
 
@@ -29,5 +29,8 @@ const out = species.map(({ species: id, look, skin }) => {
29
29
  { hash: row.file, kind: 'glb', compressed: glb.length, decoded: row.cost.decoded, gpu: row.cost.gpu, triangles: row.cost.triangles, draws: row.cost.draws, dependencies: [], critical: false },
30
30
  ] };
31
31
  });
32
- writeFileSync(resolve(project, 'data/skins.json'), `${JSON.stringify(out, null, 2)}\n`);
33
- console.info(`template skins: ${out.map((entry) => `${entry.species} ${entry.skin.slice(0, 8)}`).join(', ')}`);
32
+ // entries this script does not make (the Barrow Warden, scripts/bake/template-warden.mjs) stay, after the fixture's
33
+ const path = resolve(project, 'data/skins.json'), made = new Set(out.map((entry) => entry.species));
34
+ const kept = (existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : []).filter((entry) => !made.has(entry.species));
35
+ writeFileSync(path, `${JSON.stringify([...out, ...kept], null, 2)}\n`);
36
+ console.info(`template skins: ${out.map((entry) => `${entry.species} ${entry.skin.slice(0, 8)}`).join(', ')}${kept.length === 0 ? '' : `; kept ${kept.map((entry) => entry.species).join(', ')}`}`);
@@ -0,0 +1,25 @@
1
+ #!/usr/bin/env node
2
+ // SHARD-SOURCE M4.10: bake the Template's Barrow Warden skin (src/shards/_template/generators/warden.ts) into its
3
+ // content-addressed assets (the GLB and its { row, binding } skin file) and its data/skins.json entry. The generator is
4
+ // TypeScript, so it is bundled first, as scripts/bake/skins.mjs bundles the skin fixture; generators/warden.test.ts
5
+ // re-bakes and refuses committed bytes that differ.
6
+ import { build } from 'vite';
7
+ import { mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
8
+ import { join, resolve } from 'node:path';
9
+ import { pathToFileURL } from 'node:url';
10
+
11
+ const repo = resolve(import.meta.dirname, '../..'), project = resolve(repo, 'src/shards/_template'), scratch = resolve(repo, `tmp/bake-warden-${process.pid}`);
12
+ try {
13
+ mkdirSync(scratch, { recursive: true }); symlinkSync(join(repo, 'node_modules'), join(scratch, 'node_modules'));
14
+ await build({ configFile: false, logLevel: 'silent', build: { target: 'esnext', outDir: join(scratch, 'generator'), emptyOutDir: true, lib: { entry: join(project, 'generators/warden.ts'), formats: ['es'], fileName: 'warden' }, rolldownOptions: { platform: 'node', external: [/^node:/u, 'vite', '@gltf-transform/core', '@gltf-transform/extensions', 'meshoptimizer'] } } });
15
+ const { bakeWardenSkin } = await import(pathToFileURL(join(scratch, 'generator/warden.js')).href);
16
+ const { glb, json, entry } = await bakeWardenSkin();
17
+ writeFileSync(resolve(project, 'assets', entry.glb), glb); writeFileSync(resolve(project, 'assets', entry.skin), json);
18
+ const path = resolve(project, 'data/skins.json'), skins = JSON.parse(readFileSync(path, 'utf8')), at = skins.findIndex((row) => row.species === entry.species);
19
+ const previous = at === -1 ? undefined : skins[at];
20
+ if (at === -1) skins.push(entry); else skins[at] = entry;
21
+ writeFileSync(path, `${JSON.stringify(skins, null, 2)}\n`);
22
+ for (const hash of [previous?.glb, previous?.skin]) if (hash !== undefined && hash !== entry.glb && hash !== entry.skin) rmSync(resolve(project, 'assets', hash), { force: true });
23
+ const glbRow = entry.files[1];
24
+ console.info(`template warden: skin ${entry.skin.slice(0, 8)}, glb ${entry.glb.slice(0, 8)} (${glb.length} bytes, ${glbRow.triangles} triangles, ${glbRow.draws} draws)`);
25
+ } finally { rmSync(scratch, { recursive: true, force: true }); }
@@ -0,0 +1,89 @@
1
+ import { mkdirSync, writeFileSync } from 'node:fs';
2
+ import { resolve } from 'node:path';
3
+ import { returnProjectionV2Layout } from '@wildshard/format/returnProjectionV2';
4
+ import { compileScript } from '../src/sharddev/bake/compileScript.ts';
5
+ import { compileScriptV2 } from '../src/sharddev/bake/compileScriptV2.ts';
6
+ import { v2CoreSource } from '../src/sharddev/as/wsV2.ts';
7
+
8
+ const target = resolve(process.argv[2] ?? '../engine/test/fixtures/wasm');
9
+ const ioBytes = returnProjectionV2Layout(2).bytes;
10
+ const source = `import * as core from './core';
11
+ export function ws_abi():i32{return 2;}export function ws_io():i32{return 0;}
12
+ export function ws_init(lo:i32,hi:i32,fuel:i32):i32{return fuel;}
13
+ export function ws_project(fuel:i32):i32{
14
+ core.beginState();assert(core.beginBinding(0));
15
+ core.pageOutput(2,core.field(0));core.pageOutput(1,core.parameter(0));
16
+ core.endBinding();return fuel;
17
+ }`;
18
+
19
+ mkdirSync(target, { recursive: true });
20
+ const bytes = await compileScriptV2(source, { lane: 'project', ioBytes, sources: { 'core.ts': v2CoreSource(0) } });
21
+ writeFileSync(resolve(target, 'return-projection-template.wasm'), bytes);
22
+ writeFileSync(resolve(target, 'return-projection-template.json'), `${JSON.stringify({ source, fixture: 'return-projection-template.wasm', ioBytes }, null, 2)}\n`);
23
+
24
+ const groupRngSource = `import * as core from './sdk/as/wsV2';
25
+ export function ws_abi():i32{return 2;}export function ws_io():i32{return 0;}
26
+ export function ws_init(lo:i32,hi:i32,fuel:i32):i32{return fuel;}
27
+ export function ws_project(fuel:i32):i32{core.beginState();assert(core.beginBinding(0));
28
+ core.setState(0,core.random(1));core.setState(1,core.random(2));
29
+ core.setState(2,core.random(1));core.setState(3,core.random(2));
30
+ if(core.parameter(0)==2)core.pageOutput(99);
31
+ core.endBinding();return fuel;}`;
32
+ const groupRngIoBytes = 1216;
33
+ writeFileSync(resolve(target, 'script-v2-group-rng.wasm'), await compileScriptV2(groupRngSource, {
34
+ lane: 'project', ioBytes: groupRngIoBytes, sources: { 'sdk/as/wsV2.ts': v2CoreSource(0) },
35
+ }));
36
+ writeFileSync(resolve(target, 'script-v2-group-rng.json'), `${JSON.stringify({ source: groupRngSource, fixture: 'script-v2-group-rng.wasm', ioBytes: groupRngIoBytes }, null, 2)}\n`);
37
+
38
+ const groupMembersSource = `import * as core from './sdk/as/wsV2';
39
+ export function ws_abi():i32{return 2;}export function ws_io():i32{return 0;}
40
+ export function ws_init(lo:i32,hi:i32,fuel:i32):i32{return fuel;}
41
+ export function ws_project(fuel:i32):i32{core.beginState();assert(core.beginBinding(0));
42
+ core.setState(0,core.state(0)+1);const signal=i32(core.parameter(0));
43
+ if(signal==4){core.pageOutput(6,3,4);core.pageOutput(2,0,1);core.endBinding();return fuel;}
44
+ core.pageOutput(1,0,core.field(1),signal==3?2:core.field(0));
45
+ core.pageOutput(2,0,signal==2?99:1);core.pageOutput(3,0,1.2,2.3,3.4);
46
+ core.pageOutput(4,0,6,7,8);core.pageOutput(5,0,.5);core.pageOutput(6,3,4);
47
+ core.endBinding();return fuel;}`;
48
+ const groupMembersIoBytes = 1408;
49
+ writeFileSync(resolve(target, 'script-v2-group-members.wasm'), await compileScriptV2(groupMembersSource, {
50
+ lane: 'project', ioBytes: groupMembersIoBytes, sources: { 'sdk/as/wsV2.ts': v2CoreSource(0) },
51
+ }));
52
+ writeFileSync(resolve(target, 'script-v2-group-members.json'), `${JSON.stringify({ source: groupMembersSource, fixture: 'script-v2-group-members.wasm', ioBytes: groupMembersIoBytes }, null, 2)}\n`);
53
+
54
+ const legacyGuests = {
55
+ 'script-call-results': `let calls:i32=0;
56
+ export function abi_version():i32{return 0;}
57
+ export function init(lo:i32,hi:i32):void{calls=lo;}
58
+ export function in_ptr():i32{return 16384;}export function in_cap():i32{return 4096;}
59
+ export function out_ptr():i32{return 24576;}export function out_cap():i32{return 32;}
60
+ export function out_count():i32{return 2;}
61
+ export function on_tick():void{
62
+ calls++;let value=load<f64>(16416);if(value==99)unreachable();
63
+ store<f64>(24576,1);store<f64>(24584,1);store<f64>(24592,value);
64
+ store<f64>(24616,3);store<f64>(24624,9);store<f64>(24632,1);store<f64>(24640,load<f64>(16384));
65
+ }`,
66
+ 'script-lane-results': `let calls:i32=0;
67
+ export function abi_version():i32{return 0;}
68
+ export function init(lo:i32,hi:i32):void{calls=lo;}
69
+ export function in_ptr():i32{return 16384;}export function in_cap():i32{return 4096;}
70
+ export function out_ptr():i32{return 24576;}export function out_cap():i32{return 32;}
71
+ export function out_count():i32{return 2;}
72
+ export function on_tick():void{
73
+ calls++;let value=load<f64>(16400);if(value==99)unreachable();
74
+ store<f64>(24576,1);store<f64>(24584,1);store<f64>(24592,value);
75
+ store<f64>(24616,3);store<f64>(24624,9);store<f64>(24632,1);store<f64>(24640,load<f64>(16384));
76
+ }`,
77
+ 'script-virgin-memory': `let value:i32=0;
78
+ export function abi_version():i32{return 0;}
79
+ export function init(lo:i32,hi:i32):void{value=lo;store<i32>(32768,value);}
80
+ export function in_ptr():i32{return 16384;}export function in_cap():i32{return 4096;}
81
+ export function out_ptr():i32{return 24576;}export function out_cap():i32{return 32;}
82
+ export function out_count():i32{return 0;}
83
+ export function on_tick():void{value++;store<i32>(32768,value);}`,
84
+ };
85
+ for (const [name, guest] of Object.entries(legacyGuests)) {
86
+ const maximumPages = name === 'script-virgin-memory' ? 2 : 1;
87
+ writeFileSync(resolve(target, `${name}.wasm`), await compileScript(guest, { maximumPages }));
88
+ }
89
+ writeFileSync(resolve(target, 'legacy-guests.json'), `${JSON.stringify({ legacyGuests }, null, 2)}\n`);
@@ -6,7 +6,8 @@
6
6
  //
7
7
  // It looks at each folder directly under <repo>/tmp/ and would remove one in which nothing (the folder or anything in
8
8
  // it) changed for <n> days (3 by default), with or without a DK3 `.owner`. It keeps:
9
- // - a folder holding `.keep`, or named in `tmp/keep` (one name per line, `#` comments);
9
+ // - a folder holding `.keep`, or named in `tmp/keep` (one name per line, `#` comments); `tmp/keep` itself when it is a
10
+ // folder (singleplayer keeps hand-kept work there);
10
11
  // - a folder that is, or holds, some process's cwd (lsof -d cwd; /proc on Linux); an unreadable table keeps all;
11
12
  // - a folder holding a Git root with dirty files or commits no remote has (DS14's list: the reason names the root);
12
13
  // - dot folders, symlinks, and `tmp/vitest` (vite-tmp.mjs's own).
@@ -124,6 +125,7 @@ export function plan({ root, days = DEFAULT_DAYS, cwds = processCwds() }) {
124
125
  const keep = reason => rows.push({ name, action: /** @type {const} */ ('keep'), reason });
125
126
  if (stat(join(dir, '.keep')) !== null) keep('.keep');
126
127
  else if (kept.has(name)) keep('tmp/keep');
128
+ else if (name === 'keep') keep('tmp/keep is a folder of kept work');
127
129
  else if (real === undefined || real === null) keep('process table unreadable');
128
130
  else if (real.some(cwd => cwd === at || cwd.startsWith(at + sep))) keep('busy: a process cwd inside');
129
131
  else if (touched(dir, days)) keep(`changed within ${String(days)} days`);
@@ -0,0 +1,67 @@
1
+ /** The ABI-v0 script prelude (meta SHARD-SOURCE AP27): a behaviour script's input slots, events and commands by name, so
2
+ * no script reads or writes a literal address. `compileScript` hands it to the compiler as `wildshard.ts` for every ABI-v0
3
+ * script (a script that does not import it compiles to the same bytes), unless the shard supplies its own `wildshard.ts`.
4
+ * It is a source string so guest globals never enter the host TypeScript program. */
5
+ export const SCRIPT_PRELUDE: string = String.raw`
6
+ // The sdk's script prelude for ABI v0 (SHARD-SOURCE AP27): a behaviour script's input, events and commands by name, so
7
+ // no script reads or writes a literal address. Import its helpers from './wildshard'; the entry file re-exports the ABI:
8
+ // export { abi_version, init, in_ptr, in_cap, out_ptr, out_cap, out_count } from './wildshard';
9
+ // The sdk hands this file to the compiler as 'wildshard.ts'; a shard's own 'wildshard.ts' source replaces it.
10
+ const IN: i32 = 16384, IN_CAP: i32 = 4096, OUT: i32 = 24576, OUT_CAP: i32 = 4, RECORD: i32 = 40;
11
+ let count: i32 = 0;
12
+ export function abi_version(): i32 { return 0; }
13
+ export function init(lo: i32, hi: i32): void {}
14
+ export function in_ptr(): i32 { return IN; }
15
+ export function in_cap(): i32 { return IN_CAP; }
16
+ export function out_ptr(): i32 { return OUT; }
17
+ /** Commands one call may write: four. */
18
+ export function out_cap(): i32 { return OUT_CAP; }
19
+ export function out_count(): i32 { return count; }
20
+ /** Start a call's commands over: the first line of 'on_tick'. */
21
+ export function begin(): void { count = 0; }
22
+
23
+ /** Input slot 'i' (0 to 31) as the host wrote it. */
24
+ @inline export function input(i: i32): f64 { assert(i >= 0 && i < 32); return load<f64>(IN + i * 8); }
25
+ /** The fixed tick, the seconds it covers, the actor's command, this entity's content handle, the actor's token, and
26
+ * the role (0 server, 1 client). */
27
+ @inline export function tick(): f64 { return input(0); }
28
+ @inline export function dt(): f64 { return input(1); }
29
+ @inline export function command(): f64 { return input(2); }
30
+ @inline export function self(): f64 { return input(3); }
31
+ @inline export function actor(): f64 { return input(4); }
32
+ @inline export function role(): f64 { return input(5); }
33
+ /** How many shared and player fields the shard declares. */
34
+ @inline export function sharedCount(): i32 { return i32(input(6)); }
35
+ @inline export function playerCount(): i32 { return i32(input(7)); }
36
+ /** Shared field 'index' (0 first), in the order 'state.shared' declares them. */
37
+ @inline export function shared(index: i32): f64 { assert(index >= 0 && index < sharedCount()); return input(8 + index); }
38
+ /** The calling actor's player field 'index', in the order 'state.player' declares them. */
39
+ @inline export function player(index: i32): f64 { assert(index >= 0 && index < playerCount()); return input(8 + sharedCount() + index); }
40
+
41
+ /** The events delivered this call, each a type (a 'hooks.scenes' row's 'type'), its target and its value. */
42
+ @inline export function eventCount(): i32 { return i32(load<f64>(IN + 32 * 8)); }
43
+ @inline function eventSlot(i: i32, k: i32): f64 { assert(i >= 0 && i < eventCount()); return load<f64>(IN + (33 + i * 6 + k) * 8); }
44
+ @inline export function eventType(i: i32): f64 { return eventSlot(i, 0); }
45
+ @inline export function eventTarget(i: i32): f64 { return eventSlot(i, 1); }
46
+ @inline export function eventValue(i: i32): f64 { return eventSlot(i, 2); }
47
+
48
+ /** One command record; a fifth in one call traps (the host would refuse it). */
49
+ function write(op: f64, a: f64, b: f64, c: f64, d: f64): void {
50
+ assert(count < OUT_CAP);
51
+ const at = OUT + count * RECORD;
52
+ store<f64>(at, op); store<f64>(at + 8, a); store<f64>(at + 16, b); store<f64>(at + 24, c); store<f64>(at + 32, d);
53
+ count += 1;
54
+ }
55
+ /** Set this entity's field 'id' (a 'fields' row) to 'value'. */
56
+ export function setField(id: f64, value: f64): void { write(1, id, value, 0, 0); }
57
+ /** Spawn a declared archetype at a position. */
58
+ export function spawn(archetype: f64, x: f64, y: f64, z: f64): void { write(2, archetype, x, y, z); }
59
+ /** Send a declared event to an entity, delivered next tick. */
60
+ export function emit(type: f64, target: f64, value: f64): void { write(3, type, target, value, 0); }
61
+ /** Move this entity. */
62
+ export function moveTo(x: f64, y: f64, z: f64): void { write(4, x, y, z, 0); }
63
+ /** Set shared field 'id' (a 'state.shared' row's id) to 'value': every player sees it. */
64
+ export function setShared(id: f64, value: f64): void { write(5, id, value, 0, 0); }
65
+ /** Set the calling actor's player field 'id' to 'value'. */
66
+ export function setPlayer(id: f64, value: f64): void { write(6, id, value, 0, 0); }
67
+ `;
@@ -0,0 +1,45 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- Find the repo's and the SDK's lint config and oxlint on disk.
2
+ import { existsSync } from 'node:fs';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- Find oxlint the way the repo (or this package) resolves it.
4
+ import { createRequire } from 'node:module';
5
+ // oxlint-disable-next-line import/no-nodejs-modules -- Resolve the repo root, its config and the linted folder.
6
+ import { dirname, relative, resolve } from 'node:path';
7
+ import { shardRepoRoot } from './shardSource';
8
+
9
+ /** How `wildshard check` runs the author lint for one project, or why it skips it. */
10
+ export type AuthorLintPlan =
11
+ | { readonly kind: 'run'; readonly bin: string; readonly cwd: string; readonly args: readonly string[]; readonly env: Readonly<Record<string, string>> }
12
+ | { readonly kind: 'skip'; readonly note: string };
13
+
14
+ export const AUTHOR_LINT_CONFIG = '.oxlintrc.author.json';
15
+
16
+ /** The oxlint binary `root`'s package resolves, if it has one. */
17
+ export function oxlintFrom(root: string): string | undefined {
18
+ try {
19
+ const manifest = createRequire(resolve(root, 'package.json')).resolve('oxlint/package.json');
20
+ const bin = resolve(dirname(manifest), 'bin/oxlint');
21
+ return existsSync(bin) ? bin : undefined;
22
+ } catch { return undefined; }
23
+ }
24
+
25
+ /**
26
+ * SS3 follow-up: a shard repo's own author lint first. Every shard repo carries `.oxlintrc.author.json` (its jsPlugins are
27
+ * the installed engine's and sdk's lint plugins, under `./node_modules`) and lints `src` with it from its root; oxlint
28
+ * matches a config's `overrides` against paths under the config's folder, so the wildshard rules hold only when the
29
+ * config sits in the repo. `check` runs that same lint, with the repo's oxlint and `lint/ratchet.json`, so an npm-installed
30
+ * sdk lints too. Without one, the SDK's own config (a sharddev checkout); without either, a skip that names the fix.
31
+ */
32
+ export function authorLintPlan(projectPath: string, sdkRoot: string, findOxlint: (root: string) => string | undefined = oxlintFrom): AuthorLintPlan {
33
+ const project = resolve(projectPath), root = shardRepoRoot(project), repoConfig = resolve(root, AUTHOR_LINT_CONFIG);
34
+ if (resolve(root) !== resolve(sdkRoot) && existsSync(repoConfig)) {
35
+ const bin = findOxlint(root) ?? findOxlint(sdkRoot);
36
+ if (bin === undefined) return { kind: 'skip', note: `oxlint is installed neither in ${root} nor with this @wildshard/sdk, so ${AUTHOR_LINT_CONFIG} cannot run` };
37
+ const ratchet = resolve(root, 'lint/ratchet.json');
38
+ return { kind: 'run', bin, cwd: root, args: ['-c', repoConfig, '--format', 'json', relative(root, project) || '.'],
39
+ env: existsSync(ratchet) ? { WILDSHARD_RATCHET_FILE: ratchet } : {} };
40
+ }
41
+ const sdkConfig = resolve(sdkRoot, AUTHOR_LINT_CONFIG), bin = findOxlint(sdkRoot);
42
+ // The SDK's jsPlugins resolve engine from the working directory: run from the SDK root, as `pnpm lint:author` does.
43
+ if (bin !== undefined && existsSync(sdkConfig)) return { kind: 'run', bin, cwd: sdkRoot, args: ['-c', sdkConfig, '--format', 'json', project], env: {} };
44
+ return { kind: 'skip', note: `no author lint: ${root} has no ${AUTHOR_LINT_CONFIG} (a shard repo's lints src with the engine's and the sdk's lint plugins)` };
45
+ }
@@ -2,6 +2,10 @@
2
2
  import binaryen from 'binaryen';
3
3
  import { loadAssemblyScriptCompiler } from '../assemblyscriptCompiler.mjs';
4
4
  import type { AssemblyScriptMemo } from './assemblyscriptMemoPort';
5
+ import { SCRIPT_PRELUDE } from '../as/prelude';
6
+
7
+ /** The prelude's virtual file name. */
8
+ const PRELUDE = 'wildshard.ts';
5
9
 
6
10
  interface Compiler { main: (args: string[], options: { readFile: (name: string) => string | null; writeFile: (name: string, contents: string | Uint8Array) => void }) => Promise<{ error: Error | null; stderr?: { toString: () => string } }> }
7
11
  function isCompiler(value: unknown): value is Compiler { return typeof value === 'object' && value !== null && 'main' in value && typeof value.main === 'function'; }
@@ -98,6 +102,8 @@ export async function compileScript(source: string, options: { abi?: 0 | 1; maxi
98
102
  const ceiling = options.abi === 1 ? 4 : 64;
99
103
  if (!Number.isSafeInteger(maximumPages) || maximumPages < 1 || maximumPages > ceiling) throw new Error(`Script maximumPages must be 1..${ceiling}`);
100
104
  const sources = new Map(Object.entries(options.sources ?? {}));
105
+ // AP27: ABI v0's prelude, `import { ... } from './wildshard'`; a script that never imports it never reads it (same bytes)
106
+ if (options.abi !== 1 && !sources.has(PRELUDE)) sources.set(PRELUDE, SCRIPT_PRELUDE);
101
107
  if (sources.size > 64 || [...sources].some(([name, text]) => name === 'main.ts' || !/^(?:[a-zA-Z0-9_-][a-zA-Z0-9_.-]*\/)*[a-zA-Z0-9_-][a-zA-Z0-9_.-]*\.ts$/u.test(name) || typeof text !== 'string')) throw new Error('Invalid virtual AssemblyScript sources');
102
108
  // asc's declaration bundle globally changes Array.at to return T, unsound in host JS.
103
109
  // Keep its portable ambient declarations inside the author compiler, not the host type program.
@@ -122,8 +122,11 @@ export interface BakedTerrain {
122
122
  critical: string[]; assets: Map<string, Uint8Array>;
123
123
  }
124
124
 
125
- /** Bake a shared 257² lattice into 64 L0 and 16 L1 tiles, with an independent whole-sim collision file. */
126
- export function bakeTerrain(source: TerrainBakeSource): BakedTerrain {
125
+ /**
126
+ * The shared 257² lattice (heights and colours, 500 m centred on the origin) every tile and the collider are cut from.
127
+ * `wildshard watch` (AP18) sends it whole, as one terrain tile's wire bytes, to a page's dev hook.
128
+ */
129
+ export function groundLattice(source: Pick<TerrainBakeSource, 'heightAt' | 'colourAt' | 'overrides'>): TerrainTileData & { colours: Float32Array } {
127
130
  for (const patch of source.overrides ?? []) if (![patch.x, patch.z, patch.radius, patch.height].every(Number.isFinite) || patch.radius <= 0 || patch.x < -250 || patch.x > 250 || patch.z < -250 || patch.z > 250 || patch.height < -CELL_BELOW || patch.height > CELL_ABOVE || !['replace', 'lower', 'raise'].includes(patch.mode)) throw new Error('Invalid terrain override');
128
131
  const heights = new Float32Array(257 ** 2), colours = new Float32Array(257 ** 2 * 3);
129
132
  for (let z = 0; z < 257; z++) for (let x = 0; x < 257; x++) {
@@ -140,6 +143,12 @@ export function bakeTerrain(source: TerrainBakeSource): BakedTerrain {
140
143
  if (rgb.length !== 3 || rgb.some((c) => !Number.isFinite(c) || c < 0 || c > 1)) throw new Error('Invalid terrain generator colour');
141
144
  colours.set(rgb, i * 3);
142
145
  }
146
+ return { resolution: 257, x: -250, z: -250, size: 500, heights, colours };
147
+ }
148
+
149
+ /** Bake a shared 257² lattice into 64 L0 and 16 L1 tiles, with an independent whole-sim collision file. */
150
+ export function bakeTerrain(source: TerrainBakeSource): BakedTerrain {
151
+ const { heights, colours } = groundLattice(source);
143
152
  const grid: TerrainTileData = { resolution: 257, x: -250, z: -250, size: 500, heights };
144
153
  const assets = new Map<string, Uint8Array>(), files: Shardfile['files'] = [];
145
154
  const store = (data: TerrainTileData, critical: boolean): string => {
@@ -1,12 +1,10 @@
1
1
  // The real steps behind `wildshard check` (SA4); check.ts runs them in order and gives the verdict.
2
- // oxlint-disable-next-line import/no-nodejs-modules -- Lint runs the SDK's own oxlint as a child process.
2
+ // oxlint-disable-next-line import/no-nodejs-modules -- Lint runs oxlint (the repo's or the SDK's) as a child process.
3
3
  import { spawnSync } from 'node:child_process';
4
4
  // oxlint-disable-next-line import/no-nodejs-modules -- The author proof tape is an explicit local input file.
5
5
  import { existsSync, readFileSync } from 'node:fs';
6
- // oxlint-disable-next-line import/no-nodejs-modules -- Find oxlint the way this installed package resolves it.
7
- import { createRequire } from 'node:module';
8
6
  // oxlint-disable-next-line import/no-nodejs-modules -- Resolve the project, its output and the SDK's lint config.
9
- import { basename, dirname, resolve } from 'node:path';
7
+ import { basename, resolve } from 'node:path';
10
8
  import * as v from 'valibot';
11
9
  import { AuthorProofPlanSchema } from '@wildshard/engine/host/tickProtocol';
12
10
  import { measureSimulation, proveAuthorSimulation } from '@wildshard/engine/host/headless';
@@ -21,6 +19,7 @@ import type { ProjectManifestSource } from './projectManifest';
21
19
  import { authorErrorText } from './authorError';
22
20
  import { refusalCode } from './refusals';
23
21
  import { DRAFT_SDK, draftMessage } from './draft';
22
+ import { authorLintPlan } from './authorLint';
24
23
 
25
24
  /** The author proof tape `check` runs when the project has one (format: `AuthorProofPlanSchema`). */
26
25
  export const PROOF_FILE = 'proof.json';
@@ -32,22 +31,12 @@ export function readProofTape(path: string): v.InferOutput<typeof AuthorProofPla
32
31
  const unmeasured: PerformanceObservations = { scripts: { p95Micros: 0, maxMicros: 0, samples: 0 }, fuel: { p95: 0, max: 0, samples: 0 } };
33
32
  // The bundled CLI defines import.meta.dirname as the package's src/sharddev, so the package root is two up.
34
33
  const SDK_ROOT = resolve(import.meta.dirname, '../..');
35
- const LINT_CONFIG = resolve(SDK_ROOT, '.oxlintrc.author.json');
36
34
 
37
- function oxlintBin(): string | undefined {
38
- try {
39
- const manifest = createRequire(resolve(SDK_ROOT, 'package.json')).resolve('oxlint/package.json');
40
- const bin = resolve(dirname(manifest), 'bin/oxlint');
41
- return existsSync(bin) ? bin : undefined;
42
- } catch { return undefined; }
43
- }
44
-
45
- /** The SDK's author lint (`.oxlintrc.author.json` and its wildshard rules) over the project's source. */
35
+ /** The author lint over the project's source: its repo's `.oxlintrc.author.json`, else the SDK's (authorLint.ts). */
46
36
  function lintProject(project: string): StepOutcome {
47
- const bin = oxlintBin();
48
- if (bin === undefined || !existsSync(LINT_CONFIG)) return { status: 'skip', note: 'the author lint (oxlint and .oxlintrc.author.json) is not installed with this @wildshard/sdk' };
49
- // The jsPlugins resolve engine from the working directory: run from the SDK root, as `pnpm lint:author` does.
50
- const done = spawnSync(bin, ['-c', LINT_CONFIG, '--format', 'json', project], { cwd: SDK_ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
37
+ const plan = authorLintPlan(project, SDK_ROOT);
38
+ if (plan.kind === 'skip') return { status: 'skip', note: plan.note };
39
+ const done = spawnSync(plan.bin, plan.args, { cwd: plan.cwd, env: { ...process.env, ...plan.env }, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
51
40
  if (done.error !== undefined) return { status: 'fail', refusals: [{ message: `oxlint did not run: ${done.error.message}` }] };
52
41
  return lintOutcome(`${done.stdout}${done.stdout.trim() === '' ? done.stderr : ''}`, done.status);
53
42
  }
@@ -0,0 +1,23 @@
1
+ import { ENGINE_MUSIC_STYLE, engineMusicFiles, musicDir } from '@wildshard/engine/audio/bootAudio';
2
+ import { withAssetTables, type AssetTables } from '@wildshard/engine/boot/tables';
3
+ import { MUSIC_MANIFESTS, SFX_MANIFESTS } from '@wildshard/engine/game/boot/audio.generated';
4
+ import { PUBLIC_BYTES } from '@wildshard/engine/game/boot/bytes.generated';
5
+ import { ASSET_VERSIONS } from '@wildshard/engine/game/boot/versions.generated';
6
+ import { PACKS } from '@wildshard/engine/game/boot/packs.generated';
7
+ import type { AudioData } from '@wildshard/format/audio';
8
+
9
+ /** The engine's own boot tables, as the page installs them: which engine music ships, and each file's bytes. */
10
+ export const ENGINE_TABLES: AssetTables = { bytes: PUBLIC_BYTES, versions: ASSET_VERSIONS, music: MUSIC_MANIFESTS, sfx: SFX_MANIFESTS, packs: PACKS };
11
+
12
+ /** AUDIO AU18: the build log's line for the engine music a shard plays, derived from its `audio/audio` rows by name,
13
+ * in the engine cook's `engineMusicLine` format. Undefined when the shard has no audio section. Throws, naming each,
14
+ * when the rows name engine music this engine's style lacks. */
15
+ export function engineMusicLine(shard: string, section: unknown, tables: AssetTables = ENGINE_TABLES): string | undefined {
16
+ if (typeof section !== 'object' || section === null || !('audio' in section)) return undefined;
17
+ const data = section.audio as AudioData, dir = musicDir(ENGINE_MUSIC_STYLE);
18
+ let files: string[];
19
+ try { files = withAssetTables(tables, () => engineMusicFiles(data)); }
20
+ catch (error) { throw new Error(`${shard}: ${error instanceof Error ? error.message : String(error)}`, { cause: error }); }
21
+ const bytes = files.reduce((sum, url) => sum + (tables.bytes[url] ?? 0), 0);
22
+ return `${shard}: engine music: ${files.length} files, ${(bytes / 1e6).toFixed(2)} MB${files.length === 0 ? '' : ` (${files.map(url => url.slice(dir.length)).join(', ')})`}`;
23
+ }
@@ -150,7 +150,9 @@ readonly skyLightDirection: Node<"vec3">;
150
150
  /** Its linear colour multiplied by intensity; excludes shadowing and atmosphere fog colour. */
151
151
  readonly skyLightColour: Node<"vec3">;
152
152
  /** the scene colour at the pixel (a post input) */
153
- readonly sceneColour: Node<"vec4">; } = {
153
+ readonly sceneColour: Node<"vec4">;
154
+ /** the world direction through the pixel (a post input: sky detail; SHARD-SOURCE AP13) */
155
+ readonly viewRay: Node<"vec3">; } = {
154
156
  /** toward the light (the `sun` sub-graph only) */
155
157
  /** true for a front-facing fragment; vertex stages refuse this input */
156
158
  frontFacing: op('frontFacing', 'bool'),
@@ -198,6 +200,7 @@ readonly sceneColour: Node<"vec4">; } = {
198
200
  skyLightColour: op('skyLightColour', 'vec3'),
199
201
  /** the scene colour at the pixel (a post input) */
200
202
  sceneColour: op('sceneColour', 'vec4'),
203
+ viewRay: op('viewRay', 'vec3'),
201
204
  } as const;
202
205
 
203
206
  /** TSL built-ins that are graph inputs as they are (matched by identity; `uv()` by its attribute). */
@@ -264,7 +267,7 @@ function constLiteral(value: unknown): GraphLiteral | undefined {
264
267
  * const ir = graph({ flatShading: true, lighting: { sun: graphInputs.albedo.mul(graphInputs.sunColour).mul(cel).mul(1 / Math.PI) } });
265
268
  * ```
266
269
  */
267
- export function graph(spec: GraphSpec): GraphIr {
270
+ export function graph(spec: GraphSpec, host: { readonly budget?: GraphBudget } = {}): GraphIr {
268
271
  const nodes: Record<string, GraphNode> = {}, ids = new Map<Node, string>(), used = new Set<string>(), paramDefs: Record<string, GraphParam> = {};
269
272
  let counter = 0;
270
273
  const fresh = (): string => { let id = `n${counter++}`; while (used.has(id)) id = `n${counter++}`; return id; };
@@ -381,7 +384,8 @@ export function graph(spec: GraphSpec): GraphIr {
381
384
  ...(spec.doubleSided === undefined ? {} : { doubleSided: spec.doubleSided }), ...(spec.flipBackfaceNormals === undefined ? {} : { flipBackfaceNormals: spec.flipBackfaceNormals }), ...(spec.toonCaustics === undefined ? {} : { toonCaustics: spec.toonCaustics }), ...(spec.flatShading === undefined ? {} : { flatShading: spec.flatShading }),
382
385
  ...(Object.keys(paramDefs).length === 0 ? {} : { params: paramDefs }), nodes, stages,
383
386
  };
384
- const checked = validateGraph(structuredClone(ir), { trustedBudget: true });
387
+ // `host.budget`: the ceilings a host grants this kind of graph (a look's sky, AP14), checked here and never written in it
388
+ const checked = validateGraph(structuredClone(ir), { trustedBudget: true, ...(host.budget === undefined ? {} : { budget: host.budget }) });
385
389
  if (!checked.ok) throw new Error(`graph: ${checked.errors.join('; ')}`);
386
390
  return checked.graph;
387
391
  }