wallhammer-web 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (408) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +88 -2
  3. package/dist/base/data.d.ts +67 -0
  4. package/dist/base/data.js +10 -0
  5. package/dist/base/destructible.d.ts +167 -0
  6. package/dist/base/destructible.js +47 -0
  7. package/dist/base/env-slot.d.ts +101 -0
  8. package/dist/base/env-slot.js +8 -0
  9. package/dist/base/frames.d.ts +138 -0
  10. package/dist/base/frames.js +459 -0
  11. package/dist/base/index.d.ts +21 -0
  12. package/dist/base/index.js +11 -0
  13. package/dist/base/mat34.d.ts +46 -0
  14. package/dist/base/mat34.js +173 -0
  15. package/dist/base/material.d.ts +87 -0
  16. package/dist/base/material.js +6 -0
  17. package/dist/base/math.d.ts +27 -0
  18. package/dist/base/math.js +60 -0
  19. package/dist/base/progress.d.ts +38 -0
  20. package/dist/base/progress.js +81 -0
  21. package/dist/base/rig.d.ts +177 -0
  22. package/dist/base/rig.js +97 -0
  23. package/dist/base/trig.d.ts +29 -0
  24. package/dist/base/trig.js +169 -0
  25. package/dist/base/up.d.ts +26 -0
  26. package/dist/base/up.js +40 -0
  27. package/dist/base/view.d.ts +128 -0
  28. package/dist/base/view.js +136 -0
  29. package/dist/camera/camera.d.ts +99 -0
  30. package/dist/camera/camera.js +228 -0
  31. package/dist/camera/follow.d.ts +120 -0
  32. package/dist/camera/follow.js +320 -0
  33. package/dist/camera/free.d.ts +153 -0
  34. package/dist/camera/free.js +359 -0
  35. package/dist/camera/index.d.ts +10 -0
  36. package/dist/camera/index.js +6 -0
  37. package/dist/camera/orbit.d.ts +93 -0
  38. package/dist/camera/orbit.js +261 -0
  39. package/dist/camera/path.d.ts +48 -0
  40. package/dist/camera/path.js +179 -0
  41. package/dist/core/ballistic.d.ts +66 -0
  42. package/dist/core/ballistic.js +104 -0
  43. package/dist/core/bodies.d.ts +77 -0
  44. package/dist/core/bodies.js +125 -0
  45. package/dist/core/clock.d.ts +37 -0
  46. package/dist/core/clock.js +87 -0
  47. package/dist/core/cover-fade.d.ts +14 -0
  48. package/dist/core/cover-fade.js +38 -0
  49. package/dist/core/index.d.ts +13 -0
  50. package/dist/core/index.js +8 -0
  51. package/dist/core/kepler.d.ts +74 -0
  52. package/dist/core/kepler.js +108 -0
  53. package/dist/core/level-fade.d.ts +66 -0
  54. package/dist/core/level-fade.js +123 -0
  55. package/dist/core/palette.d.ts +15 -0
  56. package/dist/core/palette.js +47 -0
  57. package/dist/env/atmosphere.d.ts +129 -0
  58. package/dist/env/atmosphere.js +707 -0
  59. package/dist/env/cloud-field.d.ts +44 -0
  60. package/dist/env/cloud-field.js +111 -0
  61. package/dist/env/environment.d.ts +217 -0
  62. package/dist/env/environment.js +441 -0
  63. package/dist/env/frame-block.d.ts +29 -0
  64. package/dist/env/frame-block.js +152 -0
  65. package/dist/env/glsl.d.ts +35 -0
  66. package/dist/env/glsl.js +246 -0
  67. package/dist/env/index.d.ts +13 -0
  68. package/dist/env/index.js +9 -0
  69. package/dist/env/sky.d.ts +48 -0
  70. package/dist/env/sky.js +227 -0
  71. package/dist/env/sun.d.ts +31 -0
  72. package/dist/env/sun.js +42 -0
  73. package/dist/gen-arch/build.d.ts +17 -0
  74. package/dist/gen-arch/build.js +414 -0
  75. package/dist/gen-arch/damage/damaged.d.ts +44 -0
  76. package/dist/gen-arch/damage/damaged.js +1119 -0
  77. package/dist/gen-arch/damage/fall-material.d.ts +10 -0
  78. package/dist/gen-arch/damage/fall-material.js +47 -0
  79. package/dist/gen-arch/damage/fall.d.ts +78 -0
  80. package/dist/gen-arch/damage/fall.js +797 -0
  81. package/dist/gen-arch/damage/rubble.d.ts +22 -0
  82. package/dist/gen-arch/damage/rubble.js +188 -0
  83. package/dist/gen-arch/index.d.ts +25 -0
  84. package/dist/gen-arch/index.js +16 -0
  85. package/dist/gen-arch/interior/interior-plan.d.ts +114 -0
  86. package/dist/gen-arch/interior/interior-plan.js +615 -0
  87. package/dist/gen-arch/interior/interior.d.ts +97 -0
  88. package/dist/gen-arch/interior/interior.js +966 -0
  89. package/dist/gen-arch/structure/building-shader.d.ts +25 -0
  90. package/dist/gen-arch/structure/building-shader.js +946 -0
  91. package/dist/gen-arch/structure/buildings.d.ts +248 -0
  92. package/dist/gen-arch/structure/buildings.js +294 -0
  93. package/dist/gen-arch/structure/dims.d.ts +77 -0
  94. package/dist/gen-arch/structure/dims.js +39 -0
  95. package/dist/gen-arch/structure/distant.d.ts +62 -0
  96. package/dist/gen-arch/structure/distant.js +316 -0
  97. package/dist/gen-arch/structure/env-slots.d.ts +18 -0
  98. package/dist/gen-arch/structure/env-slots.js +47 -0
  99. package/dist/gen-arch/structure/facade.d.ts +193 -0
  100. package/dist/gen-arch/structure/facade.js +159 -0
  101. package/dist/gen-arch/structure/parts.d.ts +31 -0
  102. package/dist/gen-arch/structure/parts.js +69 -0
  103. package/dist/gen-arch/structure/roof.d.ts +76 -0
  104. package/dist/gen-arch/structure/roof.js +568 -0
  105. package/dist/gen-arch/structure/structure-material.d.ts +23 -0
  106. package/dist/gen-arch/structure/structure-material.js +55 -0
  107. package/dist/gen-arch/structure/writer.d.ts +94 -0
  108. package/dist/gen-arch/structure/writer.js +195 -0
  109. package/dist/gen-core/cell.d.ts +138 -0
  110. package/dist/gen-core/cell.js +150 -0
  111. package/dist/gen-core/cube-sphere.d.ts +57 -0
  112. package/dist/gen-core/cube-sphere.js +159 -0
  113. package/dist/gen-core/field.d.ts +55 -0
  114. package/dist/gen-core/field.js +154 -0
  115. package/dist/gen-core/geometry.d.ts +31 -0
  116. package/dist/gen-core/geometry.js +231 -0
  117. package/dist/gen-core/hash.d.ts +18 -0
  118. package/dist/gen-core/hash.js +58 -0
  119. package/dist/gen-core/height-field.d.ts +33 -0
  120. package/dist/gen-core/height-field.js +137 -0
  121. package/dist/gen-core/index.d.ts +22 -0
  122. package/dist/gen-core/index.js +17 -0
  123. package/dist/gen-core/instance-cells.d.ts +37 -0
  124. package/dist/gen-core/instance-cells.js +72 -0
  125. package/dist/gen-core/near-scatter.d.ts +56 -0
  126. package/dist/gen-core/near-scatter.js +120 -0
  127. package/dist/gen-core/noise.d.ts +23 -0
  128. package/dist/gen-core/noise.js +72 -0
  129. package/dist/gen-core/occupancy.d.ts +21 -0
  130. package/dist/gen-core/occupancy.js +104 -0
  131. package/dist/gen-core/sphere-patch.d.ts +138 -0
  132. package/dist/gen-core/sphere-patch.js +544 -0
  133. package/dist/gen-core/strip-surface.d.ts +34 -0
  134. package/dist/gen-core/strip-surface.js +246 -0
  135. package/dist/gen-core/strip.d.ts +102 -0
  136. package/dist/gen-core/strip.js +817 -0
  137. package/dist/gen-ground/env-slots.d.ts +48 -0
  138. package/dist/gen-ground/env-slots.js +78 -0
  139. package/dist/gen-ground/ground.d.ts +78 -0
  140. package/dist/gen-ground/ground.js +208 -0
  141. package/dist/gen-ground/index.d.ts +9 -0
  142. package/dist/gen-ground/index.js +7 -0
  143. package/dist/gen-ground/markings.d.ts +46 -0
  144. package/dist/gen-ground/markings.js +124 -0
  145. package/dist/gen-ground/materials.d.ts +18 -0
  146. package/dist/gen-ground/materials.js +22 -0
  147. package/dist/gen-ground/terrain-shader.d.ts +5 -0
  148. package/dist/gen-ground/terrain-shader.js +151 -0
  149. package/dist/gen-mesh/bare-shapes.d.ts +194 -0
  150. package/dist/gen-mesh/bare-shapes.js +596 -0
  151. package/dist/gen-mesh/bisect-surface.d.ts +47 -0
  152. package/dist/gen-mesh/bisect-surface.js +261 -0
  153. package/dist/gen-mesh/box.d.ts +18 -0
  154. package/dist/gen-mesh/box.js +2 -0
  155. package/dist/gen-mesh/cell-morph-mesh.d.ts +52 -0
  156. package/dist/gen-mesh/cell-morph-mesh.js +258 -0
  157. package/dist/gen-mesh/cell-surface-mesh.d.ts +32 -0
  158. package/dist/gen-mesh/cell-surface-mesh.js +140 -0
  159. package/dist/gen-mesh/chunk-mesh.d.ts +25 -0
  160. package/dist/gen-mesh/chunk-mesh.js +112 -0
  161. package/dist/gen-mesh/drape-mesh.d.ts +36 -0
  162. package/dist/gen-mesh/drape-mesh.js +98 -0
  163. package/dist/gen-mesh/height-field-mesh.d.ts +14 -0
  164. package/dist/gen-mesh/height-field-mesh.js +98 -0
  165. package/dist/gen-mesh/index.d.ts +26 -0
  166. package/dist/gen-mesh/index.js +15 -0
  167. package/dist/gen-mesh/line-mesh.d.ts +25 -0
  168. package/dist/gen-mesh/line-mesh.js +62 -0
  169. package/dist/gen-mesh/mesh-builder.d.ts +115 -0
  170. package/dist/gen-mesh/mesh-builder.js +315 -0
  171. package/dist/gen-mesh/packed-mesh.d.ts +53 -0
  172. package/dist/gen-mesh/packed-mesh.js +205 -0
  173. package/dist/gen-mesh/prism-mesh.d.ts +33 -0
  174. package/dist/gen-mesh/prism-mesh.js +176 -0
  175. package/dist/gen-mesh/rig-mesh.d.ts +9 -0
  176. package/dist/gen-mesh/rig-mesh.js +135 -0
  177. package/dist/gen-mesh/strip-mesh.d.ts +45 -0
  178. package/dist/gen-mesh/strip-mesh.js +258 -0
  179. package/dist/gen-plan/drain.d.ts +58 -0
  180. package/dist/gen-plan/drain.js +270 -0
  181. package/dist/gen-plan/grid.d.ts +37 -0
  182. package/dist/gen-plan/grid.js +182 -0
  183. package/dist/gen-plan/horizon.d.ts +50 -0
  184. package/dist/gen-plan/horizon.js +185 -0
  185. package/dist/gen-plan/index.d.ts +15 -0
  186. package/dist/gen-plan/index.js +13 -0
  187. package/dist/gen-plan/line-tiles.d.ts +35 -0
  188. package/dist/gen-plan/line-tiles.js +190 -0
  189. package/dist/gen-plan/lines.d.ts +31 -0
  190. package/dist/gen-plan/lines.js +183 -0
  191. package/dist/gen-plan/plots.d.ts +40 -0
  192. package/dist/gen-plan/plots.js +282 -0
  193. package/dist/gen-plan/route.d.ts +55 -0
  194. package/dist/gen-plan/route.js +297 -0
  195. package/dist/gen-plan/sites.d.ts +32 -0
  196. package/dist/gen-plan/sites.js +209 -0
  197. package/dist/gen-tex/code-stamp.d.ts +31 -0
  198. package/dist/gen-tex/code-stamp.js +137 -0
  199. package/dist/gen-tex/index.d.ts +7 -0
  200. package/dist/gen-tex/index.js +5 -0
  201. package/dist/gen-tex/light-horizon.d.ts +47 -0
  202. package/dist/gen-tex/light-horizon.js +180 -0
  203. package/dist/gen-tex/textures.d.ts +8 -0
  204. package/dist/gen-tex/textures.js +49 -0
  205. package/dist/gen-tex/value-textures.d.ts +46 -0
  206. package/dist/gen-tex/value-textures.js +102 -0
  207. package/dist/gen-vegetation/env-slots.d.ts +20 -0
  208. package/dist/gen-vegetation/env-slots.js +29 -0
  209. package/dist/gen-vegetation/index.d.ts +8 -0
  210. package/dist/gen-vegetation/index.js +7 -0
  211. package/dist/gen-vegetation/materials.d.ts +7 -0
  212. package/dist/gen-vegetation/materials.js +17 -0
  213. package/dist/gen-vegetation/planting.d.ts +170 -0
  214. package/dist/gen-vegetation/planting.js +363 -0
  215. package/dist/gen-vegetation/tree-shader.d.ts +23 -0
  216. package/dist/gen-vegetation/tree-shader.js +229 -0
  217. package/dist/gen-vegetation/trees.d.ts +59 -0
  218. package/dist/gen-vegetation/trees.js +329 -0
  219. package/dist/gpu/device.d.ts +286 -0
  220. package/dist/gpu/device.js +1157 -0
  221. package/dist/gpu/gl.d.ts +134 -0
  222. package/dist/gpu/gl.js +276 -0
  223. package/dist/gpu/index.d.ts +4 -0
  224. package/dist/gpu/index.js +3 -0
  225. package/dist/index.d.ts +11 -0
  226. package/dist/index.js +13 -0
  227. package/dist/motion/graph.d.ts +244 -0
  228. package/dist/motion/graph.js +739 -0
  229. package/dist/motion/index.d.ts +8 -0
  230. package/dist/motion/index.js +8 -0
  231. package/dist/motion/pose-ops.d.ts +30 -0
  232. package/dist/motion/pose-ops.js +232 -0
  233. package/dist/motion/reach.d.ts +45 -0
  234. package/dist/motion/reach.js +264 -0
  235. package/dist/motion/skeleton.d.ts +49 -0
  236. package/dist/motion/skeleton.js +99 -0
  237. package/dist/platform/byte-store.d.ts +21 -0
  238. package/dist/platform/byte-store.js +137 -0
  239. package/dist/platform/canvas.d.ts +29 -0
  240. package/dist/platform/canvas.js +76 -0
  241. package/dist/platform/context-loss.d.ts +8 -0
  242. package/dist/platform/context-loss.js +17 -0
  243. package/dist/platform/free-input.d.ts +51 -0
  244. package/dist/platform/free-input.js +100 -0
  245. package/dist/platform/index.d.ts +18 -0
  246. package/dist/platform/index.js +10 -0
  247. package/dist/platform/input.d.ts +48 -0
  248. package/dist/platform/input.js +117 -0
  249. package/dist/platform/keys.d.ts +12 -0
  250. package/dist/platform/keys.js +29 -0
  251. package/dist/platform/loop.d.ts +41 -0
  252. package/dist/platform/loop.js +84 -0
  253. package/dist/platform/walk-input.d.ts +74 -0
  254. package/dist/platform/walk-input.js +226 -0
  255. package/dist/platform/worker.d.ts +51 -0
  256. package/dist/platform/worker.js +170 -0
  257. package/dist/render/bone-instances.d.ts +24 -0
  258. package/dist/render/bone-instances.js +74 -0
  259. package/dist/render/cells.d.ts +70 -0
  260. package/dist/render/cells.js +144 -0
  261. package/dist/render/glsl.d.ts +66 -0
  262. package/dist/render/glsl.js +173 -0
  263. package/dist/render/index.d.ts +26 -0
  264. package/dist/render/index.js +16 -0
  265. package/dist/render/instance-sets.d.ts +97 -0
  266. package/dist/render/instance-sets.js +241 -0
  267. package/dist/render/near-instances.d.ts +75 -0
  268. package/dist/render/near-instances.js +219 -0
  269. package/dist/render/particles.d.ts +63 -0
  270. package/dist/render/particles.js +215 -0
  271. package/dist/render/pieces.d.ts +57 -0
  272. package/dist/render/pieces.js +151 -0
  273. package/dist/render/point-lights.d.ts +97 -0
  274. package/dist/render/point-lights.js +243 -0
  275. package/dist/render/renderer.d.ts +447 -0
  276. package/dist/render/renderer.js +1100 -0
  277. package/dist/render/rig.d.ts +74 -0
  278. package/dist/render/rig.js +576 -0
  279. package/dist/render/shadow-areas.d.ts +49 -0
  280. package/dist/render/shadow-areas.js +125 -0
  281. package/dist/render/shadow-glsl.d.ts +12 -0
  282. package/dist/render/shadow-glsl.js +146 -0
  283. package/dist/render/transient.d.ts +61 -0
  284. package/dist/render/transient.js +213 -0
  285. package/dist/render/value-glsl.d.ts +17 -0
  286. package/dist/render/value-glsl.js +208 -0
  287. package/dist/render/value-layers.d.ts +180 -0
  288. package/dist/render/value-layers.js +333 -0
  289. package/dist/runtime/atmosphere.d.ts +37 -0
  290. package/dist/runtime/atmosphere.js +304 -0
  291. package/dist/runtime/cloud-shell.d.ts +29 -0
  292. package/dist/runtime/cloud-shell.js +158 -0
  293. package/dist/runtime/engine.d.ts +155 -0
  294. package/dist/runtime/engine.js +305 -0
  295. package/dist/runtime/environment-link.d.ts +22 -0
  296. package/dist/runtime/environment-link.js +49 -0
  297. package/dist/runtime/index.d.ts +13 -0
  298. package/dist/runtime/index.js +12 -0
  299. package/dist/runtime/precipitation-glsl.d.ts +2 -0
  300. package/dist/runtime/precipitation-glsl.js +70 -0
  301. package/dist/runtime/precipitation.d.ts +11 -0
  302. package/dist/runtime/precipitation.js +78 -0
  303. package/dist/runtime/sky.d.ts +30 -0
  304. package/dist/runtime/sky.js +114 -0
  305. package/dist/runtime/streaming.d.ts +245 -0
  306. package/dist/runtime/streaming.js +602 -0
  307. package/dist/sim/agenda.d.ts +167 -0
  308. package/dist/sim/agenda.js +425 -0
  309. package/dist/sim/bytes.d.ts +34 -0
  310. package/dist/sim/bytes.js +125 -0
  311. package/dist/sim/destruction/apply.d.ts +59 -0
  312. package/dist/sim/destruction/apply.js +243 -0
  313. package/dist/sim/destruction/cell-states.d.ts +54 -0
  314. package/dist/sim/destruction/cell-states.js +198 -0
  315. package/dist/sim/destruction/index.d.ts +11 -0
  316. package/dist/sim/destruction/index.js +10 -0
  317. package/dist/sim/destruction/int-geometry.d.ts +17 -0
  318. package/dist/sim/destruction/int-geometry.js +131 -0
  319. package/dist/sim/destruction/pick.d.ts +13 -0
  320. package/dist/sim/destruction/pick.js +59 -0
  321. package/dist/sim/destruction/rubble.d.ts +8 -0
  322. package/dist/sim/destruction/rubble.js +159 -0
  323. package/dist/sim/destruction/state.d.ts +15 -0
  324. package/dist/sim/destruction/state.js +83 -0
  325. package/dist/sim/destruction/structure.d.ts +30 -0
  326. package/dist/sim/destruction/structure.js +139 -0
  327. package/dist/sim/events.d.ts +37 -0
  328. package/dist/sim/events.js +106 -0
  329. package/dist/sim/fixed.d.ts +21 -0
  330. package/dist/sim/fixed.js +64 -0
  331. package/dist/sim/flow-probe.d.ts +58 -0
  332. package/dist/sim/flow-probe.js +158 -0
  333. package/dist/sim/flow.d.ts +257 -0
  334. package/dist/sim/flow.js +967 -0
  335. package/dist/sim/index.d.ts +28 -0
  336. package/dist/sim/index.js +20 -0
  337. package/dist/sim/interlock.d.ts +47 -0
  338. package/dist/sim/interlock.js +252 -0
  339. package/dist/sim/movers.d.ts +228 -0
  340. package/dist/sim/movers.js +1083 -0
  341. package/dist/sim/nav.d.ts +72 -0
  342. package/dist/sim/nav.js +292 -0
  343. package/dist/sim/paths.d.ts +80 -0
  344. package/dist/sim/paths.js +197 -0
  345. package/dist/sim/regions.d.ts +87 -0
  346. package/dist/sim/regions.js +517 -0
  347. package/dist/sim/simulation.d.ts +114 -0
  348. package/dist/sim/simulation.js +291 -0
  349. package/dist/sim/states.d.ts +23 -0
  350. package/dist/sim/states.js +54 -0
  351. package/dist/sim/table.d.ts +49 -0
  352. package/dist/sim/table.js +126 -0
  353. package/dist/sim/zones.d.ts +11 -0
  354. package/dist/sim/zones.js +196 -0
  355. package/dist/tools/collision-lines.d.ts +12 -0
  356. package/dist/tools/collision-lines.js +50 -0
  357. package/dist/tools/data-view-glsl.d.ts +3 -0
  358. package/dist/tools/data-view-glsl.js +63 -0
  359. package/dist/tools/data-view-layers.d.ts +20 -0
  360. package/dist/tools/data-view-layers.js +60 -0
  361. package/dist/tools/debug-view.d.ts +30 -0
  362. package/dist/tools/debug-view.js +4 -0
  363. package/dist/tools/index.d.ts +10 -0
  364. package/dist/tools/index.js +7 -0
  365. package/dist/tools/mesh-checks.d.ts +67 -0
  366. package/dist/tools/mesh-checks.js +188 -0
  367. package/dist/tools/profile.d.ts +85 -0
  368. package/dist/tools/profile.js +173 -0
  369. package/dist/world/cell-cache.d.ts +32 -0
  370. package/dist/world/cell-cache.js +60 -0
  371. package/dist/world/cell-format.d.ts +25 -0
  372. package/dist/world/cell-format.js +232 -0
  373. package/dist/world/collide.d.ts +192 -0
  374. package/dist/world/collide.js +822 -0
  375. package/dist/world/index.d.ts +16 -0
  376. package/dist/world/index.js +12 -0
  377. package/dist/world/mesh-solids.d.ts +48 -0
  378. package/dist/world/mesh-solids.js +169 -0
  379. package/dist/world/pick.d.ts +34 -0
  380. package/dist/world/pick.js +177 -0
  381. package/dist/world/providers.d.ts +66 -0
  382. package/dist/world/providers.js +83 -0
  383. package/dist/world/sphere.d.ts +69 -0
  384. package/dist/world/sphere.js +271 -0
  385. package/dist/world/streaming.d.ts +288 -0
  386. package/dist/world/streaming.js +801 -0
  387. package/dist/world/walker.d.ts +145 -0
  388. package/dist/world/walker.js +502 -0
  389. package/docs/architecture.md +111 -0
  390. package/docs/cameras.md +302 -0
  391. package/docs/concepts.md +123 -0
  392. package/docs/destruction.md +127 -0
  393. package/docs/frames.md +199 -0
  394. package/docs/generators.md +575 -0
  395. package/docs/getting-started.md +123 -0
  396. package/docs/headless.md +50 -0
  397. package/docs/motion.md +160 -0
  398. package/docs/planet.md +152 -0
  399. package/docs/recipes.md +521 -0
  400. package/docs/reference.md +364 -0
  401. package/docs/rendering.md +823 -0
  402. package/docs/rigs.md +203 -0
  403. package/docs/simulation.md +235 -0
  404. package/docs/streaming.md +590 -0
  405. package/docs/system.md +166 -0
  406. package/docs/tools.md +175 -0
  407. package/docs/walking.md +262 -0
  408. package/package.json +131 -3
@@ -0,0 +1,590 @@
1
+ # World streaming
2
+
3
+ Streaming loads and unloads cells of a quadtree around the viewer. It is split by layer:
4
+
5
+ | Part | Entry | GPU? |
6
+ | --- | --- | --- |
7
+ | Cell ids, `FlatWorld`, `CellContent` | `wallhammer-web/gen-core` | no |
8
+ | `StreamingManager`, providers, the WHC1 file format | `wallhammer-web/world` | no |
9
+ | `StreamedWorld` (a `Layer`), `WorkerCellProvider`, `serveCellGenerator`, `viewTickets` | `wallhammer-web/runtime` | yes |
10
+
11
+ The working example is `examples/endless`. Its generator and the golden recipes named on this page ("streaming seams" and the others, except "streaming GPU ceiling") live there too.
12
+
13
+ ## Cells
14
+
15
+ A `CellId` is `{ face, level, x, y }`. The flat world uses `FACE_FLAT` (7). A root cell at level 0 is `FLAT_ROOT_EDGE_M` (65,536 m) wide; each level halves the edge. `LEVEL` names three levels (`region` 4, `district` 6, `cell` 8). `FlatWorld` implements `WorldShape`: `edgeM(level)`, `origin(cell)` and so on.
16
+
17
+ The manager asks the shape every question of place, so it works on any shape, not only on a plane:
18
+
19
+ | `WorldShape` member | The manager uses it for |
20
+ | --- | --- |
21
+ | `cellsNear(p, reachM, level)` | The coarsest cells near a ticket (a superset is fine). |
22
+ | `distanceM(cell, p)` | The distance along the surface from under a ticket to a cell; the ticket's altitude is combined with it. |
23
+ | `center(cell)`, `upAt(p)` | Which cells lie ahead of a ticket's direction, measured across "up" at the ticket. |
24
+ | `children(cell)`, `parent(cell)`, `edgeM(level)` | The quadtree. |
25
+ | `hashKey` | The identity of the shape. `shapeHash(shape)` turns it into a 32-bit number for cell files. |
26
+
27
+ `StreamingConfig.face` is optional: without it every face the shape reports near a ticket is streamed.
28
+
29
+ A cell's content is plain data:
30
+
31
+ ```ts
32
+ import type { CellContent } from 'wallhammer-web/gen-core';
33
+
34
+ const empty = (c: CellContent['cell']): CellContent => ({
35
+ cell: c,
36
+ domainVersion: 1, // bump when the generator's output changes on purpose
37
+ bounds: { min: [0, 0, 0], max: [1, 1, 1] }, // relative to the cell origin
38
+ meshes: [], // { material: name, mesh: MeshData } relative to the cell origin
39
+ instances: [], // { archetype: name, data: InstanceData, ids: Uint32Array of [high, low] pairs }
40
+ // Optional, both off by default (a cell that states either is written in cell format 2):
41
+ // shapeHash: shapeHash(shape) - the shape the cell was built for
42
+ // error: 0.4 - metres between this cell's surface and the one its children would show
43
+ });
44
+ ```
45
+
46
+ Positions inside a cell are relative to the cell origin. That keeps float precision at 10,000 km from the origin.
47
+
48
+ ## Generators and providers
49
+
50
+ A `CellGenerator` is `(seed, cell) => CellContent`. It must be pure. A generator that also takes edits is an `EditableCellGenerator` (see [Edits and refresh](#edits-and-refresh)). Neighbouring cells must agree on their shared border; the golden test of the examples checks this for the example generator ("streaming seams").
51
+
52
+ A `CellProvider` delivers content: `{ name, blocking, request(cell, signal) }`.
53
+
54
+ | Provider | Entry | Source |
55
+ | --- | --- | --- |
56
+ | `GeneratorCellProvider(seed, gen, edits?)` | `world` | Runs the generator on the main thread (`blocking: true`). `generateNow` and `bytes` serve tools. |
57
+ | `WorkerCellProvider(url, seed, size?, edits?)` | `runtime` | Runs the generator in workers. The worker script calls `serveCellGenerator(gen)`. |
58
+ | `FileCellProvider(baseUrl, fetch, { shapeHash? })` | `world` | Reads `<base>/<face>/<level>/<x>/<y>.whc` (`cellFilePath`). Pass `fetchBytes` from `platform` in the browser. |
59
+
60
+ Workers that need the same data before they generate cells (a plan of the whole sphere, say) get it with `WorkerPool.broadcast(message)`: one structured copy goes to every worker, to a busy one right after its running job and in any case before the jobs still queued, and the promise resolves when every worker has answered. A cell job sent after the broadcast resolved therefore finds the data in whichever worker takes it. Broadcast replies do not count in `timing`.
61
+
62
+ `encodeCell` and `decodeCell` convert content to and from the WHC1 binary format. A file provider and a generator provider must give the same bytes; the golden test of the examples checks it, and `examples/endless/scripts/verify.ts` checks baked files.
63
+
64
+ The format has two versions. A cell that states neither `shapeHash` nor `error` is written in format 1 (`CELL_FORMAT_VERSION`), with the same bytes as before. A cell that states one of them is written in format 2 (`CELL_FORMAT_VERSION_SHAPED`), which adds the two fields after the cell id. `decodeCell` reads both.
65
+
66
+ The shape hash keeps cells of different shapes apart (another radius, another root edge):
67
+
68
+ - `cellFilePath(cell, shapeHash)` puts the hash in front of the path: `s<8 hex digits>/<face>/<level>/<x>/<y>.whc`.
69
+ - `FileCellProvider` with the `shapeHash` option reads from that folder and rejects a file that states another shape.
70
+ - `StreamedWorld` refuses a cell whose `shapeHash` differs from its own shape (`stats().shapeMismatches`).
71
+
72
+ ## The manager
73
+
74
+ `StreamingManager(config)` decides which cells are wanted. It does no I/O itself. Each frame:
75
+
76
+ 1. `update(tickets)` returns `StreamingActions`: `requests`, `cancels`, `uploads`, `releases`, `evictions`.
77
+ 2. The caller runs them and reports back: `complete(req, cpuBytes, errorM?)` or `fail(req)` for a request, `resident(cell, gpuBytes)` after an upload.
78
+ 3. `state(cell)`, `drawn()`, `wanted()`, `settled`, `stale` and `counters` describe the state.
79
+
80
+ A `Ticket` is a point of interest: `{ id, kind, center, altitude?, base, dir?, pixelsPerRadian?, preload? }`. `dir` is `[x, z]` on a flat world or a world direction `[x, y, z]`. `viewTickets(eye, altitude, forward, velocity)` makes the usual set on a flat world: the camera plus a predicted point ahead. `viewerTickets({ eye, altitude, forward, velocity?, pixelsPerRadian? })` does the same with world directions, for any shape.
81
+
82
+ `DEFAULT_STREAMING` (without `shape` and `face`): `rootLevel` 4, `leafLevel` 8, `rootRange` 2, `splitLevel` 1, `prefetch` 0.5, `hysteresis` 0.75, `maxInFlight` 8, `memoryBudgetBytes` 128 MB. `screenError` is not set.
83
+
84
+ ## Selection by screen-space error
85
+
86
+ Off by default. Without it a cell is split while a ticket is within `splitLevel` cell edges. With `screenError` in the config the split distance follows from the screen instead:
87
+
88
+ | `ScreenErrorConfig` | Meaning |
89
+ | --- | --- |
90
+ | `maxErrorPx` | The largest error left on the screen, in pixels. |
91
+ | `errorPerEdge` | Error of a cell as a share of its edge. For a grid of n quads per edge use `1 / (8 · n)`. |
92
+ | `minErrorPerEdge?` | A measured error never counts as less than this share of the edge. Default 0. |
93
+ | `pixelsPerRadian` | For tickets that do not state their own. `pixelsPerRadian(viewportHeightPx, fovYRad)` computes it. |
94
+ | `maxCells?` | Budget of cells wanted on the GPU at once. |
95
+
96
+ A cell is split while a ticket is within `errorPerEdge × pixelsPerRadian ÷ maxErrorPx` edges (`manager.splitDistance(ticket)`). `prefetch` and `hysteresis` keep their share of that distance. Four more rules apply:
97
+
98
+ - **Loaded parents only.** The manager never asks for a cell whose parent is not loaded. Until a cell is loaded nothing could stand in for its children, and its error is not known. After `complete` the manager reports `stale`: run another `update` (`StreamedWorld` does).
99
+ - **Measured error.** A cell that reports `CellContent.error` smaller than `errorPerEdge × edge` is split later; with error 0 and no `minErrorPerEdge`, never. A generator whose cells carry content the error does not measure (instances that appear at finer levels) should report the full error for those cells. With blending between levels the same holds for every cell whose shape differs from its children's: the blend ends where a cell with the full error is split, so a cell split later is replaced by children already in their own shape, a step of up to `maxErrorPx` on the screen.
100
+ - **Budget of cells.** When the plan wants more than `maxCells`, the split distance shrinks in steps of 2^¼ until the plan fits, and grows back when the finer plan would use at most 85 % of the budget. `counters().detail` is the share in use.
101
+ - **Ahead first.** Jobs for cells in front of a ticket's direction start before the others, then the nearest. `maxInFlight` is the budget of jobs.
102
+ - **Preloading tickets.** A ticket with `preload: true` fetches the cells it would split and keeps them ready on the CPU, but does not change what is drawn; the cells go to the screen once another ticket wants them. Default off. Use it for the predicted point ahead of the viewer when levels blend: `tickets.map((t) => (t.kind === 'predict' ? { ...t, preload: true } : t))`.
103
+
104
+ ```ts
105
+ import { FACE_FLAT, FlatWorld } from 'wallhammer-web/gen-core';
106
+ import { DEFAULT_STREAMING, StreamingManager, pixelsPerRadian } from 'wallhammer-web/world';
107
+ import type { StreamingConfig } from 'wallhammer-web/world';
108
+ import { viewerTickets } from 'wallhammer-web/runtime';
109
+
110
+ const fovY = (50 * Math.PI) / 180;
111
+ const config: StreamingConfig = {
112
+ ...DEFAULT_STREAMING,
113
+ shape: new FlatWorld(),
114
+ face: FACE_FLAT,
115
+ prefetch: 0.2,
116
+ hysteresis: 0.3,
117
+ screenError: {
118
+ maxErrorPx: 2,
119
+ errorPerEdge: 1 / (8 * 32), // cells of 32 quads per edge
120
+ pixelsPerRadian: pixelsPerRadian(1080, fovY),
121
+ maxCells: 800,
122
+ },
123
+ };
124
+ const manager = new StreamingManager(config);
125
+ // Every frame: the viewer with the size of its own screen.
126
+ const tickets = viewerTickets({ eye: [0, 300, 0], altitude: 300, forward: [0, 0, -1], pixelsPerRadian: pixelsPerRadian(1440, fovY) });
127
+ const actions = manager.update(tickets);
128
+ ```
129
+
130
+ ## Blending between levels
131
+
132
+ Off by default. Without it a level-of-detail change is a visible jump and only the skirt hides the cracks. The blend has three parts:
133
+
134
+ 1. **The generator** builds the cell with `cellMorphMesh` (module `gen-mesh`) instead of `cellSurfaceMesh`. Every vertex then also carries the distance to the surface of the cell one level coarser, and that surface's normal and colour (`CELL_MORPH_LAYOUT`). The coarser surface is not sampled again: it is the cell's own grid thinned by two. The result also gives `error` for `CellContent.error` and a skirt deep enough for its border.
135
+ 2. **The material** pastes `CELL_MORPH_GLSL` into its vertex shaders (colour and shadow) and moves each vertex by `cellMorph(p)`: 0 is the cell's own shape, 1 the coarser one.
136
+ 3. **`StreamedWorld`** gets `morph: true`. It then sets `u_morphEye`, `u_morphUp` (per frame) and `u_cellMorph` (per cell) from `manager.morphRange(level)`, and redraws shadows when the viewer has moved far enough to change the blend.
137
+
138
+ `morphRange(level)` returns `{ startM, endM }` for the viewer (`manager.viewer()`, the ticket with the lowest base). A cell is in its own shape nearer than `startM` and in its parent's shape from `endM`, which is exactly where the parent stops being split. So a cell that has just replaced its parent looks like the parent, and a cell next to a coarser one meets it without a crack. This holds for a parent that is split at the full split distance. A parent that reported a smaller `error` is split nearer, where its children have already left its shape; report the full error (`errorPerEdge × edge`) for cells that must not show that step, as the endless example does for every cell with land.
139
+
140
+ The blend is measured from the viewer alone. A second ticket that splits cells away from the viewer (the predicted point of `viewTickets`) puts cells on the screen in their parent's plain shape, next to cells that already blend into theirs: a step, which the skirt covers, and a jump when the split happens. Mark such a ticket `preload: true`.
141
+
142
+ The blend is exact while the split distance is at least 2.02 cell edges. Below that (a small `splitLevel`, or the budget of cells holding the detail down) the blend is squeezed into the last 15 % of the way and small steps remain; the skirt covers them.
143
+
144
+ ```ts
145
+ import { FlatWorld, shapeHash, valueNoise2 } from 'wallhammer-web/gen-core';
146
+ import type { CellContent, CellId } from 'wallhammer-web/gen-core';
147
+ import { CELL_MORPH_GLSL, cellMorphMesh } from 'wallhammer-web/gen-mesh';
148
+
149
+ const shape = new FlatWorld();
150
+
151
+ export function generate(seed: number, cell: CellId): CellContent {
152
+ const size = shape.edgeM(cell.level);
153
+ const o = shape.origin(cell);
154
+ const s = cellMorphMesh({ originX: o[0], originZ: o[2], size, quads: 32, heightAt: (x, z) => 40 * valueNoise2(x, z, 300, seed), skirtDepth: 0.5 });
155
+ return {
156
+ cell,
157
+ domainVersion: 1,
158
+ bounds: { min: [0, s.minY, 0], max: [size, s.maxY, size] },
159
+ meshes: [{ material: 'terrain', mesh: s.mesh }],
160
+ instances: [],
161
+ shapeHash: shapeHash(shape),
162
+ error: s.error,
163
+ };
164
+ }
165
+
166
+ // Vertex shader of the material named 'terrain' (attribute locations: CELL_MORPH_ATTRIBS).
167
+ export const TERRAIN_VS = `#include <header>
168
+ uniform vec3 u_cellOffset;
169
+ ${CELL_MORPH_GLSL}
170
+ in vec3 a_pos;
171
+ in vec4 a_normal;
172
+ in vec4 a_color;
173
+ in float a_coarseShift;
174
+ in vec4 a_coarseNormal;
175
+ in vec4 a_coarseColor;
176
+ out vec3 v_world;
177
+ out vec3 v_normal;
178
+ out vec4 v_color;
179
+ void main() {
180
+ vec3 p = a_pos + u_cellOffset;
181
+ float m = cellMorph(p);
182
+ p += u_morphUp * (a_coarseShift * m);
183
+ v_world = p;
184
+ v_normal = mix(a_normal.xyz, a_coarseNormal.xyz, m);
185
+ v_color = mix(a_color, a_coarseColor, m);
186
+ gl_Position = u_viewProj * vec4(p, 1.0);
187
+ }`;
188
+ ```
189
+
190
+ `colorAt` of a blended cell must give a vertex the same colour at every level (from the position and height, not from the normal of that level). Instances can follow the surface the same way: give each instance the shift of its base point as one more instance attribute and add `u_morphUp * (shift * cellMorph(base))`; the endless example does (`PROP_MORPH_LAYOUT`). An instance that the coarser level does not hold can grow with the same factor instead of appearing at once: the example gives it a size of 0 on the coarser level and scales by `mix(1.0, size, cellMorph(base))`.
191
+
192
+ `HeightField.coarseSurface(cols, rows, values, n)` is the building block: the surface a grid thinned to every n-th vertex would draw, evaluated at every vertex of the full grid.
193
+
194
+ The endless example switches both options on with `#lod=smooth`. The golden test of the examples checks the seams between levels ("streaming seams between levels") and the cover ("streaming coverage by screen-space error").
195
+
196
+ ## `StreamedWorld`
197
+
198
+ `StreamedWorld` runs the manager, uploads cells within a time budget and draws them. It is a `Layer`.
199
+
200
+ <!-- check: wrap -->
201
+ ```ts
202
+ import { FACE_FLAT, FlatWorld } from 'wallhammer-web/gen-core';
203
+ import type { CellContent, CellId } from 'wallhammer-web/gen-core';
204
+ import type { Material, Renderer } from 'wallhammer-web/render';
205
+ import { DEFAULT_STREAMING, GeneratorCellProvider } from 'wallhammer-web/world';
206
+ import { StreamedWorld, viewTickets } from 'wallhammer-web/runtime';
207
+ declare const renderer: Renderer;
208
+ declare const terrain: Material;
209
+ declare function generateCell(seed: number, cell: CellId): CellContent;
210
+
211
+ const world = new StreamedWorld({
212
+ renderer,
213
+ config: { ...DEFAULT_STREAMING, shape: new FlatWorld(), face: FACE_FLAT },
214
+ provider: new GeneratorCellProvider(7, generateCell),
215
+ materials: { terrain }, // names used by CellContent.meshes and archetypes
216
+ onActivity: () => {
217
+ // request another frame here (engine.invalidate())
218
+ },
219
+ // morph: true - blend between levels, see "Blending between levels"
220
+ });
221
+ renderer.add(world);
222
+
223
+ // Every frame, before rendering: where the viewer is, in world metres (double precision).
224
+ const eye: [number, number, number] = [0, 300, 0];
225
+ world.setFocus([eye[0], 0, eye[2]]);
226
+ world.setEye(eye);
227
+ world.setTickets(viewTickets(eye, 300, [0, -1]));
228
+ ```
229
+
230
+ Render space is shifted: the render origin snaps to a grid (`originGridM`, default 1,024 m) near the focus. Convert with `toRender` and `toWorld`. Shaders of streamed materials read `u_cellOffset` (cell origin minus render origin, vec3) and may read `u_cellLevel`.
231
+
232
+ **Origin on all axes.** By default the origin follows the focus on x and z only and its height stays 0. That is exact enough near height 0, but a 32-bit float 400 km up has steps of 3 cm, and the image shakes. `originAxes: 'all'` makes the origin follow the height of the focus too:
233
+
234
+ <!-- check: wrap -->
235
+ ```ts
236
+ import type { FreeRig } from 'wallhammer-web/camera';
237
+ import type { StreamedWorld } from 'wallhammer-web/runtime';
238
+ declare const world: StreamedWorld; // created with originAxes: 'all'
239
+ declare const rig: FreeRig;
240
+
241
+ // Every frame: the focus is the eye itself, height included; the rig then works relative to the same origin.
242
+ world.setFocus(rig.position);
243
+ rig.origin = [world.origin[0], world.origin[1], world.origin[2]];
244
+ ```
245
+
246
+ Cell origins and the eye stay doubles on the CPU; only their difference to the origin reaches the GPU. With `'all'`, `world.origin[1]` is no longer 0: heights handed to anything that works in render space (a view target, the fog layer, the cloud height of the sky) need it subtracted. Layers of your own do the same as the streamed world: keep the position in doubles and hand the GPU `toRenderSpace(position, world.origin)` (module `base`); `snapRenderOrigin` is the grid rule itself, for a renderer without a streamed world (set `renderer.worldOrigin` to the same origin, so shadow texels stay fixed to the world).
247
+
248
+ Budgets: `uploadMsPerFrame` (default 3), `blockingMsPerFrame` for blocking providers (default 6). `stats()` reports counts and timings.
249
+
250
+ ## A sphere world
251
+
252
+ `SphereWorld` (module `world`) is a second `WorldShape`: a sphere of a radius you choose, made of a cube whose six faces are each a quadtree. Nothing uses it unless you create it; a flat world is not touched.
253
+
254
+ - **Cells.** `face` of a cell id is the face of the cube: 0 +x, 1 −x, 2 +y, 3 −y, 4 +z, 5 −z. Level 0 is a whole face, a quarter of the way round along its middle (`edgeM(0)`); every level halves it. The grid of a face is spaced evenly in angle (`cubeWarp`), so cells of one level differ in area by a factor of 1.41 at most.
255
+ - **Neighbours.** `neighbours(cell)` crosses the edges of the cube. A cell has eight neighbours, seven at a corner of the cube; a whole face has four.
256
+ - **Points.** Positions are metres from the sphere's centre, in doubles. `cellAt`, `distanceM` (along the surface, 0 inside the cell) and `cellsNear` look only at the direction of a point, so its height does not matter. `center(cell)` is the middle of the cell on the base sphere and is also the cell origin; cell data are relative to it with the world's axes.
257
+ - **Up.** `upAt(p)` points away from the centre. `noiseDomain(p)` is the point of the base sphere under `p`: sample `valueNoise3` / `fractalNoise3` there and the content has no seam and no pole.
258
+ - **Shape hash.** `hashKey` holds the radius and the centre, so cell files of another sphere are refused.
259
+
260
+ **Cells of a sphere.** `spherePatchMesh` (module `gen-core`) builds the surface of one cell: a grid of `quads × quads` on the face, every vertex at the base radius plus `heightAt(x, y, z)` of its point of the base sphere. Heights and colours must be functions of that point alone. Then neighbours agree on their shared border, across the edges of the cube as well, and the mesh carries the shape of the cell one level coarser (`a_coarseShift` along the vertex's own up, `a_coarseNormal`, `a_coarseColor`) and a skirt, like the cell morph mesh of the flat world. `spherePatchRadius` tells where a direction meets the triangles of a level (or of the level above it): stand instances there, with the difference as their own shift.
261
+
262
+ <!-- check: wrap -->
263
+ ```ts
264
+ import type { CellContent, CellId } from 'wallhammer-web/gen-core';
265
+ import { fractalNoise3, shapeHash, spherePatchMesh } from 'wallhammer-web/gen-core';
266
+ import { SphereWorld } from 'wallhammer-web/world';
267
+
268
+ const shape = new SphereWorld(100_000); // radius in metres; an optional second argument is the centre
269
+ const QUADS = 32;
270
+
271
+ function generateCell(seed: number, cell: CellId): CellContent {
272
+ const patch = spherePatchMesh({
273
+ radiusM: shape.radiusM,
274
+ face: cell.face,
275
+ level: cell.level,
276
+ x: cell.x,
277
+ y: cell.y,
278
+ quads: QUADS,
279
+ // A function of the point on the base sphere; never negative here, so the surface never dips under the sphere.
280
+ heightAt: (x, y, z) => 3000 * fractalNoise3(x, y, z, { cellM: 20_000, octaves: 5 }, seed),
281
+ skirtDepth: shape.edgeM(cell.level) * 0.004,
282
+ });
283
+ return { cell, domainVersion: 1, bounds: patch.bounds, meshes: [{ material: 'terrain', mesh: patch.mesh }], instances: [], shapeHash: shapeHash(shape), error: patch.error };
284
+ }
285
+ ```
286
+
287
+ **Streaming it.** The manager needs no `face` (all six are streamed) and `rootRange: Infinity`, so every face is always wanted and the far side stays covered by its coarsest cells. Use selection by screen-space error: the error of a cell includes the bulge of the sphere, so a view from far away settles on a few coarse cells by itself.
288
+
289
+ <!-- check: wrap -->
290
+ ```ts
291
+ import { definePalette } from 'wallhammer-web';
292
+ import type { MaterialDesc } from 'wallhammer-web/base';
293
+ import { FreeRig } from 'wallhammer-web/camera';
294
+ import type { CellContent, CellId } from 'wallhammer-web/gen-core';
295
+ import { bindFreeInput } from 'wallhammer-web/platform';
296
+ import { StreamedWorld, createEngine, viewerTickets } from 'wallhammer-web/runtime';
297
+ import { DEFAULT_STREAMING, GeneratorCellProvider, SphereWorld, pixelsPerRadian } from 'wallhammer-web/world';
298
+ declare const canvas: HTMLCanvasElement;
299
+ declare const TERRAIN: MaterialDesc; // a material that uses SPHERE_PATCH_GLSL, see below
300
+ declare function generateCell(seed: number, cell: CellId): CellContent;
301
+ declare function heightAt(x: number, y: number, z: number): number; // the generator's height function
302
+
303
+ const shape = new SphereWorld(100_000);
304
+ const QUADS = 32;
305
+ const ROOT_LEVEL = 0;
306
+ const MIN_HEIGHT_M = 0; // the lowest height the generator gives
307
+
308
+ // The camera: up from the shape, height above the surface from the generator's own function.
309
+ const start = shape.atHeight([1, 0.6, 0.3], 180_000); // 180 km above the surface, on the line from the centre through a point
310
+ const rig = new FreeRig(
311
+ { fovYDeg: 50, minClearance: 2, maxSpeed: 40_000 },
312
+ {
313
+ shape,
314
+ heightAbove: (p) => {
315
+ const b = shape.noiseDomain(p);
316
+ return shape.altitude(p) - heightAt(b[0], b[1], b[2]);
317
+ },
318
+ },
319
+ { position: [start[0], start[1], start[2]], pitchDeg: 89 },
320
+ );
321
+ const engine = createEngine({
322
+ canvas,
323
+ view: rig,
324
+ palette: definePalette({ sky: '#05070c' }),
325
+ background: [0.02, 0.027, 0.047],
326
+ // A depth mode that reaches from a metre to the far side, and up that points away from the centre.
327
+ renderer: { depth: 'reversed', radialUp: shape.radial },
328
+ environment: { mode: 'day', hour: 13 },
329
+ });
330
+ const world = new StreamedWorld({
331
+ renderer: engine.renderer,
332
+ config: {
333
+ ...DEFAULT_STREAMING,
334
+ shape, // no `face`
335
+ rootLevel: ROOT_LEVEL,
336
+ leafLevel: 11,
337
+ rootRange: Infinity,
338
+ prefetch: 0.2,
339
+ hysteresis: 0.3,
340
+ screenError: { errorPerEdge: 1 / (8 * QUADS), minErrorPerEdge: 1 / (32 * QUADS), maxErrorPx: 2, maxCells: 900, pixelsPerRadian: 1158 },
341
+ },
342
+ provider: new GeneratorCellProvider(7, generateCell),
343
+ originAxes: 'all', // the render origin follows the camera on three axes
344
+ morph: true, // blend between levels
345
+ // Cells behind the sphere's own horizon are not drawn. The hiding sphere must lie under everything drawn.
346
+ horizon: { center: shape.centerM, radiusM: shape.radiusM + MIN_HEIGHT_M - 2 * shape.facetDropM(ROOT_LEVEL, QUADS) },
347
+ materials: { terrain: engine.renderer.material(TERRAIN) },
348
+ onActivity: () => engine.invalidate(),
349
+ });
350
+ engine.add(world);
351
+
352
+ const input = bindFreeInput(engine.canvas, rig, { onChange: () => engine.invalidate() });
353
+ engine.renderer.beforeFrame.unshift(() => {
354
+ input.step();
355
+ const eye: [number, number, number] = [rig.position[0], rig.position[1], rig.position[2]];
356
+ world.setFocus(eye);
357
+ rig.origin = [world.origin[0], world.origin[1], world.origin[2]];
358
+ world.setEye(eye);
359
+ world.setTickets(viewerTickets({ eye, altitude: rig.clearance, forward: rig.axes().forward, velocity: rig.velocity, pixelsPerRadian: pixelsPerRadian(engine.canvas.clientHeight, (50 * Math.PI) / 180) }));
360
+ });
361
+ ```
362
+
363
+ **Shaders.** A renderer made with `radialUp` defines `WH_LOCAL_UP` and gives every shader `localUp(p)`, `localHeight(p)` and `localFrame(p)` (see [Local up](rendering.md#local-up)). The vertex shader of the surface pastes `SPHERE_PATCH_GLSL` after `#include <header>` and blends with the distance measured along the sphere:
364
+
365
+ <!-- check: skip -->
366
+ ```ts
367
+ // vertex shader
368
+ vec3 p = a_pos + u_cellOffset;
369
+ float m = spherePatchMorph(p); // 0 own shape, 1 the parent's
370
+ p += localUp(p) * (a_coarseShift * m);
371
+ v_normal = mix(a_normal.xyz, a_coarseNormal.xyz, m); // world axes
372
+ // an upright instance: its axes are the local frame of its base point
373
+ vec3 world = base + localFrame(base) * (a_pos * scale);
374
+ // fragment shader: the sky light of the place
375
+ vec3 lit = albedo * lightOnAt(v_world, n, sunVisibility(v_world, n, 1.2), 1.0);
376
+ ```
377
+
378
+ **Horizon culling.** `StreamedWorldOptions.horizon` (off by default) names the centre and the radius of a sphere that hides what lies behind it. A cell is skipped in the view pass when even its highest point, at its nearest distance, is below the horizon of that sphere as seen from the eye: `horizonHidden(eye, radius, nearest, farthest radius)`. The test is on the safe side: it never hides what a straight line of sight reaches. The radius must lie under everything that is drawn: under the lowest height of the content and under the flat triangles of the coarsest cells, which dip inside the sphere between their vertices by up to `facetDropM(level, quads)`. `stats().horizonCulled` counts the cells skipped in the last frame. The shadow pass is not culled by the horizon.
379
+
380
+ The page `sphere.html` of the endless example is a sphere of radius 100 km built this way (`examples/endless/src/sphere-world.ts`, `sphere-shaders.ts`, `sphere-main.ts`). The golden test of the examples checks the shape ("world sphere shape"), the seams ("gen-core sphere patch seams"), the cells, the horizon test and the cover of all six faces on a descent from 300 km to 30 m. The example `examples/planet` adds the atmosphere and a scripted flight from the surface to orbit and back ([The planet example](planet.md)).
381
+
382
+ Limits of the sphere shape:
383
+
384
+ - Positions inside a cell are 32-bit floats relative to the middle of the cell. A whole face of a 100 km sphere has steps of 8 mm; a face of a sphere of 6,400 km has steps of half a metre, which is fine from the distance such a cell is drawn at. Leaf cells are exact to micrometres.
385
+ - Blending assumes one viewer, as on the flat world. The skirt covers what remains.
386
+ - The shadow map, its modes `'snapped'` and `'cascades'` and the light horizon assume a flat ground along y. On a sphere use the default mode with a `shadowDistanceM` of a few kilometres; far from the +y side of the sphere the fit of the light is looser.
387
+ - The environment has one sun direction for the whole world and computes it for a site with up along +y. Sky light and direct light fade where the local up turns away from the sun, but dawn colours do not follow the place. The `sky` include and the sky layer assume up along +y. The atmosphere (off by default) lifts these for a sphere: a sky from the ground to orbit, light computed per place, and `Environment.observer` for the sun by the eye's place; see [The atmosphere](rendering.md#the-atmosphere).
388
+
389
+ ## Content beyond its levels
390
+
391
+ Objects (instances) exist only in the finest levels of cells. Farther away the surface itself has to look the way they did, or an area covered with them changes colour and loses its outline where they stop. The engine gives the generic parts and does not know what the objects are:
392
+
393
+ - **A baked cover per vertex.** `SpherePatchOptions.coverAt(x, y, z, height)` (off by default) returns RGBA bytes for a surface point: rgb what the content standing there looks like from afar, a the share of the surface it hides (its density). The content function decides both; use the same rule that places the objects, as an expected value, and a function of the point alone so every level agrees. The mesh then has `SPHERE_PATCH_COVER_LAYOUT`: the plain attributes plus `a_cover` and `a_coarseCover` (the cover on the level one coarser, for the blend), at the locations of `SPHERE_PATCH_COVER_ATTRIBS`. Without `coverAt` the bytes of a patch are what they were.
394
+ - **The fade.** `coverFade(objectLevel, cellLevel, morph)` (core, also as `COVER_FADE_GLSL`) is the share of the far look for a cell: 0 in cells finer than `objectLevel` (the coarsest level whose cells hold the objects), 1 in coarser ones, and the cell's own blend factor on `objectLevel` itself. So the change is spread over the band in which that level blends into its parent (needs `morph: true`; `u_cellLevel` is set per cell by `StreamedWorld`), and it meets both neighbouring levels without a step.
395
+ - **The objects leave one by one.** `coverKeep(fade, order)` is the size of one object at that share, for a number `order` in 0–1 fixed per object (a hash, or any attribute spread evenly): about `1 − fade` of the objects remain, each shrinking over a tenth of the band. Use it in the colour and in the shadow program.
396
+
397
+ <!-- check: wrap -->
398
+ ```ts
399
+ import { spherePatchMesh } from 'wallhammer-web/gen-core';
400
+ import type { SpherePatchOptions } from 'wallhammer-web/gen-core';
401
+
402
+ declare const patch: SpherePatchOptions; // the cell, heightAt, colorAt, skirtDepth
403
+ declare const density: (x: number, y: number, z: number, height: number) => number; // 0–1, the rule of the content
404
+
405
+ const { mesh } = spherePatchMesh({
406
+ ...patch,
407
+ // rgb: the mean colour of the objects; a: the share of the surface they hide.
408
+ coverAt: (x, y, z, h) => [52, 84, 40, Math.round(255 * density(x, y, z, h))],
409
+ });
410
+ // mesh.layout is SPHERE_PATCH_COVER_LAYOUT; the material lists SPHERE_PATCH_COVER_ATTRIBS.
411
+ ```
412
+
413
+ <!-- check: skip -->
414
+ ```ts
415
+ // surface, vertex shader (after SPHERE_PATCH_GLSL and COVER_FADE_GLSL)
416
+ float m = spherePatchMorph(p);
417
+ v_cover = mix(a_cover, a_coarseCover, m);
418
+ v_cover.a *= coverFade(u_coverLevel, u_cellLevel, m);
419
+ // surface, fragment shader
420
+ albedo = mix(albedo, v_cover.rgb, v_cover.a);
421
+ // objects, vertex shader of the colour and the shadow program
422
+ float fade = coverFade(u_coverLevel, u_cellLevel, spherePatchMorph(base));
423
+ vec3 world = base + axes * (a_pos * scale * coverKeep(fade, order));
424
+ ```
425
+
426
+ `u_coverLevel` is the content's own uniform (set it through `StreamedWorld.uniforms`). Return the colour of the objects from `coverAt` also where the share is 0, so the colour does not darken toward the border of a covered area. The sphere page of the endless example does all of this with `#cover=1` (`surfaceCover` in `sphere-world.ts`, the cover materials in `sphere-shaders.ts`). Limits: the cover is a property of the sphere patch only (the flat `cellMorphMesh` has no such attribute), one cover per vertex stands for all content of the cell, and its share does not follow the angle of view.
427
+
428
+ - **Four more bytes per vertex.** `SpherePatchOptions.extraAt(x, y, z, height)` (off by default) returns four bytes the content gives a meaning, for example the skyline code of `horizonCodeAt` ([The plan of a sphere](generators.md#gen-plan-the-plan-of-a-sphere)) so the surface shader knows where a far light is hidden. The mesh then has `SPHERE_PATCH_EXTRA_LAYOUT` (or `SPHERE_PATCH_COVER_EXTRA_LAYOUT` with `coverAt` too): `a_extra` and `a_coarseExtra` (thinned to the level one coarser like the colour, for the blend) after the other attributes, at the locations of `SPHERE_PATCH_EXTRA_ATTRIBS` or `SPHERE_PATCH_COVER_EXTRA_ATTRIBS`. Blend them in the vertex shader with the same factor as the height. Make the bytes a function of the point alone, so a vertex on the border of two cells and of two levels gets the same bytes from both. Without `extraAt` the bytes of a patch are what they were.
429
+
430
+ Narrow, long content (a strip along a broken line) is a second mesh of the cells it passes, at every level, rather than colour in the surface: at a vertex spacing of metres a baked colour blurs and vanishes from afar. The cell generator cuts and fills its ground with `stripCarve`, adds the mesh of `stripMesh` under its own material name, and merges its bounds into the cell's; a cell that `stripTouches` rejects stays as it was apart from its domain version. The strip blends between levels with the surface's blend factor and its vertex shader keeps it a least number of pixels wide, so it stays a thin unbroken line on far levels with no second kind of geometry. Nothing in the runtime changes: a cell already carries several meshes by material name. See [Strips along a surface](generators.md#strips-along-a-surface).
431
+
432
+ ## Packed meshes
433
+
434
+ A cell's meshes can be stored compactly: positions as 16-bit steps from the cell's corner instead of three floats, and loose triangles as indexed ones. `packMesh` (module `gen-mesh`) does both for any mesh whose layout has `a_pos` as three floats; everything else in a vertex is copied byte for byte.
435
+
436
+ - Horizontally a cell edge has 16,384 steps (`PACK_STEPS_PER_EDGE`), so a level 8 cell of the flat world (256 m) resolves 1.6 cm and a position may lie up to one edge outside the cell on either side.
437
+ - Vertically the step and the height of step 0 are the same for the whole world (`stepY`, `heightOrigin`); with 1/64 m the range is 512 m either side of the origin.
438
+ - A mesh without indices is indexed: equal packed vertices are stored once, in the order of their first use. With `spans` (ascending vertex boundaries) vertices are merged only inside a span. Each span is then one run of vertices, and the same span packed alone gives exactly the bytes it has inside the whole mesh, so one object can be overwritten in a cell's vertex buffer without touching the rest.
439
+ - A mesh with indices keeps its vertices and their order. Indices are 16-bit when there are at most 65,536 vertices.
440
+
441
+ `packedMaterial(desc)` returns the material for such meshes. Every vertex shader of `desc` must contain the line `in vec3 a_pos;`. It is replaced by the packed attribute and a function that unpacks it, and `a_pos` becomes that function's value, so the rest of the shader is unchanged. A `'depth'` pass becomes a depth program that unpacks too. The unpacking reads `u_pack` (`packUniform`) and the per-cell `u_cellLevel` and `u_cellOffset` that `StreamedWorld` sets. A shader that declares `u_cellOffset` itself is taken to add it itself: its `a_pos` then stays relative to the cell.
442
+
443
+ <!-- check: wrap -->
444
+ ```ts
445
+ import type { MaterialDesc, MeshData } from 'wallhammer-web/base';
446
+ import { FlatWorld } from 'wallhammer-web/gen-core';
447
+ import type { CellId } from 'wallhammer-web/gen-core';
448
+ import { packFrame, packMesh, packUniform, packedMaterial } from 'wallhammer-web/gen-mesh';
449
+
450
+ declare const shape: FlatWorld;
451
+ declare const cell: CellId;
452
+ declare const mesh: MeshData; // positions in world metres, `a_pos` as three floats
453
+ declare const desc: MaterialDesc; // its vertex shader has the line `in vec3 a_pos;`
454
+ const STEP_Y = 1 / 64;
455
+ const HEIGHT_ORIGIN = 300;
456
+
457
+ // In the generator: positions become steps from the cell's corner.
458
+ const packed = packMesh(mesh, packFrame(shape.edgeM(cell.level), shape.origin(cell), HEIGHT_ORIGIN, STEP_Y));
459
+ // On the page: the same material reading the packed position, and the uniform it needs.
460
+ const material = packedMaterial(desc);
461
+ const uniforms = { u_pack: packUniform(shape.rootEdgeM, STEP_Y, HEIGHT_ORIGIN) };
462
+ ```
463
+
464
+ `packed.clamped` counts positions that lay outside the 16-bit range and were moved to its border; it should be 0.
465
+
466
+ ### A surface within a tolerance
467
+
468
+ `bisectSurface` (module `gen-mesh`) turns a square grid of heights into a packed mesh with as few triangles as an error tolerance allows. The square is two right triangles, and a triangle is cut in two at the middle of its long edge while the grid differs from it by more than `toleranceM` anywhere inside. Flat ground ends up as a few large triangles; broken ground keeps the full grid. A cell of each level samples the ground at its own spacing, so the levels are the densities of the surface.
469
+
470
+ - `heights` holds `(quads + 3)²` samples with one extra sample all round, used for normals only, so cells that share an edge agree on the normals there.
471
+ - Neighbouring cells may be cut differently along their shared edge. Every outer edge gets a skirt `skirtM` deep that hides the gap.
472
+ - `cuts` marks sides (low x, high x, low z, high z) as a cut through the ground, for the border of a world that ends: the strip then reaches down to the given height and carries the cut kind.
473
+ - `clip` cuts the square off at a rectangle, for a cell that the world only partly covers.
474
+
475
+ <!-- check: wrap -->
476
+ ```ts
477
+ import { bisectSurface } from 'wallhammer-web/gen-mesh';
478
+
479
+ declare const heightAt: (x: number, z: number) => number;
480
+ const quads = 64;
481
+ const edgeM = 512;
482
+ const wide = quads + 3;
483
+ const heights = new Float32Array(wide * wide);
484
+ for (let j = 0; j < wide; j++) {
485
+ for (let i = 0; i < wide; i++) heights[j * wide + i] = heightAt(((i - 1) * edgeM) / quads, ((j - 1) * edgeM) / quads);
486
+ }
487
+ const surface = bisectSurface(heights, { quads, edgeM, toleranceM: 0.5, stepY: 1 / 64, heightOrigin: 300, skirtM: 8 });
488
+ // surface.mesh has the layout BISECT_SURFACE_LAYOUT; surface.triangles of surface.gridTriangles were kept.
489
+ ```
490
+
491
+ The mesh is drawn by any material of a height field mesh passed through `packedMaterial` (the attributes are the packed position and the normal with a kind).
492
+
493
+ ## A cache in the browser's storage
494
+
495
+ `CachedCellProvider` (module `world`) stands in front of another provider and keeps every finished cell as bytes of the cell format. A cell asked for a second time, in this visit or a later one, is decoded from the store instead of being built. The store is a port (`CellStore`: `get` and `put`); in a browser it is `openByteStore` of `platform`, which keeps byte arrays in IndexedDB.
496
+
497
+ The third argument is a version: a text that names everything the cells depend on (a fingerprint of the data, the generator's version, the world seed). It is the prefix of every key, so cells made from other data are never read, and `keepOnly(prefix)` deletes what older versions left behind.
498
+
499
+ <!-- check: wrap -->
500
+ ```ts
501
+ import { openByteStore } from 'wallhammer-web/platform';
502
+ import { CachedCellProvider } from 'wallhammer-web/world';
503
+ import type { CellProvider, CellStore } from 'wallhammer-web/world';
504
+
505
+ declare const inner: CellProvider;
506
+ // The store opens in the background; until then (and where the browser has no storage) cells are simply built.
507
+ const opened = openByteStore('my-world-cells');
508
+ const store: CellStore = {
509
+ get: async (key) => (await opened)?.get(key) ?? null,
510
+ put: async (key, bytes) => {
511
+ await (await opened)?.put(key, bytes);
512
+ },
513
+ };
514
+ const provider = new CachedCellProvider(inner, store, 'data-2026-11.generator-3');
515
+ void opened.then((s) => s?.keepOnly(provider.prefix));
516
+ ```
517
+
518
+ `provider.stats` counts hits, misses, broken entries and bytes. Writes are not awaited, and nothing in the store can reject: a full or missing store only means that a cell is built again.
519
+
520
+ ## Edits and refresh
521
+
522
+ Content that changes after it was generated (damage, say) is kept outside the cells and handed to the generator as edits: opaque text per cell, whose form the content decides. The cell is then a pure function of (seed, cell, edits), so it comes back the same after it left, and a reload with the same edits gives the same bytes.
523
+
524
+ - An `EditableCellGenerator` is `(seed, cell, edits?) => CellContent`. With no edits or `''` it must give the same bytes as the call without them. A plain `CellGenerator` takes no edits; the two are separate types so a generator whose own optional third argument means something else stays a plain one.
525
+ - `GeneratorCellProvider(seed, gen, edits)` and `WorkerCellProvider(url, seed, size, edits)` take a `CellEdits` source, `(cell) => string`, read when a request starts. A non-empty text goes to the generator as its third argument; with `''` the call is exactly `gen(seed, cell)`. `serveCellGenerator` in the worker passes it on.
526
+ - `StreamingManager.refresh(cells)` marks cells whose content is out of date and returns how many tracked cells it touched. A job in flight is cancelled (its late result is stale) and requested again. A MESHED cell is forgotten (listed in the next step's `evictions`). A RESIDENT cell stays drawn with its old content; the next step requests it ahead of every other candidate, and when its new content arrives `complete` leaves it RESIDENT. The execution part then swaps the GPU data and calls `swapped(cell, gpuBytes)`, so the cell never leaves the picture. A refreshing cell that stops being wanted is simply forgotten.
527
+ - `refreshes()` gives the cells still waiting for new content (`pending`) and all cells refresh touched (`total`). `settled` waits for the pending ones.
528
+ - `StreamedWorld.refresh(cells)` does all of it on the GPU side: swap, `onResident` with the new content, shadows drawn again. `busy` stays true while a refresh is pending.
529
+
530
+ Without a call to `refresh` the manager takes exactly the decisions it took before; the golden test of the engine ("streaming refresh") checks that and the cases above. `FileCellProvider` and `CachedCellProvider` know nothing of edits: a cache keeps the cells as first built, so keep edited cells out of it (or put the edits in its version).
531
+
532
+ <!-- check: wrap -->
533
+ ```ts
534
+ import type { CellContent, CellId } from 'wallhammer-web/gen-core';
535
+ import type { StreamedWorld } from 'wallhammer-web/runtime';
536
+ import { GeneratorCellProvider } from 'wallhammer-web/world';
537
+
538
+ declare function generate(seed: number, cell: CellId, edits?: string): CellContent;
539
+ declare function editsOf(cell: CellId): string; // e.g. CellStates.text(cell) of sim/destruction
540
+ declare const world: StreamedWorld; // streams from `provider`
541
+ declare const changed: CellId[]; // the cells that draw what changed
542
+ const provider = new GeneratorCellProvider(7, generate, editsOf);
543
+ world.refresh(changed);
544
+ const { pending, total } = world.manager.refreshes();
545
+ ```
546
+
547
+ ## A ceiling of GPU memory
548
+
549
+ `memoryBudgetBytes` bounds what the streamed cells hold on the CPU and the GPU together, and forgets cells that are no longer wanted. A ceiling of GPU memory is a second, separate limit that also counts what is not a cell. It is off by default.
550
+
551
+ - `StreamedWorldOptions.gpuCeilingBytes` switches it on. Before every step the layer reads `Device.memory().total`, subtracts the cells' own bytes and gives the rest to the manager as `gpuReserveBytes`, so the ceiling holds for everything the page has on the GPU.
552
+ - Over the ceiling the manager takes cells off the GPU: first cells kept only by hysteresis, the one wanted longest ago first; then wanted cells from the least urgent. Their CPU data stays, so they come back without a new job.
553
+ - Cells kept only by hysteresis also leave when the waiting uploads would not fit beside them, so a cell nobody wants never holds a wanted one back.
554
+ - An upload that would not fit waits, and its parent stays drawn in its place.
555
+ - Cells of the coarsest level are exempt both ways: the cover of last resort is never dropped, so the ceiling cannot make a hole. Their size is the floor of what the ceiling can reach.
556
+
557
+ <!-- check: wrap -->
558
+ ```ts
559
+ import type { StreamedWorld } from 'wallhammer-web/runtime';
560
+
561
+ declare const world: StreamedWorld; // created with gpuCeilingBytes: 512 * 1024 * 1024
562
+ const { released, deferred } = world.manager.gpuPressure();
563
+ const held = world.renderer.device.memory().total;
564
+ ```
565
+
566
+ The manager alone takes the same limit as `StreamingConfig.gpuBudgetBytes`. The golden test of the engine ("streaming GPU ceiling") pans for 18 km under a ceiling and checks the bytes after every step.
567
+
568
+ `StreamedWorld` also takes textures and uniforms per material name (`textures`, `materialUniforms`; both stay reachable as fields and can be changed at any time) and reports cells that reach or leave the GPU (`onResident`, `onReleased`), for code that writes into a cell's buffers. Materials of one streamed layer are drawn in the order of their names without the draw state being reset between them, so give every material of a layer that mixes states its full state.
569
+
570
+ ## Baking cells to files
571
+
572
+ The endless example can bake cells and verify them. Both run inside the `dev` container:
573
+
574
+ ```sh
575
+ docker compose exec -T dev sh -c 'cd /app/examples/endless && pnpm bake'
576
+ docker compose exec -T dev sh -c 'cd /app/examples/endless && pnpm verify'
577
+ ```
578
+
579
+ `bake` writes into `examples/endless/public/cells/`. Open the example with `#src=files` to read them.
580
+
581
+ ## Known weaknesses
582
+
583
+ From the project's status notes:
584
+
585
+ - Clouds, fog and sky shift slightly when the render origin is rebased. With `originAxes: 'all'` this also happens on a change of height, and the environment still takes its heights (fog layer, cloud deck) in render space.
586
+ - Without `morph`, level-of-detail changes are visible as jumps. With it, the surface and instances that carry a shift blend; instances still appear at once at the level that first holds them unless their material scales them by the blend (see [Blending between levels](#blending-between-levels)).
587
+ - When the budget of cells changes the detail, all blend ranges change by one step (16 %) in the same frame.
588
+ - The blend is measured from one viewer. Cells split only because of another ticket (a predicted point far ahead) meet their coarser neighbours with a small step that the skirt covers.
589
+ - The render origin of `StreamedWorld` follows the focus in x and z only, unless it is created with `originAxes: 'all'`.
590
+ - Two world shapes exist: the flat one and `SphereWorld` (see [A sphere world](#a-sphere-world) for its limits).