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.

feat(eht): an enum says how strongly it is promised

esengine3791c5478738
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 not
built 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`. So
diff --git a/desktop b/desktop
index 49c9e5ed5..f0d4546ee 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 49c9e5ed5af00339e652414b69f428e2a42da41e
+Subproject commit f0d4546ee669bf1e02619a0c140d955b909df70b
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 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.md
index 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: number
restitution: number
```
-## ClearFlags — enum @experimental
+## ClearFlags — enum @beta
```
Color = 1
ColorAndDepth = 3
@@ -2936,7 +2936,7 @@ wasm: Uint8Array<ArrayBufferLike>
Partial<Record<SideModuleId, EmbeddedSideModuleEntry>>
```
-## EmitterShape — enum @experimental
+## EmitterShape — enum @beta
```
Circle = 1
Cone = 3
@@ -3157,7 +3157,7 @@ tooltip: string | undefined
unit: string | undefined
```
-## FillMethod — enum @experimental
+## FillMethod — enum @beta
```
Horizontal = 0
Radial180 = 4
@@ -3166,7 +3166,7 @@ Radial90 = 3
Vertical = 1
```
-## FillOrigin — enum @experimental
+## FillOrigin — enum @beta
```
Bottom = 2
Left = 0
@@ -5173,7 +5173,7 @@ static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI
static prototype: ParticleAPI
```
-## ParticleEasing — enum @experimental
+## ParticleEasing — enum @beta
```
EaseIn = 1
EaseInOut = 3
@@ -6133,7 +6133,7 @@ value: number | undefined
world: World
```
-## ProjectionType — enum @experimental
+## ProjectionType — enum @beta
```
Orthographic = 1
Perspective = 0
@@ -7200,7 +7200,7 @@ subscribe: (fn: (value: T) => void) => () => void
update: (fn: (prev: T) => T) => void
```
-## SimulationSpace — enum @experimental
+## SimulationSpace — enum @beta
```
Local = 1
World = 0
@@ -7606,7 +7606,7 @@ toDeactivate: string[]
'unload' | 'sleep'
```
-## SubEmitterTrigger — enum @experimental
+## SubEmitterTrigger — enum @beta
```
Birth = 1
Death = 0
@@ -8164,14 +8164,6 @@ tileHeight: number
tileWidth: 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 (): TilemapPlugin
static 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: Vec2
visualType: 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 | undefined
visualType: UIVisualType | undefined
```
-## UIVisualType — enum @experimental
+## UIVisualType — enum @beta
```
Filled = 5
Image = 2
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: number
restitution: number
```
-## ClearFlags — enum @experimental
+## ClearFlags — enum @beta
```
Color = 1
ColorAndDepth = 3
@@ -2944,7 +2944,7 @@ wasm: Uint8Array<ArrayBufferLike>
Partial<Record<SideModuleId, EmbeddedSideModuleEntry>>
```
-## EmitterShape — enum @experimental
+## EmitterShape — enum @beta
```
Circle = 1
Cone = 3
@@ -3165,7 +3165,7 @@ tooltip: string | undefined
unit: string | undefined
```
-## FillMethod — enum @experimental
+## FillMethod — enum @beta
```
Horizontal = 0
Radial180 = 4
@@ -3174,7 +3174,7 @@ Radial90 = 3
Vertical = 1
```
-## FillOrigin — enum @experimental
+## FillOrigin — enum @beta
```
Bottom = 2
Left = 0
@@ -5356,7 +5356,7 @@ static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI
static prototype: ParticleAPI
```
-## ParticleEasing — enum @experimental
+## ParticleEasing — enum @beta
```
EaseIn = 1
EaseInOut = 3
@@ -6316,7 +6316,7 @@ value: number | undefined
world: World
```
-## ProjectionType — enum @experimental
+## ProjectionType — enum @beta
```
Orthographic = 1
Perspective = 0
@@ -7393,7 +7393,7 @@ subscribe: (fn: (value: T) => void) => () => void
update: (fn: (prev: T) => T) => void
```
-## SimulationSpace — enum @experimental
+## SimulationSpace — enum @beta
```
Local = 1
World = 0
@@ -7799,7 +7799,7 @@ toDeactivate: string[]
'unload' | 'sleep'
```
-## SubEmitterTrigger — enum @experimental
+## SubEmitterTrigger — enum @beta
```
Birth = 1
Death = 0
@@ -8357,14 +8357,6 @@ tileHeight: number
tileWidth: 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 (): TilemapPlugin
static 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: Vec2
visualType: 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 | undefined
visualType: UIVisualType | undefined
```
-## UIVisualType — enum @experimental
+## UIVisualType — enum @beta
```
Filled = 5
Image = 2
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: number
restitution: number
```
-## ClearFlags — enum @experimental
+## ClearFlags — enum @beta
```
Color = 1
ColorAndDepth = 3
@@ -2931,7 +2931,7 @@ wasm: Uint8Array<ArrayBufferLike>
Partial<Record<SideModuleId, EmbeddedSideModuleEntry>>
```
-## EmitterShape — enum @experimental
+## EmitterShape — enum @beta
```
Circle = 1
Cone = 3
@@ -3152,7 +3152,7 @@ tooltip: string | undefined
unit: string | undefined
```
-## FillMethod — enum @experimental
+## FillMethod — enum @beta
```
Horizontal = 0
Radial180 = 4
@@ -3161,7 +3161,7 @@ Radial90 = 3
Vertical = 1
```
-## FillOrigin — enum @experimental
+## FillOrigin — enum @beta
```
Bottom = 2
Left = 0
@@ -5168,7 +5168,7 @@ static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI
static prototype: ParticleAPI
```
-## ParticleEasing — enum @experimental
+## ParticleEasing — enum @beta
```
EaseIn = 1
EaseInOut = 3
@@ -6128,7 +6128,7 @@ value: number | undefined
world: World
```
-## ProjectionType — enum @experimental
+## ProjectionType — enum @beta
```
Orthographic = 1
Perspective = 0
@@ -7195,7 +7195,7 @@ subscribe: (fn: (value: T) => void) => () => void
update: (fn: (prev: T) => T) => void
```
-## SimulationSpace — enum @experimental
+## SimulationSpace — enum @beta
```
Local = 1
World = 0
@@ -7601,7 +7601,7 @@ toDeactivate: string[]
'unload' | 'sleep'
```
-## SubEmitterTrigger — enum @experimental
+## SubEmitterTrigger — enum @beta
```
Birth = 1
Death = 0
@@ -8159,14 +8159,6 @@ tileHeight: number
tileWidth: 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 (): TilemapPlugin
static 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: Vec2
visualType: 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 | undefined
visualType: UIVisualType | undefined
```
-## UIVisualType — enum @experimental
+## UIVisualType — enum @beta
```
Filled = 5
Image = 2
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: number
restitution: number
```
-## ClearFlags — enum @experimental
+## ClearFlags — enum @beta
```
Color = 1
ColorAndDepth = 3
@@ -2931,7 +2931,7 @@ wasm: Uint8Array<ArrayBufferLike>
Partial<Record<SideModuleId, EmbeddedSideModuleEntry>>
```
-## EmitterShape — enum @experimental
+## EmitterShape — enum @beta
```
Circle = 1
Cone = 3
@@ -3152,7 +3152,7 @@ tooltip: string | undefined
unit: string | undefined
```
-## FillMethod — enum @experimental
+## FillMethod — enum @beta
```
Horizontal = 0
Radial180 = 4
@@ -3161,7 +3161,7 @@ Radial90 = 3
Vertical = 1
```
-## FillOrigin — enum @experimental
+## FillOrigin — enum @beta
```
Bottom = 2
Left = 0
@@ -5414,7 +5414,7 @@ static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI
static prototype: ParticleAPI
```
-## ParticleEasing — enum @experimental
+## ParticleEasing — enum @beta
```
EaseIn = 1
EaseInOut = 3
@@ -6374,7 +6374,7 @@ value: number | undefined
world: World
```
-## ProjectionType — enum @experimental
+## ProjectionType — enum @beta
```
Orthographic = 1
Perspective = 0
@@ -7441,7 +7441,7 @@ subscribe: (fn: (value: T) => void) => () => void
update: (fn: (prev: T) => T) => void
```
-## SimulationSpace — enum @experimental
+## SimulationSpace — enum @beta
```
Local = 1
World = 0
@@ -7847,7 +7847,7 @@ toDeactivate: string[]
'unload' | 'sleep'
```
-## SubEmitterTrigger — enum @experimental
+## SubEmitterTrigger — enum @beta
```
Birth = 1
Death = 0
@@ -8405,14 +8405,6 @@ tileHeight: number
tileWidth: 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 (): TilemapPlugin
static 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: Vec2
visualType: 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 | undefined
visualType: UIVisualType | undefined
```
-## UIVisualType — enum @experimental
+## UIVisualType — enum @beta
```
Filled = 5
Image = 2
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: number
restitution: number
```
-## ClearFlags — enum @experimental
+## ClearFlags — enum @beta
```
Color = 1
ColorAndDepth = 3
@@ -2931,7 +2931,7 @@ wasm: Uint8Array<ArrayBufferLike>
Partial<Record<SideModuleId, EmbeddedSideModuleEntry>>
```
-## EmitterShape — enum @experimental
+## EmitterShape — enum @beta
```
Circle = 1
Cone = 3
@@ -3152,7 +3152,7 @@ tooltip: string | undefined
unit: string | undefined
```
-## FillMethod — enum @experimental
+## FillMethod — enum @beta
```
Horizontal = 0
Radial180 = 4
@@ -3161,7 +3161,7 @@ Radial90 = 3
Vertical = 1
```
-## FillOrigin — enum @experimental
+## FillOrigin — enum @beta
```
Bottom = 2
Left = 0
@@ -5175,7 +5175,7 @@ static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI
static prototype: ParticleAPI
```
-## ParticleEasing — enum @experimental
+## ParticleEasing — enum @beta
```
EaseIn = 1
EaseInOut = 3
@@ -6135,7 +6135,7 @@ value: number | undefined
world: World
```
-## ProjectionType — enum @experimental
+## ProjectionType — enum @beta
```
Orthographic = 1
Perspective = 0
@@ -7202,7 +7202,7 @@ subscribe: (fn: (value: T) => void) => () => void
update: (fn: (prev: T) => T) => void
```
-## SimulationSpace — enum @experimental
+## SimulationSpace — enum @beta
```
Local = 1
World = 0
@@ -7608,7 +7608,7 @@ toDeactivate: string[]
'unload' | 'sleep'
```
-## SubEmitterTrigger — enum @experimental
+## SubEmitterTrigger — enum @beta
```
Birth = 1
Death = 0
@@ -8166,14 +8166,6 @@ tileHeight: number
tileWidth: 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 (): TilemapPlugin
static 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: Vec2
visualType: 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 | undefined
visualType: UIVisualType | undefined
```
-## UIVisualType — enum @experimental
+## UIVisualType — enum @beta
```
Filled = 5
Image = 2
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 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.ts
index 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.ts
index 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.ts
index 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): Vec2L
const 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 box
const 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.ts
index 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 UIN
export {
UIVisual,
UIVisualType,
+ UIVisualFit,
FillMethod,
FillOrigin,
type UIVisualData,
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index 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.ts
index 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.ts
index 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 Team
import { 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: numbe
describe('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 +hh
centerEq(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 shifted
centerEq(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 = 32
centerEq(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 = 20
centerEq(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 = 24
centerEq(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 = 36
centerEq(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 box
expect(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 axis
expect(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.hpp
index 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 bindings
diff --git a/src/esengine/ecs/components/Camera.hpp b/src/esengine/ecs/components/Camera.hpp
index 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.hpp
index 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.hpp
index 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.hpp
index 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.mjs
index 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.py
index a196f5e79..51b056272 100644
--- a/tools/eht/data.py
+++ b/tools/eht/data.py
@@ -47,3 +47,4 @@ class Enum:
namespace: str
values: 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.py
index 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.py
index 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: