@wildshard/sdk 0.2.6 → 0.2.8

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 CHANGED
@@ -18,13 +18,15 @@ production) each one moves. The **hero** is the shard's card: three images (thum
18
18
  landscape) shown on SHARD SELECT. A **budget** is a limit on what the shard costs a player (section 3). A **refusal**
19
19
  is a command stopping with a rule id, a fix and a link into section 6.
20
20
 
21
- **Running `wildshard` today.** The real `@wildshard/sdk` is not on npm yet: the npm copy is a README-only placeholder
22
- (NPM-PUBLISH NP4 publishes the real one). Until then, run the CLI from a checkout of
23
- `github.com/project-wildshard/sharddev`, for example `alias wildshard='node /path/to/sharddev/bin/wildshard.mjs'`.
24
- This guide writes `wildshard <verb>`. `wildshard --help` lists every verb; `wildshard <verb> --help` prints one.
25
- `wildshard --version` prints the sdk, engine, shard-format and `three` versions. `new` writes a `package.json` that pins
26
- `@wildshard/sdk`, shard-format, engine and `three` exactly; once the sdk is on npm, `pnpm install` then
27
- `pnpm exec wildshard <verb>` runs the copy it pins. Add npm packages of your own with `pnpm add <name>`.
21
+ **Running `wildshard` today.** Install the published SDK with `pnpm add @wildshard/sdk`, then run
22
+ `pnpm exec wildshard <verb>`. The intended npm command is `npm install @wildshard/sdk`, but the current release
23
+ fails with `EUNSUPPORTEDPROTOCOL`: npm prepares its git-hosted engine dependency and cannot read engine's `link:`
24
+ devDependency. Use pnpm until NPM-PUBLISH NP7 publishes the dependency switch.
25
+ This guide writes `wildshard <verb>`. `wildshard --help` lists every verb;
26
+ `wildshard <verb> --help` prints one. `wildshard --version` prints the sdk, engine, shard-format and `three` versions.
27
+ `new` writes a `package.json` that pins `@wildshard/sdk`, shard-format, engine and `three` exactly;
28
+ run `pnpm install` in the new project, then `pnpm exec wildshard <verb>` to use the copy it pins.
29
+ Add npm packages of your own with `pnpm add <name>`.
28
30
 
29
31
  ## 1. The loop
30
32
 
@@ -35,10 +37,10 @@ repo's one `src/shards/<slug>/`).
35
37
  | # | Step | Command | Today |
36
38
  |---|---|---|---|
37
39
  | 1 | Start | `wildshard new my-shard` | Works. Writes a shard repo in `my-shard/`: the reference world (Template 1, Mossgate) as its shard source at `src/`, plus `package.json`, `tsconfig.json`, `.gitignore`, `.npmrc`, a README, this guide, the four `wildshard` skills and the agent files (`AGENTS.md`, `CLAUDE.md`, `.agents/skills/`) |
38
- | 2 | Walk it | `wildshard dev .` | **Not built yet (SA15).** See "Walking your shard" below |
40
+ | 2 | Walk it | `wildshard dev .` | Works. The first run fetches engine's dev client once. See "Walking your shard" below |
39
41
  | 3 | Check | `wildshard check .` | Works: lint, build, validate, prove and the report card, one verdict |
40
- | 4 | Hero | `wildshard hero . --base <url>` | Works only with an engine checkout: it needs your shard in a served engine build. See "The hero" below |
41
- | 5 | Prepare | `wildshard prepare public/shardfiles/my-shard --base <url>`, then `wildshard build public/shardfiles/my-shard` | Works only with an engine checkout. See "Uploading" below |
42
+ | 4 | Hero | `wildshard hero . --base <url>` | Works, with `wildshard dev .` running: `<url>` is the one it prints. See "The hero" below |
43
+ | 5 | Prepare | `wildshard prepare public/shardfiles/my-shard`, then `wildshard build public/shardfiles/my-shard` | The first run fetches engine's preparation client once. See "Uploading" below |
42
44
  | 6 | Upload to staging | `wildshard upload public/shardfiles/my-shard.shardfile --channel staging --version 0.0.1` | Works only for the Wildshard team today: it needs the team's creator key. See "Uploading" below |
43
45
  | 7 | Upload to production | the same with `--channel prod` and a higher version | The same. Try staging first |
44
46
  | 8 | Share | `https://staging.wildshard.io/slug/my-shard` | **Not built yet (SA36, SA37).** See section 5 |
@@ -54,7 +56,7 @@ with `rule`, `fix` and `guide`) for agents and scripts.
54
56
  |---|---|
55
57
  | `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
58
  | `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
- | `wildshard dev <source>` | Serve the shard source on localhost and rebuild on every save (section 4). **Not built yet** for an installed sdk (SA15) |
59
+ | `wildshard dev <source>` | Serve the shard source on localhost and rebuild on every save (section 4). The first run fetches engine's dev client once ("Walking your shard") |
58
60
  | `wildshard check <source> [folder] [--json]` | The loop's check: lint, build, validate, prove, report card, verdict |
59
61
  | `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 |
60
62
  | `wildshard upload <file> --channel staging\|prod` | Send a prepared shard file to the API (section 5) |
@@ -62,30 +64,28 @@ with `rule`, `fix` and `guide`) for agents and scripts.
62
64
  | `wildshard whoami` | Say which account key upload would send (from `WILDSHARD_API_KEY` or the key file), show its first characters, and print its account's email and how many slugs it owns (`--server` or `WILDSHARD_API_URL`) |
63
65
  | `wildshard delete <slug> [--yes]` | Delete your shard from the catalogue, every channel and the grid, after you type its slug (see "Deleting a shard") |
64
66
  | `wildshard build <source>` | Build alone: bake the shard source into `public/shardfiles/<slug>/` and write `public/shardfiles/<slug>.shardfile`. `wildshard build <folder>` writes the shard file of a built folder (after `prepare`) |
65
- | `wildshard prepare <folder> --base <url>` | Record the built folder in phone WebKit against an exact engine preview, which turns a draft into the uploadable form (see "Uploading") |
67
+ | `wildshard prepare <folder> [--base <url>]` | Record the built folder in phone WebKit against engine's preparation client (or the exact engine preview `--base` names), which turns a draft into the uploadable form (see "Uploading") |
66
68
  | `wildshard validate <source \| folder>` | Shard-format's checks and the headless budget run, alone |
67
69
  | `wildshard prove <source> <proof.json>` | Play a proof tape headlessly and print what happened |
68
70
  | `wildshard synth <source>` | Run `shard.config.ts`'s scene exports and write the scene as data |
69
71
  | `wildshard schema [list\|shardfile\|<root>] [pointer]` | Print the JSON Schema of the shard file, or of one section or field |
70
72
  | `wildshard serve` | The sharddev web app on localhost (tools for this repo, not for your shard) |
71
- | `wildshard build-shards` | Build every shard source under a repo's `src/shards/` (repos holding several shards) |
73
+ | `wildshard build-shards` | Build every shard source in the repo: its `src/` (a single-shard repo) and each `src/shards/<folder>/` (repos holding several shards) |
72
74
  | `wildshard pack <folder>` | Old name for `wildshard build <folder>`; use `build` |
73
75
 
74
76
  ### Walking your shard
75
77
 
76
- `wildshard dev .` is how you will walk a shard on your machine: it serves the shard on localhost and reloads the page
77
- when you save. It is **not built yet (SA15)**: today it stops with "wildshard dev requires the SDK devserver client",
78
- also from a sharddev checkout. Engine has to publish the dev client first (HOW-WE-BUILD ENG-16, then SD-2).
78
+ `wildshard dev .` walks the shard on your machine: it serves the shard on localhost and reloads the page when you
79
+ save (section 4). Open the URL it prints; it ends in `?skipintro`, which walks straight into your shard. Ctrl-C stops
80
+ it and frees the port.
79
81
 
80
- Until then there are two ways to walk a shard, and neither works from this folder alone:
82
+ The first run fetches engine's dev client once, from the engine release at this sdk's engine pin, into
83
+ `~/.cache/wildshard/dev-client/` (about 300 MB; `$WILDSHARD_DEV_CLIENT_CACHE` moves it). Later runs, and every project
84
+ on the same sdk, reuse it. If the download fails, `dev` stops and says which release it asked for; nothing half-fetched
85
+ is kept, so run it again.
81
86
 
82
- - **In an engine checkout:** build an engine preview that carries your built shard file folder, then enter it from
83
- SHARD SELECT. These steps are not written down for authors yet (HOW-WE-BUILD F5 writes them, in sharddev
84
- `docs/second-machine.md`): ask the Wildshard team.
85
- - **On staging, after an upload:** only once the Wildshard team has placed the shard on the grid (section 5).
86
-
87
- What you can do from this folder alone: `wildshard check .` builds the shard, runs it headlessly against its budgets
88
- and, with a `proof.json` tape, plays its quests headlessly (`prove`).
87
+ `dev` serves this shard alone: no other shards, no grid and no other players. To see it beside the rest of the
88
+ world, upload it to staging once the Wildshard team has placed it on the grid (section 5).
89
89
 
90
90
  ### The hero
91
91
 
@@ -93,12 +93,13 @@ The hero is three images: thumb 640x360, portrait 804x1626 and landscape 1600x90
93
93
  generated card (a `data:` image) so it has one from the start. Build accepts that card with a note. To capture a real
94
94
  hero:
95
95
 
96
- 1. Point `card.thumb`, `card.portrait` and `card.landscape` in `manifest.json` at image files inside the shard source
97
- (for example `card/thumb.jpg`). Hero capture refuses a `data:` card.
98
- 2. Serve an engine build that carries this exact shard (see "Walking your shard": an engine checkout today).
99
- 3. Run `wildshard hero . --base <served-build-url>`. It opens the build in headless Chromium, enters your shard from
100
- SHARD SELECT, shoots the view `hero.json`'s `camera` names (or the spawn view), writes the three files and stamps
101
- `hero.json` with a hash of your content.
96
+ 1. Run `wildshard dev .` and leave it running. Any served build that carries this exact shard works too (an engine
97
+ checkout's, entered from SHARD SELECT).
98
+ 2. Run `wildshard hero . --base <url>` with the URL `dev` printed. It opens that page in headless Chromium, enters your
99
+ shard, shoots the view `hero.json`'s `camera` names (or the spawn view), writes the three files and stamps
100
+ `hero.json` with a hash of your content. A `data:` card becomes `card/thumb.jpg`, `card/portrait.jpg` and
101
+ `card/landscape.jpg`, named in both `manifest.json` and `data/card.json`.
102
+ 3. Look at the three images, then stop `dev` with Ctrl-C.
102
103
 
103
104
  Build then refuses a shard file whose content changed after the hero was stamped (`hero-stale`), and upload refuses a
104
105
  new version whose hero is the same as the previous version's (`hero-unchanged`). Section 6 has every hero refusal.
@@ -115,11 +116,11 @@ before every upload:
115
116
  Every time: commit everything, the hero included. Done when `git status` is clean.
116
117
  3. **Check.** `wildshard check .` builds the shard file. It is a **draft** (`sdk: "0.2"`): check prints a
117
118
  `shardfile-draft` warning, and upload and the API refuse a draft. Done at `check pass`.
118
- 4. **Prepare.** `wildshard prepare public/shardfiles/<slug> --base <url>`, with the URL of an exact engine preview made
119
- for preparation, turns the draft into the uploadable form (`sdk: "0.3"`). Then `wildshard build
120
- public/shardfiles/<slug>` writes the prepared shard file. That preview comes from an engine checkout today, so an
121
- author outside the Wildshard team cannot prepare yet: the steps are not written down for authors (HOW-WE-BUILD F5);
122
- ask the Wildshard team.
119
+ 4. **Prepare.** `wildshard prepare public/shardfiles/<slug>` records the draft in phone WebKit and turns it into the
120
+ uploadable form (`sdk: "0.3"`). It serves engine's preparation client around the draft itself, fetched once from
121
+ engine's release at the SDK's engine pin (about 310 MB, kept in `~/.cache/wildshard/dev-client`), so no engine
122
+ checkout is needed. Then `wildshard build public/shardfiles/<slug>` writes the prepared shard file. Done when
123
+ prepare prints `{"slug":…,"programs":…}` and build prints the shard file line.
123
124
  5. **Keys.** Set `WILDSHARD_API_URL=https://api.wildshard.io` (or pass `--server`) and
124
125
  `WILDSHARD_CREATOR_PRIVATE_KEY`, the base64 creator key upload signs with. There is one Wildshard creator key and
125
126
  no per-author creator keys yet: ask the Wildshard team for it, and never commit it. Upload also sends your
@@ -242,8 +243,6 @@ guide names them and points at what prints them:
242
243
 
243
244
  ## 4. What reloads under `dev`
244
245
 
245
- `wildshard dev` is **not built yet** for an installed sdk (SA15); this is how it behaves once it runs.
246
-
247
246
  - **Every saved file in the shard source rebuilds the whole shard**, about 0.1 s after the last save, and the open page
248
247
  reloads itself when the new build is ready. Nothing is patched in place: data, generators, behaviour scripts,
249
248
  assets, `shard.config.ts` and `manifest.json` all take the same path.
@@ -0,0 +1,204 @@
1
+ # @wildshard/sdk exports, by tier
2
+
3
+ <!-- generated by scripts/export-tiers.mjs from package.json exports and lint/export-tiers.json: do not edit -->
4
+
5
+ 164 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
+
7
+ ## contract (28)
8
+
9
+ The project contract: what a shard project declares and what a build reads and writes (identity, manifest, outputs, blobs, admission).
10
+
11
+ | Export | Tier | File |
12
+ |---|---|---|
13
+ | `@wildshard/sdk/admission` | contract | `./src/sharddev/admission.ts` |
14
+ | `@wildshard/sdk/assetHandle` | contract | `./src/sharddev/assetHandle.ts` |
15
+ | `@wildshard/sdk/assets` | contract | `./src/sharddev/assets.ts` |
16
+ | `@wildshard/sdk/author` | contract | `./src/sharddev/author.ts` |
17
+ | `@wildshard/sdk/blobBytes` | contract | `./src/sharddev/blobBytes.ts` |
18
+ | `@wildshard/sdk/blobs` | contract | `./src/sharddev/blobs.ts` |
19
+ | `@wildshard/sdk/bootInventory` | contract | `./src/sharddev/bootInventory.ts` |
20
+ | `@wildshard/sdk/entryReads` | contract | `./src/sharddev/entryReads.ts` |
21
+ | `@wildshard/sdk/formatJsonSchema` | contract | `./src/sharddev/formatJsonSchema.ts` |
22
+ | `@wildshard/sdk/immutable` | contract | `./src/sharddev/immutable.ts` |
23
+ | `@wildshard/sdk/measure` | contract | `./src/sharddev/measure.ts` |
24
+ | `@wildshard/sdk/outputProduct` | contract | `./src/sharddev/outputProduct.ts` |
25
+ | `@wildshard/sdk/outputRuntime` | contract | `./src/sharddev/outputRuntime.ts` |
26
+ | `@wildshard/sdk/package.json` | contract | `./package.json` |
27
+ | `@wildshard/sdk/platformSections` | contract | `./src/sharddev/platformSections.ts` |
28
+ | `@wildshard/sdk/productOutput` | contract | `./src/sharddev/productOutput.ts` |
29
+ | `@wildshard/sdk/project` | contract | `./src/sharddev/project.ts` |
30
+ | `@wildshard/sdk/projectDecisions` | contract | `./src/sharddev/projectDecisions.ts` |
31
+ | `@wildshard/sdk/projectGeneration` | contract | `./src/sharddev/projectGeneration.ts` |
32
+ | `@wildshard/sdk/projectManifest` | contract | `./src/sharddev/projectManifest.ts` |
33
+ | `@wildshard/sdk/projectMap` | contract | `./src/sharddev/projectMap.ts` |
34
+ | `@wildshard/sdk/projectOutput` | contract | `./src/sharddev/projectOutput.ts` |
35
+ | `@wildshard/sdk/reportCard` | contract | `./src/sharddev/reportCard.ts` |
36
+ | `@wildshard/sdk/schemaValidation` | contract | `./src/sharddev/schemaValidation.ts` |
37
+ | `@wildshard/sdk/sections` | contract | `./src/sharddev/sections.ts` |
38
+ | `@wildshard/sdk/synth` | contract | `./src/sharddev/synth.ts` |
39
+ | `@wildshard/sdk/version` | contract | `./src/sharddev/version.ts` |
40
+ | `@wildshard/sdk/worldSource` | contract | `./src/sharddev/worldSource.ts` |
41
+
42
+ ## rows (35)
43
+
44
+ Content rows: typed helpers that write a section of the shardfile (species, quests, movers, scenes, audio).
45
+
46
+ | Export | Tier | File |
47
+ |---|---|---|
48
+ | `@wildshard/sdk/arenaView` | rows | `./src/sharddev/arenaView.ts` |
49
+ | `@wildshard/sdk/audio` | rows | `./src/sharddev/audio.ts` |
50
+ | `@wildshard/sdk/bossProfiles` | rows | `./src/sharddev/bossProfiles.ts` |
51
+ | `@wildshard/sdk/clientChannels` | rows | `./src/sharddev/clientChannels.ts` |
52
+ | `@wildshard/sdk/crowds` | rows | `./src/sharddev/crowds.ts` |
53
+ | `@wildshard/sdk/director` | rows | `./src/sharddev/director.ts` |
54
+ | `@wildshard/sdk/eliteEntryRows` | rows | `./src/sharddev/eliteEntryRows.ts` |
55
+ | `@wildshard/sdk/entries` | rows | `./src/sharddev/entries.ts` |
56
+ | `@wildshard/sdk/finds` | rows | `./src/sharddev/finds.ts` |
57
+ | `@wildshard/sdk/interactions` | rows | `./src/sharddev/interactions.ts` |
58
+ | `@wildshard/sdk/ledger` | rows | `./src/sharddev/ledger.ts` |
59
+ | `@wildshard/sdk/looks/tileField` | rows | `./src/sharddev/looks/tileField.ts` |
60
+ | `@wildshard/sdk/materials` | rows | `./src/sharddev/materials.ts` |
61
+ | `@wildshard/sdk/modes` | rows | `./src/sharddev/modes.ts` |
62
+ | `@wildshard/sdk/movers` | rows | `./src/sharddev/movers.ts` |
63
+ | `@wildshard/sdk/nativePopulationRows` | rows | `./src/sharddev/nativePopulationRows.ts` |
64
+ | `@wildshard/sdk/phasedBoss` | rows | `./src/sharddev/phasedBoss.ts` |
65
+ | `@wildshard/sdk/physics` | rows | `./src/sharddev/physics.ts` |
66
+ | `@wildshard/sdk/plumbing` | rows | `./src/sharddev/plumbing.ts` |
67
+ | `@wildshard/sdk/questGraph` | rows | `./src/sharddev/questGraph.ts` |
68
+ | `@wildshard/sdk/quests` | rows | `./src/sharddev/quests.ts` |
69
+ | `@wildshard/sdk/rows` | rows | `./src/sharddev/rows.ts` |
70
+ | `@wildshard/sdk/scene` | rows | `./src/sharddev/scene.ts` |
71
+ | `@wildshard/sdk/sceneAnimation` | rows | `./src/sharddev/sceneAnimation.ts` |
72
+ | `@wildshard/sdk/sceneAudio` | rows | `./src/sharddev/sceneAudio.ts` |
73
+ | `@wildshard/sdk/sceneGraph` | rows | `./src/sharddev/sceneGraph.ts` |
74
+ | `@wildshard/sdk/spawns` | rows | `./src/sharddev/spawns.ts` |
75
+ | `@wildshard/sdk/species` | rows | `./src/sharddev/species.ts` |
76
+ | `@wildshard/sdk/species/clips` | rows | `./src/sharddev/species/clips.ts` |
77
+ | `@wildshard/sdk/speciesBrains` | rows | `./src/sharddev/speciesBrains.ts` |
78
+ | `@wildshard/sdk/weapons/bowProfile` | rows | `./src/sharddev/weapons/bowProfile.ts` |
79
+ | `@wildshard/sdk/weapons/firearmRows` | rows | `./src/sharddev/weapons/firearmRows.ts` |
80
+ | `@wildshard/sdk/weapons/meleeProfile` | rows | `./src/sharddev/weapons/meleeProfile.ts` |
81
+ | `@wildshard/sdk/weapons/thrownProfile` | rows | `./src/sharddev/weapons/thrownProfile.ts` |
82
+ | `@wildshard/sdk/worldScenes` | rows | `./src/sharddev/worldScenes.ts` |
83
+
84
+ ## scripts (17)
85
+
86
+ Scripts: the decision and client script compilers, their AssemblyScript helpers and the director ABI.
87
+
88
+ | Export | Tier | File |
89
+ |---|---|---|
90
+ | `@wildshard/sdk/as/groupBankV2` | scripts | `./src/sharddev/as/groupBankV2.ts` |
91
+ | `@wildshard/sdk/as/groupStepV2` | scripts | `./src/sharddev/as/groupStepV2.ts` |
92
+ | `@wildshard/sdk/as/ws` | scripts | `./src/sharddev/as/ws.ts` |
93
+ | `@wildshard/sdk/as/wsV2` | scripts | `./src/sharddev/as/wsV2.ts` |
94
+ | `@wildshard/sdk/buildBehaviour` | scripts | `./src/sharddev/buildBehaviour.ts` |
95
+ | `@wildshard/sdk/buildDecisionScripts` | scripts | `./src/sharddev/buildDecisionScripts.ts` |
96
+ | `@wildshard/sdk/clientScripts` | scripts | `./src/sharddev/clientScripts.ts` |
97
+ | `@wildshard/sdk/commons/scripts/course.as` | scripts | `./src/commons/scripts/course.as` |
98
+ | `@wildshard/sdk/compileMovers` | scripts | `./src/sharddev/compileMovers.ts` |
99
+ | `@wildshard/sdk/compileScript` | scripts | `./src/sharddev/bake/compileScript.ts` |
100
+ | `@wildshard/sdk/compileScriptV2` | scripts | `./src/sharddev/bake/compileScriptV2.ts` |
101
+ | `@wildshard/sdk/decisionBindingMap` | scripts | `./src/sharddev/decisionBindingMap.ts` |
102
+ | `@wildshard/sdk/decisionScriptBindings` | scripts | `./src/sharddev/decisionScriptBindings.ts` |
103
+ | `@wildshard/sdk/decisionScripts` | scripts | `./src/sharddev/decisionScripts.ts` |
104
+ | `@wildshard/sdk/decisionSource` | scripts | `./src/sharddev/decisionSource.ts` |
105
+ | `@wildshard/sdk/directorAbi` | scripts | `./src/sharddev/directorAbi.ts` |
106
+ | `@wildshard/sdk/returnProjectionV2` | scripts | `./src/sharddev/returnProjectionV2.ts` |
107
+
108
+ ## bake kit (78)
109
+
110
+ The bake kit: build-time geometry, texture, map and commons helpers; nothing here runs in the game.
111
+
112
+ | Export | Tier | File |
113
+ |---|---|---|
114
+ | `@wildshard/sdk/bake` | bake kit | `./src/sharddev/bake.ts` |
115
+ | `@wildshard/sdk/bake/annulus` | bake kit | `./src/sharddev/bake/annulus.ts` |
116
+ | `@wildshard/sdk/bake/basisGlb` | bake kit | `./src/sharddev/bake/basisGlb.ts` |
117
+ | `@wildshard/sdk/bake/byteCodec` | bake kit | `./src/sharddev/bake/byteCodec.ts` |
118
+ | `@wildshard/sdk/bake/canvasAtlas` | bake kit | `./src/sharddev/bake/canvasAtlas.ts` |
119
+ | `@wildshard/sdk/bake/coarseCopy` | bake kit | `./src/sharddev/bake/coarseCopy.ts` |
120
+ | `@wildshard/sdk/bake/colliders` | bake kit | `./src/sharddev/bake/colliders.ts` |
121
+ | `@wildshard/sdk/bake/compactGlb` | bake kit | `./src/sharddev/bake/compactGlb.ts` |
122
+ | `@wildshard/sdk/bake/contactRows` | bake kit | `./src/sharddev/bake/contactRows.ts` |
123
+ | `@wildshard/sdk/bake/creaturePlacement` | bake kit | `./src/sharddev/bake/creaturePlacement.ts` |
124
+ | `@wildshard/sdk/bake/export` | bake kit | `./src/sharddev/bake/export.ts` |
125
+ | `@wildshard/sdk/bake/facetedGeometry` | bake kit | `./src/sharddev/bake/facetedGeometry.ts` |
126
+ | `@wildshard/sdk/bake/farImpostor` | bake kit | `./src/sharddev/bake/farImpostor.ts` |
127
+ | `@wildshard/sdk/bake/forest` | bake kit | `./src/sharddev/bake/forest.ts` |
128
+ | `@wildshard/sdk/bake/generatorGlb` | bake kit | `./src/sharddev/bake/generatorGlb.ts` |
129
+ | `@wildshard/sdk/bake/geometryBounds` | bake kit | `./src/sharddev/bake/geometryBounds.ts` |
130
+ | `@wildshard/sdk/bake/geometryError` | bake kit | `./src/sharddev/bake/geometryError.ts` |
131
+ | `@wildshard/sdk/bake/glb` | bake kit | `./src/sharddev/bake/glb.ts` |
132
+ | `@wildshard/sdk/bake/glbCompression` | bake kit | `./src/sharddev/bake/glbCompression.ts` |
133
+ | `@wildshard/sdk/bake/groundMap` | bake kit | `./src/sharddev/bake/groundMap.ts` |
134
+ | `@wildshard/sdk/bake/image` | bake kit | `./src/sharddev/bake/image.ts` |
135
+ | `@wildshard/sdk/bake/keyedSky` | bake kit | `./src/sharddev/bake/keyedSky.ts` |
136
+ | `@wildshard/sdk/bake/kinds` | bake kit | `./src/sharddev/bake/kinds.ts` |
137
+ | `@wildshard/sdk/bake/lightSources` | bake kit | `./src/sharddev/bake/lightSources.ts` |
138
+ | `@wildshard/sdk/bake/mapAssembly` | bake kit | `./src/sharddev/bake/mapAssembly.ts` |
139
+ | `@wildshard/sdk/bake/mapRaster` | bake kit | `./src/sharddev/bake/mapRaster.ts` |
140
+ | `@wildshard/sdk/bake/mapRest` | bake kit | `./src/sharddev/bake/mapRest.ts` |
141
+ | `@wildshard/sdk/bake/materialGraph` | bake kit | `./src/sharddev/bake/materialGraph.ts` |
142
+ | `@wildshard/sdk/bake/meadow` | bake kit | `./src/sharddev/bake/meadow.ts` |
143
+ | `@wildshard/sdk/bake/nativeInteractionFacts` | bake kit | `./src/sharddev/bake/nativeInteractionFacts.ts` |
144
+ | `@wildshard/sdk/bake/nativeLattice` | bake kit | `./src/sharddev/bake/nativeLattice.ts` |
145
+ | `@wildshard/sdk/bake/nativeRaster` | bake kit | `./src/sharddev/bake/nativeRaster.ts` |
146
+ | `@wildshard/sdk/bake/nativeTerrainField` | bake kit | `./src/sharddev/bake/nativeTerrainField.ts` |
147
+ | `@wildshard/sdk/bake/navigation` | bake kit | `./src/sharddev/bake/navigation.ts` |
148
+ | `@wildshard/sdk/bake/navigationAsset` | bake kit | `./src/sharddev/bake/navigationAsset.ts` |
149
+ | `@wildshard/sdk/bake/nearPlaceholder` | bake kit | `./src/sharddev/bake/nearPlaceholder.ts` |
150
+ | `@wildshard/sdk/bake/normalizeRig` | bake kit | `./src/sharddev/bake/normalizeRig.ts` |
151
+ | `@wildshard/sdk/bake/placeholders` | bake kit | `./src/sharddev/bake/placeholders.ts` |
152
+ | `@wildshard/sdk/bake/placement` | bake kit | `./src/sharddev/bake/placement.ts` |
153
+ | `@wildshard/sdk/bake/portableBytes` | bake kit | `./src/sharddev/bake/portableBytes.ts` |
154
+ | `@wildshard/sdk/bake/practiceCourse` | bake kit | `./src/sharddev/bake/practiceCourse.ts` |
155
+ | `@wildshard/sdk/bake/primitives` | bake kit | `./src/sharddev/bake/primitives.ts` |
156
+ | `@wildshard/sdk/bake/props` | bake kit | `./src/sharddev/bake/props.ts` |
157
+ | `@wildshard/sdk/bake/questPlacement` | bake kit | `./src/sharddev/bake/questPlacement.ts` |
158
+ | `@wildshard/sdk/bake/rawTexture` | bake kit | `./src/sharddev/bake/rawTexture.ts` |
159
+ | `@wildshard/sdk/bake/riderArms` | bake kit | `./src/sharddev/bake/riderArms.ts` |
160
+ | `@wildshard/sdk/bake/rig` | bake kit | `./src/sharddev/bake/rig.ts` |
161
+ | `@wildshard/sdk/bake/riggedHullRecipes` | bake kit | `./src/sharddev/bake/riggedHullRecipes.ts` |
162
+ | `@wildshard/sdk/bake/signPlacements` | bake kit | `./src/sharddev/bake/signPlacements.ts` |
163
+ | `@wildshard/sdk/bake/simplifier` | bake kit | `./src/sharddev/bake/simplifier.ts` |
164
+ | `@wildshard/sdk/bake/skinned` | bake kit | `./src/sharddev/bake/skinned.ts` |
165
+ | `@wildshard/sdk/bake/slabs` | bake kit | `./src/sharddev/bake/slabs.ts` |
166
+ | `@wildshard/sdk/bake/sourceMetadata` | bake kit | `./src/sharddev/bake/sourceMetadata.ts` |
167
+ | `@wildshard/sdk/bake/species` | bake kit | `./src/sharddev/bake/species.ts` |
168
+ | `@wildshard/sdk/bake/specimenCatalogue` | bake kit | `./src/sharddev/bake/specimenCatalogue.ts` |
169
+ | `@wildshard/sdk/bake/splatGround` | bake kit | `./src/sharddev/bake/splatGround.ts` |
170
+ | `@wildshard/sdk/bake/staticMaterials` | bake kit | `./src/sharddev/bake/staticMaterials.ts` |
171
+ | `@wildshard/sdk/bake/terrain` | bake kit | `./src/sharddev/bake/terrain.ts` |
172
+ | `@wildshard/sdk/bake/texture` | bake kit | `./src/sharddev/bake/texture.ts` |
173
+ | `@wildshard/sdk/bake/textureWasm` | bake kit | `./src/sharddev/bake/textureWasm.ts` |
174
+ | `@wildshard/sdk/bake/tileEncoder` | bake kit | `./src/sharddev/bake/tileEncoder.ts` |
175
+ | `@wildshard/sdk/bake/tileGrid` | bake kit | `./src/sharddev/bake/tileGrid.ts` |
176
+ | `@wildshard/sdk/bake/wholePartition` | bake kit | `./src/sharddev/bake/wholePartition.ts` |
177
+ | `@wildshard/sdk/bake/wholePieceJoin` | bake kit | `./src/sharddev/bake/wholePieceJoin.ts` |
178
+ | `@wildshard/sdk/bake/world` | bake kit | `./src/sharddev/bake/world.ts` |
179
+ | `@wildshard/sdk/bake/worldCollision` | bake kit | `./src/sharddev/bake/worldCollision.ts` |
180
+ | `@wildshard/sdk/bake/worldLod` | bake kit | `./src/sharddev/bake/worldLod.ts` |
181
+ | `@wildshard/sdk/bake/worldRows` | bake kit | `./src/sharddev/bake/worldRows.ts` |
182
+ | `@wildshard/sdk/commons` | bake kit | `./src/sharddev/commons.ts` |
183
+ | `@wildshard/sdk/commons/bake/portableMath` | bake kit | `./src/commons/bake/portableMath.ts` |
184
+ | `@wildshard/sdk/commons/catalogue` | bake kit | `./src/commons/catalogue.ts` |
185
+ | `@wildshard/sdk/commons/courseProgram` | bake kit | `./src/commons/courseProgram.ts` |
186
+ | `@wildshard/sdk/commons/practiceCourse` | bake kit | `./src/commons/practiceCourse.ts` |
187
+ | `@wildshard/sdk/commonsCosts` | bake kit | `./src/sharddev/commonsCosts.ts` |
188
+ | `@wildshard/sdk/kit/bakedGeometry` | bake kit | `./src/sharddev/kit/bakedGeometry.ts` |
189
+ | `@wildshard/sdk/kit/geometryPack` | bake kit | `./src/sharddev/kit/geometryPack.ts` |
190
+ | `@wildshard/sdk/noise` | bake kit | `./src/sharddev/noise.ts` |
191
+ | `@wildshard/sdk/random` | bake kit | `./src/sharddev/random.ts` |
192
+
193
+ ## internal (6)
194
+
195
+ Internal: exported for sharddev's own tools and tests; a shard project must not import it, and it may change in any release.
196
+
197
+ | Export | Tier | File |
198
+ |---|---|---|
199
+ | `@wildshard/sdk/configBoundary` | internal | `./src/sharddev/configBoundary.ts` |
200
+ | `@wildshard/sdk/executeBundle` | internal | `./src/sharddev/executeBundle.ts` |
201
+ | `@wildshard/sdk/runtimeMirrors` | internal | `./src/sharddev/runtimeMirrors.ts` |
202
+ | `@wildshard/sdk/scripts/*` | internal | `./scripts/*` |
203
+ | `@wildshard/sdk/sourceReader` | internal | `./src/sharddev/sourceReader.ts` |
204
+ | `@wildshard/sdk/test/compileDualScriptV2` | internal | `./src/sharddev/test/compileDualScriptV2.ts` |
@@ -0,0 +1,176 @@
1
+ {
2
+ "//": "SHARD-AUTHORING SA5 (J317): every @wildshard/sdk export (package.json exports) in one tier. test/export-tiers.test.ts fails on an export with no row here, a row for no export, or an unknown tier; scripts/export-tiers.mjs renders docs/api/EXPORT-TIERS.md from it.",
3
+ "tiers": {
4
+ "contract": "The project contract: what a shard project declares and what a build reads and writes (identity, manifest, outputs, blobs, admission).",
5
+ "rows": "Content rows: typed helpers that write a section of the shardfile (species, quests, movers, scenes, audio).",
6
+ "scripts": "Scripts: the decision and client script compilers, their AssemblyScript helpers and the director ABI.",
7
+ "bake kit": "The bake kit: build-time geometry, texture, map and commons helpers; nothing here runs in the game.",
8
+ "internal": "Internal: exported for sharddev's own tools and tests; a shard project must not import it, and it may change in any release."
9
+ },
10
+ "exports": {
11
+ "./package.json": "contract",
12
+ "./entryReads": "contract",
13
+ "./immutable": "contract",
14
+ "./bake/tileEncoder": "bake kit",
15
+ "./bake/wholePartition": "bake kit",
16
+ "./bake/basisGlb": "bake kit",
17
+ "./bake/placement": "bake kit",
18
+ "./bake/colliders": "bake kit",
19
+ "./bake/questPlacement": "bake kit",
20
+ "./bake/contactRows": "bake kit",
21
+ "./bake/sourceMetadata": "bake kit",
22
+ "./bake/forest": "bake kit",
23
+ "./bake/materialGraph": "bake kit",
24
+ "./bake/meadow": "bake kit",
25
+ "./bake/annulus": "bake kit",
26
+ "./bake/primitives": "bake kit",
27
+ "./bake/creaturePlacement": "bake kit",
28
+ "./bake/geometryBounds": "bake kit",
29
+ "./noise": "bake kit",
30
+ "./bake/groundMap": "bake kit",
31
+ "./bake/mapAssembly": "bake kit",
32
+ "./bake/mapRaster": "bake kit",
33
+ "./bake/riderArms": "bake kit",
34
+ "./bake/species": "bake kit",
35
+ "./decisionBindingMap": "scripts",
36
+ "./projectManifest": "contract",
37
+ "./outputRuntime": "contract",
38
+ "./reportCard": "contract",
39
+ "./crowds": "rows",
40
+ "./species": "rows",
41
+ "./version": "contract",
42
+ "./author": "contract",
43
+ "./assets": "contract",
44
+ "./bootInventory": "contract",
45
+ "./project": "contract",
46
+ "./projectGeneration": "contract",
47
+ "./projectOutput": "contract",
48
+ "./ledger": "rows",
49
+ "./bake/terrain": "bake kit",
50
+ "./quests": "rows",
51
+ "./audio": "rows",
52
+ "./rows": "rows",
53
+ "./plumbing": "rows",
54
+ "./bake/props": "bake kit",
55
+ "./bake/tileGrid": "bake kit",
56
+ "./bake/simplifier": "bake kit",
57
+ "./bake/glb": "bake kit",
58
+ "./bake/specimenCatalogue": "bake kit",
59
+ "./bake/lightSources": "bake kit",
60
+ "./bake/canvasAtlas": "bake kit",
61
+ "./bake/nativeRaster": "bake kit",
62
+ "./bake/keyedSky": "bake kit",
63
+ "./bake/coarseCopy": "bake kit",
64
+ "./bake/glbCompression": "bake kit",
65
+ "./bake/generatorGlb": "bake kit",
66
+ "./bake/compactGlb": "bake kit",
67
+ "./bake/nearPlaceholder": "bake kit",
68
+ "./bake/placeholders": "bake kit",
69
+ "./bake/farImpostor": "bake kit",
70
+ "./bake/kinds": "bake kit",
71
+ "./bake/texture": "bake kit",
72
+ "./bake/rawTexture": "bake kit",
73
+ "./bake/byteCodec": "bake kit",
74
+ "./bake/export": "bake kit",
75
+ "./movers": "rows",
76
+ "./director": "rows",
77
+ "./clientScripts": "scripts",
78
+ "./clientChannels": "rows",
79
+ "./speciesBrains": "rows",
80
+ "./phasedBoss": "rows",
81
+ "./admission": "contract",
82
+ "./commons": "bake kit",
83
+ "./commonsCosts": "bake kit",
84
+ "./worldSource": "contract",
85
+ "./weapons/meleeProfile": "rows",
86
+ "./weapons/thrownProfile": "rows",
87
+ "./bake/world": "bake kit",
88
+ "./weapons/bowProfile": "rows",
89
+ "./bake/textureWasm": "bake kit",
90
+ "./bake/worldLod": "bake kit",
91
+ "./bake/worldCollision": "bake kit",
92
+ "./bake/nativeLattice": "bake kit",
93
+ "./bake/splatGround": "bake kit",
94
+ "./bake/worldRows": "bake kit",
95
+ "./bake/staticMaterials": "bake kit",
96
+ "./interactions": "rows",
97
+ "./questGraph": "rows",
98
+ "./kit/geometryPack": "bake kit",
99
+ "./looks/tileField": "rows",
100
+ "./kit/bakedGeometry": "bake kit",
101
+ "./species/clips": "rows",
102
+ "./compileScript": "scripts",
103
+ "./compileScriptV2": "scripts",
104
+ "./test/compileDualScriptV2": "internal",
105
+ "./buildBehaviour": "scripts",
106
+ "./scene": "rows",
107
+ "./physics": "rows",
108
+ "./entries": "rows",
109
+ "./spawns": "rows",
110
+ "./synth": "contract",
111
+ "./formatJsonSchema": "contract",
112
+ "./bake/rig": "bake kit",
113
+ "./bake/skinned": "bake kit",
114
+ "./bake/riggedHullRecipes": "bake kit",
115
+ "./bake/signPlacements": "bake kit",
116
+ "./bake/image": "bake kit",
117
+ "./sceneGraph": "rows",
118
+ "./materials": "rows",
119
+ "./sceneAudio": "rows",
120
+ "./directorAbi": "scripts",
121
+ "./sceneAnimation": "rows",
122
+ "./assetHandle": "contract",
123
+ "./sourceReader": "internal",
124
+ "./runtimeMirrors": "internal",
125
+ "./bake/normalizeRig": "bake kit",
126
+ "./compileMovers": "scripts",
127
+ "./modes": "rows",
128
+ "./bake/navigation": "bake kit",
129
+ "./bake": "bake kit",
130
+ "./bake/navigationAsset": "bake kit",
131
+ "./productOutput": "contract",
132
+ "./projectMap": "contract",
133
+ "./random": "bake kit",
134
+ "./measure": "contract",
135
+ "./sections": "contract",
136
+ "./platformSections": "contract",
137
+ "./blobs": "contract",
138
+ "./blobBytes": "contract",
139
+ "./schemaValidation": "contract",
140
+ "./outputProduct": "contract",
141
+ "./as/ws": "scripts",
142
+ "./as/wsV2": "scripts",
143
+ "./decisionScriptBindings": "scripts",
144
+ "./decisionSource": "scripts",
145
+ "./buildDecisionScripts": "scripts",
146
+ "./projectDecisions": "contract",
147
+ "./bake/practiceCourse": "bake kit",
148
+ "./returnProjectionV2": "scripts",
149
+ "./as/groupBankV2": "scripts",
150
+ "./as/groupStepV2": "scripts",
151
+ "./bake/portableBytes": "bake kit",
152
+ "./bake/mapRest": "bake kit",
153
+ "./worldScenes": "rows",
154
+ "./finds": "rows",
155
+ "./nativePopulationRows": "rows",
156
+ "./weapons/firearmRows": "rows",
157
+ "./bossProfiles": "rows",
158
+ "./arenaView": "rows",
159
+ "./eliteEntryRows": "rows",
160
+ "./decisionScripts": "scripts",
161
+ "./bake/facetedGeometry": "bake kit",
162
+ "./bake/nativeTerrainField": "bake kit",
163
+ "./bake/nativeInteractionFacts": "bake kit",
164
+ "./bake/geometryError": "bake kit",
165
+ "./bake/slabs": "bake kit",
166
+ "./bake/wholePieceJoin": "bake kit",
167
+ "./configBoundary": "internal",
168
+ "./executeBundle": "internal",
169
+ "./commons/catalogue": "bake kit",
170
+ "./commons/practiceCourse": "bake kit",
171
+ "./commons/courseProgram": "bake kit",
172
+ "./commons/scripts/course.as": "scripts",
173
+ "./commons/bake/portableMath": "bake kit",
174
+ "./scripts/*": "internal"
175
+ }
176
+ }
@@ -6,9 +6,9 @@
6
6
  // SHARD-AUTHORING SA38 (J319): generators are arbitrary Node code, so in `generators/` the rule is a denylist of
7
7
  // Wildshard cheats (the engine, sdk paths outside its exports, another shard's source, a second three); any npm
8
8
  // package, valibot and node:* pass. data/, quests/ and shard.config.ts keep the authoring allowlist, minus the engine.
9
- import { readFileSync } from 'node:fs';
9
+ import { existsSync, readFileSync } from 'node:fs';
10
10
  import { isBuiltin } from 'node:module';
11
- import { dirname, isAbsolute, resolve } from 'node:path';
11
+ import { basename, dirname, isAbsolute, resolve } from 'node:path';
12
12
  import { fileURLToPath, pathToFileURL } from 'node:url';
13
13
 
14
14
  const RULE = 'generator-imports';
@@ -77,10 +77,22 @@ const nodePath = (filename, source) => {
77
77
  } catch { return null; }
78
78
  };
79
79
 
80
+ /**
81
+ * The shard source a file sits in, as [whole, slug-or-src, path within the shard], or null outside one. The nearest
82
+ * src/shards/<slug>/ above the file names the shard, so a checkout under some other src/shards/ still matches. SA44: a
83
+ * single-shard repo keeps its source at src/ (J317), marked by `src/shard.config.ts`; whichever is nearer wins.
84
+ */
85
+ const shardFile = (path) => {
86
+ for (let at = dirname(path); dirname(at) !== at; at = dirname(at)) {
87
+ const nested = basename(dirname(at)) === 'shards' && basename(dirname(dirname(at))) === 'src';
88
+ if (nested || (basename(at) === 'src' && existsSync(resolve(at, 'shard.config.ts')))) return [path, nested ? basename(at) : 'src', path.slice(at.length + 1)];
89
+ }
90
+ return null;
91
+ };
92
+
80
93
  /** Why `source` may not be imported from `filename` under a shard's author folders, or null when it may. */
81
94
  export function generatorImportViolation(filename, rawSource, required = false) {
82
- // The last src/shards/ in the path names the shard, so a checkout under some other src/shards/ still matches.
83
- const path = resolve(filename).replaceAll('\\', '/'), match = /^.*\/src\/shards\/([^/]+)\/(.+)$/u.exec(path);
95
+ const path = resolve(filename).replaceAll('\\', '/'), match = shardFile(path);
84
96
  if (match === null || !(/^(?:generators|data|quests)\//u.test(match[2]) || match[2] === 'shard.config.ts')) return null;
85
97
  if (typeof rawSource !== 'string') return null;
86
98
  // Vite resolves the path before the first `?` or `#` through the package exports and keeps the rest (`?raw`, `?url`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wildshard/sdk",
3
- "version": "0.2.6",
3
+ "version": "0.2.8",
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": {
@@ -12,6 +12,7 @@
12
12
  },
13
13
  "files": [
14
14
  "GUIDE.md",
15
+ "docs/api/EXPORT-TIERS.md",
15
16
  "skills",
16
17
  "codemods",
17
18
  "bin",
@@ -82,7 +83,7 @@
82
83
  "@types/three": "0.186.0",
83
84
  "@typescript/typescript6": "6.0.2",
84
85
  "@valibot/to-json-schema": "1.8.0",
85
- "@wildshard/engine": "github:project-wildshard/engine#867f3b968429d8b90ae33b363dae3f15f16f6b84",
86
+ "@wildshard/engine": "github:project-wildshard/engine#d10f30e3ddec11dc14c11692a86d7eb1dd86a3c3",
86
87
  "@wildshard/format": "github:project-wildshard/shard-format#v0.4.9",
87
88
  "ajv": "6.15.0",
88
89
  "assemblyscript": "0.28.20",