@wildshard/sdk 0.0.1 → 0.2.4

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 (688) hide show
  1. package/GUIDE.md +895 -0
  2. package/README.md +13 -5
  3. package/bin/wildshard.mjs +38 -0
  4. package/lint/declaration-config.d.mts +2 -0
  5. package/lint/declaration-config.mjs +19 -0
  6. package/lint/engine-plugin.d.mts +2 -0
  7. package/lint/engine-plugin.mjs +40 -0
  8. package/lint/host-callbacks.d.mts +6 -0
  9. package/lint/host-callbacks.mjs +123 -0
  10. package/lint/host-files.d.mts +1 -0
  11. package/lint/host-files.mjs +7 -0
  12. package/lint/layer-exports.d.mts +2 -0
  13. package/lint/layer-exports.mjs +21 -0
  14. package/lint/legacy-line-basis.json +995 -0
  15. package/lint/nine-tiling-baseline.json +35 -0
  16. package/lint/ratchet.json +11 -0
  17. package/lint/runtime-files.d.mts +12 -0
  18. package/lint/runtime-files.json +16 -0
  19. package/lint/runtime-files.mjs +69 -0
  20. package/lint/runtime-performance.d.mts +6 -0
  21. package/lint/runtime-performance.mjs +184 -0
  22. package/lint/sdk-plugin.d.mts +4 -0
  23. package/lint/sdk-plugin.mjs +134 -0
  24. package/lint/shardfile-boundaries.d.mts +10 -0
  25. package/lint/shardfile-boundaries.mjs +122 -0
  26. package/lint/tile-bake-debt.json +556 -0
  27. package/package.json +365 -3
  28. package/scripts/agent-parity.mjs +1524 -0
  29. package/scripts/agent-sync.mjs +518 -0
  30. package/scripts/apfs-clone.mjs +67 -0
  31. package/scripts/assert-store-layout.mjs +23 -0
  32. package/scripts/astc6-phone-cap.d.mts +3 -0
  33. package/scripts/astc6-phone-cap.mjs +137 -0
  34. package/scripts/audit-assets.d.mts +10 -0
  35. package/scripts/audit-assets.mjs +151 -0
  36. package/scripts/bake/coatFiles.d.mts +6 -0
  37. package/scripts/bake/coatFiles.mjs +37 -0
  38. package/scripts/bake/environment.d.mts +2 -0
  39. package/scripts/bake/environment.mjs +58 -0
  40. package/scripts/bake/far-proxies.mjs +45 -0
  41. package/scripts/bake/keyed-sky.d.mts +4 -0
  42. package/scripts/bake/keyed-sky.mjs +34 -0
  43. package/scripts/bake/movers.mjs +56 -0
  44. package/scripts/bake/nativeWorld.d.mts +6 -0
  45. package/scripts/bake/nativeWorld.mjs +43 -0
  46. package/scripts/bake/navmeshGround.ts +22 -0
  47. package/scripts/bake/near-placeholder.mjs +331 -0
  48. package/scripts/bake/placeholderShards.mjs +41 -0
  49. package/scripts/bake/skins.mjs +15 -0
  50. package/scripts/bake/template-skins.mjs +33 -0
  51. package/scripts/bake/viewmodelBytes.ts +26 -0
  52. package/scripts/bake/viewmodelPage.ts +11 -0
  53. package/scripts/bake/worldHost.d.mts +35 -0
  54. package/scripts/bake/worldHost.mjs +110 -0
  55. package/scripts/bake-astc6.cache.json +80 -0
  56. package/scripts/bake-astc6.far-reach.cache.json +23 -0
  57. package/scripts/bake-astc6.list.json +111 -0
  58. package/scripts/bake-astc6.mjs +279 -0
  59. package/scripts/bake-astc6.nalati-grasslands.cache.json +42 -0
  60. package/scripts/bake-catalogue.mjs +44 -0
  61. package/scripts/bake-check.mjs +54 -0
  62. package/scripts/bake-chunk.mjs +124 -0
  63. package/scripts/bake-cloud-field.mjs +24 -0
  64. package/scripts/bake-coats.mjs +110 -0
  65. package/scripts/bake-data-maps.d.mts +24 -0
  66. package/scripts/bake-data-maps.mjs +72 -0
  67. package/scripts/bake-entry-programs.mjs +117 -0
  68. package/scripts/bake-geometry.mjs +106 -0
  69. package/scripts/bake-hybrid-tiles.mjs +28 -0
  70. package/scripts/bake-ktx2.cache.json +276 -0
  71. package/scripts/bake-ktx2.list.json +365 -0
  72. package/scripts/bake-ktx2.mjs +477 -0
  73. package/scripts/bake-map-glb.mjs +127 -0
  74. package/scripts/bake-map-rest.d.mts +7 -0
  75. package/scripts/bake-map-rest.mjs +50 -0
  76. package/scripts/bake-maps.mjs +200 -0
  77. package/scripts/bake-navmesh.mjs +259 -0
  78. package/scripts/bake-packs.mjs +129 -0
  79. package/scripts/bake-pickups.mjs +102 -0
  80. package/scripts/bake-query-terrain.mjs +64 -0
  81. package/scripts/bake-recurve-pool.mjs +16 -0
  82. package/scripts/bake-section-schemas.d.mts +3 -0
  83. package/scripts/bake-template-shardfile.mjs +32 -0
  84. package/scripts/bake-textures.mjs +80 -0
  85. package/scripts/bake-viewmodel-sets.json +45 -0
  86. package/scripts/bake-viewmodel-sets.mjs +137 -0
  87. package/scripts/bake-voxel-ao.mjs +119 -0
  88. package/scripts/bake-water-ripples.mjs +25 -0
  89. package/scripts/blender/README.md +129 -0
  90. package/scripts/blender/build.sh +166 -0
  91. package/scripts/blender/lib/export-scene.mjs +129 -0
  92. package/scripts/blender/lib/glb-digest.mjs +188 -0
  93. package/scripts/blender/lib/glb.py +68 -0
  94. package/scripts/blender/lib/save_blend.py +17 -0
  95. package/scripts/blender/lib/world_fixture.py +55 -0
  96. package/scripts/blender/targets.json +591 -0
  97. package/scripts/build-sdk.mjs +95 -0
  98. package/scripts/build-shardfiles.d.mts +7 -0
  99. package/scripts/build-shardfiles.mjs +206 -0
  100. package/scripts/capture-hero.mjs +137 -0
  101. package/scripts/check-lift-review.mjs +23 -0
  102. package/scripts/chromium-keychain-check.mjs +139 -0
  103. package/scripts/chromium-keychain.d.mts +1 -0
  104. package/scripts/chromium-keychain.mjs +5 -0
  105. package/scripts/compile-script.d.mts +3 -0
  106. package/scripts/compile-script.mjs +8 -0
  107. package/scripts/creature-color.mjs +255 -0
  108. package/scripts/decide/calibrate.py +127 -0
  109. package/scripts/decide/calibration/2026-10-03/labels-s1.tsv +281 -0
  110. package/scripts/decide/calibration/2026-10-03/labels-s2.tsv +97 -0
  111. package/scripts/decide/calibration/2026-10-03/labels-s3.tsv +48 -0
  112. package/scripts/decide/calibration/2026-10-03/labels-s3b.tsv +26 -0
  113. package/scripts/decide/calibration/2026-10-03/res-capture-status-v1.jsonl +376 -0
  114. package/scripts/decide/calibration/2026-10-03/res-text-garbled-strings.jsonl +48 -0
  115. package/scripts/decide/calibration/2026-10-03/res-text-garbled-v1.jsonl +73 -0
  116. package/scripts/decide/decide.py +262 -0
  117. package/scripts/decide/decide.sh +50 -0
  118. package/scripts/decide/layer-purity-pilot.mjs +41 -0
  119. package/scripts/decide/sets/capture-status.json +46 -0
  120. package/scripts/decide/sets/layer-purity.json +28 -0
  121. package/scripts/decide/sets/text-garbled.json +17 -0
  122. package/scripts/decide/test_decide.py +37 -0
  123. package/scripts/docs.mjs +15 -0
  124. package/scripts/entry-reads/crawl.ts +152 -0
  125. package/scripts/entry-reads/tsconfig.json +25 -0
  126. package/scripts/gen-format-schema.d.mts +2 -0
  127. package/scripts/gen-format-schema.mjs +21 -0
  128. package/scripts/gen-host-catalogue.d.mts +14 -0
  129. package/scripts/gen-host-catalogue.mjs +108 -0
  130. package/scripts/gen-shard-layout-doc.d.mts +4 -0
  131. package/scripts/gen-shard-layout-doc.mjs +55 -0
  132. package/scripts/gen-shards.d.mts +17 -0
  133. package/scripts/gen-shards.mjs +311 -0
  134. package/scripts/goldens/capture-inputs.d.mts +4 -0
  135. package/scripts/goldens/capture-inputs.mjs +34 -0
  136. package/scripts/goldens/colour_shift.py +27 -0
  137. package/scripts/goldens/native-residency.d.mts +10 -0
  138. package/scripts/goldens/native-residency.mjs +104 -0
  139. package/scripts/goldens/plot-inputs.d.mts +12 -0
  140. package/scripts/goldens/plot-inputs.mjs +46 -0
  141. package/scripts/gpu-texmem.mjs +98 -0
  142. package/scripts/horizon-matte/config.py +24 -0
  143. package/scripts/horizon-matte/encode.py +91 -0
  144. package/scripts/horizon-matte/key.py +141 -0
  145. package/scripts/horizon-matte/mkjobs.py +33 -0
  146. package/scripts/horizon-matte/mkjobs_day2.py +11 -0
  147. package/scripts/horizon-matte/overlap.py +80 -0
  148. package/scripts/horizon-matte/run_codex.py +57 -0
  149. package/scripts/horizon-matte/stitch.py +133 -0
  150. package/scripts/img2mesh/CC0.md +105 -0
  151. package/scripts/img2mesh/README.md +209 -0
  152. package/scripts/img2mesh/ab_board.py +102 -0
  153. package/scripts/img2mesh/birds/birds.json +255 -0
  154. package/scripts/img2mesh/birds/birds_atlas.py +150 -0
  155. package/scripts/img2mesh/birds/birds_fix_preview.mjs +103 -0
  156. package/scripts/img2mesh/birds/birds_fix_render.py +75 -0
  157. package/scripts/img2mesh/birds/birds_pack.py +110 -0
  158. package/scripts/img2mesh/birds/birds_phone_b.py +112 -0
  159. package/scripts/img2mesh/birds/birds_post.py +550 -0
  160. package/scripts/img2mesh/birds/birds_render.py +125 -0
  161. package/scripts/img2mesh/birds/birds_sheet.py +33 -0
  162. package/scripts/img2mesh/birds/birds_view.py +60 -0
  163. package/scripts/img2mesh/board.py +100 -0
  164. package/scripts/img2mesh/build_cc0.sh +52 -0
  165. package/scripts/img2mesh/build_driftwood.sh +12 -0
  166. package/scripts/img2mesh/build_faces.sh +53 -0
  167. package/scripts/img2mesh/build_props.py +81 -0
  168. package/scripts/img2mesh/cc0_export.py +186 -0
  169. package/scripts/img2mesh/driftwood_post.py +571 -0
  170. package/scripts/img2mesh/e304_faces.sh +67 -0
  171. package/scripts/img2mesh/face_remaster.py +911 -0
  172. package/scripts/img2mesh/face_views.py +95 -0
  173. package/scripts/img2mesh/faces-e304.json +9 -0
  174. package/scripts/img2mesh/faces.json +30 -0
  175. package/scripts/img2mesh/head_cut.py +100 -0
  176. package/scripts/img2mesh/hi3d_paint.py +94 -0
  177. package/scripts/img2mesh/hi3d_refine.py +161 -0
  178. package/scripts/img2mesh/hunyuan_cpu_rasterizer.sh +42 -0
  179. package/scripts/img2mesh/pine_hollow_phone.sh +13 -0
  180. package/scripts/img2mesh/props/coral-arch.json +32 -0
  181. package/scripts/img2mesh/props/ember-furnace.json +30 -0
  182. package/scripts/img2mesh/props/night-market-gate.json +10 -0
  183. package/scripts/img2mesh/render_still.py +86 -0
  184. package/scripts/img2mesh/rig_strip.mjs +46 -0
  185. package/scripts/img2mesh/rig_transfer.mjs +104 -0
  186. package/scripts/img2mesh/split_sheet.py +48 -0
  187. package/scripts/img2mesh/trellis_batch.py +110 -0
  188. package/scripts/img2mesh/versus_board.py +114 -0
  189. package/scripts/import-bundle.d.mts +2 -0
  190. package/scripts/import-bundle.mjs +20 -0
  191. package/scripts/ktx2-ab-board.py +133 -0
  192. package/scripts/ktx2-ab.mjs +111 -0
  193. package/scripts/ktx2-settings.mjs +18 -0
  194. package/scripts/land.d.mts +14 -0
  195. package/scripts/land.mjs +809 -0
  196. package/scripts/lint-dispatch.mjs +14 -0
  197. package/scripts/map-bake-frames.d.mts +4 -0
  198. package/scripts/map-bake-frames.mjs +23 -0
  199. package/scripts/map-geometry.d.mts +9 -0
  200. package/scripts/map-geometry.mjs +29 -0
  201. package/scripts/map-world.mjs +162 -0
  202. package/scripts/mockup-local.sh +46 -0
  203. package/scripts/music/export-midi.mjs +68 -0
  204. package/scripts/music/gen/analyze.py +308 -0
  205. package/scripts/music/gen/audio_jobs.py +46 -0
  206. package/scripts/music/gen/briefs.json +51 -0
  207. package/scripts/music/gen/build_page.py +334 -0
  208. package/scripts/music/gen/folk.json +3187 -0
  209. package/scripts/music/gen/gen_ace_step.py +156 -0
  210. package/scripts/music/gen/gen_heartmula.py +187 -0
  211. package/scripts/music/gen/gen_minimax.py +143 -0
  212. package/scripts/music/gen/gen_sao.py +122 -0
  213. package/scripts/music/gen/gen_sao_small.py +104 -0
  214. package/scripts/music/gen/gen_sfx.py +98 -0
  215. package/scripts/music/gen/gen_sfx_ezaudio.py +112 -0
  216. package/scripts/music/gen/gen_sfx_moss.py +112 -0
  217. package/scripts/music/gen/models.json +61 -0
  218. package/scripts/music/gen/nalati-jobs.json +104 -0
  219. package/scripts/music/gen/nalati-score-build.json +119 -0
  220. package/scripts/music/gen/nalati-score.json +3448 -0
  221. package/scripts/music/gen/ob7-fit-decisions.json +38 -0
  222. package/scripts/music/gen/ob7-score-jobs.json +152 -0
  223. package/scripts/music/gen/ob7-sfx-jobs.json +897 -0
  224. package/scripts/music/gen/ob7_build.py +469 -0
  225. package/scripts/music/gen/ob7_generate.py +67 -0
  226. package/scripts/music/gen/ob7_run.sh +42 -0
  227. package/scripts/music/gen/orchestral.json +3187 -0
  228. package/scripts/music/gen/own_score.py +486 -0
  229. package/scripts/music/gen/ph-jobs.json +27 -0
  230. package/scripts/music/gen/ph_page.py +222 -0
  231. package/scripts/music/gen/piano.json +3175 -0
  232. package/scripts/music/gen/rank_v3.py +248 -0
  233. package/scripts/music/gen/sfx-best.json +2486 -0
  234. package/scripts/music/gen/sfx-ezaudio.json +4082 -0
  235. package/scripts/music/gen/sfx-jobs.json +57 -0
  236. package/scripts/music/gen/sfx-minimax-jobs.json +16 -0
  237. package/scripts/music/gen/sfx-minimax.json +289 -0
  238. package/scripts/music/gen/sfx-moss.json +4082 -0
  239. package/scripts/music/gen/sfx-nalati-b3-jobs.json +17 -0
  240. package/scripts/music/gen/sfx-nalati-jobs.json +338 -0
  241. package/scripts/music/gen/sfx-nalati.json +11202 -0
  242. package/scripts/music/gen/sfx-nd-jobs.json +57 -0
  243. package/scripts/music/gen/sfx-nd-moss.json +2097 -0
  244. package/scripts/music/gen/sfx-nd-sa3-medium.json +2097 -0
  245. package/scripts/music/gen/sfx-nd-summary.json +38 -0
  246. package/scripts/music/gen/sfx-peaks.json +7 -0
  247. package/scripts/music/gen/sfx-ph-jobs.json +169 -0
  248. package/scripts/music/gen/sfx-ph-moss.json +6564 -0
  249. package/scripts/music/gen/sfx-ph-sa3-medium.json +7239 -0
  250. package/scripts/music/gen/sfx-ph-summary.json +63 -0
  251. package/scripts/music/gen/sfx-sa3-medium.json +4082 -0
  252. package/scripts/music/gen/sfx-sa3.json +4082 -0
  253. package/scripts/music/gen/sfx-summary.json +107 -0
  254. package/scripts/music/gen/sfx_build.py +332 -0
  255. package/scripts/music/gen/sfx_merge.py +255 -0
  256. package/scripts/music/gen/sfx_minimax.py +61 -0
  257. package/scripts/music/gen/sfx_nalati.py +331 -0
  258. package/scripts/music/gen/sfx_sprite.py +424 -0
  259. package/scripts/music/gen/stems.py +539 -0
  260. package/scripts/music/gen/test_loop_meter.py +29 -0
  261. package/scripts/music/gen/test_ob7_provenance.py +77 -0
  262. package/scripts/music/gen/v3-folk-build.json +148 -0
  263. package/scripts/music/gen/v3-folk.json +1818 -0
  264. package/scripts/music/gen/v3-jobs.json +145 -0
  265. package/scripts/music/gen/v3-orchestral-build.json +148 -0
  266. package/scripts/music/gen/v3-orchestral.json +1813 -0
  267. package/scripts/music/gen/v3-ph-folk-build.json +94 -0
  268. package/scripts/music/gen/v3-ph-folk.json +1806 -0
  269. package/scripts/music/gen/v3-ph-orchestral-build.json +94 -0
  270. package/scripts/music/gen/v3-ph-orchestral.json +1824 -0
  271. package/scripts/music/gen/v3-ph-piano-build.json +94 -0
  272. package/scripts/music/gen/v3-ph-piano.json +1818 -0
  273. package/scripts/music/gen/v3-piano-build.json +148 -0
  274. package/scripts/music/gen/v3-piano.json +1813 -0
  275. package/scripts/music/wildshard-theme.mid +0 -0
  276. package/scripts/music/wildshard-trailer30.mid +0 -0
  277. package/scripts/named-blob-output.d.mts +8 -0
  278. package/scripts/named-blob-output.mjs +48 -0
  279. package/scripts/pack-all.mjs +15 -0
  280. package/scripts/pid-lock.d.mts +1 -0
  281. package/scripts/pid-lock.mjs +63 -0
  282. package/scripts/practice/bake_dummy.py +53 -0
  283. package/scripts/practice/build_dummies.sh +43 -0
  284. package/scripts/practice/dummy_parts.py +568 -0
  285. package/scripts/practice/dummy_rig_gate.py +139 -0
  286. package/scripts/practice/gate_sheet.py +36 -0
  287. package/scripts/practice/generate_dummy_unimate.py +132 -0
  288. package/scripts/practice/pack_dummy.mjs +59 -0
  289. package/scripts/practice/repair_dummy_weights.mjs +68 -0
  290. package/scripts/practice/rig_dummy.py +828 -0
  291. package/scripts/practice/verify_unimate_skin.mjs +356 -0
  292. package/scripts/preparation-seed.mjs +15 -0
  293. package/scripts/prepare-basis-tool.mjs +6 -0
  294. package/scripts/prepare-product.d.mts +14 -0
  295. package/scripts/prepare-product.mjs +101 -0
  296. package/scripts/product-build-tools.d.mts +3 -0
  297. package/scripts/product-build-tools.json +3 -0
  298. package/scripts/product-build-tools.mjs +31 -0
  299. package/scripts/publish-public.mjs +7 -0
  300. package/scripts/push-tables.d.mts +1 -0
  301. package/scripts/push-tables.mjs +28 -0
  302. package/scripts/record-shard-mounts.mjs +133 -0
  303. package/scripts/sdk-externals.d.mts +2 -0
  304. package/scripts/sdk-externals.mjs +2 -0
  305. package/scripts/section-inventory.ts +209 -0
  306. package/scripts/select-candidate.mjs +15 -0
  307. package/scripts/shard-build-pool.d.mts +4 -0
  308. package/scripts/shard-build-pool.mjs +53 -0
  309. package/scripts/shard-line-baseline.json +17 -0
  310. package/scripts/shard-milestones.d.mts +15 -0
  311. package/scripts/shard-milestones.mjs +105 -0
  312. package/scripts/shard-output-report.d.mts +9 -0
  313. package/scripts/shard-output-report.mjs +85 -0
  314. package/scripts/shard-platform-cli.mjs +93 -0
  315. package/scripts/shard-progress.mjs +212 -0
  316. package/scripts/shard-timelapse.py +102 -0
  317. package/scripts/shardfile-cold-boot.mjs +79 -0
  318. package/scripts/shardfile-vite.d.mts +4 -0
  319. package/scripts/shardfile-vite.mjs +20 -0
  320. package/scripts/simplify-models.mjs +24 -0
  321. package/scripts/site-facts.mjs +88 -0
  322. package/scripts/test-template-gate.mjs +44 -0
  323. package/scripts/test_golden_compare.py +68 -0
  324. package/scripts/tex-tiers.cache.json +181 -0
  325. package/scripts/tex-tiers.mjs +240 -0
  326. package/scripts/texmem-probe.mjs +184 -0
  327. package/scripts/unused-assets.mjs +173 -0
  328. package/scripts/vite-tmp.d.mts +23 -0
  329. package/scripts/vite-tmp.mjs +157 -0
  330. package/scripts/wave-line-baselines.json +32 -0
  331. package/scripts/wildshard.d.mts +4 -0
  332. package/scripts/wildshard.mjs +105 -0
  333. package/scripts/witness-checkpoints.d.mts +10 -0
  334. package/scripts/witness-checkpoints.mjs +84 -0
  335. package/scripts/witness-generation.d.mts +10 -0
  336. package/scripts/witness-generation.mjs +45 -0
  337. package/scripts/witness-manifests.d.mts +8 -0
  338. package/scripts/witness-manifests.mjs +157 -0
  339. package/scripts/worktree-ignore.d.mts +4 -0
  340. package/scripts/worktree-ignore.mjs +36 -0
  341. package/scripts/worktree-reap.mjs +214 -0
  342. package/scripts/worktree.mjs +396 -0
  343. package/scripts/worldclaw/capture-front.sh +28 -0
  344. package/scripts/worldclaw/design-template.md +62 -0
  345. package/scripts/worldclaw/spec-map.py +92 -0
  346. package/scripts/worldclaw/spec.ts +96 -0
  347. package/skills/wildshard/SKILL.md +50 -0
  348. package/skills/wildshard-goldens/SKILL.md +54 -0
  349. package/skills/wildshard-mockup-to-model/SKILL.md +56 -0
  350. package/skills/wildshard-upgrade/SKILL.md +47 -0
  351. package/src/.oxfmtrc.json +50 -0
  352. package/src/.oxlintrc.json +173 -0
  353. package/src/cli/account/account.ts +199 -0
  354. package/src/cli/account/command.ts +193 -0
  355. package/src/cli/account/key.ts +154 -0
  356. package/src/cli/args.ts +97 -0
  357. package/src/cli/audio/audio.ts +39 -0
  358. package/src/cli/bin.mjs +8 -0
  359. package/src/cli/delete/delete.ts +258 -0
  360. package/src/cli/help.ts +204 -0
  361. package/src/cli/hero/adopt.ts +103 -0
  362. package/src/cli/hero/hero.ts +112 -0
  363. package/src/cli/hero/stamp.ts +298 -0
  364. package/src/cli/main.ts +291 -0
  365. package/src/cli/report.ts +20 -0
  366. package/src/cli/shardfile/command.ts +49 -0
  367. package/src/cli/shardfile/shardfile.ts +192 -0
  368. package/src/cli/upload/api.ts +246 -0
  369. package/src/cli/upload/compress.ts +55 -0
  370. package/src/cli/upload/hero.ts +62 -0
  371. package/src/cli/upload/placement.ts +115 -0
  372. package/src/cli/upload/provenance.ts +192 -0
  373. package/src/cli/upload/signature.ts +30 -0
  374. package/src/cli/upload/upload.ts +269 -0
  375. package/src/cli/upload/validate.ts +74 -0
  376. package/src/cli/upload/wire.ts +147 -0
  377. package/src/cli/version.ts +63 -0
  378. package/src/commons/bake/portableMath.ts +187 -0
  379. package/src/commons/catalogue.ts +10 -0
  380. package/src/commons/courseProgram.ts +32 -0
  381. package/src/commons/practiceCourse.ts +16 -0
  382. package/src/commons/scripts/abi.as +14 -0
  383. package/src/commons/scripts/bridge.as +14 -0
  384. package/src/commons/scripts/course.as +63 -0
  385. package/src/scripts/ask-new.sh +29 -0
  386. package/src/scripts/asks.mjs +141 -0
  387. package/src/scripts/herdr-prompt.sh +34 -0
  388. package/src/scripts/herdr-question-open.sh +67 -0
  389. package/src/scripts/md-wrap.mjs +229 -0
  390. package/src/server/app.ts +19 -0
  391. package/src/server/serve.ts +49 -0
  392. package/src/sharddev/admission.ts +7 -0
  393. package/src/sharddev/agentFiles.ts +127 -0
  394. package/src/sharddev/arenaView.ts +15 -0
  395. package/src/sharddev/as/groupBankV2.ts +36 -0
  396. package/src/sharddev/as/groupStepV2.ts +13 -0
  397. package/src/sharddev/as/ws.ts +30 -0
  398. package/src/sharddev/as/wsV2.ts +180 -0
  399. package/src/sharddev/assemblyscriptCompiler.d.mts +5 -0
  400. package/src/sharddev/assemblyscriptCompiler.mjs +14 -0
  401. package/src/sharddev/assetHandle.ts +84 -0
  402. package/src/sharddev/assetOwner.ts +70 -0
  403. package/src/sharddev/assetScope.ts +30 -0
  404. package/src/sharddev/assets.ts +21 -0
  405. package/src/sharddev/audio.ts +9 -0
  406. package/src/sharddev/audioEncode.ts +211 -0
  407. package/src/sharddev/author.ts +3 -0
  408. package/src/sharddev/authorError.ts +28 -0
  409. package/src/sharddev/authorManifest.ts +39 -0
  410. package/src/sharddev/bake/annulus.ts +19 -0
  411. package/src/sharddev/bake/assemblyscriptMemo.ts +76 -0
  412. package/src/sharddev/bake/assemblyscriptMemoPort.ts +4 -0
  413. package/src/sharddev/bake/authoredWorld.ts +201 -0
  414. package/src/sharddev/bake/basisEncoder.ts +95 -0
  415. package/src/sharddev/bake/basisGlb.ts +85 -0
  416. package/src/sharddev/bake/basisTool.ts +74 -0
  417. package/src/sharddev/bake/basisToolInputs.ts +476 -0
  418. package/src/sharddev/bake/byteCodec.ts +33 -0
  419. package/src/sharddev/bake/canvasAtlas.ts +406 -0
  420. package/src/sharddev/bake/coarseCopy.ts +59 -0
  421. package/src/sharddev/bake/colliders.ts +87 -0
  422. package/src/sharddev/bake/compactGlb.ts +224 -0
  423. package/src/sharddev/bake/compileScript.ts +119 -0
  424. package/src/sharddev/bake/compileScriptV2.ts +75 -0
  425. package/src/sharddev/bake/contactRows.ts +84 -0
  426. package/src/sharddev/bake/creaturePlacement.ts +117 -0
  427. package/src/sharddev/bake/export.ts +67 -0
  428. package/src/sharddev/bake/facetedGeometry.ts +379 -0
  429. package/src/sharddev/bake/farImpostor.ts +120 -0
  430. package/src/sharddev/bake/forest.ts +100 -0
  431. package/src/sharddev/bake/format-hook.mjs +2 -0
  432. package/src/sharddev/bake/generatorGlb.ts +23 -0
  433. package/src/sharddev/bake/geometryBounds.ts +77 -0
  434. package/src/sharddev/bake/geometryError.ts +48 -0
  435. package/src/sharddev/bake/glb.ts +355 -0
  436. package/src/sharddev/bake/glbCompression.ts +143 -0
  437. package/src/sharddev/bake/gltfSource.ts +59 -0
  438. package/src/sharddev/bake/groundMap.ts +142 -0
  439. package/src/sharddev/bake/image.ts +20 -0
  440. package/src/sharddev/bake/isleMap.ts +64 -0
  441. package/src/sharddev/bake/json.mjs +84 -0
  442. package/src/sharddev/bake/keyedSky.ts +47 -0
  443. package/src/sharddev/bake/keyedSkyMemo.ts +39 -0
  444. package/src/sharddev/bake/kinds.ts +137 -0
  445. package/src/sharddev/bake/lightSources.ts +31 -0
  446. package/src/sharddev/bake/mapAssembly.ts +84 -0
  447. package/src/sharddev/bake/mapRaster.ts +173 -0
  448. package/src/sharddev/bake/mapRest.ts +57 -0
  449. package/src/sharddev/bake/mapScenes.ts +234 -0
  450. package/src/sharddev/bake/materialGraph.ts +32 -0
  451. package/src/sharddev/bake/meadow.ts +27 -0
  452. package/src/sharddev/bake/meshoptChoiceMemo.ts +34 -0
  453. package/src/sharddev/bake/nativeInteractionFacts.ts +5 -0
  454. package/src/sharddev/bake/nativeLattice.ts +178 -0
  455. package/src/sharddev/bake/nativeRaster.ts +106 -0
  456. package/src/sharddev/bake/nativeTerrainField.ts +11 -0
  457. package/src/sharddev/bake/navigation-json.mjs +38 -0
  458. package/src/sharddev/bake/navigation.ts +113 -0
  459. package/src/sharddev/bake/navigationAsset.ts +18 -0
  460. package/src/sharddev/bake/nearPlaceholder.ts +206 -0
  461. package/src/sharddev/bake/normalizeRig.ts +80 -0
  462. package/src/sharddev/bake/phoneAstc.ts +93 -0
  463. package/src/sharddev/bake/placeholders.ts +581 -0
  464. package/src/sharddev/bake/placement.ts +80 -0
  465. package/src/sharddev/bake/portableBytes.ts +18 -0
  466. package/src/sharddev/bake/portableBytesMemo.ts +50 -0
  467. package/src/sharddev/bake/practiceCourse.ts +49 -0
  468. package/src/sharddev/bake/primitives.ts +96 -0
  469. package/src/sharddev/bake/props.ts +443 -0
  470. package/src/sharddev/bake/questPlacement.ts +98 -0
  471. package/src/sharddev/bake/rawTexture.ts +26 -0
  472. package/src/sharddev/bake/riderArms.ts +97 -0
  473. package/src/sharddev/bake/rig.ts +95 -0
  474. package/src/sharddev/bake/riggedHullRecipes.ts +40 -0
  475. package/src/sharddev/bake/signPlacements.ts +25 -0
  476. package/src/sharddev/bake/simplifier.ts +52 -0
  477. package/src/sharddev/bake/skinned.ts +312 -0
  478. package/src/sharddev/bake/slabChunks.ts +149 -0
  479. package/src/sharddev/bake/slabs.ts +263 -0
  480. package/src/sharddev/bake/source-loader.mjs +55 -0
  481. package/src/sharddev/bake/sourceMetadata.ts +54 -0
  482. package/src/sharddev/bake/species.ts +368 -0
  483. package/src/sharddev/bake/specimenCatalogue.ts +47 -0
  484. package/src/sharddev/bake/splatGround.ts +141 -0
  485. package/src/sharddev/bake/staticMaterials.ts +171 -0
  486. package/src/sharddev/bake/terrain.ts +195 -0
  487. package/src/sharddev/bake/texture.ts +33 -0
  488. package/src/sharddev/bake/textureWasm.ts +81 -0
  489. package/src/sharddev/bake/tileEncoder.ts +11 -0
  490. package/src/sharddev/bake/tileGrid.ts +62 -0
  491. package/src/sharddev/bake/v2Finite.ts +160 -0
  492. package/src/sharddev/bake/v2Fuel.ts +71 -0
  493. package/src/sharddev/bake/wholePartition.ts +74 -0
  494. package/src/sharddev/bake/wholePieceJoin.ts +147 -0
  495. package/src/sharddev/bake/world.ts +173 -0
  496. package/src/sharddev/bake/worldCollision.ts +128 -0
  497. package/src/sharddev/bake/worldGeometry.ts +237 -0
  498. package/src/sharddev/bake/worldGlb.ts +123 -0
  499. package/src/sharddev/bake/worldImage.ts +12 -0
  500. package/src/sharddev/bake/worldLod.ts +128 -0
  501. package/src/sharddev/bake/worldRows.ts +102 -0
  502. package/src/sharddev/bake/worldTextureMemo.ts +63 -0
  503. package/src/sharddev/bake/zstdBytesMemo.ts +52 -0
  504. package/src/sharddev/bake.ts +193 -0
  505. package/src/sharddev/bakePublication.ts +31 -0
  506. package/src/sharddev/behaviourSource.ts +94 -0
  507. package/src/sharddev/bin/wildshard.mjs +7 -0
  508. package/src/sharddev/blobBytes.ts +65 -0
  509. package/src/sharddev/blobs.ts +138 -0
  510. package/src/sharddev/bootInventory.ts +129 -0
  511. package/src/sharddev/bossProfiles.ts +18 -0
  512. package/src/sharddev/buildBehaviour.ts +77 -0
  513. package/src/sharddev/buildCacheMetrics.ts +17 -0
  514. package/src/sharddev/buildDecisionScripts.ts +122 -0
  515. package/src/sharddev/check.ts +118 -0
  516. package/src/sharddev/checkProject.ts +127 -0
  517. package/src/sharddev/cli.ts +200 -0
  518. package/src/sharddev/clientChannels.ts +169 -0
  519. package/src/sharddev/clientScripts.ts +10 -0
  520. package/src/sharddev/commons.ts +77 -0
  521. package/src/sharddev/commonsCosts.ts +11 -0
  522. package/src/sharddev/compileMovers.ts +11 -0
  523. package/src/sharddev/configBoundary.ts +6 -0
  524. package/src/sharddev/cookInput.ts +40 -0
  525. package/src/sharddev/crowds.ts +6 -0
  526. package/src/sharddev/decisionBindingMap.ts +11 -0
  527. package/src/sharddev/decisionScriptBindings.ts +117 -0
  528. package/src/sharddev/decisionScripts.ts +28 -0
  529. package/src/sharddev/decisionSource.ts +51 -0
  530. package/src/sharddev/dev.ts +113 -0
  531. package/src/sharddev/director.ts +26 -0
  532. package/src/sharddev/directorAbi.ts +77 -0
  533. package/src/sharddev/discoveryDocument.ts +97 -0
  534. package/src/sharddev/draft.ts +11 -0
  535. package/src/sharddev/eliteEntryRows.ts +29 -0
  536. package/src/sharddev/entries.ts +76 -0
  537. package/src/sharddev/entryReads.ts +73 -0
  538. package/src/sharddev/executeBundle.ts +55 -0
  539. package/src/sharddev/finds.ts +5 -0
  540. package/src/sharddev/formatJsonSchema.ts +3 -0
  541. package/src/sharddev/generationCache.ts +257 -0
  542. package/src/sharddev/generationRecipe.ts +94 -0
  543. package/src/sharddev/handwritten.ts +110 -0
  544. package/src/sharddev/immutable.ts +14 -0
  545. package/src/sharddev/interactions.ts +38 -0
  546. package/src/sharddev/kit/bakedGeometry.ts +16 -0
  547. package/src/sharddev/kit/geometryPack.ts +110 -0
  548. package/src/sharddev/ledger.ts +13 -0
  549. package/src/sharddev/looks/tileField.ts +67 -0
  550. package/src/sharddev/materialGraphFiles.ts +57 -0
  551. package/src/sharddev/materials.ts +574 -0
  552. package/src/sharddev/measure.ts +18 -0
  553. package/src/sharddev/modes.ts +115 -0
  554. package/src/sharddev/moverPrograms.ts +213 -0
  555. package/src/sharddev/movers.ts +75 -0
  556. package/src/sharddev/nativePopulationRows.ts +46 -0
  557. package/src/sharddev/newProject.ts +226 -0
  558. package/src/sharddev/noise.ts +54 -0
  559. package/src/sharddev/outputProduct.ts +188 -0
  560. package/src/sharddev/outputRuntime.ts +66 -0
  561. package/src/sharddev/performancePolicy.ts +29 -0
  562. package/src/sharddev/phasedBoss.ts +34 -0
  563. package/src/sharddev/physics.ts +194 -0
  564. package/src/sharddev/platformSections.ts +42 -0
  565. package/src/sharddev/plumbing.ts +8 -0
  566. package/src/sharddev/productOutput.ts +128 -0
  567. package/src/sharddev/project.ts +337 -0
  568. package/src/sharddev/projectCompilerIdentity.ts +94 -0
  569. package/src/sharddev/projectDecisions.ts +66 -0
  570. package/src/sharddev/projectEntryProof.ts +32 -0
  571. package/src/sharddev/projectGeneration.ts +219 -0
  572. package/src/sharddev/projectInputFiles.ts +47 -0
  573. package/src/sharddev/projectManifest.ts +108 -0
  574. package/src/sharddev/projectMap.ts +35 -0
  575. package/src/sharddev/projectOutput.ts +242 -0
  576. package/src/sharddev/projectPolicy.ts +17 -0
  577. package/src/sharddev/projectSections.ts +27 -0
  578. package/src/sharddev/questGraph.ts +25 -0
  579. package/src/sharddev/quests.ts +65 -0
  580. package/src/sharddev/random.ts +61 -0
  581. package/src/sharddev/refusals.ts +304 -0
  582. package/src/sharddev/reportCard.ts +13 -0
  583. package/src/sharddev/returnProjectionV2.ts +81 -0
  584. package/src/sharddev/rows.ts +192 -0
  585. package/src/sharddev/runtimeImports.ts +38 -0
  586. package/src/sharddev/runtimeMirrors.ts +39 -0
  587. package/src/sharddev/runtimePerformance.ts +38 -0
  588. package/src/sharddev/scene.ts +321 -0
  589. package/src/sharddev/sceneAnimation.ts +54 -0
  590. package/src/sharddev/sceneAudio.ts +64 -0
  591. package/src/sharddev/sceneDeclarations.ts +100 -0
  592. package/src/sharddev/sceneGraph.ts +139 -0
  593. package/src/sharddev/sceneTransform.ts +12 -0
  594. package/src/sharddev/schemaValidation.ts +61 -0
  595. package/src/sharddev/sections.ts +47 -0
  596. package/src/sharddev/shardSource.ts +59 -0
  597. package/src/sharddev/sourceReader.ts +26 -0
  598. package/src/sharddev/spawns.ts +38 -0
  599. package/src/sharddev/species/clips.ts +24 -0
  600. package/src/sharddev/species.ts +29 -0
  601. package/src/sharddev/speciesBrains.ts +19 -0
  602. package/src/sharddev/synth.ts +66 -0
  603. package/src/sharddev/test/compileDualScriptV2.ts +71 -0
  604. package/src/sharddev/test/compileSimV2.ts +21 -0
  605. package/src/sharddev/test/diskScriptScenario.ts +86 -0
  606. package/src/sharddev/test/scriptScenario.ts +249 -0
  607. package/src/sharddev/test/scriptSource.ts +12 -0
  608. package/src/sharddev/version.ts +4 -0
  609. package/src/sharddev/weapons/bowProfile.ts +20 -0
  610. package/src/sharddev/weapons/firearmRows.ts +11 -0
  611. package/src/sharddev/weapons/meleeProfile.ts +71 -0
  612. package/src/sharddev/weapons/thrownProfile.ts +10 -0
  613. package/src/sharddev/worldScenes.ts +308 -0
  614. package/src/sharddev/worldSource.ts +82 -0
  615. package/src/shards/_template/README.md +78 -0
  616. package/src/shards/_template/assets/2bf489fdb15f1734ddb4c4f32d500ec6da85c765ec7a4eb28dc6781160e7ec8c +0 -0
  617. package/src/shards/_template/assets/97ec4d8f75f5fa6239ee919444d6dc19fd35896bb305930c1f050ac6e0e0e6a6 +1 -0
  618. package/src/shards/_template/assets/a6a587a31327f936b1b04c05ade818c73fc8964260918662db43539465e27586 +0 -0
  619. package/src/shards/_template/assets/b4fbde0422e125b498c3dc8b9a5cc2516c8598f09e9d0e5f6b639b32f98179e6 +0 -0
  620. package/src/shards/_template/assets/bfa4dfc9c18979f904557ee8deab0058b8a399be10266f5fb1578b403f482fd4 +1 -0
  621. package/src/shards/_template/assets/ef3b7ff4fd22715771cb7d68a3977a903c5e7c3dc293542687d04b3ef3ace2cb +0 -0
  622. package/src/shards/_template/assets/f2db05998615ce1cb79ea96be32c168842eb6a2b34ec01feb86d36404603ee54 +0 -0
  623. package/src/shards/_template/assets/fef98ebb7fce6f66b26e78ac699e5c90f9bdcfaf8cabeb2b58125347eea8b4ab +0 -0
  624. package/src/shards/_template/behaviour/boss.as +39 -0
  625. package/src/shards/_template/behaviour/door.as +32 -0
  626. package/src/shards/_template/behaviour/hooks.json +129 -0
  627. package/src/shards/_template/behaviour/idle.as +75 -0
  628. package/src/shards/_template/behaviour/items.as +22 -0
  629. package/src/shards/_template/card/landscape.jpg +0 -0
  630. package/src/shards/_template/card/portrait.jpg +0 -0
  631. package/src/shards/_template/card/thumb.jpg +0 -0
  632. package/src/shards/_template/data/audio.json +45 -0
  633. package/src/shards/_template/data/bossDecision.json +83 -0
  634. package/src/shards/_template/data/budgets.json +70 -0
  635. package/src/shards/_template/data/card.json +281 -0
  636. package/src/shards/_template/data/clientScripts.json +987 -0
  637. package/src/shards/_template/data/creatures.json +65 -0
  638. package/src/shards/_template/data/director.json +39 -0
  639. package/src/shards/_template/data/encounters.json +96 -0
  640. package/src/shards/_template/data/items.json +172 -0
  641. package/src/shards/_template/data/layout.json +66 -0
  642. package/src/shards/_template/data/ledger.json +32 -0
  643. package/src/shards/_template/data/look.json +521 -0
  644. package/src/shards/_template/data/map.json +64 -0
  645. package/src/shards/_template/data/moves.json +16 -0
  646. package/src/shards/_template/data/placeholder.json +8 -0
  647. package/src/shards/_template/data/plumbing.json +32 -0
  648. package/src/shards/_template/data/quests.json +223 -0
  649. package/src/shards/_template/data/rows.json +423 -0
  650. package/src/shards/_template/data/skins.json +66 -0
  651. package/src/shards/_template/data/spawn.json +6 -0
  652. package/src/shards/_template/data/targets.json +150 -0
  653. package/src/shards/_template/data/text.json +12 -0
  654. package/src/shards/_template/data/ui.json +33 -0
  655. package/src/shards/_template/data/water.json +13 -0
  656. package/src/shards/_template/generators/behaviour.ts +34 -0
  657. package/src/shards/_template/generators/boss.ts +29 -0
  658. package/src/shards/_template/generators/buildOptions.ts +2 -0
  659. package/src/shards/_template/generators/cell.ts +224 -0
  660. package/src/shards/_template/generators/districts.ts +215 -0
  661. package/src/shards/_template/generators/farLook.ts +15 -0
  662. package/src/shards/_template/generators/generate.ts +27 -0
  663. package/src/shards/_template/generators/ground.ts +15 -0
  664. package/src/shards/_template/generators/kit.ts +69 -0
  665. package/src/shards/_template/generators/landscape.ts +59 -0
  666. package/src/shards/_template/generators/landscapeNoise.ts +62 -0
  667. package/src/shards/_template/generators/mapInputs.ts +10 -0
  668. package/src/shards/_template/generators/product.ts +100 -0
  669. package/src/shards/_template/generators/productOutput.ts +18 -0
  670. package/src/shards/_template/generators/props.ts +9 -0
  671. package/src/shards/_template/generators/templatePropsSource.ts +58 -0
  672. package/src/shards/_template/generators/terrain.ts +17 -0
  673. package/src/shards/_template/generators/world.ts +630 -0
  674. package/src/shards/_template/hero.json +10 -0
  675. package/src/shards/_template/look/entry-reads.json +20 -0
  676. package/src/shards/_template/manifest.json +281 -0
  677. package/src/shards/_template/shard.config.ts +10 -0
  678. package/src/shared/health.ts +10 -0
  679. package/src/tools/build-web.ts +59 -0
  680. package/src/tsconfig.json +30 -0
  681. package/src/web/app.tsx +53 -0
  682. package/src/web/index.html +12 -0
  683. package/src/web/main.tsx +10 -0
  684. package/src/web/tsconfig.json +13 -0
  685. package/tsconfig.author.json +23 -0
  686. package/tsconfig.commons.json +21 -0
  687. package/tsconfig.json +47 -0
  688. package/tsconfig.sharddev.json +20 -0
package/GUIDE.md ADDED
@@ -0,0 +1,895 @@
1
+ # The shard author's guide
2
+
3
+ > Written by: Claude
4
+
5
+ > **State:** living, 2026-11-13, sharddev `@wildshard/sdk` 0.2.x (SHARD-AUTHORING SA13). This file ships in the
6
+ > package and `wildshard new` copies it into every new project. Steps marked **not built yet** name the plan row
7
+ > (meta repo `docs/plans/SHARD-AUTHORING-PLAN.md`) that builds them; until then, do what that step says instead.
8
+
9
+ This guide is for people and agents making a Wildshard shard. Read sections 1 and 2 first; use the rest when you need
10
+ it. Facts that change with every release (each budget's number, each command's flags) are not copied here: each one
11
+ names the command or page that prints it. Only limits a decision fixed, such as the audio budget (J303), are written in.
12
+
13
+ **Words.** A **shard source** is your folder: data, generators, scripts and assets. **Build** turns the shard source
14
+ into a **shard file** (`<slug>.shardfile`), the one file you upload. **Bake** is the part of build that turns parts of
15
+ the shard source into data (maps, colliders, compiled scripts). **Upload** sends a shard file to the Wildshard API for a
16
+ **channel**, `--channel staging` or `--channel prod`; section 5 shows which of the three sites (preview, staging,
17
+ production) each one moves. The **hero** is the shard's card: three images (thumb, portrait,
18
+ landscape) shown on SHARD SELECT. A **budget** is a limit on what the shard costs a player (section 3). A **refusal**
19
+ is a command stopping with a rule id, a fix and a link into section 6.
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>`.
28
+
29
+ ## 1. The loop
30
+
31
+ The loop is: `new`, `dev`, `check`, `hero`, `upload --channel staging`, then `upload --channel prod`, then share the
32
+ link. Run each command from the project folder. `.` names the project: commands find its shard source at `src/` (or a
33
+ repo's one `src/shards/<slug>/`).
34
+
35
+ | # | Step | Command | Today |
36
+ |---|---|---|---|
37
+ | 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 |
39
+ | 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
+ | 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
+ | 7 | Upload to production | the same with `--channel prod` and a higher version | The same. Try staging first |
44
+ | 8 | Share | `https://staging.wildshard.io/slug/my-shard` | **Not built yet (SA36, SA37).** See section 5 |
45
+
46
+ `check` is the one verb to run after every change: it runs `build`, `validate` and `prove` for you. The one separate
47
+ `build` in the loop is `build <folder>` after `prepare`. Done when the last line reads `check pass in N s` (exit code
48
+ 0); `check fail` lists each refusal. `wildshard check . --json` prints one JSON document (verdict, steps, refusals
49
+ with `rule`, `fix` and `guide`) for agents and scripts.
50
+
51
+ ### Every verb
52
+
53
+ | Verb | What it is for |
54
+ |---|---|
55
+ | `wildshard new <dir> [slug] [--template sdk\|blender] [--empty]` | Start a shard repo in a folder that does not exist yet, its shard source at `src/`. The slug is the folder's name unless you give one. `--template sdk` (the default) copies the reference world; `--template blender` copies the hand-written Blender template (below); any other template refuses before writing. `--empty` writes a bare shard source instead of the reference world |
56
+ | `wildshard update [dir]` | Rewrite this guide and the four `wildshard` skills from the installed sdk, after you move to a newer one (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) |
58
+ | `wildshard check <source> [folder] [--json]` | The loop's check: lint, build, validate, prove, report card, verdict |
59
+ | `wildshard hero <source> --base <url>` | Capture the hero from a served build and stamp `hero.json`. `--stamp-existing` marks the images already there as current: only when you have looked at them and they show the current world |
60
+ | `wildshard upload <file> --channel staging\|prod` | Send a prepared shard file to the API (section 5) |
61
+ | `wildshard account <email>` | Make your account once and save its key, which upload sends (see "Uploading", step 5) |
62
+ | `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
+ | `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
+ | `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") |
66
+ | `wildshard validate <source \| folder>` | Shard-format's checks and the headless budget run, alone |
67
+ | `wildshard prove <source> <proof.json>` | Play a proof tape headlessly and print what happened |
68
+ | `wildshard synth <source>` | Run `shard.config.ts`'s scene exports and write the scene as data |
69
+ | `wildshard schema [list\|shardfile\|<root>] [pointer]` | Print the JSON Schema of the shard file, or of one section or field |
70
+ | `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) |
72
+ | `wildshard pack <folder>` | Old name for `wildshard build <folder>`; use `build` |
73
+
74
+ ### Walking your shard
75
+
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).
79
+
80
+ Until then there are two ways to walk a shard, and neither works from this folder alone:
81
+
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`).
89
+
90
+ ### The hero
91
+
92
+ The hero is three images: thumb 640x360, portrait 804x1626 and landscape 1600x900. `wildshard new` gives your shard a
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
+ hero:
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.
102
+
103
+ Build then refuses a shard file whose content changed after the hero was stamped (`hero-stale`), and upload refuses a
104
+ new version whose hero is the same as the previous version's (`hero-unchanged`). Section 6 has every hero refusal.
105
+
106
+ ### Uploading
107
+
108
+ An upload sends one shard file to the API (`https://api.wildshard.io`) and names its channel. Do these in order,
109
+ before every upload:
110
+
111
+ 1. **Hero.** A new version needs a new hero (J306). After your last change to the world, capture one
112
+ (`wildshard hero . --base <url>`, "The hero" above). Done when `hero.json` and the three card images are rewritten.
113
+ 2. **Commit.** Upload names the commit the bytes came from and refuses uncommitted changes to tracked files. The first
114
+ time: `git init`, then commit (the `.gitignore` `new` wrote keeps `public/shardfiles/` and `node_modules/` out).
115
+ Every time: commit everything, the hero included. Done when `git status` is clean.
116
+ 3. **Check.** `wildshard check .` builds the shard file. It is a **draft** (`sdk: "0.2"`): check prints a
117
+ `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.
123
+ 5. **Keys.** Set `WILDSHARD_API_URL=https://api.wildshard.io` (or pass `--server`) and
124
+ `WILDSHARD_CREATOR_PRIVATE_KEY`, the base64 creator key upload signs with. There is one Wildshard creator key and
125
+ no per-author creator keys yet: ask the Wildshard team for it, and never commit it. Upload also sends your
126
+ **account key**, which says whose shard it is: the first upload of a slug makes it yours, and nobody else's key can
127
+ upload to it. Make the account once with `wildshard account you@example.com`: it saves the key to
128
+ `~/.config/wildshard/sharddev-key` (only you can read it) and the API never shows it again, so keep that file. An
129
+ email that has an account already is refused (`account-exists`); a lost key needs an operator reset by the
130
+ Wildshard team. In CI, set `WILDSHARD_API_KEY` instead: it wins over the file. `wildshard whoami` says which key
131
+ upload will send and whose it is. Done when `wildshard whoami` prints `key wsk_…` and `account <your email>`.
132
+ 6. **Upload,** with a version `X.Y.Z` higher than the last one uploaded (`0.0.1` the first time). Upload reads
133
+ `version` from the repo's `package.json` (`new` writes `0.0.1`; raise it before each upload), or pass `--version`:
134
+
135
+ ```sh
136
+ wildshard upload public/shardfiles/my-shard.shardfile --channel staging --version 0.0.1
137
+ ```
138
+
139
+ Upload checks the shard file as the API will, checks the hero, signs, compresses and sends it, then prints the
140
+ version and what moved. Uploading the same bytes again sends nothing.
141
+
142
+ ### Deleting a shard
143
+
144
+ `wildshard delete my-shard` deletes a shard you uploaded, with the same account key: only the key that first uploaded
145
+ a slug can delete it. It makes two calls to the API, with you in between:
146
+
147
+ 1. **Start.** It prints what the delete touches: the shard's versions, the channels pointing at it, the grid cells
148
+ placing it, and a plain line saying whether a signed release still plays it. A shard a live release plays can still be deleted: that release
149
+ keeps its copy until its next release.
150
+ 2. **Type the slug.** Type `my-shard` and press Enter. Anything else deletes nothing (`delete-not-confirmed`). You
151
+ have 10 minutes; after that the confirmation lapses and you start again (`delete-expired`).
152
+ 3. **Finalize.** The shard leaves the catalogue, every channel and the grid at once, and its grid cell is freed
153
+ for the next new shard. Its downloads stop after the daily prune, once no signed release names it.
154
+
155
+ In a script, `wildshard delete my-shard --yes` skips the typing. A deleted slug stays yours: uploading a new version
156
+ of it with your key brings it back, on preview only. Done when the last line starts `deleted my-shard at`.
157
+
158
+ ## 2. The shard source
159
+
160
+ A project made by `wildshard new` is a repo with one shard source at `src/`. Inside `src/`:
161
+
162
+ | Path | What it is | Ships in the shard file? |
163
+ |---|---|---|
164
+ | `shard.config.ts` | The build entry: exports `generate` (default) and `buildOptions`. Build runs it | No: its output does |
165
+ | `data/` | JSON rows: identity (`data/identity.json`, the slug), card, layout, creatures, items, quests, text, audio, look, budgets (`data/budgets.json`) | As baked sections, never as code |
166
+ | `generators/` | TypeScript that runs at build time (any Node package, J319) to make terrain, props, maps and sections | No: what they produce does |
167
+ | `behaviour/` | AssemblyScript (`.as`) scripts and `hooks.json`. Build compiles them to Wasm | The compiled Wasm |
168
+ | `assets/` | Source assets, named by their SHA-256 | The ones the shard uses, by hash |
169
+ | `look/` | Recorded entry reads for the build | No |
170
+ | `manifest.json` | The card and discovery fields: name, `card` images, `shardfile` path | The card, as data |
171
+ | `hero.json` | The hero stamp (`wildshard hero` writes it) | No |
172
+ | `proof.json` | Optional: a proof tape `check` plays with `prove` | No |
173
+ | `audio-waiver.json` | Optional: a dated waiver for the audio budget | Into the shard file's admission data |
174
+
175
+ At the repo root, around `src/`:
176
+
177
+ | Path | What it is | Ships in the shard file? |
178
+ |---|---|---|
179
+ | `package.json` | Pins `@wildshard/sdk`, shard-format, engine and `three` exactly, and pnpm 10.34.9 (`packageManager`); its `version` is what upload sends | No |
180
+ | `tsconfig.json`, `.npmrc`, `.gitignore` | TypeScript settings for `src/`; exact versions for `pnpm add`; what git leaves out (build output, `node_modules/`) | No |
181
+ | `README.md`, `GUIDE.md` | This repo's README, and this guide | No |
182
+ | `pnpm-workspace.yaml` | pnpm's install-script allowlist (SA39): a dependency's install script runs only if listed | No |
183
+ | `.claude/skills/wildshard*/SKILL.md` | The `wildshard` skill (SA14): the loop's order for Claude Code, pointing into this guide; and its siblings (SA27): `wildshard-mockup-to-model` (a picture to a model), `wildshard-goldens` (refresh the hero and proof tape), `wildshard-upgrade` (move to a newer sdk). `wildshard update` rewrites them: never edit them | No |
184
+ | `.agents/skills/wildshard*` | Links to the four `.claude/skills/` folders, so Codex lists the same skills | No |
185
+ | `AGENTS.md`, `CLAUDE.md` | For agents: read this guide first; the skills are in `.claude/skills/`. `CLAUDE.md` is `@AGENTS.md`, so Claude Code reads the same file. Yours to change: `update` keeps your edits | No |
186
+ | `public/shardfiles/` | Build output: the built folder and `<slug>.shardfile`. Never edit; never commit | It is the shard file |
187
+
188
+ **Two files to change together.** `src/manifest.json` and `src/data/card.json` hold the same card: `new` writes
189
+ both, build refuses a shard whose two copies differ, and hero capture reads `manifest.json`, so change both together.
190
+
191
+ Blender files (`.blend`), mockups and other working files never ship: keep them in a folder of your own, such as
192
+ `blender/`, and export what the shard needs into `assets/`. A shard never ships runtime TypeScript: everything that
193
+ runs in the game is data, or Wasm compiled from `behaviour/`. `shard.config.ts` and `generators/` run only at build
194
+ time; lint refuses runtime code there (section 6).
195
+
196
+ **Repo layout (J317).** A repo with one shard keeps its shard source at `src/` (`src/shard.config.ts`,
197
+ `src/data/`, ...); a repo with several keeps `src/shards/<slug>/`. Commands take the repo (`.`) and find the shard
198
+ source at `src/`, or at the one `src/shards/<slug>/` a repo holds; in a repo with several, name the shard source
199
+ (`src/shards/<slug>`). The slug is `manifest.json`'s, whatever the repo folder is called. A `src/` source builds
200
+ into the repo's `public/shardfiles/`; a `src/shards/<slug>/` source into its own folder's. SA24 moves the existing
201
+ single-shard repos to `src/`.
202
+
203
+ **The hand-written template (`--template blender`).** shard-format's `blender-template`: no sdk at runtime, no
204
+ three.js, no `shard.config.ts`. Its `src/` is a shard file folder held by hand: `shard.json` (the index),
205
+ `sections/` (the JSON you edit), `blobs/` (baked files, Blender models among them, each named by its SHA-256),
206
+ `mounts/` (what the boot reads first, with its receipt) and `validation.json`. `check` lint skips it (no code); its
207
+ build runs shard-format's `shard-format pack`, which settles every hash and size the sections measure and validates
208
+ the whole folder, then writes the built folder and shard file as any build does. A changed blob is a new file under
209
+ its new hash, with every row that names it changed to match. `package.json` lists only `@wildshard/sdk` (the CLI) and
210
+ shard-format, as dev dependencies; there is no `tsconfig.json`.
211
+
212
+ **What a shard may declare.** The runtime contract lists every section, `client/plan` kind, named file, script rule,
213
+ budget and limit a shard file may carry, and what validation refuses:
214
+ [shard-format `docs/RUNTIME-CONTRACT.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/RUNTIME-CONTRACT.md).
215
+ Read with it [`SHARDFILE.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/SHARDFILE.md) (the
216
+ fields), [`SCRIPT-ABI.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/SCRIPT-ABI.md) (the Wasm
217
+ scripts) and [`PLATFORM-FILE-FAMILIES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/PLATFORM-FILE-FAMILIES.md)
218
+ (the named files). `wildshard schema list` prints the section roots from your installed copy.
219
+
220
+ ## 3. Budgets
221
+
222
+ A budget is a limit on what your shard costs a player's phone or desktop: bytes to download, memory, draw calls,
223
+ triangles, script time and audio. Build measures the shard, and the **report card** compares each cost with its limit.
224
+ A cost over a hard limit is a refusal; one over a soft line is a warning. The numbers change with releases, so this
225
+ guide names them and points at what prints them:
226
+
227
+ | Budget | What it limits | Checked by | Where the numbers are |
228
+ |---|---|---|---|
229
+ | Download | Bytes before the shard is playable (critical) and in all (library) | `check` (report), `build`, `validate` | `wildshard check .` prints "N MB download, ~S s to playable"; RUNTIME-CONTRACT §6 |
230
+ | Draws, triangles | Draw calls and triangles in the near and far views | `check` (report) | The report step's refusals: `metric: actual over limit` |
231
+ | Memory | Resident, loading and playing bytes | `check` (report) | Report only for now: printed, not refused (RUNTIME-CONTRACT §6) |
232
+ | Script CPU and fuel | Time and instructions per tick of your Wasm scripts | `check` (report), from a headless run | The report step; SCRIPT-ABI.md |
233
+ | Frame targets | fps and per-system milliseconds per device | The running game reports against them; `check` does not | Your `data/budgets.json` |
234
+ | Server | Tick time, memory, entities, commands per tick | `validate` | `shard.json` `admission.serverBudget`; RUNTIME-CONTRACT §6 |
235
+ | Audio | Your shard's own recordings: green to 6 MB, amber 6 to 10 MB, red over 10 MB (J303) | `build` and `upload` | `check` prints "audio green: ... MB"; shard-format `docs/audio.md` |
236
+ | File limits | Sizes and counts: source bytes, files, ids, text, Wasm modules | `validate`, `upload` | RUNTIME-CONTRACT §7 |
237
+
238
+ `wildshard check . --json` is the one place to read them for your shard: the `report` step's `note` and each refusal's
239
+ `message` carry the measured value and its limit. Shard-format's codes for every budget finding are in
240
+ [`docs/VALIDATION-CODES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/VALIDATION-CODES.md)
241
+ (sections "performance" and "audio"). Section 6 says what to do when one refuses.
242
+
243
+ ## 4. What reloads under `dev`
244
+
245
+ `wildshard dev` is **not built yet** for an installed sdk (SA15); this is how it behaves once it runs.
246
+
247
+ - **Every saved file in the shard source rebuilds the whole shard**, about 0.1 s after the last save, and the open page
248
+ reloads itself when the new build is ready. Nothing is patched in place: data, generators, behaviour scripts,
249
+ assets, `shard.config.ts` and `manifest.json` all take the same path.
250
+ - **A failed rebuild keeps the last good build** on the page and prints the refusal in the terminal and the browser
251
+ console. Fix it and save again.
252
+ - **Not watched:** `node_modules/`, `.git/`, `dist/`, `public/` and `.worktrees/`. After `pnpm install` or an sdk
253
+ update, stop `dev` and start it again.
254
+ - **Not made by `dev`:** a shard file to upload. `dev` builds a private copy for the page. Run `wildshard check .`
255
+ for the shard file, and capture the hero again before you upload a changed world.
256
+
257
+ ## 5. Channels and the grid
258
+
259
+ **Channels (J301).** Every upload names one:
260
+
261
+ | `--channel` | preview (`preview.wildshard.io`) | staging (`staging.wildshard.io`) | production (`play.wildshard.io`) |
262
+ |---|---|---|---|
263
+ | `staging` | moves to this version | moves to this version | stays |
264
+ | `prod` | moves | moves | moves |
265
+
266
+ There is no default: upload without `--channel` refuses. Upload to staging; once the Wildshard team has placed the
267
+ shard (below), walk it there; then upload the next version with `--channel prod`. The same bytes cannot go to staging
268
+ and then to prod: production needs a new version, and a new version needs a new hero (J306).
269
+
270
+ **The grid.** The world is a grid of cells, one shard per cell, and players walk from cell to cell. Today it is 5×5,
271
+ and only the Wildshard team places a shard on it. An uploaded shard with no cell is recorded on its channels, but no
272
+ player can reach it there yet.
273
+
274
+ **What upload says about the grid (SA32).** After the `committed:` line, upload prints one grid line, then the
275
+ `/slug/<slug>` link on each channel it moved:
276
+
277
+ | Grid line | Means |
278
+ |---|---|
279
+ | `placed at (0,3) on preview, staging` | The shard's cell, and the channels whose grid has it |
280
+ | `grid full, not placed` | Every cell is taken; the upload still counts, and the Wildshard team is told |
281
+ | `not placed (--no-place)` | You passed `--no-place` on the shard's first upload |
282
+ | `grid left as it was (--no-place)` | You passed `--no-place` on a later upload: a cell the shard has stays, and is not added to a new channel |
283
+ | `not placed: the grid step failed; run the same upload again to retry` | The upload counts; the same `wildshard upload` again places it |
284
+ | `no new cell: grid placement is off on the API, or this is not the shard's first upload` | Today's answer: the API does not place yet (below); or the shard had an upload before and no cell |
285
+
286
+ `wildshard upload --no-place` uploads without taking a cell, for a proof upload you will delete. Only a shard's
287
+ first upload can take a cell, so a shard uploaded with `--no-place` never gets one from a later upload. The links
288
+ point at the share page, which is not built yet (below), and each says `(page not built yet)`.
289
+
290
+ **Not built yet:**
291
+
292
+ - **The 7×7 grid that fills itself (J314; SA29 to SA35).** A brand-new slug's first upload will get the nearest free
293
+ cell in the outer ring, and that cell is the slug's for life, on every channel it reaches: a staging upload places
294
+ it on preview and staging, and a later prod upload puts it at the same cell on production. The API side is built
295
+ but switched off until the MMO server and the play page can show a new cell; upload already prints its answer.
296
+ - **The share link (SA36, SA37):** `https://staging.wildshard.io/slug/<slug>` (and the same path on preview and
297
+ production) will show your shard's name and hero with a Play button that spawns you at its cell, and unfurl with
298
+ the hero when pasted into a chat. A shard with no cell shows its card with Play off: "not on the grid yet".
299
+
300
+ **How to share today:** there is no per-shard link yet. Once the Wildshard team has placed your shard, share
301
+ `https://staging.wildshard.io` and its cell; until then, share the hero images and the shard file.
302
+
303
+ ## 6. Refusals and their fixes
304
+
305
+ Every refusal prints the refusing code's own words, then one line:
306
+
307
+ ```text
308
+ [<rule>] fix: <what to do> (GUIDE.md#<rule's heading>)
309
+ ```
310
+
311
+ `wildshard check . --json` carries the same `rule`, `fix` and `guide` on each refusal. The headings below are those
312
+ links, one per rule. The printed `fix` is the short answer; each heading adds why. Shard-format's own refusals also
313
+ carry a stable code, listed in
314
+ [`docs/VALIDATION-CODES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/VALIDATION-CODES.md);
315
+ the rule is chosen by that code, and each heading below that one names lists its codes.
316
+
317
+ ### Any command
318
+
319
+ #### usage
320
+
321
+ A verb got arguments or flags it does not take. `wildshard <verb> --help` prints what it takes.
322
+
323
+ ### New
324
+
325
+ #### new-target
326
+
327
+ `new` needs a folder that does not exist yet and a kebab-case slug (`my-shard`, not `My Shard`). It never writes into
328
+ an existing folder.
329
+
330
+ #### new-template
331
+
332
+ `--template` names `sdk` (the reference world, the default) or `blender` (the hand-written Blender template). Any
333
+ other name refuses before `new` writes anything. Leave the flag out or pass `--template sdk` or `--template blender`.
334
+
335
+ #### new-refused
336
+
337
+ `new` could not copy the reference world shipped with the sdk. Reinstall the sdk.
338
+
339
+ ### Update
340
+
341
+ #### update-target
342
+
343
+ `update` works on a shard repo: a folder whose `package.json` lists `@wildshard/sdk`, as `new` writes it. Run it in
344
+ that folder, or name it: `wildshard update my-shard`.
345
+
346
+ #### update-pins
347
+
348
+ `wildshard update --pins` (SA18) is not built yet. Move the pins by hand as the `wildshard-upgrade` skill says, then
349
+ run `wildshard update` with no flag.
350
+
351
+ #### update-refused
352
+
353
+ `update` could not copy this guide or a skill from the installed sdk. Reinstall the sdk (`pnpm install`).
354
+
355
+ ### Build
356
+
357
+ #### source-file-missing
358
+
359
+ A path the command was given, or a file the shard source names, is not there. Check the path in the message.
360
+
361
+ #### source-import-missing
362
+
363
+ An import in `shard.config.ts`, `generators/` or `data/` names a file or package that is not there. Fix the path, or
364
+ add the package to `package.json` and install.
365
+
366
+ #### json-syntax
367
+
368
+ A JSON file in the shard source does not parse. The message gives the line and column.
369
+
370
+ #### source-syntax
371
+
372
+ A TypeScript or AssemblyScript file does not parse. The message gives the file and line.
373
+
374
+ #### config-default-export
375
+
376
+ `shard.config.ts` must default-export its `generate` function, as `new` wrote it.
377
+
378
+ #### config-file-access
379
+
380
+ Code that `shard.config.ts` imports read a file with `node:fs`. Read files through the build context (`ctx.cached`),
381
+ so build knows the input and can cache it.
382
+
383
+ #### project-folder-slug
384
+
385
+ The shard source's folder name and its slug (`data/identity.json`) differ. Rename one to match the other.
386
+
387
+ #### source-schema
388
+
389
+ A field in your data does not have the shape the shard file needs. The message gives the path;
390
+ `wildshard schema shardfile <pointer>` prints the expected shape.
391
+
392
+ #### build-refused
393
+
394
+ Build stopped for a reason no rule above names. Read the message: it names the file, field or generator. Fix it and
395
+ run `wildshard check .` again.
396
+
397
+ ### Validate
398
+
399
+ #### validate-refused
400
+
401
+ Shard-format's checks refused the built shard. The message names the check; RUNTIME-CONTRACT §8 lists what is refused.
402
+ If a fresh, unedited build still fails, report it with the message.
403
+
404
+ ### Prove
405
+
406
+ #### proof-tape-invalid
407
+
408
+ `proof.json` does not have the proof tape's shape. Fix it where the message says.
409
+
410
+ #### proof-failed
411
+
412
+ The tape played, but a step it expected did not happen. Fix the data, or the tape step.
413
+
414
+ ### Budgets
415
+
416
+ Each of these is the report card naming a budget over its limit (section 3). The message gives the measured value and
417
+ the limit.
418
+
419
+ #### budget-unmeasured
420
+
421
+ A cost could not be measured: too few headless ticks for scripts, or native gameplay that needs a browser run. Codes
422
+ `perf-native-view-unmeasured`, `perf-native-resident-unmeasured`, `perf-script-sample-invalid`,
423
+ `perf-script-samples-missing`.
424
+
425
+ #### budget-download
426
+
427
+ Too many bytes to download, before play (critical) or in all (library). Shrink or drop assets, or load them later.
428
+ Codes `perf-library-download-budget`, `perf-critical-download-budget`, `perf-library-download`,
429
+ `perf-critical-download`, `perf-tile-download`, `perf-far-download`.
430
+
431
+ #### budget-draws
432
+
433
+ Too many draw calls in a view. Merge meshes that share a material, or show fewer objects from that view. Codes
434
+ `perf-tile-draws`, `perf-far-draws`.
435
+
436
+ #### budget-triangles
437
+
438
+ Too many triangles in a view. Use lower-detail meshes or fewer props there. Codes `perf-tile-triangles`,
439
+ `perf-far-triangles`.
440
+
441
+ #### budget-memory
442
+
443
+ A memory total is over its line. Smaller or fewer textures and meshes. Memory reports only, for now. Codes
444
+ `perf-memory-target`, `perf-playing-memory`, `perf-loading-memory`.
445
+
446
+ #### budget-script-cpu
447
+
448
+ Behaviour scripts take too long per tick. Spread work over ticks, or run it on events. Code `perf-script-cpu`.
449
+
450
+ #### budget-script-fuel
451
+
452
+ Behaviour scripts run too many instructions per tick. Shorten the hottest loops. Code `perf-script-fuel`.
453
+
454
+ #### budget-over
455
+
456
+ A budget not named above is over its limit. The message names it; `wildshard check . --json` lists each.
457
+
458
+ #### budget-refused
459
+
460
+ Build or validate refused the whole report card. Run `wildshard check .`: its report step names each budget over.
461
+ Codes `declared-costs`, `performance-targets` (shard-format checking the costs the shard file declares).
462
+
463
+ ### The shard file and the hero
464
+
465
+ #### hero-stale
466
+
467
+ The shard's content changed after its hero was captured, or the card names images `hero.json` has no stamp for. The
468
+ hero must show the current world: capture it again (`wildshard hero . --base <url>`). Only if the images already show
469
+ the current world, `wildshard hero . --stamp-existing`.
470
+
471
+ #### hero-not-in-product
472
+
473
+ The shard file does not carry the captured hero: it was built before the capture. Run `wildshard check .`, then
474
+ prepare again ("Uploading", steps 3 and 4).
475
+
476
+ #### hero-unchanged
477
+
478
+ Upload only: this new version's hero is the same as the previous version's (J306: a new version needs a new hero).
479
+ Capture a new hero, build, prepare and upload again.
480
+
481
+ #### audio-refused
482
+
483
+ The audio rules found a red problem: a recording that will not play, runs too long, or a shard over 10 MB of its own
484
+ audio. Fix each red finding, or add a dated waiver in `audio-waiver.json`. Shard-format `docs/audio.md` explains each.
485
+ Code `audio-refused`. Build prints every finding with one of the rules below under it; only upload refuses a red one.
486
+
487
+ #### audio-unreadable
488
+
489
+ Red. The recording does not read as AAC-LC at 48 kHz, mono or stereo. Export it again in that form. Code
490
+ `audio-unreadable`.
491
+
492
+ #### audio-container
493
+
494
+ Red. The recording's bytes are FLAC, AIFF, Ogg, MP3, WebM, CAF or no container the game knows; it still counts toward
495
+ the audio budget. Export it again as AAC (in an mp4 file) or as WAV. Code `audio-container`.
496
+
497
+ #### audio-encoding
498
+
499
+ Amber. The recording plays, but it is PCM WAV, AAC at a sample rate other than 48 kHz, or AAC outside the strict
500
+ playback index. Encode it as AAC-LC at 48 kHz. Codes `audio-wav`, `audio-sample-rate`, `audio-strict-index`.
501
+
502
+ #### audio-duration
503
+
504
+ Red. The recording runs longer than the maximum the message gives. Cut it, or split it in two. Code `audio-duration`.
505
+
506
+ #### audio-bitrate
507
+
508
+ Amber. The recording's bitrate is over the cap for its role (music or sound effect) and channels. Encode it lower.
509
+ Code `audio-bitrate`.
510
+
511
+ #### audio-budget
512
+
513
+ The shard's own audio is over the amber line (amber), over the red line (red), or over the red line with a dated
514
+ waiver that holds (amber). Cut, shorten or re-encode recordings, or add a waiver in `audio-waiver.json`. Codes
515
+ `audio-budget-amber`, `audio-budget-red`, `audio-budget-waived`.
516
+
517
+ #### audio-waiver
518
+
519
+ Amber. `audio-waiver.json` names another shard, has expired, or covers fewer bytes than the shard holds, so it does
520
+ not hold; the budget finding after it says what that leaves. Code `audio-waiver-invalid`.
521
+
522
+ #### shardfile-draft
523
+
524
+ A warning from `build` and `check`, a refusal from `upload`: the shard file is a draft (`sdk: "0.2"`). Prepare it
525
+ first ("Uploading", step 1).
526
+
527
+ #### shardfile-link
528
+
529
+ The built folder holds a symbolic link; a shard file holds only real files. Replace the link, then check and prepare
530
+ again ("Uploading", steps 3 and 4).
531
+
532
+ #### shardfile-folder-missing
533
+
534
+ There is no built folder to write a shard file from. Run `wildshard check .` (or `wildshard build .`) first.
535
+
536
+ #### shardfile-invalid
537
+
538
+ The shard file breaks a format check: it is not a tarball shard-format can read. Upload the shard file `prepare` and
539
+ `build <folder>` wrote, unedited. Code `archive-invalid`.
540
+
541
+ #### shardfile-index
542
+
543
+ `shard.json` is missing, too large, not canonical JSON, or does not fit the index schema. Build again so it is written
544
+ for you; a hand-written shard file's `shard.json` must parse and fit. Code `index-invalid`.
545
+
546
+ #### shardfile-files
547
+
548
+ The files in the folder differ from the ones `shard.json` lists: one is missing, changed or a link, one is not listed,
549
+ a pack lacks a member, or the sections differ from the source hash. Something edited the built folder: build again.
550
+ Codes `file-mismatch`, `unlisted-file`, `source-hash`, `pack-invalid`.
551
+
552
+ #### shardfile-section
553
+
554
+ A section, or the whole shard file the sections make, does not fit its schema. The message gives the path;
555
+ `wildshard schema shardfile <pointer>` prints the expected shape. Codes `section-invalid`, `shard-schema`.
556
+
557
+ #### shardfile-assets
558
+
559
+ An asset's bytes do not match what the shard file declares (its kind, extension, schema, size or costs), or fail
560
+ the asset checks, or a mount or runtime file is wrong. Export the named asset again and build. Codes `blob-invalid`,
561
+ `server-file-invalid`, `ktx2-costs`, `asset-admission`, `cook-invalid`, `runtime-files`.
562
+
563
+ #### shardfile-scripts
564
+
565
+ A behaviour script runs on a side (client or server) its declaration does not allow, or the script rows are
566
+ invalid. Fix the declaration or move the script, then build again. Codes `script-side`, `script-admission`.
567
+
568
+ #### shardfile-targets
569
+
570
+ The world targets name an item or quest the shard does not declare. Declare it, or take it out. Code `world-targets`.
571
+
572
+ #### shardfile-stream
573
+
574
+ Upload's streaming check refused: a file, pack or the placed assets are over the streaming cap, or the stored file
575
+ changed while it was read. Shrink what the message names; if it changed mid-read, upload again. Codes `stream-cap`,
576
+ `stream-miss`, `stream-changed`.
577
+
578
+ #### shardfile-refused
579
+
580
+ Writing or checking the shard file failed for another reason. Check and prepare again ("Uploading", steps 3 and 4).
581
+
582
+ ### Upload
583
+
584
+ Upload checks all of these before a byte is sent.
585
+
586
+ #### upload-shardfile-missing
587
+
588
+ The path is not a shard file. Pass the one build wrote: `public/shardfiles/<slug>.shardfile`.
589
+
590
+ #### upload-channel
591
+
592
+ No `--channel`, or one that is not `staging` or `prod` (section 5).
593
+
594
+ #### upload-credentials
595
+
596
+ `WILDSHARD_API_URL` (or `--server`) or `WILDSHARD_CREATOR_PRIVATE_KEY` is not set ("Uploading", step 5).
597
+
598
+ #### upload-level
599
+
600
+ `--level` is the compression level, 0 to 11. Leave it out for the default.
601
+
602
+ #### upload-version
603
+
604
+ No version: set `version` (X.Y.Z) in `package.json`, or pass `--version X.Y.Z`, higher than the last one uploaded.
605
+
606
+ #### upload-commit
607
+
608
+ The shard source is not in a git checkout, or `--commit` is not a full 40-character sha. Upload names the commit
609
+ its bytes came from.
610
+
611
+ #### upload-uncommitted
612
+
613
+ Tracked files have uncommitted changes. Commit, then check and prepare again before you upload ("Uploading").
614
+
615
+ #### upload-sdk-missing
616
+
617
+ Upload could not find the sdk, engine or shard-format version to send. Install the project's packages.
618
+
619
+ #### upload-refused
620
+
621
+ The API refused, or a check no rule above names. The message says what it wants: a format refusal means check and
622
+ prepare again; a server refusal (409 or 422) names the field, the version or the hero.
623
+
624
+ ### Account
625
+
626
+ The account key upload sends ("Uploading", step 5), `wildshard account` and `wildshard whoami`.
627
+
628
+ #### account-key-missing
629
+
630
+ Upload found no account key: `WILDSHARD_API_KEY` is unset and `~/.config/wildshard/sharddev-key` is not there. It
631
+ refuses before anything is sent, because the API refuses an upload with no key. Run `wildshard account <email>` once,
632
+ or set `WILDSHARD_API_KEY`.
633
+
634
+ #### account-exists
635
+
636
+ That email has an account already, and the API shows a key only once, when the account is made. Use the key you
637
+ saved for it. A lost key stays lost until the Wildshard team resets it.
638
+
639
+ #### account-key-file
640
+
641
+ `~/.config/wildshard/sharddev-key` already holds a key, and `account` never overwrites one by accident: you would lose
642
+ the key to an account you made. Keep it, or pass `--force` to replace the file; the old key keeps working.
643
+
644
+ #### account-refused
645
+
646
+ The API refused the account for another reason: a malformed email is 400, and more than five tries a minute is 429
647
+ (wait a minute).
648
+
649
+ ### Delete
650
+
651
+ `wildshard delete <slug>` ("Deleting a shard"). No account key refuses before anything is sent
652
+ (`account-key-missing`, above).
653
+
654
+ #### delete-not-confirmed
655
+
656
+ You typed something other than the slug, or nothing, so the delete was not finalized and nothing changed. Run it
657
+ again and type the slug exactly; in a script, pass `--yes`.
658
+
659
+ #### delete-expired
660
+
661
+ The confirmation from the start call was spent, or its 10 minutes passed, so finalize changed nothing. Run
662
+ `wildshard delete <slug>` again and type the slug within 10 minutes.
663
+
664
+ #### delete-not-owner
665
+
666
+ The key you sent does not own this shard: only the account whose key first uploaded a slug can delete it (the
667
+ Wildshard team can delete any shard). `wildshard whoami` shows which key you send. A 401 means the API does not know
668
+ the key at all.
669
+
670
+ #### delete-unknown
671
+
672
+ The API has no shard by that slug (404), or the slug is not a valid one (400). Check its spelling against the
673
+ catalogue.
674
+
675
+ #### delete-refused
676
+
677
+ The API refused for another reason, or `--server` is not https (the key goes only to https or localhost). The
678
+ message says which.
679
+
680
+ ### Lint
681
+
682
+ `check` lints the shard source with the sdk's rules. Each wildshard lint rule keeps a shard to data and build-time
683
+ code; its printed fix says what to change.
684
+
685
+ #### lint-not-run
686
+
687
+ The linter that ships with the sdk did not run. Reinstall the sdk.
688
+
689
+ #### lint-refused
690
+
691
+ A lint finding with no rule of its own. Fix what it names at the file and line shown.
692
+
693
+ #### lint-rules
694
+
695
+ A lint rule that is not Wildshard's own (oxlint's built-in rules). Its own help line is printed as the fix.
696
+
697
+ #### lint-generator-imports
698
+
699
+ An import the rule denies. In `generators/` any npm package, valibot, shard-format and `node:*` are fine (J319); the
700
+ rule denies engine, sdk paths outside its exports, another shard's source and a second copy of `three`. In `data/` and
701
+ `shard.config.ts` only `three`, valibot, shard-format, the sdk and Node built-ins are allowed.
702
+
703
+ #### lint-engine-internal
704
+
705
+ Shard code imports a game-only engine export; use the sdk's shard-facing one.
706
+
707
+ #### lint-engine-sides
708
+
709
+ Client and server code are mixed; import the shared module instead.
710
+
711
+ #### lint-engine-words
712
+
713
+ Shard and game names belong in content data, not in engine code.
714
+
715
+ #### lint-exec-max-buffer
716
+
717
+ An exec call that captures output needs an explicit `maxBuffer`.
718
+
719
+ #### lint-layer
720
+
721
+ An import reaches upward or into another shard; import through the public index.
722
+
723
+ #### lint-no-active-chunk
724
+
725
+ Read current content through the game layer, not the active chunk.
726
+
727
+ #### lint-no-active-singleton
728
+
729
+ Take the service from your context, not a global singleton.
730
+
731
+ #### lint-no-authored-html
732
+
733
+ Set text with `textContent`, never HTML.
734
+
735
+ #### lint-no-base64
736
+
737
+ Binary content stays binary: ship bytes as an asset, never base64 text.
738
+
739
+ #### lint-no-build-time-import
740
+
741
+ Runtime code imports build-time code. Move the shared part into a runtime module.
742
+
743
+ #### lint-no-client-plan-reflection
744
+
745
+ Pass data to a client feature; never reflect into shard TypeScript.
746
+
747
+ #### lint-no-generated-import
748
+
749
+ Do not import a generated file; call the function that makes it, or read the built folder.
750
+
751
+ #### lint-no-generated-json-import
752
+
753
+ Read generated JSON as data at build time, not through an import.
754
+
755
+ #### lint-no-global-listener-patch
756
+
757
+ Register listeners through your scope, not on globals.
758
+
759
+ #### lint-no-hook-chain
760
+
761
+ Subscribe to the typed event instead of chaining hooks.
762
+
763
+ #### lint-no-inline-ui-string
764
+
765
+ Player-facing text goes in the string table, `data/text.json`.
766
+
767
+ #### lint-no-level-identity
768
+
769
+ Put level and style choices in data instead of branching on the shard's identity.
770
+
771
+ #### lint-no-module-mock
772
+
773
+ Test through a seam (pass the dependency in), not a module mock.
774
+
775
+ #### lint-no-production-test-import
776
+
777
+ Production code imports a test module. Move what it needs out of the test.
778
+
779
+ #### lint-no-raw-animation-mixer
780
+
781
+ Use the engine's animation API, not a raw three.js mixer.
782
+
783
+ #### lint-no-raw-hud
784
+
785
+ Mount HUD through the numbered HUD slots your scope owns.
786
+
787
+ #### lint-no-raw-input
788
+
789
+ Read input through the input service, not DOM listeners.
790
+
791
+ #### lint-no-raw-random-time
792
+
793
+ Use the engine's seeded random and clock, never `Math.random` or `Date`: the game must replay the same way.
794
+
795
+ #### lint-no-raw-save
796
+
797
+ Save through the saves service, not `localStorage`.
798
+
799
+ #### lint-no-raw-shader-patch
800
+
801
+ Patch shaders through the shader registry.
802
+
803
+ #### lint-no-reexport
804
+
805
+ Import a name from the module that defines it; do not re-export it.
806
+
807
+ #### lint-no-renderer-type
808
+
809
+ Renderer types stay inside rendering code; pass plain data out.
810
+
811
+ #### lint-no-runtime-generator
812
+
813
+ Generators run at build time only: import them from `shard.config.ts`, bakers and other generators.
814
+
815
+ #### lint-no-runtime-in-build
816
+
817
+ Build code imports runtime code. Share a plain data module instead.
818
+
819
+ #### lint-no-shard-branch
820
+
821
+ A shard-specific choice belongs in the shard's data, not a branch on its name.
822
+
823
+ #### lint-no-shard-host-callback
824
+
825
+ Give host APIs data, not TypeScript callbacks: a shard file carries no code engine runs.
826
+
827
+ #### lint-no-shard-runtime
828
+
829
+ The shard source holds authoring and declarations; gameplay goes in `behaviour/` scripts.
830
+
831
+ #### lint-no-url-switch
832
+
833
+ No URL query switches; read settings from the shard's data.
834
+
835
+ #### lint-public-index
836
+
837
+ Import a package by its public export, not a file path inside it.
838
+
839
+ #### lint-runtime-commons
840
+
841
+ Runtime code imports build-time commons; use the runtime export.
842
+
843
+ #### lint-runtime-performance
844
+
845
+ Runtime code must bound its work: no per-frame allocation, raw rendering, DOM, timers or fetch.
846
+
847
+ #### lint-runtime-standalone
848
+
849
+ Runtime code imports only the runtime surface.
850
+
851
+ #### lint-sdk-no-facade
852
+
853
+ Import the sdk's own export; do not alias a game or engine binding.
854
+
855
+ #### lint-shard-engine-imports
856
+
857
+ Shard source imports `@wildshard/sdk`, never engine internals (J158).
858
+
859
+ #### lint-shard-game-imports
860
+
861
+ Shard source imports `@wildshard/sdk`, never the game.
862
+
863
+ #### lint-shard-game-plugins
864
+
865
+ Import only the game plugin exports that define your runtime.
866
+
867
+ #### lint-shard-names
868
+
869
+ Name no other shard outside its own folder.
870
+
871
+ #### lint-shard-sandbox
872
+
873
+ Services, globals, settings and assets stay inside the shard's context.
874
+
875
+ #### lint-shard-services
876
+
877
+ Get engine services from `ShardContext`.
878
+
879
+ #### lint-sim-no-render
880
+
881
+ Code the headless simulation imports must not render.
882
+
883
+ ## 7. `wildshard update`
884
+
885
+ `wildshard update` (or `wildshard update <dir>`) rewrites this guide and the four `wildshard` skills in
886
+ `.claude/skills/` from the installed sdk, and prints each file it wrote. Run it after you move to a newer sdk; the
887
+ `wildshard-upgrade` skill walks the whole move. It touches nothing else: your shard source, `package.json`, README and
888
+ every other file stay as they are. It adds the `.agents/skills/` links, `AGENTS.md` and `CLAUDE.md` only if one is
889
+ missing, and it leaves an `AGENTS.md` or `CLAUDE.md` you changed and says so (`left AGENTS.md: you changed it`). So
890
+ keep your own notes for agents in `AGENTS.md`, never in this guide or a skill: `update` rewrites those. Done when it
891
+ prints `already up to date` or the files it wrote, and `git status` shows only `GUIDE.md`, `.claude/skills/` and any
892
+ agent file it added.
893
+
894
+ `wildshard update --pins` (SA18) is not built yet: it will also move the sdk, shard-format and `three` versions,
895
+ install, apply the release's code changes and run the build.