wallhammer-web 0.0.0-stage → 0.4.0

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 (408) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +88 -2
  3. package/dist/base/data.d.ts +67 -0
  4. package/dist/base/data.js +10 -0
  5. package/dist/base/destructible.d.ts +167 -0
  6. package/dist/base/destructible.js +47 -0
  7. package/dist/base/env-slot.d.ts +101 -0
  8. package/dist/base/env-slot.js +8 -0
  9. package/dist/base/frames.d.ts +138 -0
  10. package/dist/base/frames.js +459 -0
  11. package/dist/base/index.d.ts +21 -0
  12. package/dist/base/index.js +11 -0
  13. package/dist/base/mat34.d.ts +46 -0
  14. package/dist/base/mat34.js +173 -0
  15. package/dist/base/material.d.ts +87 -0
  16. package/dist/base/material.js +6 -0
  17. package/dist/base/math.d.ts +27 -0
  18. package/dist/base/math.js +60 -0
  19. package/dist/base/progress.d.ts +38 -0
  20. package/dist/base/progress.js +81 -0
  21. package/dist/base/rig.d.ts +177 -0
  22. package/dist/base/rig.js +97 -0
  23. package/dist/base/trig.d.ts +29 -0
  24. package/dist/base/trig.js +169 -0
  25. package/dist/base/up.d.ts +26 -0
  26. package/dist/base/up.js +40 -0
  27. package/dist/base/view.d.ts +128 -0
  28. package/dist/base/view.js +136 -0
  29. package/dist/camera/camera.d.ts +99 -0
  30. package/dist/camera/camera.js +228 -0
  31. package/dist/camera/follow.d.ts +120 -0
  32. package/dist/camera/follow.js +320 -0
  33. package/dist/camera/free.d.ts +153 -0
  34. package/dist/camera/free.js +359 -0
  35. package/dist/camera/index.d.ts +10 -0
  36. package/dist/camera/index.js +6 -0
  37. package/dist/camera/orbit.d.ts +93 -0
  38. package/dist/camera/orbit.js +261 -0
  39. package/dist/camera/path.d.ts +48 -0
  40. package/dist/camera/path.js +179 -0
  41. package/dist/core/ballistic.d.ts +66 -0
  42. package/dist/core/ballistic.js +104 -0
  43. package/dist/core/bodies.d.ts +77 -0
  44. package/dist/core/bodies.js +125 -0
  45. package/dist/core/clock.d.ts +37 -0
  46. package/dist/core/clock.js +87 -0
  47. package/dist/core/cover-fade.d.ts +14 -0
  48. package/dist/core/cover-fade.js +38 -0
  49. package/dist/core/index.d.ts +13 -0
  50. package/dist/core/index.js +8 -0
  51. package/dist/core/kepler.d.ts +74 -0
  52. package/dist/core/kepler.js +108 -0
  53. package/dist/core/level-fade.d.ts +66 -0
  54. package/dist/core/level-fade.js +123 -0
  55. package/dist/core/palette.d.ts +15 -0
  56. package/dist/core/palette.js +47 -0
  57. package/dist/env/atmosphere.d.ts +129 -0
  58. package/dist/env/atmosphere.js +707 -0
  59. package/dist/env/cloud-field.d.ts +44 -0
  60. package/dist/env/cloud-field.js +111 -0
  61. package/dist/env/environment.d.ts +217 -0
  62. package/dist/env/environment.js +441 -0
  63. package/dist/env/frame-block.d.ts +29 -0
  64. package/dist/env/frame-block.js +152 -0
  65. package/dist/env/glsl.d.ts +35 -0
  66. package/dist/env/glsl.js +246 -0
  67. package/dist/env/index.d.ts +13 -0
  68. package/dist/env/index.js +9 -0
  69. package/dist/env/sky.d.ts +48 -0
  70. package/dist/env/sky.js +227 -0
  71. package/dist/env/sun.d.ts +31 -0
  72. package/dist/env/sun.js +42 -0
  73. package/dist/gen-arch/build.d.ts +17 -0
  74. package/dist/gen-arch/build.js +414 -0
  75. package/dist/gen-arch/damage/damaged.d.ts +44 -0
  76. package/dist/gen-arch/damage/damaged.js +1119 -0
  77. package/dist/gen-arch/damage/fall-material.d.ts +10 -0
  78. package/dist/gen-arch/damage/fall-material.js +47 -0
  79. package/dist/gen-arch/damage/fall.d.ts +78 -0
  80. package/dist/gen-arch/damage/fall.js +797 -0
  81. package/dist/gen-arch/damage/rubble.d.ts +22 -0
  82. package/dist/gen-arch/damage/rubble.js +188 -0
  83. package/dist/gen-arch/index.d.ts +25 -0
  84. package/dist/gen-arch/index.js +16 -0
  85. package/dist/gen-arch/interior/interior-plan.d.ts +114 -0
  86. package/dist/gen-arch/interior/interior-plan.js +615 -0
  87. package/dist/gen-arch/interior/interior.d.ts +97 -0
  88. package/dist/gen-arch/interior/interior.js +966 -0
  89. package/dist/gen-arch/structure/building-shader.d.ts +25 -0
  90. package/dist/gen-arch/structure/building-shader.js +946 -0
  91. package/dist/gen-arch/structure/buildings.d.ts +248 -0
  92. package/dist/gen-arch/structure/buildings.js +294 -0
  93. package/dist/gen-arch/structure/dims.d.ts +77 -0
  94. package/dist/gen-arch/structure/dims.js +39 -0
  95. package/dist/gen-arch/structure/distant.d.ts +62 -0
  96. package/dist/gen-arch/structure/distant.js +316 -0
  97. package/dist/gen-arch/structure/env-slots.d.ts +18 -0
  98. package/dist/gen-arch/structure/env-slots.js +47 -0
  99. package/dist/gen-arch/structure/facade.d.ts +193 -0
  100. package/dist/gen-arch/structure/facade.js +159 -0
  101. package/dist/gen-arch/structure/parts.d.ts +31 -0
  102. package/dist/gen-arch/structure/parts.js +69 -0
  103. package/dist/gen-arch/structure/roof.d.ts +76 -0
  104. package/dist/gen-arch/structure/roof.js +568 -0
  105. package/dist/gen-arch/structure/structure-material.d.ts +23 -0
  106. package/dist/gen-arch/structure/structure-material.js +55 -0
  107. package/dist/gen-arch/structure/writer.d.ts +94 -0
  108. package/dist/gen-arch/structure/writer.js +195 -0
  109. package/dist/gen-core/cell.d.ts +138 -0
  110. package/dist/gen-core/cell.js +150 -0
  111. package/dist/gen-core/cube-sphere.d.ts +57 -0
  112. package/dist/gen-core/cube-sphere.js +159 -0
  113. package/dist/gen-core/field.d.ts +55 -0
  114. package/dist/gen-core/field.js +154 -0
  115. package/dist/gen-core/geometry.d.ts +31 -0
  116. package/dist/gen-core/geometry.js +231 -0
  117. package/dist/gen-core/hash.d.ts +18 -0
  118. package/dist/gen-core/hash.js +58 -0
  119. package/dist/gen-core/height-field.d.ts +33 -0
  120. package/dist/gen-core/height-field.js +137 -0
  121. package/dist/gen-core/index.d.ts +22 -0
  122. package/dist/gen-core/index.js +17 -0
  123. package/dist/gen-core/instance-cells.d.ts +37 -0
  124. package/dist/gen-core/instance-cells.js +72 -0
  125. package/dist/gen-core/near-scatter.d.ts +56 -0
  126. package/dist/gen-core/near-scatter.js +120 -0
  127. package/dist/gen-core/noise.d.ts +23 -0
  128. package/dist/gen-core/noise.js +72 -0
  129. package/dist/gen-core/occupancy.d.ts +21 -0
  130. package/dist/gen-core/occupancy.js +104 -0
  131. package/dist/gen-core/sphere-patch.d.ts +138 -0
  132. package/dist/gen-core/sphere-patch.js +544 -0
  133. package/dist/gen-core/strip-surface.d.ts +34 -0
  134. package/dist/gen-core/strip-surface.js +246 -0
  135. package/dist/gen-core/strip.d.ts +102 -0
  136. package/dist/gen-core/strip.js +817 -0
  137. package/dist/gen-ground/env-slots.d.ts +48 -0
  138. package/dist/gen-ground/env-slots.js +78 -0
  139. package/dist/gen-ground/ground.d.ts +78 -0
  140. package/dist/gen-ground/ground.js +208 -0
  141. package/dist/gen-ground/index.d.ts +9 -0
  142. package/dist/gen-ground/index.js +7 -0
  143. package/dist/gen-ground/markings.d.ts +46 -0
  144. package/dist/gen-ground/markings.js +124 -0
  145. package/dist/gen-ground/materials.d.ts +18 -0
  146. package/dist/gen-ground/materials.js +22 -0
  147. package/dist/gen-ground/terrain-shader.d.ts +5 -0
  148. package/dist/gen-ground/terrain-shader.js +151 -0
  149. package/dist/gen-mesh/bare-shapes.d.ts +194 -0
  150. package/dist/gen-mesh/bare-shapes.js +596 -0
  151. package/dist/gen-mesh/bisect-surface.d.ts +47 -0
  152. package/dist/gen-mesh/bisect-surface.js +261 -0
  153. package/dist/gen-mesh/box.d.ts +18 -0
  154. package/dist/gen-mesh/box.js +2 -0
  155. package/dist/gen-mesh/cell-morph-mesh.d.ts +52 -0
  156. package/dist/gen-mesh/cell-morph-mesh.js +258 -0
  157. package/dist/gen-mesh/cell-surface-mesh.d.ts +32 -0
  158. package/dist/gen-mesh/cell-surface-mesh.js +140 -0
  159. package/dist/gen-mesh/chunk-mesh.d.ts +25 -0
  160. package/dist/gen-mesh/chunk-mesh.js +112 -0
  161. package/dist/gen-mesh/drape-mesh.d.ts +36 -0
  162. package/dist/gen-mesh/drape-mesh.js +98 -0
  163. package/dist/gen-mesh/height-field-mesh.d.ts +14 -0
  164. package/dist/gen-mesh/height-field-mesh.js +98 -0
  165. package/dist/gen-mesh/index.d.ts +26 -0
  166. package/dist/gen-mesh/index.js +15 -0
  167. package/dist/gen-mesh/line-mesh.d.ts +25 -0
  168. package/dist/gen-mesh/line-mesh.js +62 -0
  169. package/dist/gen-mesh/mesh-builder.d.ts +115 -0
  170. package/dist/gen-mesh/mesh-builder.js +315 -0
  171. package/dist/gen-mesh/packed-mesh.d.ts +53 -0
  172. package/dist/gen-mesh/packed-mesh.js +205 -0
  173. package/dist/gen-mesh/prism-mesh.d.ts +33 -0
  174. package/dist/gen-mesh/prism-mesh.js +176 -0
  175. package/dist/gen-mesh/rig-mesh.d.ts +9 -0
  176. package/dist/gen-mesh/rig-mesh.js +135 -0
  177. package/dist/gen-mesh/strip-mesh.d.ts +45 -0
  178. package/dist/gen-mesh/strip-mesh.js +258 -0
  179. package/dist/gen-plan/drain.d.ts +58 -0
  180. package/dist/gen-plan/drain.js +270 -0
  181. package/dist/gen-plan/grid.d.ts +37 -0
  182. package/dist/gen-plan/grid.js +182 -0
  183. package/dist/gen-plan/horizon.d.ts +50 -0
  184. package/dist/gen-plan/horizon.js +185 -0
  185. package/dist/gen-plan/index.d.ts +15 -0
  186. package/dist/gen-plan/index.js +13 -0
  187. package/dist/gen-plan/line-tiles.d.ts +35 -0
  188. package/dist/gen-plan/line-tiles.js +190 -0
  189. package/dist/gen-plan/lines.d.ts +31 -0
  190. package/dist/gen-plan/lines.js +183 -0
  191. package/dist/gen-plan/plots.d.ts +40 -0
  192. package/dist/gen-plan/plots.js +282 -0
  193. package/dist/gen-plan/route.d.ts +55 -0
  194. package/dist/gen-plan/route.js +297 -0
  195. package/dist/gen-plan/sites.d.ts +32 -0
  196. package/dist/gen-plan/sites.js +209 -0
  197. package/dist/gen-tex/code-stamp.d.ts +31 -0
  198. package/dist/gen-tex/code-stamp.js +137 -0
  199. package/dist/gen-tex/index.d.ts +7 -0
  200. package/dist/gen-tex/index.js +5 -0
  201. package/dist/gen-tex/light-horizon.d.ts +47 -0
  202. package/dist/gen-tex/light-horizon.js +180 -0
  203. package/dist/gen-tex/textures.d.ts +8 -0
  204. package/dist/gen-tex/textures.js +49 -0
  205. package/dist/gen-tex/value-textures.d.ts +46 -0
  206. package/dist/gen-tex/value-textures.js +102 -0
  207. package/dist/gen-vegetation/env-slots.d.ts +20 -0
  208. package/dist/gen-vegetation/env-slots.js +29 -0
  209. package/dist/gen-vegetation/index.d.ts +8 -0
  210. package/dist/gen-vegetation/index.js +7 -0
  211. package/dist/gen-vegetation/materials.d.ts +7 -0
  212. package/dist/gen-vegetation/materials.js +17 -0
  213. package/dist/gen-vegetation/planting.d.ts +170 -0
  214. package/dist/gen-vegetation/planting.js +363 -0
  215. package/dist/gen-vegetation/tree-shader.d.ts +23 -0
  216. package/dist/gen-vegetation/tree-shader.js +229 -0
  217. package/dist/gen-vegetation/trees.d.ts +59 -0
  218. package/dist/gen-vegetation/trees.js +329 -0
  219. package/dist/gpu/device.d.ts +286 -0
  220. package/dist/gpu/device.js +1157 -0
  221. package/dist/gpu/gl.d.ts +134 -0
  222. package/dist/gpu/gl.js +276 -0
  223. package/dist/gpu/index.d.ts +4 -0
  224. package/dist/gpu/index.js +3 -0
  225. package/dist/index.d.ts +11 -0
  226. package/dist/index.js +13 -0
  227. package/dist/motion/graph.d.ts +244 -0
  228. package/dist/motion/graph.js +739 -0
  229. package/dist/motion/index.d.ts +8 -0
  230. package/dist/motion/index.js +8 -0
  231. package/dist/motion/pose-ops.d.ts +30 -0
  232. package/dist/motion/pose-ops.js +232 -0
  233. package/dist/motion/reach.d.ts +45 -0
  234. package/dist/motion/reach.js +264 -0
  235. package/dist/motion/skeleton.d.ts +49 -0
  236. package/dist/motion/skeleton.js +99 -0
  237. package/dist/platform/byte-store.d.ts +21 -0
  238. package/dist/platform/byte-store.js +137 -0
  239. package/dist/platform/canvas.d.ts +29 -0
  240. package/dist/platform/canvas.js +76 -0
  241. package/dist/platform/context-loss.d.ts +8 -0
  242. package/dist/platform/context-loss.js +17 -0
  243. package/dist/platform/free-input.d.ts +51 -0
  244. package/dist/platform/free-input.js +100 -0
  245. package/dist/platform/index.d.ts +18 -0
  246. package/dist/platform/index.js +10 -0
  247. package/dist/platform/input.d.ts +48 -0
  248. package/dist/platform/input.js +117 -0
  249. package/dist/platform/keys.d.ts +12 -0
  250. package/dist/platform/keys.js +29 -0
  251. package/dist/platform/loop.d.ts +41 -0
  252. package/dist/platform/loop.js +84 -0
  253. package/dist/platform/walk-input.d.ts +74 -0
  254. package/dist/platform/walk-input.js +226 -0
  255. package/dist/platform/worker.d.ts +51 -0
  256. package/dist/platform/worker.js +170 -0
  257. package/dist/render/bone-instances.d.ts +24 -0
  258. package/dist/render/bone-instances.js +74 -0
  259. package/dist/render/cells.d.ts +70 -0
  260. package/dist/render/cells.js +144 -0
  261. package/dist/render/glsl.d.ts +66 -0
  262. package/dist/render/glsl.js +173 -0
  263. package/dist/render/index.d.ts +26 -0
  264. package/dist/render/index.js +16 -0
  265. package/dist/render/instance-sets.d.ts +97 -0
  266. package/dist/render/instance-sets.js +241 -0
  267. package/dist/render/near-instances.d.ts +75 -0
  268. package/dist/render/near-instances.js +219 -0
  269. package/dist/render/particles.d.ts +63 -0
  270. package/dist/render/particles.js +215 -0
  271. package/dist/render/pieces.d.ts +57 -0
  272. package/dist/render/pieces.js +151 -0
  273. package/dist/render/point-lights.d.ts +97 -0
  274. package/dist/render/point-lights.js +243 -0
  275. package/dist/render/renderer.d.ts +447 -0
  276. package/dist/render/renderer.js +1100 -0
  277. package/dist/render/rig.d.ts +74 -0
  278. package/dist/render/rig.js +576 -0
  279. package/dist/render/shadow-areas.d.ts +49 -0
  280. package/dist/render/shadow-areas.js +125 -0
  281. package/dist/render/shadow-glsl.d.ts +12 -0
  282. package/dist/render/shadow-glsl.js +146 -0
  283. package/dist/render/transient.d.ts +61 -0
  284. package/dist/render/transient.js +213 -0
  285. package/dist/render/value-glsl.d.ts +17 -0
  286. package/dist/render/value-glsl.js +208 -0
  287. package/dist/render/value-layers.d.ts +180 -0
  288. package/dist/render/value-layers.js +333 -0
  289. package/dist/runtime/atmosphere.d.ts +37 -0
  290. package/dist/runtime/atmosphere.js +304 -0
  291. package/dist/runtime/cloud-shell.d.ts +29 -0
  292. package/dist/runtime/cloud-shell.js +158 -0
  293. package/dist/runtime/engine.d.ts +155 -0
  294. package/dist/runtime/engine.js +305 -0
  295. package/dist/runtime/environment-link.d.ts +22 -0
  296. package/dist/runtime/environment-link.js +49 -0
  297. package/dist/runtime/index.d.ts +13 -0
  298. package/dist/runtime/index.js +12 -0
  299. package/dist/runtime/precipitation-glsl.d.ts +2 -0
  300. package/dist/runtime/precipitation-glsl.js +70 -0
  301. package/dist/runtime/precipitation.d.ts +11 -0
  302. package/dist/runtime/precipitation.js +78 -0
  303. package/dist/runtime/sky.d.ts +30 -0
  304. package/dist/runtime/sky.js +114 -0
  305. package/dist/runtime/streaming.d.ts +245 -0
  306. package/dist/runtime/streaming.js +602 -0
  307. package/dist/sim/agenda.d.ts +167 -0
  308. package/dist/sim/agenda.js +425 -0
  309. package/dist/sim/bytes.d.ts +34 -0
  310. package/dist/sim/bytes.js +125 -0
  311. package/dist/sim/destruction/apply.d.ts +59 -0
  312. package/dist/sim/destruction/apply.js +243 -0
  313. package/dist/sim/destruction/cell-states.d.ts +54 -0
  314. package/dist/sim/destruction/cell-states.js +198 -0
  315. package/dist/sim/destruction/index.d.ts +11 -0
  316. package/dist/sim/destruction/index.js +10 -0
  317. package/dist/sim/destruction/int-geometry.d.ts +17 -0
  318. package/dist/sim/destruction/int-geometry.js +131 -0
  319. package/dist/sim/destruction/pick.d.ts +13 -0
  320. package/dist/sim/destruction/pick.js +59 -0
  321. package/dist/sim/destruction/rubble.d.ts +8 -0
  322. package/dist/sim/destruction/rubble.js +159 -0
  323. package/dist/sim/destruction/state.d.ts +15 -0
  324. package/dist/sim/destruction/state.js +83 -0
  325. package/dist/sim/destruction/structure.d.ts +30 -0
  326. package/dist/sim/destruction/structure.js +139 -0
  327. package/dist/sim/events.d.ts +37 -0
  328. package/dist/sim/events.js +106 -0
  329. package/dist/sim/fixed.d.ts +21 -0
  330. package/dist/sim/fixed.js +64 -0
  331. package/dist/sim/flow-probe.d.ts +58 -0
  332. package/dist/sim/flow-probe.js +158 -0
  333. package/dist/sim/flow.d.ts +257 -0
  334. package/dist/sim/flow.js +967 -0
  335. package/dist/sim/index.d.ts +28 -0
  336. package/dist/sim/index.js +20 -0
  337. package/dist/sim/interlock.d.ts +47 -0
  338. package/dist/sim/interlock.js +252 -0
  339. package/dist/sim/movers.d.ts +228 -0
  340. package/dist/sim/movers.js +1083 -0
  341. package/dist/sim/nav.d.ts +72 -0
  342. package/dist/sim/nav.js +292 -0
  343. package/dist/sim/paths.d.ts +80 -0
  344. package/dist/sim/paths.js +197 -0
  345. package/dist/sim/regions.d.ts +87 -0
  346. package/dist/sim/regions.js +517 -0
  347. package/dist/sim/simulation.d.ts +114 -0
  348. package/dist/sim/simulation.js +291 -0
  349. package/dist/sim/states.d.ts +23 -0
  350. package/dist/sim/states.js +54 -0
  351. package/dist/sim/table.d.ts +49 -0
  352. package/dist/sim/table.js +126 -0
  353. package/dist/sim/zones.d.ts +11 -0
  354. package/dist/sim/zones.js +196 -0
  355. package/dist/tools/collision-lines.d.ts +12 -0
  356. package/dist/tools/collision-lines.js +50 -0
  357. package/dist/tools/data-view-glsl.d.ts +3 -0
  358. package/dist/tools/data-view-glsl.js +63 -0
  359. package/dist/tools/data-view-layers.d.ts +20 -0
  360. package/dist/tools/data-view-layers.js +60 -0
  361. package/dist/tools/debug-view.d.ts +30 -0
  362. package/dist/tools/debug-view.js +4 -0
  363. package/dist/tools/index.d.ts +10 -0
  364. package/dist/tools/index.js +7 -0
  365. package/dist/tools/mesh-checks.d.ts +67 -0
  366. package/dist/tools/mesh-checks.js +188 -0
  367. package/dist/tools/profile.d.ts +85 -0
  368. package/dist/tools/profile.js +173 -0
  369. package/dist/world/cell-cache.d.ts +32 -0
  370. package/dist/world/cell-cache.js +60 -0
  371. package/dist/world/cell-format.d.ts +25 -0
  372. package/dist/world/cell-format.js +232 -0
  373. package/dist/world/collide.d.ts +192 -0
  374. package/dist/world/collide.js +822 -0
  375. package/dist/world/index.d.ts +16 -0
  376. package/dist/world/index.js +12 -0
  377. package/dist/world/mesh-solids.d.ts +48 -0
  378. package/dist/world/mesh-solids.js +169 -0
  379. package/dist/world/pick.d.ts +34 -0
  380. package/dist/world/pick.js +177 -0
  381. package/dist/world/providers.d.ts +66 -0
  382. package/dist/world/providers.js +83 -0
  383. package/dist/world/sphere.d.ts +69 -0
  384. package/dist/world/sphere.js +271 -0
  385. package/dist/world/streaming.d.ts +288 -0
  386. package/dist/world/streaming.js +801 -0
  387. package/dist/world/walker.d.ts +145 -0
  388. package/dist/world/walker.js +502 -0
  389. package/docs/architecture.md +111 -0
  390. package/docs/cameras.md +302 -0
  391. package/docs/concepts.md +123 -0
  392. package/docs/destruction.md +127 -0
  393. package/docs/frames.md +199 -0
  394. package/docs/generators.md +575 -0
  395. package/docs/getting-started.md +123 -0
  396. package/docs/headless.md +50 -0
  397. package/docs/motion.md +160 -0
  398. package/docs/planet.md +152 -0
  399. package/docs/recipes.md +521 -0
  400. package/docs/reference.md +364 -0
  401. package/docs/rendering.md +823 -0
  402. package/docs/rigs.md +203 -0
  403. package/docs/simulation.md +235 -0
  404. package/docs/streaming.md +590 -0
  405. package/docs/system.md +166 -0
  406. package/docs/tools.md +175 -0
  407. package/docs/walking.md +262 -0
  408. package/package.json +131 -3
package/docs/system.md ADDED
@@ -0,0 +1,166 @@
1
+ # The system example
2
+
3
+ `examples/system` is one scene with a sun and four bodies on their paths. The camera starts at a view of the whole system and flies down to a few metres above the surface of any body, in one shot and without a loading screen. It imports the engine and, for the structures of its settlements and their damage, the content modules `gen-arch` and `sim/destruction` (the structure material with the `framed` and `finishes` options, see [Finishes and frames](generators.md#finishes-and-frames)). The bodies, their terrain, the materials, what is drawn from afar and the flights are files of the example.
4
+
5
+ Read [Bodies on rails and nested frames](frames.md) and [The planet example](planet.md) first; this page only says what the example adds to them.
6
+
7
+ ## Run
8
+
9
+ ```sh
10
+ docker compose up -d
11
+ ```
12
+
13
+ Open <http://127.0.0.1:5281/system/>. The `dev` service serves it with the other examples; the port comes from `EXAMPLES_PORT`.
14
+
15
+ | Key | What |
16
+ | --- | --- |
17
+ | `1` `2` `3` `4` | Fly to Hearth, Pale, Ember, Rime: from the surface of one body to the surface of the other, or down from where the camera is. |
18
+ | `0` | Fly to the view of the whole system. |
19
+ | `F` | Fly to the next stop of the tour (the four bodies, then the whole system), or stop the flight. `Escape` stops it too. |
20
+ | `W` `A` `S` `D`, `E` `Q`, `Shift`, drag, wheel | The free camera, anywhere between the view of the whole system and two metres above a surface. Its speed follows its height. |
21
+ | `,` `.` | Time slower and faster: ×0, ×1, ×10, ×100, ×1000. `P` pauses it. |
22
+ | `O`, `N` | Show and hide the paths of the bodies, and their names. |
23
+ | `L` | Tint every cell by its quadtree level. |
24
+ | `M` | Show and hide the marks of the plan of Hearth: its rivers by class and the edges of its lakes. |
25
+ | `R` | Fly from orbit down to the spring of the longest river of Hearth and along it to the sea (with the plan built). |
26
+ | `C` | Show and hide the clouds of Hearth (stage 2, `world=2`). |
27
+ | `J` | Show the shade of the relief alone, in grey (stage 5, `world=5`). |
28
+ | `B` | Measure a frame of the current view with the graphics work finished. |
29
+ | `H` | Hide the panel. The line at the bottom stays. |
30
+
31
+ The line at the bottom shows the body the camera is kept by, the height, the speed, the rate of the time, the patches drawn, the time of a frame and the GPU memory. The README of the example lists the keys of the URL hash.
32
+
33
+ ## What the scene is made of
34
+
35
+ | Part | Engine | In the example |
36
+ | --- | --- | --- |
37
+ | The paths and the turning | `BodySystem` of `wallhammer-web/core`, stepped with `setTick` ([A system of bodies](frames.md#a-system-of-bodies)) | `bodies.ts`: a sun, Hearth with its moon Pale, Ember, Rime; the time is a whole number of ticks |
38
+ | The camera's place | `FrameSet.convertPoint` and `convertDirection` ([Nested frames](frames.md#nested-frames)) | kept in the frame of the body the camera is at; see below |
39
+ | Up | `UpSource` of `FreeRig` and `radialUp` of the renderer ([Local up](rendering.md#local-up)) | away from the centre near a body, along its axis farther out, the up of the system between the bodies |
40
+ | The surface of each body | `SphereWorld`, `spherePatchMesh`, `StreamedWorld` with `morph: true` ([A sphere world](streaming.md#a-sphere-world)) | one generator for all bodies (`world.ts`), four terrains, the seed of a body is the seed of the system and its index |
41
+ | The body the camera is at | one `StreamedWorld`, made on arrival and disposed on leaving | all cells from one pool of workers; the six coarsest cells of every body are kept from the start |
42
+ | Every other body | a layer of the example (`Layer` of `wallhammer-web/render`) | `far.ts`: the six coarsest cells of the same generator, lit by the sun from the body's own place |
43
+ | The air | `atmosphereFor(radius, height)` for the body the camera is at ([The atmosphere](rendering.md#the-atmosphere)) | from afar a shell with a thickness worked out per pixel (`SHELL_FS`); the two are blended over a range of distance |
44
+ | The sun, the stars, the paths | none | `far.ts` and `shaders.ts`; the stars are fixed to the frame of the system |
45
+ | Precision | `originAxes: 'all'`, `snapRenderOrigin`, `relativeMatrix`, depth mode `reversed` ([Depth modes](rendering.md#depth-modes)) | everything on the GPU is relative to a render origin near the eye |
46
+
47
+ ## One frame for the camera, handed over without a jump
48
+
49
+ The position of the camera is a 64-bit point in one frame of the system, and the picture is drawn in that frame:
50
+
51
+ - near a body (within 6 radii) the **turning frame** of that body: the ground stands still under the camera, and its cells are streamed in the frame they were generated in;
52
+ - farther out, inside the reach of a body (`influence`), its **carried frame**: the body stays in place, the stars do not turn;
53
+ - between the bodies the carried frame of the sun.
54
+
55
+ `BodySystem.dominantBody` picks the body. Entering a reach takes the camera over at its border, leaving it a tenth beyond, so the choice does not flip on the border. When the frame changes, the position, the heading and the velocity are converted, and nothing else changes: it is the same place and the same view in other numbers.
56
+
57
+ <!-- check: wrap -->
58
+ ```ts
59
+ import { FreeRig } from 'wallhammer-web/camera';
60
+ import { BodySystem } from 'wallhammer-web/core';
61
+
62
+ declare const system: BodySystem;
63
+ declare const rig: FreeRig;
64
+ /** The frame the camera's position is in, and the body it is kept by. */
65
+ declare let frame: number;
66
+ declare let attached: number;
67
+
68
+ function handOver(): void {
69
+ const enter = system.dominantBody(rig.position, frame, 1);
70
+ const keep = system.dominantBody(rig.position, frame, 1.1);
71
+ const next = keep === attached ? attached : Math.max(enter, 0);
72
+ const body = system.bodies[next]!;
73
+ const centre = system.frames.convertPoint([0, 0, 0], body.carriedFrame, frame);
74
+ const p = rig.position;
75
+ const near = Math.hypot(p[0] - centre[0], p[1] - centre[1], p[2] - centre[2]) < 6 * body.radius;
76
+ const nextFrame = near ? body.turningFrame : body.carriedFrame;
77
+ if (nextFrame === frame) return;
78
+ const heading = system.frames.convertDirection(rig.headingDir(), frame, nextFrame);
79
+ const position = system.frames.convertPoint(p, frame, nextFrame);
80
+ const velocity = system.frames.convertDirection(rig.velocity, frame, nextFrame);
81
+ const pitch = rig.pitch;
82
+ frame = nextFrame;
83
+ attached = next;
84
+ rig.position = position;
85
+ rig.velocity = velocity;
86
+ rig.lookAt([position[0] + heading[0] * 1e4, position[1] + heading[1] * 1e4, position[2] + heading[2] * 1e4]);
87
+ rig.pitch = pitch;
88
+ }
89
+ ```
90
+
91
+ Three things keep the hand-over out of the picture:
92
+
93
+ - **Up is a function of the place.** The `UpSource` of the rig blends from "away from the centre" (within 2 radii) to the axis of the body (from 5 radii) to what the parent body says (toward the border of the reach). It never asks which frame the position is in, so the horizon does not tip when the frame changes.
94
+ - **The turning is taken up before the frame.** A body turns under a camera that stands in its carried frame. Between 10 and 7 radii the example turns the camera about the axis by a growing share of the body's turn, so at 6 radii, where the turning frame takes over, the camera already turns with the body.
95
+ - **The stars are fixed to the system.** The star field of the example reads a direction in the root frame (`relativeMatrix` of the pose of the picture's frame), so it does not move when the axes of the picture change.
96
+
97
+ The render origin follows the camera on all three axes (`snapRenderOrigin(eye, 1024, 'all')`, or the streamed world's own). Every body, path and shell is placed by `relativeMatrix(frames.relativePose(itsFrame, pictureFrame), renderOrigin)`: the subtraction is done in 64 bits, the GPU gets small numbers.
98
+
99
+ ## Near and far
100
+
101
+ A body is drawn in one of two ways, and both use the same generator and the same look:
102
+
103
+ - **From afar** its six coarsest cells (32 × 32 quads each) are drawn by the layer of the example, with the light of the sun from the body's own direction. This gives the right lit phase of a neighbouring body in the sky of another. A body smaller than three pixels is drawn larger, so it stays a visible dot at the view of the whole system.
104
+ - **Near** (within 6 radii) a `StreamedWorld` streams its cells. Its six coarsest cells are answered from memory, so the streamed surface starts with the very meshes the far layer draws. The far layer stops drawing the body in the frame after the streamed surface covers it without a hole; the finer levels then blend in with `morph`.
105
+
106
+ The air works the same way. The engine has one atmosphere; it belongs to the body the camera is at. From 5.7 radii down to 4.2 its share in the picture grows from none to all (`u_airNear`), and the shell of the far layer fades by the same share. Every body with air has a shell 0.3 radii thick, so the tables of the engine's atmosphere hold for all of them and only the medium's radius changes on arrival.
107
+
108
+ ## The flights
109
+
110
+ `flight.ts` holds the flights as pure functions of their time and of where the bodies are. A flight is one or two legs. A leg belongs to one body and is kept in its turning frame: the low end stands over a place of the surface, the far end is a point that may move (the middle between two bodies, a point of another frame).
111
+
112
+ - The height grows as a power of the leg's time, so every doubling of the height takes about the same time, from 3 m to a hundred thousand kilometres.
113
+ - The camera stays straight above its place until nothing of the body stands in the way, then goes over to the direction of the far end.
114
+ - Two legs meet in one point and pass it at one speed (`matchedSeconds`).
115
+ - The far end is read every frame, so a leg ends exactly where it should, whatever the system did meanwhile. The flights work at any rate of the time.
116
+ - The place of a landing is chosen for the time of the arrival (`landingDirection`, `landingView`). Where the body has a neighbour worth it, the place aims at that neighbour 15° to 28° above the horizon, on the side of it that faces the sun, and the view turns to it. The sun is then above the horizon too, unless the two stand nearly opposite each other: the landing is then on the night side under a fully lit neighbour. The search for level ground (`findSite`) may move the place by some degrees, and the neighbour in the sky with it. A neighbour that stands close to the sun in the sky shows only a thin lit edge; that is its right phase. Hearth and Pale are each other's neighbour.
117
+
118
+ ## The plan of a world
119
+
120
+ Hearth gets a plan of its whole surface before its finer cells need it, built with `gen-plan` from the same terrain the cells use (`plan.ts`, `plan-water.ts`). Stage 1 is the water: the heights at every node of a level-9 grid (1 572 864 nodes), the hollows filled from the sea inward (the larger ones stay as lakes), flow gathered downstream from a supply that follows the climate of the terrain, and the rivers as smooth lines whose grade never rises and ends at the level of the sea or lake they reach. An index from the cells of level 8 to the lines near them goes with it.
121
+
122
+ - The plan is a pure function of the seed of the body. It is written in its own binary format (`WHP1`, sections aligned to 8 bytes) and carries a 64-bit fingerprint of its water (`planHash`), the same in Node and in a browser.
123
+ - With workers (`inhabited.ts`) one `plan` job runs after the root cells; the page decodes its bytes, checks the fingerprint and sends them to every worker with `WorkerPool.broadcast`, so each one holds the plan. Without workers the plan is built on the main thread after one frame that shows that it is being built.
124
+ - The line at the bottom shows its time, the number of rivers and lakes and the fingerprint. `M` (or `map=1` in the hash) draws the marks: line meshes in the frame of the body, drawn after the far layer with a depth test and lifted toward the eye by a small share of their distance, so the coarse facets do not hide them.
125
+ - `world=0` in the hash builds no plan at all and the cells are today's; `world=1` lets the cells of Hearth read the water of the plan once it is there; `world=2` adds the climate and `world=3` (the default) the settlements (below).
126
+
127
+ Stage 1 reaches the cells (`plan-lines.ts`, `ground.ts`, `planned-cell.ts`). Ground and water are one pure function of the point, so cells, levels and threads agree without talking to each other:
128
+
129
+ - The river lines of the plan become strip nets (`stripNet` of `wallhammer-web/gen-core`), one per tile of level 8 with the lines that touch it and their neighbours at the nodes, cached in each thread. `stripCarve` cuts them into the ground; the wide shoulder of each profile opens the valley.
130
+ - The share of a lake at a point comes from `gridWeights` of `wallhammer-web/gen-plan` and a little noise; a shore band after the carve makes the ground exactly the level of the lake on its outline.
131
+ - A planned cell (`buildBodyCell` with hooks) draws the terrain with the plan's surface and colour, drops objects where there is water and adds one `water` mesh: `stripMesh` of a view of the net with flat sections, its vertices carrying metres to the end of the water and the class of the line. It is blended and drawn after the terrain.
132
+ - `R` flies from orbit to the spring of the longest river and down its stream to the sea (`river-flight.ts`).
133
+
134
+ A script reads the fingerprint from `window.__wh.planHash()` and the report of the build from `window.__wh.stats().plan`. The presets add five views of the plan (`world-orbit`, `world-orbit-plain`, `world-mouth-20km`, `world-pool-20km`, `world-edge-60km`), each at a time with the sun over its place.
135
+
136
+ Stage 2 is the climate (`plan-climate.ts`, `climate.ts`, `weather.ts`; `world=2` in the hash). The plan gains a moisture per node (`wet`, its own section and the part `climate` of `planHash`): wet near rivers, lakes and the sea and fading with the distance along the grid, over the moisture the terrain had. The cells read temperature from latitude, height and noise, and moisture from the plan; first-match rules give the biome, its ground colour and cover and its plants (four more shapes, `shapes.ts`); the sea and lakes freeze near the poles. The weather is a pure function of plan, place and time: the engine's cloud cover by place ([Cloud cover by place](rendering.md#cloud-cover-by-place)) with a profile by latitude and patches drifting with the wind, its clouds as a `CloudShellLayer` over their shadows, and under the eye rain or snow, wet ground and fresh snow faded with height. `C` (or `clouds=0`) hides the clouds. The presets add the views `world-climate-…`: from orbit, a river through warm country, clouds from above and below, the cap, the equator, rain, snow and a border of biomes with level tints.
137
+
138
+ From stage 2, details round the camera stand on Hearth's ground (`details.ts`, `details-page.ts`; `details=0` in the hash leaves them out): tufts out to 60 m, stones and flowers out to 120 m, made per square of quadtree level 13 (about 19 m) by `nearScatter` and drawn by `NearInstanceLayer` ([Instances near the viewer](rendering.md#instances-near-the-viewer)). Their density follows the biome weights of the climate, water and slope at the vertices of the finest mesh, so a border is a gradient; each stands on the drawn triangles, none in water or on a line of the plan. A square is a `details` job on the pool (two at a time), nearest first; while squares are missing the reach shrinks toward the camera (the gain), so none appears in view. From 200 m up the reach shrinks, from 300 m nothing is made or drawn. Tufts and flowers bend in Hearth's wind. `window.__wh.stats().details` reports squares, records held, drawn and clipped, jobs, the gain of both groups and the time of the last rebuild; the presets add the views `world-detail-…`.
139
+
140
+ Stage 3 is the settlements (`plan-sites.ts`, `settlement.ts`, `settlement-layer.ts`; `world=3` in the hash). The plan picks one town and up to 127 villages with `pickSites` of `wallhammer-web/gen-plan`: a score per node from water near (`gridSteps`), a kind climate, gentle slope (`gridSlopeAt`) and moderate height, then a fit of a flat, slightly tilted pad to the terrain at each candidate (no sea, lake, river, ice, dry land or rock within it, nothing steeper than 6 %). Its sections hold the site table; the lanes and streets are lines of the kind `lane` after the rivers, with their nodes, and the part `sites` of `planHash` fingerprints both. The ground eases onto the pad over a skirt before the lines are cut (`ground.ts`); a planned cell colours yards, the village green or the town square and a patchwork of fields round each site, keeps the wild out of it, and draws its lanes as a mesh of material `way`. Lots come from `plotsAlong` along the lanes on any thread and are never stored; near the eye one block with a pitched top stands on each lot. `M` draws a cross over every site, `G` (or `site=<n>`) goes to the next site, the presets add the views `world-sites-…`, `world-town-1km`, `world-village-…` and `world-pad-edge`.
141
+
142
+ Stage 4 is the roads (`plan-routes.ts`; `world=4` in the hash). The example joins the settlements with the least-cost tools of `wallhammer-web/gen-plan`: `routeRegions` grows a region round every site, `regionLinks` gives the cheapest link between touching regions, each site keeps the link to its nearest neighbour and the cheapest links join the rest, and `routeGrid` finds each road over the grid, cheaper over steps already laid so roads share trunks. A trunk is smoothed, gets a deck where it reaches a river's water, and its heights stay under a grade limit (`limitGrade`, node heights solved over the whole graph). Roads are lines of the kind `road` cut into the ground like the lanes; decks are lines of the kind `deck`, never carved, drawn from their own net. The route table is its own sections and the part `routes` of `planHash`. `M` draws the roads, the line at the bottom counts routes, decks and sites without a road, `__wh.routes()` returns `routeStats`, and the presets add the views `world-roads-…`, `world-road-…`, `world-deck…` and `world-junction`.
143
+
144
+ Stage 5 is the shade of the mountains and the lights at night (`shade.ts`, `lights.ts`; `world=5` in the hash, now the default). Nothing new is stored in the plan: every vertex of a planned cell carries the skyline code of `horizonCodeAt` of `wallhammer-web/gen-plan` over the plan's relief (reach 20 km, 32 samples, the sea as the floor) as the extra channel of the sphere patch (`extraAt`), strips and objects carry it per vertex and per instance, and the shaders multiply the sun by `horizonLit`, so a valley stays in shade in the morning while the ridges are lit and the shade moves with the sun. The far body carries the same codes. Lights are points of a pure function of the plan: one per site from afar, one per lit structure near the eye, each on from about 6° of the sun under its horizon, staggered by a byte of its hash; one additive draw (`LightsLayer`). `J` shows the shade alone; the presets add `world-shade-…`, `world-night-…` and `world-dusk-town`.
145
+
146
+ From stage 3 figures walk round the camera on Hearth (`creatures.ts`, `life.ts`, `life-layer.ts`; `life=0` in the hash leaves them out). Four rigs of the example are drawn by one `RigLayer` ([Rigs and actors](rigs.md)): a figure on two legs in plain clothes, a thin figure of pale rods, a four-limbed pack carrier with a bending neck and tail on the free gait ([Free gait and chains](rigs.md#free-gait-and-chains)), and a small four-limbed grazer. Nothing is simulated and nothing is stored: every walker has a fixed path of plan lines that it walks there and back for ever, standing at either end (ramped speed, half a turn to the right while it stands), so its pose is a closed form of the system's time and a jump of the clock poses at once. Every settlement has `clamp(round(0.6 · lots), 8, 24)` walkers on its lanes (the town `min(140, round(0.35 · lots))`), chains of one to three lane lines from the home lot, at most 250 m, standing 20–90 s; every road `clamp(round(length / 800), 1, 12)` parties over its whole length, 60 % a pack carrier with a walker 2.2 m ahead and 40 % a lone walker with a pack, standing 120–600 s; a road of 3 km or more a troop of three rod figures 1.5 m apart on its middle third, standing 5–10 s; every village two groups of three to six grazers standing in the ring 1.05–1.35 radii from its centre. Speeds 1.15–1.45, 1.1–1.3 and 0.95–1.05 m/s. Only sites within their radius + 450 m of the eye and roads in the tiles within 450 m take part, nothing from 450 m above the ground; poses within 400 m are drawn, at most 300 (200, 24, 40 and 36 per rig). Each stands on the drawn surface of its strip (grade plus the section at its offset, a deck on the deck), up along the body's radius. `window.__wh.stats().life` reports `near`, `far`, `hidden`, `made`, `capped` and `logicMs`; the presets add `world-life-lane`, `world-life-lane-later`, `world-road`, `world-gait`, `world-troop`, `world-field`, `world-far-side` and `world-village-top`.
147
+
148
+ ## The budget
149
+
150
+ The example is built for a frame under 8 ms and under 600 MB of GPU memory at 1920×1080.
151
+
152
+ - Only one body is streamed at a time, with the budget of the planet example (900 cells, a ceiling of 560 MB).
153
+ - Every other body costs six draw calls of one 32 × 32 patch each, and one sphere for its air.
154
+ - The stars are one pass over the screen; the paths are four line loops.
155
+ - The plan of Hearth is one job in a worker; its limits (5 s, 64 MB of working memory, 12 MB of bytes) and measured times are in the README of the example.
156
+
157
+ The panel shows a report of the last flight, as in the planet example. A script reads it from `window.__wh.flightReport()`, starts a flight with `window.__wh.startFlight(name)` and steps it with `window.__wh.setFlight(seconds)`.
158
+
159
+ ## Checks
160
+
161
+ The golden test of the examples (`tools/golden/golden.ts`) holds two recipes of the example ([Tools](tools.md#golden-hashes)):
162
+
163
+ - "system example cells": every body has its own surface, the bytes of a cell do not depend on the order of generation and survive the cell format;
164
+ - "system example flights": the reaches of the bodies are nested or apart; a flight from the surface of Hearth to the surface of Pale and a descent from the view of the whole system to Rime, flown at 60 steps per second while the system runs, make no step longer than their share of the distance, meet at one speed and end at the planned place with the neighbour in the sky.
165
+
166
+ What these checks cannot see is the picture: the shaders, the hand-over between the far layer and the streamed surface, the look of the air and the frame time need a browser with a GPU.
package/docs/tools.md ADDED
@@ -0,0 +1,175 @@
1
+ # Tools
2
+
3
+ Dev tools live in `tools/`. Run the checks inside the `dev` container from the repository root. The workspace root is `/app` there.
4
+
5
+ | Command (in `/app`) | What it checks | Exit code |
6
+ | --- | --- | --- |
7
+ | `pnpm typecheck` | Types of every workspace package (each package's `typecheck` script). | non-zero on a type error |
8
+ | `pnpm check:layers` | Module layers and boundaries ([Architecture](architecture.md#what-pnpm-checklayers-enforces)). | 1 on any violation |
9
+ | `pnpm check:layers:test` | The layer check against its good and bad fixtures. | 1 if the check misbehaves |
10
+ | `pnpm test:golden` | Output hashes of the engine's generators and deterministic systems (`tools/golden/engine/`), then of those that need example code (`tools/golden/`). `pnpm test:golden:engine` and `pnpm test:golden:examples` run one set. | 1 on `CHANGED` or `MISSING` |
11
+ | `pnpm check:docs` | This documentation: code samples, links, entry names. | 1 on any finding |
12
+ | `pnpm check:pack` | The package as it would be published: it packs, installs into an empty project, loads in Node and type-checks. | 1 when a step fails |
13
+ | `pnpm check:mesh` | The mesh builder core and the bare shapes in plain Node: vertex and index counts, closed shapes (every edge twice, once each way), outward winding (positive volume near the analytic one), mirroring flips the winding, `append` keeps payloads, two different vertex formats, determinism (`tools/mesh/check.ts`; see [Generators](generators.md#building-meshes-in-your-own-vertex-format)). | 1 when a case fails |
14
+ | `pnpm check:motion` | The motion module in plain Node on made-up bone chains: blends and masks, automatic weights, transitions, marks and events, reach and ground fit, saved state, determinism, layer stacks, processor time for many figures (`tools/motion/check.ts`; see [Motion](motion.md)). | 1 when a scenario fails or the run takes over 5 s |
15
+ | `pnpm check:walk` | The collision world, the walker and the walking example's course in plain Node (comes with the examples, `tools/walk`). | 1 when a scenario fails |
16
+ | `pnpm check:follow` | The following view (`FollowRig`) in plain Node: the boom cut to the clearance, its smooth return, the pivot reaching its target, `forward` against the heading, first person, the cached key, processor time per frame (comes with the examples, `tools/follow-check`; `runFollowChecks()` is exported for other check scripts). | 1 when a case fails |
17
+
18
+ ```sh
19
+ docker compose exec -T dev sh -c 'cd /app && pnpm check:layers'
20
+ ```
21
+
22
+ ## Layer check
23
+
24
+ `tools/layers/check.ts`. Output ends with `layers: N violation(s)`. Each finding names the rule id, the file and the import. Options: `--root <dir>` checks another tree (used by the fixtures), `--list` prints every module with its layer.
25
+
26
+ Fix a finding by moving code, not by adding an exception. There is no exception list.
27
+
28
+ ## Golden hashes
29
+
30
+ `tools/golden/engine/golden.ts` runs small fixed recipes, each through one generator or deterministic system, hashes the output bytes and compares with `tools/golden/engine/hashes.json`. A generator is pure, so a difference is a real change in output.
31
+
32
+ Output: one line per recipe, `ok <name>`, `CHANGED <name>: … (old → new)` or `MISSING <name>`, then `golden: N of M generators unchanged`.
33
+
34
+ The recipes import engine sources by relative path. Scenarios that are too long for one line live next to it in `tools/golden/engine/`: `sim-scenario.ts`, `behaviour-scenario.ts`, `destruction-scenario.ts`, `frames-scenario.ts`, `depth-scenario.ts`, `tiles-scenario.ts`, `flow-scenario.ts`, `shadow-scenario.ts`.
35
+
36
+ Recipes that need the code of an example (the streaming generator of the endless example, the sphere, the planet and the system) are not here. They live in the golden test of the examples one folder up (`tools/golden/golden.ts`, with `streaming-scenario.ts`, `sphere-scenario.ts`, `planet-scenario.ts`, `system-scenario.ts` and its own `hashes.json`). The same rules apply to both. A change to the engine is checked against both sets.
37
+
38
+ ### Add an entry
39
+
40
+ 1. Add a recipe to the `RECIPES` map in `golden.ts`: a name and a function that returns `hash(...)` over the output arrays.
41
+ 2. Run the test. It prints `MISSING <name>` with the new hash and exits 1.
42
+ 3. Store it: `docker compose exec -T dev sh -c 'cd /app && node tools/golden/engine/golden.ts --accept'`.
43
+ 4. Run the test again. It must pass.
44
+
45
+ Keep inputs small and fixed. Do not read data files from outside the tool's folder; the test must run from a clean checkout.
46
+
47
+ ### When re-accepting is legitimate
48
+
49
+ `--accept` rewrites **every** hash at once, not only the changed one. Before running it:
50
+
51
+ - Run the test without `--accept` and read which recipes changed.
52
+ - Accept only when every `CHANGED` line is an output change you intended. Then look at the result in the browser or with screenshots, and commit `hashes.json` together with the code change.
53
+ - Do not accept when a recipe changed that your change should not touch. That is a regression or hidden nondeterminism (for example `Math.random` in a generator, or iteration order of a `Map` built from unordered input).
54
+ - Do not accept to silence a flaky result. A golden recipe must give the same hash on every run.
55
+ - A refactor that should not change output must leave all hashes unchanged.
56
+
57
+ ## Docs check
58
+
59
+ `tools/docs/check.ts` reads `packages/wallhammer-web/README.md` and every `.md` under `packages/wallhammer-web/docs/`.
60
+
61
+ - **Code.** Every ` ```ts ` block is written to a temporary file and type-checked with the package's `tsc`, strict, with imports resolved like the package exports. Unused locals are allowed. An HTML comment on the line before the fence changes this: `<!-- check: wrap -->` treats the block as a fragment (imports stay on top, the rest becomes a function body; declare what the fragment uses with `declare const x: T;`), `<!-- check: skip -->` skips it. Use `sh` or `text` fences for shell and layouts.
62
+ - **Links.** Every relative link must point to an existing file. A `#anchor` into a Markdown file must match one of its headings.
63
+ - **Entries.** Every `wallhammer-web/<subpath>` in the text must be an export of the package.
64
+
65
+ `node tools/docs/check.ts --keep` keeps the generated files and prints their folder, for debugging a failing sample.
66
+
67
+ If the package source itself has a type error, the samples cannot be checked; such findings say "in the package source, not a sample". Fix the package (or wait for whoever is editing it) and run again.
68
+
69
+ What it does not check: that samples run, that GLSL inside samples compiles, or that prose is true.
70
+
71
+ ## Walking check
72
+
73
+ `pnpm check:walk` (`tools/walk/check.ts`) comes with the examples, because it walks the course of the walking example. It checks the collision world, the walker (`tools/walk/walker-scenarios.ts`: wall, corner, steps, slopes, jump and ceiling, fall, thin wall, determinism, a solid that appears, CPU time), the follow camera, and the stations of the walking example's test course (`tools/walk/course-scenarios.ts` over `examples/walk/src/course.ts`, walked by the same `driveTo` as the page's `__wh.walkTo`) in plain Node, prints one line per scenario (`ok`, `FAIL`, or `slow` for a CPU-time measurement that missed its target, which does not fail the run) and exits 1 when a scenario fails or the run takes over 5 seconds. `node tools/walk/check.ts <text>` runs only the scenarios whose name contains the text.
74
+
75
+ ```sh
76
+ docker compose exec -T dev sh -c 'cd /app && pnpm check:walk'
77
+ ```
78
+
79
+ A package of scenarios is a file `tools/walk/<package>-scenarios.ts` exporting an array of `Scenario` (`tools/walk/scenario.ts`: a unique name, an optional `kind: 'timing'` and `run()` returning `{ ok, detail }`), imported in `check.ts` and appended to its `PACKAGES`. See [Walking](walking.md).
80
+
81
+ ## Mesh checks
82
+
83
+ Checks of built geometry without a browser, in `wallhammer-web/tools`, for a project's own inspection script (plain
84
+ Node, they allocate):
85
+
86
+ - `meshParts(positions, indices, { heightAt, label?, stride?, transform?, weld? })` splits a triangle mesh into
87
+ connected parts (triangles sharing a vertex, or vertices within `weld`, default 1 cm, of each other). Each
88
+ `MeshPart` has its world bounds, its lowest `gap` over the ground and where (`at`), its vertex count and `label`.
89
+ - `floatingParts(parts, { groundTolerance?, touchTolerance? })` returns the parts that hang in the air: neither within
90
+ `groundTolerance` (5 cm) of the ground nor touching (bounds within `touchTolerance`, 2 cm), directly or through a
91
+ chain, a part that is. Pass the parts of every mesh that may hold another up.
92
+ - `routeClearance(world, route, { closed?, step?, minY?, maxY?, ignore? })` samples a route (x, z pairs) every `step`
93
+ (25 cm) and returns the least horizontal distance to the side of a solid of a `CollisionWorld` (negative: inside),
94
+ with the point, the solid's id and tag. `minY`/`maxY` keep only solids that overlap the walking body's height;
95
+ `ignore(id, tag)` leaves some out.
96
+
97
+ <!-- check: wrap -->
98
+ ```ts
99
+ import { CollisionWorld } from 'wallhammer-web/world';
100
+ import { floatingParts, meshParts, routeClearance } from 'wallhammer-web/tools';
101
+ declare const positions: Float32Array;
102
+ declare const indices: Uint32Array;
103
+ declare const heightAt: (x: number, z: number) => number;
104
+
105
+ const parts = meshParts(positions, indices, { heightAt, label: 'props' });
106
+ for (const p of floatingParts(parts)) console.log(`${p.label}: ${p.gap.toFixed(2)} m over the ground at ${p.at.join(', ')}`);
107
+
108
+ const world = new CollisionWorld({ heightAt });
109
+ world.addCylinder(5, 0, 0.5, 0, 2);
110
+ const near = routeClearance(world, [0, 0, 10, 0, 10, 10], { minY: 0, maxY: 1.8 });
111
+ console.log(near.distance, near.solid);
112
+ ```
113
+
114
+ ## Pack check
115
+
116
+ `pnpm check:pack` (`tools/pack/check.sh`) checks the package in the shape npm would get. It runs `pnpm pack` in `packages/wallhammer-web` (which builds `dist/` first: JavaScript and type declarations from `tsconfig.build.json`, and swaps the package's `exports` for the ones in `publishConfig`), installs the tarball into an empty project outside the workspace, imports every entry in plain Node and type-checks a small program against the packed declarations. It needs the network for the package's own dependency. Its last line is `ok: the packed package installs, loads and type-checks`.
117
+
118
+ In the workspace the package exports its TypeScript sources (`exports` → `src/`); only the packed package points at `dist/`. Publish with `pnpm publish`, not `npm publish`: only pnpm applies `publishConfig.exports`.
119
+
120
+ ## Screenshots
121
+
122
+ `tools/shot/shot.mjs` takes reproducible screenshots of fixed views of the example pages. It runs **on the host**, not in Docker, because the real GPU decides the image. It drives the host's installed Chrome through `puppeteer-core` against the example pages that the `dev` container serves. Its own `node_modules` must be installed in `tools/shot/`.
123
+
124
+ ```sh
125
+ cd tools/shot
126
+ node shot.mjs --url http://127.0.0.1:5281/minimal-3d/ --tod 13,21 # the minimal-3d example
127
+ ```
128
+
129
+ Pictures in Docker, on the software renderer and independent of the host's graphics card, come from `tools/shot/page-shot.mjs` in the `shot` service (options in its header).
130
+
131
+ Animation time is frozen at the given value, so the same input gives the same image. Pages expose a small script interface on `window.__wh` (views, time, weather, stats, benchmark) that the tool uses.
132
+
133
+ ## Benchmarks
134
+
135
+ `tools/bench/` measures cost per frame, startup, hitches, memory and streaming. Like the screenshot tool it runs on the host and reuses its `puppeteer-core` and Chrome. `bench.mjs` has the commands (`frames`, `counts`, `startup`, `hitches`, `memory`, `scale`, `shadow`, `hit`, `flight`, `profile`); `run-all.sh` runs the whole set one after another. Results go to `tools/bench/out/`, which git ignores. Headless Chrome caps presentation at 30 fps, so results are cost per frame from synchronous renders, never fps.
136
+
137
+ Do not run two browser tools at once; they compete for the GPU.
138
+
139
+ ## Frame profile
140
+
141
+ `profileFrame(renderer, view, options?)` from `wallhammer-web/tools` answers "what is slow" with numbers, inside the page, on whatever graphics card the page runs on. It renders the current view synchronously, waits for the graphics after every frame (`Device.finish`, which reads one pixel and so blocks until the frame is done) and keeps the median of `frames` frames (default 20, after two warm-up frames) per measurement:
142
+
143
+ | Field | Measurement |
144
+ | --- | --- |
145
+ | `empty` | Only clearing and presenting the main target (no bounds, no layers). |
146
+ | `kept` | The current frame; the shadow map is kept as the renderer keeps it. `shadowFrames` says in how many frames it was redrawn anyway (a layer's `cullStale`, `invalidateShadows` from the app). |
147
+ | `shadow` | The current frame with the shadow map redrawn in every frame. |
148
+ | `running` | Only with `options.step`: `step(i)` advances the scene before every frame (clocks, extraction), so this is the frame of a moving scene with the shadow updates the motion causes. The step's own time is part of it. |
149
+ | `layers` | Per layer in drawing order: `name` (`Layer.name`, else the class name and the material name), `passes` it drew in, and for `color` (the main passes with `prepare`) and `shadow` its triangles, calls and `ms`: the frame time with the layer minus the frame time without it (`kept` for colour, `shadow` for the shadow pass). Every layer is measured, also one that does not count its draws (`DrawContext.count`); its counts are then 0. `ms` is null only with `options.layers: false`. |
150
+
151
+ Besides that the profile holds the target size in physical pixels, `dpr`, `samples` of the main target, `shadowMapEdgePx` and `shadowMapPx` (texture edge and the part in use), the GPU name, `syncMs` (the wait with nothing pending, included in every time), the `FrameStats` of a frame with the shadow map redrawn, and `spreadMs` (interquartile range) for every timing: a layer cost below the spread is noise and may even come out negative.
152
+
153
+ `formatProfile(profile)` returns the same as a fixed-width text table. A sample, given an app's renderer and view:
154
+
155
+ <!-- check: wrap -->
156
+ ```ts
157
+ import type { View } from 'wallhammer-web/base';
158
+ import type { Renderer } from 'wallhammer-web/render';
159
+ import { formatProfile, profileFrame } from 'wallhammer-web/tools';
160
+ declare const renderer: Renderer;
161
+ declare const view: View;
162
+
163
+ const profile = profileFrame(renderer, view, { frames: 20 });
164
+ console.log(formatProfile(profile));
165
+ const worst = [...profile.layers].sort((a, b) => (b.color.ms ?? 0) - (a.color.ms ?? 0))[0];
166
+ ```
167
+
168
+ Rules for reading it:
169
+
170
+ - The page is blocked while it runs: about `frames × (3 + 2 × layers)` frames plus warm-ups. `options.layers: false` skips the per-layer measurements (counts stay).
171
+ - Frames are waited for one by one, so a time is the frame's latency, processor and graphics in series. With the processor time per frame small (`cpuMs`), that is the graphics cost.
172
+ - Leaving a layer out changes only that layer's draws; culling runs as before. The shadow map is marked for a redraw at the end, so the next normal frame is whole again.
173
+ - Numbers from a software renderer (headless Chrome in Docker, SwiftShader) say nothing about a real graphics card. Profile in a browser on the machine in question.
174
+
175
+ It uses two renderer hooks that are idle in normal use: `Layer.name` and `Renderer.probe` ([Rendering](rendering.md#statistics-and-benchmarks)). An example exposes it on `window.__wh` (the fantasy village: `__wh.profile(frames?)` and `__wh.profileText(frames?)`), so a browser tool or a person in the console can call it. The host-side benchmark tool (`tools/bench`) patches the renderer from outside for per-pass timer queries; it names layers by `Layer.name` when set.
@@ -0,0 +1,262 @@
1
+ # Walking
2
+
3
+ Moving a body over a world: the collision world answers where the ground and the sides are, a walker moves over it
4
+ in fixed steps, a follow camera stays behind it ([`FollowRig`](cameras.md#followrig)). Everything here runs in plain
5
+ Node: no DOM, no graphics. `pnpm check:walk` checks it without a browser
6
+ (`tools/walk/`).
7
+
8
+ ## Collision world
9
+
10
+ `CollisionWorld` (`wallhammer-web/world`) is a base surface given as a height function plus upright solids: prisms
11
+ over an outline, cylinders and turned boxes (a box is a prism with four corners). Solids are listed in a uniform grid
12
+ of cells (`cellSize`, default 8 m); a query visits only the cells it touches. Queries allocate nothing: results go
13
+ into an object the caller passes and reuses. The hot paths use only `+ − × ÷` and `Math.sqrt`, so the same inputs
14
+ give the same bits.
15
+
16
+ <!-- check: wrap -->
17
+ ```ts
18
+ import { CollisionWorld, newRayHit, newSlideResult } from 'wallhammer-web/world';
19
+ import { HeightField } from 'wallhammer-web/gen-core';
20
+
21
+ declare const field: HeightField;
22
+
23
+ const world = new CollisionWorld({
24
+ heightAt: (x, z) => field.heightAt(x, z),
25
+ baseMinY: field.minY, // optional: a ray only searches for the base between these
26
+ baseMaxY: field.maxY,
27
+ });
28
+ const block = world.addBox(10, 10, 2, 1, 0.3, 0, 3, { tag: 1 }); // centre, half extents, yaw, minY, maxY
29
+ world.addCylinder(14, 10, 0.4, 0, 4);
30
+ world.addPrism([0, 0, 4, 0, 4, 1, 0, 1], 0, 0.3); // a step 0.3 m high
31
+ world.addPrism([20, 0, 30, 0, 30, 30, 20, 30], -1, 50, { standable: false, blocksSight: false }); // an invisible limit
32
+
33
+ // Per step of a mover: ground under the feet, sides at the height of the body above the step height.
34
+ const slid = newSlideResult();
35
+ let x = 1;
36
+ let z = -1;
37
+ let y = world.groundAt(x, z, 0, 0.35, 0.3);
38
+ world.slide(x, z, 0.3, y + 0.35, y + 1.7, 0.05, 0.02, slid);
39
+ x = slid.x;
40
+ z = slid.z;
41
+ y = world.groundAt(x, z, y, 0.35, 0.3);
42
+ const headroom = world.ceilingAt(x, z, y + 1.7, 0.3); // Infinity when open
43
+
44
+ // A ray and a camera boom.
45
+ const hit = newRayHit();
46
+ if (world.raycast(x, y + 1.6, z, 1, -0.2, 0, 50, hit)) console.log(hit.t, hit.solid, hit.tag, hit.nx, hit.ny, hit.nz);
47
+ const boom = world.clearance(x, y + 1.6, z, -1, 0.5, 0, 4, 0.2); // how far a sphere of 0.2 m gets, at most 4 m
48
+
49
+ world.remove(block); // other ids stay valid
50
+ ```
51
+
52
+ | Member | Meaning |
53
+ | --- | --- |
54
+ | `new CollisionWorld({ heightAt, cellSize?, baseMinY?, baseMaxY?, baseStep?, baseExtent? })` | The base surface as a height function. `baseMinY`/`baseMaxY` bound it (a ray above the highest point skips the search); `baseStep` is the horizontal step of the ray search on it (default 0.5 m); `baseExtent` (`[minX, minZ, maxX, maxZ]`) is where the base exists, so a ray that leaves it stops searching. Without an extent and without a finite `maxT`, a ray that misses everything searches the base for 1e5 lengths, which takes milliseconds. |
55
+ | `baseHeightAt(x, z)`, `baseSlopeAt(x, z, out)` | The base height at a point; its gradient (rise per metre along x and z) into `out` and its length, the tangent of the slope (central differences 0.05 m apart). |
56
+ | `addPrism(outline, minY, maxY, options?)` | Upright prism over a closed outline of x, z pairs (either winding, may be concave, a repeated closing point is dropped). Returns the id. |
57
+ | `addCylinder(x, z, radius, minY, maxY, options?)`, `addBox(x, z, halfX, halfZ, yawRad, minY, maxY, options?)` | A cylinder; a turned box (local +x points to (cos yaw, −sin yaw), as a view's yaw turns). |
58
+ | `SolidOptions` | `standable` (default true: its top is ground), `blocksSight` (default true: stops rays and booms; false for invisible limits), `tag` (the caller's number, returned in hits). |
59
+ | `remove(id)`, `has(id)`, `solidCount` | Ids are never reused, so removing one leaves the others valid. A removed or unknown id is ignored. |
60
+ | `groundAt(x, z, y, maxStepUp, radius?)` | The highest of the base and of the standable tops at most `y + maxStepUp`. The base counts always. With `radius`, a top counts when the solid reaches within that distance of the point (a body stands on an edge). |
61
+ | `ceilingAt(x, z, y, radius?)` | The lowest underside at or above `y`; Infinity when open. Every solid counts. |
62
+ | `slide(x, z, radius, minY, maxY, dx, dz, out)` | Moves a circle against the sides of the solids whose height span overlaps `minY`..`maxY` (touching does not count; the base is not a side). It slides along a side, stops in a corner, never ends inside a solid: a circle that starts inside is pushed out the shortest way first. The move is split into sub-steps of at most half the radius, so it does not pass a side thinner than that. `out.hit`, `out.nx`, `out.nz`, `out.solid` tell the last contact. |
63
+ | `raycast(ox, oy, oz, dx, dy, dz, maxT, out)` | The first hit with the base and the solids that block sight, for t in 0..`maxT` (t in lengths of the direction). The normal is unit and turned against the ray; `solid` and `tag` are −1 for the base. |
64
+ | `clearance(ox, oy, oz, dx, dy, dz, maxDist, radius)` | How far a sphere gets along the direction, in metres, at most `maxDist`: the centre line is cast as a ray first, then the sphere is tested every `radius` metres and the contact refined by bisection. 0 when the sphere overlaps something at the origin. Pass it to `FollowRig` as the boom clearance. |
65
+ | `forEachSolid(fn)`, type `SolidInfo` | Every solid with its shape and options, for debug drawing (allocates). |
66
+ | `newRayHit()`, `newSlideResult()` | Result objects to allocate once and reuse. |
67
+
68
+ The base surface is not a side: a mover decides by itself what slope it climbs. Tops count only through `groundAt`, so
69
+ a step lower than the mover's step height is left out of `slide` by passing `minY` above it.
70
+
71
+ The ray search of the base steps along the ray `baseStep` metres at a time and refines the intersection by bisection, the
72
+ same search as `raycastHeightField` (both use one function). A ridge narrower than the step can be missed.
73
+
74
+ CPU time in plain Node in the development container, a world of 2,000 solids on a height field, mean of 10,000
75
+ calls (`pnpm check:walk` prints it each run): a 30 m `raycast` about 2 µs on a quiet machine (up to 8 µs measured
76
+ while the machine was busy), a `slide` of one step 1–3 µs, `groundAt` under 1 µs, a 4 m `clearance` 5–15 µs.
77
+
78
+ ## Walker
79
+
80
+ `Walker` (`wallhammer-web/world`) is a kinematic body, an upright cylinder of `radius` and `height` with its feet at
81
+ `position`, that moves over a `CollisionWorld` in fixed steps of `1 / stepHz` seconds. Each step:
82
+
83
+ 1. The wanted velocity is the intent's direction (clamped to length 1) times `walkSpeed` or `runSpeed`. The horizontal
84
+ velocity moves toward it by at most `acceleration` per second (braking the same way); in the air only
85
+ `airControl` of it.
86
+ 2. A jump (`intent.jump`) starts only from the ground, not from a slope too steep to stand on: the vertical speed
87
+ becomes `jumpSpeed`.
88
+ 3. The body slides by its velocity with `slide`, against the sides of solids between `maxStepUp` above the feet and
89
+ the head, so a step up to `maxStepUp` is not a side. Velocity into the touched side is dropped: the body slides
90
+ along a wall and rests in a corner. A base surface steeper than `maxSlopeDeg` that rises ahead takes the uphill
91
+ part of the move away. The slide runs even standing still, so a solid that appears over the body pushes it out.
92
+ 4. On the ground the feet follow `groundAt` (the highest base or standable top within `maxStepUp` above, the body
93
+ standing on an edge while its circle touches the top). The ground may also drop by up to `maxStepUp` plus the drop
94
+ of the base over the move, so the body walks down steps and slopes; a bigger drop starts a fall. In the air the
95
+ height follows gravity exactly (the top of a jump is `jumpSpeed² / (2 gravity)` at any step rate), the head stops
96
+ at `ceilingAt`, and the body lands on the first ground it meets.
97
+ 5. On a base surface steeper than `maxSlopeDeg` (`steep`), the body slides downhill (the horizontal part of gravity
98
+ along the incline); the intent steers it across and may speed it downhill but not brake or climb. The slope is
99
+ steep only when the base rises steeply on both sides of the feet (over 5 cm each way along the gradient): at the
100
+ flat lip of a cliff or a pit the central slope straddles the kink, and the body must still be able to walk away.
101
+ 6. `yaw` turns toward the wanted direction (or, without an intent, the direction moved) at most `turnSpeed` rad/s.
102
+
103
+ `advance(dt, intent)` takes real seconds, runs the steps due and carries the rest to the next call, so the path does not
104
+ depend on the frame rate: one call of 1/30 s and two of 1/60 s end in the same place. At most `maxStepsPerAdvance`
105
+ steps run per call (the rest of a long stall is dropped). A jump asked while no step is due is kept for the next one.
106
+ `renderPosition(out)` and `renderYaw()` give the pose between the last two steps for drawing; a step up or down is
107
+ eased in the drawn height over `stepSmoothing` seconds, the simulated position is not. Only `+ − × ÷`, `Math.sqrt` and
108
+ the reproducible `detAtan2` run in a step, so the same inputs give the same path bit for bit.
109
+
110
+ The heading has the convention of a view's yaw: yaw 0 faces −z, the facing direction is (−sin yaw, −cos yaw). A
111
+ `FollowRig` with `yawDeg` equal to the walker's yaw in degrees looks the way the body faces, and the rig's `forward`
112
+ turns a "forward and right" input into the world direction of the intent.
113
+
114
+ <!-- check: wrap -->
115
+ ```ts
116
+ import { CollisionWorld, Walker, newWalkIntent } from 'wallhammer-web/world';
117
+
118
+ const world = new CollisionWorld({ heightAt: (x, z) => 0.1 * x + 0.05 * Math.sin(z) });
119
+ world.addBox(6, 0, 2, 2, 0, 0, 0.3); // a step the body walks up
120
+ world.addBox(6, 6, 0.2, 4, 0, 0, 3); // a wall it slides along
121
+
122
+ const body = new Walker(world, { runSpeed: 5, jumpSpeed: 4 }); // the rest from DEFAULT_WALKER
123
+ body.teleport(0, 0, 0);
124
+ const intent = newWalkIntent(); // allocate once, reuse every frame
125
+ const drawAt = new Float64Array(3);
126
+
127
+ // Once per frame: the intent from the input, the walker advanced by the frame's real seconds.
128
+ function frame(dtSeconds: number, forward: number, right: number, cameraYawRad: number): void {
129
+ // Forward and right in the camera's frame to a world direction (yaw 0 faces −z).
130
+ const s = Math.sin(cameraYawRad);
131
+ const c = Math.cos(cameraYawRad);
132
+ intent.moveX = -s * forward + c * right;
133
+ intent.moveZ = -c * forward - s * right;
134
+ intent.run = false;
135
+ intent.jump = false;
136
+ body.advance(dtSeconds, intent);
137
+ body.renderPosition(drawAt); // draw the figure here, turned by body.renderYaw()
138
+ }
139
+ frame(1 / 60, 1, 0, 0);
140
+ console.log(body.position, body.velocity, body.grounded, body.steep, body.yaw, body.travelled);
141
+ ```
142
+
143
+ | Member | Meaning |
144
+ | --- | --- |
145
+ | `new Walker(world, setup?)`, `setup` | `WalkerSetup` over `DEFAULT_WALKER`: `radius` 0.3, `height` 1.7, `walkSpeed` 1.6, `runSpeed` 4.5 m/s, `acceleration` 20 m/s², `airControl` 0.3, `jumpSpeed` 4.2 m/s (0: no jumps), `gravity` 9.81, `maxStepUp` 0.35 m, `maxSlopeDeg` 45, `stepHz` 60, `turnSpeed` 12 rad/s, `stepSmoothing` 0.1 s, `maxStepsPerAdvance` 15. |
146
+ | `position`, `velocity` | Feet and velocity (x, y, z), `Float64Array`s; read them, change them through `teleport`. |
147
+ | `yaw`, `grounded`, `steep` | Heading in radians; standing on ground; standing on a base too steep to climb (sliding). |
148
+ | `travelled`, `steps` | Horizontal metres moved (for the stride of an animation); fixed steps since the last `teleport`. |
149
+ | `renderTravelled(alpha?)`, `lastStepDistance` | `travelled` between the last two steps for drawing (a stride in step with `renderPosition`); horizontal metres of the last step (÷ `stepSeconds`: the speed), 0 after a `teleport`. |
150
+ | `advance(dt, intent)` | Runs the fixed steps due in `dt` real seconds; returns how many ran. |
151
+ | `step(intent)`, `stepSeconds` | One fixed step, for scripts and tests; its length in seconds. |
152
+ | `renderPosition(out)`, `renderYaw()`, `alpha` | The pose between the last two steps for drawing; the share of the way to the next step. |
153
+ | `teleport(x, y, z, yaw?)` | Puts the feet at a point with no velocity; the body settles onto the ground in the next step. |
154
+ | `WalkIntent`, `newWalkIntent()` | `moveX`, `moveZ` (world direction, length at most 1), `run`, `jump` (true in the step a jump is asked). |
155
+
156
+ CPU time of one step in plain Node in the development container, in a world of 2,000 solids, mean of 10,000 steps
157
+ (`pnpm check:walk` prints it each run): 3–4 µs, up to 15 µs measured while the machine was heavily loaded (target 20 µs).
158
+
159
+ ### Saving and restoring
160
+
161
+ `saveState(out?, offset?)` writes the walker's whole moving state (position, velocity, yaw, ground and jump flags,
162
+ travelled distance, step count, the previous pose and distance for interpolation and the step remainder) as `WALKER_STATE_BYTES`
163
+ (160) bytes: 20 doubles, the first a format version. `loadState(bytes, offset?)` restores it into a walker of the same
164
+ setup and world. Without `out` the bytes are the walker's own scratch: copy them to keep them.
165
+
166
+ `simState(name)` wraps both as a part of a fixed-step simulation's state (the shape of `SimState` of `sim`; `world`
167
+ does not import `sim`, the two only agree on `bytes` and `into`), so `Simulation.addState(walker.simState('walker'))`
168
+ saves, restores and hashes it with the rest. Step the walker from a system of that simulation with `step(intent)`, one
169
+ step per tick, and draw it with the simulation's alpha: `renderPosition(out, alpha)`, `renderYaw(alpha)` and
170
+ `renderTravelled(alpha)` take an external share of the way (clamped to 0..1) in place of the walker's own `alpha`. A
171
+ stride animation reads its phase from `renderTravelled` and its weight from the speed of the last step,
172
+ `lastStepDistance / stepSeconds`, so nothing outside the simulation's state has to be kept or reset.
173
+
174
+ <!-- check: wrap -->
175
+ ```ts
176
+ import { Simulation } from 'wallhammer-web/sim';
177
+ import { CollisionWorld, Walker, newWalkIntent } from 'wallhammer-web/world';
178
+
179
+ const world = new CollisionWorld({ heightAt: () => 0 });
180
+ const walker = new Walker(world, { stepHz: 60 });
181
+ const sim = new Simulation({ seed: 'walk', hz: 60 });
182
+ sim.addState(walker.simState('walker'));
183
+ const intent = newWalkIntent();
184
+ intent.moveX = 1;
185
+ sim.addSystem('walk', () => walker.step(intent));
186
+ const kept = walker.saveState().slice();
187
+ walker.loadState(kept);
188
+ const at = [0, 0, 0];
189
+ walker.renderPosition(at, sim.alpha);
190
+ const stride = walker.renderTravelled(sim.alpha) / 1.4; // passes of a 1.4 m walk cycle
191
+ const speed = walker.lastStepDistance / walker.stepSeconds; // m/s over the last tick
192
+ ```
193
+
194
+ ### Solids from a mesh
195
+
196
+ For compact things whose solid is roughly their footprint, `meshPrismFootprint(positions, options?)` gives the
197
+ upright prism over the convex hull (in x, z) of a mesh's vertices, from its lowest to its highest vertex, and
198
+ `meshCylinderFootprint` the upright cylinder round the centroid of that hull reaching its farthest corner.
199
+ `addMeshSolid(world, positions, options?)` adds either (`shape: 'prism'` default, or `'cylinder'`) to a
200
+ `CollisionWorld` with the usual `SolidOptions` and returns the id (−1 for no footprint). Options (`MeshFootprintOptions`):
201
+
202
+ | Option | Default | Meaning |
203
+ | --- | --- | --- |
204
+ | `stride` | 3 | Numbers per vertex, the position first. |
205
+ | `indices` | none | Only the vertices these name count. |
206
+ | `from`, `to` | whole buffer | A vertex range (a group in a shared buffer); ignored with `indices`. |
207
+ | `transform` | none | 12 numbers, mesh → world (a `Mat34`, the same layout as an instance record). |
208
+ | `below` | all | Only vertices at most this far above the lowest one shape the outline: an overhang the body passes under is left out. |
209
+ | `grow` | 0 | Moves the corners outward (negative: inward), metres. |
210
+ | `snap` | 0.05 | Outline points are rounded to this grid before the hull (0: exact). |
211
+
212
+ `convexHullXZ(points)` is the hull itself (x, z pairs, counter-clockwise, no collinear points). These run at build time
213
+ and allocate. A hull fills in concave shapes: an L-shaped thing needs one solid per arm.
214
+
215
+ <!-- check: wrap -->
216
+ ```ts
217
+ import { mat34Translation } from 'wallhammer-web/base';
218
+ import { CollisionWorld, addMeshSolid, meshCylinderFootprint } from 'wallhammer-web/world';
219
+ declare const positions: Float32Array; // x, y, z per vertex
220
+
221
+ const world = new CollisionWorld({ heightAt: () => 0 });
222
+ const place = mat34Translation(10, 0, 4);
223
+ const id = addMeshSolid(world, positions, { transform: place, below: 2.2, grow: 0.05, standable: false });
224
+ const round = meshCylinderFootprint(positions, { transform: place });
225
+ if (round) world.addCylinder(round.x + 3, round.z, round.radius, round.minY, round.maxY);
226
+ console.log(id);
227
+ ```
228
+
229
+ ### Seeing the solids
230
+
231
+ `collisionLines(world, options?)` in `wallhammer-web/tools` draws the solids of a collision world as a wireframe
232
+ (`LINE_LAYOUT` lines, drawn with a one-colour line material): a prism as its outline at the bottom and the top with an
233
+ upright at each corner, a cylinder as two circles with four uprights. `select(info, id)` keeps only some solids (draw
234
+ standable, blocking and invisible ones in different colours), `segments` sets the circle (default 16), `floorY` cuts
235
+ off the bottom of solids that reach far below the ground. Build it once, after the solids are added; it is a debugging
236
+ view, not drawn in normal use. The walking example (`examples/walk`, key `C`) shows it.
237
+
238
+ <!-- check: wrap -->
239
+ ```ts
240
+ import { CollisionWorld } from 'wallhammer-web/world';
241
+ import { collisionLines } from 'wallhammer-web/tools';
242
+
243
+ const world = new CollisionWorld({ heightAt: () => 0 });
244
+ world.addBox(0, 0, 1, 1, 0, 0, 2, { standable: false });
245
+ const standable = collisionLines(world, { select: (s) => s.standable });
246
+ const blocking = collisionLines(world, { select: (s) => !s.standable, segments: 24, floorY: -1 });
247
+ console.log(standable.count, blocking.count);
248
+ ```
249
+
250
+ ### Not built
251
+
252
+ - A curved world (a sphere, up pointing away from a centre). The world is flat with +y up. The places where a local
253
+ up would replace y are marked `UP:` in `src/world/collide.ts`: the vertical span of a solid in `slide`, the base
254
+ height in `groundAt`, the height above the base in `clearance`; and in `src/world/walker.ts`: gravity, the height
255
+ span of the body, the slope of the base and the plane of the heading.
256
+ - Sloped or shaped tops: the top of a solid is flat at `maxY`. Ramps are made of the base surface or of thin steps.
257
+ - Moving solids. Remove and add again to move one (the grid lists are updated each time). A walker standing on a
258
+ solid is not carried with it.
259
+ - For the walker: sloped tops of solids (a ramp is the base surface), crouching, swimming, ledges to hang from,
260
+ being pushed by other bodies (two walkers do not see each other), and a solid lower than `maxStepUp` that cannot be
261
+ stood on (`standable: false`) is neither a side nor ground, so the body walks through it. A step up is not checked
262
+ against a ceiling over the step.