@wildshard/sdk 0.2.4 → 0.2.6
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 +77 -11
- package/codemods/0.2.5.mjs +12 -0
- package/lint/ratchet.json +1 -9
- package/lint/sdk-plugin.mjs +24 -2
- package/package.json +4 -3
- package/scripts/build-shardfiles.mjs +1 -1
- package/scripts/gen-format-schema.mjs +1 -1
- package/scripts/shard-build-pool.mjs +1 -1
- package/scripts/wildshard.mjs +11 -3
- package/skills/wildshard-upgrade/SKILL.md +22 -23
- package/src/cli/help.ts +6 -3
- package/src/sharddev/agentFiles.ts +4 -3
- package/src/sharddev/author.ts +16 -3
- package/src/sharddev/bake/authoredWorld.ts +1 -1
- package/src/sharddev/bake/specimenCatalogue.ts +1 -1
- package/src/sharddev/bake/staticMaterials.ts +1 -1
- package/src/sharddev/checkProject.ts +1 -1
- package/src/sharddev/cli.ts +11 -7
- package/src/sharddev/formatJsonSchema.ts +1117 -3
- package/src/sharddev/kit/bakedGeometry.ts +58 -12
- package/src/sharddev/nativePopulationRows.ts +1 -1
- package/src/sharddev/performancePolicy.ts +1 -1
- package/src/sharddev/phasedBoss.ts +212 -34
- package/src/sharddev/project.ts +1 -1
- package/src/sharddev/projectEntryProof.ts +1 -1
- package/src/sharddev/projectGeneration.ts +1 -1
- package/src/sharddev/projectOutput.ts +1 -1
- package/src/sharddev/projectSections.ts +1 -1
- package/src/sharddev/refusals.ts +9 -5
- package/src/sharddev/reportCard.ts +1 -1
- package/src/sharddev/sections.ts +1 -1
- package/src/sharddev/species/clips.ts +64 -24
- package/src/sharddev/speciesBrains.ts +98 -15
- package/src/sharddev/updatePins.ts +358 -0
- package/src/sharddev/weapons/bowProfile.ts +3 -3
- package/src/sharddev/weapons/meleeProfile.ts +48 -4
- package/src/sharddev/worldScenes.ts +1 -1
- package/tsconfig.author.json +1 -0
package/GUIDE.md
CHANGED
|
@@ -53,7 +53,7 @@ with `rule`, `fix` and `guide`) for agents and scripts.
|
|
|
53
53
|
| Verb | What it is for |
|
|
54
54
|
|---|---|
|
|
55
55
|
| `wildshard new <dir> [slug] [--template sdk\|blender] [--empty]` | Start a shard repo in a folder that does not exist yet, its shard source at `src/`. The slug is the folder's name unless you give one. `--template sdk` (the default) copies the reference world; `--template blender` copies the hand-written Blender template (below); any other template refuses before writing. `--empty` writes a bare shard source instead of the reference world |
|
|
56
|
-
| `wildshard update [dir]` | Rewrite this guide and the four `wildshard` skills from the installed sdk
|
|
56
|
+
| `wildshard update [dir] [--pins[=<version>]]` | Rewrite this guide and the four `wildshard` skills from the installed sdk. `--pins` first moves the repo to a newer sdk release (npm's latest, or `--pins=<version>`), installs it and applies its codemods, and runs `check` after (section 7) |
|
|
57
57
|
| `wildshard dev <source>` | Serve the shard source on localhost and rebuild on every save (section 4). **Not built yet** for an installed sdk (SA15) |
|
|
58
58
|
| `wildshard check <source> [folder] [--json]` | The loop's check: lint, build, validate, prove, report card, verdict |
|
|
59
59
|
| `wildshard hero <source> --base <url>` | Capture the hero from a served build and stamp `hero.json`. `--stamp-existing` marks the images already there as current: only when you have looked at them and they show the current world |
|
|
@@ -340,13 +340,46 @@ other name refuses before `new` writes anything. Leave the flag out or pass `--t
|
|
|
340
340
|
|
|
341
341
|
#### update-target
|
|
342
342
|
|
|
343
|
-
`update` works on a shard repo: a folder whose `package.json` lists `@wildshard/sdk`, as `new` writes it
|
|
344
|
-
that folder, or name it: `wildshard update my-shard`.
|
|
343
|
+
`update` works on a shard repo: a folder whose `package.json` lists `@wildshard/sdk`, as `new` writes it, or
|
|
344
|
+
`@wildshard/sharddev`. Run it in that folder, or name it: `wildshard update my-shard`.
|
|
345
|
+
|
|
346
|
+
#### update-pins-no-git
|
|
347
|
+
|
|
348
|
+
`wildshard update --pins` edits `package.json`, `pnpm-lock.yaml` and, through its codemods, your shard source, so it
|
|
349
|
+
runs only in a git repo whose `package.json` is committed: `git diff` afterwards is how you see what it changed. It
|
|
350
|
+
refused before it changed anything. Put the shard repo in git and commit it (`git init`, `git add .`, `git commit`),
|
|
351
|
+
then run `wildshard update --pins` again.
|
|
352
|
+
|
|
353
|
+
#### update-pins-dirty
|
|
354
|
+
|
|
355
|
+
The shard repo has uncommitted or untracked changes (the refusal names the first few). `update --pins` refuses them so
|
|
356
|
+
its edits never mix with yours. It refused before it changed anything. Commit or stash your changes (`git stash -u`),
|
|
357
|
+
then run `wildshard update --pins` again. Ignored files, such as `node_modules/` and build output, do not count.
|
|
345
358
|
|
|
346
359
|
#### update-pins
|
|
347
360
|
|
|
348
|
-
`wildshard update --pins`
|
|
349
|
-
|
|
361
|
+
`wildshard update --pins` stopped. The line above says why. If it stopped before its codemods were done, it has
|
|
362
|
+
already put `package.json` and `pnpm-lock.yaml` back and installed the old sdk again (it says `back on
|
|
363
|
+
@wildshard/sdk <old>`), so after the fix run `wildshard update --pins` again; `git diff` shows any edit a codemod made
|
|
364
|
+
before it stopped.
|
|
365
|
+
|
|
366
|
+
- `npm has no @wildshard/sdk@<version>`, `npm gave no version` or `pnpm view ... failed`: name a version npm lists
|
|
367
|
+
(`pnpm view @wildshard/sdk versions`), or check your network.
|
|
368
|
+
- `moves forward only`: the repo is already on a newer sdk than the one you named. To go back, edit the pins in
|
|
369
|
+
`package.json` by hand and run `pnpm install`.
|
|
370
|
+
- `names <manager> as its package manager`: `--pins` installs with pnpm; set `packageManager` to the
|
|
371
|
+
`pnpm@...` that `new` writes, or move the pins by hand as the `wildshard-upgrade` skill says.
|
|
372
|
+
- `git not found`: `--pins` reads `git status` before it starts; install git.
|
|
373
|
+
- `cannot tell which sdk ... is on`: pin `@wildshard/sdk` to a version, not `link:` or `file:`.
|
|
374
|
+
- `pins @wildshard/sdk <a> but has <b> installed`: run `pnpm install` and `wildshard check .` on the pins you have,
|
|
375
|
+
then `--pins` again.
|
|
376
|
+
- `pnpm install failed`, `pnpm installed ...` or `pins three ...`: the install did not give the versions the release
|
|
377
|
+
names. Read pnpm's output above it.
|
|
378
|
+
- `codemod <version>.mjs failed`: the release's codemod could not change your shard source. Report the message with
|
|
379
|
+
the sdk versions; stay on the old pins until a fixed release.
|
|
380
|
+
- `its wildshard update failed`: the pins moved; run `pnpm exec wildshard update`, then `wildshard check .`.
|
|
381
|
+
- `check failed`: the pins moved and the install worked, but the shard source does not pass on the new sdk. Fix each
|
|
382
|
+
refusal check printed above it, then run `wildshard check .` again.
|
|
350
383
|
|
|
351
384
|
#### update-refused
|
|
352
385
|
|
|
@@ -486,18 +519,22 @@ Code `audio-refused`. Build prints every finding with one of the rules below und
|
|
|
486
519
|
|
|
487
520
|
#### audio-unreadable
|
|
488
521
|
|
|
489
|
-
Red. The recording does not read as AAC-LC at 48 kHz, mono or stereo. Export it again
|
|
490
|
-
`audio-unreadable`.
|
|
522
|
+
Red. The recording does not read as AAC-LC at 48 kHz, mono or stereo. Export it again as AAC-LC at 48 kHz in an
|
|
523
|
+
`.m4a` file. Code `audio-unreadable`.
|
|
491
524
|
|
|
492
525
|
#### audio-container
|
|
493
526
|
|
|
494
527
|
Red. The recording's bytes are FLAC, AIFF, Ogg, MP3, WebM, CAF or no container the game knows; it still counts toward
|
|
495
|
-
the audio budget. Export it again as AAC
|
|
528
|
+
the audio budget. Export it again as AAC-LC at 48 kHz in an `.m4a` file, not as WAV: a WAV file is `audio-wav`, amber.
|
|
529
|
+
With ffmpeg on your PATH, `build` re-encodes a `.wav`, `.flac`, `.aif` or `.aiff` file under `/assets/music/` or
|
|
530
|
+
`/assets/sfx/` to that form itself, so you see this rule for MP3, Ogg, WebM or CAF, for a file outside those folders or
|
|
531
|
+
named otherwise, or when ffmpeg is missing. Code `audio-container`.
|
|
496
532
|
|
|
497
533
|
#### audio-encoding
|
|
498
534
|
|
|
499
535
|
Amber. The recording plays, but it is PCM WAV, AAC at a sample rate other than 48 kHz, or AAC outside the strict
|
|
500
|
-
playback index. Encode it as AAC-LC at 48 kHz
|
|
536
|
+
playback index. Encode it again with ffmpeg as AAC-LC at 48 kHz in an `.m4a` file, or let `build` do it (it needs
|
|
537
|
+
ffmpeg on your PATH). Codes `audio-wav`, `audio-sample-rate`, `audio-strict-index`.
|
|
501
538
|
|
|
502
539
|
#### audio-duration
|
|
503
540
|
|
|
@@ -891,5 +928,34 @@ keep your own notes for agents in `AGENTS.md`, never in this guide or a skill: `
|
|
|
891
928
|
prints `already up to date` or the files it wrote, and `git status` shows only `GUIDE.md`, `.claude/skills/` and any
|
|
892
929
|
agent file it added.
|
|
893
930
|
|
|
894
|
-
|
|
895
|
-
|
|
931
|
+
To move to a newer sdk, run the newest CLI once, whatever sdk the repo is on now:
|
|
932
|
+
|
|
933
|
+
```sh
|
|
934
|
+
pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins
|
|
935
|
+
```
|
|
936
|
+
|
|
937
|
+
An older installed CLI cannot do the move: 0.2.4 and earlier refuse the flag, and 0.2.5 refuses a repo that lists
|
|
938
|
+
the sdk as `@wildshard/sharddev` or by a GitHub pin. Once the repo is on the newest sdk, `pnpm exec wildshard
|
|
939
|
+
update --pins` works too.
|
|
940
|
+
|
|
941
|
+
`wildshard update --pins` moves the repo to a newer sdk release first: npm's latest, or the one you name with
|
|
942
|
+
`--pins=<version>` (`--pins=0.2.5`). In order, it:
|
|
943
|
+
|
|
944
|
+
1. reads the release from npm (`pnpm view`) and refuses one older than the repo's sdk;
|
|
945
|
+
2. moves every pin `package.json` lists to what that release names: the sdk to the release, `@wildshard/format`,
|
|
946
|
+
`@wildshard/engine` and `three` to the exact specs it pins, each `pnpm.overrides` entry for one of those packages
|
|
947
|
+
with it, and `engines.node` to the Node it needs. The sdk keeps the name and form the repo lists it with:
|
|
948
|
+
`@wildshard/sdk` or `@wildshard/sharddev`; an exact version, an `npm:@wildshard/sdk@<version>` alias, or a GitHub
|
|
949
|
+
pin, which moves to the commit the release's `v<version>` tag names (or to that tag, if it named a tag). It changes
|
|
950
|
+
nothing else in the file and prints each move;
|
|
951
|
+
3. runs `pnpm install`, and refuses if pnpm did not install that sdk and, when the repo lists `three`, that `three`;
|
|
952
|
+
4. applies the release's codemods: each `codemods/<version>.mjs` the new sdk ships, for every version above the old
|
|
953
|
+
sdk and up to the new one, oldest first. A codemod edits your shard source for a change that would otherwise
|
|
954
|
+
break it, and prints what it changed;
|
|
955
|
+
5. runs the new sdk's own `wildshard update`, which rewrites this guide and the skills as above;
|
|
956
|
+
6. runs the new sdk's `wildshard check .`.
|
|
957
|
+
|
|
958
|
+
If step 3 or 4 fails, it puts `package.json` and `pnpm-lock.yaml` back and installs the old sdk again. It refuses to
|
|
959
|
+
start unless `git status` is clean (`update-pins-dirty`, `update-pins-no-git`): a codemod edits your files. Done when
|
|
960
|
+
its last line reads `on @wildshard/sdk <version>, check pass`. Commit `package.json`, `pnpm-lock.yaml`, the guide,
|
|
961
|
+
the skills and any codemod edit together. A refusal is `update-pins` (section 6).
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// SHARD-AUTHORING SA18: the codemod for the sdk release named by this file (`codemods/<version>.mjs`).
|
|
2
|
+
// `wildshard update --pins` runs every codemod whose version v is above the repo's old sdk and at most the new one
|
|
3
|
+
// (old < v <= new), oldest first, after `pnpm install` and before `wildshard update` rewrites GUIDE.md and the skills.
|
|
4
|
+
// A codemod edits the shard repo at `project` for the release's breaking changes and returns one line per change.
|
|
5
|
+
// This release changes nothing in a shard repo, so it is a no-op that keeps the hook's shape on file.
|
|
6
|
+
|
|
7
|
+
/** @param {Readonly<{ project: string, from: string, to: string }>} move @returns {string[]} */
|
|
8
|
+
// oxlint-disable-next-line import/no-default-export -- `update --pins` loads each codemod by its default export.
|
|
9
|
+
export default function codemod(move) {
|
|
10
|
+
void move;
|
|
11
|
+
return [];
|
|
12
|
+
}
|
package/lint/ratchet.json
CHANGED
|
@@ -1,11 +1,3 @@
|
|
|
1
1
|
{
|
|
2
|
-
"budgets": {}
|
|
3
|
-
"wildshard/sdk-no-facade": {
|
|
4
|
-
"src/sharddev/kit/bakedGeometry.ts": 7,
|
|
5
|
-
"src/sharddev/phasedBoss.ts": 9,
|
|
6
|
-
"src/sharddev/species/clips.ts": 11,
|
|
7
|
-
"src/sharddev/speciesBrains.ts": 3,
|
|
8
|
-
"src/sharddev/weapons/bowProfile.ts": 1,
|
|
9
|
-
"src/sharddev/weapons/meleeProfile.ts": 2
|
|
10
|
-
}
|
|
2
|
+
"budgets": {}
|
|
11
3
|
}
|
package/lint/sdk-plugin.mjs
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
import { readFileSync } from 'node:fs';
|
|
10
10
|
import { isBuiltin } from 'node:module';
|
|
11
11
|
import { dirname, isAbsolute, resolve } from 'node:path';
|
|
12
|
-
import { fileURLToPath } from 'node:url';
|
|
12
|
+
import { fileURLToPath, pathToFileURL } from 'node:url';
|
|
13
13
|
|
|
14
14
|
const RULE = 'generator-imports';
|
|
15
15
|
// Not visible to a lint, left for later: `#` subpath imports and tsconfig `paths` aliases (they name no package), and
|
|
@@ -68,16 +68,38 @@ function cheat(source, local, required) {
|
|
|
68
68
|
return null;
|
|
69
69
|
}
|
|
70
70
|
|
|
71
|
+
const plainly = (source) => `${RULE}: ${JSON.stringify(source)} names one file to Node (a URL) and another to Vite; `
|
|
72
|
+
+ 'no percent-escape, backslash, tab, newline or edge space in an import path, write the path plainly';
|
|
73
|
+
/** The file Node loads for relative `source` (a URL resolve), without a trailing slash; null when it cannot. */
|
|
74
|
+
const nodePath = (filename, source) => {
|
|
75
|
+
try {
|
|
76
|
+
return fileURLToPath(new URL(source, pathToFileURL(resolve(filename)))).replaceAll('\\', '/').replace(/(?<=.)\/$/u, '');
|
|
77
|
+
} catch { return null; }
|
|
78
|
+
};
|
|
79
|
+
|
|
71
80
|
/** Why `source` may not be imported from `filename` under a shard's author folders, or null when it may. */
|
|
72
81
|
export function generatorImportViolation(filename, rawSource, required = false) {
|
|
73
82
|
// The last src/shards/ in the path names the shard, so a checkout under some other src/shards/ still matches.
|
|
74
83
|
const path = resolve(filename).replaceAll('\\', '/'), match = /^.*\/src\/shards\/([^/]+)\/(.+)$/u.exec(path);
|
|
75
84
|
if (match === null || !(/^(?:generators|data|quests)\//u.test(match[2]) || match[2] === 'shard.config.ts')) return null;
|
|
76
85
|
if (typeof rawSource !== 'string') return null;
|
|
77
|
-
|
|
86
|
+
// Vite resolves the path before the first `?` or `#` through the package exports and keeps the rest (`?raw`, `?url`,
|
|
87
|
+
// `?worker&inline`) as a postfix, as engine's import rules read it; a leading `#` is a subpath import, not a postfix.
|
|
88
|
+
// Node keeps a bare specifier's `?` in the subpath, so there the stripped path is only ever the stricter read.
|
|
89
|
+
const postfix = rawSource.slice(1).search(/[?#]/u) + 1;
|
|
90
|
+
const bare = postfix > 0 ? rawSource.slice(0, postfix) : rawSource;
|
|
91
|
+
// Node resolves a relative path as a URL (`./%2e%2e/` is `..`, `\\` is `/`, tabs and newlines drop out, `%2f` is
|
|
92
|
+
// refused) and Vite decodes nothing, while path.resolve keeps them all as folder names: the lint and build disagree.
|
|
93
|
+
if (/%[0-9a-f]{2}|[\\\t\n\r]/iu.test(bare)) return plainly(bare);
|
|
94
|
+
let source = bare;
|
|
95
|
+
if (bare.startsWith('file:')) {
|
|
96
|
+
try { source = fileURLToPath(bare); } catch { return `${RULE}: ${bare} is not a local file: URL; import a relative path`; }
|
|
97
|
+
}
|
|
78
98
|
if (source === '<computed>') return `${RULE}: author imports require a literal module path; write the path as a string`;
|
|
79
99
|
const root = path.slice(0, path.length - match[2].length);
|
|
80
100
|
const local = source.startsWith('.') || isAbsolute(source) ? resolve(dirname(filename), source).replaceAll('\\', '/') : '';
|
|
101
|
+
// The catch-all for a rewrite not listed above: the path must name the same file as a URL (how Node loads it).
|
|
102
|
+
if (local !== '' && source.startsWith('.') && nodePath(filename, source) !== local) return plainly(bare);
|
|
81
103
|
const denied = cheat(source, local, required);
|
|
82
104
|
if (denied !== null) return denied;
|
|
83
105
|
const own = local !== '' && local.startsWith(root);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wildshard/sdk",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.6",
|
|
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": {
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
"files": [
|
|
14
14
|
"GUIDE.md",
|
|
15
15
|
"skills",
|
|
16
|
+
"codemods",
|
|
16
17
|
"bin",
|
|
17
18
|
"src",
|
|
18
19
|
"!src/**/*.test.*",
|
|
@@ -82,7 +83,7 @@
|
|
|
82
83
|
"@typescript/typescript6": "6.0.2",
|
|
83
84
|
"@valibot/to-json-schema": "1.8.0",
|
|
84
85
|
"@wildshard/engine": "github:project-wildshard/engine#867f3b968429d8b90ae33b363dae3f15f16f6b84",
|
|
85
|
-
"@wildshard/format": "github:project-wildshard/shard-format#v0.4.
|
|
86
|
+
"@wildshard/format": "github:project-wildshard/shard-format#v0.4.9",
|
|
86
87
|
"ajv": "6.15.0",
|
|
87
88
|
"assemblyscript": "0.28.20",
|
|
88
89
|
"binaryen": "132.0.0",
|
|
@@ -196,7 +197,7 @@
|
|
|
196
197
|
"overrides": {
|
|
197
198
|
"binaryen": "npm:@pre-bundled/binaryen@132.0.0-patch-1",
|
|
198
199
|
"assemblyscript>binaryen": "npm:@pre-bundled/binaryen@131.0.0-nightly.20260721-patch-1",
|
|
199
|
-
"@wildshard/format": "github:project-wildshard/shard-format#v0.4.
|
|
200
|
+
"@wildshard/format": "github:project-wildshard/shard-format#v0.4.9"
|
|
200
201
|
}
|
|
201
202
|
},
|
|
202
203
|
"exports": {
|
|
@@ -195,7 +195,7 @@ export async function buildShardfiles(root,options={}) {
|
|
|
195
195
|
const counters=createBuildCacheCounters(),stop=observeBuildCache(counters);
|
|
196
196
|
let complete=false;
|
|
197
197
|
try {const result=await buildShardfilesWork(root,options,counters);complete=true;return result;}
|
|
198
|
-
finally {stop();console.info(formatBuildCacheReport(counters.snapshot(complete)));}
|
|
198
|
+
finally {stop();if(process.env.WILDSHARD_CACHE_REPORT==='1')console.info(formatBuildCacheReport(counters.snapshot(complete)));}
|
|
199
199
|
}
|
|
200
200
|
|
|
201
201
|
if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { mkdirSync, writeFileSync } from 'node:fs';
|
|
2
2
|
import { resolve } from 'node:path';
|
|
3
3
|
import { pathToFileURL } from 'node:url';
|
|
4
|
-
import { formatJsonSchemas, namedFormatJsonSchemas } from '@wildshard/
|
|
4
|
+
import { formatJsonSchemas, namedFormatJsonSchemas } from '@wildshard/sdk/formatJsonSchema';
|
|
5
5
|
|
|
6
6
|
/** Build the migrated format documents into an ignored authoring-output folder, never into committed source.
|
|
7
7
|
* @param {string} root
|
|
@@ -30,7 +30,7 @@ export async function runShardBuildPool(items, work, prepare) {
|
|
|
30
30
|
export function runShardBuild(args, signal, cacheReport) {
|
|
31
31
|
return new Promise((resolve, reject) => {
|
|
32
32
|
const child = spawn(process.execPath, ['--import', fileURLToPath(import.meta.resolve('@wildshard/engine/scripts/shardfile-inputs.mjs')), resolvePath(import.meta.dirname, 'wildshard.mjs'), ...args], {
|
|
33
|
-
cwd: process.cwd(), env: {...process.env,WILDSHARD_WORLD_TEXTURE_CACHE:process.env.WILDSHARD_WORLD_TEXTURE_CACHE??resolvePath(shardfileCacheRoot(),'.world-textures-v1')}, signal, stdio: ['ignore', 'inherit', 'pipe'],
|
|
33
|
+
cwd: process.cwd(), env: {...process.env,...(cacheReport===undefined?{}:{WILDSHARD_CACHE_REPORT:'1'}),WILDSHARD_WORLD_TEXTURE_CACHE:process.env.WILDSHARD_WORLD_TEXTURE_CACHE??resolvePath(shardfileCacheRoot(),'.world-textures-v1')}, signal, stdio: ['ignore', 'inherit', 'pipe'],
|
|
34
34
|
});
|
|
35
35
|
// Forward all diagnostics, retaining only a bounded tail for the pool's error.
|
|
36
36
|
let stderrTail = '';
|
package/scripts/wildshard.mjs
CHANGED
|
@@ -4,7 +4,7 @@ import { build } from 'vite';
|
|
|
4
4
|
import { createBuildCacheCounters, observeBuildCache, formatBuildCacheReport } from '@wildshard/engine/scripts/build-cache-report.mjs';
|
|
5
5
|
import { captureProductInputs, recordBundle, inputRecorderPlugin } from '@wildshard/engine/scripts/shardfile-inputs.mjs';
|
|
6
6
|
import { basename, resolve } from 'node:path';
|
|
7
|
-
import { existsSync, readFileSync } from 'node:fs';
|
|
7
|
+
import { existsSync, readFileSync, realpathSync } from 'node:fs';
|
|
8
8
|
import { createHash } from 'node:crypto';
|
|
9
9
|
import { pathToFileURL } from 'node:url';
|
|
10
10
|
import { createRequire } from 'node:module';
|
|
@@ -38,7 +38,13 @@ export function prepareWildshard() {
|
|
|
38
38
|
// Resolver policy is executable compiler input too: a source-only cache hit
|
|
39
39
|
// must not replay a bundle built before an externalization change.
|
|
40
40
|
const policy = createHash('sha256').update(readFileSync(import.meta.filename)).digest('hex');
|
|
41
|
-
|
|
41
|
+
// SA18: which installed sdk is compiling is an input too. Receipts skip node_modules and paths outside the repo, and
|
|
42
|
+
// this file is byte-identical across releases, so without its root and version a repo that moved to a newer sdk with
|
|
43
|
+
// the same shard-format replayed the old sdk's bundle. (A sharddev checkout run from another folder is still keyed
|
|
44
|
+
// only by its path: edits to it outside that folder are not seen.)
|
|
45
|
+
const sdkRoot = realpathSync(resolve(import.meta.dirname, '..'));
|
|
46
|
+
const sdk = `${sdkRoot}@${JSON.parse(readFileSync(resolve(sdkRoot, 'package.json'), 'utf8')).version}`;
|
|
47
|
+
return authorBundleCached(root,[shardfileValidationRevision(root),policy,sdk],async()=>{
|
|
42
48
|
const result = await build({ configFile: false, publicDir: false, resolve: { alias: rapierAlias }, logLevel: 'silent', define: { __SHARDFILE_VALIDATOR__: JSON.stringify(shardfileValidationRevision()), 'import.meta.dirname': JSON.stringify(resolve(import.meta.dirname, '../src/sharddev')) }, plugins: [inputRecorderPlugin({execution:true}), { name: 'author-node-vite', enforce: 'pre', resolveId(id) {
|
|
43
49
|
if (id === 'vite') return { id: pathToFileURL(resolve(import.meta.dirname,'shardfile-vite.mjs')).href, external: true };
|
|
44
50
|
if (id === 'sharp' || id === 'binaryen' || id === '@typescript/typescript6' || /^assemblyscript(?:\/|$)/u.test(id)) return { id: pathToFileURL(authorRequire.resolve(id)).href, external: true };
|
|
@@ -101,5 +107,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1]
|
|
|
101
107
|
complete=true;
|
|
102
108
|
}
|
|
103
109
|
catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
|
|
104
|
-
|
|
110
|
+
// The counters line is for the build pool, which sets WILDSHARD_CACHE_REPORT=1 for the children whose report it reads,
|
|
111
|
+
// and for debugging a build's cache; an author's run, refusals included, does not print it.
|
|
112
|
+
finally {stop();if(process.env.WILDSHARD_CACHE_REPORT==='1')console.error(`\n${formatBuildCacheReport(counters.snapshot(complete))}`);}
|
|
105
113
|
}
|
|
@@ -10,38 +10,37 @@ blender` repo pins only the first two, as dev dependencies (`GUIDE.md#2-the-shar
|
|
|
10
10
|
moves every pin together, then the shard source must build again on them. `GUIDE.md` at the repo root holds the
|
|
11
11
|
facts; a pointer `GUIDE.md#<anchor>` is the guide heading with that anchor.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
Run the newest CLI once to move, whatever sdk the repo is on now:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`wildshard update --pins` does the move in one command (`GUIDE.md#7-wildshard-update`): it moves every pin to the
|
|
20
|
+
release, runs `pnpm install`, applies the release's codemods, rewrites the guide and skills, and runs check. An
|
|
21
|
+
installed 0.2.4 or older refuses the flag, and 0.2.5 refuses a repo that lists the sdk as `@wildshard/sharddev` or by
|
|
22
|
+
a GitHub pin, so start from the line above.
|
|
16
23
|
|
|
17
24
|
## The steps, in order
|
|
18
25
|
|
|
19
26
|
1. **Start clean.** Commit your own changes, then `wildshard check .` on the old pins; if it fails, fix that first.
|
|
20
27
|
Done when `git status` is clean and check passes, so any later refusal is the upgrade's.
|
|
21
|
-
2. **
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
`
|
|
25
|
-
|
|
26
|
-
4. **
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
names the new sdk version and `git status` shows only those files and the step 3 and 4 files.
|
|
33
|
-
6. **Build:** `wildshard check .` (`GUIDE.md#1-the-loop`). Done when `wildshard --version` prints the new sdk
|
|
34
|
-
version and the last line reads `check pass`.
|
|
35
|
-
7. **Read each refusal.** It ends `[<rule>] fix: ... (GUIDE.md#<anchor>)`: read that heading under
|
|
36
|
-
`GUIDE.md#6-refusals-and-their-fixes`, in the guide update wrote in step 5, make the fix, and run check again. A
|
|
37
|
-
budget can tighten between releases (`GUIDE.md#3-budgets`); a lint rule can be new. Done at `check pass`.
|
|
38
|
-
8. **Commit** the pins, the lock file, the guide, the skills, any agent file update added and your fixes together.
|
|
39
|
-
Done when `git status` is clean.
|
|
28
|
+
2. **Move:** `pnpm --package=@wildshard/sdk@latest dlx wildshard update --pins` for npm's latest sdk, or
|
|
29
|
+
`--pins=<version>` in place of `--pins` for one release. Done when it prints a line per pin it moved.
|
|
30
|
+
3. **Read its last line.** `on @wildshard/sdk <version>, check pass` means the move is done: go to step 5. A line
|
|
31
|
+
ending `[update-pins] fix: ...` is a refusal: read `GUIDE.md#update-pins` in the guide now in the repo;
|
|
32
|
+
`[update-pins-dirty]` (`GUIDE.md#update-pins-dirty`) means go back to step 1.
|
|
33
|
+
4. **Fix each refusal check printed.** It ends `[<rule>] fix: ... (GUIDE.md#<anchor>)`: read that heading under
|
|
34
|
+
`GUIDE.md#6-refusals-and-their-fixes`, make the fix, and run `wildshard check .` again. A budget can tighten
|
|
35
|
+
between releases (`GUIDE.md#3-budgets`); a lint rule can be new. Done at `check pass`.
|
|
36
|
+
5. **Reread this skill:** step 2 rewrote it, and the new copy may differ. Done when you have read the new copy.
|
|
37
|
+
6. **Commit** `package.json`, `pnpm-lock.yaml`, the guide, the skills, any agent file update added, any codemod edit
|
|
38
|
+
and your fixes together. Done when `git status` is clean.
|
|
40
39
|
A new sdk can change what the shard looks like, so before the next upload follow the `wildshard-goldens` skill.
|
|
41
40
|
|
|
42
41
|
## Rules
|
|
43
42
|
|
|
44
|
-
- Move the pins together, never one alone: the sdk is built and tested against the others it names.
|
|
43
|
+
- Move the pins together, never one alone: the sdk is built and tested against the others it names. `--pins` does.
|
|
45
44
|
- Fix the shard source to the new rules; do not pin an older piece to dodge a refusal.
|
|
46
45
|
- If check fails on a shard source you did not change and the refusal's fix does not apply, go back to the old pins
|
|
47
46
|
and report the message.
|
package/src/cli/help.ts
CHANGED
|
@@ -24,14 +24,17 @@ const VERBS: Readonly<Record<string, string>> = {
|
|
|
24
24
|
blender copies the hand-written Blender template
|
|
25
25
|
(a shard file folder, no code). --empty writes a
|
|
26
26
|
bare shard source instead`,
|
|
27
|
-
update: `update [dir]
|
|
27
|
+
update: `update [dir] [--pins[=<version>]]
|
|
28
28
|
Rewrite GUIDE.md and the four wildshard skills in
|
|
29
29
|
.claude/skills/ from the installed sdk (dir: the
|
|
30
30
|
shard repo, default the current folder). Adds the
|
|
31
31
|
.agents/skills links, AGENTS.md and CLAUDE.md if
|
|
32
32
|
missing; touches nothing else, and leaves an
|
|
33
|
-
AGENTS.md you changed (it says so).
|
|
34
|
-
|
|
33
|
+
AGENTS.md you changed (it says so). --pins first
|
|
34
|
+
moves the repo to a newer sdk (npm's latest, or
|
|
35
|
+
--pins=<version>): moves the pins, runs pnpm
|
|
36
|
+
install, applies the release's codemods, then
|
|
37
|
+
runs the new sdk's update and check`,
|
|
35
38
|
dev: `dev <source> [port]
|
|
36
39
|
Serve the shard source on localhost (port 0, the
|
|
37
40
|
default, picks a free one) and build it again on
|
|
@@ -101,15 +101,16 @@ function sdkVersion(root: string): string {
|
|
|
101
101
|
return typeof parsed === 'object' && parsed !== null && 'version' in parsed && typeof parsed.version === 'string' ? parsed.version : 'unknown';
|
|
102
102
|
}
|
|
103
103
|
|
|
104
|
-
/** A shard repo is a folder whose package.json lists `@wildshard/sdk` (`new` writes it; a blender repo as a dev dependency)
|
|
105
|
-
|
|
104
|
+
/** A shard repo is a folder whose package.json lists `@wildshard/sdk` (`new` writes it; a blender repo as a dev dependency)
|
|
105
|
+
* or `@wildshard/sharddev`, the name the org's shard repos list it under (a GitHub pin, or an `npm:@wildshard/sdk` alias). */
|
|
106
|
+
export function assertShardRepo(project: string): void {
|
|
106
107
|
const file = resolve(project, 'package.json');
|
|
107
108
|
let parsed: unknown;
|
|
108
109
|
try { parsed = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : undefined; }
|
|
109
110
|
catch (error) { throw new Error(`update: ${project} is not a shard repo: its package.json is not valid JSON (${error instanceof Error ? error.message : String(error)})`, { cause: error }); }
|
|
110
111
|
const fields: unknown[] = typeof parsed === 'object' && parsed !== null
|
|
111
112
|
? [Reflect.get(parsed, 'dependencies'), Reflect.get(parsed, 'devDependencies')] : [];
|
|
112
|
-
if (!fields.some(field => typeof field === 'object' && field !== null && Object.hasOwn(field, '@wildshard/sdk'))) throw new Error(`update: ${project} is not a shard repo: its package.json does not list @wildshard/sdk (or it has none)`);
|
|
113
|
+
if (!fields.some(field => typeof field === 'object' && field !== null && (Object.hasOwn(field, '@wildshard/sdk') || Object.hasOwn(field, '@wildshard/sharddev')))) throw new Error(`update: ${project} is not a shard repo: its package.json does not list @wildshard/sdk or @wildshard/sharddev (or it has none)`);
|
|
113
114
|
}
|
|
114
115
|
|
|
115
116
|
/** `wildshard update [dir]`: sync the agent files of the shard repo at `project`, and say what changed, one line each. */
|
package/src/sharddev/author.ts
CHANGED
|
@@ -1,3 +1,16 @@
|
|
|
1
|
-
//
|
|
2
|
-
//
|
|
3
|
-
|
|
1
|
+
// The SDK's starting shardfile (SHARD-AUTHORING SA26): built here and admitted by shard-format's own parser, the one
|
|
2
|
+
// the client runs, so a project starts from a file the game accepts.
|
|
3
|
+
import { parseShardfile, type Shardfile } from '@wildshard/format/shardSchema';
|
|
4
|
+
import { ENTRY_WIDTH } from '@wildshard/format/contentBounds';
|
|
5
|
+
import { SHARDFILE_VERSION } from '@wildshard/format/version';
|
|
6
|
+
|
|
7
|
+
/** Start an author project with a valid empty world; add baked content before shipping a playable shard. */
|
|
8
|
+
export function emptyShardfile(identity: Shardfile['identity']): Shardfile {
|
|
9
|
+
const edge = { heights: Array.from({ length: 257 }, () => 0), colours: Array.from({ length: 257 }, () => [0.5, 0.5, 0.5]), roadHeight: 0 };
|
|
10
|
+
return parseShardfile({ version: SHARDFILE_VERSION, identity, accent: 'sand', requires: { sdk: SHARDFILE_VERSION, capabilities: [], commons: [], commonsWire: {}, commonsCosts: {} }, budgets: { library: { resident: 0, compressed: 0 }, sim: { resident: 0, compressed: 0 }, overlap: 0 },
|
|
11
|
+
entryways: [{ edge: 'north', at: [0, 0, 250], width: ENTRY_WIDTH }, { edge: 'east', at: [250, 0, 0], width: ENTRY_WIDTH }, { edge: 'south', at: [0, 0, -250], width: ENTRY_WIDTH }, { edge: 'west', at: [-250, 0, 0], width: ENTRY_WIDTH }],
|
|
12
|
+
look: { families: [], grade: { exposure: 0, saturation: 1, contrast: 1, lut: null }, clock: 'engine', dayOverride: null, keys: [] },
|
|
13
|
+
sim: { fixedHz: 60, scriptTickDivisor: 2, commandVersion: 0, snapshotVersion: 0, scripts: [] },
|
|
14
|
+
state: { version: 1, sharedOwner: 'host', playerKey: 'actorId', shared: [], player: [] }, authorCaps: { players: 32, speed: 15 },
|
|
15
|
+
serverBudget: { tickMicros: 1000, memory: 1_000_000, entities: 100, commandsPerTick: 32 }, edge: { north: edge, south: edge, east: edge, west: edge }, files: [], tiles: [], library: [], critical: [], far: null });
|
|
16
|
+
}
|
|
@@ -3,7 +3,7 @@ import * as v from 'valibot';
|
|
|
3
3
|
import { isJsonData } from '@wildshard/format/json';
|
|
4
4
|
import { FAMILY_IDS, PbrMaterialSchema } from '@wildshard/format/materialFamilies';
|
|
5
5
|
import { MaterialsSchema, materialGraphIr } from '@wildshard/format/materials';
|
|
6
|
-
import { parseShardfile, type Shardfile } from '@wildshard/
|
|
6
|
+
import { parseShardfile, type Shardfile } from '@wildshard/format/shardSchema';
|
|
7
7
|
import { normalizeWorldGlb, type NormalizedWorld, type WorldPrimitive } from './world';
|
|
8
8
|
import { parseWorldSource } from '../worldSource';
|
|
9
9
|
import { bakeWorldTexture } from './textureWasm';
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { parse, object, array, string, unknown } from 'valibot';
|
|
2
2
|
import { PickupCatalogueSchema, SpecimenBookSchema, type PickupCatalogueRows, type SpecimenBookRows, type SpecimenModelMetadataRows } from '@wildshard/format/specimenCatalogue';
|
|
3
3
|
import pickupRows from '@wildshard/engine/game/data/pickupCatalogue' with { type: 'json' };
|
|
4
|
-
import { namedJsonSchema } from '
|
|
4
|
+
import { namedJsonSchema } from '../formatJsonSchema';
|
|
5
5
|
import { encodeCanonicalJson } from '../immutable';
|
|
6
6
|
import { nameBlob, type NamedBlob, type BlobOptions } from '../blobs';
|
|
7
7
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { MeshStandardMaterial, type BufferGeometry } from 'three';
|
|
2
|
-
import type { Shardfile } from '@wildshard/
|
|
2
|
+
import type { Shardfile } from '@wildshard/format/shardSchema';
|
|
3
3
|
import { parseKtx2 } from '../assets';
|
|
4
4
|
import { hashImmutableBytes } from '../immutable';
|
|
5
5
|
import type { WorldMaterial, WorldTexture } from './world';
|
|
@@ -10,7 +10,7 @@ import { basename, dirname, resolve } from 'node:path';
|
|
|
10
10
|
import * as v from 'valibot';
|
|
11
11
|
import { AuthorProofPlanSchema } from '@wildshard/engine/host/tickProtocol';
|
|
12
12
|
import { measureSimulation, proveAuthorSimulation } from '@wildshard/engine/host/headless';
|
|
13
|
-
import type { Shardfile } from '@wildshard/
|
|
13
|
+
import type { Shardfile } from '@wildshard/format/shardSchema';
|
|
14
14
|
import { buildProject } from './project';
|
|
15
15
|
import { isHandwrittenSource, isRepoSource, shardOutputRoot } from './shardSource';
|
|
16
16
|
import { handwrittenIdentity, settleHandwritten } from './handwritten';
|
package/src/sharddev/cli.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { basename, dirname, resolve } from 'node:path';
|
|
|
3
3
|
// oxlint-disable-next-line import/no-nodejs-modules -- `prove` tells a project from a built product by its config file.
|
|
4
4
|
import { existsSync } from 'node:fs';
|
|
5
5
|
import { buildProject, readProjectAssets, validateProject } from './project';
|
|
6
|
-
import { ShardfileSchema, type Shardfile } from '@wildshard/
|
|
6
|
+
import { ShardfileSchema, type Shardfile } from '@wildshard/format/shardSchema';
|
|
7
7
|
import { devProject } from './dev';
|
|
8
8
|
import { proveAuthorSimulation, measureSimulation, validateSimulation } from '@wildshard/engine/host/headless';
|
|
9
9
|
import { performanceReport, performanceReportLines, type PerformanceObservations } from './reportCard';
|
|
@@ -15,13 +15,14 @@ import { assetOverdraw } from './assets';
|
|
|
15
15
|
import process from 'node:process';
|
|
16
16
|
import { buildBehaviourProject } from './buildBehaviour';
|
|
17
17
|
import { synthProject } from './synth';
|
|
18
|
-
import { formatJsonSchemas, schemaAt, schemaDeclaration } from '
|
|
18
|
+
import { formatJsonSchemas, schemaAt, schemaDeclaration } from './formatJsonSchema';
|
|
19
19
|
import { decisionModuleContracts } from '@wildshard/format/scriptContract';
|
|
20
20
|
import { outputScriptAdmissionRows, validateOutputProduct } from './outputProduct';
|
|
21
21
|
import { locatedError } from './authorError';
|
|
22
22
|
import type { ProjectManifestSource } from './projectManifest';
|
|
23
23
|
import { templateNamed, writeShardRepo } from './newProject';
|
|
24
24
|
import { updateShardRepo } from './agentFiles';
|
|
25
|
+
import { updatePins } from './updatePins';
|
|
25
26
|
import { findShardSource, isHandwrittenSource, isRepoSource, shardOutputRoot } from './shardSource';
|
|
26
27
|
import { checkProject, readProofTape } from './checkProject';
|
|
27
28
|
import { checkLines } from './check';
|
|
@@ -82,11 +83,14 @@ async function runCommand(given: readonly string[], options: CliOptions): Promis
|
|
|
82
83
|
return;
|
|
83
84
|
}
|
|
84
85
|
if (command === 'update') {
|
|
85
|
-
// SA28 (J314 Q7, Q27): one verb
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
86
|
+
// SA28 (J314 Q7, Q27): one verb. SA18: `--pins[=<version>]` also moves the pins, installs, applies the release's
|
|
87
|
+
// codemods and runs check (updatePins.ts); with no version it takes npm's latest.
|
|
88
|
+
const rest = args.slice(1), pins = rest.filter(value => value === '--pins' || value.startsWith('--pins='));
|
|
89
|
+
const positional = rest.filter(value => !pins.includes(value)), version = pins[0]?.startsWith('--pins=') === true ? pins[0].slice('--pins='.length) : 'latest';
|
|
90
|
+
if (pins.length > 1 || version === '' || positional.length > 1 || positional.some(value => value.startsWith('-'))) throw new Error('usage: wildshard update [dir] [--pins[=<version>]]');
|
|
91
|
+
if (pins.length === 1 && /^\d+\.\d+\.\d+/u.test(positional[0] ?? '') && !existsSync(resolve(positional[0] ?? ''))) throw new Error(`usage: wildshard update [dir] [--pins[=<version>]]: name a version as --pins=${positional[0] ?? ''}`);
|
|
92
|
+
if (pins.length === 1) { await updatePins(resolve(positional[0] ?? '.'), version); return; }
|
|
93
|
+
for (const line of updateShardRepo(resolve(positional[0] ?? '.'))) console.info(line);
|
|
90
94
|
return;
|
|
91
95
|
}
|
|
92
96
|
if (input === undefined) throw new Error('usage: wildshard new <dir> | check <source> [folder] [--json] | synth <source> | build <source> [folder] [--shardfile-only|--folder-only] [--no-placeholders] [--output=<slug>] | build <source> --behaviour-only | validate <source|shard.json> | dev <source> [port] (wildshard --help lists them all)');
|