@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
@@ -0,0 +1,574 @@
1
+ import { Color, DoubleSide, FrontSide, MeshStandardMaterial, MeshToonMaterial, SRGBColorSpace, Vector2, Vector3, Vector4, type ColorRepresentation } from 'three';
2
+ import { AttributeNode, ConditionalNode, ConstNode, ConvertNode, JoinNode, MathNode, Node, OperatorNode, SplitNode, SubBuildNode, UniformNode, VaryingNode, VarNode } from 'three/webgpu';
3
+ import {
4
+ cameraPosition, dot, frontFacing, normalLocal, normalView, normalWorld, normalWorldGeometry, positionGeometry, positionLocal, positionView, positionViewDirection,
5
+ positionWorld, screenCoordinate, screenUV, smoothstep, step, time,
6
+ } from 'three/tsl';
7
+ import { GRAPH_PRESET_VERSION, parseFamilyMaterial, type PainterlyMaterialParams, type ToonMaterialParams } from '@wildshard/format/materialFamilies';
8
+ import { validateGraph, type GraphBudget, type GraphIr, type GraphLiteral, type GraphNode, type GraphParam, type GraphRef, type GraphStages, type GraphValueType } from '@wildshard/format/materialGraph';
9
+ import type { MaterialEntry } from '@wildshard/format/materials';
10
+
11
+ /**
12
+ * `@wildshard/sdk/materials` (DS1.4): the authoring materials a generator puts on its three.js meshes, and the TSL → graph
13
+ * compiler. Each class is an ordinary three.js material (so a generator previews in any three.js renderer) that also
14
+ * knows the shardfile catalogue entry it bakes to (`toMaterialEntry()`); `readScene` writes that entry into the scene
15
+ * description, so a material never becomes shader code (G306).
16
+ *
17
+ * - `ToonMaterial extends MeshToonMaterial`: the `toon` family (flat-shaded, vertex-coloured facets). With `bands` or
18
+ * `rim` set it bakes to a cel graph instead (N hard bands, a sun-coloured rim), built with `graph()` below.
19
+ * - `PainterlyMaterial extends MeshStandardMaterial`: the `painterly` family (soft cel bands, painted shade, rim, sway).
20
+ * - `GraphMaterial extends MeshStandardMaterial`: carries one validated material graph (`family: "graph"`).
21
+ * - `graph(spec)`: compiles TSL node trees (`three/tsl`) placed in the graph stages into SF59 graph IR
22
+ * (`@wildshard/format/materialGraph`), validated under the author caps. Only the approved vocabulary converts; a TSL
23
+ * node with no graph op (a `Fn`, `uniform()`, a code node, a texture not declared through `sample`) is refused with
24
+ * its class name. Graph-only inputs (the sun, irradiance, the lit colour, noise, the post taps) are the exports below.
25
+ * A trusted shard's own programs also have `atan(y, x)`, `mod`, `varying(node)`, `attribute('aName', type)`,
26
+ * `screenCoordinate` (the `fragCoord` input) and `surface.discard`; a code-fed uniform is an unbound `param()`.
27
+ */
28
+
29
+ /** A value a graph stage or op input takes: a TSL node, or a literal number / 2–4 number vector. */
30
+ export type GraphValue = Node | number | readonly number[];
31
+
32
+ /** What a graph-only op node carries (side table: the node itself is a plain TSL `Node` of the op's type). */
33
+ interface GraphOpInfo {
34
+ readonly graphOp: string;
35
+ readonly args: readonly GraphValue[];
36
+ readonly paramName: string | undefined;
37
+ readonly paramDef: GraphParam | undefined;
38
+ }
39
+ const graphOps = new WeakMap<object, GraphOpInfo>();
40
+ function op<T extends GraphValueType>(graphOp: string, type: T, args: readonly GraphValue[] = [], paramName?: string, paramDef?: GraphParam): Node<T> {
41
+ const node = new Node<T>(type);
42
+ graphOps.set(node, { graphOp, args, paramName, paramDef });
43
+ return node;
44
+ }
45
+ function isVar(node: Node): node is VarNode<unknown, Node> { return node instanceof VarNode; }
46
+ function unwrap(node: Node): Node {
47
+ let current = node;
48
+ while (isVar(current)) current = current.node;
49
+ return current;
50
+ }
51
+
52
+ /** The TSL node type a param stands for (a colour is a vec3; a texture is read with `sample`). */
53
+ export type ParamNodeType<P extends GraphParam['type']> = P extends 'colour' ? 'vec3' : P extends 'texture' ? 'vec4' : P;
54
+ /**
55
+ * A typed graph param (a uniform the graph reads): `param('bands', { type: 'float', value: 3, min: 1, max: 8 })`. The
56
+ * definition is the format's `GraphParam` as written (a colour in sRGB, an optional day / state `bind`); the returned
57
+ * TSL node stands for it in expressions. A texture param is read with `sample(param, uv)`.
58
+ */
59
+ export function param<const P extends GraphParam>(name: string, def: P): Node<ParamNodeType<P['type']>> {
60
+ const type = (def.type === 'colour' ? 'vec3' : def.type === 'texture' ? 'vec4' : def.type) as ParamNodeType<P['type']>;
61
+ return op('param', type, [], name, def);
62
+ }
63
+ /** Sample a texture param at a uv (base mip in vertex stages, derivative-selected mip in fragments). */
64
+ export function sample(texture: Node, at: GraphValue): Node<'vec4'> {
65
+ const info = graphOps.get(unwrap(texture));
66
+ if (info?.paramDef?.type !== 'texture') throw new Error('sample() reads a texture param()');
67
+ return op('texture', 'vec4', [at], info.paramName, info.paramDef);
68
+ }
69
+ /** Sample an existing lent 2D texture array at UV and nearest integer layer; no texture is repacked. */
70
+ export function sampleArray(texture: Node, at: GraphValue, layer: GraphValue): Node<'vec4'> {
71
+ const info = graphOps.get(unwrap(texture));
72
+ if (info?.paramDef?.type !== 'texture' || info.paramDef.role !== 'lent') throw new Error('sampleArray() reads a lent texture param()');
73
+ return op('textureArray', 'vec4', [at, layer], info.paramName, info.paramDef);
74
+ }
75
+ /** The original mesh material's colour map at its own UV, or white RGBA when unmapped. */
76
+ export const meshMap: Node<"vec4"> = op('meshMap', 'vec4');
77
+
78
+ /** MaterialX noise over a position (`noise`, about 40 instructions). */
79
+ export function noise(at: GraphValue): Node<'float'> { return op('noise', 'float', [at]); }
80
+ /** A view-space direction as a unit world one (`viewToWorld`). */
81
+ export function viewToWorld(direction: GraphValue): Node<'vec3'> { return op('viewToWorld', 'vec3', [direction]); }
82
+ /** Diffuse sky irradiance (× π) along a nonzero world direction, normalized by the compiler.
83
+ * Ambient lighting only; follows the live scene environment, rotation and intensity, or black without an environment.
84
+ * Reading this makes the ambient stage own the whole indirect term, like graphInputs.environmentIrradiance. */
85
+ export function environmentIrradianceAt(direction: GraphValue): Node<'vec3'> { return op('environmentIrradianceAt', 'vec3', [direction]); }
86
+ /** A world direction into the model space `vertex.offset` is added in (`worldToLocal`). */
87
+ export function worldToLocal(direction: GraphValue): Node<'vec3'> { return op('worldToLocal', 'vec3', [direction]); }
88
+ /** Apply the full instance matrix to a homogeneous vector in the vertex stage (identity on ordinary meshes).
89
+ * w=1 places a point; w=0 rotates/scales a direction. Apply placement ONCE: positionLocal already includes instancing.
90
+ * For vertex.position, transform vec4(positionGeometry, 1), not positionLocal. */
91
+ export function instanceTransform(value: GraphValue): Node<'vec4'> { return op('instanceTransform', 'vec4', [value]); }
92
+
93
+ /** The engine's gust front at world xz; reads the existing wind clock and gust owner. */
94
+ export function windGustAt(at: GraphValue): Node<'float'> { return op('windGustAt', 'float', [at]); }
95
+
96
+ /** Smooth upward wave normal at a REST xz point, using the CPU ocean's shared coefficients. */
97
+ export function gerstnerNormal(at: GraphValue, clock: GraphValue, damping: GraphValue): Node<'vec3'> {
98
+ return op('gerstnerNormal', 'vec3', [at, clock, damping]);
99
+ }
100
+
101
+ /** The scene depth (linear metres) at a uv, or at the pixel (a post tap, `sceneDepth`). */
102
+ export function sceneDepth(at?: GraphValue): Node<'float'> { return op('sceneDepth', 'float', at === undefined ? [] : [at]); }
103
+ /** The scene's view-space normal at a uv, or at the pixel (a post tap, `sceneNormal`). */
104
+ export function sceneNormal(at?: GraphValue): Node<'vec3'> { return op('sceneNormal', 'vec3', at === undefined ? [] : [at]); }
105
+
106
+ /** The lighting stage's inputs and the other graph-only inputs, as TSL nodes (each maps to one graph input op). */
107
+ export const graphInputs: {
108
+ /** toward the light (the `sun` sub-graph only) */
109
+ /** true for a front-facing fragment; vertex stages refuse this input */
110
+ readonly frontFacing: Node<"bool">;
111
+ /** shared wind clock (seconds), current gust, and prevailing xz direction */
112
+ readonly windTime: Node<"float">; readonly windGust: Node<"float">; readonly windDirection: Node<"vec2">;
113
+ /** Live fog sun direction/linear colour, from the existing atmosphere owner. */
114
+ readonly atmosphereSunDirection: Node<"vec3">; readonly atmosphereSunColour: Node<"vec3">;
115
+ /** Scene fog colour; black without fog. */
116
+ readonly fogColour: Node<"vec3">;
117
+ /** Active material/page FogModel.node colour-ramp zenith; scene fog colour if no ramp, black without fog. */
118
+ readonly fogZenithColour: Node<"vec3">; readonly sunDirection: Node<"vec3">;
119
+ /** the light's colour × intensity, unshadowed (the `sun` sub-graph only) */
120
+ readonly sunColour: Node<"vec3">;
121
+ /** 1 lit … 0 in cast shadow (the `sun` sub-graph only) */
122
+ readonly sunShadow: Node<"float">;
123
+ /** the surface colour × (1 − metalness) (the lighting stage) */
124
+ readonly albedo: Node<"vec3">;
125
+ /** the indirect irradiance (the `ambient` sub-graph only) */
126
+ readonly irradiance: Node<"vec3">;
127
+ /** the environment's prefiltered radiance along the reflected view ray (the `ambient` sub-graph only; reading it or
128
+ * `environmentIrradiance` makes `ambient` the whole indirect term) */
129
+ readonly radiance: Node<"vec3">;
130
+ /** the environment's irradiance (× π) for the shading normal (the `ambient` sub-graph only) */
131
+ readonly environmentIrradiance: Node<"vec3">;
132
+ /** the lit colour, emissive included (the `grade` sub-graph only) */
133
+ readonly litColour: Node<"vec3">;
134
+ /** a per-instance hash in [0, 1) */
135
+ readonly instanceHash: Node<"float">;
136
+ /** the world position of the object's (or instance's) origin (vertex places) */
137
+ readonly objectOrigin: Node<"vec3">;
138
+ /** the geometry's `color` attribute (rgb, linear; white where it has none) */
139
+ readonly vertexColour: Node<"vec3">;
140
+ /** Original geometry colour alpha; 1 for RGB colour attributes or no colour attribute. */
141
+ readonly vertexColourAlpha: Node<"float">;
142
+ /** The material's own colour (linear), read live: a per-material tint a runtime sets (a creature's per-animal coat). */
143
+ readonly materialColour: Node<"vec3">;
144
+ /** The material's emissive × emissiveIntensity (linear), read live: the hit-flash port a runtime drives. */
145
+ readonly materialEmissive: Node<"vec3">;
146
+ /** Camera-space vertex position after skinning/instancing; forward is negative Z. */
147
+ readonly positionView: Node<"vec3">;
148
+ /** Toward the first visible scene directional light (shadow casters first), world space; zero when absent. */
149
+ readonly skyLightDirection: Node<"vec3">;
150
+ /** Its linear colour multiplied by intensity; excludes shadowing and atmosphere fog colour. */
151
+ readonly skyLightColour: Node<"vec3">;
152
+ /** the scene colour at the pixel (a post input) */
153
+ readonly sceneColour: Node<"vec4">; } = {
154
+ /** toward the light (the `sun` sub-graph only) */
155
+ /** true for a front-facing fragment; vertex stages refuse this input */
156
+ frontFacing: op('frontFacing', 'bool'),
157
+ /** shared wind clock (seconds), current gust, and prevailing xz direction */
158
+ windTime: op('windTime', 'float'), windGust: op('windGust', 'float'), windDirection: op('windDirection', 'vec2'),
159
+ /** Live fog sun direction/linear colour, from the existing atmosphere owner. */
160
+ atmosphereSunDirection: op('atmosphereSunDirection', 'vec3'), atmosphereSunColour: op('atmosphereSunColour', 'vec3'),
161
+ /** Scene fog colour; black without fog. */
162
+ fogColour: op('fogColour', 'vec3'),
163
+ /** Active material/page FogModel.node colour-ramp zenith; scene fog colour if no ramp, black without fog. */
164
+ fogZenithColour: op('fogZenithColour', 'vec3'),
165
+ sunDirection: op('sunDirection', 'vec3'),
166
+ /** the light's colour × intensity, unshadowed (the `sun` sub-graph only) */
167
+ sunColour: op('sunColour', 'vec3'),
168
+ /** 1 lit … 0 in cast shadow (the `sun` sub-graph only) */
169
+ sunShadow: op('sunShadow', 'float'),
170
+ /** the surface colour × (1 − metalness) (the lighting stage) */
171
+ albedo: op('albedo', 'vec3'),
172
+ /** the indirect irradiance (the `ambient` sub-graph only) */
173
+ irradiance: op('irradiance', 'vec3'),
174
+ /** the environment's prefiltered radiance along the reflected view ray (the `ambient` sub-graph only; reading it or
175
+ * `environmentIrradiance` makes `ambient` the whole indirect term) */
176
+ radiance: op('radiance', 'vec3'),
177
+ /** the environment's irradiance (× π) for the shading normal (the `ambient` sub-graph only) */
178
+ environmentIrradiance: op('environmentIrradiance', 'vec3'),
179
+ /** the lit colour, emissive included (the `grade` sub-graph only) */
180
+ litColour: op('litColour', 'vec3'),
181
+ /** a per-instance hash in [0, 1) */
182
+ instanceHash: op('instanceHash', 'float'),
183
+ /** the world position of the object's (or instance's) origin (vertex places) */
184
+ objectOrigin: op('objectOrigin', 'vec3'),
185
+ /** the geometry's `color` attribute (rgb, linear; white where it has none) */
186
+ vertexColour: op('vertexColour', 'vec3'),
187
+ /** Original geometry colour alpha; 1 for RGB colour attributes or no colour attribute. */
188
+ vertexColourAlpha: op('vertexColourAlpha', 'float'),
189
+ /** The material's own colour (linear), read live: a per-material tint a runtime sets (a creature's per-animal coat). */
190
+ materialColour: op('materialColour', 'vec3'),
191
+ /** The material's emissive × emissiveIntensity (linear), read live: the hit-flash port a runtime drives. */
192
+ materialEmissive: op('materialEmissive', 'vec3'),
193
+ /** Camera-space vertex position after skinning/instancing; forward is negative Z. */
194
+ positionView: op('positionView', 'vec3'),
195
+ /** Toward the first visible scene directional light (shadow casters first), world space; zero when absent. */
196
+ skyLightDirection: op('skyLightDirection', 'vec3'),
197
+ /** Its linear colour multiplied by intensity; excludes shadowing and atmosphere fog colour. */
198
+ skyLightColour: op('skyLightColour', 'vec3'),
199
+ /** the scene colour at the pixel (a post input) */
200
+ sceneColour: op('sceneColour', 'vec4'),
201
+ } as const;
202
+
203
+ /** TSL built-ins that are graph inputs as they are (matched by identity; `uv()` by its attribute). */
204
+ const BUILTINS = new Map<Node, string>([
205
+ [positionLocal, 'positionLocal'], [positionGeometry, 'positionGeometry'], [positionWorld, 'positionWorld'], [positionView, 'positionView'],
206
+ [normalLocal, 'normalLocal'], [normalWorld, 'normalWorld'], [normalWorldGeometry, 'normalWorld'], [normalView, 'normalView'],
207
+ [positionViewDirection, 'viewDirection'], [cameraPosition, 'cameraPosition'], [time, 'time'], [screenUV, 'screenUV'],
208
+ [screenCoordinate, 'fragCoord'], [frontFacing, 'frontFacing'],
209
+ ]);
210
+ const OPERATORS: Readonly<Record<string, string>> = { '+': 'add', '-': 'sub', '*': 'mul', '/': 'div', '%': 'mod', '<': 'lt', '<=': 'lte', '>': 'gt', '>=': 'gte', '==': 'eq', '&&': 'and', '||': 'or', '!': 'not' };
211
+ const METHODS = new Set(['abs', 'floor', 'fract', 'sin', 'cos', 'exp', 'atan', 'mod', 'negate', 'oneMinus', 'fwidth', 'normalize', 'length', 'dot', 'mix', 'min', 'max', 'pow', 'step', 'smoothstep', 'clamp']);
212
+ const SWIZZLE: Readonly<Record<string, string>> = { r: 'x', g: 'y', b: 'z', a: 'w', s: 'x', t: 'y', p: 'z', q: 'w', x: 'x', y: 'y', z: 'z', w: 'w' };
213
+
214
+ /** What `graph()` compiles: TSL values in the graph's stages, plus the graph's own switches. */
215
+ export interface GraphSpec {
216
+ /** Optional geometry channels: numeric literals matching each attribute's type; omitted channels use these constants. */
217
+ readonly attributeDefaults?: Readonly<Record<string, GraphLiteral>>;
218
+ /** Validated author declaration; only an admitted host may grant this budget at runtime. */
219
+ readonly budget?: GraphBudget;
220
+ /** a material (the default) or a post pass (`post` only) */
221
+ readonly kind?: 'material' | 'post';
222
+ /** Toon borrows the runtime catalogue's live family bands, cloud clock and caustics. */
223
+ readonly model?: 'standard' | 'unlit' | 'toon';
224
+ readonly doubleSided?: boolean;
225
+ /** false: borrowed normal maps keep the front-face basis on back faces; culling is unchanged. */
226
+ readonly flipBackfaceNormals?: boolean;
227
+ /** false: omit underwater caustics on this toon material, leaving its shared look unchanged. */
228
+ readonly toonCaustics?: boolean;
229
+ readonly flatShading?: boolean;
230
+ /** shadow:true reuses displacement and alpha/discard in the shadow camera. */
231
+ readonly vertex?: { readonly offset: GraphValue; readonly shadow?: boolean };
232
+ /** World-space shadow RECEIVER lookup shift, independent of vertex displacement/caster depth. Lit mesh only. */
233
+ readonly shadow?: { readonly offset: GraphValue };
234
+ readonly surface?: {
235
+ readonly colour?: GraphValue; readonly alpha?: GraphValue; readonly alphaCutoff?: number; readonly emissive?: GraphValue;
236
+ readonly roughness?: GraphValue; readonly metalness?: GraphValue; readonly occlusion?: GraphValue;
237
+ /** bool: discard the fragment where true (a dither against `screenCoordinate`, a clip) */
238
+ readonly discard?: GraphValue;
239
+ /** vec3: the world-space shading normal (a lit model only) */
240
+ readonly normal?: GraphValue;
241
+ };
242
+ readonly lighting?: { readonly sun: GraphValue; readonly sunSpecular?: GraphValue; readonly ambient?: GraphValue; readonly grade?: GraphValue };
243
+ readonly outline?: { readonly offset: GraphValue; readonly colour: GraphValue };
244
+ readonly post?: { readonly colour: GraphValue };
245
+ }
246
+
247
+ function isLiteral(value: GraphValue): value is number | readonly number[] { return typeof value === 'number' || Array.isArray(value); }
248
+ function constLiteral(value: unknown): GraphLiteral | undefined {
249
+ if (typeof value === 'number') return value;
250
+ if (value instanceof Color) return [value.r, value.g, value.b];
251
+ if (value instanceof Vector2 || value instanceof Vector3 || value instanceof Vector4) return value.toArray();
252
+ return undefined;
253
+ }
254
+
255
+ /**
256
+ * Compile TSL node trees into one SF59 graph (a `GraphIr`), validated under the author caps (`validateGraph`). Shared
257
+ * subtrees become one graph node; `.toVar('name')` names a node (ids are otherwise `n0`, `n1` … in first-use order);
258
+ * TSL constants become inline literals. Throws, naming the node, on anything outside the approved vocabulary.
259
+ *
260
+ * ```ts
261
+ * const bands = param('bands', { type: 'float', value: 3, min: 1, max: 8 });
262
+ * const lit = dot(normalView, graphInputs.sunDirection).saturate().mul(graphInputs.sunShadow);
263
+ * const cel = lit.mul(bands).add(0.5).floor().div(bands);
264
+ * const ir = graph({ flatShading: true, lighting: { sun: graphInputs.albedo.mul(graphInputs.sunColour).mul(cel).mul(1 / Math.PI) } });
265
+ * ```
266
+ */
267
+ export function graph(spec: GraphSpec): GraphIr {
268
+ const nodes: Record<string, GraphNode> = {}, ids = new Map<Node, string>(), used = new Set<string>(), paramDefs: Record<string, GraphParam> = {};
269
+ let counter = 0;
270
+ const fresh = (): string => { let id = `n${counter++}`; while (used.has(id)) id = `n${counter++}`; return id; };
271
+ const define = (key: Node, name: string | null, node: GraphNode): string => {
272
+ const id = name ?? fresh();
273
+ if (used.has(id)) throw new Error(`graph: the node name ${id} is used twice`);
274
+ used.add(id); ids.set(key, id); nodes[id] = node;
275
+ return id;
276
+ };
277
+ const refOf = (value: GraphValue): GraphRef => {
278
+ if (isLiteral(value)) return value;
279
+ let node: Node = value, name: string | null = null;
280
+ for (;;) {
281
+ const seen = ids.get(node); if (seen !== undefined) return seen;
282
+ const builtin = BUILTINS.get(node);
283
+ if (builtin !== undefined) return define(node, name, { op: builtin });
284
+ if (!isVar(node)) break;
285
+ const label: unknown = node.name; // null at runtime for an unnamed var, whatever the typings say
286
+ if (!node.intent && typeof label === 'string' && label !== '') name ??= label;
287
+ node = node.node;
288
+ }
289
+ const key = node;
290
+ const seen = ids.get(key); if (seen !== undefined) return seen;
291
+ if (key instanceof ConstNode) {
292
+ const literal = constLiteral(key.value);
293
+ if (literal === undefined) throw new Error(`graph: a ${typeof key.value} constant is not a graph literal`);
294
+ if (name === null) return literal;
295
+ return define(key, name, { op: 'const', value: literal });
296
+ }
297
+ const info = graphOps.get(key);
298
+ if (info !== undefined) {
299
+ const paramName = info.paramName, def = info.paramDef;
300
+ if (paramName !== undefined) {
301
+ if (def === undefined) throw new Error('graph: a param must come from param()');
302
+ const prior = paramDefs[paramName];
303
+ if (prior !== undefined && JSON.stringify(prior) !== JSON.stringify(def)) throw new Error(`graph: two params are named ${paramName}`);
304
+ paramDefs[paramName] = def;
305
+ }
306
+ if (info.graphOp === 'param') {
307
+ if (paramName === undefined) throw new Error('graph: a param must come from param()');
308
+ return define(key, name, { op: 'param', param: paramName });
309
+ }
310
+ const inputs = info.args.map(refOf);
311
+ return define(key, name, { op: info.graphOp, ...(inputs.length === 0 ? {} : { in: inputs }), ...(info.paramName === undefined ? {} : { param: info.paramName }) });
312
+ }
313
+ if (key instanceof AttributeNode) {
314
+ const attributeName: unknown = Reflect.get(key, '_attributeName'), type = key.nodeType;
315
+ if (attributeName === 'uv') return define(key, name, { op: 'uv' });
316
+ if (typeof attributeName !== 'string' || (type !== 'float' && type !== 'vec2' && type !== 'vec3' && type !== 'vec4')) {
317
+ throw new Error(`graph: attribute ${String(attributeName)} needs a float / vec2 / vec3 / vec4 type: attribute('aSeed', 'float')`);
318
+ }
319
+ const fallback = spec.attributeDefaults?.[attributeName];
320
+ return define(key, name, { op: 'attribute', name: attributeName, type, ...(fallback === undefined ? {} : { default: fallback }) });
321
+ }
322
+ if (key instanceof VaryingNode) {
323
+ const source = key.node instanceof SubBuildNode ? key.node.node : key.node; // varying() wraps its input in the vertex sub-build
324
+ if ((key.interpolationType !== null && key.interpolationType !== 'flat') || key.interpolationSampling !== null) throw new Error('graph: varying interpolation supports flat or the default only');
325
+ return define(key, name, { op: 'varying', in: [refOf(source)], ...(key.interpolationType === 'flat' ? { interpolation: 'flat' } : {}) });
326
+ }
327
+ if (key instanceof OperatorNode) {
328
+ const graphOp = OPERATORS[key.op];
329
+ if (graphOp === undefined) throw new Error(`graph: the TSL operator ${key.op} has no graph op`);
330
+ const inputs = graphOp === 'not' ? [refOf(key.aNode)] : [refOf(key.aNode), refOf(key.bNode)];
331
+ return define(key, name, { op: graphOp, in: inputs });
332
+ }
333
+ if (key instanceof MathNode) {
334
+ if (!METHODS.has(key.method)) throw new Error(`graph: the TSL math ${key.method} has no graph op`);
335
+ const operands = [key.aNode, key.bNode, key.cNode].filter((input): input is Node => input !== null);
336
+ if (key.method === 'clamp' && operands.length === 3) {
337
+ const lo = constOf(operands[1]), hi = constOf(operands[2]);
338
+ if (lo === 0 && hi === 1) return define(key, name, { op: 'saturate', in: [refOf(operands[0] ?? 0)] });
339
+ }
340
+ return define(key, name, { op: key.method, in: operands.map(refOf) });
341
+ }
342
+ if (key instanceof SplitNode) {
343
+ const mask = key.components.split('').map((c) => SWIZZLE[c] ?? '?').join('');
344
+ if (mask.includes('?')) throw new Error(`graph: the swizzle ${key.components} is not xyzw / rgba`);
345
+ return define(key, name, { op: 'swizzle', in: [refOf(key.node)], mask });
346
+ }
347
+ if (key instanceof JoinNode) return define(key, name, { op: 'combine', in: key.nodes.map(refOf) });
348
+ if (key instanceof ConditionalNode) {
349
+ if (key.elseNode === null) throw new Error('graph: a select needs both sides');
350
+ return define(key, name, { op: 'select', in: [refOf(key.condNode), refOf(key.ifNode), refOf(key.elseNode)] });
351
+ }
352
+ if (key instanceof ConvertNode) {
353
+ const literal = constOf(key.node);
354
+ const width = { vec2: 2, vec3: 3, vec4: 4 }[key.convertTo];
355
+ if (typeof literal === 'number' && width !== undefined) return Array.from({ length: width }, () => literal);
356
+ throw new Error(`graph: a ${key.convertTo}() conversion of a node; write combine(x, x …) or rely on float broadcast`);
357
+ }
358
+ if (key instanceof UniformNode) throw new Error('graph: a TSL uniform() has no name or range; use param()');
359
+ throw new Error(`graph: the TSL node ${key.constructor.name} has no graph op`);
360
+ };
361
+ const vertex: GraphStages['vertex.offset'] = spec.vertex === undefined ? undefined : { offset: refOf(spec.vertex.offset), ...(spec.vertex.shadow === undefined ? {} : { shadow: spec.vertex.shadow }) };
362
+ let surface: GraphStages['surface'];
363
+ if (spec.surface !== undefined) {
364
+ const s = spec.surface, refs: Record<string, GraphRef> = {};
365
+ for (const key of ['colour', 'alpha', 'emissive', 'roughness', 'metalness', 'occlusion', 'discard', 'normal'] as const) { const value = s[key]; if (value !== undefined) refs[key] = refOf(value); }
366
+ surface = { ...refs, ...(s.alphaCutoff === undefined ? {} : { alphaCutoff: s.alphaCutoff }) };
367
+ }
368
+ const l = spec.lighting;
369
+ const lighting: GraphStages['lighting'] = l === undefined ? undefined
370
+ : { sun: refOf(l.sun), ...(l.sunSpecular === undefined ? {} : { sunSpecular: refOf(l.sunSpecular) }), ...(l.ambient === undefined ? {} : { ambient: refOf(l.ambient) }), ...(l.grade === undefined ? {} : { grade: refOf(l.grade) }) };
371
+ const outline: GraphStages['outline'] = spec.outline === undefined ? undefined : { offset: refOf(spec.outline.offset), colour: refOf(spec.outline.colour) };
372
+ const post: GraphStages['post'] = spec.post === undefined ? undefined : { colour: refOf(spec.post.colour) };
373
+ const stages: GraphStages = {
374
+ ...(spec.shadow === undefined ? {} : { 'shadow.offset': { offset: refOf(spec.shadow.offset) } }),
375
+ ...(vertex === undefined ? {} : { 'vertex.offset': vertex }), ...(surface === undefined ? {} : { surface }), ...(lighting === undefined ? {} : { lighting }),
376
+ ...(outline === undefined ? {} : { outline }), ...(post === undefined ? {} : { post }),
377
+ };
378
+ const kind = spec.kind ?? (spec.post !== undefined ? 'post' : 'material');
379
+ const ir = {
380
+ version: 1, kind, ...(spec.budget === undefined ? {} : { budget: spec.budget }), ...(kind === 'material' ? { model: spec.model ?? 'standard' } : {}),
381
+ ...(spec.doubleSided === undefined ? {} : { doubleSided: spec.doubleSided }), ...(spec.flipBackfaceNormals === undefined ? {} : { flipBackfaceNormals: spec.flipBackfaceNormals }), ...(spec.toonCaustics === undefined ? {} : { toonCaustics: spec.toonCaustics }), ...(spec.flatShading === undefined ? {} : { flatShading: spec.flatShading }),
382
+ ...(Object.keys(paramDefs).length === 0 ? {} : { params: paramDefs }), nodes, stages,
383
+ };
384
+ const checked = validateGraph(structuredClone(ir), { trustedBudget: true });
385
+ if (!checked.ok) throw new Error(`graph: ${checked.errors.join('; ')}`);
386
+ return checked.graph;
387
+ }
388
+ function constOf(node: Node | undefined): GraphLiteral | undefined {
389
+ const current = node === undefined ? undefined : unwrap(node);
390
+ return current instanceof ConstNode ? constLiteral(current.value) : undefined;
391
+ }
392
+
393
+ /** sRGB, rounded to 4 decimals (three's colour management round-trips to about 1e-5; an 8-bit step is 0.004), from a three.js colour. */
394
+ function srgb(color: Color): [number, number, number] {
395
+ const out = color.getRGB(new Color(), SRGBColorSpace);
396
+ return [out.r, out.g, out.b].map((c) => Math.round(c * 1e4) / 1e4) as [number, number, number];
397
+ }
398
+ function parseToonMaterial(input: unknown): ToonMaterialParams {
399
+ const params = parseFamilyMaterial(input);
400
+ if (params.family !== 'toon') throw new Error('expected a toon entry');
401
+ return params;
402
+ }
403
+ function parsePainterlyMaterial(input: unknown): PainterlyMaterialParams {
404
+ const params = parseFamilyMaterial(input);
405
+ if (params.family !== 'painterly') throw new Error('expected a painterly entry');
406
+ return params;
407
+ }
408
+
409
+ /** How a family material is written into the catalogue. */
410
+ export interface CatalogueOptions {
411
+ /** write `{ family: 'graph', preset, version }` (the engine re-expresses the family as graph IR) instead of the family entry */
412
+ readonly graphPreset?: boolean;
413
+ }
414
+
415
+ /** `ToonMaterial` options: three's toon parameters plus the toon family's own. */
416
+ export interface ToonMaterialOptions extends CatalogueOptions {
417
+ readonly color?: ColorRepresentation;
418
+ /** the geometry's vertex colours multiply the colour (default true) */
419
+ readonly vertexColors?: boolean;
420
+ /** one normal per triangle (default true) */
421
+ readonly faceted?: boolean;
422
+ /** both faces drawn (default true) */
423
+ readonly doubleSided?: boolean;
424
+ /** false: borrowed normal maps keep the front-face basis on back faces; culling is unchanged. */
425
+ readonly flipBackfaceNormals?: boolean;
426
+ /** false: omit underwater caustics on this toon material, leaving its shared look unchanged. */
427
+ readonly toonCaustics?: boolean;
428
+ readonly roughness?: number;
429
+ readonly metalness?: number;
430
+ /** hard cel bands (2–8); absent: the family's own two-band ramp. Set, the material bakes to a cel graph. */
431
+ readonly bands?: number;
432
+ /** rim strength (0–2) of a sun-coloured rim; absent: the toon look's rim. Set, the material bakes to a cel graph. */
433
+ readonly rim?: number;
434
+ }
435
+ /** The toon family as a three.js material (the scene reader bakes it to a catalogue entry). */
436
+ export class ToonMaterial extends MeshToonMaterial {
437
+ readonly isToonFamilyMaterial = true;
438
+ faceted: boolean;
439
+ roughness: number;
440
+ metalness: number;
441
+ bands: number | undefined;
442
+ rim: number | undefined;
443
+ graphPreset: boolean;
444
+ constructor(options: ToonMaterialOptions = {}) {
445
+ super({ color: options.color ?? 0xffffff, vertexColors: options.vertexColors ?? true, side: options.doubleSided === false ? FrontSide : DoubleSide });
446
+ this.faceted = options.faceted ?? true; this.roughness = options.roughness ?? 0.88; this.metalness = options.metalness ?? 0;
447
+ this.bands = options.bands; this.rim = options.rim; this.graphPreset = options.graphPreset ?? false;
448
+ if (this.bands !== undefined && (!Number.isInteger(this.bands) || this.bands < 2 || this.bands > 8)) throw new Error('ToonMaterial: bands is an integer 2–8');
449
+ if (this.rim !== undefined && !(this.rim >= 0 && this.rim <= 2)) throw new Error('ToonMaterial: rim is 0–2');
450
+ }
451
+ /** The toon family entry (defaults filled) this material stands for. */
452
+ toFamilyParams(): ToonMaterialParams {
453
+ return parseToonMaterial({ family: 'toon', colour: srgb(this.color), vertexColours: this.vertexColors, faceted: this.faceted, doubleSided: this.side === DoubleSide, roughness: this.roughness, metalness: this.metalness });
454
+ }
455
+ /** The catalogue entry: the toon family (or its graph preset), or a cel graph when `bands` / `rim` are set. */
456
+ toMaterialEntry(): MaterialEntry {
457
+ const params = this.toFamilyParams();
458
+ if (this.bands !== undefined || this.rim !== undefined) return { family: 'graph', graph: celGraph(params, this.bands ?? 2, this.rim ?? 0) };
459
+ return this.graphPreset ? { family: 'graph', preset: params, version: GRAPH_PRESET_VERSION } : params;
460
+ }
461
+ }
462
+
463
+ /** `PainterlyMaterial` options: three's standard colour plus the painterly family's surface terms. */
464
+ export interface PainterlyMaterialOptions extends CatalogueOptions {
465
+ readonly color?: ColorRepresentation;
466
+ readonly vertexColors?: boolean;
467
+ readonly doubleSided?: boolean;
468
+ /** false: borrowed normal maps keep the front-face basis on back faces; culling is unchanged. */
469
+ readonly flipBackfaceNormals?: boolean;
470
+ /** false: omit underwater caustics on this toon material, leaving its shared look unchanged. */
471
+ readonly toonCaustics?: boolean;
472
+ /** rim-light strength 0–1 (default 0.35) */
473
+ readonly rim?: number;
474
+ /** cel strength 0 (Lambert) … 1 (the full three-band ramp) (default 0.8) */
475
+ readonly bands?: number;
476
+ /** share of the painted shade tint (default 1) */
477
+ readonly shade?: number;
478
+ /** share of the painted floor (default 1) */
479
+ readonly floor?: number;
480
+ /** wind sway, metres per (local metre above the origin)² (default 0) */
481
+ readonly sway?: number;
482
+ readonly emissive?: ColorRepresentation;
483
+ readonly emissiveIntensity?: number;
484
+ readonly alphaCutoff?: number;
485
+ }
486
+ /** The painterly family as a three.js material (a preview is a plain standard material). */
487
+ export class PainterlyMaterial extends MeshStandardMaterial {
488
+ readonly isPainterlyFamilyMaterial = true;
489
+ rim: number; bands: number; shade: number; floor: number; sway: number; graphPreset: boolean;
490
+ constructor(options: PainterlyMaterialOptions = {}) {
491
+ super({ color: options.color ?? 0xffffff, vertexColors: options.vertexColors ?? true, side: options.doubleSided === true ? DoubleSide : FrontSide,
492
+ roughness: 1, metalness: 0, emissive: options.emissive ?? 0x000000, emissiveIntensity: options.emissiveIntensity ?? 1, alphaTest: options.alphaCutoff ?? 0 });
493
+ this.rim = options.rim ?? 0.35; this.bands = options.bands ?? 0.8; this.shade = options.shade ?? 1; this.floor = options.floor ?? 1; this.sway = options.sway ?? 0;
494
+ this.graphPreset = options.graphPreset ?? false;
495
+ }
496
+ /** The painterly family entry (defaults filled) this material stands for. */
497
+ toFamilyParams(): PainterlyMaterialParams {
498
+ return parsePainterlyMaterial({ family: 'painterly', colour: srgb(this.color), rim: this.rim, bands: this.bands, shade: this.shade, floor: this.floor, sway: this.sway,
499
+ emissive: srgb(this.emissive), emissiveIntensity: this.emissiveIntensity, vertexColours: this.vertexColors, doubleSided: this.side === DoubleSide, alphaCutoff: this.alphaTest });
500
+ }
501
+ /** The catalogue entry: the painterly family, or its graph preset. */
502
+ toMaterialEntry(): MaterialEntry {
503
+ const params = this.toFamilyParams();
504
+ return this.graphPreset ? { family: 'graph', preset: params, version: GRAPH_PRESET_VERSION } : params;
505
+ }
506
+ }
507
+
508
+ /** A material graph on a three.js material: a preview draws the standard model in `color`; the bake writes the graph. */
509
+ export class GraphMaterial extends MeshStandardMaterial {
510
+ readonly isGraphFamilyMaterial = true;
511
+ readonly graph: GraphIr;
512
+ constructor(ir: GraphIr | GraphSpec, preview: ColorRepresentation = 0xffffff) {
513
+ super({ color: preview, flatShading: false });
514
+ this.graph = 'version' in ir ? checkedGraph(ir) : graph(ir);
515
+ if (this.graph.kind !== 'material') throw new Error('GraphMaterial holds a material graph, not a post pass');
516
+ this.side = this.graph.doubleSided === true ? DoubleSide : FrontSide;
517
+ this.flatShading = this.graph.flatShading === true;
518
+ }
519
+ /** The catalogue entry: the inline graph. */
520
+ toMaterialEntry(): MaterialEntry { return { family: 'graph', graph: this.graph }; }
521
+ }
522
+ function checkedGraph(ir: GraphIr): GraphIr {
523
+ const checked = validateGraph(structuredClone(ir), { trustedBudget: true });
524
+ if (!checked.ok) throw new Error(`graph: ${checked.errors.join('; ')}`);
525
+ return checked.graph;
526
+ }
527
+
528
+ function rgb(values: readonly number[]): Color { return new Color().setRGB(values[0] ?? 0, values[1] ?? 0, values[2] ?? 0, SRGBColorSpace); }
529
+
530
+ /** An SDK material the scene reader bakes to a catalogue entry. */
531
+ export type CatalogueMaterial = ToonMaterial | PainterlyMaterial | GraphMaterial;
532
+ /** Whether a material is one of this module's catalogue materials. */
533
+ export function isCatalogueMaterial(material: unknown): material is CatalogueMaterial {
534
+ return material instanceof ToonMaterial || material instanceof PainterlyMaterial || material instanceof GraphMaterial;
535
+ }
536
+ /** Rebuild the SDK material a catalogue entry came from (the scene graph restore path). */
537
+ export function catalogueMaterial(entry: MaterialEntry): CatalogueMaterial {
538
+ if (entry.family === 'toon' || entry.family === 'graph' && 'preset' in entry && entry.preset.family === 'toon') {
539
+ const p = entry.family === 'toon' ? entry : entry.preset.family === 'toon' ? entry.preset : null;
540
+ if (p === null) throw new Error('unreachable toon entry');
541
+ return new ToonMaterial({ color: rgb(p.colour), vertexColors: p.vertexColours, faceted: p.faceted, doubleSided: p.doubleSided, roughness: p.roughness, metalness: p.metalness, graphPreset: entry.family === 'graph' });
542
+ }
543
+ if (entry.family === 'painterly' || entry.family === 'graph' && 'preset' in entry && entry.preset.family === 'painterly') {
544
+ const p = entry.family === 'painterly' ? entry : entry.preset.family === 'painterly' ? entry.preset : null;
545
+ if (p === null) throw new Error('unreachable painterly entry');
546
+ if (p.map !== null || p.terrain !== undefined) throw new Error('PainterlyMaterial: a mapped or painted-terrain surface needs its texture declarations');
547
+ return new PainterlyMaterial({ color: rgb(p.colour), vertexColors: p.vertexColours, doubleSided: p.doubleSided, rim: p.rim, bands: p.bands, shade: p.shade, floor: p.floor, sway: p.sway,
548
+ emissive: rgb(p.emissive), emissiveIntensity: p.emissiveIntensity, alphaCutoff: p.alphaCutoff, graphPreset: entry.family === 'graph' });
549
+ }
550
+ if (entry.family === 'graph' && 'graph' in entry) return new GraphMaterial(entry.graph);
551
+ throw new Error(`no SDK material for a ${entry.family} entry of this shape`);
552
+ }
553
+
554
+ /**
555
+ * The cel graph a `ToonMaterial` with `bands` / `rim` bakes to: the sun in `bands` hard steps over the albedo, a
556
+ * sun-coloured rim of `rim` strength where the surface turns from the view, the physical ambient. Built with `graph()`.
557
+ */
558
+ function celGraph(p: ToonMaterialParams, bands: number, rim: number): GraphIr {
559
+ const { albedo, sunColour, sunDirection, sunShadow, vertexColour } = graphInputs;
560
+ const colour = param('colour', { type: 'colour', value: [...p.colour] });
561
+ const bandsP = param('bands', { type: 'float', value: bands, min: 2, max: 8 });
562
+ const rimP = param('rim', { type: 'float', value: rim, min: 0, max: 2 });
563
+ const lit = dot(normalView, sunDirection).saturate().mul(sunShadow);
564
+ const cel = lit.mul(bandsP).add(0.5).floor().div(bandsP);
565
+ const fresnel = smoothstep(0.55, 1, dot(normalView, positionViewDirection).saturate().oneMinus());
566
+ // the rim shows on the lit side only (step(edge, x): 1 where lit ≥ 0.01)
567
+ const rimTerm = fresnel.mul(rimP).mul(step(0.01, lit)).mul(0.25);
568
+ const sun = albedo.mul(sunColour).mul(cel.mul(1 / Math.PI).add(rimTerm));
569
+ return graph({
570
+ model: 'standard', flatShading: p.faceted, doubleSided: p.doubleSided,
571
+ surface: { colour: p.vertexColours ? colour.mul(vertexColour) : colour, roughness: p.roughness, metalness: p.metalness },
572
+ lighting: { sun },
573
+ });
574
+ }
@@ -0,0 +1,18 @@
1
+ import { measureUv as packMeasureUv, type MeasureRole as FormatMeasureRole } from '@wildshard/format/materialFamilies';
2
+
3
+ /**
4
+ * `@wildshard/sdk/measure` (SF56): the measure layer's first-UV packing for authored grey-box geometry. A generator
5
+ * writes these UVs onto a mesh so the dev-map look draws its grid and size labels; the plain look never reads them.
6
+ */
7
+
8
+ /** The measure layer's surface roles: 1 = structure (orange in the dev-map look), 2 = trim (grey). */
9
+ export type MeasureRole = FormatMeasureRole;
10
+
11
+ /**
12
+ * The first-UV pair a measure-layer surface carries at one vertex: `role`, the vertex's metres across (`u`) and up
13
+ * (`up`) its face from the face's bottom-left corner as seen from outside, and the face's size `w` × `h` (m). A face may
14
+ * span at most 62 m; a whole or half metre size up to 31.5 m is labelled, any other size is gridded only.
15
+ */
16
+ export function measureUv(role: MeasureRole, u: number, up: number, w: number, h: number): [number, number] {
17
+ return packMeasureUv(role, u, up, w, h);
18
+ }