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
@@ -0,0 +1,111 @@
1
+ # Architecture
2
+
3
+ The engine is one npm package, `wallhammer-web`, in `packages/wallhammer-web`. Each module is a folder under `src/` with an `index.ts` and its own entry `wallhammer-web/<module>`. A module may group its files in subfolders; they belong to the module. The workspace (the repository root) also holds the examples (`examples/*`) and the dev tools (`tools/*`).
4
+
5
+ ## Layers
6
+
7
+ A module may import only modules of a **lower** layer. It may not import a module of its own layer.
8
+
9
+ | Layer | Module | Contents |
10
+ | --- | --- | --- |
11
+ | 0 | `base` | Vector math, the `View` contract, plain-data contracts (`MeshData`, `InstanceData`, `TextureData`, `VertexLayout`, `MaterialDesc`, `BakeDesc`, `DrawState`, `UniformValue`), the `EnvSlot` contract, destructible structure types, reproducible trigonometry (`detSinCosTurns`), nested 64-bit frames (`FrameSet`). |
12
+ | 1 | `platform` | The only place that touches the browser: canvas size, pointer, key and gamepad input (`bindWalkInput`), the frame loop, workers, `fetchBytes`. |
13
+ | 2 | `core` | `Clock`, the palette (`definePalette`), closed-form ballistic tracks for falling pieces, orbits and spin as functions of time (`BodySystem`). |
14
+ | 2 | `gen-core` | Hash-based randomness with named streams, value noise, polygon geometry, spatial fields (`HeightField`, `SegmentField`, `OutlineField`, `Occupancy`), instance cells (`splitInstanceCells`), cell ids and the flat world shape for streaming. |
15
+ | 2 | `motion` | Skeletons and poses as data (`Skeleton`, `Pose`, `boneMask`), blend and additive operations, world matrices (`solvePose`), a motion graph of states, transitions, layers, parameters, triggers and events at marks over motions the game writes (`MotionGraph`), a two-bone reach and ends kept on the ground. No motion of its own. See [Motion](motion.md). |
16
+ | 3 | `gen-mesh` | Mesh generators: `heightFieldMesh`, `lineMesh`, `cellSurfaceMesh`, `cellMorphMesh`. |
17
+ | 3 | `gen-tex` | Texture generators: `codeTexture`, `colorTable`, `boxBlur`. |
18
+ | 3 | `gen-arch` | Content module: structures from recipes, destructible descriptions, damaged meshes, interiors, rubble, falling pieces and their materials. Subfolders `structure/`, `interior/` and `damage/` in that one-way order, root files `build.ts` and `index.ts`; one entry. |
19
+ | 3 | `gen-ground` | Content module: ground bake from surface classes, markings, their materials, the season and snow slots. |
20
+ | 3 | `gen-vegetation` | Content module: vegetation placement and meshes, their material, the sway slot. |
21
+ | 3 | `gen-plan` | Coarse plans over a whole sphere: a grid of nodes at the middles of the cells of one cube-sphere level (`sphereGrid`, `gridNeighbours`, `gridSample`), drainage (`drainGrid`, `traceChannels`), lines over the sphere (`smoothLine`, `fallingGrade`, `limitGrade`, `lineAt`), least-cost ways and regions (`routeGrid`, `routeRegions`, `regionLinks`), picks of nodes by a score (`pickSites`, `gridSteps`), plots along lines on a plane (`plotsAlong`), an index from tiles to lines (`lineTiles`) and the skyline of a height field (`horizonField`, `gridHorizon`). Not a content module; imports only `base` and `gen-core`. |
22
+ | 4 | `gpu` | The only place with WebGL2: `Device`, programs, buffers, textures, meshes, bakes, GPU memory accounting. |
23
+ | 5 | `render` | `Renderer`, passes, the shadow map, `MeshLayer`, `PieceLayer`, `InstancedLayer`, `InstanceCellLayer`, `TransientLayer`, `RigLayer`, shader includes. |
24
+ | 5 | `camera` | `SteppedOrthoRig`, `PerspectiveOrbitRig`, `FreeRig`, `FollowRig` and keyframed orbit paths (`OrbitPath`). |
25
+ | 5 | `env` | `Environment` (clocks, sun, light, weather, wind, clouds), the `lighting` and sky GLSL, `assembleFrameBlock`. |
26
+ | 5 | `world` | Picking (`raycastHeightField`, `raycastPrisms`), the collision world (`CollisionWorld`) and a walker over it (`Walker`) and streaming without the GPU: `StreamingManager`, cell providers, the WHC1 cell file format. |
27
+ | 5 | `sim` | Deterministic fixed-step simulation that runs in plain Node. Submodule `sim/destruction`. |
28
+ | 6 | `runtime` | `createEngine`, `createHeadlessEngine`, `EnvironmentLink`, `SkyLayer`, `PrecipitationLayer`, `StreamedWorld`. |
29
+ | 7 | `tools` | Debugging aids: the data view, the frame profile. |
30
+
31
+ The root entry `wallhammer-web` re-exports `base`, `platform`, `core`, `gen-core`, `gen-mesh`, `gen-tex`, `gpu`, `camera`, `env`, `world` and `tools`. It does **not** re-export `motion`, `render`, `sim`, `runtime`, `gen-arch`, `gen-ground`, `gen-vegetation` or `gen-plan`. Import those from their own entries.
32
+
33
+ `sim/destruction` is a folder inside `sim`. The layer check treats it as part of `sim`.
34
+
35
+ ## Content modules
36
+
37
+ `gen-arch`, `gen-ground` and `gen-vegetation` are content modules. They are the only engine modules that may name what they generate (structures, vegetation, markings). The rules:
38
+
39
+ - They import only `base`, `core`, `gen-core`, `gen-mesh` and `gen-tex`, and `earcut` from npm.
40
+ - They do not import each other, any app or the root entry.
41
+ - No other engine module imports them, and the root entry does not re-export them.
42
+
43
+ Apps and the `destruction` and `system` examples may import them (`system` for the structures of its settlements and their damage). The engine-only examples (`minimal-3d`, `endless`, `planet`, `fantasy-village`, `walk`, `outpost`) may not; the layer check enforces this.
44
+
45
+ `gen-ground` and `gen-vegetation` do not import each other, but their shaders share Frame members. Both slots they share belong to `gen-ground`: the terrain shader reads `u_season` from its season slot and includes `<snow>` from its snow slot, and the vegetation shader reads the same two (the structure shaders of `gen-arch` include `<snow>` as well). So the ground depends on nothing of the vegetation, and an app that draws vegetation registers the season and snow slots of `gen-ground` together with the sway slot.
46
+
47
+ ### Subfolder order in `gen-arch`
48
+
49
+ The subfolders of `gen-arch` depend one way: `structure` <- `interior` <- `damage` <- module root. A file imports only its own subfolder and the ones before it: `structure` imports neither `interior` nor `damage`, and `interior` does not import `damage`. Type imports and re-exports count. The plan of one structure (`StructurePlan`) and the interior sizes (`INTERIOR_DIM`) live in `structure`, the falling-parts material in `damage`. The files directly in the module folder rank after all subfolders and may import every one of them: `build.ts` assembles the structure mesh (`buildBuildingMesh`) from the structure parts, the interior plan and the damage model, and `index.ts` is the entry. The layer check reads the order from `SUBFOLDER_ORDER`; a new subfolder must be given a place there.
50
+
51
+ ## The engine stays abstract
52
+
53
+ Outside the content modules the engine must not name a use case. The layer check flags these words in file names, exported identifiers and comments of non-content engine modules: city, building, roof, facade, tree, leaf, crown, car, parking, kerb, road, pavement, crossing, window, river, lake, shore, coast, mountain, biome, village, town, settlement, flower, bridge, tower, mill, creature, animal (also plural forms, and façade with the cedilla). The list is `USE_CASE_WORDS` in `tools/layers/check.ts`. `window` is allowed in `platform`, where it is the browser global.
54
+
55
+ So a renderer feature is described in neutral terms ("instances", "surface classes", "transient pieces"), and the project or a content module gives it meaning.
56
+
57
+ ## What `pnpm check:layers` enforces
58
+
59
+ `tools/layers/check.ts` walks `packages/wallhammer-web/src`, `examples/*` and, in a workspace that has them, `apps/*`. It does not walk `tools/`. Every finding is an error; there are no exceptions. Rule ids as they appear in the output:
60
+
61
+ | Rule | Meaning |
62
+ | --- | --- |
63
+ | `upward` | An engine module imports a higher layer. |
64
+ | `same-layer` | An engine module imports another module of its own layer. |
65
+ | `stray-file` | An engine source file sits outside a module folder (only `src/index.ts` may). Subfolders of a module are part of it. |
66
+ | `unknown-module` | An import points to an engine folder that is not a known module. |
67
+ | `engine-imports-content` | A non-content engine module or the root entry imports a content module, or the engine imports an app. |
68
+ | `content-imports-app` | A content module imports an app. |
69
+ | `content-imports-content` | One content module imports another. |
70
+ | `content-imports-engine` | A content module imports an engine module other than the generator layers. |
71
+ | `subfolder-order` | Inside `gen-arch`, a file imports a later subfolder or a root file (order `structure` <- `interior` <- `damage` <- root), or sits in a subfolder the order does not list. |
72
+ | `example-imports` | An example imports an app, or an engine-only example imports something other than the engine or imports a content module. |
73
+ | `webgl` | WebGL types or calls outside `gpu` (engine and examples). |
74
+ | `dom` | Browser DOM outside `platform` (engine). |
75
+ | `worker` | The Worker API outside `platform` (engine). |
76
+ | `use-case-word` | A use-case word (list above) in a non-content engine module. |
77
+ | `sim-headless` | `sim` imports anything but `base`, `core` and `gen-core`. |
78
+ | `sim-nondeterministic` | `sim` uses `Math.random`, `Date`, `performance.now` or a transcendental `Math` function (`sin`, `cos`, `atan2`, `exp`, `pow`, `hypot` and others). |
79
+
80
+ `pnpm check:layers:test` runs the check against a valid fixture and a known-bad fixture in `tools/layers/fixtures`.
81
+
82
+ ### Conventions the check does not enforce
83
+
84
+ - **No `Math.random` and no wall clock in generators.** Only `sim` is checked for this. A generator that calls `Math.random` passes `check:layers`. The golden hashes catch it only if a golden recipe covers that generator.
85
+ - **Generators never touch the GPU.** This follows from the layers (generators are below `gpu`), so it is enforced indirectly.
86
+ - **Code comments are in English.** Not checked.
87
+ - **Apps.** The check reads app files only to find engine code that imports an app. No rule applies to an app's own imports or to WebGL use inside an app.
88
+
89
+ ## Workspace layout
90
+
91
+ ```text
92
+ packages/wallhammer-web/ the engine (this package)
93
+ src/<module>/index.ts one entry per module
94
+ docs/ this documentation
95
+ examples/minimal-3d/ engine-only example
96
+ examples/destruction/ engine + gen-arch example
97
+ examples/endless/ engine-only streaming example
98
+ examples/planet/ engine-only example: a sphere with an atmosphere, from its surface to orbit
99
+ examples/system/ example with content modules: a sun and four bodies, from the whole system to a surface
100
+ examples/fantasy-village/ engine-only example: a living village from code
101
+ examples/walk/ engine-only example: the walking test course
102
+ examples/outpost/ engine-only example: a lunar research outpost in a comic look
103
+ tools/layers/ the layer check
104
+ tools/golden/engine/ golden hashes of the engine's generators
105
+ tools/golden/ golden hashes that need example code
106
+ tools/docs/ the documentation check
107
+ tools/pack/ the check of the published package
108
+ tools/walk/, tools/follow-check/ the walking and follow-camera checks (plain Node)
109
+ tools/serve/, tools/vite/ the example server (one port for all examples) and its dev-server plugin
110
+ tools/shot/, tools/bench/ screenshots and measurements of the example pages (run on the host)
111
+ ```
@@ -0,0 +1,302 @@
1
+ # Cameras and views
2
+
3
+ The renderer reads only the `View` contract from `wallhammer-web/base`. A rig in `wallhammer-web/camera` produces a view. Input binding is in `wallhammer-web/platform`.
4
+
5
+ ## The `View` contract
6
+
7
+ | Member | Meaning |
8
+ | --- | --- |
9
+ | `width`, `height`, `dpr` | Drawing surface in physical pixels; physical pixels per CSS pixel. |
10
+ | `heading` | Rotation around the vertical axis in radians. 0 looks toward −z. |
11
+ | `metresPerPixel` | World size of one screen pixel at the view centre. |
12
+ | `pixelGrowth`, `refDepth` | How pixel size grows with depth. Both 0 for an orthographic view. Shaders use them through `metresPerPixelAt` and `detailVisibleAt` in `<noise>`. |
13
+ | `axes()` | Unit screen right, screen up and view direction. |
14
+ | `viewProj(center, halfRange)` | World to clip matrix. |
15
+ | `cornerRays()` | Rays through the four image corners. The shadow map is fitted with them. |
16
+ | `cullVolume()` | A box (orthographic) or a frustum (perspective). `InstancedLayer`, `PieceLayer` and `InstanceCellLayer` cull against both (`boxInVolume` in `base`). |
17
+ | `key()` | Changes whenever the image of a static scene would change. Part of the shadow key. |
18
+
19
+ A custom rig only has to implement this, plus `width`, `height` and `dpr` being writable if you use `createEngine` (`EngineView = View & CanvasSizeTarget`).
20
+
21
+ ## `SteppedOrthoRig`
22
+
23
+ An orthographic view with four rotations in 90° steps and a table of fixed zoom levels. It holds no numbers of its own; you pass them.
24
+
25
+ <!-- check: wrap -->
26
+ ```ts
27
+ import { SteppedOrthoRig } from 'wallhammer-web/camera';
28
+
29
+ const view = new SteppedOrthoRig({ yawDeg: 22.5, pitchDegByZoom: [30, 35, 40], pxPerMeterByZoom: [1, 2, 4] });
30
+ view.bounds = { minX: 0, maxX: 800, minZ: 0, maxZ: 600 }; // the default is 0..1, which clamps the centre
31
+ view.centerX = 400;
32
+ view.centerZ = 300;
33
+ view.setZoom(view.fitZoom(800, 600, 40));
34
+ view.setRotation(1); // 90°
35
+ const ray = view.screenRay(100, 100); // for picking
36
+ ```
37
+
38
+ Fields: `rotation` (0–3), `zoom`, `centerX`, `centerZ`, `refHeight` (the reference plane), `bounds`. Methods: `panPixels`, `setZoom`, `setRotation`, `state`, `fitZoom`, `screenRay`, `project`.
39
+
40
+ Weak spot: `bounds` defaults to a 1 × 1 m rectangle. If you forget to set it, the centre is clamped and panning seems broken.
41
+
42
+ `bindCameraInput(canvas, view, { onChange })` binds drag pan, wheel and `+`/`−` zoom, `Q`/`E` rotation, arrow keys and `0` (home, through `onHome`). It returns an unbind function.
43
+
44
+ ## `PerspectiveOrbitRig`
45
+
46
+ A perspective view that orbits a target.
47
+
48
+ <!-- check: wrap -->
49
+ ```ts
50
+ import { PerspectiveOrbitRig } from 'wallhammer-web/camera';
51
+
52
+ const view = new PerspectiveOrbitRig({ fovYDeg: 40, minDistance: 25, maxDistance: 260 }, { yawDeg: 35, pitchDeg: 24, distance: 105 });
53
+ view.target = [64, 6, 64];
54
+ view.setState({ yawDeg: 200 });
55
+ const eye = view.eye();
56
+ view.orbitPixels(40, 0); // as a drag would
57
+ view.zoomBy(1.15);
58
+ ```
59
+
60
+ Setup (`OrbitSetup`, defaults in `DEFAULT_ORBIT`): `fovYDeg` 45, `minPitchDeg` 5, `maxPitchDeg` 85, `minDistance` 2, `maxDistance` 500, `turnPerPx` 0.006. Public state options are in degrees; the fields `yaw` and `pitch` are radians.
61
+
62
+ `createEngine({ orbitControls: true })` calls `bindOrbitInput` for you: drag orbits, the wheel zooms.
63
+
64
+ ### Keeping the eye above the ground
65
+
66
+ With `groundAt(x, z)` in the setup, the rig keeps the eye at least `minEyeHeight` (default 1 m) above that height:
67
+ after `setState`, `orbitPixels` and `zoomBy` it raises the pitch (never over `maxPitchDeg`) as little as needed,
68
+ found by halving the interval between the current pitch and `maxPitchDeg`. Yaw, distance and target stay as asked.
69
+ When even `maxPitchDeg` is too low the pitch stays at `maxPitchDeg`. `keepAboveGround()` does the same on demand (after
70
+ changing `target` directly) and returns whether it changed the pitch. Without `groundAt` nothing changes.
71
+
72
+ <!-- check: wrap -->
73
+ ```ts
74
+ import { PerspectiveOrbitRig } from 'wallhammer-web/camera';
75
+ declare const heightAt: (x: number, z: number) => number;
76
+
77
+ const rig = new PerspectiveOrbitRig({ groundAt: heightAt, minEyeHeight: 1.5 }, { yawDeg: 30, pitchDeg: 10, distance: 40 });
78
+ rig.target = [12, heightAt(12, 8) + 1, 8];
79
+ if (rig.keepAboveGround()) console.log('pitch raised to', rig.pitch);
80
+ ```
81
+
82
+ ### Orbit paths
83
+
84
+ `OrbitPath` moves an orbit rig along keyframes: orbit states (`OrbitKey`: `target`, `yawDeg`, `pitchDeg`, `distance`) at times `t` in seconds. Between the keys every channel is a cubic Hermite curve with Catmull-Rom tangents for uneven key spacing, so the velocity is continuous at every key. The yaw takes the shorter way round between neighbouring keys (more than 180° between two keys needs a key in between). The distance is interpolated in log space: equal zoom factors take equal time, and it never reaches zero. The target, pitch and distance may overshoot a little between keys, as any spline through the keys does; keep a margin to the limits that matter (the ground, the rig's pitch range, which `apply` clamps to).
85
+
86
+ - **Open** (default): the path starts and ends at rest, and times outside `0 … duration` are clamped. `duration` is the last key time less the first.
87
+ - **Looping** (`{ loop: true, duration }`): the path repeats every `duration` seconds and closes from the last key back to the first with the same smoothness. `duration` must be later than the last key; the closing segment takes the rest. A loop may turn the yaw by whole turns; the sampled yaw then grows from loop to loop, which the rig does not mind.
88
+
89
+ Time is relative to the first key. `sample(t, out)` writes the state at `t` into a state you own, `apply(rig, t)` writes it straight into a rig, `wrap(t)` folds a time into the path. Neither allocates, so both can run every frame.
90
+
91
+ <!-- check: wrap -->
92
+ ```ts
93
+ import { OrbitPath, PerspectiveOrbitRig, blendOrbitState, writeOrbitState } from 'wallhammer-web/camera';
94
+ import type { OrbitState } from 'wallhammer-web/camera';
95
+ declare const view: PerspectiveOrbitRig;
96
+ declare const seconds: number;
97
+
98
+ const path = new OrbitPath(
99
+ [
100
+ { t: 0, target: [0, 5, 0], yawDeg: 20, pitchDeg: 30, distance: 60 },
101
+ { t: 6, target: [10, 4, -8], yawDeg: -30, pitchDeg: 12, distance: 20 },
102
+ { t: 12, target: [0, 20, -60], yawDeg: 10, pitchDeg: 20, distance: 100 },
103
+ ],
104
+ { loop: true, duration: 18 },
105
+ );
106
+ path.apply(view, seconds); // every frame, before rendering
107
+
108
+ // Sampling into an own state, and easing from where the view was into the path.
109
+ const from: OrbitState = view.state();
110
+ const at: OrbitState = { target: [0, 0, 0], yawDeg: 0, pitchDeg: 0, distance: 1 };
111
+ path.sample(seconds, at);
112
+ writeOrbitState(view, blendOrbitState(from, at, 0.5, at));
113
+ ```
114
+
115
+ `writeOrbitState(rig, state)` is `setState` without allocating: the target is copied into the rig's own array, pitch and distance are clamped to its setup. `blendOrbitState(a, b, x, out)` lies between two states (yaw the shorter way, distance in log space); `out` may be `a` or `b`. Leaving a path is free: stop calling `apply`, and `bindOrbitInput` turns the rig on from where the path left it.
116
+
117
+ ## Sizing
118
+
119
+ `createEngine` keeps the canvas and the view sized (`observeCanvasSize`). Without it, call `syncCanvasSize(canvas, view)` before rendering. A rig starts at 1 × 1 pixels.
120
+
121
+ ## `FreeRig`
122
+
123
+ A perspective view that moves freely: a position, a heading along the local horizon and a pitch. It is an option; nothing uses it unless you create it.
124
+
125
+ - **Position in double precision.** `position` is in world metres. Everything the `View` contract hands to the renderer (`eye()`, rays, the cull volume, the matrix) is relative to `origin`, which you keep near the eye and equal to the origin your layers are drawn with (for a `StreamedWorld` that is `world.origin`). Only the difference of the two becomes a float.
126
+ - **Up comes from the world shape.** Pass a `WorldShape` (or anything with `upAt`) as `shape`. The rig asks it at its position every time, so the same rig works on a flat world and on a curved one. The heading is kept in the local horizon and carried along when up changes. Without `shape`, up is +y.
127
+ - **Height above the surface is your callback.** `heightAbove(p)` returns the height of a world position above the surface under it, measured along the local up (on a flat world `p[1] - groundAt(p[0], p[2])`). The rig never goes below `minClearance`, its cruise speed is `height × speedPerHeight` clamped to `minSpeed … maxSpeed`, and the near plane comes no farther than `nearPerHeight` of the height. Without the callback there is no clearance and the rig cruises at `minSpeed`.
128
+
129
+ <!-- check: wrap -->
130
+ ```ts
131
+ import { FreeRig } from 'wallhammer-web/camera';
132
+ import { FlatWorld } from 'wallhammer-web/gen-core';
133
+ import { bindFreeInput } from 'wallhammer-web/platform';
134
+ import type { Renderer } from 'wallhammer-web/render';
135
+ declare const canvas: HTMLCanvasElement;
136
+ declare const renderer: Renderer;
137
+ declare const world: { origin: readonly [number, number, number] }; // whatever owns the render origin
138
+ declare function groundAt(x: number, z: number): number;
139
+ declare function invalidate(): void;
140
+
141
+ const view = new FreeRig(
142
+ { fovYDeg: 50, minClearance: 2 },
143
+ { shape: new FlatWorld(), heightAbove: (p) => p[1] - groundAt(p[0], p[2]) },
144
+ { position: [0, 30, 0], yawDeg: 30, pitchDeg: 10 },
145
+ );
146
+ const input = bindFreeInput(canvas, view, { onChange: invalidate });
147
+ renderer.beforeFrame.unshift(() => {
148
+ input.step(); // held keys move the rig by the real time since the last frame
149
+ view.origin = [world.origin[0], world.origin[1], world.origin[2]];
150
+ });
151
+
152
+ // Without input: the same calls the binding makes.
153
+ view.turnPixels(40, 0); // look right
154
+ view.move(1, 0, 0, 1 / 60, false); // forward for one frame
155
+ view.lookAt([100, 0, -100]);
156
+ view.setState({ position: [500, 80, 500] }); // a jump; the clearance is applied
157
+ ```
158
+
159
+ Setup (`FreeSetup`, defaults in `DEFAULT_FREE`):
160
+
161
+ | Field | Default | Meaning |
162
+ | --- | --- | --- |
163
+ | `fovYDeg` | 50 | Vertical field of view. |
164
+ | `maxPitchDeg` | 89 | Limit of the pitch on both sides of the horizon. |
165
+ | `turnPerPx` | 0.004 | Radians of turn per CSS pixel. |
166
+ | `minClearance` | 2 | Metres kept above the surface. |
167
+ | `followSurface` | `false` | `true` holds the height above the surface while moving: the rig follows the surface up and down and only the part of a move along the local up changes the height. Needs the height callback. |
168
+ | `speedPerHeight` | 1 | Cruise speed per metre of height (1/s). |
169
+ | `minSpeed`, `maxSpeed` | 5, 5000 | Limits of the cruise speed in m/s. |
170
+ | `boost` | 6 | Speed factor while the boost key is held. |
171
+ | `inertiaS` | 0.12 | Time constant with which the velocity follows the input; 0 is immediate. |
172
+ | `levelMove` | `false` | `true` moves "forward" along the horizon instead of along the view direction. |
173
+ | `depthRatio` | 2000 | Largest far / near ratio of the projection. |
174
+ | `nearPerHeight` | 0.25 | The near plane is at most this fraction of the height above the surface. |
175
+ | `minNear` | 0.1 | Smallest near distance in metres. |
176
+
177
+ Fields: `position`, `origin`, `pitch` (radians, positive looks down), `yaw` (radians, accessor), `speedScale`, `velocity` (world m/s after the last `move`), `clearance` (height at the last `keepClear`, NaN without a callback), `focusDistance`, `heightAbove`. Methods: `setState`, `state` (degrees, as the orbit rig), `turn`, `turnPixels`, `lookAt`, `move`, `scaleSpeed`, `keepClear`, `up`, `headingDir`, `eye`, `screenRay`, `project`.
178
+
179
+ The heading is measured in the local horizon from the world −z axis (yaw 0 looks toward −z on a flat world, positive turns left, as for the orbit rig). Where up runs along z the +x axis is the reference instead.
180
+
181
+ `bindFreeInput(canvas, view, { onChange })` binds `W` `A` `S` `D` and the arrows (move), `E` / `Space` and `Q` / `C` (up, down), `Shift` (boost), a drag (turn) and the wheel (speed). It returns a `FreeInput`: call `step()` once per frame before rendering, and `dispose()` to detach. Options: `keys` (replace single entries of `DEFAULT_FREE_KEYS`), `pointerLock` (a press locks the pointer and its movement turns the view), `grab` (a drag pulls the image instead of turning toward the pointer), `wheelFactor`. It drives anything that implements `FreeControl`, not only `FreeRig`. `createEngine` has no switch for it; leave `orbitControls` off and bind it yourself.
182
+
183
+ Weak spots:
184
+
185
+ - `followSurface` holds the height measured at the last `move`, `setState` or `keepClear()`, and it follows every bump of the callback at the speed of the rig. High above a rough surface leave it off, or give the rig a smoothed height. `setup.followSurface` may be switched at any time.
186
+ - Write `position` directly only together with `keepClear()`; `setState({ position })` does both and drops the velocity.
187
+ - With a low eye and a far scene the near plane moves in (`nearPerHeight`), which spends depth precision far away. Raise `minClearance` or lower the scene's depth range if distant surfaces flicker.
188
+ - `origin` must match the origin the layers draw with in the same frame. Set it in `renderer.beforeFrame`, after the code that moves the render origin.
189
+
190
+ The endless example uses the rig behind `#cam=free` (`examples/endless/src/free-camera.ts`); its default is still an orbit rig whose target is moved with held keys (`trackHeldKeys`).
191
+
192
+ ## `FollowRig`
193
+
194
+ A perspective view that follows a moving point, typically a body that walks (`Walker` in `wallhammer-web/world`). A pivot sits `pivotHeight` above the followed point and trails it by `followLag`; a boom runs from the pivot back to the eye, turned by `yawDeg` (0 looks toward −z, positive turns left) and `pitchDeg` (positive looks down). `distance` is the wanted boom length; at 0 the eye is the pivot itself (first person). It is an option; nothing uses it unless you create it.
195
+
196
+ - **The boom never goes through things.** Pass a `BoomClearance` callback: from the pivot along a unit direction, how far may the boom reach (at most `maxDist`). `CollisionWorld.clearance` is made for it; close over the radius of the sphere you cast, a little more than the near plane's corner distance (0.25 m for `near` 0.1). The rig cuts the boom to that length at once and lets it grow back over `boomReturn` seconds, so the view does not jump back and forth at an edge. `boom` is the length drawn this frame.
197
+ - **Call `follow` and `update` once per frame**, in that order, after the body has moved: `follow(x, y, z)` with the body's render position, `update(dt)` with the real seconds of the frame. The first `follow` places the pivot at once; after a jump of the body call `snap()` to do the same.
198
+ - **`forward(out)` turns input into world movement**: the unit direction on the ground the view looks along. Screen right is `(−forward.z, 0, forward.x)`.
199
+
200
+ The camera module does not import `world`; the clearance comes in as a plain function. The wiring of one frame with a walking body (the body's own calls are those of `Walker`):
201
+
202
+ <!-- check: wrap -->
203
+ ```ts
204
+ import { FollowRig } from 'wallhammer-web/camera';
205
+ import { bindWalkInput } from 'wallhammer-web/platform';
206
+ import type { WalkInputState } from 'wallhammer-web/platform';
207
+ import type { Engine } from 'wallhammer-web/runtime';
208
+ declare const engine: Engine<FollowRig>; // createEngine({ view: rig, … }) without orbitControls
209
+ declare const world: { clearance(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDist: number, radius: number): number };
210
+ declare const walker: { advance(dt: number, intent: { moveX: number; moveZ: number; run: boolean; jump: boolean }): number; renderPosition(out: number[]): void };
211
+
212
+ const rig = new FollowRig(
213
+ { pivotHeight: 1.5, minDistance: 0, maxDistance: 10, followLag: 0.12 },
214
+ { clearance: (ox, oy, oz, dx, dy, dz, max) => world.clearance(ox, oy, oz, dx, dy, dz, max, 0.25) },
215
+ );
216
+ const input = bindWalkInput(engine.canvas, rig, { onChange: () => engine.invalidate() });
217
+
218
+ // Made once, written every frame: nothing is allocated per frame.
219
+ const state: WalkInputState = { forward: 0, right: 0, run: false, jump: false };
220
+ const intent = { moveX: 0, moveZ: 0, run: false, jump: false };
221
+ const fw = [0, 0, 0];
222
+ const at = [0, 0, 0];
223
+ let moving = false;
224
+
225
+ engine.onInput(() => {
226
+ input.read(state); // keys, pointer turns and the gamepad; the turns already went to the rig
227
+ rig.forward(fw);
228
+ // Forward along the view's heading, right along screen right (−fw.z, fw.x).
229
+ intent.moveX = fw[0]! * state.forward - fw[2]! * state.right;
230
+ intent.moveZ = fw[2]! * state.forward + fw[0]! * state.right;
231
+ intent.run = state.run;
232
+ intent.jump = state.jump;
233
+ walker.advance(engine.frameSeconds, intent);
234
+ moving = state.forward !== 0 || state.right !== 0;
235
+ });
236
+ engine.onExtract(() => {
237
+ walker.renderPosition(at);
238
+ rig.follow(at[0]!, at[1]!, at[2]!);
239
+ rig.update(engine.frameSeconds);
240
+ });
241
+ // The loop draws on demand; while the body or the view still moves it has to keep going.
242
+ engine.animateWhile(() => moving || input.gamepadConnected);
243
+
244
+ rig.distance = 0; // first person (a toggle key); the boom shortens at once
245
+ rig.distance = 4; // and grows back smoothly
246
+ ```
247
+
248
+ Setup (`FollowSetup`, defaults in `DEFAULT_FOLLOW`):
249
+
250
+ | Field | Default | Meaning |
251
+ | --- | --- | --- |
252
+ | `fovDeg` | 60 | Vertical field of view. |
253
+ | `near`, `far` | 0.1, 2000 | Near and far plane in metres; the scene's depth range only pulls them closer together. |
254
+ | `minDistance`, `maxDistance` | 1, 12 | Limits of the wheel zoom (`zoomBy`). `distance = 0` is allowed directly whatever `minDistance` is; with `minDistance` 0 zooming in below 0.5 m snaps to 0 and zooming out of 0 starts at 0.5 m. |
255
+ | `minPitchDeg`, `maxPitchDeg` | −40, 80 | Pitch limits; negative looks up from below the pivot. |
256
+ | `pivotHeight` | 1.5 | Pivot above the followed point. |
257
+ | `followLag` | 0.15 | Seconds in which the pivot closes 95 % of the gap to the followed point; 0 follows rigidly. The smoothing is the same at every frame rate. |
258
+ | `boomReturn` | 0.3 | Seconds in which a cut boom regains 95 % of its length; 0 springs back at once. |
259
+ | `turnPerPx` | 0.004 | Radians of turn per CSS pixel. |
260
+ | `minFocus` | 2 | Smallest distance in front of the eye that counts as the centre of the view (`metresPerPixel`, `refDepth`), for a short boom and first person. |
261
+
262
+ Members: `yawDeg`, `pitchDeg`, `distance` (wanted), `boom` (drawn, read only), `target` (the followed point), `pivot` (smoothed), `clearance` (replaceable), `follow`, `update`, `snap`, `turnPixels`, `zoomBy`, `forward`, `eye`, `screenRay`, `project`, and the `View` contract. `axes`, `viewProj` and `cornerRays` write into the `out` they are given; a still view keeps its `key()` string.
263
+
264
+ Weak spots:
265
+
266
+ - Flat world only: up is +y. On a curved world the pivot height, the horizon of `axes` and `forward` would be laid along the local up taken from an up source at the pivot, as `FreeRig` does; the places are marked in `camera/follow.ts`. Not built yet.
267
+ - No render origin: positions go to the renderer as they are, so keep the walking area within a few kilometres of the world origin.
268
+ - In first person the followed body is inside the near plane; hide it yourself. `followLag` still applies to the pivot; set it to 0 for a stiff head.
269
+
270
+ ### Walk controls
271
+
272
+ `bindWalkInput(canvas, view, options?)` drives anything with `dpr`, `turnPixels` and `zoomBy` (`WalkView`), `FollowRig` among them. It binds `W` `A` `S` `D` and the arrows (move), `Shift` (run), `Space` (jump, once per press), a drag (turn) and the wheel (boom length). A gamepad with the standard layout: the left stick moves, the right stick turns (`stickTurnPx` CSS pixels per second at full deflection, default 600), `A` jumps, pressing the left stick or `RT` runs; both sticks have a radial dead zone of `deadZone` (0.15). Options: `onChange` (request a frame; it is called on key changes, turns, and from `read` while movement is asked for), `keys` (replace single entries of `DEFAULT_WALK_KEYS`), `pointerLock` (a click locks the pointer and its movement turns the view; Escape lets it go), `wheelFactor`, `draggingClass`, `gamepad: false`.
273
+
274
+ It returns a `WalkInput`. Call `read(state)` once per frame: it writes `forward` and `right` (−1…1, in the view's frame), `run` and `jump` into your `WalkInputState` and returns it; the right stick turns the view by the real time since the previous call, or by the `dtSeconds` you pass. `pointerLocked` and `gamepadConnected` tell the state of the devices. A gamepad sends no events for its sticks, so while one is connected keep frames coming (`Engine.animateWhile`).
275
+
276
+ **Hand-over.** `input.enabled = false` hands the view to someone else, a scripted camera or another rig: held keys are released (a key still held counts again on its next key-down), a drag ends, a locked pointer is let go, a held gamepad button does not count as a new press afterwards, and nothing touches the view; `read` returns no movement. `true` takes it back. To switch the engine to another view use `Engine.setView(view)`: the new view gets the canvas size at once, and `createEngine({ orbitControls: true })` controls act only while their own view is the current one.
277
+
278
+ <!-- check: wrap -->
279
+ ```ts
280
+ import { FollowRig, PerspectiveOrbitRig } from 'wallhammer-web/camera';
281
+ import { bindWalkInput } from 'wallhammer-web/platform';
282
+ import type { Engine } from 'wallhammer-web/runtime';
283
+ declare const engine: Engine<PerspectiveOrbitRig | FollowRig>; // created with the orbit rig and orbitControls: true
284
+ declare const orbit: PerspectiveOrbitRig;
285
+
286
+ const rig = new FollowRig({ minDistance: 0 });
287
+ const input = bindWalkInput(engine.canvas, rig, { onChange: () => engine.invalidate(), pointerLock: true });
288
+ input.enabled = false; // start in the orbit view
289
+
290
+ function startWalking(): void {
291
+ rig.yawDeg = orbit.yaw / (Math.PI / 180);
292
+ engine.setView(rig);
293
+ input.enabled = true;
294
+ }
295
+ function stopWalking(): void {
296
+ input.enabled = false;
297
+ orbit.setState({ target: [rig.pivot[0], rig.pivot[1], rig.pivot[2]], yawDeg: rig.yawDeg });
298
+ engine.setView(orbit); // the orbit drag works again
299
+ }
300
+ ```
301
+
302
+ Touch is not built yet: a touch drag turns the view like a mouse drag, but there is no on-screen stick to walk with.
@@ -0,0 +1,123 @@
1
+ # Concepts
2
+
3
+ Six ideas explain most of the engine.
4
+
5
+ ## 1. Generators return plain data
6
+
7
+ A generator is a pure function. Input plus seed gives data. It never touches the GPU. The data contracts live in `wallhammer-web/base`:
8
+
9
+ | Type | Shape |
10
+ | --- | --- |
11
+ | `VertexLayout` | `{ stride, attribs: VertexAttrib[] }`. An attribute has `name`, `size` (1–4), `type` (`f32`, `i8`, `u8`, `i16`, `u16`, `i32`, `u32`), `offset`, and optional `normalized` and `integer`. |
12
+ | `MeshData` | `{ layout, vertices, indices, count, primitive? }`. `indices` may be `null`. |
13
+ | `InstanceData` | `{ layout, data: Float32Array }`. One record per instance. |
14
+ | `TextureData` | `{ width, height, format, data: Uint8Array, filter?, anisotropy? }`. Formats: `r8`, `r8ui`, `rg8`, `rgba8`. |
15
+ | `MaterialDesc` | `{ name, attribs, passes, state? }`. GLSL per pass, or `'depth'` for the shared shadow programs. |
16
+ | `BakeDesc` | A fragment shader with input textures, uniforms and targets that the GPU runs once into textures. |
17
+
18
+ The app hands this data to the renderer: `renderer.createMesh`, `createInstances`, `createTexture`, `bake`. That is the only upload path.
19
+
20
+ Because generators are pure, their output can be hashed. The golden test does exactly that ([Tools](tools.md#golden-hashes)).
21
+
22
+ ## 2. Determinism
23
+
24
+ Randomness comes from hashes, not from a generator state.
25
+
26
+ ```ts
27
+ import { hashInts, rand, randRange, streamSeed, unit } from 'wallhammer-web/gen-core';
28
+
29
+ const s = streamSeed('world-7', 'stones'); // a named stream of a world seed
30
+ const a = rand(s, 12, 4); // 0..1 for the keys (12, 4), always the same
31
+ const b = randRange(2, 5, s, 12, 4, 1); // 2..5
32
+ const c = unit(hashInts(s, 99)); // the same thing by hand
33
+ ```
34
+
35
+ Keys are integers from the input: a grid cell, a recipe index, an object id. They are never a loop counter over output. Then the result does not depend on generation order.
36
+
37
+ The simulation goes further. It runs on integer millimetres and integer ticks and avoids transcendental `Math` functions, so the same commands give the same state hash on every machine ([Simulation](simulation.md)).
38
+
39
+ Where an angle is needed and the result must agree between machines, use the reproducible functions of `base` (`detSinCosTurns` and relatives) instead of `Math.sin`. Orbits and nested frames are built on them ([Bodies on rails and nested frames](frames.md)).
40
+
41
+ Weak spot: only `sim` is checked for `Math.random` and clocks. In generators it is a convention. See [Architecture](architecture.md#conventions-the-check-does-not-enforce).
42
+
43
+ ## 3. The palette
44
+
45
+ The project names its colours. The engine turns them into a uniform table of up to 64 rows (`PALETTE_CAPACITY`).
46
+
47
+ ```ts
48
+ import { definePalette } from 'wallhammer-web/core';
49
+
50
+ const palette = definePalette({ ground: '#4d4335', sky: '#6795b1' });
51
+ palette.index('sky'); // 1: the row a shader reads as u_palette[1]
52
+ palette.color('sky'); // [r, g, b] in 0..1
53
+ palette.data(); // Float32Array for the renderer
54
+ ```
55
+
56
+ Rows keep insertion order. The engine has no global palette and no colour names. Content modules take row indices or RGB values.
57
+
58
+ ## 4. The Frame block and environment slots
59
+
60
+ Every program sees one uniform block, `Frame`. The renderer owns the view and light matrices in it. The environment owns the rest: light colours, time, wind, clouds, weather, fog. Projects and content modules add their own members through **environment slots** (`EnvSlot`). A slot has parameters, a pure `compute` from the generic `FrameEnvironment`, and a mapping of its values to vec4 lanes. The block layout is fixed when the engine is created. See [Rendering](rendering.md#environment-slots).
61
+
62
+ ## 5. Layers and passes
63
+
64
+ The renderer draws a list of layers in the order they were added. A layer implements `draw(ctx)` and is called once per pass. The passes are `shadow`, `color`, `data` and `overlay`. `ctx.pass` says which one is running. `MeshLayer`, `PieceLayer`, `InstancedLayer` and `InstanceCellLayer` cover most needs. See [Rendering](rendering.md).
65
+
66
+ ## 6. The frame order
67
+
68
+ `createEngine` owns the order. Init:
69
+
70
+ 1. simulation, 2. environment, 3. canvas and device, 4. Frame block from the slots, 5. renderer, 6. environment link, 7. view size, 8. input, 9. frame loop.
71
+
72
+ One frame:
73
+
74
+ 1. input hooks (`engine.onInput`). They queue commands.
75
+ 2. Whole fixed ticks of the simulation.
76
+ 3. Environment clocks.
77
+ 4. Extraction hooks (`engine.onExtract(alpha)`). They write interpolated transforms into layer data.
78
+ 5. The environment frame (Frame block values).
79
+ 6. Render.
80
+
81
+ `dispose()` runs the init order in reverse.
82
+
83
+ The loop draws on demand. It runs continuously only while the simulation or an environment clock is animating. Otherwise it draws on input, resize and `engine.invalidate()`.
84
+
85
+ The simulation never reads anything the image side owns. The image side reads the simulation only in extraction hooks.
86
+
87
+ ## 3 × 4 matrices
88
+
89
+ An affine transform (rotation, scale, shear, then translation) on the CPU is a `Mat34` of `wallhammer-web/base`: 12
90
+ numbers column by column, the three columns of the linear part and then the translation, the same layout as the first
91
+ 12 floats of an instance record (`writeInstance`). Every function takes `out` last and returns it; without `out` it
92
+ returns a new `Float64Array` (or a `[x, y, z]` for points). `out` may be one of the inputs. Angles are radians,
93
+ rotations right-handed, quaternions `[x, y, z, w]` as in `frames`.
94
+
95
+ | Function | Result |
96
+ | --- | --- |
97
+ | `mat34Identity(out?)`, `mat34Copy(m, out?)` | Identity; a copy. |
98
+ | `mat34Translation(x, y, z, out?)`, `mat34Scaling(sx, sy, sz, out?)` | Translation; scale. |
99
+ | `mat34RotationX/Y/Z(rad, out?)`, `mat34RotationAxis(ax, ay, az, rad, out?)` | Rotation about an axis (normalised; a zero axis gives the identity). |
100
+ | `mat34FromQuat(q, out?, tx?, ty?, tz?)` | Rotation of a unit quaternion, with an optional translation. |
101
+ | `mat34Multiply(a, b, out?)` | `a · b`: `b` applied first. |
102
+ | `mat34Determinant(m)`, `mat34Invert(m, out?)` | Determinant of the linear part; inverse, `null` when singular. |
103
+ | `mat34Point(m, x, y, z, out?)`, `mat34Direction(m, x, y, z, out?)`, `mat34Normal(m, x, y, z, out?)` | A point (with translation); a direction (without); a normal (cofactor matrix, normalised, sign kept for mirrors, the same rule as `instanceNormal` in GLSL). |
104
+
105
+ <!-- check: wrap -->
106
+ ```ts
107
+ import { mat34Invert, mat34Multiply, mat34Point, mat34RotationY, mat34Scaling, mat34Translation } from 'wallhammer-web/base';
108
+
109
+ const local = mat34Multiply(mat34RotationY(Math.PI / 4), mat34Scaling(2, 1, 2));
110
+ const world = mat34Multiply(mat34Translation(10, 0, 5), local);
111
+ const p = mat34Point(world, 1, 0, 0);
112
+ const back = mat34Invert(world);
113
+ const scratch = new Float32Array(12);
114
+ mat34Multiply(world, mat34RotationY(0.1), scratch); // allocation-free with out
115
+ console.log(p, back !== null && mat34Point(back, p[0], p[1], p[2]));
116
+ ```
117
+
118
+ ## Units and axes
119
+
120
+ - One unit is one metre. y is up.
121
+ - Inside the simulation, lengths are integer millimetres.
122
+ - In destructible descriptions, lengths are integer centimetres.
123
+ - Angles in public options are degrees (`yawDeg`, `pitchDeg`). Inside rigs and shaders they are radians.