@driftengine/core 3.61.1 → 3.61.2

package/scripts/png.mjs

@@ -0,0 +1,201 @@
+/**
+ * Enough of a PNG reader to compare two frames, with no dependency.
+ *
+ * A screenshot arrives as 8-bit RGBA, filter method 0, not interlaced, which is what every
+ * browser produces and is exactly what this handles. Anything else is refused by name rather
+ * than guessed at, because a reader that quietly mis-decodes produces pixel differences that
+ * look like a rendering change.
+ *
+ * `zlib` is Node's own, so this costs nothing to have.
+ */
+import { crc32, deflateSync, inflateSync } from 'node:zlib';
+import { readFileSync } from 'node:fs';
+
+const SIGNATURE = 0x89504e47;
+
+/** `{ width, height, channels, pixels }`, pixels being row-major 8-bit samples. */
+export function decodePng(bytes) {
+  if (bytes.length < 8 || bytes.readUInt32BE(0) !== SIGNATURE) throw new Error('not a PNG');
+
+  let at = 8;
+  let width = 0;
+  let height = 0;
+  let channels = 0;
+  const parts = [];
+
+  while (at + 8 <= bytes.length) {
+    const length = bytes.readUInt32BE(at);
+    const type = bytes.toString('ascii', at + 4, at + 8);
+    const body = bytes.subarray(at + 8, at + 8 + length);
+    if (type === 'IHDR') {
+      width = body.readUInt32BE(0);
+      height = body.readUInt32BE(4);
+      const depth = body[8];
+      const colorType = body[9];
+      const interlace = body[12];
+      if (depth !== 8) throw new Error(`bit depth ${depth}, only 8 is handled`);
+      if (interlace !== 0) throw new Error('interlaced PNG, not handled');
+      channels = colorType === 6 ? 4 : colorType === 2 ? 3 : 0;
+      if (channels === 0) throw new Error(`colour type ${colorType}, only 2 and 6 are handled`);
+    } else if (type === 'IDAT') {
+      parts.push(body);
+    } else if (type === 'IEND') {
+      break;
+    }
+    /* length, type, body, CRC. */
+    at += 12 + length;
+  }
+  if (width === 0 || height === 0) throw new Error('no IHDR');
+
+  const raw = inflateSync(Buffer.concat(parts));
+  const stride = width * channels;
+  const pixels = Buffer.alloc(stride * height);
+
+  /*
+   * Un-filtering, which is the whole of the format that is not zlib. Each row states one of five
+   * predictors and the residual against it; `a` is the sample one pixel left, `b` the one above,
+   * `c` the one above and left, and all three are zero outside the image rather than wrapped.
+   */
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const from = y * (stride + 1) + 1;
+    const to = y * stride;
+    for (let i = 0; i < stride; i++) {
+      const value = raw[from + i];
+      const a = i >= channels ? pixels[to + i - channels] : 0;
+      const b = y > 0 ? pixels[to - stride + i] : 0;
+      const c = i >= channels && y > 0 ? pixels[to - stride + i - channels] : 0;
+      let restored;
+      if (filter === 0) restored = value;
+      else if (filter === 1) restored = value + a;
+      else if (filter === 2) restored = value + b;
+      else if (filter === 3) restored = value + ((a + b) >> 1);
+      else if (filter === 4) restored = value + paeth(a, b, c);
+      else throw new Error(`row ${y} states filter ${filter}, which is not a PNG filter`);
+      pixels[to + i] = restored & 0xff;
+    }
+  }
+
+  return { width, height, channels, pixels };
+}
+
+/** The Paeth predictor: whichever of the three neighbours the gradient points closest to. */
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}
+
+export function readPng(path) {
+  return decodePng(readFileSync(path));
+}
+
+/**
+ * Write 8-bit RGBA as a PNG. The other half of this file, and it arrived nine months later.
+ *
+ * **Why the baker needs it.** A block-compressed DDS is decoded so a bought model's maps survive
+ * the bake, and the decoded surface was then embedded as `CODEC_RAW`, because nothing on the Node
+ * side could write an image back. Measured on one shipped car's level of detail B: 21 textures,
+ * 3.6 MB of source, 11.6 MB of RGBA in a 22.8 MB container. Both ends are lossless, so this is a
+ * smaller file and not a worse one.
+ *
+ * **`node:zlib` is the whole dependency**, which is what makes this affordable — it runs offline,
+ * in a tool, once per bake, and a game never links it.
+ *
+ * Colour type 6 only, because the one caller decodes to RGBA and a second colour type is a second
+ * set of filter arithmetic to get wrong for no measured gain.
+ */
+export function encodePng(width, height, rgba) {
+  const stride = width * 4;
+  const expected = stride * height;
+  if (rgba.length !== expected) {
+    throw new Error(`${width}x${height} RGBA is ${expected} bytes, got ${rgba.length}`);
+  }
+  const pixels = Buffer.isBuffer(rgba)
+    ? rgba
+    : Buffer.from(rgba.buffer, rgba.byteOffset, rgba.length);
+
+  /*
+   * One filter chosen per row by the sum of absolute residuals, which is the heuristic the format's
+   * own specification suggests and every encoder uses. It is a heuristic and not an optimum: it
+   * assumes the deflate that follows is cheapest on the bytes nearest zero, which is true often
+   * enough to be worth the five passes and is not a claim about any particular image.
+   */
+  const raw = Buffer.alloc((stride + 1) * height);
+  const candidate = Buffer.alloc(stride);
+  for (let y = 0; y < height; y++) {
+    const row = y * stride;
+    const prev = row - stride;
+    const out = y * (stride + 1);
+    let bestFilter = 0;
+    let bestScore = Infinity;
+    for (let filter = 0; filter <= 4; filter++) {
+      let score = 0;
+      for (let i = 0; i < stride; i++) {
+        const a = i >= 4 ? pixels[row + i - 4] : 0;
+        const b = y > 0 ? pixels[prev + i] : 0;
+        const c = i >= 4 && y > 0 ? pixels[prev + i - 4] : 0;
+        const residual = (pixels[row + i] - predict(filter, a, b, c)) & 0xff;
+        /* Distance from zero in both directions: 255 is a residual of one, not of 255. */
+        score += residual < 128 ? residual : 256 - residual;
+      }
+      if (score < bestScore) {
+        bestScore = score;
+        bestFilter = filter;
+      }
+    }
+    for (let i = 0; i < stride; i++) {
+      const a = i >= 4 ? pixels[row + i - 4] : 0;
+      const b = y > 0 ? pixels[prev + i] : 0;
+      const c = i >= 4 && y > 0 ? pixels[prev + i - 4] : 0;
+      candidate[i] = (pixels[row + i] - predict(bestFilter, a, b, c)) & 0xff;
+    }
+    raw[out] = bestFilter;
+    candidate.copy(raw, out + 1);
+  }
+
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', deflateSync(raw, { level: 9 })),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+/** The predictor a filter subtracts, with `predict(4, …)` being Paeth and `predict(0, …)` nothing. */
+function predict(filter, a, b, c) {
+  if (filter === 0) return 0;
+  if (filter === 1) return a;
+  if (filter === 2) return b;
+  if (filter === 3) return (a + b) >> 1;
+  return paeth(a, b, c);
+}
+
+/**
+ * Length, type, body, CRC.
+ *
+ * **The CRC covers the type and the body and not the length**, and it is the one part of this that
+ * `decodePng` above cannot check the work of, because it does not read one. A browser does, at
+ * `createImageBitmap`, and refuses the file — so an encoder verified only against this file's own
+ * reader would pass every test and produce images nothing else would open.
+ */
+function chunk(type, body) {
+  const out = Buffer.alloc(body.length + 12);
+  out.writeUInt32BE(body.length, 0);
+  out.write(type, 4, 'ascii');
+  body.copy(out, 8);
+  out.writeUInt32BE(crc32(out.subarray(4, 8 + body.length)), 8 + body.length);
+  return out;
+}

package/scripts/releases.mjs

@@ -0,0 +1,109 @@
+/**
+ * Release notes, read and ordered in one place so every consumer shows the same list.
+ *
+ * **The engine's `CHANGELOG.json` is the source of truth and this is how it is read.** Four things
+ * display these notes — the game, the studio, the website and the engine's own site — and each used
+ * to parse and sort them itself, with a copy of the data pushed between repositories by hand after
+ * every release. One reader, one ordering, and a consumer regenerates from the engine at build time
+ * rather than waiting for somebody to republish.
+ *
+ * **A product's own history is ordered by version, never by date.** That is the bug this was
+ * written for: a date-first order put 2.5.0 above 2.6.0 because 2.5.0 carried a date somebody had
+ * guessed, so the list a player read disagreed with the numbers in it. A date is metadata and can
+ * be wrong; a version cannot.
+ *
+ * **Plain Node, beside `browser.mjs` and `cdp.mjs`**, because the things that read it are build
+ * scripts in four other repositories rather than anything a game bundles. `scripts/releases.test.mjs`
+ * in this repository is its suite.
+ */
+/**
+ * A release is `{ product, version, date, entries, reports? }`, and an entry is
+ * `{ kind, text, short? }`. Described here rather than declared: this is the shape four
+ * repositories read, and `releases.d.ts` in the design system types it for the ones that care.
+ */
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)$/;
+
+/**
+ * Sortable rank for a semver string.
+ *
+ * Hand-rolled rather than taken from a dependency, and by *number* rather than by string — a
+ * string comparison puts `2.10.0` below `2.9.0`, which is the second ordering bug this file
+ * exists to make impossible.
+ */
+function rank(version) {
+  const match = SEMVER.exec(version);
+  if (match === null) throw new Error(`not a semver version: ${version}`);
+  return Number(match[1]) * 1_000_000 + Number(match[2]) * 1_000 + Number(match[3]);
+}
+
+/**
+ * One product's releases, newest first, field by field.
+ *
+ * Copied field by field rather than spread, so a key added to a changelog has to be added here
+ * before it can reach a reader: this output is published, and a changelog is edited far more
+ * casually than a published surface deserves.
+ */
+export function parseChangelog(raw, product) {
+  if (!Array.isArray(raw)) throw new Error(`${product}: a changelog is an array of releases`);
+
+  const releases = raw.map((release) => {
+    if (typeof release.version !== 'string' || typeof release.date !== 'string') {
+      throw new Error(`${product}: a release needs a version and a date`);
+    }
+    rank(release.version);
+
+    const entries = Array.isArray(release.entries) ? release.entries : [];
+    const out = {
+      product,
+      version: release.version,
+      date: release.date,
+      entries: entries.map((entry) => {
+        const carried = {
+          kind: typeof entry.kind === 'string' ? entry.kind : 'changed',
+          text: typeof entry.text === 'string' ? entry.text : '',
+        };
+        return typeof entry.short === 'string' && entry.short.length > 0
+          ? { ...carried, short: entry.short }
+          : carried;
+      }),
+    };
+    return Array.isArray(release.reports) && release.reports.length > 0
+      ? { ...out, reports: release.reports.map(String) }
+      : out;
+  });
+
+  return releases.sort((a, b) => rank(b.version) - rank(a.version));
+}
+
+/**
+ * Several products' releases as one list, newest first.
+ *
+ * **Across products there is nothing but the date to interleave by**, so that is what is used —
+ * but a date that would break a product's own version order is clamped rather than obeyed. A
+ * release cannot sort above a newer release of the same product, whatever its date says, which is
+ * what keeps a single wrong date from scrambling the whole list instead of just its own row.
+ *
+ * The displayed date is the authored one. Only the ordering is clamped, because showing a
+ * corrected date would hide the error rather than survive it.
+ */
+export function mergeReleases(products) {
+  const order = new Map();
+  for (const product of products) {
+    let ceiling = null;
+    /* Newest first already, so each release is clamped to the one above it. */
+    for (const release of product) {
+      const effective = ceiling === null || release.date <= ceiling ? release.date : ceiling;
+      order.set(release, effective);
+      ceiling = effective;
+    }
+  }
+
+  return products.flat().sort((a, b) => {
+    const dateA = order.get(a) ?? a.date;
+    const dateB = order.get(b) ?? b.date;
+    if (dateA !== dateB) return dateA < dateB ? 1 : -1;
+    if (a.product !== b.product) return a.product < b.product ? -1 : 1;
+    return rank(b.version) - rank(a.version);
+  });
+}