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(gates): a TS enum that restates a C++ one is held to it
esengine06ab1bd836db
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e4eaaa141..e9594a40d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -116,6 +116,26 @@ published separately; it ships inside the editor.nothing. The order is the library's now; what to say when the engine is notbuilt stays with each caller, which is the half that is actually theirs.+- **`check-enum-twins` — nine TS enums that restate a C++ one are held to it, and+ a machine says which ones nobody was holding.** These cross the boundary as+ bare numbers, so a drift raises nothing: the SDK writes 1 where the renderer+ reads 2 and the picture is merely wrong. `cpp-contract` pinned the seven+ somebody remembered, which is the problem with a list somebody remembers.++ Nine more were not on it. `MaskMode`, `ScrollMovement` and the five flex enums+ (`FlexDirection`, `FlexWrap`, `JustifyContent`, `AlignItems`, `AlignContent`)+ are re-exports of the generated enum now, so there is one declaration and the+ test pins its IDENTITY — a copy cannot come back looking equal. `TileOrientation`+ is the generated `TilemapOrientation` under its own name; its comment used to+ promise the values matched, which is a contract with nothing keeping it.++ `TextAlign` stays its own declaration and pays for it with a value pin: it is+ `@public`, the generated enums carry no tier, and re-exporting it would quietly+ demote a frozen promise. All nine agreed today — this is about the day they+ stop. The gate catches both shapes that hid them: a declaration with a+ generated enum's name, and a doc that promises to match one. Sabotage-verified+ on both, and on the identity pin the re-exports rest on.+- **The output curve's number is worked out in one place.** `OutputTransform` isa string union at the API and a number at the wasm boundary, and thetranslation — `'aces' ? 1 : 0` — was written at both call sites. A third curvediff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 306f10f4b..cfff40c6f 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -242,14 +242,22 @@ static new <Ctx = unknown>(): AiRegistry<Ctx>static prototype: AiRegistry<any>```-## AlignContent — type @experimental+## AlignContent — enum @experimental```-(typeof AlignContent)[keyof typeof AlignContent]+Center = 1+End = 2+SpaceAround = 5+SpaceBetween = 4+Start = 0+Stretch = 3```-## AlignItems — type @experimental+## AlignItems — enum @experimental```-(typeof AlignItems)[keyof typeof AlignItems]+Center = 1+End = 2+Start = 0+Stretch = 3```## AlignSelf — enum @experimental@@ -3236,14 +3244,18 @@ padding: Paddingwrap: FlexWrap```-## FlexDirection — type @experimental+## FlexDirection — enum @experimental```-(typeof FlexDirection)[keyof typeof FlexDirection]+Column = 1+ColumnReverse = 3+Row = 0+RowReverse = 2```-## FlexWrap — type @experimental+## FlexWrap — enum @experimental```-(typeof FlexWrap)[keyof typeof FlexWrap]+NoWrap = 0+Wrap = 1```## FocusManager — const @experimental@@ -3957,9 +3969,14 @@ type: stringdata: T```-## JustifyContent — type @experimental+## JustifyContent — enum @experimental```-(typeof JustifyContent)[keyof typeof JustifyContent]+Center = 1+End = 2+SpaceAround = 4+SpaceBetween = 3+SpaceEvenly = 5+Start = 0```## Key — const @public@@ -4403,9 +4420,10 @@ properties: Record<string, string>type: string```-## MaskMode — type @experimental+## MaskMode — enum @experimental```-(typeof MaskMode)[keyof typeof MaskMode]+Scissor = 0+Stencil = 1```## Material — const @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 4bda2fae2..6f3aea43a 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -242,14 +242,22 @@ static new <Ctx = unknown>(): AiRegistry<Ctx>static prototype: AiRegistry<any>```-## AlignContent — type @experimental+## AlignContent — enum @experimental```-(typeof AlignContent)[keyof typeof AlignContent]+Center = 1+End = 2+SpaceAround = 5+SpaceBetween = 4+Start = 0+Stretch = 3```-## AlignItems — type @experimental+## AlignItems — enum @experimental```-(typeof AlignItems)[keyof typeof AlignItems]+Center = 1+End = 2+Start = 0+Stretch = 3```## AlignSelf — enum @experimental@@ -3244,14 +3252,18 @@ padding: Paddingwrap: FlexWrap```-## FlexDirection — type @experimental+## FlexDirection — enum @experimental```-(typeof FlexDirection)[keyof typeof FlexDirection]+Column = 1+ColumnReverse = 3+Row = 0+RowReverse = 2```-## FlexWrap — type @experimental+## FlexWrap — enum @experimental```-(typeof FlexWrap)[keyof typeof FlexWrap]+NoWrap = 0+Wrap = 1```## FocusManager — const @experimental@@ -3965,9 +3977,14 @@ type: stringdata: T```-## JustifyContent — type @experimental+## JustifyContent — enum @experimental```-(typeof JustifyContent)[keyof typeof JustifyContent]+Center = 1+End = 2+SpaceAround = 4+SpaceBetween = 3+SpaceEvenly = 5+Start = 0```## Key — const @public@@ -4411,9 +4428,10 @@ properties: Record<string, string>type: string```-## MaskMode — type @experimental+## MaskMode — enum @experimental```-(typeof MaskMode)[keyof typeof MaskMode]+Scissor = 0+Stencil = 1```## Material — const @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 39b8220ce..91d2ce474 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -237,14 +237,22 @@ static new <Ctx = unknown>(): AiRegistry<Ctx>static prototype: AiRegistry<any>```-## AlignContent — type @experimental+## AlignContent — enum @experimental```-(typeof AlignContent)[keyof typeof AlignContent]+Center = 1+End = 2+SpaceAround = 5+SpaceBetween = 4+Start = 0+Stretch = 3```-## AlignItems — type @experimental+## AlignItems — enum @experimental```-(typeof AlignItems)[keyof typeof AlignItems]+Center = 1+End = 2+Start = 0+Stretch = 3```## AlignSelf — enum @experimental@@ -3231,14 +3239,18 @@ padding: Paddingwrap: FlexWrap```-## FlexDirection — type @experimental+## FlexDirection — enum @experimental```-(typeof FlexDirection)[keyof typeof FlexDirection]+Column = 1+ColumnReverse = 3+Row = 0+RowReverse = 2```-## FlexWrap — type @experimental+## FlexWrap — enum @experimental```-(typeof FlexWrap)[keyof typeof FlexWrap]+NoWrap = 0+Wrap = 1```## FocusManager — const @experimental@@ -3952,9 +3964,14 @@ type: stringdata: T```-## JustifyContent — type @experimental+## JustifyContent — enum @experimental```-(typeof JustifyContent)[keyof typeof JustifyContent]+Center = 1+End = 2+SpaceAround = 4+SpaceBetween = 3+SpaceEvenly = 5+Start = 0```## Key — const @public@@ -4398,9 +4415,10 @@ properties: Record<string, string>type: string```-## MaskMode — type @experimental+## MaskMode — enum @experimental```-(typeof MaskMode)[keyof typeof MaskMode]+Scissor = 0+Stencil = 1```## Material — const @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 6c5aedad6..dbf9a0ecd 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -237,14 +237,22 @@ static new <Ctx = unknown>(): AiRegistry<Ctx>static prototype: AiRegistry<any>```-## AlignContent — type @experimental+## AlignContent — enum @experimental```-(typeof AlignContent)[keyof typeof AlignContent]+Center = 1+End = 2+SpaceAround = 5+SpaceBetween = 4+Start = 0+Stretch = 3```-## AlignItems — type @experimental+## AlignItems — enum @experimental```-(typeof AlignItems)[keyof typeof AlignItems]+Center = 1+End = 2+Start = 0+Stretch = 3```## AlignSelf — enum @experimental@@ -3231,14 +3239,18 @@ padding: Paddingwrap: FlexWrap```-## FlexDirection — type @experimental+## FlexDirection — enum @experimental```-(typeof FlexDirection)[keyof typeof FlexDirection]+Column = 1+ColumnReverse = 3+Row = 0+RowReverse = 2```-## FlexWrap — type @experimental+## FlexWrap — enum @experimental```-(typeof FlexWrap)[keyof typeof FlexWrap]+NoWrap = 0+Wrap = 1```## FocusManager — const @experimental@@ -3952,9 +3964,14 @@ type: stringdata: T```-## JustifyContent — type @experimental+## JustifyContent — enum @experimental```-(typeof JustifyContent)[keyof typeof JustifyContent]+Center = 1+End = 2+SpaceAround = 4+SpaceBetween = 3+SpaceEvenly = 5+Start = 0```## Key — const @public@@ -4398,9 +4415,10 @@ properties: Record<string, string>type: string```-## MaskMode — type @experimental+## MaskMode — enum @experimental```-(typeof MaskMode)[keyof typeof MaskMode]+Scissor = 0+Stencil = 1```## Material — const @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex f2cec3645..d2ed49776 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -237,14 +237,22 @@ static new <Ctx = unknown>(): AiRegistry<Ctx>static prototype: AiRegistry<any>```-## AlignContent — type @experimental+## AlignContent — enum @experimental```-(typeof AlignContent)[keyof typeof AlignContent]+Center = 1+End = 2+SpaceAround = 5+SpaceBetween = 4+Start = 0+Stretch = 3```-## AlignItems — type @experimental+## AlignItems — enum @experimental```-(typeof AlignItems)[keyof typeof AlignItems]+Center = 1+End = 2+Start = 0+Stretch = 3```## AlignSelf — enum @experimental@@ -3231,14 +3239,18 @@ padding: Paddingwrap: FlexWrap```-## FlexDirection — type @experimental+## FlexDirection — enum @experimental```-(typeof FlexDirection)[keyof typeof FlexDirection]+Column = 1+ColumnReverse = 3+Row = 0+RowReverse = 2```-## FlexWrap — type @experimental+## FlexWrap — enum @experimental```-(typeof FlexWrap)[keyof typeof FlexWrap]+NoWrap = 0+Wrap = 1```## FocusManager — const @experimental@@ -3959,9 +3971,14 @@ type: stringdata: T```-## JustifyContent — type @experimental+## JustifyContent — enum @experimental```-(typeof JustifyContent)[keyof typeof JustifyContent]+Center = 1+End = 2+SpaceAround = 4+SpaceBetween = 3+SpaceEvenly = 5+Start = 0```## Key — const @public@@ -4405,9 +4422,10 @@ properties: Record<string, string>type: string```-## MaskMode — type @experimental+## MaskMode — enum @experimental```-(typeof MaskMode)[keyof typeof MaskMode]+Scissor = 0+Stencil = 1```## Material — const @experimentaldiff --git a/sdk/src/tilemap/tileGeometry.ts b/sdk/src/tilemap/tileGeometry.tsindex fbfc5eef1..0b2f3d10b 100644--- a/sdk/src/tilemap/tileGeometry.ts+++ b/sdk/src/tilemap/tileGeometry.ts@@ -17,13 +17,10 @@* and shaped ghost draw the true cell boundary. One geometry seam drives both.*/-/** Grid orientation, values matching the C++ TilemapOrientation / tilemap::GridType. */-export enum TileOrientation {- Orthogonal = 0,- Isometric = 1,- Staggered = 2,- Hexagonal = 3,-}+// Grid orientation, single-sourced from the C++ ES_ENUM via the generated module:+// the number a cell placement switches on is the number the engine's grid uses.+export { TilemapOrientation as TileOrientation } from '../wasm/wasm.generated';+import { TilemapOrientation as TileOrientation } from '../wasm/wasm.generated';/** The layout inputs a cell placement needs — a subset of the TilemapLayer component. */export interface TileGridParams {diff --git a/sdk/src/ui/core/ui-mask.ts b/sdk/src/ui/core/ui-mask.tsindex 7e7a757a1..065067e01 100644--- a/sdk/src/ui/core/ui-mask.ts+++ b/sdk/src/ui/core/ui-mask.ts@@ -2,11 +2,11 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { defineBuiltin } from '../../ecs/component';-export const MaskMode = {- Scissor: 0,- Stencil: 1,-} as const;-export type MaskMode = (typeof MaskMode)[keyof typeof MaskMode];+// Scissor clips to an axis-aligned rectangle and costs nothing; Stencil clips to+// the mask's own shape. Single-sourced from the C++ ES_ENUM via the generated+// module, so the number this writes is the number the renderer reads.+export { MaskMode } from '../../wasm/wasm.generated';+import { MaskMode } from '../../wasm/wasm.generated';export interface UIMaskData {enabled: boolean;diff --git a/sdk/src/ui/core/ui-scroll.ts b/sdk/src/ui/core/ui-scroll.tsindex c7595758f..851e6304d 100644--- a/sdk/src/ui/core/ui-scroll.ts+++ b/sdk/src/ui/core/ui-scroll.ts@@ -2,13 +2,11 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { defineBuiltin } from '../../ecs/component';-export const ScrollMovement = {- /** Stop dead at the ends. */- Clamped: 0,- /** Overshoot and spring back — the touch-UI feel. */- Elastic: 1,-} as const;-export type ScrollMovement = (typeof ScrollMovement)[keyof typeof ScrollMovement];+// Clamped stops dead at the ends; Elastic overshoots and springs back, which is+// the touch-UI feel. Single-sourced from the C++ ES_ENUM via the generated+// module, so the number this writes is the number the scroller reads.+export { ScrollMovement } from '../../wasm/wasm.generated';+import { ScrollMovement } from '../../wasm/wasm.generated';/*** A scrollable viewport, authored in the scene rather than constructed in code.diff --git a/sdk/src/ui/layout/flex.ts b/sdk/src/ui/layout/flex.tsindex af9e8b427..76fae95d9 100644--- a/sdk/src/ui/layout/flex.ts+++ b/sdk/src/ui/layout/flex.ts@@ -6,20 +6,15 @@ import type { Padding } from '../../wasm/wasm.generated';// -- FlexContainer -------------------------------------------------------------export const FlexDirection = { Row: 0, Column: 1, RowReverse: 2, ColumnReverse: 3 } as const;-export type FlexDirection = (typeof FlexDirection)[keyof typeof FlexDirection];--export const FlexWrap = { NoWrap: 0, Wrap: 1 } as const;-export type FlexWrap = (typeof FlexWrap)[keyof typeof FlexWrap];--export const JustifyContent = { Start: 0, Center: 1, End: 2, SpaceBetween: 3, SpaceAround: 4, SpaceEvenly: 5 } as const;-export type JustifyContent = (typeof JustifyContent)[keyof typeof JustifyContent];--export const AlignItems = { Start: 0, Center: 1, End: 2, Stretch: 3 } as const;-export type AlignItems = (typeof AlignItems)[keyof typeof AlignItems];--export const AlignContent = { Start: 0, Center: 1, End: 2, Stretch: 3, SpaceBetween: 4, SpaceAround: 5 } as const;-export type AlignContent = (typeof AlignContent)[keyof typeof AlignContent];+// The five flex enums, single-sourced from the C++ ES_ENUMs via the generated+// module. Yoga reads the C++ side, so a second spelling of these numbers is a+// layout that is merely wrong rather than an error anything raises.+export {+ FlexDirection, FlexWrap, JustifyContent, AlignItems, AlignContent,+} from '../../wasm/wasm.generated';+import {+ FlexDirection, FlexWrap, JustifyContent, AlignItems, AlignContent,+} from '../../wasm/wasm.generated';export interface FlexContainerData {direction: FlexDirection;diff --git a/sdk/tests/cpp-contract.test.ts b/sdk/tests/cpp-contract.test.tsindex 89b598b77..efc620548 100644--- a/sdk/tests/cpp-contract.test.ts+++ b/sdk/tests/cpp-contract.test.ts@@ -35,6 +35,13 @@ import * as gen from '../src/wasm/wasm.generated';import { BodyType } from '../src/physics/PhysicsComponents';import { UIPositionType, AlignSelf } from '../src/ui/core/ui-node';import { UIVisualType, FillMethod, FillOrigin } from '../src/ui/core/ui-visual';+import { MaskMode } from '../src/ui/core/ui-mask';+import { ScrollMovement } from '../src/ui/core/ui-scroll';+import { TileOrientation } from '../src/tilemap/tileGeometry';+import { TextAlign } from '../src/ui/core/text';+import {+ FlexDirection, FlexWrap, JustifyContent, AlignItems, AlignContent,+} from '../src/ui/layout/flex';import { ParticleEasing } from '../src/ecs/component';// Repo root is two levels up from sdk/tests/ (mirrors the spine integration tests).@@ -197,6 +204,14 @@ describe('C++ contract: module-published enums ARE their EHT-generated twin', ()['FillMethod', FillMethod, gen.UIFillMethod],['FillOrigin', FillOrigin, gen.UIFillOrigin],['ParticleEasing', ParticleEasing, gen.ParticleEasing],+ ['MaskMode', MaskMode, gen.MaskMode],+ ['ScrollMovement', ScrollMovement, gen.ScrollMovement],+ ['TileOrientation', TileOrientation, gen.TilemapOrientation],+ ['FlexDirection', FlexDirection, gen.FlexDirection],+ ['FlexWrap', FlexWrap, gen.FlexWrap],+ ['JustifyContent', JustifyContent, gen.JustifyContent],+ ['AlignItems', AlignItems, gen.AlignItems],+ ['AlignContent', AlignContent, gen.AlignContent],];for (const [label, published, generated] of cases) {it(`${label} is a re-export of the generated enum`, () => {@@ -204,3 +219,14 @@ describe('C++ contract: module-published enums ARE their EHT-generated twin', ()});}});++describe('C++ contract: enums that must stay their own declaration', () => {+ // TextAlign cannot be a re-export: it is @public, and the generated enums+ // carry no tier, so re-exporting would quietly demote a frozen promise. It+ // keeps its own doc and tag, and pays for that with a VALUE pin.+ it('TextAlign has the values the generated enum does', () => {+ expect({ ...TextAlign }).toEqual({+ Left: gen.TextAlign.Left, Center: gen.TextAlign.Center, Right: gen.TextAlign.Right,+ });+ });+});diff --git a/tools/check-enum-twins.mjs b/tools/check-enum-twins.mjsnew file mode 100644index 000000000..289a7b0e9--- /dev/null+++ b/tools/check-enum-twins.mjs@@ -0,0 +1,84 @@+#!/usr/bin/env node+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file check-enum-twins.mjs — a TS enum that restates a C++ one is held to it.+ *+ * The engine's enums cross as bare numbers, so a TS spelling that drifts from the+ * C++ one does not fail: it writes 1 where the renderer reads 2, and the picture+ * is merely wrong. `cpp-contract.test.ts` pins the ones somebody remembered —+ * which is the problem, because it is a list somebody remembers.+ *+ * Two shapes are caught, both found by hand before this existed:+ * - a declaration with the SAME NAME as a generated enum (`MaskMode`,+ * `ScrollMovement`, `TextAlign`);+ * - a doc that PROMISES to match one ("values matching the C+++ * TilemapOrientation"), which is a contract with nothing keeping it.+ *+ * Either way it owes a pin in `cpp-contract.test.ts` — as a re-export whose+ * identity is asserted, or, where the symbol must keep its own tier tag, as a+ * value comparison.+ *+ * node tools/check-enum-twins.mjs+ */+import { readFileSync, existsSync } from 'node:fs';+import { execFileSync } from 'node:child_process';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const GENERATED = path.join(ROOT, 'sdk/src/wasm/wasm.generated.ts');+const CONTRACT = path.join(ROOT, 'sdk/tests/cpp-contract.test.ts');++for (const [what, file] of [['the generated twins', GENERATED], ['the contract test', CONTRACT]]) {+ if (existsSync(file)) continue;+ // Loud: with either half missing this can only report "nothing to hold",+ // which reads exactly like "everything is held".+ console.error(`check-enum-twins: ${what} is not here (${path.relative(ROOT, file)}) — cannot judge.`);+ process.exit(1);+}++const generated = readFileSync(GENERATED, 'utf8');+const GEN_ENUMS = new Set([...generated.matchAll(/^export enum (\w+) \{/gm)].map((m) => m[1]));+const contract = readFileSync(CONTRACT, 'utf8');+const pinned = (name) => new RegExp(`\\b${name}\\b`).test(contract);++/** A doc that says this must agree with something, which only a check can. */+const PROMISE = /\b(?:matching|matches|must match|mirrors|same as|kept in sync)\b/i;++const sources = execFileSync('git', ['ls-files', 'sdk/src'], { cwd: ROOT, encoding: 'utf8' })+ .split('\n').filter((f) => f.endsWith('.ts') && !f.includes('.generated.'));++const problems = [];+for (const rel of sources) {+ const abs = path.join(ROOT, rel);+ if (!existsSync(abs)) continue;+ const text = readFileSync(abs, 'utf8');+ const lines = text.split('\n');++ for (const m of text.matchAll(/^export (?:enum|const) (\w+)\b/gm)) {+ const name = m[1];+ // A re-export is the single source, not a restatement of it.+ if (new RegExp(`^export \\{[^}]*\\b${name}\\b[^}]*\\} from`, 'm').test(text)) continue;+ if (!GEN_ENUMS.has(name) || pinned(name)) continue;+ problems.push(`${rel}: ${name} has the name of a generated C++ enum and nothing holds them equal`);+ }++ for (const [i, line] of lines.entries()) {+ if (!PROMISE.test(line)) continue;+ for (const gen of GEN_ENUMS) {+ if (!new RegExp(`\\b${gen}\\b`).test(line) || pinned(gen)) continue;+ problems.push(`${rel}:${i + 1}: promises to match the C++ ${gen}, and nothing checks that`);+ }+ }+}++if (problems.length) {+ console.error('check-enum-twins: a number that crosses to C++ is restated and unheld.\n');+ for (const p of [...new Set(problems)]) console.error(` ${p}`);+ console.error('\nRe-export it from sdk/src/wasm/wasm.generated and pin the identity in'+ + ' sdk/tests/cpp-contract.test.ts, or — where the symbol must keep its own tier tag —'+ + ' keep the declaration and pin its VALUES there.');+ process.exit(1);+}+console.log(`check-enum-twins: ${GEN_ENUMS.size} generated C++ enums, every TS restatement of one held to it.`);diff --git a/tools/gates.mjs b/tools/gates.mjsindex c3a8ab8f7..eac759ae3 100644--- a/tools/gates.mjs+++ b/tools/gates.mjs@@ -176,6 +176,10 @@ export const GATES = [// the tags; this holds a tier above experimental against the same evidence// check-freeze-bar asks of a @public symbol.{ id: 'tier-bar', run: 'node tools/check-tier-bar.mjs' },+ // A TS enum that restates a C++ one crosses as a bare number: drift is not an+ // error, it is a picture that is merely wrong. cpp-contract pins the ones+ // somebody remembered; this says which ones nobody did.+ { id: 'enum-twins', run: 'node tools/check-enum-twins.mjs' },{ id: 'examples', run: 'node build-tools/cli.js check-examples' },{ id: 'documents', run: 'node build-tools/cli.js validate-documents' },];