@driftengine/core 4.11.1 → 4.13.0

package/dist/render/textRenderer.d.ts

@@ -25,7 +25,9 @@ export declare class TextRenderer {
      *
      * Answers whether it drew, which the renderer counts on its frame budget.
      */
-    draw(viewportWidth: number, viewportHeight: number, originX: number, originY: number, style: TextStyle, timeSec: number): boolean;
+    draw(viewportWidth: number, viewportHeight: number, originX: number, originY: number, style: TextStyle, timeSec: number, 
+    /** The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+    outputTransform?: number, outputExposure?: number): boolean;
     dispose(): void;
     /** Both instance buffers, from the arrays the layout filled in place. */
     private upload;

package/dist/render/textRenderer.js

@@ -67,11 +67,17 @@ export class TextRenderer {
      *
      * Answers whether it drew, which the renderer counts on its frame budget.
      */
-    draw(viewportWidth, viewportHeight, originX, originY, style, timeSec) {
+    draw(viewportWidth, viewportHeight, originX, originY, style, timeSec, 
+    /** The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+    outputTransform = 0, outputExposure = 1) {
         if (this.layout.instanceCount === 0 || style.alpha <= 0)
             return false;
         const gl = this.gl;
         gl.useProgram(this.program);
+        const grade = this.uniforms['uOutputTransform'];
+        if (grade !== undefined)
+            gl.uniform1i(grade, outputTransform);
+        setFloat(gl, this.uniforms['uOutputExposure'], outputExposure);
         gl.bindVertexArray(this.vao);
         /*
          * Text gets a fresh depth buffer rather than no depth test at all.

package/dist/render/vertexDefaults.d.ts

@@ -41,7 +41,7 @@ export declare const OUTPUT_TRANSFORM_CODE: Readonly<Record<string, number>>;
 /**
  * The code a **forward** pass grades with: the transform's own, except `filmic`, which only the
  * composite carries the constants for, and which a pass grading itself therefore draws as `aces`.
- * Both backends' `gradeCode` read this, so neither can hand a forward stage a code it lacks.
+ * `passGrade.ts` reads this for both backends, so neither can hand a forward stage a code it lacks.
  */
 export declare function forwardTransformCode(transform: string): number;
 /**

package/dist/render/vertexDefaults.js

@@ -115,7 +115,7 @@ export const OUTPUT_TRANSFORM_CODE = {
 /**
  * The code a **forward** pass grades with: the transform's own, except `filmic`, which only the
  * composite carries the constants for, and which a pass grading itself therefore draws as `aces`.
- * Both backends' `gradeCode` read this, so neither can hand a forward stage a code it lacks.
+ * `passGrade.ts` reads this for both backends, so neither can hand a forward stage a code it lacks.
  */
 export function forwardTransformCode(transform) {
     return transform === 'filmic' ? 2 : (OUTPUT_TRANSFORM_CODE[transform] ?? 0);

package/dist/render/waterRenderer.d.ts

@@ -158,6 +158,6 @@ export declare class WaterRenderer {
      * by geometry in front of it, but its far edge fades out, and that fade needs
      * the sky already behind it to blend into.
      */
-    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, settings: WaterBody, directionalDir: Vec3, directionalColor: Vec3, ambient: Vec3, atmosphere: Atmosphere, underwaterEnabled: boolean, reflection: PlanarReflection | null, lights?: PointLightSet | null, lightFalloff?: 'smooth' | 'inverseSquare', windX?: number, windZ?: number): void;
+    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, settings: WaterBody, directionalDir: Vec3, directionalColor: Vec3, ambient: Vec3, atmosphere: Atmosphere, underwaterEnabled: boolean, reflection: PlanarReflection | null, lights?: PointLightSet | null, lightFalloff?: 'smooth' | 'inverseSquare', windX?: number, windZ?: number, outputTransform?: number, outputExposure?: number): void;
     dispose(gl: WebGL2RenderingContext): void;
 }

package/dist/render/waterRenderer.js

@@ -95,10 +95,13 @@ export class WaterRenderer {
      * by geometry in front of it, but its far edge fades out, and that fade needs
      * the sky already behind it to blend into.
      */
-    draw(gl, camera, timeSeconds, settings, directionalDir, directionalColor, ambient, atmosphere, underwaterEnabled, reflection, lights = null, lightFalloff = 'smooth', windX = 0, windZ = 0) {
+    draw(gl, camera, timeSeconds, settings, directionalDir, directionalColor, ambient, atmosphere, underwaterEnabled, reflection, lights = null, lightFalloff = 'smooth', windX = 0, windZ = 0, outputTransform = 0, outputExposure = 1) {
         const u = this.uniforms;
         const reflectionReady = reflection?.isReadyFor(settings.level) ?? false;
         gl.useProgram(this.program);
+        /* The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+        gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+        gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
         gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
         gl.uniformMatrix4fv(u['uReflectionViewProj'] ?? null, false, reflection?.viewProjection ?? camera.viewProjection);
         gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);

package/dist/render/windStreakRenderer.d.ts

@@ -33,6 +33,8 @@ export declare class WindStreakRenderer {
     /** Answers whether it drew, which the renderer counts on its frame budget. */
     draw(gl: WebGL2RenderingContext, camera: FrameView, wind: WindField, timeSeconds: number, tint: Vec3, 
     /** True when the camera is below the waterline. */
-    submerged?: boolean): boolean;
+    submerged?: boolean, 
+    /** The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+    outputTransform?: number, outputExposure?: number): boolean;
     dispose(gl: WebGL2RenderingContext): void;
 }

package/dist/render/windStreakRenderer.js

@@ -51,7 +51,9 @@ export class WindStreakRenderer {
     /** Answers whether it drew, which the renderer counts on its frame budget. */
     draw(gl, camera, wind, timeSeconds, tint, 
     /** True when the camera is below the waterline. */
-    submerged = false) {
+    submerged = false, 
+    /** The renderer's `passGrade`: the frame's, but none in a probe's face or a capture. */
+    outputTransform = 0, outputExposure = 1) {
         /* Chosen in `windStreakDraw.ts` so both backends show the same weather. */
         const settled = resolveWindStreaks(wind.speed, wind.driftX, wind.driftZ, this.onsetSpeed, this.fullSpeed, submerged, this.resolved);
         if (!settled.visible)
@@ -68,6 +70,8 @@ export class WindStreakRenderer {
         gl.uniform1f(u['uCellSize'] ?? null, this.cellSize);
         gl.uniform1f(u['uTime'] ?? null, timeSeconds);
         gl.uniform3fv(u['uTint'] ?? null, tint);
+        gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+        gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
         gl.enable(gl.BLEND);
         blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.depthMask(false);

package/package.json

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

package/scripts/browser.d.mts

@@ -7,6 +7,11 @@ export interface LaunchedBrowser {
   close(): Promise<void>;
 }
 
+/** Where a Chromium-based browser lives on a platform, in the order `chromePath` tries them. */
+export function browserCandidates(
+  platform?: string,
+  env?: Readonly<Record<string, string | undefined>>,
+): string[];
 export function chromePath(): string;
 export function launch(options?: {
   flags?: readonly string[];

package/scripts/browser.mjs

@@ -27,22 +27,64 @@
  * it, and it is what turns "leaks accumulate forever" into "at most one leak per still-running
  * process."
  */
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { once } from 'node:events';
 import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { sleep } from './cdp.mjs';
 
-/** Where a Chrome or Chromium lives, in the order worth trying. `CHROME_PATH` wins. */
-const CANDIDATES = [
-  '/opt/google/chrome/chrome',
-  '/usr/bin/google-chrome',
-  '/usr/bin/google-chrome-stable',
-  '/usr/bin/chromium',
-  '/usr/bin/chromium-browser',
-  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-];
+/**
+ * Where a Chromium-based browser lives on each platform, in the order worth trying.
+ *
+ * **Edge is last on every list and the only thing on Windows that is always there.** It is
+ * Chromium, it speaks the same DevTools protocol, and it ships with Windows 10 and 11, so a person
+ * who never installed Chrome still has a browser this module can drive. Chrome comes first where it
+ * exists because it is what the engine's captures are measured on.
+ *
+ * Windows paths are built from the environment rather than written out, because `Program Files`
+ * is wherever that machine put it and a per-user install sits under `LOCALAPPDATA`; a Mac's
+ * per-user install sits under `~/Applications`. Nothing here has been run on Windows or macOS by
+ * this repository yet; the lists are the browsers' documented install locations.
+ */
+export function browserCandidates(platform = process.platform, env = process.env) {
+  if (platform === 'win32') {
+    const roots = [env['PROGRAMFILES'], env['PROGRAMFILES(X86)'], env['LOCALAPPDATA']].filter(
+      (root) => typeof root === 'string' && root !== '',
+    );
+    return [
+      ...roots.map((root) =>
+        path.win32.join(root, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      ),
+      ...roots.map((root) =>
+        path.win32.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+      ),
+    ];
+  }
+  if (platform === 'darwin') {
+    /* `/Applications` for an install by an administrator, `~/Applications` for one without. */
+    const roots = [
+      '/Applications',
+      typeof env['HOME'] === 'string' && env['HOME'] !== ''
+        ? path.posix.join(env['HOME'], 'Applications')
+        : null,
+    ].filter((root) => root !== null);
+    const apps = [
+      'Google Chrome.app/Contents/MacOS/Google Chrome',
+      'Chromium.app/Contents/MacOS/Chromium',
+      'Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    ];
+    return apps.flatMap((app) => roots.map((root) => path.posix.join(root, app)));
+  }
+  return [
+    '/opt/google/chrome/chrome',
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/microsoft-edge',
+  ];
+}
 
 /**
  * What it takes to reach the real card from a headless process.
@@ -80,7 +122,7 @@ const PROFILE_PREFIX = 'driftengine-shots-';
 const OWNER_FILE = 'driftengine-owner.json';
 
 /**
- * Signal an entire process group, escalating if it does not go.
+ * Stop a browser and every process it started, escalating if it does not go.
  *
  * **Chrome is a tree, not a process.** It forks a zygote, a GPU process and one renderer per
  * page, and signalling the parent alone leaves the rest running with the port closed and the
@@ -89,9 +131,20 @@ const OWNER_FILE = 'driftengine-owner.json';
  *
  * SIGTERM first because a browser asked politely flushes and exits; SIGKILL after a grace period
  * because one that is wedged never will, and a wedged browser is exactly the case this exists for.
+ *
+ * **Windows has no process groups to signal**, so there `taskkill /T` walks the tree from the
+ * browser's own PID and `/F` ends it at once. Synchronous, because this also runs from an `exit`
+ * handler, where nothing asynchronous gets to finish.
  */
 function killTree(pid, graceMs = 2000) {
   if (!Number.isInteger(pid) || pid <= 0) return;
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], {
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    return;
+  }
   try {
     process.kill(-pid, 'SIGTERM');
   } catch {
@@ -194,10 +247,11 @@ function defaultIsAlive(pid) {
 export function chromePath() {
   const asked = process.env['CHROME_PATH'];
   if (asked !== undefined && asked !== '') return asked;
-  const found = CANDIDATES.find((candidate) => existsSync(candidate));
+  const candidates = browserCandidates();
+  const found = candidates.find((candidate) => existsSync(candidate));
   if (found === undefined) {
     throw new Error(
-      `no Chrome or Chromium found. Tried:\n  ${CANDIDATES.join('\n  ')}\nSet CHROME_PATH to one.`,
+      `no Chrome, Chromium or Edge found. Tried:\n  ${candidates.join('\n  ')}\nSet CHROME_PATH to one.`,
     );
   }
   return found;
@@ -227,7 +281,7 @@ export async function launch({ flags = GPU_FLAGS, headless = true, timeoutMs = 2
      process and every renderer with one signal to the negative PID. `unref()` is deliberately
      not called: the parent must stay attached, or its own exit and signal handlers below never
      fire, and those are half of what closes the other three holes. */
-  const child = spawn(binary, args, { stdio: 'ignore', detached: true });
+  const child = spawn(binary, args, { stdio: 'ignore', detached: true, windowsHide: true });
   writeFileSync(
     path.join(profile, OWNER_FILE),
     JSON.stringify({ ownerPid: process.pid, chromePid: child.pid }),

package/scripts/look.d.mts

@@ -0,0 +1,81 @@
+import type { RgbaImage } from './png.d.mts';
+
+/** The backends `look` photographs by default, in the order a consumer runs them. */
+export const LOOK_BACKENDS: readonly ['webgpu', 'webgl2'];
+
+/** At or above this share of one colour, a canvas is called empty. */
+export const EMPTY_SHARE: number;
+
+/** What a frame is made of. */
+export interface FrameStats {
+  readonly width: number;
+  readonly height: number;
+  /** The most common colour, as `#rrggbb`. */
+  readonly dominant: string;
+  /** The share of the frame that colour covers, 0 to 1. */
+  readonly dominantShare: number;
+  /** Rec. 709 luminance averaged over the frame, 0 to 255. */
+  readonly meanLuminance: number;
+}
+
+/** One backend's photograph and everything the page said while it was taken. */
+export interface LookCapture {
+  readonly backend: string;
+  readonly url: string;
+  /** What a player sees, interface included. */
+  readonly file: string;
+  /**
+   * The backend that actually drew, read from the context the page's canvas asked for: `'webgpu'`,
+   * `'webgl2'`, or `null` when no canvas in the page asked for either.
+   */
+  readonly drawnWith: 'webgpu' | 'webgl2' | null;
+  /** Measured over the canvas alone; `null` when the page never booted. */
+  readonly stats: FrameStats | null;
+  /** The share of the canvas that changed between two frames; `null` when the page never booted. */
+  readonly moved: number | null;
+  readonly errors: readonly string[];
+  readonly warnings: readonly string[];
+  /** Every console line, `level: text`. */
+  readonly logs: readonly string[];
+  readonly problems: readonly string[];
+}
+
+export interface LookReport {
+  readonly url: string;
+  /** The renderer string of the GPU that drew, read from a WebGL2 context. */
+  readonly gpu: string;
+  readonly captures: readonly LookCapture[];
+  readonly problems: readonly string[];
+  /** True when no capture found a problem. */
+  readonly ok: boolean;
+}
+
+export interface LookOptions {
+  /** The address of the running game. */
+  readonly url: string;
+  readonly backends?: readonly string[];
+  /** Where the PNGs and `look.json` go. Defaults to `.driftengine/look`. */
+  readonly out?: string;
+  readonly width?: number;
+  readonly height?: number;
+  /** How long to wait for a canvas in the page to ask for a WebGPU or WebGL2 context. */
+  readonly bootMs?: number;
+  /** A pause after that for the first frames. */
+  readonly settleMs?: number;
+  /** How long to wait after that for the canvas to show more than one colour. */
+  readonly drawMs?: number;
+  /** The gap between the two frames compared to tell whether the game moves. */
+  readonly moveMs?: number;
+  /** Browser flags; defaults to `gpuFlagsFor()`. */
+  readonly flags?: readonly string[] | null;
+  /** `false` opens a real window, for a machine whose headless browser cannot reach its GPU. */
+  readonly headless?: boolean;
+}
+
+export function gpuFlagsFor(platform?: string): string[] | null;
+export function lookUrl(url: string, backend: string): string;
+export function frameStats(image: RgbaImage): FrameStats;
+export function changedShare(a: RgbaImage, b: RgbaImage, tolerance?: number): number;
+export function sortConsole(lines: readonly string[]): { errors: string[]; warnings: string[] };
+export function look(options: LookOptions): Promise<LookReport>;
+export function formatLook(report: LookReport): string;