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.

fix(contract): the inventory accounts for every side a verifier compares

esengine7f1bc0936396
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 6bdb45d53..e02a097f6 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 84 beta · 1514 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"7e0589f085f150f6"
+"97a5a526f33a8a4b"
```
## ANCHOR_AXES — const @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index a1ec379ca..87e077057 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 89 beta · 1533 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"7e0589f085f150f6"
+"97a5a526f33a8a4b"
```
## ANCHOR_AXES — const @experimental
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index a45a5ee30..30a36a0c3 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, Cl
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '7e0589f085f150f6';
+export const ABI_LAYOUT_HASH = '97a5a526f33a8a4b';
/**
* One asset-valued field of a component: which field, and what kind of
diff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.ts
index 057f07256..ad344d0fc 100644
--- a/sdk/src/ui/text/plugin.ts
+++ b/sdk/src/ui/text/plugin.ts
@@ -26,13 +26,14 @@ import { getUINodeWidth, getUINodeHeight, ensureUIVisual } from '../util/helpers
import { resolveTextFamily } from './font-registry';
import { platformDevicePixelRatio } from '../../platform';
import { engineApi } from '../../ecs/bridge/engineApi';
+// UI quads use layer = base + uiOrder, off the C++ declaration that owns it.
+import { UI_BASE_LAYER } from '../../wasm/constants.generated';
// Base glyph rasterization size in CSS px; the real source is this × DPR so text
// stays crisp on HiDPI displays. 64 covers common UI sizes at 1:1 or finer.
const GLYPH_BASE_SIZE = 64;
-// Matches C++ UIElementPlugin::UI_BASE_LAYER — UI quads use layer = base + uiOrder.
-const UI_BASE_LAYER = 1000;
+
// Auto tolerance: a bitmap glyph still reads as pixel-exact within ±2% of 1:1.
const BITMAP_SCALE_EPSILON = 0.02;
diff --git a/sdk/src/wasm/constants.generated.ts b/sdk/src/wasm/constants.generated.ts
index 0a2b35be9..8a6fd284c 100644
--- a/sdk/src/wasm/constants.generated.ts
+++ b/sdk/src/wasm/constants.generated.ts
@@ -49,3 +49,6 @@ export const TILE_FLIP_V = 0x4000;
/** C++ `TILE_ID_MASK` in `src/esengine/tilemap/TilemapSystem.hpp`. */
export const TILE_ID_MASK = 0x1fff;
+
+/** C++ `UI_BASE_LAYER` in `src/esengine/renderer/plugins/UIElementPlugin.hpp`. */
+export const UI_BASE_LAYER = 1000;
diff --git a/sdk/tests/cpp-contract.test.ts b/sdk/tests/cpp-contract.test.ts
index e61040d50..8e0ad2e99 100644
--- a/sdk/tests/cpp-contract.test.ts
+++ b/sdk/tests/cpp-contract.test.ts
@@ -28,6 +28,7 @@ import { GRADIENT_LUT_SIZE } from '../src/particle/gradient';
import { ENTITY_INDEX_BITS, ENTITY_GEN_BITS } from '../src/types';
import { TILE_ID_MASK, TILE_FLIP_H, TILE_FLIP_V, TILE_FLIP_D } from '../src/tilemap/tileBits';
import { CHUNK_SIZE } from '../src/tilemap/chunkCodec';
+import { UI_BASE_LAYER } from '../src/wasm/constants.generated';
// EHT-generated twins (the authoritative C++ ES_ENUM values) + the module-local
// names the UI/physics modules publish them under.
@@ -168,14 +169,11 @@ describe('C++ contract: tilemap cell encoding (tilemap/TilemapSystem.hpp)', () =
});
describe('C++ contract: UI base layer (renderer/plugins/UIElementPlugin.hpp)', () => {
- it('UI_BASE_LAYER matches the TS text renderer', () => {
- // Not exported (module-private), so guard the source values directly:
- // the C++ plugin and the TS text plugin must agree on the UI layer base.
- const cpp = parseConst(readCpp('renderer/plugins/UIElementPlugin.hpp'), 'UI_BASE_LAYER');
- const tsSrc = readFileSync(resolve(__dirname, '../src/ui/text/plugin.ts'), 'utf8');
- const tsm = /UI_BASE_LAYER\s*=\s*(\d+)/.exec(stripComments(tsSrc));
- if (!tsm) throw new Error('TS UI_BASE_LAYER not found in ui/text/plugin.ts');
- expect(Number(tsm[1])).toBe(cpp);
+ it('UI_BASE_LAYER is generated from the header, not restated beside it', () => {
+ // It was declared twice — `const UI_BASE_LAYER = 1000` in the TS text
+ // renderer, with a comment saying it must match. Generated now, so this
+ // pin is a SECOND reader of the header rather than a guard on a copy.
+ expect(UI_BASE_LAYER).toBe(parseConst(readCpp('renderer/plugins/UIElementPlugin.hpp'), 'UI_BASE_LAYER'));
});
});
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 0981c97dd..49e83bc5c 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -3116,7 +3116,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "7e0589f085f150f6";
+static const char* kEsAbiLayoutHash = "97a5a526f33a8a4b";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/renderer/plugins/UIElementPlugin.hpp b/src/esengine/renderer/plugins/UIElementPlugin.hpp
index 67d4708b3..ef1819e02 100644
--- a/src/esengine/renderer/plugins/UIElementPlugin.hpp
+++ b/src/esengine/renderer/plugins/UIElementPlugin.hpp
@@ -4,6 +4,7 @@
#include "BatchPlugin.hpp"
#include "../../resource/TextureMetadata.hpp"
+#include "../../core/Reflection.hpp"
namespace esengine {
@@ -11,8 +12,10 @@ class UIElementPlugin : public BatchPlugin {
public:
void collect(RenderCollectContext& ctx) override;
-private:
- // UI draws above world content: its sort layer is offset past the world layer range.
+ // UI draws above world content: its sort layer is offset past the world
+ // layer range. The SDK's own text renderer puts quads at the same base, so
+ // it crosses — and a second spelling of it is two layers, not one.
+ ES_CONST()
static constexpr i32 UI_BASE_LAYER = 1000;
};
diff --git a/tools/contract-inventory.mjs b/tools/contract-inventory.mjs
index cce8f693e..8536b8975 100644
--- a/tools/contract-inventory.mjs
+++ b/tools/contract-inventory.mjs
@@ -36,7 +36,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { execFileSync } from 'node:child_process';
-import { FACTS, NOT_CONTRACT } from './lib/contractFacts.mjs';
+import { FACTS, NOT_CONTRACT, RE_EXPORTS } from './lib/contractFacts.mjs';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const JSON_OUT = process.argv.includes('--json');
@@ -206,10 +206,53 @@ if (existsSync(path.join(ROOT, PIN_FILE))) {
}
}
notes.push(`${titles.length} cross-language pin(s) in ${PIN_FILE}, each claimed by a fact.`);
+
+ /**
+ * Every side a verifier COMPARES has to be a node this list explains. The
+ * ledger said uiBaseLayer had one author while the pin read a second,
+ * hand-written declaration in the SDK — a fact with two authors, recorded
+ * as one, because nothing asked what the verifier was reading.
+ */
+ const declared = new Set(FACTS.flatMap((f) => [
+ ...f.authors.map((a) => a.path),
+ ...f.projections,
+ ...f.verification.flatMap((v) => v.compares ?? []),
+ ]).concat(Object.keys(RE_EXPORTS)));
+ const reads = readsOf(PIN_FILE);
+ for (const rel of reads) {
+ if (declared.has(rel)) continue;
+ findings.push(`GROUND: ${PIN_FILE} reads ${rel}, and no fact names it — as an author, as`
+ + ' a projection, or in the `compares` of the verification that reads it.');
+ }
+ // An excuse nobody uses is an excuse that stops being true.
+ for (const [rel, why] of Object.entries(RE_EXPORTS)) {
+ if (!reads.includes(rel)) {
+ findings.push(`RE_EXPORTS names ${rel} (${why}), which ${PIN_FILE} no longer reads.`);
+ }
+ }
} else {
findings.push(`GROUND: ${PIN_FILE} is gone; the cross-language pins it held are now unclaimed.`);
}
+/** Repo files a source names: an import, or a path handed to a reader. Resolved
+ * against the roots this repo's test helpers use, so a fragment counts too. */
+function readsOf(rel) {
+ const text = read(rel);
+ const bases = [path.dirname(rel), '', 'src/esengine'];
+ const out = new Set();
+ for (const m of text.matchAll(/'([^'\n]+)'/g)) {
+ const lit = m[1];
+ if (!lit.includes('/') || lit.startsWith('/')) continue;
+ for (const base of bases) {
+ for (const ext of ['', '.ts', '.hpp', '.cpp']) {
+ const at = path.normalize(path.join(base, lit) + ext);
+ if (tracked.includes(at)) out.add(at);
+ }
+ }
+ }
+ return [...out];
+}
+
// ── Say it ───────────────────────────────────────────────────────────────────
if (JSON_OUT) {
const shape = report.map((f) => ({
diff --git a/tools/lib/contractFacts.mjs b/tools/lib/contractFacts.mjs
index e535bec8f..244813796 100644
--- a/tools/lib/contractFacts.mjs
+++ b/tools/lib/contractFacts.mjs
@@ -228,14 +228,20 @@ export const FACTS = [
id: 'uiBaseLayer',
what: 'The layer number UI elements draw from, which orders them against the world.',
surface: 'runtime-wasm-abi',
+ // It was declared twice: this header, and `const UI_BASE_LAYER = 1000`
+ // in the SDK's text renderer with a comment saying it must match. The
+ // ledger recorded one author while the pin read both.
authors: [
- { path: 'src/esengine/renderer/plugins/UIElementPlugin.hpp', probe: /Layer/i, kind: 'semantic' },
+ { path: 'src/esengine/renderer/plugins/UIElementPlugin.hpp',
+ probe: /ES_CONST\(\)\s*\n\s*static constexpr i32 UI_BASE_LAYER/, kind: 'semantic' },
],
- projections: [],
+ projections: ['sdk/src/wasm/constants.generated.ts'],
verification: [
- { path: 'sdk/tests/cpp-contract.test.ts', how: 'test', probe: /UI base layer/ },
+ { path: 'sdk/tests/cpp-contract.test.ts', how: 'test', probe: /UI base layer/,
+ compares: ['src/esengine/renderer/plugins/UIElementPlugin.hpp',
+ 'sdk/src/wasm/constants.generated.ts'] },
],
- digest: null,
+ digest: { name: 'eht-abi-layout-hash', path: 'tools/eht/constants.py', probe: /CONST / },
},
{
id: 'shaderSources',
@@ -280,6 +286,31 @@ export const FACTS = [
},
];
+/**
+ * Modules a cross-language pin reads because they RE-EXPORT the generated value
+ * it compares — one publishing name, not a second declaration. Named so a file
+ * a verifier reads is never one the ledger pretends is not there; a hand-written
+ * twin cannot hide among them, because it would owe an entry saying it is one.
+ */
+export const RE_EXPORTS = {
+ 'sdk/src/animation/Easing.ts': 'the tween easing enum',
+ 'sdk/src/animation/TweenTypes.ts': 'tween state and loop mode',
+ 'sdk/src/animation/Tween.ts': 'the tween target enum',
+ 'sdk/src/particle/gradient.ts': 'the particle colour LUT size',
+ 'sdk/src/types.ts': 'the packed entity split',
+ 'sdk/src/tilemap/tileBits.ts': 'the cell encoding',
+ 'sdk/src/tilemap/chunkCodec.ts': 'the chunk stride',
+ 'sdk/src/tilemap/tileGeometry.ts': 'the tilemap orientation enum',
+ 'sdk/src/physics/PhysicsComponents.ts': 'the body type enum',
+ 'sdk/src/ui/core/ui-node.ts': 'the UI position and align enums',
+ 'sdk/src/ui/core/ui-visual.ts': 'the UI visual, fill method and fill origin enums',
+ 'sdk/src/ui/core/ui-mask.ts': 'the mask mode enum',
+ 'sdk/src/ui/core/ui-scroll.ts': 'the scroll movement enum',
+ 'sdk/src/ui/core/text.ts': 'the text align enum',
+ 'sdk/src/ui/layout/flex.ts': 'the flex enums',
+ 'sdk/src/ecs/component.ts': 'the particle easing enum, on a component field',
+};
+
/**
* Generated artifacts that are NOT a projection of a contract fact, and why.
* Being generated is not the same as being derived from a contract: a measured