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(eht): an enum says how strongly it is promised
esengine3791c5478738
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3a9399629..cf03b2e3b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -116,6 +116,21 @@ 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.+- **An enum can say how strongly it is promised, and ten now do.** Typing those+ fields made a hole visible that was always there: a `@beta` component whose+ field values are governed by an enum nobody promised. `ES_ENUM(stability=)`+ answers it at the C++ declaration, the way `ES_COMPONENT(stability=)` already+ did — untagged still means `experimental`. `check-enum-twins` refuses a shape+ promised at beta or better whose vocabulary is weaker.++ Chasing it turned up types a creator could read on the surface and not name:+ `TilemapLayerData.orientation` said `TilemapOrientation`, which the SDK+ published only under the alias `TileOrientation`; `staggerAxis` and+ `staggerIndex` named enums exported nowhere at all; so did `UIVisualData.fit`.+ The alias is gone, the three are exported, and the editor — which restated+ `STAGGER_AXIS_Y = 0` and three more of the same numbers under a comment saying+ they match C++ — reads the engine's enums now.+- **A component field that IS an enum is typed as one — 33 of them were `number`.**The generator had the answer and threw it away: `if is_enum(t): return 'number'`,with `ES_PROPERTY(enum=)` naming the enum for the fields stored as a `u8`. Sodiff --git a/desktop b/desktopindex 49c9e5ed5..f0d4546ee 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 49c9e5ed5af00339e652414b69f428e2a42da41e+Subproject commit f0d4546ee669bf1e02619a0c140d955b909df70bdiff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex bfdbcaa56..174c56170 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -2,11 +2,11 @@"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.","counts": {"public": 113,- "beta": 76,- "experimental": 1648,+ "beta": 89,+ "experimental": 1638,"deprecated": 3},- "total": 1837,+ "total": 1840,"subsystems": [{"id": "ecs",@@ -1860,6 +1860,54 @@"minigame"]},+ {+ "name": "ClearFlags",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "EmitterShape",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "FillMethod",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "FillOrigin",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "GraphNodeType","kind": "type",@@ -2024,6 +2072,18 @@"minigame"]},+ {+ "name": "ParticleEasing",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "ParticleEmitter","kind": "const",@@ -2123,6 +2183,18 @@"minigame"]},+ {+ "name": "ProjectionType",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "SceneConfig","kind": "interface",@@ -2195,6 +2267,18 @@"minigame"]},+ {+ "name": "SimulationSpace",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "SpawnOverride","kind": "type",@@ -2268,6 +2352,18 @@"minigame"]},+ {+ "name": "SubEmitterTrigger",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "ThemeColors","kind": "interface",@@ -2304,6 +2400,42 @@"minigame"]},+ {+ "name": "TilemapOrientation",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "TilemapStaggerAxis",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "TilemapStaggerIndex",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "TouchPoint","kind": "interface",@@ -2400,6 +2532,30 @@"minigame"]},+ {+ "name": "UIVisualFit",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "UIVisualType",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "acquireWebGPUDevice","kind": "function",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 8db772f58..7b34140ba 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 69 beta · 1511 experimental · 3 deprecated+Symbols: 113 public · 82 beta · 1501 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1996,7 +1996,7 @@ radius: numberrestitution: number```-## ClearFlags — enum @experimental+## ClearFlags — enum @beta```Color = 1ColorAndDepth = 3@@ -2936,7 +2936,7 @@ wasm: Uint8Array<ArrayBufferLike>Partial<Record<SideModuleId, EmbeddedSideModuleEntry>>```-## EmitterShape — enum @experimental+## EmitterShape — enum @beta```Circle = 1Cone = 3@@ -3157,7 +3157,7 @@ tooltip: string | undefinedunit: string | undefined```-## FillMethod — enum @experimental+## FillMethod — enum @beta```Horizontal = 0Radial180 = 4@@ -3166,7 +3166,7 @@ Radial90 = 3Vertical = 1```-## FillOrigin — enum @experimental+## FillOrigin — enum @beta```Bottom = 2Left = 0@@ -5173,7 +5173,7 @@ static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPIstatic prototype: ParticleAPI```-## ParticleEasing — enum @experimental+## ParticleEasing — enum @beta```EaseIn = 1EaseInOut = 3@@ -6133,7 +6133,7 @@ value: number | undefinedworld: World```-## ProjectionType — enum @experimental+## ProjectionType — enum @beta```Orthographic = 1Perspective = 0@@ -7200,7 +7200,7 @@ subscribe: (fn: (value: T) => void) => () => voidupdate: (fn: (prev: T) => T) => void```-## SimulationSpace — enum @experimental+## SimulationSpace — enum @beta```Local = 1World = 0@@ -7606,7 +7606,7 @@ toDeactivate: string[]'unload' | 'sleep'```-## SubEmitterTrigger — enum @experimental+## SubEmitterTrigger — enum @beta```Birth = 1Death = 0@@ -8164,14 +8164,6 @@ tileHeight: numbertileWidth: number```-## TileOrientation — enum @experimental-```-Hexagonal = 3-Isometric = 1-Orthogonal = 0-Staggered = 2-```-## TileStamp — interface @experimental```cells: number[]@@ -8269,6 +8261,14 @@ visible: boolean{ _bind(fn: ApplyTilesetRefs | null): void; setLayerTilesets(entity: number, refs: readonly string[]): void; }```+## TilemapOrientation — enum @beta+```+Hexagonal = 3+Isometric = 1+Orthogonal = 0+Staggered = 2+```+## TilemapPlugin — class @experimental```build: (app: App) => void@@ -8279,6 +8279,18 @@ static new (): TilemapPluginstatic prototype: TilemapPlugin```+## TilemapStaggerAxis — enum @beta+```+X = 1+Y = 0+```++## TilemapStaggerIndex — enum @beta+```+Even = 1+Odd = 0+```+## Tilemaps — const @experimental```ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; extrude?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>@@ -9005,6 +9017,13 @@ uvScale: Vec2visualType: UIVisualType```+## UIVisualFit — enum @beta+```+Contain = 1+Cover = 2+Fill = 0+```+## UIVisualInit — interface @experimental```color: { r: number; g: number; b: number; a: number; } | undefined@@ -9022,7 +9041,7 @@ uvScale: Vec2 | undefinedvisualType: UIVisualType | undefined```-## UIVisualType — enum @experimental+## UIVisualType — enum @beta```Filled = 5Image = 2diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 897f37c4c..bbfb21306 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 74 beta · 1530 experimental · 3 deprecated+Symbols: 113 public · 87 beta · 1520 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1996,7 +1996,7 @@ radius: numberrestitution: number```-## ClearFlags — enum @experimental+## ClearFlags — enum @beta```Color = 1ColorAndDepth = 3@@ -2944,7 +2944,7 @@ wasm: Uint8Array<ArrayBufferLike>Partial<Record<SideModuleId, EmbeddedSideModuleEntry>>```-## EmitterShape — enum @experimental+## EmitterShape — enum @beta```Circle = 1Cone = 3@@ -3165,7 +3165,7 @@ tooltip: string | undefinedunit: string | undefined```-## FillMethod — enum @experimental+## FillMethod — enum @beta```Horizontal = 0Radial180 = 4@@ -3174,7 +3174,7 @@ Radial90 = 3Vertical = 1```-## FillOrigin — enum @experimental+## FillOrigin — enum @beta```Bottom = 2Left = 0@@ -5356,7 +5356,7 @@ static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPIstatic prototype: ParticleAPI```-## ParticleEasing — enum @experimental+## ParticleEasing — enum @beta```EaseIn = 1EaseInOut = 3@@ -6316,7 +6316,7 @@ value: number | undefinedworld: World```-## ProjectionType — enum @experimental+## ProjectionType — enum @beta```Orthographic = 1Perspective = 0@@ -7393,7 +7393,7 @@ subscribe: (fn: (value: T) => void) => () => voidupdate: (fn: (prev: T) => T) => void```-## SimulationSpace — enum @experimental+## SimulationSpace — enum @beta```Local = 1World = 0@@ -7799,7 +7799,7 @@ toDeactivate: string[]'unload' | 'sleep'```-## SubEmitterTrigger — enum @experimental+## SubEmitterTrigger — enum @beta```Birth = 1Death = 0@@ -8357,14 +8357,6 @@ tileHeight: numbertileWidth: number```-## TileOrientation — enum @experimental-```-Hexagonal = 3-Isometric = 1-Orthogonal = 0-Staggered = 2-```-## TileStamp — interface @experimental```cells: number[]@@ -8462,6 +8454,14 @@ visible: boolean{ _bind(fn: ApplyTilesetRefs | null): void; setLayerTilesets(entity: number, refs: readonly string[]): void; }```+## TilemapOrientation — enum @beta+```+Hexagonal = 3+Isometric = 1+Orthogonal = 0+Staggered = 2+```+## TilemapPlugin — class @experimental```build: (app: App) => void@@ -8472,6 +8472,18 @@ static new (): TilemapPluginstatic prototype: TilemapPlugin```+## TilemapStaggerAxis — enum @beta+```+X = 1+Y = 0+```++## TilemapStaggerIndex — enum @beta+```+Even = 1+Odd = 0+```+## Tilemaps — const @experimental```ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; extrude?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>@@ -9198,6 +9210,13 @@ uvScale: Vec2visualType: UIVisualType```+## UIVisualFit — enum @beta+```+Contain = 1+Cover = 2+Fill = 0+```+## UIVisualInit — interface @experimental```color: { r: number; g: number; b: number; a: number; } | undefined@@ -9215,7 +9234,7 @@ uvScale: Vec2 | undefinedvisualType: UIVisualType | undefined```-## UIVisualType — enum @experimental+## UIVisualType — enum @beta```Filled = 5Image = 2diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex f022127ae..9464c9264 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 71 beta · 1510 experimental · 3 deprecated+Symbols: 113 public · 84 beta · 1500 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1991,7 +1991,7 @@ radius: numberrestitution: number```-## ClearFlags — enum @experimental+## ClearFlags — enum @beta```Color = 1ColorAndDepth = 3@@ -2931,7 +2931,7 @@ wasm: Uint8Array<ArrayBufferLike>Partial<Record<SideModuleId, EmbeddedSideModuleEntry>>```-## EmitterShape — enum @experimental+## EmitterShape — enum @beta```Circle = 1Cone = 3@@ -3152,7 +3152,7 @@ tooltip: string | undefinedunit: string | undefined```-## FillMethod — enum @experimental+## FillMethod — enum @beta```Horizontal = 0Radial180 = 4@@ -3161,7 +3161,7 @@ Radial90 = 3Vertical = 1```-## FillOrigin — enum @experimental+## FillOrigin — enum @beta```Bottom = 2Left = 0@@ -5168,7 +5168,7 @@ static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPIstatic prototype: ParticleAPI```-## ParticleEasing — enum @experimental+## ParticleEasing — enum @beta```EaseIn = 1EaseInOut = 3@@ -6128,7 +6128,7 @@ value: number | undefinedworld: World```-## ProjectionType — enum @experimental+## ProjectionType — enum @beta```Orthographic = 1Perspective = 0@@ -7195,7 +7195,7 @@ subscribe: (fn: (value: T) => void) => () => voidupdate: (fn: (prev: T) => T) => void```-## SimulationSpace — enum @experimental+## SimulationSpace — enum @beta```Local = 1World = 0@@ -7601,7 +7601,7 @@ toDeactivate: string[]'unload' | 'sleep'```-## SubEmitterTrigger — enum @experimental+## SubEmitterTrigger — enum @beta```Birth = 1Death = 0@@ -8159,14 +8159,6 @@ tileHeight: numbertileWidth: number```-## TileOrientation — enum @experimental-```-Hexagonal = 3-Isometric = 1-Orthogonal = 0-Staggered = 2-```-## TileStamp — interface @experimental```cells: number[]@@ -8264,6 +8256,14 @@ visible: boolean{ _bind(fn: ApplyTilesetRefs | null): void; setLayerTilesets(entity: number, refs: readonly string[]): void; }```+## TilemapOrientation — enum @beta+```+Hexagonal = 3+Isometric = 1+Orthogonal = 0+Staggered = 2+```+## TilemapPlugin — class @experimental```build: (app: App) => void@@ -8274,6 +8274,18 @@ static new (): TilemapPluginstatic prototype: TilemapPlugin```+## TilemapStaggerAxis — enum @beta+```+X = 1+Y = 0+```++## TilemapStaggerIndex — enum @beta+```+Even = 1+Odd = 0+```+## Tilemaps — const @experimental```ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; extrude?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>@@ -9000,6 +9012,13 @@ uvScale: Vec2visualType: UIVisualType```+## UIVisualFit — enum @beta+```+Contain = 1+Cover = 2+Fill = 0+```+## UIVisualInit — interface @experimental```color: { r: number; g: number; b: number; a: number; } | undefined@@ -9017,7 +9036,7 @@ uvScale: Vec2 | undefinedvisualType: UIVisualType | undefined```-## UIVisualType — enum @experimental+## UIVisualType — enum @beta```Filled = 5Image = 2diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 881fed552..7ab7f7e8b 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 69 beta · 1532 experimental · 3 deprecated+Symbols: 113 public · 82 beta · 1522 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1991,7 +1991,7 @@ radius: numberrestitution: number```-## ClearFlags — enum @experimental+## ClearFlags — enum @beta```Color = 1ColorAndDepth = 3@@ -2931,7 +2931,7 @@ wasm: Uint8Array<ArrayBufferLike>Partial<Record<SideModuleId, EmbeddedSideModuleEntry>>```-## EmitterShape — enum @experimental+## EmitterShape — enum @beta```Circle = 1Cone = 3@@ -3152,7 +3152,7 @@ tooltip: string | undefinedunit: string | undefined```-## FillMethod — enum @experimental+## FillMethod — enum @beta```Horizontal = 0Radial180 = 4@@ -3161,7 +3161,7 @@ Radial90 = 3Vertical = 1```-## FillOrigin — enum @experimental+## FillOrigin — enum @beta```Bottom = 2Left = 0@@ -5414,7 +5414,7 @@ static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPIstatic prototype: ParticleAPI```-## ParticleEasing — enum @experimental+## ParticleEasing — enum @beta```EaseIn = 1EaseInOut = 3@@ -6374,7 +6374,7 @@ value: number | undefinedworld: World```-## ProjectionType — enum @experimental+## ProjectionType — enum @beta```Orthographic = 1Perspective = 0@@ -7441,7 +7441,7 @@ subscribe: (fn: (value: T) => void) => () => voidupdate: (fn: (prev: T) => T) => void```-## SimulationSpace — enum @experimental+## SimulationSpace — enum @beta```Local = 1World = 0@@ -7847,7 +7847,7 @@ toDeactivate: string[]'unload' | 'sleep'```-## SubEmitterTrigger — enum @experimental+## SubEmitterTrigger — enum @beta```Birth = 1Death = 0@@ -8405,14 +8405,6 @@ tileHeight: numbertileWidth: number```-## TileOrientation — enum @experimental-```-Hexagonal = 3-Isometric = 1-Orthogonal = 0-Staggered = 2-```-## TileStamp — interface @experimental```cells: number[]@@ -8510,6 +8502,14 @@ visible: boolean{ _bind(fn: ApplyTilesetRefs | null): void; setLayerTilesets(entity: number, refs: readonly string[]): void; }```+## TilemapOrientation — enum @beta+```+Hexagonal = 3+Isometric = 1+Orthogonal = 0+Staggered = 2+```+## TilemapPlugin — class @experimental```build: (app: App) => void@@ -8520,6 +8520,18 @@ static new (): TilemapPluginstatic prototype: TilemapPlugin```+## TilemapStaggerAxis — enum @beta+```+X = 1+Y = 0+```++## TilemapStaggerIndex — enum @beta+```+Even = 1+Odd = 0+```+## Tilemaps — const @experimental```ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; extrude?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>@@ -9246,6 +9258,13 @@ uvScale: Vec2visualType: UIVisualType```+## UIVisualFit — enum @beta+```+Contain = 1+Cover = 2+Fill = 0+```+## UIVisualInit — interface @experimental```color: { r: number; g: number; b: number; a: number; } | undefined@@ -9263,7 +9282,7 @@ uvScale: Vec2 | undefinedvisualType: UIVisualType | undefined```-## UIVisualType — enum @experimental+## UIVisualType — enum @beta```Filled = 5Image = 2diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex f5babfcfb..71e836011 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 113 public · 69 beta · 1522 experimental · 3 deprecated+Symbols: 113 public · 82 beta · 1512 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1991,7 +1991,7 @@ radius: numberrestitution: number```-## ClearFlags — enum @experimental+## ClearFlags — enum @beta```Color = 1ColorAndDepth = 3@@ -2931,7 +2931,7 @@ wasm: Uint8Array<ArrayBufferLike>Partial<Record<SideModuleId, EmbeddedSideModuleEntry>>```-## EmitterShape — enum @experimental+## EmitterShape — enum @beta```Circle = 1Cone = 3@@ -3152,7 +3152,7 @@ tooltip: string | undefinedunit: string | undefined```-## FillMethod — enum @experimental+## FillMethod — enum @beta```Horizontal = 0Radial180 = 4@@ -3161,7 +3161,7 @@ Radial90 = 3Vertical = 1```-## FillOrigin — enum @experimental+## FillOrigin — enum @beta```Bottom = 2Left = 0@@ -5175,7 +5175,7 @@ static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPIstatic prototype: ParticleAPI```-## ParticleEasing — enum @experimental+## ParticleEasing — enum @beta```EaseIn = 1EaseInOut = 3@@ -6135,7 +6135,7 @@ value: number | undefinedworld: World```-## ProjectionType — enum @experimental+## ProjectionType — enum @beta```Orthographic = 1Perspective = 0@@ -7202,7 +7202,7 @@ subscribe: (fn: (value: T) => void) => () => voidupdate: (fn: (prev: T) => T) => void```-## SimulationSpace — enum @experimental+## SimulationSpace — enum @beta```Local = 1World = 0@@ -7608,7 +7608,7 @@ toDeactivate: string[]'unload' | 'sleep'```-## SubEmitterTrigger — enum @experimental+## SubEmitterTrigger — enum @beta```Birth = 1Death = 0@@ -8166,14 +8166,6 @@ tileHeight: numbertileWidth: number```-## TileOrientation — enum @experimental-```-Hexagonal = 3-Isometric = 1-Orthogonal = 0-Staggered = 2-```-## TileStamp — interface @experimental```cells: number[]@@ -8271,6 +8263,14 @@ visible: boolean{ _bind(fn: ApplyTilesetRefs | null): void; setLayerTilesets(entity: number, refs: readonly string[]): void; }```+## TilemapOrientation — enum @beta+```+Hexagonal = 3+Isometric = 1+Orthogonal = 0+Staggered = 2+```+## TilemapPlugin — class @experimental```build: (app: App) => void@@ -8281,6 +8281,18 @@ static new (): TilemapPluginstatic prototype: TilemapPlugin```+## TilemapStaggerAxis — enum @beta+```+X = 1+Y = 0+```++## TilemapStaggerIndex — enum @beta+```+Even = 1+Odd = 0+```+## Tilemaps — const @experimental```ResourceDef<{ initLayer(entity: number, width: number, height: number, tileWidth: number, tileHeight: number): void; destroyLayer(entity: number): void; setTile(entity: number, x: number, y: number, tileId: number): void; getTile(entity: number, x: number, y: number): number; fillRect(entity: number, x: number, y: number, w: number, h: number, tileId: number): void; setTiles(entity: number, tiles: Uint16Array): void; setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number; margin?: number; spacing?: number; extrude?: number; }[]): void; hasLayer(entity: number): boolean; setRenderProps(entity: number, textureHandle: number, tilesetColumns: number, uvTileW: number, uvTileH: number, sortLayer: number, depth: number, parallaxX: number, parallaxY: number): void; setTint(entity: number, r: number, g: number, b: number, a: number, opacity: number): void; setVisible(entity: number, visible: boolean): void; setOriginEntity(layerKey: number, originEntity: number): void; setTileAnimation(entity: number, tileId: number, frames: { tileId: number; duration: number; }[]): void; clearTileAnimations(entity: number): void; advanceAnimations(entity: number, dtMs: number): void; setTileProperty(entity: number, tileId: number, key: string, value: string): void; getTileProperty(entity: number, x: number, y: number, key: string): string; flipTile(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void; rotateTile(entity: number, x: number, y: number, degrees: number): void; initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void; setChunkTiles(entity: number, chunkX: number, chunkY: number, tiles: Uint16Array, width: number, height: number): void; setGridType(entity: number, type: number): void; setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void; tileToWorld(entity: number, tx: number, ty: number, originX: number, originY: number): { x: number; y: number; }; worldToTile(entity: number, wx: number, wy: number, originX: number, originY: number): { x: number; y: number; }; exportChunks(entity: number): string; importChunks(entity: number, encoded: string): boolean; }>@@ -9007,6 +9019,13 @@ uvScale: Vec2visualType: UIVisualType```+## UIVisualFit — enum @beta+```+Contain = 1+Cover = 2+Fill = 0+```+## UIVisualInit — interface @experimental```color: { r: number; g: number; b: number; a: number; } | undefined@@ -9024,7 +9043,7 @@ uvScale: Vec2 | undefinedvisualType: UIVisualType | undefined```-## UIVisualType — enum @experimental+## UIVisualType — enum @beta```Filled = 5Image = 2diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 60cc6bf6a..f1dde27de 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -568,7 +568,9 @@ export {isNonOrthogonal,usesStagger,isHexOrientation,- TileOrientation,+ TilemapOrientation,+ TilemapStaggerAxis,+ TilemapStaggerIndex,TB_N,TB_E,TB_S,diff --git a/sdk/src/core-ui.ts b/sdk/src/core-ui.tsindex cd54bd174..c9ff6ed23 100644--- a/sdk/src/core-ui.ts+++ b/sdk/src/core-ui.ts@@ -24,6 +24,7 @@ export {UINode,UIVisual,UIVisualType,+ UIVisualFit,UILayoutGeneration,UIMask,measureText,diff --git a/sdk/src/tilemap/index.ts b/sdk/src/tilemap/index.tsindex 08e2135f0..b6eb0a56c 100644--- a/sdk/src/tilemap/index.ts+++ b/sdk/src/tilemap/index.ts@@ -22,7 +22,7 @@ export {type CollisionBrush, type CollisionMaterial,} from './collisionPalette';export {- tileCellCenter, tileCellOutline, isNonOrthogonal, usesStagger, isHexOrientation, TileOrientation,+ tileCellCenter, tileCellOutline, isNonOrthogonal, usesStagger, isHexOrientation, TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex,type TileGridParams, type Vec2Like,} from './tileGeometry';export { mergeCollisionTiles, type MergedRect } from './collisionMerge';diff --git a/sdk/src/tilemap/tileGeometry.ts b/sdk/src/tilemap/tileGeometry.tsindex 0b2f3d10b..80ae19ddc 100644--- a/sdk/src/tilemap/tileGeometry.ts+++ b/sdk/src/tilemap/tileGeometry.ts@@ -19,8 +19,8 @@// 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';+export { TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex } from '../wasm/wasm.generated';+import { TilemapOrientation } from '../wasm/wasm.generated';/** The layout inputs a cell placement needs — a subset of the TilemapLayer component. */export interface TileGridParams {@@ -56,11 +56,11 @@ export function tileCellCenter(p: TileGridParams, tx: number, ty: number): Vec2Lconst hw = p.tileWidth * 0.5;const hh = p.tileHeight * 0.5;switch (p.orientation) {- case TileOrientation.Isometric:+ case TilemapOrientation.Isometric:return { x: (tx - ty) * hw, y: -(tx + ty) * hh };- case TileOrientation.Staggered:- case TileOrientation.Hexagonal: {- const side = p.orientation === TileOrientation.Hexagonal ? hexSide(p) : 0;+ case TilemapOrientation.Staggered:+ case TilemapOrientation.Hexagonal: {+ const side = p.orientation === TilemapOrientation.Hexagonal ? hexSide(p) : 0;if (p.staggerAxisX) {const colW = (p.tileWidth + side) * 0.5;const staggered = ((tx & 1) !== 0) !== !!p.staggerIndexEven;@@ -85,11 +85,11 @@ export function tileCellOutline(p: TileGridParams): Vec2Like[] {const hw = p.tileWidth * 0.5;const hh = p.tileHeight * 0.5;switch (p.orientation) {- case TileOrientation.Isometric:- case TileOrientation.Staggered:+ case TilemapOrientation.Isometric:+ case TilemapOrientation.Staggered:// Diamond: top, right, bottom, left.return [{ x: 0, y: hh }, { x: hw, y: 0 }, { x: 0, y: -hh }, { x: -hw, y: 0 }];- case TileOrientation.Hexagonal: {+ case TilemapOrientation.Hexagonal: {const s = Math.min(hexSide(p), p.tileHeight, p.tileWidth); // clamp so it stays inside the boxconst hs = s * 0.5;if (p.staggerAxisX) {@@ -112,15 +112,15 @@ export function tileCellOutline(p: TileGridParams): Vec2Like[] {/** True when the layout is anything other than a plain orthogonal square grid. */export function isNonOrthogonal(orientation: number): boolean {- return orientation !== TileOrientation.Orthogonal && orientation !== undefined;+ return orientation !== TilemapOrientation.Orthogonal && orientation !== undefined;}/** True for the layouts that read the stagger axis/index (staggered + hexagonal). */export function usesStagger(orientation: number): boolean {- return orientation === TileOrientation.Staggered || orientation === TileOrientation.Hexagonal;+ return orientation === TilemapOrientation.Staggered || orientation === TilemapOrientation.Hexagonal;}/** True for the hexagonal layout (the only one that reads the hex side length). */export function isHexOrientation(orientation: number): boolean {- return orientation === TileOrientation.Hexagonal;+ return orientation === TilemapOrientation.Hexagonal;}diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.tsindex fe43a8ee5..465d49cf4 100644--- a/sdk/src/ui/index.ts+++ b/sdk/src/ui/index.ts@@ -52,6 +52,7 @@ export { UINode, UIPositionType, UIDisplay, UIPointerEvents, AlignSelf, type UINexport {UIVisual,UIVisualType,+ UIVisualFit,FillMethod,FillOrigin,type UIVisualData,diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.tsindex c0827192f..466e7df2c 100644--- a/sdk/src/wasm/wasm.generated.ts+++ b/sdk/src/wasm/wasm.generated.ts@@ -61,6 +61,11 @@ export enum CanvasScaleMode {Match = 4,}+/**+ * The engine's `ClearFlags`, generated from the C++ enum.+ *+ * @beta+ */export enum ClearFlags {Nothing = 0,Color = 1,@@ -68,6 +73,11 @@ export enum ClearFlags {ColorAndDepth = 3,}+/**+ * The engine's `EmitterShape`, generated from the C++ enum.+ *+ * @beta+ */export enum EmitterShape {Point = 0,Circle = 1,@@ -115,6 +125,11 @@ export enum MaskMode {Stencil = 1,}+/**+ * The engine's `ParticleEasing`, generated from the C++ enum.+ *+ * @beta+ */export enum ParticleEasing {Linear = 0,EaseIn = 1,@@ -122,6 +137,11 @@ export enum ParticleEasing {EaseInOut = 3,}+/**+ * The engine's `ProjectionType`, generated from the C++ enum.+ *+ * @beta+ */export enum ProjectionType {Perspective = 0,Orthographic = 1,@@ -138,11 +158,21 @@ export enum ShapeType {RoundedRect = 2,}+/**+ * The engine's `SimulationSpace`, generated from the C++ enum.+ *+ * @beta+ */export enum SimulationSpace {World = 0,Local = 1,}+/**+ * The engine's `SubEmitterTrigger`, generated from the C++ enum.+ *+ * @beta+ */export enum SubEmitterTrigger {Death = 0,Birth = 1,@@ -154,6 +184,11 @@ export enum TextAlign {Right = 2,}+/**+ * The engine's `TilemapOrientation`, generated from the C++ enum.+ *+ * @beta+ */export enum TilemapOrientation {Orthogonal = 0,Isometric = 1,@@ -161,11 +196,21 @@ export enum TilemapOrientation {Hexagonal = 3,}+/**+ * The engine's `TilemapStaggerAxis`, generated from the C++ enum.+ *+ * @beta+ */export enum TilemapStaggerAxis {Y = 0,X = 1,}+/**+ * The engine's `TilemapStaggerIndex`, generated from the C++ enum.+ *+ * @beta+ */export enum TilemapStaggerIndex {Odd = 0,Even = 1,@@ -176,6 +221,11 @@ export enum UIDisplay {None = 1,}+/**+ * The engine's `UIFillMethod`, generated from the C++ enum.+ *+ * @beta+ */export enum UIFillMethod {Horizontal = 0,Vertical = 1,@@ -184,6 +234,11 @@ export enum UIFillMethod {Radial180 = 4,}+/**+ * The engine's `UIFillOrigin`, generated from the C++ enum.+ *+ * @beta+ */export enum UIFillOrigin {Left = 0,Right = 1,@@ -201,12 +256,22 @@ export enum UIPositionType {Absolute = 1,}+/**+ * The engine's `UIVisualFit`, generated from the C++ enum.+ *+ * @beta+ */export enum UIVisualFit {Fill = 0,Contain = 1,Cover = 2,}+/**+ * The engine's `UIVisualType`, generated from the C++ enum.+ *+ * @beta+ */export enum UIVisualType {None = 0,SolidColor = 1,diff --git a/sdk/tests/cpp-contract.test.ts b/sdk/tests/cpp-contract.test.tsindex 32b8f1b64..071ab9dde 100644--- a/sdk/tests/cpp-contract.test.ts+++ b/sdk/tests/cpp-contract.test.ts@@ -37,7 +37,7 @@ 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 { TilemapOrientation } from '../src/tilemap/tileGeometry';import { TextAlign } from '../src/ui/core/text';import {FlexDirection, FlexWrap, JustifyContent, AlignItems, AlignContent,@@ -206,7 +206,7 @@ describe('C++ contract: module-published enums ARE their EHT-generated twin', ()['ParticleEasing', ParticleEasing, gen.ParticleEasing],['MaskMode', MaskMode, gen.MaskMode],['ScrollMovement', ScrollMovement, gen.ScrollMovement],- ['TileOrientation', TileOrientation, gen.TilemapOrientation],+ ['TilemapOrientation', TilemapOrientation, gen.TilemapOrientation],['FlexDirection', FlexDirection, gen.FlexDirection],['FlexWrap', FlexWrap, gen.FlexWrap],['JustifyContent', JustifyContent, gen.JustifyContent],diff --git a/sdk/tests/tileGeometry.test.ts b/sdk/tests/tileGeometry.test.tsindex ce1e652a9..747e92713 100644--- a/sdk/tests/tileGeometry.test.ts+++ b/sdk/tests/tileGeometry.test.ts@@ -2,7 +2,7 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { describe, it, expect } from 'vitest';import {- tileCellCenter, tileCellOutline, isNonOrthogonal, TileOrientation,+ tileCellCenter, tileCellOutline, isNonOrthogonal, TilemapOrientation,type TileGridParams,} from '../src/tilemap/tileGeometry';@@ -16,14 +16,14 @@ const centerEq = (p: TileGridParams, tx: number, ty: number, x: number, y: numbedescribe('tileCellCenter', () => {it('orthogonal: tile (0,0) center sits at (+hw,-hh); +tx→right, +ty→down', () => {- const p = { ...base, orientation: TileOrientation.Orthogonal };+ const p = { ...base, orientation: TilemapOrientation.Orthogonal };centerEq(p, 0, 0, 32, -16);centerEq(p, 1, 0, 96, -16);centerEq(p, 0, 1, 32, -48);});it('isometric: tile (0,0) center is the origin; the lattice is a diamond', () => {- const p = { ...base, orientation: TileOrientation.Isometric };+ const p = { ...base, orientation: TilemapOrientation.Isometric };centerEq(p, 0, 0, 0, 0);centerEq(p, 1, 0, 32, -16);centerEq(p, 0, 1, -32, -16);@@ -31,20 +31,20 @@ describe('tileCellCenter', () => {});it('staggered (axis Y, index odd): odd rows shift right hw and every row drops hh', () => {- const p = { ...base, orientation: TileOrientation.Staggered };+ const p = { ...base, orientation: TilemapOrientation.Staggered };centerEq(p, 0, 0, 32, -16);centerEq(p, 0, 1, 64, -32); // row 1 (odd) shifted +hw, dropped +hhcenterEq(p, 0, 2, 32, -48); // row 2 (even) back to the column});it('staggered index even flips which rows shift', () => {- const p = { ...base, orientation: TileOrientation.Staggered, staggerIndexEven: true };+ const p = { ...base, orientation: TilemapOrientation.Staggered, staggerIndexEven: true };centerEq(p, 0, 0, 64, -16); // row 0 (even) now shiftedcenterEq(p, 0, 1, 32, -32); // row 1 (odd) unshifted});it('staggered axis X shifts odd columns down instead of rows right', () => {- const p = { ...base, orientation: TileOrientation.Staggered, staggerAxisX: true };+ const p = { ...base, orientation: TilemapOrientation.Staggered, staggerAxisX: true };// colW = (64+0)/2 = 32centerEq(p, 0, 0, 32, -16);centerEq(p, 1, 0, 64, -32); // col 1 (odd) shifted down hh, advanced one colW@@ -52,19 +52,19 @@ describe('tileCellCenter', () => {});it('hexagonal (axis Y): row pitch is (th+side)/2, side defaults to th/2', () => {- const side8 = { ...base, orientation: TileOrientation.Hexagonal, hexSideLength: 8 };+ const side8 = { ...base, orientation: TilemapOrientation.Hexagonal, hexSideLength: 8 };// rowH = (32+8)/2 = 20centerEq(side8, 0, 0, 32, -16);centerEq(side8, 0, 1, 64, -36); // odd row shifted +hw, y = -(20 + 16)centerEq(side8, 0, 2, 32, -56); // even row, y = -(40 + 16)- const dflt = { ...base, orientation: TileOrientation.Hexagonal }; // side → th/2 = 16+ const dflt = { ...base, orientation: TilemapOrientation.Hexagonal }; // side → th/2 = 16// rowH = (32+16)/2 = 24centerEq(dflt, 0, 2, 32, -64); // y = -(2*24 + 16)});it('hexagonal axis X: column pitch is (tw+side)/2', () => {- const p = { ...base, orientation: TileOrientation.Hexagonal, hexSideLength: 8, staggerAxisX: true };+ const p = { ...base, orientation: TilemapOrientation.Hexagonal, hexSideLength: 8, staggerAxisX: true };// colW = (64+8)/2 = 36centerEq(p, 0, 0, 32, -16);centerEq(p, 1, 0, 68, -32); // col 1 (odd) shifted down hh, x = 36 + 32@@ -74,7 +74,7 @@ describe('tileCellCenter', () => {describe('tileCellOutline', () => {it('orthogonal outline is the tile rect', () => {- const o = tileCellOutline({ ...base, orientation: TileOrientation.Orthogonal });+ const o = tileCellOutline({ ...base, orientation: TilemapOrientation.Orthogonal });expect(o).toHaveLength(4);// spans the full tile boxexpect(Math.max(...o.map((v) => v.x))).toBe(32);@@ -83,14 +83,14 @@ describe('tileCellOutline', () => {});it('isometric/staggered outline is a diamond (points on the axes)', () => {- for (const orientation of [TileOrientation.Isometric, TileOrientation.Staggered]) {+ for (const orientation of [TilemapOrientation.Isometric, TilemapOrientation.Staggered]) {const o = tileCellOutline({ ...base, orientation });expect(o).toEqual([{ x: 0, y: 16 }, { x: 32, y: 0 }, { x: 0, y: -16 }, { x: -32, y: 0 }]);}});it('hexagonal axis Y is a pointy-top hex: 6 verts, flat edges vertical of length side', () => {- const o = tileCellOutline({ ...base, orientation: TileOrientation.Hexagonal, hexSideLength: 8 });+ const o = tileCellOutline({ ...base, orientation: TilemapOrientation.Hexagonal, hexSideLength: 8 });expect(o).toHaveLength(6);// top and bottom are single points on the y axisexpect(o).toContainEqual({ x: 0, y: 16 });@@ -101,7 +101,7 @@ describe('tileCellOutline', () => {});it('hexagonal axis X is a flat-top hex: points on the x axis', () => {- const o = tileCellOutline({ ...base, orientation: TileOrientation.Hexagonal, hexSideLength: 8, staggerAxisX: true });+ const o = tileCellOutline({ ...base, orientation: TilemapOrientation.Hexagonal, hexSideLength: 8, staggerAxisX: true });expect(o).toHaveLength(6);expect(o).toContainEqual({ x: 32, y: 0 });expect(o).toContainEqual({ x: -32, y: 0 });@@ -113,9 +113,9 @@ describe('tileCellOutline', () => {describe('isNonOrthogonal', () => {it('is true for iso/staggered/hex, false for orthogonal', () => {- expect(isNonOrthogonal(TileOrientation.Orthogonal)).toBe(false);- expect(isNonOrthogonal(TileOrientation.Isometric)).toBe(true);- expect(isNonOrthogonal(TileOrientation.Staggered)).toBe(true);- expect(isNonOrthogonal(TileOrientation.Hexagonal)).toBe(true);+ expect(isNonOrthogonal(TilemapOrientation.Orthogonal)).toBe(false);+ expect(isNonOrthogonal(TilemapOrientation.Isometric)).toBe(true);+ expect(isNonOrthogonal(TilemapOrientation.Staggered)).toBe(true);+ expect(isNonOrthogonal(TilemapOrientation.Hexagonal)).toBe(true);});});diff --git a/src/esengine/core/Reflection.hpp b/src/esengine/core/Reflection.hppindex 08abd79da..b89fd71ec 100644--- a/src/esengine/core/Reflection.hpp+++ b/src/esengine/core/Reflection.hpp@@ -110,8 +110,13 @@** @details Enums marked with this macro will be available as* TypeScript enums with proper type checking.+ *+ * `stability=public|beta|experimental` is the SDK tier of the generated+ * enum. A component's fields are made of these, so an enum weaker than+ * the component naming it is a promise with a hole where its vocabulary+ * should be. Untagged means `experimental`, as everywhere else.*/-#define ES_ENUM()+#define ES_ENUM(...)/*** @brief Mark an enum value for explicit naming in bindingsdiff --git a/src/esengine/ecs/components/Camera.hpp b/src/esengine/ecs/components/Camera.hppindex fb036c0bb..e47a1ff62 100644--- a/src/esengine/ecs/components/Camera.hpp+++ b/src/esengine/ecs/components/Camera.hpp@@ -30,7 +30,7 @@ namespace esengine::ecs {/*** @brief Camera projection type*/-ES_ENUM()+ES_ENUM(stability=beta)enum class ProjectionType : u8 {Perspective,Orthographic@@ -39,7 +39,7 @@ enum class ProjectionType : u8 {/*** @brief Camera clear flags*/-ES_ENUM()+ES_ENUM(stability=beta)enum class ClearFlags : u8 {Nothing,Color,diff --git a/src/esengine/ecs/components/ParticleEmitter.hpp b/src/esengine/ecs/components/ParticleEmitter.hppindex 8b3bd3658..0a3e08aba 100644--- a/src/esengine/ecs/components/ParticleEmitter.hpp+++ b/src/esengine/ecs/components/ParticleEmitter.hpp@@ -9,7 +9,7 @@namespace esengine::ecs {-ES_ENUM()+ES_ENUM(stability=beta)enum class EmitterShape : i32 {Point = 0,Circle = 1,@@ -20,7 +20,7 @@ enum class EmitterShape : i32 {// Single source of the easing choice serialized by sizeEasing/colorEasing; the// particle sim consumes it as particle::EasingType (alias) and the editor// dropdown + TS const are EHT-generated from here.-ES_ENUM()+ES_ENUM(stability=beta)enum class ParticleEasing : i32 {Linear = 0,EaseIn = 1,@@ -28,7 +28,7 @@ enum class ParticleEasing : i32 {EaseInOut = 3,};-ES_ENUM()+ES_ENUM(stability=beta)enum class SimulationSpace : i32 {World = 0,Local = 1,@@ -37,7 +37,7 @@ enum class SimulationSpace : i32 {// When a sub-emitter fires the referenced child emitter's burst: as each parent// particle is born, or as it dies. (Collision joins this list once particle// collision lands.)-ES_ENUM()+ES_ENUM(stability=beta)enum class SubEmitterTrigger : i32 {Death = 0,Birth = 1,diff --git a/src/esengine/ecs/components/TilemapLayer.hpp b/src/esengine/ecs/components/TilemapLayer.hppindex 88d0ef402..ca0d48bbe 100644--- a/src/esengine/ecs/components/TilemapLayer.hpp+++ b/src/esengine/ecs/components/TilemapLayer.hpp@@ -18,7 +18,7 @@ namespace esengine::ecs {* component field maps straight to the runtime grid type. "Staggered" is the* staggered-isometric grid; it and Hexagonal share the stagger axis/index.*/-ES_ENUM()+ES_ENUM(stability=beta)enum class TilemapOrientation : u8 {Orthogonal = 0,Isometric = 1,@@ -27,14 +27,14 @@ enum class TilemapOrientation : u8 {};/** Which axis the stagger runs along (Tiled staggeraxis). Y = rows shift, X = columns shift. */-ES_ENUM()+ES_ENUM(stability=beta)enum class TilemapStaggerAxis : u8 {Y = 0,X = 1,};/** Which lines carry the half-cell shift (Tiled staggerindex). */-ES_ENUM()+ES_ENUM(stability=beta)enum class TilemapStaggerIndex : u8 {Odd = 0,Even = 1,diff --git a/src/esengine/ecs/components/UIVisual.hpp b/src/esengine/ecs/components/UIVisual.hppindex a885f5e5c..a36f3e4c6 100644--- a/src/esengine/ecs/components/UIVisual.hpp+++ b/src/esengine/ecs/components/UIVisual.hpp@@ -20,7 +20,7 @@ namespace esengine::ecs {* sliceBorder; Tiled = texture repeated by box/tileSize; Filled = texture* cropped to fillAmount along fillMethod/fillOrigin.*/-ES_ENUM()+ES_ENUM(stability=beta)enum class UIVisualType : u8 {None,SolidColor,@@ -37,7 +37,7 @@ enum class UIVisualType : u8 {* wedge from 0 to the mode's arc (90/180/360 degrees) — cooldown rings,* speedometer arcs, corner meters.*/-ES_ENUM()+ES_ENUM(stability=beta)enum class UIFillMethod : u8 {Horizontal,Vertical,@@ -46,7 +46,7 @@ enum class UIFillMethod : u8 {Radial180};-ES_ENUM()+ES_ENUM(stability=beta)enum class UIFillOrigin : u8 {Left,Right,@@ -62,7 +62,7 @@ enum class UIFillOrigin : u8 {* my artwork" mode. Cover scales up until the box is covered and crops* the overflow, so the box is filled with no distortion.*/-ES_ENUM()+ES_ENUM(stability=beta)enum class UIVisualFit : u8 {Fill,Contain,diff --git a/tools/check-enum-twins.mjs b/tools/check-enum-twins.mjsindex 289a7b0e9..cfa136cda 100644--- a/tools/check-enum-twins.mjs+++ b/tools/check-enum-twins.mjs@@ -25,6 +25,8 @@ import { readFileSync, existsSync } from 'node:fs';import { execFileSync } from 'node:child_process';import path from 'node:path';import { fileURLToPath } from 'node:url';+import { ETC, ENTRIES } from './lib/sdkProgram.mjs';+import { parseSnapshot } from './lib/apiSnapshot.mjs';const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');const GENERATED = path.join(ROOT, 'sdk/src/wasm/wasm.generated.ts');@@ -73,12 +75,40 @@ for (const rel of sources) {}}+// ------------------------------------------------------- and how strongly+//+// A shape is MADE of these: an enum weaker than the shape naming it survives a+// release while the values it may hold do not. `ES_ENUM(stability=)` answers it.+const RANK = { public: 0, beta: 1, experimental: 2 };+const api = new Map();+for (const entry of Object.keys(ENTRIES)) {+ const file = path.join(ETC, `${entry}.api.md`);+ if (!existsSync(file)) continue;+ for (const [name, sym] of parseSnapshot(readFileSync(file, 'utf8'))) {+ const seen = api.get(name);+ if (!seen) { api.set(name, { ...sym }); continue; }+ if ((RANK[sym.tier] ?? 9) < (RANK[seen.tier] ?? 9)) seen.tier = sym.tier;+ }+}+for (const [name, sym] of api) {+ if ((RANK[sym.tier] ?? 9) > RANK.beta) continue; // experimental promises nothing+ const body = (sym.body ?? '').split('\n').filter((l) => !l.startsWith('@internal ')).join('\n');+ for (const gen of GEN_ENUMS) {+ if (!new RegExp(`:\\s*${gen}\\b`).test(body)) continue;+ const theirs = api.get(gen)?.tier ?? 'experimental';+ if ((RANK[theirs] ?? 9) <= (RANK[sym.tier] ?? 9)) continue;+ problems.push(`${name} is @${sym.tier} and its shape is spelled in ${gen}, which is @${theirs}`);+ }+}+if (problems.length) {- console.error('check-enum-twins: a number that crosses to C++ is restated and unheld.\n');+ console.error('check-enum-twins: a number that crosses to C++ is restated or under-promised.\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.');+ + ' keep the declaration and pin its VALUES there. An under-promised enum is answered'+ + ' with ES_ENUM(stability=) at its C++ declaration.');process.exit(1);}-console.log(`check-enum-twins: ${GEN_ENUMS.size} generated C++ enums, every TS restatement of one held to it.`);+console.log(`check-enum-twins: ${GEN_ENUMS.size} generated C++ enums — every TS restatement held to`+ + ' one, and every shape promised at beta or better spelled in vocabulary at least as strong.');diff --git a/tools/eht/data.py b/tools/eht/data.pyindex a196f5e79..51b056272 100644--- a/tools/eht/data.py+++ b/tools/eht/data.py@@ -47,3 +47,4 @@ class Enum:namespace: strvalues: List[str] = field(default_factory=list)underlying_type: str = "int"+ annotations: Dict[str, str] = field(default_factory=dict)diff --git a/tools/eht/generators/typescript.py b/tools/eht/generators/typescript.pyindex 1697c89f2..88bd305e3 100644--- a/tools/eht/generators/typescript.py+++ b/tools/eht/generators/typescript.py@@ -57,6 +57,16 @@ class TypeScriptGenerator:return []lines = ['// Enums', '']for enum in self.enums:+ # From ES_ENUM(stability=): a component's fields are made of these, so+ # an enum with no tier makes the component's promise only as strong as+ # its weakest name. Untagged stays experimental, as everywhere else.+ tier = enum.annotations.get('stability')+ if tier:+ lines.append('/**')+ lines.append(f' * The engine\'s `{enum.name}`, generated from the C++ enum.')+ lines.append(' *')+ lines.append(f' * @{tier}')+ lines.append(' */')lines.append(f'export enum {enum.name} {{')for i, val in enumerate(enum.values):lines.append(f' {val} = {i},')diff --git a/tools/eht/parser.py b/tools/eht/parser.pyindex 51ca14e43..09b83c363 100644--- a/tools/eht/parser.py+++ b/tools/eht/parser.py@@ -24,7 +24,11 @@ class CppParser:RE_COMPONENT = re.compile(r'ES_COMPONENT\s*\(\s*((?:[^)"]|"[^"]*")*?)\s*\)\s*struct\s+(\w+)')- RE_ENUM = re.compile(r'ES_ENUM\s*\(\s*\)\s*enum\s+class\s+(\w+)(?:\s*:\s*(\w+))?')+ # Same annotation group as ES_COMPONENT: an enum takes `stability=` by the+ # grammar everything else takes its metadata.+ RE_ENUM = re.compile(+ r'ES_ENUM\s*\(\s*((?:[^)"]|"[^"]*")*?)\s*\)\s*enum\s+class\s+(\w+)(?:\s*:\s*(\w+))?'+ )# The annotation group `(?:[^)"]|"[^"]*")*?` accepts runs of non-paren chars# OR whole quoted strings, so a `)` or `,` *inside quotes* (e.g. a tooltip) does# not terminate the argument list. Non-greedy stops at the first UNquoted `)`.@@ -116,8 +120,9 @@ class CppParser:def _parse_enums(self, content: str, namespace: str) -> None:for match in self.RE_ENUM.finditer(content):- enum_name = match.group(1)- underlying = match.group(2) or "int"+ enum_annotations = self._parse_annotations(match.group(1))+ enum_name = match.group(2)+ underlying = match.group(3) or "int"brace_start = content.find('{', match.end())if brace_start == -1:@@ -136,7 +141,8 @@ class CppParser:self.enums.append(Enum(name=enum_name, namespace=namespace,- values=values, underlying_type=underlying+ values=values, underlying_type=underlying,+ annotations=enum_annotations))def _parse_components(self, content: str, namespace: str, filepath: Path) -> None: