@driftengine/core 4.8.1 → 4.8.3

package/src/index.ts

@@ -743,6 +743,21 @@ export {
   REVERSED_DEPTH,
   conventionalDepth,
 } from './render/depthConvention.ts';
+/*
+ * **What a contributed pass's blended draw does to the scene's alpha**, which carries how much of
+ * each pixel is still the opaque surface: the share the composite's ambient occlusion may darken.
+ * A pass blending into the scene states one of these for its alpha. See `sceneCoverage.ts`.
+ */
+export {
+  SCENE_ALPHA_COVERS,
+  SCENE_ALPHA_KEEPS,
+  SCENE_ALPHA_TRANSMITS,
+  blendCovering,
+  blendKeeping,
+  blendTransmitting,
+} from './render/sceneCoverage.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 +879,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);

package/src/render/backend/materialChanges.ts

@@ -31,12 +31,17 @@ export interface DrawMaterialOptions {
   readonly refracting: boolean;
 }
 
-/** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
-export function ownsMaterial(options: DrawMaterialOptions): boolean {
+/**
+ * Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore.
+ *
+ * `passFog` is how the surfaces around it meet the medium — `FOG_RECEDE` unless `setSurfaceFog`
+ * turned it off — so a translucent draw asking for what the pass already has takes nothing.
+ */
+export function ownsMaterial(options: DrawMaterialOptions, passFog = FOG_RECEDE): boolean {
   return (
     options.opacity < 1 ||
     !options.lit ||
-    options.fog !== FOG_RECEDE ||
+    options.fog !== passFog ||
     !options.toneMapped ||
     options.refracting
   );