@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,182 @@
1
+ #!/usr/bin/env node
2
+ // repo-kit's 3-day scratch sweep (meta REPO-DISK-PLAN DK6, was TEMP-HYGIENE T7). One copy lives in repo-kit; every org
3
+ // repo carries a byte-identical copy at scripts/scratch-sweep.mjs, beside scratch-dir.mjs (DK3) and vite-tmp.mjs.
4
+ //
5
+ // node scripts/scratch-sweep.mjs [--live] [--root <repo>] [--days <n>]
6
+ //
7
+ // It looks at each folder directly under <repo>/tmp/ and would remove one in which nothing (the folder or anything in
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); `tmp/keep` itself when it is a
10
+ // folder (singleplayer keeps hand-kept work there);
11
+ // - a folder that is, or holds, some process's cwd (lsof -d cwd; /proc on Linux); an unreadable table keeps all;
12
+ // - a folder holding a Git root with dirty files or commits no remote has (DS14's list: the reason names the root);
13
+ // - dot folders, symlinks, and `tmp/vitest` (vite-tmp.mjs's own).
14
+ // Dry run is the default until Jake's yes (REPO-DISK decision 1) and a week of dry-run log; `--live` removes. Every
15
+ // decision is appended to tmp/.sweep.log, one line each, and a summary line goes to stdout.
16
+ import { spawnSync } from 'node:child_process';
17
+ import { appendFileSync, lstatSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync } from 'node:fs';
18
+ import { join, resolve, sep } from 'node:path';
19
+ import { pathToFileURL } from 'node:url';
20
+
21
+ const DEFAULT_DAYS = 3;
22
+ const MINUTES_A_DAY = 1440;
23
+ const OWNED_ELSEWHERE = new Set(['vitest']);
24
+
25
+ /** Every process cwd as a real path, or null when the table can't be read (the same read as scratch-end.mjs). */
26
+ export function processCwds() {
27
+ if (process.platform === 'linux') {
28
+ let pids;
29
+ try {
30
+ pids = readdirSync('/proc').filter(name => /^\d+$/u.test(name));
31
+ } catch {
32
+ return null;
33
+ }
34
+ const cwds = [];
35
+ for (const pid of pids) {
36
+ try {
37
+ cwds.push(readlinkSync(`/proc/${pid}/cwd`).replace(/ \(deleted\)$/u, ''));
38
+ } catch {}
39
+ }
40
+ return cwds;
41
+ }
42
+ // A timed-out or failed lsof printed only part of the table: treat it as unreadable.
43
+ const lsof = spawnSync('lsof', ['-nP', '-w', '-d', 'cwd', '-Fn'], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 10_000 });
44
+ if (lsof.error || lsof.signal || lsof.status !== 0) return null;
45
+ const cwds = (lsof.stdout || '').split('\n').filter(line => line.startsWith('n')).map(line => line.slice(1));
46
+ return cwds.length > 0 ? cwds : null;
47
+ }
48
+
49
+ /** @param {string} path */
50
+ function stat(path) {
51
+ try {
52
+ return lstatSync(path);
53
+ } catch {
54
+ return null;
55
+ }
56
+ }
57
+
58
+ /** Names in tmp/keep. @param {string} tmp */
59
+ function keepList(tmp) {
60
+ let text = '';
61
+ try {
62
+ text = readFileSync(join(tmp, 'keep'), 'utf8');
63
+ } catch {
64
+ return new Set();
65
+ }
66
+ return new Set(text.split('\n').map(line => line.replace(/#.*/u, '').trim()).filter(Boolean));
67
+ }
68
+
69
+ /** True when anything under `dir` (itself included) changed in the last `days` days, or the walk failed.
70
+ * @param {string} dir @param {number} days */
71
+ function touched(dir, days) {
72
+ const find = spawnSync('find', [dir, '-mmin', `-${String(days * MINUTES_A_DAY)}`, '-print', '-quit'], { encoding: 'utf8', maxBuffer: 1024 * 1024 });
73
+ return find.status !== 0 || find.stdout.trim() !== '';
74
+ }
75
+
76
+ /** @param {string} root @param {readonly string[]} args */
77
+ function git(root, args) {
78
+ // GIT_OPTIONAL_LOCKS=0: `git status` must not refresh the index, or reading a stale clone would touch it.
79
+ const run = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });
80
+ return run.status === 0 ? run.stdout.trim() : null;
81
+ }
82
+
83
+ /** The first Git root under `dir` with dirty files or unpublished commits, and why; a Git error counts as unpublished.
84
+ * @param {string} dir @returns {string | null} */
85
+ function unpublished(dir) {
86
+ const find = spawnSync('find', [dir, '-maxdepth', '4', '-name', '.git', '-prune', '-print'], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
87
+ if (find.status !== 0) return `${dir}: Git roots unreadable`;
88
+ for (const marker of find.stdout.split('\n').filter(Boolean)) {
89
+ const root = resolve(marker, '..');
90
+ const status = git(root, ['status', '--porcelain', '--ignore-submodules']);
91
+ if (status === null) return `${root}: git status failed`;
92
+ if (status !== '') return `${root}: dirty files`;
93
+ const ahead = git(root, ['log', '--branches', '--tags', '--not', '--remotes', '--oneline', '-1']);
94
+ if (ahead === null) return `${root}: git log failed`;
95
+ if (ahead !== '') return `${root}: commits no remote has`;
96
+ }
97
+ return null;
98
+ }
99
+
100
+ /** Each tmp/ folder and what the sweep does with it, removing nothing.
101
+ * @param {{ root: string, days?: number, cwds?: readonly string[] | null }} options
102
+ * @returns {{ name: string, action: 'remove' | 'keep', reason: string }[]} */
103
+ export function plan({ root, days = DEFAULT_DAYS, cwds = processCwds() }) {
104
+ const tmp = join(root, 'tmp');
105
+ const rows = [];
106
+ let names = [];
107
+ try {
108
+ names = readdirSync(tmp).toSorted();
109
+ } catch {
110
+ return rows;
111
+ }
112
+ const kept = keepList(tmp);
113
+ const real = cwds?.map(cwd => {
114
+ try {
115
+ return realpathSync(cwd);
116
+ } catch {
117
+ return cwd;
118
+ }
119
+ });
120
+ for (const name of names) {
121
+ const dir = join(tmp, name), info = stat(dir);
122
+ if (info === null || !info.isDirectory() || name.startsWith('.') || OWNED_ELSEWHERE.has(name)) continue;
123
+ const at = realpathSync(dir);
124
+ /** @param {string} reason */
125
+ const keep = reason => rows.push({ name, action: /** @type {const} */ ('keep'), reason });
126
+ if (stat(join(dir, '.keep')) !== null) keep('.keep');
127
+ else if (kept.has(name)) keep('tmp/keep');
128
+ else if (name === 'keep') keep('tmp/keep is a folder of kept work');
129
+ else if (real === undefined || real === null) keep('process table unreadable');
130
+ else if (real.some(cwd => cwd === at || cwd.startsWith(at + sep))) keep('busy: a process cwd inside');
131
+ else if (touched(dir, days)) keep(`changed within ${String(days)} days`);
132
+ else {
133
+ const why = unpublished(dir);
134
+ if (why === null) rows.push({ name, action: /** @type {const} */ ('remove'), reason: `untouched ${String(days)} days` });
135
+ else keep(`unpublished (DS14): ${why}`);
136
+ }
137
+ }
138
+ return rows;
139
+ }
140
+
141
+ /** Plans, logs every row to tmp/.sweep.log, and removes the planned folders when live.
142
+ * @param {{ root: string, live?: boolean, days?: number, cwds?: readonly string[] | null, now?: Date }} options */
143
+ export function sweep({ root, live = false, days = DEFAULT_DAYS, cwds, now = new Date() }) {
144
+ const rows = plan({ root, days, ...(cwds === undefined ? {} : { cwds }) });
145
+ const stamp = now.toISOString(), lines = [];
146
+ let removed = 0;
147
+ for (const row of rows) {
148
+ let verb = row.action === 'keep' ? `keep (${row.reason})` : 'would remove';
149
+ if (row.action === 'remove' && live) {
150
+ try {
151
+ rmSync(join(root, 'tmp', row.name), { recursive: true, force: true });
152
+ verb = 'removed';
153
+ removed += 1;
154
+ } catch (error) {
155
+ verb = `remove failed (${error instanceof Error ? error.message : String(error)})`;
156
+ }
157
+ }
158
+ lines.push(`${stamp} ${verb} tmp/${row.name}${row.action === 'remove' ? ` (${row.reason})` : ''}\n`);
159
+ }
160
+ if (lines.length > 0) {
161
+ try {
162
+ appendFileSync(join(root, 'tmp/.sweep.log'), lines.join(''));
163
+ } catch {}
164
+ }
165
+ const planned = rows.filter(row => row.action === 'remove').length;
166
+ return { rows, planned, removed };
167
+ }
168
+
169
+ if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
170
+ const args = process.argv.slice(2);
171
+ const flag = (/** @type {string} */ name) => {
172
+ const at = args.indexOf(name);
173
+ return at === -1 ? undefined : args[at + 1];
174
+ };
175
+ const days = Number(flag('--days') ?? DEFAULT_DAYS);
176
+ if (!Number.isInteger(days) || days < 1) throw new Error('--days takes a whole number of days, 1 or more');
177
+ const root = resolve(flag('--root') ?? resolve(import.meta.dirname, '..'));
178
+ const live = args.includes('--live');
179
+ const { rows, planned, removed } = sweep({ root, live, days });
180
+ const keptRows = rows.filter(row => row.action === 'keep');
181
+ process.stdout.write(`scratch-sweep ${live ? 'live' : '(dry run)'} ${root}/tmp: ${live ? `removed ${String(removed)} of ${String(planned)}` : `would remove ${String(planned)}`}, kept ${String(keptRows.length)}; log tmp/.sweep.log\n`);
182
+ }
@@ -17,7 +17,7 @@ import { outputManifest, shardOutputs } from '@wildshard/engine/scripts/shard-ou
17
17
  import { findShardSource, shardFolderName } from '../src/sharddev/shardSource.ts';
18
18
 
19
19
  /** The verbs whose first operand is a shard source (or, for validate and prove, a built folder). */
20
- const SOURCE_VERBS = new Set(['check', 'synth', 'build', 'dev', 'validate', 'prove']);
20
+ const SOURCE_VERBS = new Set(['check', 'synth', 'build', 'dev', 'watch', 'validate', 'prove']);
21
21
 
22
22
  let runner;
23
23
  /** SA3 (J170): `build` and `check` end by writing the folder's shard file, the step `pack` was. It stays out of the author
@@ -22,7 +22,8 @@ Read `GUIDE.md#2-the-shard-source` before your first edit: it says what ships in
22
22
  3. **Pick one way to build it.**
23
23
  - **Code:** a generator in `generators/` that builds the mesh at build time. Pick it when the shape follows numbers
24
24
  or data (stairs, fences, a row of posts), or changes often. Generators run only at build time and must not import
25
- runtime code (`GUIDE.md#lint-no-runtime-in-build`). A `--template blender` repo has no generators: use Blender.
25
+ runtime code (`GUIDE.md#lint-no-runtime-in-build`). An old repo made with the retired `--template blender` has
26
+ no generators: use Blender.
26
27
  - **Blender:** model it by hand or with a Blender script, keep the `.blend` or script in `blender/`, and export a
27
28
  GLB. Pick it for an organic shape, a UV unwrap, a baked texture or a bevel.
28
29
  - **An image-to-3D tool or a CC0 model** you are licensed to use: treat its GLB as the Blender path's export.
@@ -37,8 +38,9 @@ Read `GUIDE.md#2-the-shard-source` before your first edit: it says what ships in
37
38
  nothing names it. A creature's GLB is named in `data/skins.json` and its skin file together with measured sizes:
38
39
  replacing one needs the Wildshard team today. If nothing names a model of its kind yet, ask the Wildshard team
39
40
  how it is loaded; the guide does not say yet.
40
- - **The `--template blender` repo:** the GLB goes in `blobs/glb/` as `<sha256>.glb`, and every `sections/` row that
41
- names it changes to match; `wildshard check .` settles the sizes (`GUIDE.md#2-the-shard-source`).
41
+ - **An old `--template blender` repo** (retired, J341; still checks and uploads): the GLB goes in `blobs/glb/` as
42
+ `<sha256>.glb`, and every `sections/` row that names it changes to match; `wildshard check .` settles the sizes
43
+ (`GUIDE.md#2-the-shard-source`).
42
44
  Done when `git status` shows the new file and the changed rows or imports.
43
45
  6. **Check.** `wildshard check .` (`GUIDE.md#1-the-loop`). The report card measures draws, triangles, memory and
44
46
  download against their limits (`GUIDE.md#3-budgets`); a refusal names its fix, for example
@@ -5,10 +5,10 @@ description: Move a Wildshard shard repo to a newer @wildshard/sdk - its pins in
5
5
 
6
6
  # wildshard-upgrade
7
7
 
8
- `package.json` pins `@wildshard/sdk`, `@wildshard/format`, `@wildshard/engine` and `three` exactly; a `--template
9
- blender` repo pins only the first two, as dev dependencies (`GUIDE.md#2-the-shard-source`). Moving to a newer sdk
10
- moves every pin together, then the shard source must build again on them. `GUIDE.md` at the repo root holds the
11
- facts; a pointer `GUIDE.md#<anchor>` is the guide heading with that anchor.
8
+ `package.json` pins `@wildshard/sdk`, `@wildshard/format`, `@wildshard/engine` and `three` exactly; a repo made
9
+ with the retired `--template blender` pins only the first two, as dev dependencies (`GUIDE.md#2-the-shard-source`).
10
+ Moving to a newer sdk moves every pin together, then the shard source must build again on them. `GUIDE.md` at the
11
+ repo root holds the facts; a pointer `GUIDE.md#<anchor>` is the guide heading with that anchor.
12
12
 
13
13
  Run the newest CLI once to move, whatever sdk the repo is on now:
14
14
 
package/src/cli/help.ts CHANGED
@@ -16,13 +16,13 @@ const PACK_ALIAS = `pack <folder> [--out <file>]
16
16
 
17
17
  /** Each verb's entry: its usage lines, then what it does, indented. */
18
18
  const VERBS: Readonly<Record<string, string>> = {
19
- new: `new <dir> [slug] [--template sdk|blender] [--empty]
19
+ new: `new <dir> [slug] [--template sdk] [--empty]
20
20
  Start a shard repo in <dir>, a folder that does not
21
21
  exist yet, with its shard source at src/ (slug: the
22
- folder's name unless given). --template sdk (the
23
- default) copies the reference world; --template
24
- blender copies the hand-written Blender template
25
- (a shard file folder, no code). --empty writes a
22
+ folder's name unless given). It copies the reference
23
+ world (--template sdk, the only template; blender is
24
+ retired: Blender makes models, code makes the
25
+ shard). --empty writes a
26
26
  bare shard source instead`,
27
27
  update: `update [dir] [--pins[=<version>]]
28
28
  Rewrite GUIDE.md and the four wildshard skills in
@@ -39,6 +39,10 @@ const VERBS: Readonly<Record<string, string>> = {
39
39
  Serve the shard source on localhost (port 0, the
40
40
  default, picks a free one) and build it again on
41
41
  every edit`,
42
+ watch: `watch <source> [port]
43
+ For a shard written as a three.js scene
44
+ (@wildshard/sdk/scene): serve it, then swap each
45
+ edited part into the running page, no reload`,
42
46
  check: `check <source> [folder] [--json]
43
47
  Lint, build, validate, prove (with the shard
44
48
  source's proof.json) and read the report card, then
@@ -6,7 +6,7 @@ import { heroHashOf } from './hero.ts'
6
6
 
7
7
  import type { HeroCard } from './hero.ts'
8
8
  import type { AudioReport } from '@wildshard/format/audioRules'
9
- import type { ProductFiles } from '@wildshard/format/productValidation'
9
+ import type { ShardfileFiles as ProductFiles } from '@wildshard/format/shardfileValidation'
10
10
 
11
11
  // The same check api-server runs on commit, run first on the author's
12
12
  // machine: a shardfile the server would refuse should not cost a Brotli
@@ -52,10 +52,12 @@ async function validateShardfile(
52
52
  tarball: Readonly<Uint8Array>,
53
53
  ): Promise<ValidShardfile> {
54
54
  installFormatHook()
55
- const { prepareAssetDecoders } = await import('@wildshard/format/product')
56
- const { validateShardfileProduct } =
57
- await import('@wildshard/format/productValidation')
58
- const { productAudioReport } = await import('@wildshard/format/productAudio')
55
+ const { prepareAssetDecoders } =
56
+ await import('@wildshard/format/shardfileAssets')
57
+ const { validateShardfileFolder: validateShardfileProduct } =
58
+ await import('@wildshard/format/shardfileValidation')
59
+ const { shardfileAudioReport: productAudioReport } =
60
+ await import('@wildshard/format/shardfileAudio')
59
61
  const { readTar } = await import('@wildshard/format/tar')
60
62
  await prepareAssetDecoders()
61
63
  const product = productFiles(readTar(tarball))
@@ -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
+ `;
@@ -1,5 +1,5 @@
1
1
  import type { ScriptContract } from '@wildshard/format/scriptContract';
2
- import { assetCost as cost, assetOverdraw as raster, parseAudio as audio, parseGlb as glb, prepareAssetDecoders, type AssetCost as Cost } from '@wildshard/format/product';
2
+ import { assetCost as cost, assetOverdraw as raster, parseAudio as audio, parseGlb as glb, prepareAssetDecoders, type AssetCost as Cost } from '@wildshard/format/shardfileAssets';
3
3
  import { parseKtx2 as ktx2 } from '@wildshard/format/ktx2Cost';
4
4
 
5
5
  // Author-only facade: keep synchronous cost APIs ready without suspending app modules.
@@ -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
+ }
@@ -8,7 +8,7 @@ import { hashImmutableBytes } from '../immutable';
8
8
  import { nameBlob, nameMeshoptBlob, type BlobOptions, type NamedBlob } from '../blobs';
9
9
  import { entryFootprints, obstructsEntry } from '@wildshard/format/entryGeometry';
10
10
  import type { ShardEntryways } from '@wildshard/format/entryways';
11
- import { visitGlbTriangles } from '@wildshard/format/product';
11
+ import { visitGlbTriangles } from '@wildshard/format/shardfileAssets';
12
12
 
13
13
  /** The brotli size a phone pays for a file over the wire: the deploy's own encoding, quality 3 (Vercel's responses match it
14
14
  * byte for byte). */
@@ -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.
@@ -3,7 +3,7 @@ import { EXTMeshoptCompression, KHRMeshQuantization } from '@gltf-transform/exte
3
3
  import { dedup } from '@gltf-transform/functions';
4
4
  import { MeshoptDecoder } from 'meshoptimizer';
5
5
  import { MeshoptEncoder } from 'meshoptimizer/encoder';
6
- import { parseGlb, prepareAssetDecoders } from '@wildshard/format/product';
6
+ import { parseGlb, prepareAssetDecoders } from '@wildshard/format/shardfileAssets';
7
7
 
8
8
  await MeshoptEncoder.ready;
9
9
  await prepareAssetDecoders();
@@ -3,7 +3,7 @@ import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
3
3
  import { MeshoptDecoder, MeshoptEncoder } from 'meshoptimizer';
4
4
  import * as v from 'valibot';
5
5
  import { isJsonData } from '@wildshard/format/json';
6
- import { parseGlb } from '@wildshard/format/product';
6
+ import { parseGlb } from '@wildshard/format/shardfileAssets';
7
7
 
8
8
  const MAX_BYTES = 25_000_000;
9
9
  const count = v.pipe(v.number(), v.integer(), v.minValue(0));
@@ -12,7 +12,7 @@ import { MEASURE_SLOT, parseFamilyMaterial, type FamilyMaterialParams } from '@w
12
12
  import { materialGraphIr } from '@wildshard/format/materials';
13
13
  import type { Shardfile } from '@wildshard/format/shardSchema';
14
14
  import { placeholderGeometry, placeholderLeanDrop, type PlaceholderGrid, type PlaceholderLook, type PlaceholderLookRuntime, type PlaceholderPart } from '@wildshard/engine/game/plugin/placeholderGeometry';
15
- import { assetCost } from '@wildshard/format/product';
15
+ import { assetCost } from '@wildshard/format/shardfileAssets';
16
16
  import { parseGlb } from '../assets';
17
17
  import { encodeCanonicalJson, hashImmutableBytes } from '../immutable';
18
18
  import { staticGlb } from './glb';
@@ -1,7 +1,7 @@
1
1
  import { PAINTED_TERRAIN_ATTRIBUTES } from '@wildshard/format/materialFamilies';
2
2
  import { CELL_ABOVE, CELL_BELOW, CONTENT_CAPS } from '@wildshard/format/contentBounds';
3
3
  import { bilinearTerrainSamplers, decodeTerrainTile, encodeTerrainTile, terrainTileCost, terrainTileHeight, type TerrainTileData } from '@wildshard/format/terrainTileBytes';
4
- import { validateTerrainAssets } from '@wildshard/format/product';
4
+ import { validateTerrainAssets } from '@wildshard/format/shardfileAssets';
5
5
  import { TerrainSchema, type ShardTerrain } from '@wildshard/format/terrain';
6
6
  import type { Shardfile } from '@wildshard/format/shardSchema';
7
7
  import * as v from 'valibot';
@@ -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,4 +1,4 @@
1
- import { assetCost, prepareAssetDecoders } from '@wildshard/format/product';
1
+ import { assetCost, prepareAssetDecoders } from '@wildshard/format/shardfileAssets';
2
2
  import { parseImageAsset } from '@wildshard/format/stillImage';
3
3
  import { decodeTerrainTile } from '@wildshard/format/terrainTileBytes';
4
4
  import { outputBlobPath } from '@wildshard/format/outputAddress';
@@ -1,12 +1,12 @@
1
1
  import { registeredJsonContract } from '@wildshard/format/registeredJson';
2
2
  import type { ScriptContract } from '@wildshard/format/scriptContract';
3
3
  import type { JsonSchema } from '@valibot/to-json-schema';
4
- import type { AssetCost } from '@wildshard/format/product';
4
+ import type { AssetCost } from '@wildshard/format/shardfileAssets';
5
5
  import type { OutputFile } from '@wildshard/format/outputIndex';
6
6
  import { AdmissionServerSchema, serverFilePath, type ServerFile } from '@wildshard/format/admissionServer';
7
7
  import { NATIVE_ASSEMBLY_DATA_SCHEMA, NATIVE_ASSEMBLY_FILE, NATIVE_ASSEMBLY_SCHEMA, type NativeAssemblyPlan as AssemblyPlan } from '@wildshard/format/nativeAssembly';
8
8
  import { validatePlatformFile } from '@wildshard/format/platformFileFamilies';
9
- import { outputBlobKind } from '@wildshard/format/productValidation';
9
+ import { outputBlobKind } from '@wildshard/format/shardfileValidation';
10
10
  import { parse } from 'valibot';
11
11
  import { encodeCanonicalJson, hashImmutableBytes } from './immutable';
12
12
  import { nameBlobBytes } from './blobBytes';
@@ -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
  }