@wildshard/sdk 0.0.1 → 0.2.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 (687) hide show
  1. package/GUIDE.md +790 -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 +46 -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 +24 -0
  358. package/src/cli/bin.mjs +8 -0
  359. package/src/cli/delete/delete.ts +258 -0
  360. package/src/cli/help.ts +196 -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 +292 -0
  365. package/src/cli/report.ts +16 -0
  366. package/src/cli/shardfile/command.ts +50 -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/arenaView.ts +15 -0
  394. package/src/sharddev/as/groupBankV2.ts +36 -0
  395. package/src/sharddev/as/groupStepV2.ts +13 -0
  396. package/src/sharddev/as/ws.ts +30 -0
  397. package/src/sharddev/as/wsV2.ts +180 -0
  398. package/src/sharddev/assemblyscriptCompiler.d.mts +5 -0
  399. package/src/sharddev/assemblyscriptCompiler.mjs +14 -0
  400. package/src/sharddev/assetHandle.ts +84 -0
  401. package/src/sharddev/assetOwner.ts +70 -0
  402. package/src/sharddev/assetScope.ts +30 -0
  403. package/src/sharddev/assets.ts +21 -0
  404. package/src/sharddev/audio.ts +9 -0
  405. package/src/sharddev/audioEncode.ts +211 -0
  406. package/src/sharddev/author.ts +3 -0
  407. package/src/sharddev/authorError.ts +28 -0
  408. package/src/sharddev/authorManifest.ts +39 -0
  409. package/src/sharddev/bake/annulus.ts +19 -0
  410. package/src/sharddev/bake/assemblyscriptMemo.ts +76 -0
  411. package/src/sharddev/bake/assemblyscriptMemoPort.ts +4 -0
  412. package/src/sharddev/bake/authoredWorld.ts +201 -0
  413. package/src/sharddev/bake/basisEncoder.ts +95 -0
  414. package/src/sharddev/bake/basisGlb.ts +85 -0
  415. package/src/sharddev/bake/basisTool.ts +74 -0
  416. package/src/sharddev/bake/basisToolInputs.ts +476 -0
  417. package/src/sharddev/bake/byteCodec.ts +33 -0
  418. package/src/sharddev/bake/canvasAtlas.ts +406 -0
  419. package/src/sharddev/bake/coarseCopy.ts +59 -0
  420. package/src/sharddev/bake/colliders.ts +87 -0
  421. package/src/sharddev/bake/compactGlb.ts +224 -0
  422. package/src/sharddev/bake/compileScript.ts +119 -0
  423. package/src/sharddev/bake/compileScriptV2.ts +75 -0
  424. package/src/sharddev/bake/contactRows.ts +84 -0
  425. package/src/sharddev/bake/creaturePlacement.ts +117 -0
  426. package/src/sharddev/bake/export.ts +67 -0
  427. package/src/sharddev/bake/facetedGeometry.ts +379 -0
  428. package/src/sharddev/bake/farImpostor.ts +120 -0
  429. package/src/sharddev/bake/forest.ts +100 -0
  430. package/src/sharddev/bake/format-hook.mjs +2 -0
  431. package/src/sharddev/bake/generatorGlb.ts +23 -0
  432. package/src/sharddev/bake/geometryBounds.ts +77 -0
  433. package/src/sharddev/bake/geometryError.ts +48 -0
  434. package/src/sharddev/bake/glb.ts +355 -0
  435. package/src/sharddev/bake/glbCompression.ts +143 -0
  436. package/src/sharddev/bake/gltfSource.ts +59 -0
  437. package/src/sharddev/bake/groundMap.ts +142 -0
  438. package/src/sharddev/bake/image.ts +20 -0
  439. package/src/sharddev/bake/isleMap.ts +64 -0
  440. package/src/sharddev/bake/json.mjs +84 -0
  441. package/src/sharddev/bake/keyedSky.ts +47 -0
  442. package/src/sharddev/bake/keyedSkyMemo.ts +39 -0
  443. package/src/sharddev/bake/kinds.ts +137 -0
  444. package/src/sharddev/bake/lightSources.ts +31 -0
  445. package/src/sharddev/bake/mapAssembly.ts +84 -0
  446. package/src/sharddev/bake/mapRaster.ts +173 -0
  447. package/src/sharddev/bake/mapRest.ts +57 -0
  448. package/src/sharddev/bake/mapScenes.ts +234 -0
  449. package/src/sharddev/bake/materialGraph.ts +32 -0
  450. package/src/sharddev/bake/meadow.ts +27 -0
  451. package/src/sharddev/bake/meshoptChoiceMemo.ts +34 -0
  452. package/src/sharddev/bake/nativeInteractionFacts.ts +5 -0
  453. package/src/sharddev/bake/nativeLattice.ts +178 -0
  454. package/src/sharddev/bake/nativeRaster.ts +106 -0
  455. package/src/sharddev/bake/nativeTerrainField.ts +11 -0
  456. package/src/sharddev/bake/navigation-json.mjs +38 -0
  457. package/src/sharddev/bake/navigation.ts +113 -0
  458. package/src/sharddev/bake/navigationAsset.ts +18 -0
  459. package/src/sharddev/bake/nearPlaceholder.ts +206 -0
  460. package/src/sharddev/bake/normalizeRig.ts +80 -0
  461. package/src/sharddev/bake/phoneAstc.ts +93 -0
  462. package/src/sharddev/bake/placeholders.ts +581 -0
  463. package/src/sharddev/bake/placement.ts +80 -0
  464. package/src/sharddev/bake/portableBytes.ts +18 -0
  465. package/src/sharddev/bake/portableBytesMemo.ts +50 -0
  466. package/src/sharddev/bake/practiceCourse.ts +49 -0
  467. package/src/sharddev/bake/primitives.ts +96 -0
  468. package/src/sharddev/bake/props.ts +443 -0
  469. package/src/sharddev/bake/questPlacement.ts +98 -0
  470. package/src/sharddev/bake/rawTexture.ts +26 -0
  471. package/src/sharddev/bake/riderArms.ts +97 -0
  472. package/src/sharddev/bake/rig.ts +95 -0
  473. package/src/sharddev/bake/riggedHullRecipes.ts +40 -0
  474. package/src/sharddev/bake/signPlacements.ts +25 -0
  475. package/src/sharddev/bake/simplifier.ts +52 -0
  476. package/src/sharddev/bake/skinned.ts +312 -0
  477. package/src/sharddev/bake/slabChunks.ts +149 -0
  478. package/src/sharddev/bake/slabs.ts +263 -0
  479. package/src/sharddev/bake/source-loader.mjs +55 -0
  480. package/src/sharddev/bake/sourceMetadata.ts +54 -0
  481. package/src/sharddev/bake/species.ts +368 -0
  482. package/src/sharddev/bake/specimenCatalogue.ts +47 -0
  483. package/src/sharddev/bake/splatGround.ts +141 -0
  484. package/src/sharddev/bake/staticMaterials.ts +171 -0
  485. package/src/sharddev/bake/terrain.ts +195 -0
  486. package/src/sharddev/bake/texture.ts +33 -0
  487. package/src/sharddev/bake/textureWasm.ts +81 -0
  488. package/src/sharddev/bake/tileEncoder.ts +11 -0
  489. package/src/sharddev/bake/tileGrid.ts +62 -0
  490. package/src/sharddev/bake/v2Finite.ts +160 -0
  491. package/src/sharddev/bake/v2Fuel.ts +71 -0
  492. package/src/sharddev/bake/wholePartition.ts +74 -0
  493. package/src/sharddev/bake/wholePieceJoin.ts +147 -0
  494. package/src/sharddev/bake/world.ts +173 -0
  495. package/src/sharddev/bake/worldCollision.ts +128 -0
  496. package/src/sharddev/bake/worldGeometry.ts +237 -0
  497. package/src/sharddev/bake/worldGlb.ts +123 -0
  498. package/src/sharddev/bake/worldImage.ts +12 -0
  499. package/src/sharddev/bake/worldLod.ts +128 -0
  500. package/src/sharddev/bake/worldRows.ts +102 -0
  501. package/src/sharddev/bake/worldTextureMemo.ts +63 -0
  502. package/src/sharddev/bake/zstdBytesMemo.ts +52 -0
  503. package/src/sharddev/bake.ts +193 -0
  504. package/src/sharddev/bakePublication.ts +31 -0
  505. package/src/sharddev/behaviourSource.ts +94 -0
  506. package/src/sharddev/bin/wildshard.mjs +7 -0
  507. package/src/sharddev/blobBytes.ts +65 -0
  508. package/src/sharddev/blobs.ts +138 -0
  509. package/src/sharddev/bootInventory.ts +129 -0
  510. package/src/sharddev/bossProfiles.ts +18 -0
  511. package/src/sharddev/buildBehaviour.ts +77 -0
  512. package/src/sharddev/buildCacheMetrics.ts +17 -0
  513. package/src/sharddev/buildDecisionScripts.ts +122 -0
  514. package/src/sharddev/check.ts +117 -0
  515. package/src/sharddev/checkProject.ts +126 -0
  516. package/src/sharddev/cli.ts +191 -0
  517. package/src/sharddev/clientChannels.ts +169 -0
  518. package/src/sharddev/clientScripts.ts +10 -0
  519. package/src/sharddev/commons.ts +77 -0
  520. package/src/sharddev/commonsCosts.ts +11 -0
  521. package/src/sharddev/compileMovers.ts +11 -0
  522. package/src/sharddev/configBoundary.ts +6 -0
  523. package/src/sharddev/cookInput.ts +40 -0
  524. package/src/sharddev/crowds.ts +6 -0
  525. package/src/sharddev/decisionBindingMap.ts +11 -0
  526. package/src/sharddev/decisionScriptBindings.ts +117 -0
  527. package/src/sharddev/decisionScripts.ts +28 -0
  528. package/src/sharddev/decisionSource.ts +51 -0
  529. package/src/sharddev/dev.ts +113 -0
  530. package/src/sharddev/director.ts +26 -0
  531. package/src/sharddev/directorAbi.ts +77 -0
  532. package/src/sharddev/discoveryDocument.ts +97 -0
  533. package/src/sharddev/draft.ts +11 -0
  534. package/src/sharddev/eliteEntryRows.ts +29 -0
  535. package/src/sharddev/entries.ts +76 -0
  536. package/src/sharddev/entryReads.ts +73 -0
  537. package/src/sharddev/executeBundle.ts +55 -0
  538. package/src/sharddev/finds.ts +5 -0
  539. package/src/sharddev/formatJsonSchema.ts +3 -0
  540. package/src/sharddev/generationCache.ts +257 -0
  541. package/src/sharddev/generationRecipe.ts +94 -0
  542. package/src/sharddev/handwritten.ts +110 -0
  543. package/src/sharddev/immutable.ts +14 -0
  544. package/src/sharddev/interactions.ts +38 -0
  545. package/src/sharddev/kit/bakedGeometry.ts +16 -0
  546. package/src/sharddev/kit/geometryPack.ts +110 -0
  547. package/src/sharddev/ledger.ts +13 -0
  548. package/src/sharddev/looks/tileField.ts +67 -0
  549. package/src/sharddev/materialGraphFiles.ts +57 -0
  550. package/src/sharddev/materials.ts +574 -0
  551. package/src/sharddev/measure.ts +18 -0
  552. package/src/sharddev/modes.ts +115 -0
  553. package/src/sharddev/moverPrograms.ts +213 -0
  554. package/src/sharddev/movers.ts +75 -0
  555. package/src/sharddev/nativePopulationRows.ts +46 -0
  556. package/src/sharddev/newProject.ts +247 -0
  557. package/src/sharddev/noise.ts +54 -0
  558. package/src/sharddev/outputProduct.ts +188 -0
  559. package/src/sharddev/outputRuntime.ts +66 -0
  560. package/src/sharddev/performancePolicy.ts +18 -0
  561. package/src/sharddev/phasedBoss.ts +34 -0
  562. package/src/sharddev/physics.ts +194 -0
  563. package/src/sharddev/platformSections.ts +42 -0
  564. package/src/sharddev/plumbing.ts +8 -0
  565. package/src/sharddev/productOutput.ts +128 -0
  566. package/src/sharddev/project.ts +337 -0
  567. package/src/sharddev/projectCompilerIdentity.ts +94 -0
  568. package/src/sharddev/projectDecisions.ts +66 -0
  569. package/src/sharddev/projectEntryProof.ts +32 -0
  570. package/src/sharddev/projectGeneration.ts +219 -0
  571. package/src/sharddev/projectInputFiles.ts +47 -0
  572. package/src/sharddev/projectManifest.ts +108 -0
  573. package/src/sharddev/projectMap.ts +35 -0
  574. package/src/sharddev/projectOutput.ts +242 -0
  575. package/src/sharddev/projectPolicy.ts +17 -0
  576. package/src/sharddev/projectSections.ts +27 -0
  577. package/src/sharddev/questGraph.ts +25 -0
  578. package/src/sharddev/quests.ts +65 -0
  579. package/src/sharddev/random.ts +61 -0
  580. package/src/sharddev/refusals.ts +234 -0
  581. package/src/sharddev/reportCard.ts +13 -0
  582. package/src/sharddev/returnProjectionV2.ts +81 -0
  583. package/src/sharddev/rows.ts +192 -0
  584. package/src/sharddev/runtimeImports.ts +38 -0
  585. package/src/sharddev/runtimeMirrors.ts +39 -0
  586. package/src/sharddev/runtimePerformance.ts +38 -0
  587. package/src/sharddev/scene.ts +321 -0
  588. package/src/sharddev/sceneAnimation.ts +54 -0
  589. package/src/sharddev/sceneAudio.ts +64 -0
  590. package/src/sharddev/sceneDeclarations.ts +100 -0
  591. package/src/sharddev/sceneGraph.ts +139 -0
  592. package/src/sharddev/sceneTransform.ts +12 -0
  593. package/src/sharddev/schemaValidation.ts +61 -0
  594. package/src/sharddev/sections.ts +47 -0
  595. package/src/sharddev/shardSource.ts +59 -0
  596. package/src/sharddev/sourceReader.ts +26 -0
  597. package/src/sharddev/spawns.ts +38 -0
  598. package/src/sharddev/species/clips.ts +24 -0
  599. package/src/sharddev/species.ts +29 -0
  600. package/src/sharddev/speciesBrains.ts +19 -0
  601. package/src/sharddev/synth.ts +66 -0
  602. package/src/sharddev/test/compileDualScriptV2.ts +71 -0
  603. package/src/sharddev/test/compileSimV2.ts +21 -0
  604. package/src/sharddev/test/diskScriptScenario.ts +86 -0
  605. package/src/sharddev/test/scriptScenario.ts +249 -0
  606. package/src/sharddev/test/scriptSource.ts +12 -0
  607. package/src/sharddev/version.ts +4 -0
  608. package/src/sharddev/weapons/bowProfile.ts +20 -0
  609. package/src/sharddev/weapons/firearmRows.ts +11 -0
  610. package/src/sharddev/weapons/meleeProfile.ts +71 -0
  611. package/src/sharddev/weapons/thrownProfile.ts +10 -0
  612. package/src/sharddev/worldScenes.ts +308 -0
  613. package/src/sharddev/worldSource.ts +82 -0
  614. package/src/shards/_template/README.md +78 -0
  615. package/src/shards/_template/assets/2bf489fdb15f1734ddb4c4f32d500ec6da85c765ec7a4eb28dc6781160e7ec8c +0 -0
  616. package/src/shards/_template/assets/97ec4d8f75f5fa6239ee919444d6dc19fd35896bb305930c1f050ac6e0e0e6a6 +1 -0
  617. package/src/shards/_template/assets/a6a587a31327f936b1b04c05ade818c73fc8964260918662db43539465e27586 +0 -0
  618. package/src/shards/_template/assets/b4fbde0422e125b498c3dc8b9a5cc2516c8598f09e9d0e5f6b639b32f98179e6 +0 -0
  619. package/src/shards/_template/assets/bfa4dfc9c18979f904557ee8deab0058b8a399be10266f5fb1578b403f482fd4 +1 -0
  620. package/src/shards/_template/assets/ef3b7ff4fd22715771cb7d68a3977a903c5e7c3dc293542687d04b3ef3ace2cb +0 -0
  621. package/src/shards/_template/assets/f2db05998615ce1cb79ea96be32c168842eb6a2b34ec01feb86d36404603ee54 +0 -0
  622. package/src/shards/_template/assets/fef98ebb7fce6f66b26e78ac699e5c90f9bdcfaf8cabeb2b58125347eea8b4ab +0 -0
  623. package/src/shards/_template/behaviour/boss.as +39 -0
  624. package/src/shards/_template/behaviour/door.as +32 -0
  625. package/src/shards/_template/behaviour/hooks.json +129 -0
  626. package/src/shards/_template/behaviour/idle.as +75 -0
  627. package/src/shards/_template/behaviour/items.as +22 -0
  628. package/src/shards/_template/card/landscape.jpg +0 -0
  629. package/src/shards/_template/card/portrait.jpg +0 -0
  630. package/src/shards/_template/card/thumb.jpg +0 -0
  631. package/src/shards/_template/data/audio.json +45 -0
  632. package/src/shards/_template/data/bossDecision.json +83 -0
  633. package/src/shards/_template/data/budgets.json +70 -0
  634. package/src/shards/_template/data/card.json +281 -0
  635. package/src/shards/_template/data/clientScripts.json +987 -0
  636. package/src/shards/_template/data/creatures.json +65 -0
  637. package/src/shards/_template/data/director.json +39 -0
  638. package/src/shards/_template/data/encounters.json +96 -0
  639. package/src/shards/_template/data/items.json +172 -0
  640. package/src/shards/_template/data/layout.json +66 -0
  641. package/src/shards/_template/data/ledger.json +32 -0
  642. package/src/shards/_template/data/look.json +521 -0
  643. package/src/shards/_template/data/map.json +64 -0
  644. package/src/shards/_template/data/moves.json +16 -0
  645. package/src/shards/_template/data/placeholder.json +8 -0
  646. package/src/shards/_template/data/plumbing.json +32 -0
  647. package/src/shards/_template/data/quests.json +223 -0
  648. package/src/shards/_template/data/rows.json +423 -0
  649. package/src/shards/_template/data/skins.json +66 -0
  650. package/src/shards/_template/data/spawn.json +6 -0
  651. package/src/shards/_template/data/targets.json +150 -0
  652. package/src/shards/_template/data/text.json +12 -0
  653. package/src/shards/_template/data/ui.json +33 -0
  654. package/src/shards/_template/data/water.json +13 -0
  655. package/src/shards/_template/generators/behaviour.ts +34 -0
  656. package/src/shards/_template/generators/boss.ts +29 -0
  657. package/src/shards/_template/generators/buildOptions.ts +2 -0
  658. package/src/shards/_template/generators/cell.ts +224 -0
  659. package/src/shards/_template/generators/districts.ts +215 -0
  660. package/src/shards/_template/generators/farLook.ts +15 -0
  661. package/src/shards/_template/generators/generate.ts +27 -0
  662. package/src/shards/_template/generators/ground.ts +15 -0
  663. package/src/shards/_template/generators/kit.ts +69 -0
  664. package/src/shards/_template/generators/landscape.ts +59 -0
  665. package/src/shards/_template/generators/landscapeNoise.ts +62 -0
  666. package/src/shards/_template/generators/mapInputs.ts +10 -0
  667. package/src/shards/_template/generators/product.ts +100 -0
  668. package/src/shards/_template/generators/productOutput.ts +18 -0
  669. package/src/shards/_template/generators/props.ts +9 -0
  670. package/src/shards/_template/generators/templatePropsSource.ts +58 -0
  671. package/src/shards/_template/generators/terrain.ts +17 -0
  672. package/src/shards/_template/generators/world.ts +630 -0
  673. package/src/shards/_template/hero.json +10 -0
  674. package/src/shards/_template/look/entry-reads.json +20 -0
  675. package/src/shards/_template/manifest.json +281 -0
  676. package/src/shards/_template/shard.config.ts +10 -0
  677. package/src/shared/health.ts +10 -0
  678. package/src/tools/build-web.ts +59 -0
  679. package/src/tsconfig.json +30 -0
  680. package/src/web/app.tsx +53 -0
  681. package/src/web/index.html +12 -0
  682. package/src/web/main.tsx +10 -0
  683. package/src/web/tsconfig.json +13 -0
  684. package/tsconfig.author.json +23 -0
  685. package/tsconfig.commons.json +21 -0
  686. package/tsconfig.json +47 -0
  687. package/tsconfig.sharddev.json +20 -0
package/GUIDE.md ADDED
@@ -0,0 +1,790 @@
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 and the four `wildshard` 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 dev <source>` | Serve the shard source on localhost and rebuild on every save (section 4). **Not built yet** for an installed sdk (SA15) |
57
+ | `wildshard check <source> [folder] [--json]` | The loop's check: lint, build, validate, prove, report card, verdict |
58
+ | `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 |
59
+ | `wildshard upload <file> --channel staging\|prod` | Send a prepared shard file to the API (section 5) |
60
+ | `wildshard account <email>` | Make your account once and save its key, which upload sends (see "Uploading", step 5) |
61
+ | `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`) |
62
+ | `wildshard delete <slug> [--yes]` | Delete your shard from the catalogue, every channel and the grid, after you type its slug (see "Deleting a shard") |
63
+ | `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`) |
64
+ | `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") |
65
+ | `wildshard validate <source \| folder>` | Shard-format's checks and the headless budget run, alone |
66
+ | `wildshard prove <source> <proof.json>` | Play a proof tape headlessly and print what happened |
67
+ | `wildshard synth <source>` | Run `shard.config.ts`'s scene exports and write the scene as data |
68
+ | `wildshard schema [list\|shardfile\|<root>] [pointer]` | Print the JSON Schema of the shard file, or of one section or field |
69
+ | `wildshard serve` | The sharddev web app on localhost (tools for this repo, not for your shard) |
70
+ | `wildshard build-shards` | Build every shard source under a repo's `src/shards/` (repos holding several shards) |
71
+ | `wildshard pack <folder>` | Old name for `wildshard build <folder>`; use `build` |
72
+
73
+ ### Walking your shard
74
+
75
+ `wildshard dev .` is how you will walk a shard on your machine: it serves the shard on localhost and reloads the page
76
+ when you save. It is **not built yet (SA15)**: today it stops with "wildshard dev requires the SDK devserver client",
77
+ also from a sharddev checkout. Engine has to publish the dev client first (HOW-WE-BUILD ENG-16, then SD-2).
78
+
79
+ Until then there are two ways to walk a shard, and neither works from this folder alone:
80
+
81
+ - **In an engine checkout:** build an engine preview that carries your built shard file folder, then enter it from
82
+ SHARD SELECT. These steps are not written down for authors yet (HOW-WE-BUILD F5 writes them, in sharddev
83
+ `docs/second-machine.md`): ask the Wildshard team.
84
+ - **On staging, after an upload:** only once the Wildshard team has placed the shard on the grid (section 5).
85
+
86
+ What you can do from this folder alone: `wildshard check .` builds the shard, runs it headlessly against its budgets
87
+ and, with a `proof.json` tape, plays its quests headlessly (`prove`).
88
+
89
+ ### The hero
90
+
91
+ The hero is three images: thumb 640x360, portrait 804x1626 and landscape 1600x900. `wildshard new` gives your shard a
92
+ generated card (a `data:` image) so it has one from the start. Build accepts that card with a note. To capture a real
93
+ hero:
94
+
95
+ 1. Point `card.thumb`, `card.portrait` and `card.landscape` in `manifest.json` at image files inside the shard source
96
+ (for example `card/thumb.jpg`). Hero capture refuses a `data:` card.
97
+ 2. Serve an engine build that carries this exact shard (see "Walking your shard": an engine checkout today).
98
+ 3. Run `wildshard hero . --base <served-build-url>`. It opens the build in headless Chromium, enters your shard from
99
+ SHARD SELECT, shoots the view `hero.json`'s `camera` names (or the spawn view), writes the three files and stamps
100
+ `hero.json` with a hash of your content.
101
+
102
+ Build then refuses a shard file whose content changed after the hero was stamped (`hero-stale`), and upload refuses a
103
+ new version whose hero is the same as the previous version's (`hero-unchanged`). Section 6 has every hero refusal.
104
+
105
+ ### Uploading
106
+
107
+ An upload sends one shard file to the API (`https://api.wildshard.io`) and names its channel. Do these in order,
108
+ before every upload:
109
+
110
+ 1. **Hero.** A new version needs a new hero (J306). After your last change to the world, capture one
111
+ (`wildshard hero . --base <url>`, "The hero" above). Done when `hero.json` and the three card images are rewritten.
112
+ 2. **Commit.** Upload names the commit the bytes came from and refuses uncommitted changes to tracked files. The first
113
+ time: `git init`, then commit (the `.gitignore` `new` wrote keeps `public/shardfiles/` and `node_modules/` out).
114
+ Every time: commit everything, the hero included. Done when `git status` is clean.
115
+ 3. **Check.** `wildshard check .` builds the shard file. It is a **draft** (`sdk: "0.2"`): check prints a
116
+ `shardfile-draft` warning, and upload and the API refuse a draft. Done at `check pass`.
117
+ 4. **Prepare.** `wildshard prepare public/shardfiles/<slug> --base <url>`, with the URL of an exact engine preview made
118
+ for preparation, turns the draft into the uploadable form (`sdk: "0.3"`). Then `wildshard build
119
+ public/shardfiles/<slug>` writes the prepared shard file. That preview comes from an engine checkout today, so an
120
+ author outside the Wildshard team cannot prepare yet: the steps are not written down for authors (HOW-WE-BUILD F5);
121
+ ask the Wildshard team.
122
+ 5. **Keys.** Set `WILDSHARD_API_URL=https://api.wildshard.io` (or pass `--server`) and
123
+ `WILDSHARD_CREATOR_PRIVATE_KEY`, the base64 creator key upload signs with. There is one Wildshard creator key and
124
+ no per-author creator keys yet: ask the Wildshard team for it, and never commit it. Upload also sends your
125
+ **account key**, which says whose shard it is: the first upload of a slug makes it yours, and nobody else's key can
126
+ upload to it. Make the account once with `wildshard account you@example.com`: it saves the key to
127
+ `~/.config/wildshard/sharddev-key` (only you can read it) and the API never shows it again, so keep that file. An
128
+ email that has an account already is refused (`account-exists`); a lost key needs an operator reset by the
129
+ Wildshard team. In CI, set `WILDSHARD_API_KEY` instead: it wins over the file. `wildshard whoami` says which key
130
+ upload will send and whose it is. Done when `wildshard whoami` prints `key wsk_…` and `account <your email>`.
131
+ 6. **Upload,** with a version `X.Y.Z` higher than the last one uploaded (`0.0.1` the first time). Upload reads
132
+ `version` from the repo's `package.json` (`new` writes `0.0.1`; raise it before each upload), or pass `--version`:
133
+
134
+ ```sh
135
+ wildshard upload public/shardfiles/my-shard.shardfile --channel staging --version 0.0.1
136
+ ```
137
+
138
+ Upload checks the shard file as the API will, checks the hero, signs, compresses and sends it, then prints the
139
+ version and what moved. Uploading the same bytes again sends nothing.
140
+
141
+ ### Deleting a shard
142
+
143
+ `wildshard delete my-shard` deletes a shard you uploaded, with the same account key: only the key that first uploaded
144
+ a slug can delete it. It makes two calls to the API, with you in between:
145
+
146
+ 1. **Start.** It prints what the delete touches: the shard's versions, the channels pointing at it, the grid cells
147
+ 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
148
+ keeps its copy until its next release.
149
+ 2. **Type the slug.** Type `my-shard` and press Enter. Anything else deletes nothing (`delete-not-confirmed`). You
150
+ have 10 minutes; after that the confirmation lapses and you start again (`delete-expired`).
151
+ 3. **Finalize.** The shard leaves the catalogue, every channel and the grid at once, and its grid cell is freed
152
+ for the next new shard. Its downloads stop after the daily prune, once no signed release names it.
153
+
154
+ In a script, `wildshard delete my-shard --yes` skips the typing. A deleted slug stays yours: uploading a new version
155
+ of it with your key brings it back, on preview only. Done when the last line starts `deleted my-shard at`.
156
+
157
+ ## 2. The shard source
158
+
159
+ A project made by `wildshard new` is a repo with one shard source at `src/`. Inside `src/`:
160
+
161
+ | Path | What it is | Ships in the shard file? |
162
+ |---|---|---|
163
+ | `shard.config.ts` | The build entry: exports `generate` (default) and `buildOptions`. Build runs it | No: its output does |
164
+ | `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 |
165
+ | `generators/` | TypeScript that runs at build time (any Node package, J319) to make terrain, props, maps and sections | No: what they produce does |
166
+ | `behaviour/` | AssemblyScript (`.as`) scripts and `hooks.json`. Build compiles them to Wasm | The compiled Wasm |
167
+ | `assets/` | Source assets, named by their SHA-256 | The ones the shard uses, by hash |
168
+ | `look/` | Recorded entry reads for the build | No |
169
+ | `manifest.json` | The card and discovery fields: name, `card` images, `shardfile` path | The card, as data |
170
+ | `hero.json` | The hero stamp (`wildshard hero` writes it) | No |
171
+ | `proof.json` | Optional: a proof tape `check` plays with `prove` | No |
172
+ | `audio-waiver.json` | Optional: a dated waiver for the audio budget | Into the shard file's admission data |
173
+
174
+ At the repo root, around `src/`:
175
+
176
+ | Path | What it is | Ships in the shard file? |
177
+ |---|---|---|
178
+ | `package.json` | Pins `@wildshard/sdk`, shard-format, engine and `three` exactly, and pnpm 10.34.9 (`packageManager`); its `version` is what upload sends | No |
179
+ | `tsconfig.json`, `.npmrc`, `.gitignore` | TypeScript settings for `src/`; exact versions for `pnpm add`; what git leaves out (build output, `node_modules/`) | No |
180
+ | `README.md`, `GUIDE.md` | This repo's README, and this guide | No |
181
+ | `pnpm-workspace.yaml` | pnpm's install-script allowlist (SA39): a dependency's install script runs only if listed | No |
182
+ | `.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) | No |
183
+ | `public/shardfiles/` | Build output: the built folder and `<slug>.shardfile`. Never edit; never commit | It is the shard file |
184
+
185
+ **Two files to change together.** `src/manifest.json` and `src/data/card.json` hold the same card: `new` writes
186
+ both, build refuses a shard whose two copies differ, and hero capture reads `manifest.json`, so change both together.
187
+
188
+ Blender files (`.blend`), mockups and other working files never ship: keep them in a folder of your own, such as
189
+ `blender/`, and export what the shard needs into `assets/`. A shard never ships runtime TypeScript: everything that
190
+ runs in the game is data, or Wasm compiled from `behaviour/`. `shard.config.ts` and `generators/` run only at build
191
+ time; lint refuses runtime code there (section 6).
192
+
193
+ **Repo layout (J317).** A repo with one shard keeps its shard source at `src/` (`src/shard.config.ts`,
194
+ `src/data/`, ...); a repo with several keeps `src/shards/<slug>/`. Commands take the repo (`.`) and find the shard
195
+ source at `src/`, or at the one `src/shards/<slug>/` a repo holds; in a repo with several, name the shard source
196
+ (`src/shards/<slug>`). The slug is `manifest.json`'s, whatever the repo folder is called. A `src/` source builds
197
+ into the repo's `public/shardfiles/`; a `src/shards/<slug>/` source into its own folder's. SA24 moves the existing
198
+ single-shard repos to `src/`.
199
+
200
+ **The hand-written template (`--template blender`).** shard-format's `blender-template`: no sdk at runtime, no
201
+ three.js, no `shard.config.ts`. Its `src/` is a shard file folder held by hand: `shard.json` (the index),
202
+ `sections/` (the JSON you edit), `blobs/` (baked files, Blender models among them, each named by its SHA-256),
203
+ `mounts/` (what the boot reads first, with its receipt) and `validation.json`. `check` lint skips it (no code); its
204
+ build runs shard-format's `shard-format pack`, which settles every hash and size the sections measure and validates
205
+ the whole folder, then writes the built folder and shard file as any build does. A changed blob is a new file under
206
+ its new hash, with every row that names it changed to match. `package.json` lists only `@wildshard/sdk` (the CLI) and
207
+ shard-format, as dev dependencies; there is no `tsconfig.json`.
208
+
209
+ **What a shard may declare.** The runtime contract lists every section, `client/plan` kind, named file, script rule,
210
+ budget and limit a shard file may carry, and what validation refuses:
211
+ [shard-format `docs/RUNTIME-CONTRACT.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/RUNTIME-CONTRACT.md).
212
+ Read with it [`SHARDFILE.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/SHARDFILE.md) (the
213
+ fields), [`SCRIPT-ABI.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/SCRIPT-ABI.md) (the Wasm
214
+ scripts) and [`PLATFORM-FILE-FAMILIES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/PLATFORM-FILE-FAMILIES.md)
215
+ (the named files). `wildshard schema list` prints the section roots from your installed copy.
216
+
217
+ ## 3. Budgets
218
+
219
+ A budget is a limit on what your shard costs a player's phone or desktop: bytes to download, memory, draw calls,
220
+ triangles, script time and audio. Build measures the shard, and the **report card** compares each cost with its limit.
221
+ A cost over a hard limit is a refusal; one over a soft line is a warning. The numbers change with releases, so this
222
+ guide names them and points at what prints them:
223
+
224
+ | Budget | What it limits | Checked by | Where the numbers are |
225
+ |---|---|---|---|
226
+ | 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 |
227
+ | Draws, triangles | Draw calls and triangles in the near and far views | `check` (report) | The report step's refusals: `metric: actual over limit` |
228
+ | Memory | Resident, loading and playing bytes | `check` (report) | Report only for now: printed, not refused (RUNTIME-CONTRACT §6) |
229
+ | 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 |
230
+ | Frame targets | fps and per-system milliseconds per device | The running game reports against them; `check` does not | Your `data/budgets.json` |
231
+ | Server | Tick time, memory, entities, commands per tick | `validate` | `shard.json` `admission.serverBudget`; RUNTIME-CONTRACT §6 |
232
+ | 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` |
233
+ | File limits | Sizes and counts: source bytes, files, ids, text, Wasm modules | `validate`, `upload` | RUNTIME-CONTRACT §7 |
234
+
235
+ `wildshard check . --json` is the one place to read them for your shard: the `report` step's `note` and each refusal's
236
+ `message` carry the measured value and its limit. Shard-format's codes for every budget finding are in
237
+ [`docs/VALIDATION-CODES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/VALIDATION-CODES.md)
238
+ (sections "performance" and "audio"). Section 6 says what to do when one refuses.
239
+
240
+ ## 4. What reloads under `dev`
241
+
242
+ `wildshard dev` is **not built yet** for an installed sdk (SA15); this is how it behaves once it runs.
243
+
244
+ - **Every saved file in the shard source rebuilds the whole shard**, about 0.1 s after the last save, and the open page
245
+ reloads itself when the new build is ready. Nothing is patched in place: data, generators, behaviour scripts,
246
+ assets, `shard.config.ts` and `manifest.json` all take the same path.
247
+ - **A failed rebuild keeps the last good build** on the page and prints the refusal in the terminal and the browser
248
+ console. Fix it and save again.
249
+ - **Not watched:** `node_modules/`, `.git/`, `dist/`, `public/` and `.worktrees/`. After `pnpm install` or an sdk
250
+ update, stop `dev` and start it again.
251
+ - **Not made by `dev`:** a shard file to upload. `dev` builds a private copy for the page. Run `wildshard check .`
252
+ for the shard file, and capture the hero again before you upload a changed world.
253
+
254
+ ## 5. Channels and the grid
255
+
256
+ **Channels (J301).** Every upload names one:
257
+
258
+ | `--channel` | preview (`preview.wildshard.io`) | staging (`staging.wildshard.io`) | production (`play.wildshard.io`) |
259
+ |---|---|---|---|
260
+ | `staging` | moves to this version | moves to this version | stays |
261
+ | `prod` | moves | moves | moves |
262
+
263
+ There is no default: upload without `--channel` refuses. Upload to staging; once the Wildshard team has placed the
264
+ shard (below), walk it there; then upload the next version with `--channel prod`. The same bytes cannot go to staging
265
+ and then to prod: production needs a new version, and a new version needs a new hero (J306).
266
+
267
+ **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,
268
+ and only the Wildshard team places a shard on it. An uploaded shard with no cell is recorded on its channels, but no
269
+ player can reach it there yet.
270
+
271
+ **What upload says about the grid (SA32).** After the `committed:` line, upload prints one grid line, then the
272
+ `/slug/<slug>` link on each channel it moved:
273
+
274
+ | Grid line | Means |
275
+ |---|---|
276
+ | `placed at (0,3) on preview, staging` | The shard's cell, and the channels whose grid has it |
277
+ | `grid full, not placed` | Every cell is taken; the upload still counts, and the Wildshard team is told |
278
+ | `not placed (--no-place)` | You passed `--no-place` on the shard's first upload |
279
+ | `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 |
280
+ | `not placed: the grid step failed; run the same upload again to retry` | The upload counts; the same `wildshard upload` again places it |
281
+ | `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 |
282
+
283
+ `wildshard upload --no-place` uploads without taking a cell, for a proof upload you will delete. Only a shard's
284
+ first upload can take a cell, so a shard uploaded with `--no-place` never gets one from a later upload. The links
285
+ point at the share page, which is not built yet (below), and each says `(page not built yet)`.
286
+
287
+ **Not built yet:**
288
+
289
+ - **The 7×7 grid that fills itself (J314; SA29 to SA35).** A brand-new slug's first upload will get the nearest free
290
+ cell in the outer ring, and that cell is the slug's for life, on every channel it reaches: a staging upload places
291
+ it on preview and staging, and a later prod upload puts it at the same cell on production. The API side is built
292
+ but switched off until the MMO server and the play page can show a new cell; upload already prints its answer.
293
+ - **The share link (SA36, SA37):** `https://staging.wildshard.io/slug/<slug>` (and the same path on preview and
294
+ production) will show your shard's name and hero with a Play button that spawns you at its cell, and unfurl with
295
+ the hero when pasted into a chat. A shard with no cell shows its card with Play off: "not on the grid yet".
296
+
297
+ **How to share today:** there is no per-shard link yet. Once the Wildshard team has placed your shard, share
298
+ `https://staging.wildshard.io` and its cell; until then, share the hero images and the shard file.
299
+
300
+ ## 6. Refusals and their fixes
301
+
302
+ Every refusal prints the refusing code's own words, then one line:
303
+
304
+ ```text
305
+ [<rule>] fix: <what to do> (GUIDE.md#<rule's heading>)
306
+ ```
307
+
308
+ `wildshard check . --json` carries the same `rule`, `fix` and `guide` on each refusal. The headings below are those
309
+ links, one per rule. The printed `fix` is the short answer; each heading adds why. Shard-format's own refusals also
310
+ carry a stable code, listed in
311
+ [`docs/VALIDATION-CODES.md`](https://github.com/project-wildshard/shard-format/blob/main/docs/VALIDATION-CODES.md).
312
+
313
+ ### Any command
314
+
315
+ #### usage
316
+
317
+ A verb got arguments or flags it does not take. `wildshard <verb> --help` prints what it takes.
318
+
319
+ ### New
320
+
321
+ #### new-target
322
+
323
+ `new` needs a folder that does not exist yet and a kebab-case slug (`my-shard`, not `My Shard`). It never writes into
324
+ an existing folder.
325
+
326
+ #### new-template
327
+
328
+ `--template` names `sdk` (the reference world, the default) or `blender` (the hand-written Blender template). Any
329
+ other name refuses before `new` writes anything. Leave the flag out or pass `--template sdk` or `--template blender`.
330
+
331
+ #### new-refused
332
+
333
+ `new` could not copy the reference world shipped with the sdk. Reinstall the sdk.
334
+
335
+ ### Build
336
+
337
+ #### source-file-missing
338
+
339
+ A path the command was given, or a file the shard source names, is not there. Check the path in the message.
340
+
341
+ #### source-import-missing
342
+
343
+ An import in `shard.config.ts`, `generators/` or `data/` names a file or package that is not there. Fix the path, or
344
+ add the package to `package.json` and install.
345
+
346
+ #### json-syntax
347
+
348
+ A JSON file in the shard source does not parse. The message gives the line and column.
349
+
350
+ #### source-syntax
351
+
352
+ A TypeScript or AssemblyScript file does not parse. The message gives the file and line.
353
+
354
+ #### config-default-export
355
+
356
+ `shard.config.ts` must default-export its `generate` function, as `new` wrote it.
357
+
358
+ #### config-file-access
359
+
360
+ Code that `shard.config.ts` imports read a file with `node:fs`. Read files through the build context (`ctx.cached`),
361
+ so build knows the input and can cache it.
362
+
363
+ #### project-folder-slug
364
+
365
+ The shard source's folder name and its slug (`data/identity.json`) differ. Rename one to match the other.
366
+
367
+ #### source-schema
368
+
369
+ A field in your data does not have the shape the shard file needs. The message gives the path;
370
+ `wildshard schema shardfile <pointer>` prints the expected shape.
371
+
372
+ #### build-refused
373
+
374
+ Build stopped for a reason no rule above names. Read the message: it names the file, field or generator. Fix it and
375
+ run `wildshard check .` again.
376
+
377
+ ### Validate
378
+
379
+ #### validate-refused
380
+
381
+ Shard-format's checks refused the built shard. The message names the check; RUNTIME-CONTRACT §8 lists what is refused.
382
+ If a fresh, unedited build still fails, report it with the message.
383
+
384
+ ### Prove
385
+
386
+ #### proof-tape-invalid
387
+
388
+ `proof.json` does not have the proof tape's shape. Fix it where the message says.
389
+
390
+ #### proof-failed
391
+
392
+ The tape played, but a step it expected did not happen. Fix the data, or the tape step.
393
+
394
+ ### Budgets
395
+
396
+ Each of these is the report card naming a budget over its limit (section 3). The message gives the measured value and
397
+ the limit.
398
+
399
+ #### budget-unmeasured
400
+
401
+ A cost could not be measured: too few headless ticks for scripts, or native gameplay that needs a browser run.
402
+
403
+ #### budget-download
404
+
405
+ Too many bytes to download, before play (critical) or in all (library). Shrink or drop assets, or load them later.
406
+
407
+ #### budget-draws
408
+
409
+ Too many draw calls in a view. Merge meshes that share a material, or show fewer objects from that view.
410
+
411
+ #### budget-triangles
412
+
413
+ Too many triangles in a view. Use lower-detail meshes or fewer props there.
414
+
415
+ #### budget-memory
416
+
417
+ A memory total is over its line. Smaller or fewer textures and meshes. Memory reports only, for now.
418
+
419
+ #### budget-script-cpu
420
+
421
+ Behaviour scripts take too long per tick. Spread work over ticks, or run it on events.
422
+
423
+ #### budget-script-fuel
424
+
425
+ Behaviour scripts run too many instructions per tick. Shorten the hottest loops.
426
+
427
+ #### budget-over
428
+
429
+ A budget not named above is over its limit. The message names it; `wildshard check . --json` lists each.
430
+
431
+ #### budget-refused
432
+
433
+ Build or validate refused the whole report card. Run `wildshard check .`: its report step names each budget over.
434
+
435
+ ### The shard file and the hero
436
+
437
+ #### hero-stale
438
+
439
+ The shard's content changed after its hero was captured, or the card names images `hero.json` has no stamp for. The
440
+ hero must show the current world: capture it again (`wildshard hero . --base <url>`). Only if the images already show
441
+ the current world, `wildshard hero . --stamp-existing`.
442
+
443
+ #### hero-not-in-product
444
+
445
+ The shard file does not carry the captured hero: it was built before the capture. Run `wildshard check .`, then
446
+ prepare again ("Uploading", steps 3 and 4).
447
+
448
+ #### hero-unchanged
449
+
450
+ Upload only: this new version's hero is the same as the previous version's (J306: a new version needs a new hero).
451
+ Capture a new hero, build, prepare and upload again.
452
+
453
+ #### audio-refused
454
+
455
+ 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
456
+ audio. Fix each red finding, or add a dated waiver in `audio-waiver.json`. Shard-format `docs/audio.md` explains each.
457
+
458
+ #### shardfile-draft
459
+
460
+ A warning from `build` and `check`, a refusal from `upload`: the shard file is a draft (`sdk: "0.2"`). Prepare it
461
+ first ("Uploading", step 1).
462
+
463
+ #### shardfile-link
464
+
465
+ The built folder holds a symbolic link; a shard file holds only real files. Replace the link, then check and prepare
466
+ again ("Uploading", steps 3 and 4).
467
+
468
+ #### shardfile-folder-missing
469
+
470
+ There is no built folder to write a shard file from. Run `wildshard check .` (or `wildshard build .`) first.
471
+
472
+ #### shardfile-invalid
473
+
474
+ The shard file breaks a format check. Upload the shard file `prepare` and `build <folder>` wrote, unedited.
475
+
476
+ #### shardfile-refused
477
+
478
+ Writing or checking the shard file failed for another reason. Check and prepare again ("Uploading", steps 3 and 4).
479
+
480
+ ### Upload
481
+
482
+ Upload checks all of these before a byte is sent.
483
+
484
+ #### upload-shardfile-missing
485
+
486
+ The path is not a shard file. Pass the one build wrote: `public/shardfiles/<slug>.shardfile`.
487
+
488
+ #### upload-channel
489
+
490
+ No `--channel`, or one that is not `staging` or `prod` (section 5).
491
+
492
+ #### upload-credentials
493
+
494
+ `WILDSHARD_API_URL` (or `--server`) or `WILDSHARD_CREATOR_PRIVATE_KEY` is not set ("Uploading", step 5).
495
+
496
+ #### upload-level
497
+
498
+ `--level` is the compression level, 0 to 11. Leave it out for the default.
499
+
500
+ #### upload-version
501
+
502
+ No version: set `version` (X.Y.Z) in `package.json`, or pass `--version X.Y.Z`, higher than the last one uploaded.
503
+
504
+ #### upload-commit
505
+
506
+ The shard source is not in a git checkout, or `--commit` is not a full 40-character sha. Upload names the commit
507
+ its bytes came from.
508
+
509
+ #### upload-uncommitted
510
+
511
+ Tracked files have uncommitted changes. Commit, then check and prepare again before you upload ("Uploading").
512
+
513
+ #### upload-sdk-missing
514
+
515
+ Upload could not find the sdk, engine or shard-format version to send. Install the project's packages.
516
+
517
+ #### upload-refused
518
+
519
+ The API refused, or a check no rule above names. The message says what it wants: a format refusal means check and
520
+ prepare again; a server refusal (409 or 422) names the field, the version or the hero.
521
+
522
+ ### Account
523
+
524
+ The account key upload sends ("Uploading", step 5), `wildshard account` and `wildshard whoami`.
525
+
526
+ #### account-key-missing
527
+
528
+ Upload found no account key: `WILDSHARD_API_KEY` is unset and `~/.config/wildshard/sharddev-key` is not there. It
529
+ refuses before anything is sent, because the API refuses an upload with no key. Run `wildshard account <email>` once,
530
+ or set `WILDSHARD_API_KEY`.
531
+
532
+ #### account-exists
533
+
534
+ That email has an account already, and the API shows a key only once, when the account is made. Use the key you
535
+ saved for it. A lost key stays lost until the Wildshard team resets it.
536
+
537
+ #### account-key-file
538
+
539
+ `~/.config/wildshard/sharddev-key` already holds a key, and `account` never overwrites one by accident: you would lose
540
+ the key to an account you made. Keep it, or pass `--force` to replace the file; the old key keeps working.
541
+
542
+ #### account-refused
543
+
544
+ The API refused the account for another reason: a malformed email is 400, and more than five tries a minute is 429
545
+ (wait a minute).
546
+
547
+ ### Delete
548
+
549
+ `wildshard delete <slug>` ("Deleting a shard"). No account key refuses before anything is sent
550
+ (`account-key-missing`, above).
551
+
552
+ #### delete-not-confirmed
553
+
554
+ You typed something other than the slug, or nothing, so the delete was not finalized and nothing changed. Run it
555
+ again and type the slug exactly; in a script, pass `--yes`.
556
+
557
+ #### delete-expired
558
+
559
+ The confirmation from the start call was spent, or its 10 minutes passed, so finalize changed nothing. Run
560
+ `wildshard delete <slug>` again and type the slug within 10 minutes.
561
+
562
+ #### delete-not-owner
563
+
564
+ The key you sent does not own this shard: only the account whose key first uploaded a slug can delete it (the
565
+ Wildshard team can delete any shard). `wildshard whoami` shows which key you send. A 401 means the API does not know
566
+ the key at all.
567
+
568
+ #### delete-unknown
569
+
570
+ The API has no shard by that slug (404), or the slug is not a valid one (400). Check its spelling against the
571
+ catalogue.
572
+
573
+ #### delete-refused
574
+
575
+ The API refused for another reason, or `--server` is not https (the key goes only to https or localhost). The
576
+ message says which.
577
+
578
+ ### Lint
579
+
580
+ `check` lints the shard source with the sdk's rules. Each wildshard lint rule keeps a shard to data and build-time
581
+ code; its printed fix says what to change.
582
+
583
+ #### lint-not-run
584
+
585
+ The linter that ships with the sdk did not run. Reinstall the sdk.
586
+
587
+ #### lint-refused
588
+
589
+ A lint finding with no rule of its own. Fix what it names at the file and line shown.
590
+
591
+ #### lint-rules
592
+
593
+ A lint rule that is not Wildshard's own (oxlint's built-in rules). Its own help line is printed as the fix.
594
+
595
+ #### lint-generator-imports
596
+
597
+ An import the rule denies. In `generators/` any npm package, valibot, shard-format and `node:*` are fine (J319); the
598
+ rule denies engine, sdk paths outside its exports, another shard's source and a second copy of `three`. In `data/` and
599
+ `shard.config.ts` only `three`, valibot, shard-format, the sdk and Node built-ins are allowed.
600
+
601
+ #### lint-engine-internal
602
+
603
+ Shard code imports a game-only engine export; use the sdk's shard-facing one.
604
+
605
+ #### lint-engine-sides
606
+
607
+ Client and server code are mixed; import the shared module instead.
608
+
609
+ #### lint-engine-words
610
+
611
+ Shard and game names belong in content data, not in engine code.
612
+
613
+ #### lint-exec-max-buffer
614
+
615
+ An exec call that captures output needs an explicit `maxBuffer`.
616
+
617
+ #### lint-layer
618
+
619
+ An import reaches upward or into another shard; import through the public index.
620
+
621
+ #### lint-no-active-chunk
622
+
623
+ Read current content through the game layer, not the active chunk.
624
+
625
+ #### lint-no-active-singleton
626
+
627
+ Take the service from your context, not a global singleton.
628
+
629
+ #### lint-no-authored-html
630
+
631
+ Set text with `textContent`, never HTML.
632
+
633
+ #### lint-no-base64
634
+
635
+ Binary content stays binary: ship bytes as an asset, never base64 text.
636
+
637
+ #### lint-no-build-time-import
638
+
639
+ Runtime code imports build-time code. Move the shared part into a runtime module.
640
+
641
+ #### lint-no-client-plan-reflection
642
+
643
+ Pass data to a client feature; never reflect into shard TypeScript.
644
+
645
+ #### lint-no-generated-import
646
+
647
+ Do not import a generated file; call the function that makes it, or read the built folder.
648
+
649
+ #### lint-no-generated-json-import
650
+
651
+ Read generated JSON as data at build time, not through an import.
652
+
653
+ #### lint-no-global-listener-patch
654
+
655
+ Register listeners through your scope, not on globals.
656
+
657
+ #### lint-no-hook-chain
658
+
659
+ Subscribe to the typed event instead of chaining hooks.
660
+
661
+ #### lint-no-inline-ui-string
662
+
663
+ Player-facing text goes in the string table, `data/text.json`.
664
+
665
+ #### lint-no-level-identity
666
+
667
+ Put level and style choices in data instead of branching on the shard's identity.
668
+
669
+ #### lint-no-module-mock
670
+
671
+ Test through a seam (pass the dependency in), not a module mock.
672
+
673
+ #### lint-no-production-test-import
674
+
675
+ Production code imports a test module. Move what it needs out of the test.
676
+
677
+ #### lint-no-raw-animation-mixer
678
+
679
+ Use the engine's animation API, not a raw three.js mixer.
680
+
681
+ #### lint-no-raw-hud
682
+
683
+ Mount HUD through the numbered HUD slots your scope owns.
684
+
685
+ #### lint-no-raw-input
686
+
687
+ Read input through the input service, not DOM listeners.
688
+
689
+ #### lint-no-raw-random-time
690
+
691
+ Use the engine's seeded random and clock, never `Math.random` or `Date`: the game must replay the same way.
692
+
693
+ #### lint-no-raw-save
694
+
695
+ Save through the saves service, not `localStorage`.
696
+
697
+ #### lint-no-raw-shader-patch
698
+
699
+ Patch shaders through the shader registry.
700
+
701
+ #### lint-no-reexport
702
+
703
+ Import a name from the module that defines it; do not re-export it.
704
+
705
+ #### lint-no-renderer-type
706
+
707
+ Renderer types stay inside rendering code; pass plain data out.
708
+
709
+ #### lint-no-runtime-generator
710
+
711
+ Generators run at build time only: import them from `shard.config.ts`, bakers and other generators.
712
+
713
+ #### lint-no-runtime-in-build
714
+
715
+ Build code imports runtime code. Share a plain data module instead.
716
+
717
+ #### lint-no-shard-branch
718
+
719
+ A shard-specific choice belongs in the shard's data, not a branch on its name.
720
+
721
+ #### lint-no-shard-host-callback
722
+
723
+ Give host APIs data, not TypeScript callbacks: a shard file carries no code engine runs.
724
+
725
+ #### lint-no-shard-runtime
726
+
727
+ The shard source holds authoring and declarations; gameplay goes in `behaviour/` scripts.
728
+
729
+ #### lint-no-url-switch
730
+
731
+ No URL query switches; read settings from the shard's data.
732
+
733
+ #### lint-public-index
734
+
735
+ Import a package by its public export, not a file path inside it.
736
+
737
+ #### lint-runtime-commons
738
+
739
+ Runtime code imports build-time commons; use the runtime export.
740
+
741
+ #### lint-runtime-performance
742
+
743
+ Runtime code must bound its work: no per-frame allocation, raw rendering, DOM, timers or fetch.
744
+
745
+ #### lint-runtime-standalone
746
+
747
+ Runtime code imports only the runtime surface.
748
+
749
+ #### lint-sdk-no-facade
750
+
751
+ Import the sdk's own export; do not alias a game or engine binding.
752
+
753
+ #### lint-shard-engine-imports
754
+
755
+ Shard source imports `@wildshard/sdk`, never engine internals (J158).
756
+
757
+ #### lint-shard-game-imports
758
+
759
+ Shard source imports `@wildshard/sdk`, never the game.
760
+
761
+ #### lint-shard-game-plugins
762
+
763
+ Import only the game plugin exports that define your runtime.
764
+
765
+ #### lint-shard-names
766
+
767
+ Name no other shard outside its own folder.
768
+
769
+ #### lint-shard-sandbox
770
+
771
+ Services, globals, settings and assets stay inside the shard's context.
772
+
773
+ #### lint-shard-services
774
+
775
+ Get engine services from `ShardContext`.
776
+
777
+ #### lint-sim-no-render
778
+
779
+ Code the headless simulation imports must not render.
780
+
781
+ ## 7. `wildshard update`
782
+
783
+ **Not built yet (SA28).** `new` writes the four `wildshard` skills (SA14, SA27) but no `AGENTS.md` yet (SA28). `wildshard update` will rewrite this guide and the four `wildshard` skills in `.claude/skills/` from the
784
+ installed sdk, and touch nothing else; it will leave an `AGENTS.md` you changed and say so. `wildshard update --pins` (SA18, after the sdk is on npm)
785
+ will also move the sdk, shard-format and `three` versions, install, apply the release's code changes and run the
786
+ build.
787
+
788
+ Until then: after you move to a newer sdk, copy `GUIDE.md` from the sdk (the sharddev checkout's root, or
789
+ `node_modules/@wildshard/sdk/GUIDE.md` once installed from npm) over this one, and each of the sdk's
790
+ `skills/wildshard*/SKILL.md` over `.claude/skills/<same name>/SKILL.md`. The `wildshard-upgrade` skill walks it.