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
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.mdindex 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 @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 @experimentaldiff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex 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 ofdiff --git a/sdk/src/ui/text/plugin.ts b/sdk/src/ui/text/plugin.tsindex 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/helpersimport { 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.tsindex 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.tsindex 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.cppindex 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.hppindex 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.mjsindex 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.mjsindex 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