wallhammer-web 0.0.0-stage → 0.4.1

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 +92 -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/rigs.md ADDED
@@ -0,0 +1,203 @@
1
+ # Rigs and actors
2
+
3
+ A rig is an instanced, animated model made of rigid parts. The vertex shader poses every part from the instance record (position, heading, distance travelled, speed, turn rate, seed, state) with closed-form functions: legs swing in a gait, wheels roll and steer, bodies roll in curves and bob, people look around while they stand. Nothing is stored between frames, so a jump in time poses correctly at once, and thousands of instances cost one draw per kind and level of detail.
4
+
5
+ - The description is plain data in `base` (`RigDesc`, `RigPart`, `RIG_INSTANCE_FLOATS`, `writeRigInstance`).
6
+ - `gen-mesh` builds the part meshes; `render` draws them in `RigLayer`.
7
+ - Concrete rigs (people, vehicles, stop furniture) are content of the app; the campus app keeps them in one folder of its own, the walking example in `examples/walk/src/`.
8
+
9
+ ## The description
10
+
11
+ Local axes of every rig: x to the right of travel, y up, z forward, the origin on the ground under the anchor. A part has a shape (`box`, `frustum`, `roller`, `rod`), a place (`at`), an optional pivot and a motion:
12
+
13
+ | Motion | Meaning |
14
+ | --- | --- |
15
+ | `fixed` | Moves with the body (bob, roll, sway). |
16
+ | `spin`, `spin-steer` | Turns about x by distance / `amount` (a wheel of that radius); `spin-steer` also steers by the curvature (`steerBase`). |
17
+ | `limb` | A leg of length `amount`, swinging in the gait; the foot stays put during the stance half. `phase` 0 or 0.5 picks the side; with the free gait any phase. |
18
+ | `swing` | Swings in the gait by up to `amount` radians (arms, a bag). |
19
+ | `look` | Turns about y while standing, slowly. |
20
+ | `wobble` | Small noise about x and y. |
21
+ | `bend` | A link of a chain: turns about the chain's root, about its `axis`, more the farther it is from the root. See [Free gait and chains](#free-gait-and-chains). |
22
+
23
+ Colour comes from one of four instance colour slots times `tint`, or from `tint` alone. `finish` makes a part glass, a front or rear lamp (lit by `RigLayer.lamps`), a lit interior (`glow`) or a paved top (`tiles`, a world-aligned 0.5 m grid). `variant` shows a part only when the instance sets that bit (a backpack). `nearOnly` drops it from the far level of detail. A rig has one or two segments; the second (an articulated vehicle's trailer) gets its own anchor and heading in the record.
24
+
25
+ ## Free gait and chains
26
+
27
+ Two optional parts of a description serve bodies on more than two limbs and long bodies. A description without them is drawn by the same program, with the same mesh bytes, as before they existed; one with them (`rigExtended(desc)` is true) is drawn by a second program that `RigLayer` makes when the first such kind is added.
28
+
29
+ - **Free gait** (`gait: 'free'`): every `limb` plants its own end point, for any `phase` and any `amount`. The end point is the point `amount` under the pivot at rest. With `f = fract(distance / (stride · scale) + seed + phase)` it lies on the ground and moves backward at exactly the speed of travel for `f < 0.5`, and comes forward on a smooth step, lifted by at most 0.22 · `amount`, for the rest of the cycle. The limb is aimed at its end point and stretched along its own length, so a pivot between 0.8 and 1.2 times `amount` above the ground still keeps the end point down; put the pivot at `amount` for a limb that is never stretched at rest. The body dips by `dip` twice per cycle and keeps the sway. The gait fades in between the two speeds of `walkSpeed` (times the height scale), so a slow or small rig walks without sliding. Standing and at the far level of detail every limb is at rest.
30
+ - **Chains** (`motion: 'bend'`): the links of one chain share their `pivot`, the root of the chain. Every vertex of a link turns about the root, about the link's `axis` (default `y`), by `amount · d · wave` radians, `d` its rest distance from the root in metres and `wave` a sine of the gait phase lagged by `phase` cycles per metre along the chain (a slow sway of 0.4 of it while standing). The turn is zero at the root and continuous along the chain, so the chain never leaves the body and its links stay joined; give the links of one chain the same `amount`, `phase` and `axis`.
31
+
32
+ Content rules: keep `stride ≤ 3.6 · amount` for every limb (the pair gait clamps the swing there), and with the free gait a stride near 2 · `amount` and a small `dip` keep the stretch of a limb low.
33
+
34
+ <!-- check: wrap -->
35
+ ```ts
36
+ import { rigExtended } from 'wallhammer-web/base';
37
+ import type { RigDesc, RigPart } from 'wallhammer-web/base';
38
+
39
+ /** A body on four limbs of two lengths, with a chain of three links at the front that bends sideways. */
40
+ const limb = (x: number, z: number, length: number, phase: number): RigPart => ({
41
+ shape: { kind: 'box', size: [0.1, length, 0.1] },
42
+ at: [x, length / 2, z],
43
+ pivot: [x, length, z],
44
+ motion: 'limb',
45
+ amount: length,
46
+ phase,
47
+ slot: 1,
48
+ });
49
+ const chain = (i: number): RigPart => ({
50
+ shape: { kind: 'box', size: [0.2, 0.2, 0.3] },
51
+ at: [0, 0.9, 0.7 + 0.3 * i],
52
+ pivot: [0, 0.9, 0.55],
53
+ motion: 'bend',
54
+ axis: 'y',
55
+ amount: 0.3,
56
+ phase: 0.2,
57
+ slot: 0,
58
+ });
59
+ const body: RigDesc = {
60
+ name: 'four limbs',
61
+ parts: [
62
+ { shape: { kind: 'box', size: [0.5, 0.4, 1.2] }, at: [0, 0.95, 0], slot: 0 },
63
+ limb(-0.2, 0.45, 0.8, 0),
64
+ limb(0.2, 0.45, 0.8, 0.5),
65
+ limb(-0.2, -0.45, 0.75, 0.25),
66
+ limb(0.2, -0.45, 0.75, 0.75),
67
+ chain(0),
68
+ chain(1),
69
+ chain(2),
70
+ ],
71
+ segments: [{ shadow: [0.4, 0.8, 0] }],
72
+ stride: 1.6,
73
+ gait: 'free',
74
+ dip: 0.03,
75
+ walkSpeed: [0.1, 0.6],
76
+ height: 1.2,
77
+ radius: 1.4,
78
+ };
79
+ console.log(rigExtended(body));
80
+ ```
81
+
82
+ ## Drawing instances
83
+
84
+ <!-- check: wrap -->
85
+ ```ts
86
+ import { RIG_INSTANCE_FLOATS, packRgb, writeRigInstance } from 'wallhammer-web/base';
87
+ import type { RigDesc, RigInstance } from 'wallhammer-web/base';
88
+ import { RigLayer } from 'wallhammer-web/render';
89
+ import type { Renderer } from 'wallhammer-web/render';
90
+ import { POSE_STRIDE } from 'wallhammer-web/sim';
91
+ import type { Movers } from 'wallhammer-web/sim';
92
+ declare const renderer: Renderer;
93
+ declare const people: Movers;
94
+ declare const groundAt: (x: number, z: number) => number;
95
+
96
+ /** A minimal walker: a body on two legs that swing in the gait, coloured from instance slots 0 and 1. */
97
+ const walker: RigDesc = {
98
+ name: 'walker',
99
+ parts: [
100
+ { shape: { kind: 'frustum', r0: 0.18, r1: 0.14, height: 0.75, sides: 8 }, at: [0, 0.85, 0], slot: 0, tint: [1, 1, 1] },
101
+ { shape: { kind: 'box', size: [0.12, 0.85, 0.14] }, at: [-0.1, 0.42, 0], pivot: [-0.1, 0.85, 0], motion: 'limb', amount: 0.85, phase: 0, slot: 1, tint: [1, 1, 1] },
102
+ { shape: { kind: 'box', size: [0.12, 0.85, 0.14] }, at: [0.1, 0.42, 0], pivot: [0.1, 0.85, 0], motion: 'limb', amount: 0.85, phase: 0.5, slot: 1, tint: [1, 1, 1] },
103
+ ],
104
+ segments: [{ shadow: [0.3, 0.3, 0] }],
105
+ height: 1.6,
106
+ radius: 0.5,
107
+ };
108
+
109
+ const rigs = new RigLayer(renderer);
110
+ renderer.add(rigs);
111
+ const FIGURES = 2000;
112
+ const kind = rigs.addKind(walker, FIGURES);
113
+ const pose = new Float32Array(FIGURES * POSE_STRIDE);
114
+ // One look per person, keyed by the `tag` given at spawn (rows move around; tags do not).
115
+ const looks = Array.from({ length: FIGURES }, (_, i) => ({
116
+ heightScale: 0.9 + 0.2 * ((i * 7) % 10) / 10,
117
+ widthScale: 1,
118
+ variants: 0,
119
+ colors: [packRgb(0.3, 0.35, 0.5), packRgb(0.2, 0.2, 0.25), 0, 0] as const,
120
+ }));
121
+ const r: RigInstance = { x: 0, y: 0, z: 0, slope: 0, dirX: 0, dirZ: 1, x1: 0, y1: 0, z1: 0, slope1: 0, dirX1: 0, dirZ1: 1, distance: 0, speed: 0, turnRate: 0, seed: 0, state: 0, heightScale: 1, widthScale: 1, variants: 0, colors: [0, 0, 0, 0] };
122
+
123
+ /** Every frame: poses from the simulation into instance records. */
124
+ function frame(alpha: number, lamps: number): void {
125
+ const n = people.extractPose(alpha, pose);
126
+ const out = rigs.staging(kind);
127
+ for (let i = 0; i < n; i++) {
128
+ const o = i * POSE_STRIDE;
129
+ const look = looks[people.table.col.tag[i]! % FIGURES]!;
130
+ r.x = r.x1 = pose[o]!;
131
+ r.z = r.z1 = pose[o + 1]!;
132
+ r.y = r.y1 = groundAt(r.x, r.z);
133
+ r.dirX = r.dirX1 = pose[o + 2]!;
134
+ r.dirZ = r.dirZ1 = pose[o + 3]!;
135
+ r.distance = pose[o + 4]!;
136
+ r.speed = pose[o + 5]!;
137
+ r.turnRate = pose[o + 6]!;
138
+ r.state = r.speed > 0.05 ? 0 : 1;
139
+ r.heightScale = look.heightScale;
140
+ r.widthScale = look.widthScale;
141
+ r.variants = look.variants;
142
+ r.colors = look.colors;
143
+ writeRigInstance(out, i, r);
144
+ }
145
+ rigs.commit(kind, n);
146
+ rigs.lamps = lamps;
147
+ }
148
+ ```
149
+
150
+ `RIG_INSTANCE_FLOATS` (24) floats per record; `staging` + `commit` fill in place, `set(kind, data, count)` copies. The layer culls each kind against the view every frame and splits it into near (all parts, animated), far (fewer parts, still) and hidden by the size on screen (`farPx`, `hidePx`). Rigs receive shadows and stand on a soft contact shadow; by default they do not cast into the shadow map (see below).
151
+
152
+ A rig that never moves (stop furniture, a parked vehicle) is written once with state 2 and committed once; the layer still culls it every frame.
153
+
154
+ The field `state` (float 16, `i_look.x` in GLSL) is **not read by any shader of the engine**: a standing rig stands because its speed is 0, not because of its state. It is kept in the record for the owner and for a game material that wants it.
155
+
156
+ ## A material of the game, shadows into the map
157
+
158
+ The posing is a vertex include of its own, `RIG_POSE_GLSL`, which `RigLayer` registers as `<rig-pose>`. It declares the attributes and the instance record (`RIG_ATTRIBS`), the uniforms the layer sets (`u_rig`, `u_rig2`, and `u_rig3` where `WH_RIG_EXT` is defined) and two functions: `bool rigPose(out vec3 pos, out vec3 nrm)`, the world position and normal of the vertex in its instance's pose (false: the instance lacks the part's variant, collapse the vertex), and `vec3 rigColor()`, the part's colour times its instance colour slot. Write it after `<header>` and `<noise>`.
159
+
160
+ `new RigLayer(renderer, options)` takes `RigLayerOptions`:
161
+
162
+ - `material`: the game's `MaterialDesc` for the bodies (attributes `RIG_ATTRIBS`), with its own look in the fragment shader. Kinds with a free gait or chains get the same description with `WH_RIG_EXT` defined after the header line. Without it the engine's material draws exactly as before.
163
+ - `castShadow` (default false): the posed bodies are drawn into the shadow map, every instance at near detail, as a dynamic caster (`shadowCasters: 'dynamic'`, `shadowDirty()` true after `set` or `commit`). The depth program is the `shadow` pass of the game's material when it has one, otherwise the engine's (`rigPose` and `u_lightRender`).
164
+ - `contactShadows` (default true): the soft shadow under every rig.
165
+
166
+ <!-- check: wrap -->
167
+ ```ts
168
+ import type { MaterialDesc } from 'wallhammer-web/base';
169
+ import { RIG_ATTRIBS } from 'wallhammer-web/base';
170
+ import { RigLayer } from 'wallhammer-web/render';
171
+ import type { Renderer } from 'wallhammer-web/render';
172
+ declare const renderer: Renderer;
173
+
174
+ const flat: MaterialDesc = {
175
+ name: 'flat-rig',
176
+ attribs: RIG_ATTRIBS,
177
+ passes: {
178
+ color: {
179
+ vs: `#include <header>
180
+ #include <noise>
181
+ #include <rig-pose>
182
+ out vec3 v_color;
183
+ void main() {
184
+ vec3 pos, nrm;
185
+ if (!rigPose(pos, nrm)) { gl_Position = vec4(2.0, 2.0, 2.0, 1.0); return; }
186
+ v_color = rigColor() * (0.6 + 0.4 * max(nrm.y, 0.0));
187
+ gl_Position = u_viewProj * vec4(pos, 1.0);
188
+ }`,
189
+ fs: `#include <header>
190
+ in vec3 v_color;
191
+ out vec4 o_color;
192
+ void main() { o_color = vec4(v_color, 1.0); }`,
193
+ },
194
+ },
195
+ state: { color: { depthTest: true, depthWrite: true, cullBack: true, blend: null, polygonOffset: null } },
196
+ };
197
+ const rigs = new RigLayer(renderer, { material: flat, castShadow: true });
198
+ renderer.add(rigs);
199
+ ```
200
+
201
+ Vehicles with a trailing segment: the anchors sit on the rear axle of the leading segment and on the trailing segment's own axle. To place one, sample its path at the anchor and at the trailing distance behind it, and turn the trailing heading toward the joint.
202
+
203
+ See [Recipes](recipes.md#add-an-animated-rig) for adding a rig of your own.
@@ -0,0 +1,235 @@
1
+ # Simulation
2
+
3
+ `wallhammer-web/sim` is a deterministic fixed-step simulation. It runs in plain Node and in the browser. The image never writes into it; it reads it only through extraction.
4
+
5
+ ## Determinism tier
6
+
7
+ - Time is an integer tick. The default rate is 20 Hz.
8
+ - The only input is a log of tick-stamped commands.
9
+ - Lengths are integer millimetres, speeds whole millimetres per tick. Values entering the simulation are quantised at the boundary (`mm`, `mmPerTick`).
10
+ - `sim` may not use `Math.random`, `Date`, `performance.now` or transcendental `Math` functions. `pnpm check:layers` enforces this (`sim-nondeterministic`). Input built with `Math.cos` outside the simulation is fine because it is quantised on entry.
11
+ - `sim` imports only `base`, `core` and `gen-core` (`sim-headless`).
12
+
13
+ So the same seed and the same commands give the same `stateHash()` on every machine.
14
+
15
+ ## `Simulation`
16
+
17
+ <!-- check: wrap -->
18
+ ```ts
19
+ import { EntityTable, Simulation } from 'wallhammer-web/sim';
20
+
21
+ const sim = new Simulation({ seed: 'demo-1' }); // hz 20, maxTicksPerFrame 8, checkpoint every 200 ticks
22
+ const counters = new EntityTable('counters', { value: 'i32' });
23
+ sim.addState(counters); // everything in addState is saved, restored and hashed
24
+
25
+ sim.onCommand('add', (cmd, s) => {
26
+ const id = counters.create();
27
+ counters.col.value[counters.rowOf(id)] = Number(cmd.data.amount ?? 1);
28
+ s.events.post('counter.added', id);
29
+ });
30
+ sim.addSystem('grow', (s) => {
31
+ for (let r = 0; r < counters.count; r++) counters.col.value[r]! += s.random('grow', counters.idAt(r)) % 3;
32
+ });
33
+
34
+ sim.command('add', { amount: 5 }); // applies before the systems of the next tick
35
+ sim.step(100);
36
+ const hash = sim.stateHash();
37
+ sim.seek(40); // restores a checkpoint and replays the command log
38
+ ```
39
+
40
+ Members:
41
+
42
+ | Member | Meaning |
43
+ | --- | --- |
44
+ | `tick`, `time`, `alpha` | Current tick, simulated seconds, fraction between the last two ticks (for interpolation). |
45
+ | `addSystem(name, fn)` | A system is a plain function, run every tick in registration order. |
46
+ | `addState(state)` | Something with `name`, `save(writer)` and `load(reader)`. `EntityTable`, `NavGraph` and `Movers` qualify. |
47
+ | `onCommand(kind, handler)`, `command(kind, data, tick?)` | Commands. A command for a past tick is an error. `data` is a flat record of numbers, strings and booleans. |
48
+ | `random(stream, ...keys)` | A uint32 from the named stream, keyed by the current tick and the keys. |
49
+ | `events` | `EventQueue`: `post`, `thisTick`, `lastTick`, `drain`. |
50
+ | `step(n)`, `advance(realSeconds)` | Run ticks. `advance` runs at most `maxTicksPerFrame` per call; beyond that simulated time slows down. |
51
+ | `pause`, `play`, `setSpeed`, `stepOnce`, `paused`, `speed`, `animating` | Playback. |
52
+ | `seek(tick)` | Jump to a tick: restore the nearest checkpoint, replay commands. |
53
+ | `snapshot()`, `restore(bytes)`, `stateHash()` | Save, load, hash. |
54
+ | `rebase(snapshot?)` | Restore a snapshot (or keep the state) and make it tick 0 with an empty command log: setting the world up anew. |
55
+ | `onTick`, `onChange` | Listeners. |
56
+
57
+ ## `EntityTable`
58
+
59
+ Dense typed columns. Column types: `i32`, `u32`, `i16`, `u8`, `f64`.
60
+
61
+ - `create()` returns a stable id: namespace · 2³² + serial.
62
+ - `rowOf(id)`, `idAt(row)`, `has(id)`, `count`, `col.<name>[row]`, `ids`.
63
+ - `remove(id)` swaps the last row into the gap. Row order is not stable across removals; ids are.
64
+
65
+ ## Navigation and movement
66
+
67
+ - `NavGraph(name, { nodes: [x, z, …], edges: [{ from, to, cost?, speed?, both? }] })`. `findEdge`, `findPath(from, to)` (A* with a cache), `path(edges, { loop, rightOffset, stops })` turns edges into a `PathDef`. `setCost` and `setBlocked` change the graph.
68
+ - `PathSet` holds `PathDef`s (`points`, `loop?`, `speeds?`, `lanes?`, `stops`). `lanes` gives each segment a lane id: segments of different paths with the same lane id are one lane (the same street direction driven by several loops).
69
+ - `Movers(name, { hz, collision, width })` moves entities along paths: acceleration, cruising, braking for lower limits ahead, dwelling at stops.
70
+ - Movers post `move.arrive`, `move.depart` and `move.end` events.
71
+ - `movers.extract(alpha, out)` writes `TRANSFORM_STRIDE` (6) floats per entity in row order; `extractPose(alpha, out)` writes `POSE_STRIDE` (8): the same six, the turn rate and the state. These are the only reads of movement for the image.
72
+
73
+ `examples/minimal-3d/src/life.ts` is a complete example: a graph, a procession that loops, wanderers that pick A* routes, and a `call` command.
74
+
75
+ ## Collision modes
76
+
77
+ `collision` picks what an entity respects. Everything is decided from the state at the start of the tick, in integer millimetres, so the order of rows never matters.
78
+
79
+ | Mode | What it does |
80
+ | --- | --- |
81
+ | `none` | Nothing. |
82
+ | `follow` | Keeps `gap` to the entity ahead on the same lane. |
83
+ | `static` | Stops before static obstacles (`addObstacle(capsule)`) on its path. |
84
+ | `lanes` | `follow` and `static`, plus conflict zones where lanes cross or merge, known moving obstacles and shared areas. For vehicles. |
85
+ | `agents` | Local avoidance in a crowd (side steps, standing groups pushed apart, patience against gridlock), static and known obstacles, shared areas. For people. |
86
+
87
+ The modes other than `none` and `follow` are the extended ones: they add columns (`front`, `back`, `half`, offsets, `wait`) and accept `front`, `back` and `width` on `spawn`.
88
+
89
+ **Zones (`lanes`).** `buildZones({ clearance, parallelClearance })` runs once after all paths are added. Where segments of different lanes come closer than `clearance` (3 m), the stretches on both become one zone; side-by-side segments only conflict closer than `parallelClearance` (2 m). A zone has one holder at a time. An entity takes a zone it is in, asks for the first zone ahead within its stopping reach when it heads its queue, and gets it when the zone is free, the lane behind the zone has room for its whole body and no known obstacle will be in the way. When a holder leaves a zone that another entity followed it into, that one holds it next. `zonesOf(path)` lists a path's stretches. `blocked(path)` lists the stretches of a path that static obstacles close; leave such a path out instead of letting entities wait there forever.
90
+
91
+ **Known obstacles.** `setKnownObstacles((tick) => capsules)` gives moving obstacles that do not take part in the simulation (a replayed schedule). It must be a pure function of the tick. Entities do not enter a capsule; one already inside is free to leave.
92
+
93
+ **Gridlock.** Zones prevent collisions, not rings: queues on loops that share a few junctions can close into a circle where every head waits for room the next one holds. `waited(id)` counts the ticks an entity has waited for a zone, an area or an obstacle (it stays 0 while it only follows). An app can watch it and move a long waiter on (`setPath(id, path, at)`), as the campus app does after 45 s. Fewer entities per junction is the real remedy.
94
+
95
+ <!-- check: wrap -->
96
+ ```ts
97
+ import { Movers, NavGraph, Simulation } from 'wallhammer-web/sim';
98
+
99
+ const hz = 10;
100
+ const sim = new Simulation({ seed: 'lanes-demo', hz });
101
+ const nav = new NavGraph('streets', { nodes: [0, 0, 80, 0, 80, 80, 0, 80], edges: [{ from: 0, to: 1, both: true }, { from: 1, to: 2, both: true }, { from: 2, to: 3, both: true }, { from: 3, to: 0, both: true }] });
102
+ const vehicles = new Movers('vehicles', { hz, collision: 'lanes', width: 1.8 });
103
+ sim.addState(vehicles);
104
+ const route = [nav.findEdge(0, 1), nav.findEdge(1, 2), nav.findEdge(2, 3), nav.findEdge(3, 0)];
105
+ const loop = vehicles.paths.add(nav.path(route, { loop: true, rightOffset: 1.7 }));
106
+ vehicles.addObstacle({ ax: 40, az: 1, bx: 44, bz: 1, radius: 0.9 });
107
+ if (vehicles.blocked(loop).length === 0) {
108
+ for (let i = 0; i < 3; i++) vehicles.spawn({ path: loop, at: i * 90, cruise: 9, gap: 8, front: 3.5, back: 1 });
109
+ }
110
+ vehicles.buildZones();
111
+ sim.addSystem('vehicles', vehicles.system);
112
+ sim.step(600);
113
+ ```
114
+
115
+ ## Shared areas
116
+
117
+ `Interlock(name, { areas, approach })` lets two mover sets share places where their paths cross: each area is a capsule with a priority side. Attach the sets (`attach(people, 0)`, `attach(vehicles, 1)`) and register `interlock.system` before both sets' systems. The yielding side does not enter while the priority side is on the area, close before it or can no longer stop; the priority side does not enter while a committed yielding entity is there. Nobody waits for a waiting entity of the other side, so the two sides cannot lock each other. A zebra gives people priority; a plain crossing point gives it to vehicles.
118
+
119
+ ## Agendas and states
120
+
121
+ `Agendas(name, { movers, nav, places, origin, spawn, onAppear, onArrive })` drives entities by a list of activities: a place, a time and a stay. The system routes each trip through the graph, hands it to the mover set, waits for the arrival and the stay, and goes on. Places are graph nodes with an optional spot off the graph (`x`, `z`) and `inside` (staying hides the entity: its mover is removed, so only people out of doors cost anything).
122
+
123
+ - The agenda clock is seconds; tick 0 is `origin`. `setOrigin(s)` moves it before the first tick.
124
+ - The first activity is where the entity appears. A trip that should have begun before tick 0 starts at the distance walked by now, so a world set up at any time of day looks plausible at once.
125
+ - `arrive: true` on an activity means "be there by `at`"; the trip starts the route's walking time earlier.
126
+ - `mode` and `tag` are free integers for the app.
127
+ - Events: `agenda.appear`, `agenda.arrive`, `agenda.leave`, `agenda.done`, `agenda.unreachable`.
128
+
129
+ The states are a `StateMachine` with four built in: `before`, `stay`, `travel`, `done`. An app defines its own with `agendas.states.define(name, { enter, update })`; `update` returns the next state's id or nothing. It switches into them from `onAppear` and `onArrive`. Inside an `update` these helpers act on the entity: `show`, `hide`, `walkTo`, `stayUntil`, `leave`, `finish`, `arriveNext` (carried to the next activity without a trip: a ride, a lift), and `activity`, `nextActivity`, `standing`, `timer`, `data`. `now` is the tick and `time` the agenda clock in seconds.
130
+
131
+ <!-- check: wrap -->
132
+ ```ts
133
+ import { Agendas, Movers, NavGraph, Simulation } from 'wallhammer-web/sim';
134
+
135
+ const hz = 10;
136
+ const sim = new Simulation({ seed: 'agenda-demo', hz });
137
+ const nav = new NavGraph('ways', { nodes: [0, 0, 60, 0, 60, 40], edges: [{ from: 0, to: 1, both: true }, { from: 1, to: 2, both: true }] });
138
+ const people = new Movers('people', { hz, collision: 'agents', width: 0.5 });
139
+ const places = [{ node: 0 }, { node: 2, inside: true }, { node: 1, x: 61, z: 2 }];
140
+ let WAITING = -1;
141
+ const agendas = new Agendas('agendas', {
142
+ movers: people,
143
+ nav,
144
+ places,
145
+ origin: 8 * 3600,
146
+ // Activities with mode 1 end in a wait for a ride.
147
+ onArrive: (e, a) => (a.activity(e).mode === 1 ? WAITING : undefined),
148
+ });
149
+ // Wait until the ride comes (here: a fixed time), then be carried on.
150
+ WAITING = agendas.states.define('waiting', {
151
+ update: (e, a) => (a.time >= 8 * 3600 + 120 ? a.arriveNext(e) : undefined),
152
+ });
153
+ agendas.add({ activities: [{ place: 0, at: 8 * 3600, stay: 0 }, { place: 2, at: 8 * 3600 + 10, stay: 0, mode: 1 }, { place: 1, at: 8 * 3600 + 200, stay: 3600 }] });
154
+ sim.addState(people);
155
+ sim.addState(agendas);
156
+ sim.addSystem('people', people.system);
157
+ sim.addSystem('agendas', agendas.system);
158
+ sim.step(3000);
159
+ ```
160
+
161
+ [Recipes](recipes.md#drive-entities-with-agendas) walks through a larger case; [feed agendas from external data](recipes.md#feed-agendas-from-external-data) shows a file format.
162
+
163
+ ## A clock that jumps
164
+
165
+ A simulation only runs forward. When the app's clock jumps (a time slider, fast play), set the world up again at the new time instead of simulating the gap: keep a `snapshot()` from right after setup, `rebase(snapshot)` (tick 0 again), move the agenda `origin` to the new time minus a short warm-up, and step through the warm-up within a frame budget before showing anything. While the clock runs faster than the simulation can follow, hide the moving entities. The campus app does this in `population.ts`.
166
+
167
+ ## Movement over a whole network
168
+
169
+ `Movers` and `Agendas` cost per entity, so they fit what the camera sees. For a network far larger than the view there is a coarse model: `FlowNetwork` makes every edge of a `NavGraph` a queue, and a trip in it is only a number. Individual movers exist only inside a focus circle, and they are the same trips.
170
+
171
+ **Segments.** Per edge: `capacity` trips fit (length · lanes / `spacing`), a trip that enters may leave after `free` ticks at the earliest (length / speed), at most `outflow` trips per second and lane leave, first in first out. A full segment lets nobody in, so queues spill back along the routes; a head that has waited longer than `patience` is pushed on, so rings of full segments dissolve. The queues step every `period` seconds (1 by default), so an edge shorter than speed · period is travelled slower than free travel would take.
172
+
173
+ **Trips.** `add({ from, to, at, tag })` before the first tick; `at` is a clock second and tick 0 is `origin`. A trip is `pending`, `waiting` (its first segment is full), `queued`, `individual`, `arrived` or `unreachable` (`FLOW_STATE`). `census()` counts them, `check()` recounts everything from the queues and the movers and returns what is wrong, or null.
174
+
175
+ **Focus and hand-over.** The command `<name>.focus` with `x`, `z` and `radius` in metres sets the circle; edges with both ends inside are detailed. The focus is input, so it only ever comes as a command. A trip is always exactly one of number and mover, and a hand-over never changes the census:
176
+
177
+ - a trip that moves from a coarse segment into a detailed one becomes a mover at the start of that segment, which lies on the rim of the circle;
178
+ - when the circle moves, all trips queued on a segment that turns detailed become movers along it, placed by their leaving time, and the movers of a segment that turns coarse go back into its queue with the leaving time their position gives;
179
+ - a mover that leaves the circle is taken back into the queue of the segment it has entered.
180
+
181
+ So nobody appears in the middle of the circle, except where a trip starts there. Keep the circle larger than the view and grow it step by step: a circle that jumps turns many segments detailed in one tick. The movers are an ordinary set (`flow.movers`, the `tag` column is the trip index), so `extractPose` feeds rigs as usual. `spawn(trip)` gives the mover parameters of a trip and must be a pure function of its index.
182
+
183
+ **Routes on two levels.** `RegionNav(nav, { cell })` splits the nodes into regions (a square grid of `cell` metres, or `regionOf` per node). A node with an edge into another region is a gate; per gate the cheapest ways inside its region are kept as tables. `find(from, to)` searches only the graph of gates and stitches the route from the tables, then caches it. A route costs what `nav.findPath` finds. `prepare(n)` builds the tables of `n` regions per call; a query builds what it needs itself, so the routes are the same either way. After `setCost` or `setBlocked` call `rebuild()`.
184
+
185
+ **Set-up in pieces.** `flow.prepare(units)` sets the network up for the clock time of tick 0: trips that left before `origin` are put where free travel has taken them by then, or are over (`horizon` bounds how far back it looks). It does at most `units` pieces of work per call and returns the pieces left. The state does not depend on how the calls are cut, and a simulation stepped before it is ready finishes the work in its first step. For a clock that jumps: `sim.rebase(snapshot)`, `flow.setOrigin(seconds)`, then `prepare` over a few frames.
186
+
187
+ <!-- check: wrap -->
188
+ ```ts
189
+ import { FlowNetwork, NavGraph, RegionNav, Simulation } from 'wallhammer-web/sim';
190
+
191
+ const hz = 10;
192
+ const sim = new Simulation({ seed: 'flow-demo', hz });
193
+ const nav = new NavGraph('net', { nodes: [0, 0, 300, 0, 600, 0, 600, 300], edges: [{ from: 0, to: 1, both: true }, { from: 1, to: 2, both: true }, { from: 2, to: 3, both: true }] });
194
+ const routes = new RegionNav(nav, { cell: 400 });
195
+ const flow = new FlowNetwork('flow', { nav, routes, hz, speed: 12, origin: 8 * 3600, spawn: () => ({ cruise: 12, gap: 6 }) });
196
+ for (let i = 0; i < 200; i++) flow.add({ from: i % 2 ? 0 : 3, to: i % 2 ? 3 : 0, at: 8 * 3600 - 60 + i * 3, tag: i });
197
+ flow.attach(sim);
198
+ // A frame loop calls this with a small number until it returns 0.
199
+ while (flow.prepare(16) > 0);
200
+ // The two edges between the first three nodes are detailed, the third one stays a queue.
201
+ sim.command('flow.focus', { x: 300, z: 0, radius: 350 });
202
+ sim.step(3000);
203
+ const census = flow.census();
204
+ if (flow.check() !== null || census.queued + census.individual !== census.load) throw new Error('trips were lost');
205
+ ```
206
+
207
+ `createFlowProbe()` is a reference run of all of this that is the same on every machine: a lattice from a seed, two networks, 40,000 trips, a scripted focus that pans, jumps, disappears and comes back. `flowProbeLine(probe.result())` is one line with the state hash. The golden test runs it headless (`node tools/golden/engine/flow-scenario.ts` prints the line); an app can run it in slices with `prepare(units)` and `advance(maxTicks)` and print the same line, as the campus app does with `otisk=1` in the address.
208
+
209
+ ## Wiring it to the image
210
+
211
+ With `createEngine`, pass the simulation as `sim` and use the hooks:
212
+
213
+ <!-- check: wrap -->
214
+ ```ts
215
+ import { TRANSFORM_STRIDE } from 'wallhammer-web/sim';
216
+ import type { Movers } from 'wallhammer-web/sim';
217
+ import type { Engine, EngineView } from 'wallhammer-web/runtime';
218
+ declare const engine: Engine<EngineView>;
219
+ declare const figures: Movers;
220
+
221
+ const transforms = new Float32Array(256 * TRANSFORM_STRIDE);
222
+ engine.onExtract((alpha) => {
223
+ const n = figures.extract(alpha, transforms);
224
+ // write n transforms into an instance buffer here
225
+ });
226
+ engine.onInput(() => {
227
+ // turn held keys into commands here: engine.command('kind', { ... })
228
+ });
229
+ ```
230
+
231
+ `engine.command(kind, data)` queues a command for the next tick the simulation runs. `engine.system(name, fn)` adds a system.
232
+
233
+ ## Posed rigs
234
+
235
+ `extractPose` gives what a rig needs: position, heading, distance travelled (gait and wheel phase), speed, turn rate (steering, body roll) and the mover state (moving, dwelling, standing). [Rigs](rigs.md) shows how to turn it into instance records for `RigLayer`.