@wildshard/sdk 0.2.6 → 0.2.7

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,9 +37,9 @@ 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 |
42
+ | 4 | Hero | `wildshard hero . --base <url>` | Works, with `wildshard dev .` running: `<url>` is the one it prints. See "The hero" below |
41
43
  | 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
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 |
@@ -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) |
@@ -68,24 +70,22 @@ with `rule`, `fix` and `guide`) for agents and scripts.
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.
@@ -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
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wildshard/sdk",
3
- "version": "0.2.6",
3
+ "version": "0.2.7",
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",
@@ -14,7 +14,7 @@ import { randomBytes } from 'node:crypto';
14
14
  import { InputHashMemo } from '@wildshard/engine/scripts/bake-input-hashes.mjs';
15
15
  import { productInputKey, productToolchainKey, matchingProductInputKey, publishProductInputs } from '@wildshard/engine/scripts/shardfile-inputs.mjs';
16
16
  import { quietCli } from '@wildshard/engine/scripts/quiet-cli.mjs';
17
- import { outputManifest, shardOutputs } from '@wildshard/engine/scripts/shard-outputs.mjs';
17
+ import { outputManifest, shardOutputs, shardSourceDir, shardSourceFolders } from '@wildshard/engine/scripts/shard-outputs.mjs';
18
18
  import { usesProgramDiscovery } from '@wildshard/engine/scripts/program-discovery.mjs';
19
19
  import { shardfileValidationRevision } from '@wildshard/engine/scripts/shardfile-validation-revision.mjs';
20
20
  import { runShardBuild, runShardBuildPool } from './shard-build-pool.mjs';
@@ -45,7 +45,6 @@ async function buildShardfilesWork(root, { strict = [process.env.CI, process.env
45
45
  const outputRoot = resolve(root, 'out');
46
46
  // Discard the retired discovery artifact left by older builds.
47
47
  rmSync(resolve(outputRoot, 'catalog.json'), { force: true });
48
- const projects = resolve(root, 'src/shards');
49
48
  let count = 0;
50
49
  const stale = [], runtimeReport = [];
51
50
  // A folder may emit many products. Its shared source closure and prerequisite
@@ -60,7 +59,9 @@ async function buildShardfilesWork(root, { strict = [process.env.CI, process.env
60
59
  if (issues === undefined) { issues = runtimeCopyIssues(root, project); runtimeChecks.set(project, issues); }
61
60
  return issues;
62
61
  };
63
- const folders = readdirSync(projects, { withFileTypes: true }).filter(entry => entry.isDirectory() && existsSync(resolve(projects, entry.name, 'shard.config.ts'))).map(entry => entry.name).sort((a, b) => a.localeCompare(b));
62
+ // SA42 (SA16's rule): a single-shard repo's source is `src/` (its folder named by its slug), a multi-shard repo's is
63
+ // `src/shards/<folder>/`. The engine's shard-outputs owns the layout, so every product helper below agrees with it.
64
+ const folders = shardSourceFolders(root, ['shard.config.ts']).sort((a, b) => a.localeCompare(b));
64
65
  // SF88g: a folder with declared outputs (scripts/shard-outputs.mjs) builds one product per output, each to out/<slug>
65
66
  const products = folders.flatMap(folder => (shardOutputs(root, folder) ?? [{ slug: folder }]).map(row => ({ name: row.slug, folder, output: row.slug === folder ? undefined : row.slug })));
66
67
  const built = products.map(row => row.name).sort((a, b) => a.localeCompare(b));
@@ -72,7 +73,7 @@ async function buildShardfilesWork(root, { strict = [process.env.CI, process.env
72
73
  }
73
74
  for (const slug of scope ?? only ?? []) if (!built.includes(slug)) throw new Error(`wildshard build: --shard=${slug} is not an output this repo builds (${built.join(', ')})`);
74
75
  const bound = (only === undefined || strict ? [] : products).filter(({ folder, output }) => {
75
- const manifest = resolve(projects, folder, 'manifest.json');
76
+ const manifest = resolve(shardSourceDir(root, folder), 'manifest.json');
76
77
  if (!existsSync(manifest)) return false;
77
78
  const row = output === undefined ? undefined : shardOutputs(root, folder)?.find(entry => entry.slug === output);
78
79
  return usesProgramDiscovery(row === undefined ? JSON.parse(readFileSync(manifest, 'utf8')) : outputManifest(root, folder, row));
@@ -98,7 +99,7 @@ async function buildShardfilesWork(root, { strict = [process.env.CI, process.env
98
99
  await runShardBuildPool(ordered, async ({ name, folder, output }, signal) => {
99
100
  if (scope !== undefined && !scope.includes(name)) return;
100
101
  const buildOne = args => build === runWildshard ? runShardBuild(args, signal, report=>{counters.merge(report);}) : build(args);
101
- const project = resolve(projects, folder);
102
+ const project = shardSourceDir(root, folder);
102
103
  try {
103
104
  const started = performance.now();
104
105
  const map = productMapInput(project, output), expected = map?.tilesHash ?? null;