tosijs-3d 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -6,6 +6,61 @@ All notable changes to **tosijs-3d**. This project is pre-1.0 (`0.x`), so minor
 versions may carry breaking peer-dependency changes — each is called out in a
 **⚠️ Breaking** block in its version section below, with what a consumer must do.
 
+## 0.8.2
+
+### Added
+
+- **The encoded sky** — `starfield-codec` + `skybox-baker`. A starfield is data,
+  not a picture: six small RGBA faces carry sub-texel position, gamma brightness
+  and a spectral A-byte, decoded in the sky shader into points that stay points
+  at any zoom. The shipped pair (256 smooth + 1024 data) renders a 100k-star
+  galaxy at 25 MiB of VRAM and 0.4 MB on disk, against the 2.3 MB / 96 MiB
+  raster it replaces. The A-byte spends precision where the eye is: faint stars
+  are warm yellow, bright stars carry a 224-step spectral ramp, galaxy discs
+  their size.
+- **`png.ts`** — a lossless PNG encoder — and with it the package's first
+  runtime dependency: **`fflate` (`^0.8.3`)** supplies the deflate, because
+  Chrome's `CompressionStream` output is rejected by Chrome's own PNG decoder
+  and the packed fields must survive byte-exact. The packed fields must survive
+  byte-exact, and both the canvas path (premultiplied backing store) and
+  Chrome's `CompressionStream` deflate destroy them; the encoder writes the
+  bytes directly and a test round-trips through real inflate.
+- **Distant dim stars** (`distantStars`, default 3000) — isotropic points
+  outside the disc, so the off-band sky has texture instead of blankness.
+- **`b3d-cloud-deck`** — the cloud DECK: a tiled field shader with one
+  coverage dial driving transmission, gloom and depth; orographic clouds that
+  ask the terrain for its own height sampler; a shared cloud shadow.
+- **The `world-sim` page** — the kitchen sink: live-dialed terrain (sea level
+  as a fraction of v-size), weather, and the encoded sky, under Demos.
+- **`spectralGlsl`/`spectralRamp`/`spectralValue`** and the `generatePlanets`
+  galaxy option — the colour follows the class, and planets (71% of galaxy
+  generation time) are computed on demand via `generateStarSystem`.
+
+### Changed
+
+- **Galaxy generation is ~70× faster** — names derive from each star's own
+  seed via a cheap PRNG (no collision retries, no name table), planets are
+  on-demand, and the core nebulae are a fixed budget rather than a fraction.
+- **The sky is one rigid frame** — the dome's rotation carries the gradient,
+  the sun, the moon and the stars together; the star fade dies by gamma at the
+  first hint of daylight, and the golden hour has two stops (amber, then a
+  pink-red at the horizon crossing) feeding the deck's fringe and the fog
+  through the light's colour.
+- **The baker downloads ONE zip** — twelve separate downloads got silently
+  dropped by the browser mid-burst.
+
+### Fixed
+
+- The biome classifier's sea level and lapse rate are LIVE dials — they
+  move the snow line without re-cutting the tile pool (the shader reads the
+  plugin params every bind; the old spelling regenerated the world for a
+  value the shader never saw).
+- The cloud-deck shadow survived field re-bakes (the shadow's sampler was
+  left pointing at a disposed texture).
+- The cloud-deck's core glow no longer blows out at high star counts.
+- The sky shader compiles under the strictest decoders — floats in the
+  generated GLSL now LOOK like floats.
+
 ## 0.8.1
 
 ### ⚠️ Breaking

package/README.md

@@ -6,12 +6,56 @@
   <img style="width: 280px; height: 280px;" alt="tosijs-3d logo" src="https://3d.tosijs.net/favicon.svg">
 </div>
 
-**Looking for a capability?** Search the **[attribute
-index](https://3d.tosijs.net/attributes.txt)** before assuming it does not
-exist — one greppable line per attribute, generated from source on every
-build. There is a [JSON form](https://3d.tosijs.net/attributes.json) for
-tools, and both ship **inside the package** — an agent already in a consumer
-project reads `node_modules/tosijs-3d/static/attributes.txt` with no network.
+**tosijs-3d is a library for building 3D web apps** — and standalone apps, if
+that is what you want. Under the hood it uses Babylon.js for rendering, glTF/GLB
+for models and the usual bitmap formats for textures — but it also leans on
+**SVG**, for textures and for the entire user interface.
+
+Free and open source, and light for what it is (Babylon is not small; this
+adds little to it). Scenes are composed from **web components**, so a world is
+markup you can read:
+
+```javascript
+b3d(
+  b3dSun({ shadowCascading: true }),
+  b3dSkybox({ timeOfDay: 6 }),
+  b3dLoader({ url: './scene.glb' }),
+  b3dWater({ y: -0.2 })
+)
+```
+
+See the [b3d](?tosi-b3d.ts) page for that running, and every page here carries a
+live demo you can edit in place.
+
+## Four things you may not have seen in a 3D library
+
+**Flat 3D and VR are the same app.** You can enter and leave an immersive
+session without the simulation resetting — the scene, the physics and your
+place in the world all survive the transition, because nothing is torn down to
+make it.
+
+**One user interface, in three places.** The SVG-powered widget set renders
+identically as a DOM overlay, on a plane inside a 3D scene, and in VR. Not three
+implementations that drift — one, with three presentations, where any divergence
+is treated as a bug.
+
+**One control system, every input.** Keyboard and mouse, gamepads, VR
+controllers and touch all arrive as the same `ControlInput`. You write the
+behaviour once; supporting a new device is a new provider, not a rewrite.
+
+**The simulation is testable without a GPU.** The flight model, the combat
+maths, the world state and the layout engine are deliberately Babylon-free,
+deterministic, and unit-tested — so the interesting logic can be exercised in
+milliseconds rather than in a browser.
+
+## Finding things
+
+**Search the [attribute index](https://3d.tosijs.net/attributes.txt)** before
+assuming a capability does not exist — one greppable line per attribute,
+generated from source on every build. There is a [JSON
+form](https://3d.tosijs.net/attributes.json) for tools, and both ship **inside
+the package**, so an agent already in a consumer project reads
+`node_modules/tosijs-3d/static/attributes.txt` with no network.
 
 It exists because the recurring adopter failure is not a missing feature, it is
 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
 what to do about them, and [CHANGELOG.md](./CHANGELOG.md) for the full detail.
 Both ship inside the package, so they work from `node_modules` too.
 
-Declarative 3D/XR framework built on Babylon.js and tosijs. Compose 3D scenes with web components.
-See the [b3d](?tosi-b3d.ts) page for a live interactive demo.
-
 ```javascript
 import {
   b3d,

package/dist/aim.d.ts

@@ -0,0 +1,157 @@
+/** A plain direction. Babylon's `Vector3` satisfies it structurally. */
+export interface AimVec {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Yaw and pitch in degrees — yaw RELATIVE to the body, pitch absolute. */
+export interface Aim {
+    /** Twist from the body's facing. Positive is to the character's right. */
+    yawDeg: number;
+    /** Positive is DOWN, matching `swim-aim` and `RotationYawPitchRoll`. */
+    pitchDeg: number;
+}
+export interface AimLimits {
+    /** Twist held with the feet planted. Beyond it, the body starts to come round. */
+    yawFree: number;
+    /** The spine's limit. The body is dragged rather than letting this be exceeded. */
+    yawMax: number;
+    /** How far up the character can aim (a positive magnitude). */
+    pitchUp: number;
+    /** How far down (a positive magnitude). Usually larger — looking down is easier. */
+    pitchDown: number;
+}
+/**
+ * Human-ish defaults, and each one is a posture rather than a round number.
+ *
+ * 45° is about what you can twist without moving your feet; 90° is a hard
+ * shoulder check. Down beats up because looking down is mostly the neck while
+ * looking up fights the spine — and because the thing you are aiming at is more
+ * often below you than above.
+ */
+export declare const DEFAULT_AIM_LIMITS: AimLimits;
+/**
+ * Wrap to (−180, 180].
+ *
+ * Everything that subtracts two yaws needs this, and forgetting it produces the
+ * single most recognisable aim bug: a character that turns 350° to the left
+ * instead of 10° to the right. Exported because callers holding a body yaw need
+ * the same operation.
+ */
+export declare function wrapDeg(deg: number): number;
+/** Hold an aim inside what a body can do. Yaw is clamped at the HARD limit. */
+export declare function clampAim2(aim: Aim, limits?: AimLimits): Aim;
+/**
+ * The aim that points a body at a world direction.
+ *
+ * This is the join between "where should I shoot" and "what can my body do".
+ * `dir` need not be normalised — only its proportions matter — and a zero
+ * vector returns a level, forward aim rather than `NaN`, because a degenerate
+ * direction is a thing that happens (a target at the muzzle) and a character
+ * frozen at `NaN` is unrecoverable.
+ */
+export declare function aimToward(bodyYawDeg: number, dir: AimVec, limits?: AimLimits): Aim;
+/** The world direction an aim points, given the body's facing. */
+export declare function aimDirection(bodyYawDeg: number, aim: Aim): AimVec;
+export interface AimStep {
+    /** Degrees per second the aim may move. The skill dial — see the module doc. */
+    slewDeg?: number;
+    limits?: AimLimits;
+}
+/**
+ * Move an aim toward a target, at a limited RATE.
+ *
+ * A rate limit rather than an ease, and the difference matters more than it
+ * looks. An ease closes a fraction of the gap per second, so it never quite
+ * arrives and its lag depends on how far away the target was — which makes a
+ * shooter's accuracy a function of the target's distance from where he was
+ * already looking, in a way nobody can tune. A slew arrives in a knowable time
+ * and its lag is a speed you can put in a table.
+ *
+ * Yaw takes the SHORT way round. Pitch cannot wrap, so it does not need to.
+ */
+export declare function stepAim(current: Aim, target: Aim, dt: number, options?: AimStep): Aim;
+export interface BodyCatchUp {
+    /** Degrees the BODY should turn this frame. Positive is to its right. */
+    bodyTurnDeg: number;
+    /** The twist that remains once it has. Feed this back as the stored aim. */
+    yawDeg: number;
+}
+/**
+ * How far the body comes round to face what the character is aiming at.
+ *
+ * Returns BOTH halves because they are one decision. A caller that turned the
+ * body and then re-derived the twist separately would have two sources for one
+ * number, and they would disagree on the frame the clamp fires — which is
+ * exactly the frame you would be looking at.
+ *
+ * Three regimes, no state:
+ *
+ * | twist | what happens |
+ * | --- | --- |
+ * | under `yawFree` | nothing. Feet planted, shoulders turned. |
+ * | `yawFree`..`yawMax` | the body turns at `rateDeg`, unwinding the excess |
+ * | over `yawMax` | the body is DRAGGED — at least enough to restore the limit |
+ *
+ * The third is a floor on the turn rather than a separate mode, so a stick
+ * yanked to the side produces a fast turn rather than a broken neck, and it
+ * blends back into the second regime as soon as the excess is gone.
+ */
+export declare function bodyCatchUp(yawDeg: number, dt: number, rateDeg?: number, limits?: AimLimits): BodyCatchUp;
+/**
+ * Unwind an aim toward neutral when nobody is driving it.
+ *
+ * Holstering, going idle, or simply letting go should return the character to
+ * facing where it walks — and it should do so on the same clock as everything
+ * else, so it is the same slew rather than a tween. `swim-aim`'s `aimTarget`
+ * makes the same argument for pitch: one branch here rather than an `if` at
+ * every call site.
+ */
+export declare function relaxAim(current: Aim, dt: number, slewDeg?: number, limits?: AimLimits): Aim;
+/** Weights for a three-pose aim set, summing to 1. */
+export interface AimPoseWeights {
+    up: number;
+    level: number;
+    down: number;
+}
+/**
+ * Turn a pitch into weights over an **aim-up / aim-level / aim-down** clip set.
+ *
+ * This is the shape [[animation-layers]] can actually play. Babylon has no
+ * additive layer, so "point the gun 30° down" is not a bone rotation you can
+ * add — it is a blend between poses somebody authored, and a blend is weights.
+ * Two of the three are always zero, which is not a waste: it means a caller can
+ * hand the same three numbers to three groups every frame and never branch.
+ *
+ * Falls back to pure `level` when a limit is zero, rather than dividing by it.
+ */
+export declare function aimPoseWeights(pitchDeg: number, limits?: AimLimits): AimPoseWeights;
+/**
+ * How much authority the aim layer should have, `0`..`1`.
+ *
+ * An aim that matches where the body already points needs no layer at all — the
+ * locomotion is already doing it, and overriding it with a "forward" aim pose
+ * costs you the walk's arm swing for no gain. Authority rises with the twist,
+ * so the layer fades in exactly as it starts to say something the base clip
+ * does not.
+ *
+ * Multiply it into the mask's weights, which is why this returns a scalar and
+ * not a mask: [[bone-mask]] owns WHICH bones, this owns HOW MUCH.
+ */
+export declare function aimAuthority(aim: Aim, limits?: AimLimits): number;
+/**
+ * A deterministic wander, for a shooter who cannot hold still.
+ *
+ * `AI-DESIGN.md`: invest in the LOW end of the skill dial. A bad shot does not
+ * miss by rolling badly at the moment of firing — that is invisible, and it
+ * reads as the game cheating. A bad shot's aim visibly *drifts*, so you can
+ * watch it wander off you and back, and shooting the instant it wanders is a
+ * skill the player can acquire.
+ *
+ * Two frequencies at an irrational-ish ratio rather than one, because a single
+ * sine reads as a machine sweeping. No RNG: it is a function of time, so a
+ * replay of the same fight produces the same misses, which is the rule the
+ * whole `world-store` is built on.
+ */
+export declare function aimWobble(seconds: number, amplitudeDeg: number, hz?: number, phase?: number): Aim;
+//# sourceMappingURL=aim.d.ts.map

package/dist/aim.d.ts.map

@@ -0,0 +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"}