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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mjsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});