@driftengine/core 4.7.3 → 4.8.0

package/CHANGELOG.json

@@ -1,4 +1,71 @@
 [
+  {
+    "version": "4.8.0",
+    "date": "2026-10-03",
+    "entries": [
+      {
+        "kind": "changed",
+        "short": "A drift/* answer that is one of a few things is an enum a script matches on: a contact, a phase of matter, a chemistry event, a tree's or a save's status, the editor's modes, a hand and its joints.",
+        "text": "Twelve enums are declared by the engine for DriftScript 1.15.0's host enums: `TreeStatus`, `MatterPhase`, `ChemistryEvent`, `ContactKind`, `SaveStatus`, `GizmoMode`, `GizmoSpace`, `GizmoHandle`, `EditorMode`, `FieldKind`, `Hand` and `HandJoint`. `behavior.tick`, `step` and `status`, `chemistry.phase` and `eventKind`, `physics.contactKind`, `persistence.saveStatus` and the editor's `gizmoMode`, `space`, `hovered`, `mode` and `fieldKind` answer a variant where they answered a number or a string, and `drift/xr` takes a `Hand` and a `HandJoint` where it took `\"right\"` and `\"index-finger-tip\"`. A script that compared one of these against a number or a string no longer compiles, which is the point: those comparisons were checked by nothing, and a misspelt joint read zero. Each variant list is tested against the engine constants it translates. `contactKind`, `eventKind` and `fieldKind` refuse an index past what exists, where they answered a stale entry or nothing."
+      },
+      {
+        "kind": "fixed",
+        "short": "An optional component field reads and writes as an option from a script, in a query loop and through a handle: a cleared one reads none, and writing one no longer stores NaN.",
+        "text": "**`driftscript` moves to 1.16.0.** A loop read only an optional field's value column and an assignment put the option object into it, which stored `NaN` marked present; through a handle the read answered a bare number. The compiler now reads and writes the presence column beside the value, and `drift/ecs`'s `read` answers `undefined` for an absent optional field where it answered zero, which the compiler turns into `none`. The entities example's frogs keep their target as an `Entity?`, where they kept a flag beside a plain `Entity` because of this."
+      },
+      {
+        "kind": "fixed",
+        "short": "A lockstep session whose player holds a control on the first tick stays in step: the ticks before anyone can publish an input are neutral on every peer, where each peer guessed its own.",
+        "text": "No peer can publish an input for the ticks before its first tick plus the input delay, so every peer guessed them and nothing ever corrected the guess. A guess repeats the newest input the log holds, and for a peer's own participant that was the input it had just submitted for a later tick, which the other peer cannot know. So a key held when the match began split the two worlds, and the first fingerprint halted the session. `LockstepSession` settles those ticks as neutral for every participant on its first `submit`."
+      },
+      {
+        "kind": "fixed",
+        "short": "WebSocketTransport takes a browser WebSocket as it is typed: the socket shape asked for any buffer, which a browser's send does not accept, so the package's own example did not compile.",
+        "text": "`SocketLike.send` and `DataChannelLike.send` take a view of an `ArrayBuffer`, which is what a browser's `WebSocket` and `RTCDataChannel` accept, and both transports copy a message on shared memory off it before sending, since a browser refuses to send one."
+      },
+      {
+        "kind": "added",
+        "short": "runSchedule takes a failure reporter: every system failure, every tick, with the system's name, the tick and the error, where it logged once per system and nothing else could see it.",
+        "text": "`runSchedule(world, schedule, tick, report)`. Without a reporter a failing system is still skipped and logged once per system per world, as before. With one, nothing is logged and the reporter decides: count failures, show them in an overlay, send them to telemetry, or throw to make a failure fatal while developing, which stops the schedule at that system."
+      },
+      {
+        "kind": "changed",
+        "short": "A system's component access follows its calls into other files, so DS0291 stops calling a correct declaration unused and an undeclared write is a compile error, not a refusal at runtime.",
+        "text": "From DriftScript 1.16.0. Access was inferred from a module's own functions, so a helper imported from another file touched nothing as far as a system was concerned: a declaration of what it wrote drew `DS0291`, and leaving it out drew no `DS0288` and left the write out of the metadata the engine builds its schedule from. And from 1.15.0, `==` compares what two values hold, so an enum variant still equals itself after a hot reload; it compared objects by identity, and a rule written `if round.phase != Phase.Playing` returned forever after the first save."
+      },
+      {
+        "kind": "added",
+        "short": "The manual gains a DriftScript section and a networking chapter: what a script is for, setting one up, patterns, everything it can reach, testing, and two peers in one match over a lossy link.",
+        "text": "**DriftScript in a game** says what belongs in a script and what stays in TypeScript, **Setting up scripts** covers the build, binding, services and hot reload, **Patterns** names the shapes the examples share, **What a script can reach** lists every module, function and enum from the capability file, and **Determinism, testing and shipping** covers `@deterministic`, testing a script in Node and what reaches the bundle. The starter and the first game keep their rules in `.drs` files, the starter carries the Vite config and declaration a copied project needs and builds without a warning, and the first game's round is tested in Node. **Networking and rollback** is built on the new netplay example: two peers in one page over an impaired loopback, with the link, the redundancy and the input delay as live switches."
+      }
+    ]
+  },
+  {
+    "version": "4.7.4",
+    "date": "2026-10-02",
+    "entries": [
+      {
+        "kind": "fixed",
+        "short": "A component's declared field values fill every field an entity is not given: an add with some fields, a prefab that leaves one out, a script's instantiate, a save from before the field.",
+        "text": "**`driftscript` moves to 1.14.0**, whose compiler now carries the value each component field was declared with (`seed: u32 = 7`). Before, the value was parsed and dropped, so every entity started at zero and nothing said so. A component type has `defaults`, and `defineComponent(schema, defaults)` refuses one that names no field or does not fit its column. The store fills an omitted field from them, so `world.add` with some of the fields, a prefab that leaves one out and a script's `ecs.instantiate` all start at the declared values; a `null` given for an optional field is still its absence. `deserializeWorld` gives a field the saved scene does not have its declared value, so a save loads across an added field with what the component says. DriftScript 1.14.0 also type-checks a component's defaults, which nothing did before, and refuses one that is computed (DS0275)."
+      },
+      {
+        "kind": "added",
+        "short": "The manual gains XR, and a Systems section that opens with saves and preferences, each chapter built on an example that runs live and keeps its behaviour in DriftScript.",
+        "text": "**XR** covers asking a browser what it can present, entering a session, and reading the head, the controllers and a tracked hand, from TypeScript and from `drift/xr`, through the simulated runtime the package tests against. It says plainly that the renderer cannot draw into a headset yet, and the xr README's sample, which called `renderer.setViewport` and `renderer.draw`, now stops where the renderer does. **Saves and preferences** covers the synchronous store and why it is synchronous, preferences checked field by field, `RemoteSaveStore` over a backend that answers later, `serializeWorld` and `deserializeWorld` with a save read back across an added field, and `drift/persistence`, around a garden bed that saves to a server the page can make slow or take offline."
+      },
+      {
+        "kind": "fixed",
+        "short": "Four examples behave on any machine: the vehicle starts clear of the cones, readouts fit a small frame, chemistry holds 60 fps, and DriftLight starts smoothly on a slow CPU.",
+        "text": "The vehicle spawned overlapping a cone and came to rest on it with two wheels in the air; it starts on the ramp's line. A readout is sized to the frame it is in, so the manual's 768 by 432 frames no longer cut lines off, and it can keep clear of a panel. Chemistry stepped a quarter second sixty times a second and drew 3 fps once smoke filled the air; it steps a sixteenth, about four times the clock, at 60 fps, and `stage.run` takes loop options so a slow frame catches up two ticks at most. DriftLight baked 64 bricks a frame and ran at 1 to 8 fps for its first ten seconds on a CPU three times slower; it bakes for four milliseconds a frame and stays above 18. Under that throttling 44 of the 46 examples hold 57 to 60 fps, and chemistry 16."
+      },
+      {
+        "kind": "changed",
+        "short": "The repository lints without a warning: oxlint's 170 are fixed, one of them a test that divided its fallback where it meant to check a length.",
+        "text": "Unused imports, constants, functions, variables and parameters are gone, products by zero are written as the terms that remain, and optional chains in tests stay optional to the end. Inside the native host, the window, the document and the canvas take their `on<type>` attributes from a base class that declares them, in place of an interface merged into each class, and fdlibm's constants are spelled with the digits a double holds, each parsing to the same value."
+      }
+    ]
+  },
   {
     "version": "4.7.3",
     "date": "2026-10-02",

package/README.md

@@ -36,6 +36,9 @@ import {
   createRenderer,
   startLoop,
 } from '@driftengine/core';
+import { bindModule } from '@driftengine/script';
+import { loadModule, patchModule } from 'driftscript';
+import * as spinScript from './spin.drs';
 
 const canvas = document.querySelector<HTMLCanvasElement>('#stage');
 if (canvas === null) throw new Error('the page must carry <canvas id="stage">');
@@ -94,6 +97,22 @@ camera.position[1] = 4.5;
 camera.position[2] = 8;
 camera.lookAt(0, 1, 0);
 
+/*
+ * How fast the cube turns is a rule, and rules live in DriftScript: `spin.drs`. The bundler compiles
+ * the file, `loadModule` makes a module of it, and `bindModule` gives it the engine capabilities it
+ * imports. Saving the file while the page is open replaces its function in place.
+ */
+const spinModule = loadModule(spinScript as Record<string, unknown>);
+const bound = bindModule(spinModule, {});
+if (!bound.bound) throw new Error(bound.reason);
+const rules = spinModule.exports as unknown as { spinRate(time: number): number };
+
+if (import.meta.hot) {
+  import.meta.hot.accept('./spin.drs', (next) => {
+    if (next !== undefined) patchModule(spinModule, next as Record<string, unknown>);
+  });
+}
+
 /*
  * Two angles, because that is what `alpha` is for. The simulation advances in fixed steps and
  * the display does not, so a frame almost never lands on a step boundary: drawing `spin`
@@ -102,11 +121,13 @@ camera.lookAt(0, 1, 0);
  */
 let spin = 0;
 let previousSpin = 0;
+let time = 0;
 
 startLoop({
   simulate(dt) {
     previousSpin = spin;
-    spin += dt * 0.8;
+    time += dt;
+    spin += dt * rules.spinRate(time);
   },
   render(alpha) {
     spinner.setRotationAxisAngle(0, 1, 0, previousSpin + (spin - previousSpin) * alpha);
@@ -123,6 +144,26 @@ startLoop({
 });
 ```
 
+How fast the cube turns is a rule, so it lives in DriftScript, in `spin.drs` beside the page:
+
+```drs
+// How the cube turns. The page owns the cube; this file only says how fast it goes.
+//
+// Save it while the page is open and the cube takes the new rate without the page reloading. Try a
+// steady 2, a cube that stops every few seconds, or one that turns the other way.
+
+import { sin } from "std/math"
+
+// Radians a second: a steady turn that quickens and eases every few seconds.
+fn spinRate(time: f32) -> f32 {
+    return 0.8 + 0.4 * math.sin(time * 0.5)
+}
+```
+
+The bundler compiles it with DriftScript's Vite plugin, set up as in the starter's `vite.config.ts`;
+[Installation](https://driftengine.dev/docs/start/installation#driftscript) has the two packages and
+the config.
+
 This is the engine's `examples/starter`, and a test keeps the two the same.
 [Hello world](https://driftengine.dev/docs/start/hello-world) walks through it, and
 [Your first game](https://driftengine.dev/docs/start/first-game) builds a complete one.

package/dist/geometry/meshBuilder.js

@@ -812,8 +812,9 @@ export class MeshBuilder {
                 // later one is transported from it, so the choice never shows.
                 const ax = Math.abs(tx) < 0.9 ? 1 : 0;
                 const ay = Math.abs(tx) < 0.9 ? 0 : 1;
-                ux = ay * tz - 0 * ty;
-                uy = 0 * tx - ax * tz;
+                // (ax, ay, 0) x tangent, with the terms the zero removes left out.
+                ux = ay * tz;
+                uy = -ax * tz;
                 uz = ax * ty - ay * tx;
                 seeded = true;
             }

package/dist/math/exact.js

@@ -66,14 +66,14 @@ const HALF_PI = 1.5707963267948966;
 const PI = 3.141592653589793;
 /* fdlibm's `__kernel_sin` coefficients. */
 const S1 = -1.6666666666666632e-1;
-const S2 = 8.3333333333224894e-3;
+const S2 = 8.33333333332249e-3;
 const S3 = -1.984126982985795e-4;
 const S4 = 2.7557313707070068e-6;
 const S5 = -2.5050760253406863e-8;
 const S6 = 1.5896909952115501e-10;
 /* fdlibm's `__kernel_cos` coefficients. */
 const C1 = 4.1666666666666602e-2;
-const C2 = -1.3888888888874109e-3;
+const C2 = -1.388888888887411e-3;
 const C3 = 2.480158728947673e-5;
 const C4 = -2.7557314351390663e-7;
 const C5 = 2.0875723212981748e-9;
@@ -273,7 +273,7 @@ export function exactLog(x) {
         /* |f| < 2^-20: two terms of the series are the whole answer. */
         if (f === 0)
             return k === 0 ? 0 : k * LN2_HI + k * LN2_LO;
-        const r = f * f * (0.5 - 0.33333333333333333 * f);
+        const r = f * f * (0.5 - 0.3333333333333333 * f);
         return k === 0 ? f - r : k * LN2_HI - (r - k * LN2_LO - f);
     }
     const s = f / (2 + f);

package/dist/render/mesh.js

@@ -23,8 +23,6 @@ import { validateMeshData } from '@driftengine/drft';
  * well. Both halves are fixed — `flat.ts` normalises the lobe, and this is the width that
  * actually matches.
  */
-/* The engine's fixed lobe, stated once in `vertexDefaults.ts` so both backends read one number. */
-const DEFAULT_ROUGHNESS = ABSENT_ATTRIBUTE['roughness']?.[0] ?? 0.4277;
 /** Attribute locations are fixed engine-wide (`layout(location = n)` in GLSL). */
 const ATTR_POSITION = 0;
 const ATTR_NORMAL = 1;

package/dist/render/plumeRenderer.js

@@ -3,37 +3,8 @@ import { compileProgram, uniformLocations } from './shader.js';
 import { bindAtmosphere } from './atmosphere.js';
 import { plumeShaders } from './plumeMaterial.js';
 import { buildPlumeGeometry } from './plumeGeometry.js';
-/**
- * Blades in each plume's cross, and the vertices that costs.
- *
- * **Two, crossed at 90°, instead of one card turned to face the viewer.** A single
- * billboard has no three-dimensional structure to see: orbiting a fire showed the
- * identical silhouette from every angle, because every card shared one camera-derived
- * axis and the whole plume swivelled as a sheet. Reported twice: the fire did not read
- * as three-dimensional, it read as something that moved with the camera — and after a
- * first attempt that only *leaned* edge-on cards toward the viewer, it still did,
- * correctly, because leaning still rotates whichever cards are edge-on, so the ensemble
- * still tracks the viewer.
- *
- * A cross cannot track anything: both blades are fixed in world space, so turning
- * around a fire genuinely brings one broadside as the other goes edge-on, which is
- * the parallax a volume has. It also removes the reason billboarding existed — a
- * blade going edge-on no longer vanishes, because its partner is square-on at that
- * exact moment.
- *
- * Two rather than three because the plumes blend additively and are drawn in
- * quantity: the third blade costs 50% more geometry for a difference the eye does not
- * separate at the sizes these are drawn.
- */
-const BLADES = 2;
 /* The shared count, so both backends step a plume's vertices the same way. */
 const VERTS_PER_PLUME = PLUME_VERTS;
-const CORNERS = [
-    [-1, -1],
-    [1, -1],
-    [1, 1],
-    [-1, 1],
-];
 export class PlumeRenderer {
     program;
     uniforms;

package/dist/scene/node.js

@@ -122,7 +122,7 @@ export class SceneNode {
     attachChild(child) {
         if (child === this)
             throw new Error('SceneNode: a node cannot be its own child (cycle)');
-        for (let at = this; at !== null; at = at.parent) {
+        for (let at = this.parent; at !== null; at = at.parent) {
             if (at === child)
                 throw new Error('SceneNode: that would make a cycle');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.7.3",
+  "version": "4.8.0",
   "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.7.3",
-    "@driftengine/physics": "4.7.3",
+    "@driftengine/drft": "4.8.0",
+    "@driftengine/physics": "4.8.0",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.7.3",
-    "@driftengine/network": "4.7.3",
-    "@driftengine/texture": "4.7.3"
+    "@driftengine/nav": "4.8.0",
+    "@driftengine/network": "4.8.0",
+    "@driftengine/texture": "4.8.0"
   }
 }

package/src/geometry/meshBuilder.ts

@@ -969,8 +969,9 @@ export class MeshBuilder {
         // later one is transported from it, so the choice never shows.
         const ax = Math.abs(tx) < 0.9 ? 1 : 0;
         const ay = Math.abs(tx) < 0.9 ? 0 : 1;
-        ux = ay * tz - 0 * ty;
-        uy = 0 * tx - ax * tz;
+        // (ax, ay, 0) x tangent, with the terms the zero removes left out.
+        ux = ay * tz;
+        uy = -ax * tz;
         uz = ax * ty - ay * tx;
         seeded = true;
       }

package/src/math/exact.ts

@@ -69,7 +69,7 @@ const PI = 3.141592653589793;
 
 /* fdlibm's `__kernel_sin` coefficients. */
 const S1 = -1.6666666666666632e-1;
-const S2 = 8.3333333333224894e-3;
+const S2 = 8.33333333332249e-3;
 const S3 = -1.984126982985795e-4;
 const S4 = 2.7557313707070068e-6;
 const S5 = -2.5050760253406863e-8;
@@ -77,7 +77,7 @@ const S6 = 1.5896909952115501e-10;
 
 /* fdlibm's `__kernel_cos` coefficients. */
 const C1 = 4.1666666666666602e-2;
-const C2 = -1.3888888888874109e-3;
+const C2 = -1.388888888887411e-3;
 const C3 = 2.480158728947673e-5;
 const C4 = -2.7557314351390663e-7;
 const C5 = 2.0875723212981748e-9;
@@ -286,7 +286,7 @@ export function exactLog(x: number): number {
   if ((0x000fffff & (2 + hx)) < 3) {
     /* |f| < 2^-20: two terms of the series are the whole answer. */
     if (f === 0) return k === 0 ? 0 : k * LN2_HI + k * LN2_LO;
-    const r = f * f * (0.5 - 0.33333333333333333 * f);
+    const r = f * f * (0.5 - 0.3333333333333333 * f);
     return k === 0 ? f - r : k * LN2_HI - (r - k * LN2_LO - f);
   }
   const s = f / (2 + f);

package/src/render/backend/webgpu/linePass.ts

@@ -5,7 +5,6 @@ import {
   LINE_VERT_WGSL,
 } from '../../shaders/generated/line.wgsl.ts';
 import { buildSegmentQuads } from '../../segmentQuads.ts';
-import type { LineSegments } from '../../linePoints.ts';
 import type { UniformFields } from './scatterPass.ts';
 import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';

package/src/render/mesh.ts

@@ -30,8 +30,6 @@ import { validateMeshData } from '@driftengine/drft';
  * well. Both halves are fixed — `flat.ts` normalises the lobe, and this is the width that
  * actually matches.
  */
-/* The engine's fixed lobe, stated once in `vertexDefaults.ts` so both backends read one number. */
-const DEFAULT_ROUGHNESS = ABSENT_ATTRIBUTE['roughness']?.[0] ?? 0.4277;
 
 /** Attribute locations are fixed engine-wide (`layout(location = n)` in GLSL). */
 const ATTR_POSITION = 0;

package/src/render/plumeRenderer.ts

@@ -62,39 +62,9 @@ export interface PlumeOptions {
   tint?: Vec3;
 }
 
-/**
- * Blades in each plume's cross, and the vertices that costs.
- *
- * **Two, crossed at 90°, instead of one card turned to face the viewer.** A single
- * billboard has no three-dimensional structure to see: orbiting a fire showed the
- * identical silhouette from every angle, because every card shared one camera-derived
- * axis and the whole plume swivelled as a sheet. Reported twice: the fire did not read
- * as three-dimensional, it read as something that moved with the camera — and after a
- * first attempt that only *leaned* edge-on cards toward the viewer, it still did,
- * correctly, because leaning still rotates whichever cards are edge-on, so the ensemble
- * still tracks the viewer.
- *
- * A cross cannot track anything: both blades are fixed in world space, so turning
- * around a fire genuinely brings one broadside as the other goes edge-on, which is
- * the parallax a volume has. It also removes the reason billboarding existed — a
- * blade going edge-on no longer vanishes, because its partner is square-on at that
- * exact moment.
- *
- * Two rather than three because the plumes blend additively and are drawn in
- * quantity: the third blade costs 50% more geometry for a difference the eye does not
- * separate at the sizes these are drawn.
- */
-const BLADES = 2;
 /* The shared count, so both backends step a plume's vertices the same way. */
 const VERTS_PER_PLUME = PLUME_VERTS;
 
-const CORNERS = [
-  [-1, -1],
-  [1, -1],
-  [1, 1],
-  [-1, 1],
-] as const;
-
 export class PlumeRenderer {
   private readonly program: WebGLProgram;
   private readonly uniforms: Record<string, WebGLUniformLocation>;

package/src/scene/node.ts

@@ -140,7 +140,7 @@ export class SceneNode {
    */
   attachChild(child: SceneNode): void {
     if (child === this) throw new Error('SceneNode: a node cannot be its own child (cycle)');
-    for (let at: SceneNode | null = this; at !== null; at = at.parent) {
+    for (let at = this.parent; at !== null; at = at.parent) {
       if (at === child) throw new Error('SceneNode: that would make a cycle');
     }
     if (child.parent === this) return;