@driftengine/core 4.8.1 → 4.8.2

package/dist/render/surfaceTexture.d.ts

@@ -199,6 +199,8 @@ export declare class SurfaceTexture {
      */
     constructor(gl: WebGL2RenderingContext, source: TexImageSource | readonly TexImageSource[], options?: SurfaceTextureOptions);
     /** Bind the effects table to `unit`, or `fallback` for a texture given none. */
+    /** Whether this texture carries an effects table, which the lit program reads only once one exists. */
+    get hasEffects(): boolean;
     bindEffects(gl: WebGL2RenderingContext, unit: number, fallback: WebGLTexture): void;
     /**
      * Replace the pixels, keeping the GPU object and its sampler state.

package/dist/render/surfaceTexture.js

@@ -108,6 +108,10 @@ export class SurfaceTexture {
         }
     }
     /** Bind the effects table to `unit`, or `fallback` for a texture given none. */
+    /** Whether this texture carries an effects table, which the lit program reads only once one exists. */
+    get hasEffects() {
+        return this.effectsTable !== null;
+    }
     bindEffects(gl, unit, fallback) {
         gl.activeTexture(gl.TEXTURE0 + unit);
         gl.bindTexture(gl.TEXTURE_2D, this.effectsTable ?? fallback);

package/dist/render/viewModel.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The slice of depth a view model is drawn into: the nearest share of the range.
+ *
+ * **A first-person view model — arms and a held weapon — must never go into the wall it is pushed
+ * against**, and clearing depth to draw it on top costs every pass that reads depth afterwards:
+ * ambient occlusion, depth of field and the fog all see a hole where the world was. Squeezing the
+ * view model's depth into the nearest sliver of the range does neither. Anything past the near
+ * plane in the world lands behind it, the world's depth is kept, and the view model still sorts
+ * against itself, at a fraction of the precision.
+ *
+ * **The near end is where the convention says it is**: 1 under reversed depth and 0 under the
+ * conventional sense, which a WebGL2 context without `EXT_clip_control` runs. Taken from the
+ * renderer's own `reversedDepth`, never from the constant, for the reason `depthConvention.ts`
+ * gives at length.
+ *
+ * **What it gives up**: a view model is in front of everything, so it cannot be drawn reaching
+ * behind a world object in its own frame — which is what a view model is for. And under temporal
+ * reconstruction its pixels take no motion of their own, because the motion pass matches the frame's
+ * depth exactly and a squeezed draw matches nothing; draw a view model with multisampling.
+ */
+/** The share of depth a view model is drawn into when the caller names none: the nearest 1%. */
+export declare const VIEW_MODEL_DEPTH_SHARE = 0.01;
+/**
+ * Fill `out` with the `[min, max]` window depth a view model's draws are squeezed into.
+ *
+ * `share` is clamped to `[1e-4, 1]`: zero would collapse every view-model fragment onto one depth
+ * and lose its own sorting, and more than the whole range is no squeeze.
+ */
+export declare function viewModelDepthRange(reversed: boolean, share: number, out: [number, number] | Float32Array): void;

package/dist/render/viewModel.js

@@ -0,0 +1,35 @@
+/**
+ * The slice of depth a view model is drawn into: the nearest share of the range.
+ *
+ * **A first-person view model — arms and a held weapon — must never go into the wall it is pushed
+ * against**, and clearing depth to draw it on top costs every pass that reads depth afterwards:
+ * ambient occlusion, depth of field and the fog all see a hole where the world was. Squeezing the
+ * view model's depth into the nearest sliver of the range does neither. Anything past the near
+ * plane in the world lands behind it, the world's depth is kept, and the view model still sorts
+ * against itself, at a fraction of the precision.
+ *
+ * **The near end is where the convention says it is**: 1 under reversed depth and 0 under the
+ * conventional sense, which a WebGL2 context without `EXT_clip_control` runs. Taken from the
+ * renderer's own `reversedDepth`, never from the constant, for the reason `depthConvention.ts`
+ * gives at length.
+ *
+ * **What it gives up**: a view model is in front of everything, so it cannot be drawn reaching
+ * behind a world object in its own frame — which is what a view model is for. And under temporal
+ * reconstruction its pixels take no motion of their own, because the motion pass matches the frame's
+ * depth exactly and a squeezed draw matches nothing; draw a view model with multisampling.
+ */
+/** The share of depth a view model is drawn into when the caller names none: the nearest 1%. */
+export const VIEW_MODEL_DEPTH_SHARE = 0.01;
+/**
+ * Fill `out` with the `[min, max]` window depth a view model's draws are squeezed into.
+ *
+ * `share` is clamped to `[1e-4, 1]`: zero would collapse every view-model fragment onto one depth
+ * and lose its own sorting, and more than the whole range is no squeeze.
+ */
+export function viewModelDepthRange(reversed, share, out) {
+    const width = Number.isFinite(share)
+        ? Math.min(1, Math.max(1e-4, share))
+        : VIEW_MODEL_DEPTH_SHARE;
+    out[0] = reversed ? 1 - width : 0;
+    out[1] = reversed ? 1 : width;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.8.1",
+  "version": "4.8.2",
   "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.8.1",
-    "@driftengine/physics": "4.8.1",
+    "@driftengine/drft": "4.8.2",
+    "@driftengine/physics": "4.8.2",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.8.1",
-    "@driftengine/network": "4.8.1",
-    "@driftengine/texture": "4.8.1"
+    "@driftengine/nav": "4.8.2",
+    "@driftengine/network": "4.8.2",
+    "@driftengine/texture": "4.8.2"
   }
 }

package/src/index.ts

@@ -743,6 +743,8 @@ export {
   REVERSED_DEPTH,
   conventionalDepth,
 } from './render/depthConvention.ts';
+/* How much of the depth range `beginViewModel` takes when it is given no share. See `viewModel.ts`. */
+export { VIEW_MODEL_DEPTH_SHARE } from './render/viewModel.ts';
 export type { ColliderSurfaceOptions } from './physics/colliderSurface.ts';
 export { BoxSurface } from './physics/boxSurface.ts';
 export { heightSurface } from './physics/heightSurface.ts';
@@ -864,7 +866,13 @@ export {
 export { InputSource } from './input/input.ts';
 export { isTypingTarget } from './input/typingTarget.ts';
 export type { TouchPoint, InputCallbacks } from './input/input.ts';
-export type { GamepadIdentity, GamepadView, InputOptions, InputSourceName } from './input/input.ts';
+export type {
+  GamepadIdentity,
+  GamepadView,
+  InputOptions,
+  InputSourceName,
+  MouseButton,
+} from './input/input.ts';
 export type { InputDevice } from './input/activeDevice.ts';
 export type { GamepadFamily } from './input/gamepadIdentity.ts';
 /* Positions rather than lettering, and the constant a consumer overrides to taste. */

package/src/input/actionMap.ts

@@ -1,5 +1,5 @@
 import type { KeyValueStore } from '../core/storage.ts';
-import type { InputSource } from './input.ts';
+import type { InputSource, MouseButton } from './input.ts';
 import type { GamepadButton } from './gamepadMapping.ts';
 
 /**
@@ -18,12 +18,15 @@ import type { GamepadButton } from './gamepadMapping.ts';
 /** One thing that can satisfy an action. */
 export type Binding =
   | { readonly device: 'keyboard'; readonly code: string }
-  | { readonly device: 'gamepad'; readonly button: GamepadButton };
+  | { readonly device: 'gamepad'; readonly button: GamepadButton }
+  | { readonly device: 'mouse'; readonly button: MouseButton };
 
 /** Jump, fire, pause: a state, bound to keys and buttons. */
 export interface DigitalAction {
   readonly keys?: readonly string[];
   readonly buttons?: readonly GamepadButton[];
+  /** Mouse buttons, pressed over the input source's target: fire on the left, aim on the right. */
+  readonly mouseButtons?: readonly MouseButton[];
 }
 
 /**
@@ -92,7 +95,9 @@ export class ActionMap {
     return this.any(action, (binding) =>
       binding.device === 'keyboard'
         ? this.input.isDown(binding.code)
-        : (this.input.pad(0)?.down(binding.button) ?? false),
+        : binding.device === 'mouse'
+          ? this.input.mouseDown(binding.button)
+          : (this.input.pad(0)?.down(binding.button) ?? false),
     );
   }
 
@@ -101,7 +106,9 @@ export class ActionMap {
     return this.any(action, (binding) =>
       binding.device === 'keyboard'
         ? this.input.keyPressed(binding.code)
-        : (this.input.pad(0)?.pressed(binding.button) ?? false),
+        : binding.device === 'mouse'
+          ? this.input.mousePressed(binding.button)
+          : (this.input.pad(0)?.pressed(binding.button) ?? false),
     );
   }
 
@@ -118,6 +125,8 @@ export class ActionMap {
     for (const binding of bindings) {
       if (binding.device === 'keyboard') {
         if (this.input.consumeKeyPress(binding.code)) return true;
+      } else if (binding.device === 'mouse') {
+        if (this.input.consumeMousePress(binding.button)) return true;
       } else if (this.input.pad(0)?.consumePress(binding.button) === true) {
         return true;
       }
@@ -354,16 +363,19 @@ function bindingsOf(definition: DigitalAction): Binding[] {
   const list: Binding[] = [];
   for (const code of definition.keys ?? []) list.push({ device: 'keyboard', code });
   for (const button of definition.buttons ?? []) list.push({ device: 'gamepad', button });
+  for (const button of definition.mouseButtons ?? []) list.push({ device: 'mouse', button });
   return list;
 }
 
 function sameBinding(a: Binding, b: Binding): boolean {
-  if (a.device !== b.device) return false;
-  return a.device === 'keyboard' && b.device === 'keyboard'
-    ? a.code === b.code
-    : a.device === 'gamepad' && b.device === 'gamepad' && a.button === b.button;
+  if (a.device === 'keyboard' || b.device === 'keyboard') {
+    return a.device === 'keyboard' && b.device === 'keyboard' && a.code === b.code;
+  }
+  return a.device === b.device && a.button === b.button;
 }
 
+const MOUSE_BUTTONS: ReadonlySet<string> = new Set(['left', 'middle', 'right', 'back', 'forward']);
+
 function sameList(a: readonly Binding[], b: readonly Binding[]): boolean {
   return a.length === b.length && a.every((entry, at) => sameBinding(entry, b[at] as Binding));
 }
@@ -373,5 +385,8 @@ function isBinding(value: unknown): value is Binding {
   if (typeof value !== 'object' || value === null) return false;
   const candidate = value as { device?: unknown; code?: unknown; button?: unknown };
   if (candidate.device === 'keyboard') return typeof candidate.code === 'string';
+  if (candidate.device === 'mouse') {
+    return typeof candidate.button === 'string' && MOUSE_BUTTONS.has(candidate.button);
+  }
   return candidate.device === 'gamepad' && typeof candidate.button === 'string';
 }

package/src/input/input.ts

@@ -104,6 +104,23 @@ export interface TouchPoint {
 /** The devices this source watches, and the granularity a consumer may switch off. */
 export type InputSourceName = 'keyboard' | 'mouse' | 'touch' | 'gamepad';
 
+/** A mouse button by what it is, in `MouseEvent.button` order. */
+export type MouseButton = 'left' | 'middle' | 'right' | 'back' | 'forward';
+
+/** One bit a button, so the held, pressed and claimed states are integers and a read allocates nothing. */
+const MOUSE_BIT: Readonly<Record<MouseButton, number>> = {
+  left: 1,
+  middle: 2,
+  right: 4,
+  back: 8,
+  forward: 16,
+};
+
+/** `MouseEvent.button` as a bit, or 0 for a button past the five this names. */
+function mouseBit(button: number): number {
+  return button >= 0 && button < 5 ? 1 << button : 0;
+}
+
 export interface InputOptions {
   /**
    * Turn a device off. Absent means on.
@@ -420,6 +437,19 @@ export class InputSource {
   private mouseDx = 0;
   private mouseDy = 0;
   private mouseButtonDown = false;
+  /**
+   * Each mouse button's own state, as the keyboard's sets are for keys: held, pressed since the
+   * last poll, claimed this frame, and waiting for somebody to act on it. Bits, by `MOUSE_BIT`.
+   *
+   * **Beside `mouseButtonDown`, not instead of it.** That flag is "a button is held", which is what
+   * an unlocked drag-to-look reads; a game binding fire to the left button and aim to the right
+   * needs to know which, and to see a release of one while the other stays down.
+   */
+  private mouseHeld = 0;
+  private mousePressedNow = 0;
+  private mousePressedNext = 0;
+  private mouseClaimed = 0;
+  private mouseUnclaimed = 0;
   private readonly disposers: Array<() => void> = [];
 
   /** Which device the player last actually used, and who wants telling when that changes. */
@@ -531,13 +561,21 @@ export class InputSource {
       this.keysUnclaimed.clear();
     });
 
-    this.listen(target, 'mousedown', () => {
+    this.listen(target, 'mousedown', (e: MouseEvent) => {
       if (!this.enabled.mouse) return;
       this.mouseButtonDown = true;
+      const bit = mouseBit(e.button);
+      this.mouseHeld |= bit;
+      this.mousePressedNext |= bit;
+      this.mouseUnclaimed |= bit;
       this.active.use('mouse');
     });
-    this.listen(window, 'mouseup', () => {
+    /* On the window, so a press that becomes a drag off the canvas still comes back up. */
+    this.listen(window, 'mouseup', (e: MouseEvent) => {
       this.mouseButtonDown = false;
+      const bit = mouseBit(e.button);
+      this.mouseHeld &= ~bit;
+      this.mouseUnclaimed &= ~bit;
     });
     /*
      * **Released by anything that can eat the mouseup, exactly as the keys are.**
@@ -559,15 +597,11 @@ export class InputSource {
      * `visibilitychange` as well as `blur`, because a tab switched away with a button held
      * comes back to a document that never saw the release either.
      */
-    this.listen(window, 'blur', () => {
-      this.mouseButtonDown = false;
-    });
-    this.listen(window, 'pointercancel', () => {
-      this.mouseButtonDown = false;
-    });
+    this.listen(window, 'blur', () => this.releaseMouse());
+    this.listen(window, 'pointercancel', () => this.releaseMouse());
     /* Not in `GlobalEventHandlersEventMap`, so it is bound directly and disposed by hand. */
     const onHidden = (): void => {
-      if (document.visibilityState !== 'visible') this.mouseButtonDown = false;
+      if (document.visibilityState !== 'visible') this.releaseMouse();
     };
     document.addEventListener('visibilitychange', onHidden);
     this.disposers.push(() => document.removeEventListener('visibilitychange', onHidden));
@@ -676,6 +710,10 @@ export class InputSource {
     spent.clear();
     this.keysPressedNext = spent;
     this.keysClaimed.clear();
+    /* The mouse buttons' frame boundary, on the same poll and by the same rule. */
+    this.mousePressedNow = this.mousePressedNext;
+    this.mousePressedNext = 0;
+    this.mouseClaimed = 0;
 
     if (!this.enabled.gamepad) return;
     const source = (globalThis as { navigator?: { getGamepads?: () => (RawPad | null)[] } })
@@ -768,6 +806,38 @@ export class InputSource {
     return true;
   }
 
+  /**
+   * Whether a mouse button is held: pressed over the target and not yet released anywhere.
+   *
+   * A browser opens its context menu on the right button's release; a game binding that button
+   * cancels `contextmenu` on its canvas, which is a decision about the page and not this source's.
+   */
+  mouseDown(button: MouseButton): boolean {
+    return (this.mouseHeld & MOUSE_BIT[button]) !== 0;
+  }
+
+  /** Whether a mouse button went down since the last poll, as `keyPressed` is for a key. */
+  mousePressed(button: MouseButton): boolean {
+    const bit = MOUSE_BIT[button];
+    return (this.mousePressedNow & bit) !== 0 && (this.mouseClaimed & bit) === 0;
+  }
+
+  /** The same edge, claimed, as `consumeKeyPress` is for a key: true for exactly one caller. */
+  consumeMousePress(button: MouseButton): boolean {
+    const bit = MOUSE_BIT[button];
+    if ((this.mouseUnclaimed & bit) === 0) return false;
+    this.mouseUnclaimed &= ~bit;
+    this.mouseClaimed |= bit;
+    return true;
+  }
+
+  /** Every button up and every waiting press gone: what a lost focus or a cancelled pointer means. */
+  private releaseMouse(): void {
+    this.mouseButtonDown = false;
+    this.mouseHeld = 0;
+    this.mouseUnclaimed = 0;
+  }
+
   /**
    * Add a device-event subscriber. Multiple reusable control layers may listen
    * without overwriting one another; interpretation still happens outside the

package/src/input/inputHarness.ts

@@ -96,9 +96,19 @@ export function fakeBrowser(id = 'Xbox 360 Controller (XInput STANDARD GAMEPAD)'
   const frameCallbacks: ((time: number) => void)[] = [];
   let nextFrameHandle = 1;
 
+  const targetListeners = new Map<string, ((event: unknown) => void)[]>();
   const target = {
-    addEventListener: () => {},
-    removeEventListener: () => {},
+    addEventListener: (type: string, fn: (event: unknown) => void) => {
+      const existing = targetListeners.get(type);
+      if (existing === undefined) targetListeners.set(type, [fn]);
+      else existing.push(fn);
+    },
+    removeEventListener: (type: string, fn: (event: unknown) => void) => {
+      const existing = targetListeners.get(type);
+      if (existing === undefined) return;
+      const at = existing.indexOf(fn);
+      if (at >= 0) existing.splice(at, 1);
+    },
     requestPointerLock: () => undefined,
     getBoundingClientRect: () => ({ left: 0, top: 0, width: 640, height: 480 }),
   } as unknown as HTMLElement;
@@ -204,6 +214,21 @@ export function fakeBrowser(id = 'Xbox 360 Controller (XInput STANDARD GAMEPAD)'
     keyUp(code: string): void {
       for (const fn of windowListeners.get('keyup') ?? []) fn({ code });
     },
+    /**
+     * Press a mouse button over the target, by `MouseEvent.button`: 0 left, 1 middle, 2 right.
+     * Pressed on the target and released on the window, as a browser delivers a drag that ends
+     * off the canvas.
+     */
+    mouseDown(button: number): void {
+      for (const fn of targetListeners.get('mousedown') ?? []) fn({ button, movementX: 0 });
+    },
+    mouseUp(button: number): void {
+      for (const fn of windowListeners.get('mouseup') ?? []) fn({ button });
+    },
+    /** The window losing focus, which eats every release that would have followed. */
+    blur(): void {
+      for (const fn of windowListeners.get('blur') ?? []) fn({});
+    },
     /** Run exactly one animation frame, which is what a poll rides on. */
     frame(): void {
       const pending = frameCallbacks.splice(0, frameCallbacks.length);