tosijs-3d 0.8.1 → 0.8.3

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 (231) hide show
  1. package/CHANGELOG.md +169 -0
  2. package/README.md +50 -9
  3. package/dist/aim.d.ts +157 -0
  4. package/dist/aim.d.ts.map +1 -0
  5. package/dist/aim.js +399 -0
  6. package/dist/aim.js.map +1 -0
  7. package/dist/animation-layers.d.ts +44 -0
  8. package/dist/animation-layers.d.ts.map +1 -0
  9. package/dist/animation-layers.js +273 -0
  10. package/dist/animation-layers.js.map +1 -0
  11. package/dist/asset-url.d.ts +27 -1
  12. package/dist/asset-url.d.ts.map +1 -1
  13. package/dist/asset-url.js +29 -2
  14. package/dist/asset-url.js.map +1 -1
  15. package/dist/atmosphere.d.ts +15 -0
  16. package/dist/atmosphere.d.ts.map +1 -1
  17. package/dist/atmosphere.js.map +1 -1
  18. package/dist/b3d-aircraft.d.ts +28 -0
  19. package/dist/b3d-aircraft.d.ts.map +1 -1
  20. package/dist/b3d-aircraft.js +91 -1
  21. package/dist/b3d-aircraft.js.map +1 -1
  22. package/dist/b3d-biped.d.ts +273 -1
  23. package/dist/b3d-biped.d.ts.map +1 -1
  24. package/dist/b3d-biped.js +1090 -25
  25. package/dist/b3d-biped.js.map +1 -1
  26. package/dist/b3d-cloud-deck.d.ts +538 -0
  27. package/dist/b3d-cloud-deck.d.ts.map +1 -0
  28. package/dist/b3d-cloud-deck.js +2206 -0
  29. package/dist/b3d-cloud-deck.js.map +1 -0
  30. package/dist/b3d-clouds.d.ts +2 -0
  31. package/dist/b3d-clouds.d.ts.map +1 -1
  32. package/dist/b3d-clouds.js +36 -4
  33. package/dist/b3d-clouds.js.map +1 -1
  34. package/dist/b3d-crowd.d.ts +399 -0
  35. package/dist/b3d-crowd.d.ts.map +1 -0
  36. package/dist/b3d-crowd.js +2264 -0
  37. package/dist/b3d-crowd.js.map +1 -0
  38. package/dist/b3d-elevator.d.ts +70 -0
  39. package/dist/b3d-elevator.d.ts.map +1 -0
  40. package/dist/b3d-elevator.js +243 -0
  41. package/dist/b3d-elevator.js.map +1 -0
  42. package/dist/b3d-exploder.d.ts.map +1 -1
  43. package/dist/b3d-exploder.js +4 -9
  44. package/dist/b3d-exploder.js.map +1 -1
  45. package/dist/b3d-fog.js +1 -1
  46. package/dist/b3d-fog.js.map +1 -1
  47. package/dist/b3d-galaxy.d.ts +89 -10
  48. package/dist/b3d-galaxy.d.ts.map +1 -1
  49. package/dist/b3d-galaxy.js +503 -150
  50. package/dist/b3d-galaxy.js.map +1 -1
  51. package/dist/b3d-input-focus.d.ts.map +1 -1
  52. package/dist/b3d-input-focus.js +50 -6
  53. package/dist/b3d-input-focus.js.map +1 -1
  54. package/dist/b3d-interactive.d.ts.map +1 -1
  55. package/dist/b3d-interactive.js +27 -3
  56. package/dist/b3d-interactive.js.map +1 -1
  57. package/dist/b3d-launcher.d.ts +127 -0
  58. package/dist/b3d-launcher.d.ts.map +1 -1
  59. package/dist/b3d-launcher.js +526 -6
  60. package/dist/b3d-launcher.js.map +1 -1
  61. package/dist/b3d-light.d.ts +1 -0
  62. package/dist/b3d-light.d.ts.map +1 -1
  63. package/dist/b3d-light.js +11 -0
  64. package/dist/b3d-light.js.map +1 -1
  65. package/dist/b3d-manipulator.d.ts +16 -0
  66. package/dist/b3d-manipulator.d.ts.map +1 -1
  67. package/dist/b3d-manipulator.js +93 -7
  68. package/dist/b3d-manipulator.js.map +1 -1
  69. package/dist/b3d-physics.d.ts.map +1 -1
  70. package/dist/b3d-physics.js +4 -9
  71. package/dist/b3d-physics.js.map +1 -1
  72. package/dist/b3d-primitives.d.ts +66 -0
  73. package/dist/b3d-primitives.d.ts.map +1 -1
  74. package/dist/b3d-primitives.js +179 -9
  75. package/dist/b3d-primitives.js.map +1 -1
  76. package/dist/b3d-shadows.d.ts.map +1 -1
  77. package/dist/b3d-shadows.js +20 -1
  78. package/dist/b3d-shadows.js.map +1 -1
  79. package/dist/b3d-skybox.d.ts +173 -0
  80. package/dist/b3d-skybox.d.ts.map +1 -1
  81. package/dist/b3d-skybox.js +1575 -28
  82. package/dist/b3d-skybox.js.map +1 -1
  83. package/dist/b3d-sound.d.ts.map +1 -1
  84. package/dist/b3d-sound.js +5 -7
  85. package/dist/b3d-sound.js.map +1 -1
  86. package/dist/b3d-star-system.d.ts.map +1 -1
  87. package/dist/b3d-star-system.js +5 -2
  88. package/dist/b3d-star-system.js.map +1 -1
  89. package/dist/b3d-terrain.d.ts +21 -0
  90. package/dist/b3d-terrain.d.ts.map +1 -1
  91. package/dist/b3d-terrain.js +195 -23
  92. package/dist/b3d-terrain.js.map +1 -1
  93. package/dist/b3d-trigger.d.ts.map +1 -1
  94. package/dist/b3d-trigger.js +8 -1
  95. package/dist/b3d-trigger.js.map +1 -1
  96. package/dist/b3d-utils.d.ts +77 -0
  97. package/dist/b3d-utils.d.ts.map +1 -1
  98. package/dist/b3d-utils.js +164 -4
  99. package/dist/b3d-utils.js.map +1 -1
  100. package/dist/biome-plugin.d.ts.map +1 -1
  101. package/dist/biome-plugin.js +5 -1
  102. package/dist/biome-plugin.js.map +1 -1
  103. package/dist/bone-mask.d.ts +96 -0
  104. package/dist/bone-mask.d.ts.map +1 -0
  105. package/dist/bone-mask.js +207 -0
  106. package/dist/bone-mask.js.map +1 -0
  107. package/dist/box.d.ts.map +1 -1
  108. package/dist/box.js +11 -3
  109. package/dist/box.js.map +1 -1
  110. package/dist/camera-fit.d.ts +119 -0
  111. package/dist/camera-fit.d.ts.map +1 -0
  112. package/dist/camera-fit.js +154 -0
  113. package/dist/camera-fit.js.map +1 -0
  114. package/dist/cloud-field.d.ts +41 -0
  115. package/dist/cloud-field.d.ts.map +1 -0
  116. package/dist/cloud-field.js +236 -0
  117. package/dist/cloud-field.js.map +1 -0
  118. package/dist/cloud-shadows.d.ts +13 -0
  119. package/dist/cloud-shadows.d.ts.map +1 -1
  120. package/dist/cloud-shadows.js +32 -2
  121. package/dist/cloud-shadows.js.map +1 -1
  122. package/dist/control-input.d.ts +9 -0
  123. package/dist/control-input.d.ts.map +1 -1
  124. package/dist/control-input.js +3 -0
  125. package/dist/control-input.js.map +1 -1
  126. package/dist/galaxy-data.d.ts +59 -2
  127. package/dist/galaxy-data.d.ts.map +1 -1
  128. package/dist/galaxy-data.js +229 -24
  129. package/dist/galaxy-data.js.map +1 -1
  130. package/dist/game-controller.d.ts +51 -0
  131. package/dist/game-controller.d.ts.map +1 -1
  132. package/dist/game-controller.js +195 -4
  133. package/dist/game-controller.js.map +1 -1
  134. package/dist/icon-grid.d.ts.map +1 -1
  135. package/dist/icon-grid.js +12 -2
  136. package/dist/icon-grid.js.map +1 -1
  137. package/dist/index.d.ts +19 -3
  138. package/dist/index.d.ts.map +1 -1
  139. package/dist/index.js +28 -2
  140. package/dist/index.js.map +1 -1
  141. package/dist/interactive-behavior.d.ts +14 -0
  142. package/dist/interactive-behavior.d.ts.map +1 -1
  143. package/dist/interactive-behavior.js +23 -1
  144. package/dist/interactive-behavior.js.map +1 -1
  145. package/dist/land-and-sky.d.ts +2 -0
  146. package/dist/land-and-sky.d.ts.map +1 -0
  147. package/dist/land-and-sky.js +238 -0
  148. package/dist/land-and-sky.js.map +1 -0
  149. package/dist/landform.d.ts +77 -7
  150. package/dist/landform.d.ts.map +1 -1
  151. package/dist/landform.js +186 -16
  152. package/dist/landform.js.map +1 -1
  153. package/dist/mersenne-twister.d.ts +32 -2
  154. package/dist/mersenne-twister.d.ts.map +1 -1
  155. package/dist/mersenne-twister.js +56 -2
  156. package/dist/mersenne-twister.js.map +1 -1
  157. package/dist/model-transform.d.ts +10 -0
  158. package/dist/model-transform.d.ts.map +1 -1
  159. package/dist/model-transform.js +8 -1
  160. package/dist/model-transform.js.map +1 -1
  161. package/dist/perf-probe.d.ts +6 -0
  162. package/dist/perf-probe.d.ts.map +1 -1
  163. package/dist/perf-probe.js +3 -0
  164. package/dist/perf-probe.js.map +1 -1
  165. package/dist/playground.d.ts +18 -0
  166. package/dist/playground.d.ts.map +1 -0
  167. package/dist/playground.js +525 -0
  168. package/dist/playground.js.map +1 -0
  169. package/dist/png.d.ts +12 -0
  170. package/dist/png.d.ts.map +1 -0
  171. package/dist/png.js +105 -0
  172. package/dist/png.js.map +1 -0
  173. package/dist/rocket-ascent.d.ts +20 -0
  174. package/dist/rocket-ascent.d.ts.map +1 -0
  175. package/dist/rocket-ascent.js +410 -0
  176. package/dist/rocket-ascent.js.map +1 -0
  177. package/dist/scene-schemas.d.ts.map +1 -1
  178. package/dist/scene-schemas.js +32 -1
  179. package/dist/scene-schemas.js.map +1 -1
  180. package/dist/skybox-baker.d.ts +249 -0
  181. package/dist/skybox-baker.d.ts.map +1 -0
  182. package/dist/skybox-baker.js +582 -0
  183. package/dist/skybox-baker.js.map +1 -0
  184. package/dist/starfield-codec.d.ts +162 -0
  185. package/dist/starfield-codec.d.ts.map +1 -0
  186. package/dist/starfield-codec.js +554 -0
  187. package/dist/starfield-codec.js.map +1 -0
  188. package/dist/surface.d.ts.map +1 -1
  189. package/dist/surface.js +6 -2
  190. package/dist/surface.js.map +1 -1
  191. package/dist/surroundings-probe.d.ts +69 -0
  192. package/dist/surroundings-probe.d.ts.map +1 -0
  193. package/dist/surroundings-probe.js +164 -0
  194. package/dist/surroundings-probe.js.map +1 -0
  195. package/dist/surroundings.d.ts +162 -0
  196. package/dist/surroundings.d.ts.map +1 -0
  197. package/dist/surroundings.js +508 -0
  198. package/dist/surroundings.js.map +1 -0
  199. package/dist/tosi-b3d.d.ts +100 -0
  200. package/dist/tosi-b3d.d.ts.map +1 -1
  201. package/dist/tosi-b3d.js +321 -33
  202. package/dist/tosi-b3d.js.map +1 -1
  203. package/dist/vector-field.d.ts.map +1 -1
  204. package/dist/vector-field.js +6 -2
  205. package/dist/vector-field.js.map +1 -1
  206. package/dist/vertex-animation.d.ts +126 -0
  207. package/dist/vertex-animation.d.ts.map +1 -0
  208. package/dist/vertex-animation.js +215 -0
  209. package/dist/vertex-animation.js.map +1 -0
  210. package/dist/virtual-gamepad.d.ts +5 -1
  211. package/dist/virtual-gamepad.d.ts.map +1 -1
  212. package/dist/virtual-gamepad.js +64 -9
  213. package/dist/virtual-gamepad.js.map +1 -1
  214. package/dist/weapon-fit.d.ts +2 -0
  215. package/dist/weapon-fit.d.ts.map +1 -0
  216. package/dist/weapon-fit.js +212 -0
  217. package/dist/weapon-fit.js.map +1 -0
  218. package/dist/widget-box.d.ts.map +1 -1
  219. package/dist/widget-box.js +5 -1
  220. package/dist/widget-box.js.map +1 -1
  221. package/dist/widgets3d-layout.d.ts +24 -0
  222. package/dist/widgets3d-layout.d.ts.map +1 -1
  223. package/dist/widgets3d-layout.js +47 -0
  224. package/dist/widgets3d-layout.js.map +1 -1
  225. package/dist/widgets3d.d.ts +31 -0
  226. package/dist/widgets3d.d.ts.map +1 -1
  227. package/dist/widgets3d.js +295 -56
  228. package/dist/widgets3d.js.map +1 -1
  229. package/package.json +4 -1
  230. package/static/attributes.json +513 -3
  231. package/static/attributes.txt +121 -2
package/CHANGELOG.md CHANGED
@@ -6,6 +6,175 @@ All notable changes to **tosijs-3d**. This project is pre-1.0 (`0.x`), so minor
6
6
  versions may carry breaking peer-dependency changes — each is called out in a
7
7
  **⚠️ Breaking** block in its version section below, with what a consumer must do.
8
8
 
9
+ ## 0.8.3
10
+
11
+ **A galaxy that costs nothing per frame, a sky that keeps the right time, and
12
+ clouds that light like clouds.** Galaxy billboarding moved into the vertex
13
+ shader (3.19 ms → ~0.02 ms of CPU per render). The sun now runs a northern arc,
14
+ ignores `starfieldTilt`, and a skybox without a sun still knows it is night.
15
+ The cloud deck's silver lining finally faces the sun, and fair-weather cloud
16
+ is white from below and outshines the sky at its thinnest. The kitchen-sink
17
+ demo is now **Land and Sky**.
18
+
19
+ > **Visible, not breaking:** scenes tuned by eye will look different. The sun
20
+ > crosses the SOUTH at noon (it crossed the north), the tilt no longer lifts or
21
+ > drops it, the moon rides the night arc, cloud undersides are brighter and
22
+ > their rims glow toward the sun rather than away from it, and a volcano grows
23
+ > a basalt apron. No component API was removed, but two paths moved: the
24
+ > kitchen-sink demo module `tosijs-3d/world-sim` is now `tosijs-3d/land-and-sky`
25
+ > (a side-effect-only demo, not a library entry point), and the unused 2048
26
+ > reference sky (`/sky/default_*.png`) is no longer served — it lives in
27
+ > `reference/sky/` in the repo.
28
+
29
+ ### Added
30
+
31
+ - **`galaxy.pickStar(x, y)`** — the star under a screen point, or `-1`: the
32
+ nearest star whose DRAWN disc the ray crosses (the old triangle pick also
33
+ hit a quad's invisible corners), else the nearest within 3 px, so a
34
+ one-pixel star is clickable. `getStarPoints()` — every point in the star
35
+ mesh, for bakers.
36
+ - **`SHIPPED_SKY`** — the recipe for `static/sky` (seed, 100k stars, 42% out,
37
+ 1 off-plane, roll 0, 256 + 1024, and the `12,25,58` tilt it is framed for),
38
+ plus a "use shipped recipe" button in the baker demo. It used to live only
39
+ in commit messages.
40
+ - **Live terrain climate:** `biomeTemperature`, `biomeMoisture` and
41
+ `biomeVolcanicScale` attributes (−1 = the plugin's default), synced like
42
+ `biomeSeaLevel`. The moisture default (0.45) is steppe — a green world
43
+ wants ~0.7. And `terrain.generationKey`, which changes whenever the
44
+ terrain's shape does.
45
+
46
+ ### Changed
47
+
48
+ - **`b3d-galaxy` billboards in the vertex shader.** Stars and nebulae are
49
+ static quads the shader turns to face the viewpoint; the per-frame
50
+ `setParticles()` that rewrote every vertex whether or not anything moved is
51
+ gone. Measured on the baker's 10k-star galaxy: **3.19 ms → ~0.02 ms of CPU
52
+ per render**, and it no longer scales with star count. A sky baked through
53
+ it is byte-identical in the data cube and differs by 1/255 in 3 of 393,216
54
+ smooth-cube pixels (GPU float32 vs CPU float64 at a triangle edge). Quads
55
+ face the camera's POSITION rather than its view plane — the rule the cube
56
+ bake already used, so there is one mechanism where there were two that
57
+ could stack. `setVisibility()` now genuinely fades.
58
+ - **`cirrus` is signed, `-1…1`.** The magnitude is how wispy; the sign is
59
+ the axis — positive streaks ALONG the wind heading (as before, bit for
60
+ bit), negative ACROSS it.
61
+ - **A volcano goes through basalt before lava.** Its province tail was one
62
+ smooth ramp from 0.5 at the rim, so almost all of it sat on the ladder's
63
+ glowing-seam stage and vegetation met glowing rock directly. It now cools
64
+ gradually over 0.3 R past the rim and holds a cold-basalt apron (~0.15)
65
+ before fading into the biome by 0.75 R; the shader's local volcanic mask is
66
+ fully on by 0.12 (was 0.3), so the apron reads as solid basalt.
67
+ - **Fair-weather cloud is white from below, and outshines the sky at its
68
+ thinnest.** The underside lift peaked at 42% toward white on a clear day; it
69
+ is now ~90% up to coverage 0.5, easing onto the storm curve by full cover
70
+ (following the dial, so an orographic cap does not turn fair weather into a
71
+ slab). Below 0.5 the cloud gains a forward-scatter glow in the sun's HUE —
72
+ golden at golden hour — rising to ~3× as cover falls to 0, mostly spared the
73
+ distance fog. An explicit `transmission` keeps its authority.
74
+ - **The kitchen-sink demo is "Land and Sky"** (`/land-and-sky/`, under
75
+ Demos). Titled `world-sim`, it slugified onto the World Sim category and
76
+ adopted all twelve world-simulation pages as its children; `/world-sim/` is
77
+ the category's landing page again. New defaults (Tonio's): volcano on,
78
+ moisture 0.72 (forest), volcanic scale 0.02 for its 420 m cone (the
79
+ demo's value — the library default stays 0.09, right for ~50 m cones),
80
+ cover 0.10,
81
+ 18:30. A Climate group joins the panel, and the camera turns in place —
82
+ arrows ROTATE (up = look up); it was an orbit camera, so up-arrow nose-dived
83
+ and left/right swung the eye round a 300 m circle.
84
+
85
+ ### Fixed
86
+
87
+ - **The sun ran a southern-hemisphere arc at a northern latitude.** North is
88
+ +Z (every heading is `atan2(x, z)`) and the latitude rotation leaned the arc
89
+ toward +Z. Now it rises east, crosses the south at noon and sets west
90
+ (98° / 180° / 262° at 7:00 / 12:00 / 17:00, latitude 40).
91
+ - **`starfieldTilt` moved the sun.** It orients the galaxy behind the
92
+ atmosphere; noon is latitude and time. With the demos' `12,25,58` the noon
93
+ sun sat ~15° up instead of 50°. The tilt now sits in the celestial frame,
94
+ inside the diurnal turn, so sun, moon and stars still wheel as one, and the
95
+ moon rides the night arc — up at night with or without a tilt.
96
+ - **A skybox with no `<tosi-b3d-sun>` ignored the clock.** The dome's
97
+ day/night writes sat inside the sun-element branch, so without a sun it
98
+ stayed at stock daylight while the star exposure said night — stars through
99
+ a sunlit sky (the beacon demo). Only the light's writes need a light now.
100
+ - **Cloud deck: the silver lining pointed the wrong way.** `sunDir` is the
101
+ light's travel direction and the forward-scatter term read it unnegated, so
102
+ rims blazed with the sun BEHIND the viewer and the clouds in front of a
103
+ sunset were the darkest in the sky.
104
+ - **Cloud deck: `orographic` was not live.** The local-weather field only
105
+ re-sampled when the grid moved, so dragging `orographic` (or reshaping the
106
+ terrain under it) did nothing until the camera travelled a grid step.
107
+ - **Cloud deck: `coverage: 0` is a clear sky.** The orographic boost was added
108
+ on top of the dial, so zero still left cloud on every peak; it now ramps in
109
+ over the first quarter of the dial.
110
+ - **The skybox baker encoded every distant star twice** — once as a
111
+ spectral-less 0.02 "star" (it walked the whole star mesh, whose tail IS the
112
+ distant stars) and once properly. The shipped sky (`static/sky/stars_*`) is
113
+ rebaked without them; the recipe was first proven by reproducing the old
114
+ faces byte-for-byte with the pre-fix code.
115
+
116
+ ### Deprecated
117
+
118
+ - **`getStarSPS()`** returns `null` and warns once — there is no particle
119
+ system. Use `pickStar`. `getDistantStarParticles()` /
120
+ `getDistantGalaxyParticles()` now return `GalaxyPoint`s (the
121
+ `position`/`scaling`/`color` subset of a `SolidParticle` the baker read).
122
+
123
+ ## 0.8.2
124
+
125
+ ### Added
126
+
127
+ - **The encoded sky** — `starfield-codec` + `skybox-baker`. A starfield is data,
128
+ not a picture: six small RGBA faces carry sub-texel position, gamma brightness
129
+ and a spectral A-byte, decoded in the sky shader into points that stay points
130
+ at any zoom. The shipped pair (256 smooth + 1024 data) renders a 100k-star
131
+ galaxy at 25 MiB of VRAM and 0.4 MB on disk, against the 2.3 MB / 96 MiB
132
+ raster it replaces. The A-byte spends precision where the eye is: faint stars
133
+ are warm yellow, bright stars carry a 224-step spectral ramp, galaxy discs
134
+ their size.
135
+ - **`png.ts`** — a lossless PNG encoder — and with it the package's first
136
+ runtime dependency: **`fflate` (`^0.8.3`)** supplies the deflate, because
137
+ Chrome's `CompressionStream` output is rejected by Chrome's own PNG decoder
138
+ and the packed fields must survive byte-exact. The packed fields must survive
139
+ byte-exact, and both the canvas path (premultiplied backing store) and
140
+ Chrome's `CompressionStream` deflate destroy them; the encoder writes the
141
+ bytes directly and a test round-trips through real inflate.
142
+ - **Distant dim stars** (`distantStars`, default 3000) — isotropic points
143
+ outside the disc, so the off-band sky has texture instead of blankness.
144
+ - **`b3d-cloud-deck`** — the cloud DECK: a tiled field shader with one
145
+ coverage dial driving transmission, gloom and depth; orographic clouds that
146
+ ask the terrain for its own height sampler; a shared cloud shadow.
147
+ - **The `world-sim` page** — the kitchen sink: live-dialed terrain (sea level
148
+ as a fraction of v-size), weather, and the encoded sky, under Demos.
149
+ - **`spectralGlsl`/`spectralRamp`/`spectralValue`** and the `generatePlanets`
150
+ galaxy option — the colour follows the class, and planets (71% of galaxy
151
+ generation time) are computed on demand via `generateStarSystem`.
152
+
153
+ ### Changed
154
+
155
+ - **Galaxy generation is ~70× faster** — names derive from each star's own
156
+ seed via a cheap PRNG (no collision retries, no name table), planets are
157
+ on-demand, and the core nebulae are a fixed budget rather than a fraction.
158
+ - **The sky is one rigid frame** — the dome's rotation carries the gradient,
159
+ the sun, the moon and the stars together; the star fade dies by gamma at the
160
+ first hint of daylight, and the golden hour has two stops (amber, then a
161
+ pink-red at the horizon crossing) feeding the deck's fringe and the fog
162
+ through the light's colour.
163
+ - **The baker downloads ONE zip** — twelve separate downloads got silently
164
+ dropped by the browser mid-burst.
165
+
166
+ ### Fixed
167
+
168
+ - The biome classifier's sea level and lapse rate are LIVE dials — they
169
+ move the snow line without re-cutting the tile pool (the shader reads the
170
+ plugin params every bind; the old spelling regenerated the world for a
171
+ value the shader never saw).
172
+ - The cloud-deck shadow survived field re-bakes (the shadow's sampler was
173
+ left pointing at a disposed texture).
174
+ - The cloud-deck's core glow no longer blows out at high star counts.
175
+ - The sky shader compiles under the strictest decoders — floats in the
176
+ generated GLSL now LOOK like floats.
177
+
9
178
  ## 0.8.1
10
179
 
11
180
  ### ⚠️ Breaking
package/README.md CHANGED
@@ -6,12 +6,56 @@
6
6
  <img style="width: 280px; height: 280px;" alt="tosijs-3d logo" src="https://3d.tosijs.net/favicon.svg">
7
7
  </div>
8
8
 
9
- **Looking for a capability?** Search the **[attribute
10
- index](https://3d.tosijs.net/attributes.txt)** before assuming it does not
11
- exist — one greppable line per attribute, generated from source on every
12
- build. There is a [JSON form](https://3d.tosijs.net/attributes.json) for
13
- tools, and both ship **inside the package** — an agent already in a consumer
14
- project reads `node_modules/tosijs-3d/static/attributes.txt` with no network.
9
+ **tosijs-3d is a library for building 3D web apps** — and standalone apps, if
10
+ that is what you want. Under the hood it uses Babylon.js for rendering, glTF/GLB
11
+ for models and the usual bitmap formats for textures — but it also leans on
12
+ **SVG**, for textures and for the entire user interface.
13
+
14
+ Free and open source, and light for what it is (Babylon is not small; this
15
+ adds little to it). Scenes are composed from **web components**, so a world is
16
+ markup you can read:
17
+
18
+ ```javascript
19
+ b3d(
20
+ b3dSun({ shadowCascading: true }),
21
+ b3dSkybox({ timeOfDay: 6 }),
22
+ b3dLoader({ url: './scene.glb' }),
23
+ b3dWater({ y: -0.2 })
24
+ )
25
+ ```
26
+
27
+ See the [b3d](?tosi-b3d.ts) page for that running, and every page here carries a
28
+ live demo you can edit in place.
29
+
30
+ ## Four things you may not have seen in a 3D library
31
+
32
+ **Flat 3D and VR are the same app.** You can enter and leave an immersive
33
+ session without the simulation resetting — the scene, the physics and your
34
+ place in the world all survive the transition, because nothing is torn down to
35
+ make it.
36
+
37
+ **One user interface, in three places.** The SVG-powered widget set renders
38
+ identically as a DOM overlay, on a plane inside a 3D scene, and in VR. Not three
39
+ implementations that drift — one, with three presentations, where any divergence
40
+ is treated as a bug.
41
+
42
+ **One control system, every input.** Keyboard and mouse, gamepads, VR
43
+ controllers and touch all arrive as the same `ControlInput`. You write the
44
+ behaviour once; supporting a new device is a new provider, not a rewrite.
45
+
46
+ **The simulation is testable without a GPU.** The flight model, the combat
47
+ maths, the world state and the layout engine are deliberately Babylon-free,
48
+ deterministic, and unit-tested — so the interesting logic can be exercised in
49
+ milliseconds rather than in a browser.
50
+
51
+ ## Finding things
52
+
53
+ **Search the [attribute index](https://3d.tosijs.net/attributes.txt)** before
54
+ assuming a capability does not exist — one greppable line per attribute,
55
+ generated from source on every build. There is a [JSON
56
+ form](https://3d.tosijs.net/attributes.json) for tools, and both ship **inside
57
+ the package**, so an agent already in a consumer project reads
58
+ `node_modules/tosijs-3d/static/attributes.txt` with no network.
15
59
 
16
60
  It exists because the recurring adopter failure is not a missing feature, it is
17
61
  a feature that ships, is documented, and cannot be found: three issues in one
@@ -22,9 +66,6 @@ week turned out to be capability that was already there. One `grep water` finds
22
66
  what to do about them, and [CHANGELOG.md](./CHANGELOG.md) for the full detail.
23
67
  Both ship inside the package, so they work from `node_modules` too.
24
68
 
25
- Declarative 3D/XR framework built on Babylon.js and tosijs. Compose 3D scenes with web components.
26
- See the [b3d](?tosi-b3d.ts) page for a live interactive demo.
27
-
28
69
  ```javascript
29
70
  import {
30
71
  b3d,
package/dist/aim.d.ts ADDED
@@ -0,0 +1,157 @@
1
+ /** A plain direction. Babylon's `Vector3` satisfies it structurally. */
2
+ export interface AimVec {
3
+ x: number;
4
+ y: number;
5
+ z: number;
6
+ }
7
+ /** Yaw and pitch in degrees — yaw RELATIVE to the body, pitch absolute. */
8
+ export interface Aim {
9
+ /** Twist from the body's facing. Positive is to the character's right. */
10
+ yawDeg: number;
11
+ /** Positive is DOWN, matching `swim-aim` and `RotationYawPitchRoll`. */
12
+ pitchDeg: number;
13
+ }
14
+ export interface AimLimits {
15
+ /** Twist held with the feet planted. Beyond it, the body starts to come round. */
16
+ yawFree: number;
17
+ /** The spine's limit. The body is dragged rather than letting this be exceeded. */
18
+ yawMax: number;
19
+ /** How far up the character can aim (a positive magnitude). */
20
+ pitchUp: number;
21
+ /** How far down (a positive magnitude). Usually larger — looking down is easier. */
22
+ pitchDown: number;
23
+ }
24
+ /**
25
+ * Human-ish defaults, and each one is a posture rather than a round number.
26
+ *
27
+ * 45° is about what you can twist without moving your feet; 90° is a hard
28
+ * shoulder check. Down beats up because looking down is mostly the neck while
29
+ * looking up fights the spine — and because the thing you are aiming at is more
30
+ * often below you than above.
31
+ */
32
+ export declare const DEFAULT_AIM_LIMITS: AimLimits;
33
+ /**
34
+ * Wrap to (−180, 180].
35
+ *
36
+ * Everything that subtracts two yaws needs this, and forgetting it produces the
37
+ * single most recognisable aim bug: a character that turns 350° to the left
38
+ * instead of 10° to the right. Exported because callers holding a body yaw need
39
+ * the same operation.
40
+ */
41
+ export declare function wrapDeg(deg: number): number;
42
+ /** Hold an aim inside what a body can do. Yaw is clamped at the HARD limit. */
43
+ export declare function clampAim2(aim: Aim, limits?: AimLimits): Aim;
44
+ /**
45
+ * The aim that points a body at a world direction.
46
+ *
47
+ * This is the join between "where should I shoot" and "what can my body do".
48
+ * `dir` need not be normalised — only its proportions matter — and a zero
49
+ * vector returns a level, forward aim rather than `NaN`, because a degenerate
50
+ * direction is a thing that happens (a target at the muzzle) and a character
51
+ * frozen at `NaN` is unrecoverable.
52
+ */
53
+ export declare function aimToward(bodyYawDeg: number, dir: AimVec, limits?: AimLimits): Aim;
54
+ /** The world direction an aim points, given the body's facing. */
55
+ export declare function aimDirection(bodyYawDeg: number, aim: Aim): AimVec;
56
+ export interface AimStep {
57
+ /** Degrees per second the aim may move. The skill dial — see the module doc. */
58
+ slewDeg?: number;
59
+ limits?: AimLimits;
60
+ }
61
+ /**
62
+ * Move an aim toward a target, at a limited RATE.
63
+ *
64
+ * A rate limit rather than an ease, and the difference matters more than it
65
+ * looks. An ease closes a fraction of the gap per second, so it never quite
66
+ * arrives and its lag depends on how far away the target was — which makes a
67
+ * shooter's accuracy a function of the target's distance from where he was
68
+ * already looking, in a way nobody can tune. A slew arrives in a knowable time
69
+ * and its lag is a speed you can put in a table.
70
+ *
71
+ * Yaw takes the SHORT way round. Pitch cannot wrap, so it does not need to.
72
+ */
73
+ export declare function stepAim(current: Aim, target: Aim, dt: number, options?: AimStep): Aim;
74
+ export interface BodyCatchUp {
75
+ /** Degrees the BODY should turn this frame. Positive is to its right. */
76
+ bodyTurnDeg: number;
77
+ /** The twist that remains once it has. Feed this back as the stored aim. */
78
+ yawDeg: number;
79
+ }
80
+ /**
81
+ * How far the body comes round to face what the character is aiming at.
82
+ *
83
+ * Returns BOTH halves because they are one decision. A caller that turned the
84
+ * body and then re-derived the twist separately would have two sources for one
85
+ * number, and they would disagree on the frame the clamp fires — which is
86
+ * exactly the frame you would be looking at.
87
+ *
88
+ * Three regimes, no state:
89
+ *
90
+ * | twist | what happens |
91
+ * | --- | --- |
92
+ * | under `yawFree` | nothing. Feet planted, shoulders turned. |
93
+ * | `yawFree`..`yawMax` | the body turns at `rateDeg`, unwinding the excess |
94
+ * | over `yawMax` | the body is DRAGGED — at least enough to restore the limit |
95
+ *
96
+ * The third is a floor on the turn rather than a separate mode, so a stick
97
+ * yanked to the side produces a fast turn rather than a broken neck, and it
98
+ * blends back into the second regime as soon as the excess is gone.
99
+ */
100
+ export declare function bodyCatchUp(yawDeg: number, dt: number, rateDeg?: number, limits?: AimLimits): BodyCatchUp;
101
+ /**
102
+ * Unwind an aim toward neutral when nobody is driving it.
103
+ *
104
+ * Holstering, going idle, or simply letting go should return the character to
105
+ * facing where it walks — and it should do so on the same clock as everything
106
+ * else, so it is the same slew rather than a tween. `swim-aim`'s `aimTarget`
107
+ * makes the same argument for pitch: one branch here rather than an `if` at
108
+ * every call site.
109
+ */
110
+ export declare function relaxAim(current: Aim, dt: number, slewDeg?: number, limits?: AimLimits): Aim;
111
+ /** Weights for a three-pose aim set, summing to 1. */
112
+ export interface AimPoseWeights {
113
+ up: number;
114
+ level: number;
115
+ down: number;
116
+ }
117
+ /**
118
+ * Turn a pitch into weights over an **aim-up / aim-level / aim-down** clip set.
119
+ *
120
+ * This is the shape [[animation-layers]] can actually play. Babylon has no
121
+ * additive layer, so "point the gun 30° down" is not a bone rotation you can
122
+ * add — it is a blend between poses somebody authored, and a blend is weights.
123
+ * Two of the three are always zero, which is not a waste: it means a caller can
124
+ * hand the same three numbers to three groups every frame and never branch.
125
+ *
126
+ * Falls back to pure `level` when a limit is zero, rather than dividing by it.
127
+ */
128
+ export declare function aimPoseWeights(pitchDeg: number, limits?: AimLimits): AimPoseWeights;
129
+ /**
130
+ * How much authority the aim layer should have, `0`..`1`.
131
+ *
132
+ * An aim that matches where the body already points needs no layer at all — the
133
+ * locomotion is already doing it, and overriding it with a "forward" aim pose
134
+ * costs you the walk's arm swing for no gain. Authority rises with the twist,
135
+ * so the layer fades in exactly as it starts to say something the base clip
136
+ * does not.
137
+ *
138
+ * Multiply it into the mask's weights, which is why this returns a scalar and
139
+ * not a mask: [[bone-mask]] owns WHICH bones, this owns HOW MUCH.
140
+ */
141
+ export declare function aimAuthority(aim: Aim, limits?: AimLimits): number;
142
+ /**
143
+ * A deterministic wander, for a shooter who cannot hold still.
144
+ *
145
+ * `AI-DESIGN.md`: invest in the LOW end of the skill dial. A bad shot does not
146
+ * miss by rolling badly at the moment of firing — that is invisible, and it
147
+ * reads as the game cheating. A bad shot's aim visibly *drifts*, so you can
148
+ * watch it wander off you and back, and shooting the instant it wanders is a
149
+ * skill the player can acquire.
150
+ *
151
+ * Two frequencies at an irrational-ish ratio rather than one, because a single
152
+ * sine reads as a machine sweeping. No RNG: it is a function of time, so a
153
+ * replay of the same fight produces the same misses, which is the rule the
154
+ * whole `world-store` is built on.
155
+ */
156
+ export declare function aimWobble(seconds: number, amplitudeDeg: number, hz?: number, phase?: number): Aim;
157
+ //# sourceMappingURL=aim.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"aim.d.ts","sourceRoot":"","sources":["../src/aim.ts"],"names":[],"mappings":"AAgMA,wEAAwE;AACxE,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACV;AAED,2EAA2E;AAC3E,MAAM,WAAW,GAAG;IAClB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAA;IACd,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;IACf,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAA;IACd,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAA;IACf,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAKhC,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK3C;AAOD,+EAA+E;AAC/E,wBAAgB,SAAS,CACvB,GAAG,EAAE,GAAG,EACR,MAAM,GAAE,SAA8B,GACrC,GAAG,CAWL;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,SAA8B,GACrC,GAAG,CASL;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,MAAM,CAKjE;AAED,MAAM,WAAW,OAAO;IACtB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,GAAG,EACZ,MAAM,EAAE,GAAG,EACX,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,OAAY,GACpB,GAAG,CAaL;AAED,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,OAAO,SAAM,EACb,MAAM,GAAE,SAA8B,GACrC,WAAW,CAab;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,GAAG,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,SAAM,EACb,MAAM,GAAE,SAA8B,GACrC,GAAG,CAEL;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,SAA8B,GACrC,cAAc,CAUhB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,GAAG,EACR,MAAM,GAAE,SAA8B,GACrC,MAAM,CAOR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,EAAE,SAAM,EACR,KAAK,SAAI,GACR,GAAG,CAUL"}