Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(tools): a seam is measured against the frame's own interior, not a stored image

yhhcfe4d06234c4
diff --git a/tools/lib/seamProbe.mjs b/tools/lib/seamProbe.mjs
new file mode 100644
index 000000000..612149604
--- /dev/null
+++ b/tools/lib/seamProbe.mjs
@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file seamProbe.mjs — is there a line on the tile grid, measured rather than judged.
+ *
+ * A point probe (`ESTELLA_VERIFY_EXPECT`) says "this pixel is red". A seam is not
+ * a pixel — it is a column that behaves differently from its neighbours, on a
+ * grid, across a band of rows. So it needs its own measurement, and this is it.
+ *
+ * REFERENCE-FREE, which is what keeps it from going stale: it compares the
+ * boundary columns against the frame's OWN interior columns rather than against
+ * a stored image. Art changes, the ratio does not.
+ */
+
+/** Mean luminance of a column over `[y0, y1)`, from RGBA8 rows. */
+function columnLuma(px, w, x, y0, y1) {
+ let sum = 0;
+ for (let y = y0; y < y1; y++) {
+ const i = (y * w + x) * 4;
+ sum += (px[i] + px[i + 1] + px[i + 2]) / 3;
+ }
+ return sum / (y1 - y0);
+}
+
+/**
+ * Per-column step: how much a column differs from the one before it, averaged
+ * down the band. A seam is a spike in this; texture detail is a floor under it.
+ */
+export function columnSteps(px, w, h, band) {
+ const y0 = Math.max(0, Math.floor(band?.y0 ?? 0));
+ const y1 = Math.min(h, Math.ceil(band?.y1 ?? h));
+ if (y1 - y0 < 2) throw new Error('seamProbe: the band needs at least two rows');
+ const steps = new Float64Array(w);
+ let prev = columnLuma(px, w, 0, y0, y1);
+ for (let x = 1; x < w; x++) {
+ const cur = columnLuma(px, w, x, y0, y1);
+ steps[x] = Math.abs(cur - prev);
+ prev = cur;
+ }
+ return steps;
+}
+
+/** Columns within `slack` of a grid line at `period`/`phase`, and the rest. */
+function splitOnGrid(w, period, phase, slack) {
+ const boundary = [];
+ const interior = [];
+ for (let x = 1; x < w; x++) {
+ const off = Math.abs(((x - phase) % period + period) % period);
+ const near = Math.min(off, period - off);
+ (near <= slack ? boundary : interior).push(x);
+ }
+ return { boundary, interior };
+}
+
+function median(values) {
+ if (values.length === 0) return 0;
+ const sorted = [...values].sort((a, b) => a - b);
+ const mid = sorted.length >> 1;
+ return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+/**
+ * How much more the tile boundaries step than the frame's own interior. A ratio,
+ * because a detailed texture steps everywhere and a flat one nowhere.
+ *
+ * @param {Uint8Array|Uint8ClampedArray} px RGBA8, row 0 = top.
+ * @param {{y0?: number, y1?: number}} band Rows to measure over — pick a band that
+ * is all content, since sky and UI have edges of their own.
+ * @param {number} period Tile pitch in screen px; `phase` is the first boundary.
+ * @param {number} [slack] How far from a grid line still counts as the boundary.
+ * One px each side by default: a seam is a column, not a region.
+ */
+export function seamRatio(px, w, h, band, period, phase, slack = 1) {
+ if (!(period > 1)) throw new Error(`seamProbe: period ${period} is not a grid`);
+ const steps = columnSteps(px, w, h, band);
+ const { boundary, interior } = splitOnGrid(w, period, phase, slack);
+ if (boundary.length === 0 || interior.length === 0) {
+ throw new Error('seamProbe: the period leaves no interior to compare against');
+ }
+ // Max on the boundary, median inside: one visible line is the failure, and a
+ // mean would let a single strong seam average away. So clean lands near 1.4
+ // rather than 1 (synthetic wall: 1.4 clean, 2.2 quarter seam, 4.0 full).
+ const worst = Math.max(...boundary.map((x) => steps[x]));
+ const floor = median(interior.map((x) => steps[x]));
+ // A frame with no detail at all has no floor to divide by; report the step
+ // itself rather than an infinity that reads as a catastrophic seam.
+ return floor > 1e-6 ? worst / floor : worst;
+}
+
+/**
+ * Verdict for a gate: the ratio, and whether it clears `limit`.
+ * Kept separate from {@link seamRatio} so a failure can report the number.
+ */
+export function checkSeam(px, w, h, { band, period, phase = 0, slack = 1, limit = 2 }) {
+ const ratio = seamRatio(px, w, h, band, period, phase, slack);
+ return { ratio, limit, ok: ratio <= limit };
+}
diff --git a/tools/tests/seam-probe.test.ts b/tools/tests/seam-probe.test.ts
new file mode 100644
index 000000000..5c850bb87
--- /dev/null
+++ b/tools/tests/seam-probe.test.ts
@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The seam probe has to tell a seam from a texture, so both are fed to it.
+ * A measurement that only ever saw clean frames would report a small
+ * number and prove nothing — the same failure the colour-count gate had
+ * when it passed text-less, upside-down frames.
+ */
+import { describe, it, expect } from 'vitest';
+// @ts-expect-error — a tools .mjs helper, deliberately untyped
+import { seamRatio, checkSeam, columnSteps } from '../lib/seamProbe.mjs';
+
+const W = 240, H = 80, PERIOD = 24;
+
+/** A detailed wall: noise that repeats every tile, so a clean render has no grid line. */
+function wall(seam: number): Uint8Array {
+ const px = new Uint8Array(W * H * 4);
+ for (let y = 0; y < H; y++) {
+ for (let x = 0; x < W; x++) {
+ const local = x % PERIOD;
+ // Detail that is CONTINUOUS across a tile boundary, because that is what
+ // seamless art is. A pattern keyed on the position within a tile would
+ // step at every boundary on its own and the probe would be right to say so.
+ let v = 128 + 60 * Math.sin(x * 0.35) + 30 * Math.sin(y * 0.9 + x * 0.2);
+ // The seam: the first column of each tile pushed off its neighbour, the
+ // way a clamped outer half-texel reads.
+ if (local === 0) v += seam;
+ const i = (y * W + x) * 4;
+ px[i] = px[i + 1] = px[i + 2] = Math.max(0, Math.min(255, Math.round(v)));
+ px[i + 3] = 255;
+ }
+ }
+ return px;
+}
+
+const BAND = { y0: 8, y1: H - 8 };
+
+describe('seamRatio', () => {
+ it('a clean wall is near 1 — a boundary column looks like any other', () => {
+ expect(seamRatio(wall(0), W, H, BAND, PERIOD, 0)).toBeLessThan(2);
+ });
+
+ it('...and a seamed one is not, which is what makes the number mean something', () => {
+ // The same wall, the same measurement, one column pushed off. Without this
+ // pair the assertion above would pass on a probe that returned a constant.
+ expect(seamRatio(wall(40), W, H, BAND, PERIOD, 0)).toBeGreaterThan(3);
+ });
+
+ it('grows with the seam rather than latching', () => {
+ const weak = seamRatio(wall(12), W, H, BAND, PERIOD, 0);
+ const strong = seamRatio(wall(48), W, H, BAND, PERIOD, 0);
+ expect(strong).toBeGreaterThan(weak);
+ expect(weak).toBeGreaterThan(seamRatio(wall(0), W, H, BAND, PERIOD, 0));
+ });
+
+ it('a seam off the declared grid does not count — the gate looks where it was told', () => {
+ // Phase shifted by half a tile: the real seam now sits in the interior, so
+ // it becomes the floor rather than the spike. A probe that scored it anyway
+ // would be finding seams that are not on the tile grid.
+ const onGrid = seamRatio(wall(40), W, H, BAND, PERIOD, 0);
+ const offGrid = seamRatio(wall(40), W, H, BAND, PERIOD, PERIOD / 2);
+ expect(offGrid).toBeLessThan(onGrid);
+ });
+
+ it('is not fooled by a flat frame', () => {
+ // No detail, no floor. Reporting a ratio against ~0 would read as a
+ // catastrophic seam on a frame that has nothing in it at all.
+ const flat = new Uint8Array(W * H * 4).fill(255);
+ expect(Number.isFinite(seamRatio(flat, W, H, BAND, PERIOD, 0))).toBe(true);
+ });
+
+ it('refuses a period that is not a grid, and a band with no rows', () => {
+ expect(() => seamRatio(wall(0), W, H, BAND, 0, 0)).toThrow(/not a grid/);
+ expect(() => seamRatio(wall(0), W, H, { y0: 5, y1: 5 }, PERIOD, 0)).toThrow(/two rows/);
+ });
+});
+
+describe('checkSeam', () => {
+ it('reports the number with the verdict, so a red gate says how bad', () => {
+ const bad = checkSeam(wall(40), W, H, { band: BAND, period: PERIOD, limit: 2 });
+ expect(bad.ok).toBe(false);
+ expect(bad.ratio).toBeGreaterThan(bad.limit);
+
+ const good = checkSeam(wall(0), W, H, { band: BAND, period: PERIOD, limit: 2 });
+ expect(good.ok).toBe(true);
+ });
+});
+
+describe('columnSteps', () => {
+ it('measures down the band it was given, not the whole frame', () => {
+ // A band that misses the content would report a floor of zero and make
+ // every boundary look catastrophic — the gate has to be aimed.
+ const px = wall(40);
+ const narrow = columnSteps(px, W, H, { y0: 20, y1: 24 });
+ const wide = columnSteps(px, W, H, BAND);
+ expect(narrow.length).toBe(wide.length);
+ expect(narrow[PERIOD]).toBeGreaterThan(0);
+ });
+});