@wildshard/sdk 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/GUIDE.md +19 -6
  2. package/bin/wildshard.mjs +4 -0
  3. package/docs/api/EXPORT-TIERS.md +3 -2
  4. package/lint/export-tiers.json +1 -0
  5. package/lint/sdk-plugin.d.mts +2 -0
  6. package/lint/sdk-plugin.mjs +39 -1
  7. package/package.json +10 -9
  8. package/scripts/capture-hero.mjs +48 -18
  9. package/scripts/ci21-sdk-tail-lint.mjs +95 -0
  10. package/scripts/keep-copy.mjs +172 -0
  11. package/scripts/land.mjs +34 -4
  12. package/scripts/lane-live.mjs +136 -0
  13. package/scripts/leftovers-report.mjs +47 -0
  14. package/scripts/lint-dispatch.mjs +5 -0
  15. package/scripts/music/export-midi.mjs +3 -2
  16. package/scripts/prepare-product.mjs +3 -2
  17. package/scripts/scratch-dir.d.mts +3 -0
  18. package/scripts/scratch-dir.mjs +33 -14
  19. package/scripts/scratch-sweep.mjs +15 -23
  20. package/scripts/typecheck.mjs +15 -0
  21. package/scripts/worktree-reap.mjs +46 -104
  22. package/scripts/worktree.mjs +35 -13
  23. package/skills/wildshard/SKILL.md +3 -1
  24. package/src/cli/content-command.ts +44 -0
  25. package/src/cli/content.ts +287 -0
  26. package/src/cli/help.ts +7 -2
  27. package/src/cli/hero/hero.ts +6 -1
  28. package/src/cli/hero/scene-card.ts +46 -0
  29. package/src/cli/hero/stamp.ts +5 -3
  30. package/src/sharddev/authorManifest.ts +20 -2
  31. package/src/sharddev/cli.ts +1 -1
  32. package/src/sharddev/dev.ts +23 -4
  33. package/src/sharddev/newProject.ts +27 -8
  34. package/src/sharddev/project.ts +2 -2
  35. package/src/sharddev/refusals.ts +1 -0
  36. package/src/sharddev/scene/author.ts +22 -1
  37. package/src/sharddev/scene/budget.ts +87 -0
  38. package/src/sharddev/scene/creature.ts +171 -0
  39. package/src/sharddev/scene/description.ts +41 -0
  40. package/src/sharddev/scene/lower.ts +127 -3
  41. package/src/sharddev/scene/shardfile.ts +196 -14
  42. package/src/sharddev/shardSource.ts +2 -2
  43. package/src/sharddev/test/diskScriptScenario.ts +4 -2
  44. package/src/sharddev/test/ownedScratch.ts +14 -0
  45. package/src/sharddev/test/scriptScenario.ts +18 -13
  46. package/src/sharddev/tsconfig.json +3 -0
  47. package/src/sharddev/watch/pageEntry.ts +1 -19
  48. package/src/sharddev/watch/parity-baseline.json +6 -6
  49. package/src/sharddev/watch/parity.mjs +24 -0
  50. package/src/sharddev/watch/watch.ts +10 -2
  51. package/src/shards/_template/behaviour/boss.as +13 -4
  52. package/src/shards/_template/behaviour/door.as +8 -3
  53. package/src/shards/_template/behaviour/hooks.json +35 -0
  54. package/src/shards/_template/card/landscape.jpg +0 -0
  55. package/src/shards/_template/card/portrait.jpg +0 -0
  56. package/src/shards/_template/card/thumb.jpg +0 -0
  57. package/src/shards/_template/data/bossDecision.json +11 -1
  58. package/src/shards/_template/data/card.json +49 -1
  59. package/src/shards/_template/data/clientScripts.json +411 -0
  60. package/src/shards/_template/data/creatures.json +280 -2
  61. package/src/shards/_template/data/items.json +1 -1
  62. package/src/shards/_template/data/layout.json +32 -1
  63. package/src/shards/_template/data/ledger.json +45 -0
  64. package/src/shards/_template/data/npcs/hermit.json +72 -0
  65. package/src/shards/_template/data/quests.json +297 -11
  66. package/src/shards/_template/data/rows.json +154 -0
  67. package/src/shards/_template/data/skins.json +14 -0
  68. package/src/shards/_template/data/targets.json +47 -0
  69. package/src/shards/_template/data/text.json +4 -1
  70. package/src/shards/_template/generators/lift.ts +71 -0
  71. package/src/shards/_template/generators/product.ts +19 -5
  72. package/src/shards/_template/generators/templatePropsSource.ts +5 -4
  73. package/src/shards/_template/generators/terrain.ts +10 -2
  74. package/src/shards/_template/generators/world.ts +42 -7
  75. package/src/shards/_template/hero.json +6 -6
  76. package/src/shards/_template/manifest.json +49 -1
  77. package/src/shards/authoring-slice/generators/shard.ts +2 -1
  78. package/src/shards/authoring-slice/generators/world.ts +8 -1
  79. package/tsconfig.author.json +24 -0
@@ -0,0 +1,287 @@
1
+ /* eslint-disable max-lines-per-function, max-statements, no-magic-numbers, node/no-sync, unicorn/explicit-length-check, unicorn/import-style, unicorn/max-nested-calls, unicorn/no-array-callback-reference, unicorn/no-nested-ternary, typescript/array-type, typescript/explicit-function-return-type, typescript/no-unsafe-type-assertion, typescript/prefer-readonly-parameter-types */
2
+ import { readFileSync } from 'node:fs'
3
+ import { resolve } from 'node:path'
4
+
5
+ type Json = Record<string, unknown>
6
+
7
+ interface ContentCounts {
8
+ readonly weapons: number
9
+ readonly loadoutWeapons: number
10
+ readonly pickups: number
11
+ readonly hostileSpecies: number
12
+ readonly bodies: number
13
+ readonly groups: number
14
+ readonly brainKinds: number
15
+ readonly creatureStrikes: number
16
+ readonly bossHp: number
17
+ readonly bossStrikes: number
18
+ readonly npcs: number
19
+ readonly dialogueStates: number
20
+ readonly quests: number
21
+ readonly questSteps: number
22
+ readonly interactables: number
23
+ readonly movers: number
24
+ readonly achievements: number
25
+ readonly pois: number
26
+ }
27
+
28
+ interface ContentReport {
29
+ readonly slug: string
30
+ readonly counts: ContentCounts
31
+ readonly short: readonly string[]
32
+ }
33
+
34
+ const TEMPLATE_BAR: ReadonlyArray<
35
+ readonly [keyof ContentCounts, number, string]
36
+ > = [
37
+ ['loadoutWeapons', 1, 'weapons in loadout'],
38
+ ['pickups', 2, 'placed pickups'],
39
+ ['hostileSpecies', 4, 'hostile species'],
40
+ ['bodies', 12, 'bodies'],
41
+ ['groups', 1, 'creature groups'],
42
+ ['brainKinds', 3, 'brain kinds'],
43
+ ['creatureStrikes', 4, 'creature strikes'],
44
+ ['bossHp', 400, 'boss hp'],
45
+ ['bossStrikes', 3, 'boss strikes'],
46
+ ['npcs', 1, 'NPCs'],
47
+ ['dialogueStates', 2, 'dialogue states'],
48
+ ['quests', 1, 'quests'],
49
+ ['questSteps', 4, 'quest steps'],
50
+ ['interactables', 3, 'interactables'],
51
+ ['movers', 1, 'movers'],
52
+ ['achievements', 2, 'achievements'],
53
+ ['pois', 8, 'POIs'],
54
+ ]
55
+
56
+ function record(value: unknown): Json {
57
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
58
+ ? (value as Json)
59
+ : {}
60
+ }
61
+ function array(value: unknown): readonly unknown[] {
62
+ return Array.isArray(value) ? value : []
63
+ }
64
+ function number(value: unknown): number {
65
+ return typeof value === 'number' && Number.isFinite(value) ? value : 0
66
+ }
67
+ function text(value: unknown): string {
68
+ return typeof value === 'string' ? value : ''
69
+ }
70
+ function get(value: unknown, key: string): unknown {
71
+ return record(value)[key]
72
+ }
73
+
74
+ function section(dir: string, name: string): Json {
75
+ try {
76
+ return record(
77
+ JSON.parse(
78
+ readFileSync(resolve(dir, 'sections', `${name}.json`), 'utf8'),
79
+ ),
80
+ )
81
+ } catch (error: unknown) {
82
+ if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
83
+ return {}
84
+ }
85
+ throw error
86
+ }
87
+ }
88
+
89
+ function itemRows(items: Json): readonly Json[] {
90
+ return array(get(get(items, 'items'), 'rows')).map(record)
91
+ }
92
+ function speciesRows(species: Json): readonly Json[] {
93
+ return array(get(get(species, 'rows'), 'species')).map(record)
94
+ }
95
+ function creaturesOf(creatures: Json): Json {
96
+ return record(get(creatures, 'creatures'))
97
+ }
98
+ function maxHp(species: readonly Json[]): number {
99
+ return Math.max(
100
+ 0,
101
+ ...species.flatMap(row =>
102
+ array(get(row, 'variants'))
103
+ .map(record)
104
+ .map(variant => number(get(variant, 'hp'))),
105
+ ),
106
+ )
107
+ }
108
+
109
+ /** Count both row-authored and native platform-section shapes without reading source. */
110
+ function readContent(dir: string, bar?: string): ContentReport {
111
+ const index = record(
112
+ JSON.parse(readFileSync(resolve(dir, 'shard.json'), 'utf8')),
113
+ )
114
+ const items = section(dir, 'combat/items')
115
+ const creatures = creaturesOf(section(dir, 'actors/creatures'))
116
+ const species = speciesRows(section(dir, 'actors/species'))
117
+ const strikes = array(
118
+ get(get(record(section(dir, 'combat/strikes')), 'rows'), 'strikes'),
119
+ ).map(record)
120
+ const nativeStrikes = array(section(dir, 'actors/strikes')).map(record)
121
+ const questSection = record(section(dir, 'quests/quests'))
122
+ const questData = record(get(questSection, 'quests'))
123
+ const quests = (
124
+ Array.isArray(get(questData, 'quests'))
125
+ ? array(get(questData, 'quests'))
126
+ : array(get(questSection, 'quests'))
127
+ ).map(record)
128
+ const host = section(dir, 'quests/host')
129
+ const npcs = array(get(record(section(dir, 'actors/npcs')), 'questNpcs')).map(
130
+ record,
131
+ )
132
+ const ledger = array(
133
+ get(record(section(dir, 'economy/ledger')), 'ledger'),
134
+ ).map(record)
135
+ const movers = array(get(record(section(dir, 'world/movers')), 'movers'))
136
+ const targets = record(section(dir, 'world/targets'))
137
+ const ui = section(dir, 'ui/ui')
138
+ const sourceItems = itemRows(items)
139
+ const weapons = sourceItems.filter(row => text(get(row, 'kind')) === 'weapon')
140
+ const itemData = record(get(items, 'items'))
141
+ const loadout = record(get(itemData, 'loadout'))
142
+ const loadoutIds = [
143
+ text(get(loadout, 'primary')),
144
+ text(get(loadout, 'secondary')),
145
+ ...array(get(loadout, 'weapons')).map(text),
146
+ ].filter(Boolean)
147
+ const spawns = array(get(creatures, 'spawns')).map(record)
148
+ const brains = array(get(creatures, 'brains')).map(record)
149
+ const groups = array(get(creatures, 'groups'))
150
+ const targetRows = record(get(targets, 'rows'))
151
+ const uiTargets = record(get(ui, 'targets'))
152
+ const interactionRows = [
153
+ ...array(get(targetRows, 'itemActions')),
154
+ ...array(get(targetRows, 'interactables')),
155
+ ...array(get(ui, 'interaction')),
156
+ ...array(get(ui, 'braziers')),
157
+ ...array(get(ui, 'talk')),
158
+ ...array(get(uiTargets, 'interactions')),
159
+ ...array(get(uiTargets, 'itemActions')),
160
+ ]
161
+ const nativePrograms = record(section(dir, 'actors/species-programs'))
162
+ const nativeSpecies = array(get(nativePrograms, 'species')).map(record)
163
+ const allSpecies = [...species, ...nativeSpecies]
164
+ const nativeBodies = array(section(dir, 'sim/bodies'))
165
+ // A talk is an NPC too: a row-authored shard's NPCs are its `targets.talks` (Mossgate's Lamplighter and Pond Hermit)
166
+ const talks = array(get(uiTargets, 'talks')).map(record)
167
+ const questNpcs = [...npcs, ...array(get(host, 'npcs')).map(record), ...talks]
168
+ // A placed pickup is a prompt whose scene hands over or refills an item (a rack's sword, a chest's oil)
169
+ const itemActionScenes = new Set(
170
+ [
171
+ ...array(get(targetRows, 'itemActions')),
172
+ ...array(get(uiTargets, 'itemActions')),
173
+ ]
174
+ .map(record)
175
+ .map(row => text(get(row, 'scene')))
176
+ .filter(Boolean),
177
+ )
178
+ const itemPrompts = array(get(uiTargets, 'interactions'))
179
+ .map(record)
180
+ .filter(row => itemActionScenes.has(text(get(row, 'scene'))))
181
+ // A brain's own strike (a ram, a dive) is its species' strike as much as a spawn's
182
+ // a brain names its strike (`strike`), or a challenge pair (`charge`, `close`)
183
+ const brainStrikes = new Map(
184
+ brains.map(row => [
185
+ text(get(row, 'id')),
186
+ text(get(row, 'strike')) ||
187
+ text(get(row, 'charge')) ||
188
+ text(get(row, 'close')),
189
+ ]),
190
+ )
191
+ const dialogue = [
192
+ ...array(get(host, 'dialogue')).map(record),
193
+ ...array(get(questData, 'dialogue')).map(record),
194
+ ...array(get(questSection, 'dialogue')).map(record),
195
+ ]
196
+ const manifest = get(record(section(dir, 'ui/level')), 'manifest')
197
+ const manifestPois = array(get(manifest, 'pois'))
198
+ const targetPois = [
199
+ ...array(get(targets, 'pois')),
200
+ ...array(get(targetRows, 'pois')),
201
+ ]
202
+ const count: ContentCounts = {
203
+ weapons: weapons.length,
204
+ loadoutWeapons: loadoutIds.filter(id =>
205
+ weapons.some(row => text(get(row, 'id')) === id),
206
+ ).length,
207
+ pickups:
208
+ array(get(itemData, 'pickups')).length +
209
+ array(get(targetRows, 'itemScenes')).length +
210
+ array(get(targetRows, 'loot')).length +
211
+ itemPrompts.length,
212
+ hostileSpecies: allSpecies.filter(
213
+ row => get(row, 'aggressive') === true || get(row, 'hostile') === true,
214
+ ).length,
215
+ bodies: Math.max(spawns.length, nativeBodies.length),
216
+ groups: groups.length,
217
+ brainKinds: new Set(
218
+ brains.map(row => text(get(row, 'kind'))).filter(Boolean),
219
+ ).size,
220
+ creatureStrikes:
221
+ new Set(
222
+ spawns
223
+ .filter(
224
+ row =>
225
+ text(get(row, 'strike')) !== '' ||
226
+ (brainStrikes.get(text(get(row, 'brain'))) ?? '') !== '',
227
+ )
228
+ .map(row => text(get(row, 'species'))),
229
+ ).size ||
230
+ new Set(
231
+ [...strikes, ...nativeStrikes]
232
+ .map(row => text(get(row, 'id')))
233
+ .filter(Boolean),
234
+ ).size,
235
+ bossHp: maxHp(allSpecies),
236
+ bossStrikes: [...strikes, ...nativeStrikes].filter(row =>
237
+ /boss|warden|wyrm/u.test(text(get(row, 'id'))),
238
+ ).length,
239
+ npcs: questNpcs.length,
240
+ dialogueStates: dialogue.reduce(
241
+ (total, row) => total + array(get(row, 'nodes')).length,
242
+ 0,
243
+ ),
244
+ quests: quests.length,
245
+ questSteps: quests.reduce(
246
+ (total, row) => total + array(get(row, 'steps')).length,
247
+ 0,
248
+ ),
249
+ interactables: interactionRows.length,
250
+ movers: movers.length,
251
+ achievements: ledger.reduce(
252
+ (total, row) =>
253
+ total +
254
+ array(get(row, 'rewards')).filter(
255
+ reward => text(get(reward, 'kind')) === 'achievement',
256
+ ).length,
257
+ 0,
258
+ ),
259
+ pois: manifestPois.length + targetPois.length,
260
+ }
261
+ const short =
262
+ bar === 'templates'
263
+ ? TEMPLATE_BAR.filter(([key, minimum]) => count[key] < minimum).map(
264
+ ([key, minimum, label]) => `${label}: ${count[key]}/${minimum}`,
265
+ )
266
+ : []
267
+ return {
268
+ slug: text(get(record(get(index, 'identity')), 'slug')) || dir,
269
+ counts: count,
270
+ short,
271
+ }
272
+ }
273
+
274
+ function formatContent(report: ContentReport, bar?: string): string {
275
+ const values = Object.entries(report.counts)
276
+ .map(([name, value]) => ` ${name}: ${value}`)
277
+ .join('\n')
278
+ const verdict =
279
+ bar === undefined
280
+ ? ''
281
+ : report.short.length === 0
282
+ ? `\nbar ${bar}: pass`
283
+ : `\nbar ${bar}: fail\n${report.short.map(line => ` short ${line}`).join('\n')}`
284
+ return `content ${report.slug}\n${values}${verdict}\n`
285
+ }
286
+
287
+ export { formatContent, readContent }
package/src/cli/help.ts CHANGED
@@ -16,11 +16,12 @@ const PACK_ALIAS = `pack <folder> [--out <file>]
16
16
 
17
17
  /** Each verb's entry: its usage lines, then what it does, indented. */
18
18
  const VERBS: Readonly<Record<string, string>> = {
19
- new: `new <dir> [slug] [--template sdk] [--empty]
19
+ new: `new <dir> [slug] [--template sdk|scene] [--empty]
20
20
  Start a shard repo in <dir>, a folder that does not
21
21
  exist yet, with its shard source at src/ (slug: the
22
22
  folder's name unless given). It copies the reference
23
- world (--template sdk, the only template; blender is
23
+ world (--template sdk), or Mossgate Hollow as one
24
+ three.js scene module (--template scene; blender is
24
25
  retired: Blender makes models, code makes the
25
26
  shard). --empty writes a
26
27
  bare shard source instead`,
@@ -172,6 +173,10 @@ const VERBS: Readonly<Record<string, string>> = {
172
173
  shard file folders (one per output) under out/.
173
174
  --shard builds only those outputs; --reuse keeps a
174
175
  folder whose inputs are unchanged`,
176
+ content: `content <built-shard-dir> [--bar templates]
177
+ Count player-facing content in a built shard's sections.
178
+ --bar templates checks the template content minimums
179
+ and names every short line`,
175
180
  pack: PACK_ALIAS,
176
181
  }
177
182
 
@@ -1,6 +1,7 @@
1
1
  import { readdir } from 'node:fs/promises'
2
2
  import path from 'node:path'
3
3
 
4
+ import { isSceneShard } from './scene-card.ts'
4
5
  import {
5
6
  MANIFEST,
6
7
  NONE,
@@ -139,7 +140,11 @@ async function assertHeroCurrent(
139
140
  ): Promise<void> {
140
141
  // SA3: `build` names the project it built; a bare folder is read by layout.
141
142
  const shard = source ?? sourceShard(product)
142
- if ((await readJson(path.join(shard, MANIFEST))) === undefined) {
143
+ // F28: a scene shard keeps no manifest; its folder (a shard.config.ts) is still the source a hero shows
144
+ if (
145
+ (await readJson(path.join(shard, MANIFEST))) === undefined &&
146
+ !(await isSceneShard(shard))
147
+ ) {
143
148
  report(`hero: no source shard with a ${MANIFEST} at ${shard}; not checked`)
144
149
  return
145
150
  }
@@ -0,0 +1,46 @@
1
+ import { stat } from 'node:fs/promises'
2
+ import path from 'node:path'
3
+
4
+ // Meta NEW-SHARD-E2E F28: a scene shard keeps no manifest.json (its discovery
5
+ // is generated), so its captured hero is `card/<slot>.jpg` in the shard
6
+ // folder, which the generated discovery card wears from the next build on
7
+ // (`authorManifest`).
8
+
9
+ const SCENE_CARD = 'card'
10
+ const SCENE_SLOTS = ['thumb', 'portrait', 'landscape'] as const
11
+
12
+ /** Whether a file is there; an unreadable path counts as absent. */
13
+ async function present(file: string): Promise<boolean> {
14
+ return await stat(file).then(
15
+ (): boolean => true,
16
+ (): boolean => false,
17
+ )
18
+ }
19
+
20
+ /** A scene shard's source folder: its `shard.config.ts`. */
21
+ async function isSceneShard(shard: string): Promise<boolean> {
22
+ return await present(path.join(shard, 'shard.config.ts'))
23
+ }
24
+
25
+ /** A scene shard's captured card files, by slot: only the ones on disk. */
26
+ async function sceneCardUrls(
27
+ shard: string,
28
+ ): Promise<Readonly<Record<string, string>>> {
29
+ const found = await Promise.all(
30
+ SCENE_SLOTS.map(
31
+ async (slot: string): Promise<readonly [string, string] | undefined> => {
32
+ const url = `${SCENE_CARD}/${slot}.jpg`
33
+ return (await present(path.join(shard, url))) ? [slot, url] : undefined
34
+ },
35
+ ),
36
+ )
37
+ return Object.fromEntries(
38
+ found.filter(
39
+ (
40
+ row: readonly [string, string] | undefined,
41
+ ): row is readonly [string, string] => row !== undefined,
42
+ ),
43
+ )
44
+ }
45
+
46
+ export { isSceneShard, sceneCardUrls }
@@ -3,6 +3,7 @@ import { readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
3
3
  import path from 'node:path'
4
4
 
5
5
  import { shardFolderName } from '../../sharddev/shardSource.ts'
6
+ import { sceneCardUrls } from './scene-card.ts'
6
7
 
7
8
  // A shard's hero (its SHARD SELECT card: thumb, portrait and landscape) is a
8
9
  // picture of its world, so it goes stale when the world changes (Jake,
@@ -95,11 +96,12 @@ function field(value: unknown, key: string): unknown {
95
96
  )?.[VALUE]
96
97
  }
97
98
 
98
- /** The manifest's card urls, by slot. */
99
+ /** The manifest's card urls, by slot; a scene shard's captured card files (F28). */
99
100
  async function cardUrls(
100
101
  shard: string,
101
102
  ): Promise<Readonly<Record<string, string>>> {
102
- const card = field(await readJson(path.join(shard, MANIFEST)), 'card')
103
+ const manifest = await readJson(path.join(shard, MANIFEST))
104
+ const card = field(manifest, 'card')
103
105
  const urls: Record<string, string> = {}
104
106
  for (const slot of SLOTS) {
105
107
  const url = field(card, slot)
@@ -107,7 +109,7 @@ async function cardUrls(
107
109
  urls[slot] = url
108
110
  }
109
111
  }
110
- return urls
112
+ return manifest === undefined ? await sceneCardUrls(shard) : urls
111
113
  }
112
114
 
113
115
  /**
@@ -1,5 +1,21 @@
1
+ // oxlint-disable-next-line import/no-nodejs-modules -- the author tool reads the shard folder's captured card files.
2
+ import { existsSync } from 'node:fs';
3
+ // oxlint-disable-next-line import/no-nodejs-modules -- the author tool reads the shard folder's captured card files.
4
+ import { join } from 'node:path';
1
5
  import type { Shardfile } from '@wildshard/format/shardSchema';
2
6
 
7
+ /** The card slots a hero fills. */
8
+ type CardSlot = 'thumb' | 'portrait' | 'landscape';
9
+ /**
10
+ * meta NEW-SHARD-E2E F28: a scene shard's captured hero (`wildshard hero` writes `card/<slot>.jpg` in its folder), as
11
+ * the urls the discovery packs (`/src/shards/<folder>/card/<slot>.jpg`); only the slots captured.
12
+ */
13
+ export function sceneCardUrls(source: string, folder: string): Partial<Record<CardSlot, string>> {
14
+ const urls: Partial<Record<CardSlot, string>> = {};
15
+ for (const slot of ['thumb', 'portrait', 'landscape'] as const) if (existsSync(join(source, 'card', `${slot}.jpg`))) urls[slot] = `/src/shards/${folder}/card/${slot}.jpg`;
16
+ return urls;
17
+ }
18
+
3
19
  /** C3: what a page needs before it admits a shard, for an author who wrote no level metadata: `withDiscovery` writes this
4
20
  * as the product's discovery, so the shard wears its own card and enters on its own page, with no first-party manifest
5
21
  * source. Every value is the platform's plain default or the shard's own; a shard's `manifest` replaces all of it. */
@@ -18,11 +34,13 @@ export function authorCard(name: string, seed: number): string {
18
34
  return `data:image/svg+xml,${encodeURIComponent(svg)}`;
19
35
  }
20
36
 
21
- export function authorManifest(shard: Shardfile): unknown {
37
+ export function authorManifest(shard: Shardfile, captured: Partial<Record<CardSlot, string>> = {}): unknown {
22
38
  const {slug, name, seed} = shard.identity, art = authorCard(name, seed), {spawn} = shard;
39
+ // F28: a captured hero replaces the generated art slot by slot
40
+ const card = {thumb: captured.thumb ?? art, portrait: captured.portrait ?? art, landscape: captured.landscape ?? art};
23
41
  return {
24
42
  api: 1, hoverSpeedClass: 'road', slug, order: 1000, status: 'live', name, label: '(+0, +0)', seed, biome: `By ${shard.identity.author}`, blurb: name,
25
- card: {thumb: art, portrait: art, landscape: art}, style: 'greybox', kitLook: 'toon', hands: 'toon', weapon: 'custom', treeCount: 0,
43
+ card, style: 'greybox', kitLook: 'toon', hands: 'toon', weapon: 'custom', treeCount: 0,
26
44
  trees: {factory: 'none', noun: 'trees'}, minimap: {image: art}, pois: [], assetGlobs: [], spawn,
27
45
  bounds: {x0: -250, x1: 250, z0: -250, z1: 250, floor: -10},
28
46
  sky: {sunColor: NEUTRAL, sunIntensity: 1.5, envIntensity: 0.5, bgIntensity: 1, fogSunColor: NEUTRAL, cloudSunColor: NEUTRAL, hemiSky: 10266548, hemiGround: 6316128, hemiIntensity: 0.7, sun: {azimuth: 35, elevation: 45}},
@@ -118,7 +118,7 @@ async function runCommand(given: readonly string[], options: CliOptions): Promis
118
118
  else if (value.startsWith('--')) unknown = true;
119
119
  else names.push(value);
120
120
  }
121
- if (input.startsWith('--') || names.length > 1 || unknown || empty > 1 || templates.length > 1) throw new Error('usage: wildshard new <dir> [slug] [--template sdk] [--empty]');
121
+ if (input.startsWith('--') || names.length > 1 || unknown || empty > 1 || templates.length > 1) throw new Error('usage: wildshard new <dir> [slug] [--template sdk|scene] [--empty]');
122
122
  // An unknown template refuses here, before anything is written.
123
123
  const template = templateNamed(templates[0] ?? 'sdk');
124
124
  const slug = names[0] ?? input.split('/').reverse().find((part) => part !== '') ?? '';
@@ -2,17 +2,36 @@
2
2
  import { createServer } from 'node:http';
3
3
  // oxlint-disable-next-line import/no-nodejs-modules -- Author changes rebuild a private disposable product.
4
4
  import { createReadStream, existsSync, mkdtempSync, realpathSync, readdirSync, rmSync, statSync, watch, readFileSync, writeFileSync, type Dirent } from 'node:fs';
5
- // oxlint-disable-next-line import/no-nodejs-modules -- Own temporary build directory.
6
- import { tmpdir } from 'node:os';
7
5
  // oxlint-disable-next-line import/no-nodejs-modules -- Resolve static requests inside the product directory.
8
6
  import { extname, join, resolve, sep } from 'node:path';
9
7
  import { buildProject } from './project';
8
+ import { shardRepoRoot } from './shardSource';
10
9
  import { Scope } from '@wildshard/engine/app/scope';
10
+ import { scratchDir } from '../../scripts/scratch-dir.mjs';
11
11
 
12
12
  const POLL = '<script>let wsRevision=WS_REVISION;setInterval(async()=>{try{const r=await fetch("/__wildshard_dev_revision",{cache:"no-store"});const s=await r.json();if(s.error){console.error(s.error);return}if(s.revision!==wsRevision)location.reload()}catch{}},500)</script>';
13
13
  const MIME: Record<string, string> = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.wasm': 'application/wasm', '.svg': 'image/svg+xml', '.png': 'image/png', '.woff2': 'font/woff2', '.ktx2': 'image/ktx2' };
14
14
  // .worktrees: a shard repo's plan worktrees (DEV-SPEED DS11) are other checkouts, never this project's source.
15
- const ignored = new Set(['node_modules', '.git', 'dist', 'public', '.worktrees']);
15
+ const ignored = new Set(['node_modules', '.git', 'dist', 'public', '.worktrees', 'tmp']);
16
+
17
+ /** DK23: each dev process owns output inside the project's lane folder. */
18
+ export function createDevScratch(source: string): string {
19
+ const session = process.env['CODEX_THREAD_ID'] ?? process.env['CLAUDE_SESSION_ID'] ?? process.env['CLAUDE_CODE_SESSION_ID'];
20
+ const named = process.env['WS_LANE_NAME'] ?? `dev-${(session ?? String(process.pid)).replaceAll(/[^\w-]/gu, '-').slice(0, 80)}`;
21
+ if (!/^[a-zA-Z0-9_-][a-zA-Z0-9._-]{0,99}$/u.test(named) || named.includes('..')) throw new Error('Invalid dev lane name');
22
+ const root = shardRepoRoot(source), env = { ...process.env, WS_LANE_NAME: named };
23
+ let parent: string;
24
+ try { parent = scratchDir(named, 'wildshard dev', { root, env }); }
25
+ catch (cause) {
26
+ if (!(cause instanceof Error) || !cause.message.includes('already belongs to session')) throw cause;
27
+ parent = scratchDir(`${named.slice(0, 80)}-${process.pid}`, 'wildshard dev', { root, env });
28
+ }
29
+ const record = { ...JSON.parse(readFileSync(join(parent, '.owner'), 'utf8')) as Record<string, unknown>, pid: process.pid };
30
+ const scratch = realpathSync(mkdtempSync(join(parent, ['dev', String(process.pid), ''].join('-'))));
31
+ writeFileSync(join(scratch, '.owner'), JSON.stringify(record), { flag: 'wx' });
32
+ writeFileSync(join(scratch, 'server.pid'), String(process.pid), { flag: 'wx' });
33
+ return scratch;
34
+ }
16
35
 
17
36
  /** Synchronous author-source baseline: native recursive watch notifications can miss quick overwrites during startup.
18
37
  * Nanosecond change time also detects same-length edits whose modification time was restored. Symlink directories
@@ -41,7 +60,7 @@ export function projectSourceStamp(source: string): string {
41
60
  export interface DevProject { url: string; close: (options?: { exiting?: boolean }) => Promise<void> }
42
61
  /** Only the author command chooses DEVSERVER; requests, cookies and URL switches cannot enable it. */
43
62
  export async function devProject(project: string, options: { decisionLegacyLines?: number; port?: number; client?: string } = {}): Promise<DevProject> {
44
- const source = resolve(project), scratch = realpathSync(mkdtempSync(join(tmpdir(), 'wildshard-dev-')));
63
+ const source = resolve(project), scratch = createDevScratch(source);
45
64
  let revision = 0, error: string | null = null, current = '', previous = '', stopped = false, shardRoot = '';
46
65
  const scope = new Scope('sdk.dev');
47
66
  let debounce: Scope | undefined, work = Promise.resolve();
@@ -31,9 +31,10 @@ function writeInstallScriptPolicy(project: string): void {
31
31
  writeFileSync(resolve(project, 'pnpm-workspace.yaml'), INSTALL_SCRIPT_POLICY);
32
32
  }
33
33
 
34
- /** SA16 (J314, J317): `new --template <name>`. `sdk` is Mossgate (sharddev's `_template`), the only template since
35
- * SS5 (J341): a shard is TypeScript three.js scene source, and Blender makes the models it loads. */
36
- export const TEMPLATES = ['sdk'] as const;
34
+ /** SA16 (J314, J317): `new --template <name>`. `sdk` is the Template (sharddev's `_template`, Mossgate's gameplay);
35
+ * `scene` (AP37a) is Mossgate Hollow's three.js scene module (`src/shards/mossgate`, AP15), the shape every template
36
+ * moves to (AP36). SS5 (J341): a shard is TypeScript three.js scene source, and Blender makes the models it loads. */
37
+ export const TEMPLATES = ['sdk', 'scene'] as const;
37
38
  export type TemplateName = (typeof TEMPLATES)[number];
38
39
  /** What `writeShardRepo` can still lay out. `blender` is the retired hand-written shape (shard-format's
39
40
  * `blender-template`, a shard file folder held by hand): `new` refuses it, but repos made that way still check and upload,
@@ -48,7 +49,7 @@ export const SHARD_SOURCE_FOLDER = 'src';
48
49
  export function templateNamed(name: string): TemplateName {
49
50
  if (name === 'blender') throw new Error('new: --template blender is retired (J341): a shard is TypeScript three.js scene source, and Blender makes the .glb models that code loads; leave out --template. Repos made with it still check and upload');
50
51
  const found = TEMPLATES.find(template => template === name);
51
- if (found === undefined) throw new Error(`new: unknown template ${name}: leave out --template, or pass --template sdk`);
52
+ if (found === undefined) throw new Error(`new: unknown template ${name}: leave out --template, or pass --template sdk or --template scene`);
52
53
  return found;
53
54
  }
54
55
 
@@ -89,9 +90,11 @@ export function repoPackageJson(slug: string, template: RepoShape = DEFAULT_TEMP
89
90
  dependencies[name] = spec;
90
91
  }
91
92
  const sorted = Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b)));
93
+ // AP22: a scene-module repo gets `pnpm watch` (each saved edit swapped into the running page); the Template has no scene to watch.
94
+ const scripts = template === 'scene' ? { check: 'wildshard check .', watch: 'wildshard watch .' } : { check: 'wildshard check .' };
92
95
  // `version` is what `wildshard upload` sends (provenance.ts reads the nearest package.json).
93
96
  return `${JSON.stringify({ name: slug, version: '0.0.1', private: true, type: 'module', packageManager: 'pnpm@10.34.9',
94
- engines: { node: sdk.node }, scripts: { check: 'wildshard check .' }, [template === 'blender' ? 'devDependencies' : 'dependencies']: sorted }, null, 2)}\n`;
97
+ engines: { node: sdk.node }, scripts, [template === 'blender' ? 'devDependencies' : 'dependencies']: sorted }, null, 2)}\n`;
95
98
  }
96
99
 
97
100
  const TSCONFIG = `${JSON.stringify({
@@ -125,8 +128,11 @@ const HANDWRITTEN_LAYOUT = `- \`src/\` is the shard source, written by hand: a s
125
128
 
126
129
  function repoReadme(slug: string, template: RepoShape, empty: boolean): string {
127
130
  const handwritten = template === 'blender' && !empty;
128
- const world = empty ? 'a bare shard source (`--empty`)' : template === 'sdk' ? 'the reference world, Mossgate (Template 1)' : 'the hand-written Blender template (`blender-template`)';
129
- const files = empty ? '`data/`, `generators/`,\n `behaviour/` and `assets/`' : '`data/`,\n `generators/`, `behaviour/`, `assets/` and `manifest.json` (the card)';
131
+ const world = empty ? 'a bare shard source (`--empty`)' : template === 'sdk' ? 'the reference world, Mossgate (Template 1)'
132
+ : template === 'scene' ? 'Mossgate Hollow, a three.js scene module (`--template scene`)' : 'the hand-written Blender template (`blender-template`)';
133
+ const files = empty ? '`data/`, `generators/`,\n `behaviour/` and `assets/`' : template === 'scene'
134
+ ? '`identity.json` (the slug and name)\n and `generators/` (`world.ts` is the scene; `wildshard watch .` shows each save)'
135
+ : '`data/`,\n `generators/`, `behaviour/`, `assets/` and `manifest.json` (the card)';
130
136
  const layout = handwritten ? HANDWRITTEN_LAYOUT : `- \`src/\` is the shard source: \`shard.config.ts\` (the build entry), ${files}.
131
137
  - \`package.json\` pins \`@wildshard/sdk\`, shard-format, engine and \`three\`
132
138
  exactly; its \`version\` is the version \`wildshard upload\` sends.`;
@@ -190,6 +196,18 @@ function writeReferenceSource(source: string, slug: string): void {
190
196
  writeFileSync(resolve(source, 'shard.config.ts'), `import { generate as reference } from './generators/generate';\nimport { BUILD_OPTIONS } from './generators/buildOptions';\nimport identity from './data/identity.json' with { type: 'json' };\nimport type { GeneratedProject, ProjectGenerationContext } from '@wildshard/sdk/projectGeneration';\n\n/** Author this world's data and generators; the identity belongs to this project. */\nexport async function generate(context: ProjectGenerationContext): Promise<GeneratedProject> {\n const product = await reference(context);\n return { ...product, shard: { ...product.shard, identity: { ...product.shard.identity, ...identity } } };\n}\n\n// oxlint-disable-next-line import/no-default-export -- The author CLI loads this documented generation entry.\nexport default generate;\nexport const buildOptions: typeof BUILD_OPTIONS = { ...BUILD_OPTIONS };\n`);
191
197
  }
192
198
 
199
+ /** AP37a: copy Mossgate Hollow's scene module (AP15) into `source` under this project's identity. Its only source is
200
+ * three.js: `generators/world.ts` builds the scene, `wildshard build` compiles it, `wildshard watch` streams each save. */
201
+ function writeSceneSource(source: string, slug: string): void {
202
+ // The trusted CLI bundle defines dirname as its installed source directory.
203
+ const scene = resolve(import.meta.dirname, '../shards/mossgate');
204
+ cpSync(scene, source, { recursive: true, errorOnExist: true, force: false,
205
+ filter: from => !/\.(?:test|spec)\.[cm]?[jt]sx?$/u.test(from) && from !== resolve(scene, 'public') });
206
+ writeFileSync(resolve(source, 'identity.json'), encodeCanonicalJson({ slug, name: slug, author: 'Local author', revision: 1, seed: 357 }));
207
+ writeFileSync(resolve(source, 'generators/shard.ts'), `import { defineShard } from '@wildshard/sdk/scene/shard';\nimport identity from '../identity.json' with { type: 'json' };\nimport { buildMossgate } from './world';\n\n/** This shard: the scene \`world.ts\` builds, under this project's identity. */\nexport const shard = defineShard(identity, buildMossgate);\n`);
208
+ writeFileSync(resolve(source, 'shard.config.ts'), `// The shard is one three.js scene module: \`generators/world.ts\`. \`wildshard build\` runs it as the generator;\n// \`wildshard watch\` reads its describe() and streams each saved edit to a running page.\nimport { shard } from './generators/shard';\n\nexport const generate: typeof shard = shard;\n// oxlint-disable-next-line import/no-default-export -- The author CLI executes this project entry.\nexport default generate;\n`);
209
+ }
210
+
193
211
  /** Write the runtime-free bare shard source (`new --empty`) into `source`. */
194
212
  function writeEmptySource(source: string, slug: string): void {
195
213
  for (const folder of ['generators', 'data', 'behaviour', 'assets']) mkdirSync(resolve(source, folder), { recursive: true });
@@ -207,7 +225,7 @@ export function writeEmptyShardSource(source: string, slug: string): void {
207
225
  writeEmptySource(source, slug);
208
226
  }
209
227
 
210
- /** `wildshard new <dir> [slug] [--template sdk] [--empty]` (and the retired `blender` shape, for tests): a whole single-shard repo, its shard source at `src/`. */
228
+ /** `wildshard new <dir> [slug] [--template sdk|scene] [--empty]` (and the retired `blender` shape, for tests): a whole single-shard repo, its shard source at `src/`. */
211
229
  export function writeShardRepo(project: string, slug: string, options: { readonly template?: RepoShape; readonly empty?: boolean } = {}): void {
212
230
  const template = options.template ?? DEFAULT_TEMPLATE;
213
231
  assertTarget(project, slug);
@@ -216,6 +234,7 @@ export function writeShardRepo(project: string, slug: string, options: { readonl
216
234
  try {
217
235
  if (options.empty === true) writeEmptySource(source, slug);
218
236
  else if (template === 'blender') writeHandwrittenSource(source, slug);
237
+ else if (template === 'scene') writeSceneSource(source, slug);
219
238
  else writeReferenceSource(source, slug);
220
239
  writeRepoFiles(project, slug, template, options.empty === true);
221
240
  } catch (error) {
@@ -38,7 +38,7 @@ import type { ScriptAdmissionRows } from '@wildshard/format/scriptContract';
38
38
  import { readCookInput, type CookInput } from './cookInput';
39
39
  import { audioEncodeLine, encodeMountAudio, readStereoMarks } from './audioEncode';
40
40
  import { engineMusicLine } from './engineMusic';
41
- import { AUTHOR_BUDGETS, AUTHOR_BUDGETS_MODULE, authorManifest } from './authorManifest';
41
+ import { AUTHOR_BUDGETS, AUTHOR_BUDGETS_MODULE, authorManifest, sceneCardUrls } from './authorManifest';
42
42
  import { discoveryDocument, discoveryUrl } from './discoveryDocument';
43
43
  import { outputScriptAdmissionRows, outputPlatformPayloads, clearOutputProduct, writeOutputProduct, type OutputProductOptions } from './outputProduct';
44
44
  import { prepareProjectOutput, mergeProjectBlobs, projectMirrors, type PreparedProjectOutput } from './projectOutput';
@@ -282,7 +282,7 @@ export async function buildProject(project: string, output?: string, options: {
282
282
  try {
283
283
  const runtime = options.copyRuntime === true || clientPlan ? writeRuntimeFiles(project, destination) : undefined;
284
284
  const encoded = await encodedCookInput(project, shard.identity.slug);
285
- const cook = await withDiscovery(project, shard.manifest ?? options.manifest?.composed ?? authorManifest(shard), loaded.output.discovery, encoded?.input, assets);
285
+ const cook = await withDiscovery(project, shard.manifest ?? options.manifest?.composed ?? authorManifest(shard, sceneCardUrls(project, shardFolderName(project))), loaded.output.discovery, encoded?.input, assets);
286
286
  descriptor = writeOutputProduct(shard, assets, destination, { ...loaded.output, ...(runtime === undefined ? {} : { runtime }), ...(cook === undefined ? {} : { cook }) });
287
287
  assertNoRenamedAudioNames(destination, encoded?.renamed ?? new Map());
288
288
  phase('product-write');
@@ -208,6 +208,7 @@ export const REFUSAL_RULES: readonly RefusalRule[] = [
208
208
  /** Wildshard's lint rules an author's source can hit (`.oxlintrc.author.json`), with the fix for each. */
209
209
  const LINT_FIXES: Readonly<Record<string, string>> = {
210
210
  'wildshard-sdk/generator-imports': 'Import Wildshard code only through @wildshard/sdk\'s exports; copy what another shard has instead of importing it.',
211
+ 'wildshard-sdk/no-hand-graph': 'Write the graph in TSL with graph() from @wildshard/sdk/materials; it compiles to the graph IR.',
211
212
  'wildshard/engine-internal': 'Use the shard-facing SDK export instead of the game-only engine export.',
212
213
  'wildshard/engine-sides': 'Keep client, server and shared code apart: import the shared module, not the other side\'s.',
213
214
  'wildshard/engine-words': 'Move Wildshard words (shard and game names) out of engine code into content data.',