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(api): UI, Physics and Animation are Beta; Audio stays experimental, and why

esengine8cae4308ad36
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 1f31337f5..a4994da41 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -1,9 +1,9 @@
{
"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",
"counts": {
- "public": 107,
- "beta": 45,
- "experimental": 1478,
+ "public": 111,
+ "beta": 57,
+ "experimental": 1462,
"deprecated": 3
},
"total": 1630,
@@ -284,6 +284,30 @@
"minigame"
]
},
+ {
+ "name": "Dimension",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "DimensionUnit",
+ "kind": "type",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "Entity",
"kind": "type",
@@ -1291,6 +1315,30 @@
"wechat",
"minigame"
]
+ },
+ {
+ "name": "percent",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "px",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
}
],
"beta": [
@@ -1342,6 +1390,19 @@
"minigame"
]
},
+ {
+ "name": "CharacterController",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "physics",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "GraphNodeType",
"kind": "type",
@@ -1506,6 +1567,32 @@
"minigame"
]
},
+ {
+ "name": "Physics",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "physics",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "PhysicsEvents",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "physics",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "PrefabOverride",
"kind": "interface",
@@ -1626,6 +1713,43 @@
"minigame"
]
},
+ {
+ "name": "Spine",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "spine",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "SpineAnimation",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "ThemeColors",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "TouchPoint",
"kind": "interface",
@@ -1662,6 +1786,54 @@
"minigame"
]
},
+ {
+ "name": "UICameraData",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "UICameraInfo",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "UINode",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "UIVisual",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "addNode",
"kind": "function",
@@ -1794,6 +1966,30 @@
"minigame"
]
},
+ {
+ "name": "spawnUIEntity",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "themeColors",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "transitionTo",
"kind": "function",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index b9f45bb35..1a32b610f 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: 107 public · 38 beta · 1363 experimental · 3 deprecated
+Symbols: 111 public · 50 beta · 1347 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1706,7 +1706,7 @@ ComponentDef<ChainColliderData>
@internal _filterType: "changed"
```
-## CharacterController — const @experimental
+## CharacterController — const @beta
```
ComponentDef<CharacterControllerData>
```
@@ -2266,13 +2266,13 @@ ignoreEntityNames: readonly string[] | undefined
ignoreMetadataKeys: readonly string[] | undefined
```
-## Dimension — interface @experimental
+## Dimension — interface @public
```
unit: number
value: number
```
-## DimensionUnit — type @experimental
+## DimensionUnit — type @public
```
(typeof DimensionUnit)[keyof typeof DimensionUnit]
```
@@ -4653,7 +4653,7 @@ static prototype: PerceptionPlugin
ComponentDef<{}>
```
-## Physics — const @experimental
+## Physics — const @beta
```
ResourceDef<PhysicsAPI>
```
@@ -4670,7 +4670,7 @@ other: number
typeof PhysicsEventType[keyof typeof PhysicsEventType]
```
-## PhysicsEvents — const @experimental
+## PhysicsEvents — const @beta
```
ResourceDef<PhysicsEventsData>
```
@@ -6468,12 +6468,12 @@ rolloff: number
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
-## Spine — const @experimental
+## Spine — const @beta
```
ResourceDef<SpineManager>
```
-## SpineAnimation — const @experimental
+## SpineAnimation — const @beta
```
BuiltinComponentDef<SpineAnimationData>
```
@@ -7208,7 +7208,7 @@ textureId: number
(typeof TextureWrap)[keyof typeof TextureWrap]
```
-## ThemeColors — interface @experimental
+## ThemeColors — interface @beta
```
backdrop: Color
control: Color
@@ -7829,7 +7829,7 @@ static prototype: TweenSequence
(typeof TweenTarget)[keyof typeof TweenTarget]
```
-## UICameraData — interface @experimental
+## UICameraData — interface @beta
```
screenH: number
screenW: number
@@ -7847,7 +7847,7 @@ worldRight: number
worldTop: number
```
-## UICameraInfo — const @experimental
+## UICameraInfo — const @beta
```
ResourceDef<UICameraData>
```
@@ -8012,7 +8012,7 @@ static new (): UIMaskPlugin
static prototype: UIMaskPlugin
```
-## UINode — const @experimental
+## UINode — const @beta
```
BuiltinComponentDef<UINodeData>
```
@@ -8108,7 +8108,7 @@ static new (): UIVisibilityPlugin
static prototype: UIVisibilityPlugin
```
-## UIVisual — const @experimental
+## UIVisual — const @beta
```
BuiltinComponentDef<UIVisualData>
```
@@ -10162,7 +10162,7 @@ ParticlePlugin
(grid: NavGrid, path: Cell[]): Vec2[]
```
-## percent — const @experimental
+## percent — const @public
```
(n: number) => Dimension
```
@@ -10252,7 +10252,7 @@ PrefabsPlugin
(): string[]
```
-## px — const @experimental
+## px — const @public
```
(n: number) => Dimension
```
@@ -10812,7 +10812,7 @@ ServicesPlugin
(raw: number): TileStamp
```
-## spawnUIEntity — function @experimental
+## spawnUIEntity — function @beta
```
(init: UIEntityInit): Entity
```
@@ -10877,7 +10877,7 @@ TextPlugin
(): Record<string, ButtonStateVisual>
```
-## themeColors — function @experimental
+## themeColors — function @beta
```
(): ThemeColors
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 54bcfd9f7..ed80b0fd5 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: 107 public · 43 beta · 1382 experimental · 3 deprecated
+Symbols: 111 public · 55 beta · 1366 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -1706,7 +1706,7 @@ ComponentDef<ChainColliderData>
@internal _filterType: "changed"
```
-## CharacterController — const @experimental
+## CharacterController — const @beta
```
ComponentDef<CharacterControllerData>
```
@@ -2274,13 +2274,13 @@ ignoreEntityNames: readonly string[] | undefined
ignoreMetadataKeys: readonly string[] | undefined
```
-## Dimension — interface @experimental
+## Dimension — interface @public
```
unit: number
value: number
```
-## DimensionUnit — type @experimental
+## DimensionUnit — type @public
```
(typeof DimensionUnit)[keyof typeof DimensionUnit]
```
@@ -4836,7 +4836,7 @@ static prototype: PerceptionPlugin
ComponentDef<{}>
```
-## Physics — const @experimental
+## Physics — const @beta
```
ResourceDef<PhysicsAPI>
```
@@ -4853,7 +4853,7 @@ other: number
typeof PhysicsEventType[keyof typeof PhysicsEventType]
```
-## PhysicsEvents — const @experimental
+## PhysicsEvents — const @beta
```
ResourceDef<PhysicsEventsData>
```
@@ -6661,12 +6661,12 @@ rolloff: number
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
-## Spine — const @experimental
+## Spine — const @beta
```
ResourceDef<SpineManager>
```
-## SpineAnimation — const @experimental
+## SpineAnimation — const @beta
```
BuiltinComponentDef<SpineAnimationData>
```
@@ -7401,7 +7401,7 @@ textureId: number
(typeof TextureWrap)[keyof typeof TextureWrap]
```
-## ThemeColors — interface @experimental
+## ThemeColors — interface @beta
```
backdrop: Color
control: Color
@@ -8022,7 +8022,7 @@ static prototype: TweenSequence
(typeof TweenTarget)[keyof typeof TweenTarget]
```
-## UICameraData — interface @experimental
+## UICameraData — interface @beta
```
screenH: number
screenW: number
@@ -8040,7 +8040,7 @@ worldRight: number
worldTop: number
```
-## UICameraInfo — const @experimental
+## UICameraInfo — const @beta
```
ResourceDef<UICameraData>
```
@@ -8205,7 +8205,7 @@ static new (): UIMaskPlugin
static prototype: UIMaskPlugin
```
-## UINode — const @experimental
+## UINode — const @beta
```
BuiltinComponentDef<UINodeData>
```
@@ -8301,7 +8301,7 @@ static new (): UIVisibilityPlugin
static prototype: UIVisibilityPlugin
```
-## UIVisual — const @experimental
+## UIVisual — const @beta
```
BuiltinComponentDef<UIVisualData>
```
@@ -10405,7 +10405,7 @@ ParticlePlugin
(grid: NavGrid, path: Cell[]): Vec2[]
```
-## percent — const @experimental
+## percent — const @public
```
(n: number) => Dimension
```
@@ -10495,7 +10495,7 @@ PrefabsPlugin
(): string[]
```
-## px — const @experimental
+## px — const @public
```
(n: number) => Dimension
```
@@ -11055,7 +11055,7 @@ ServicesPlugin
(raw: number): TileStamp
```
-## spawnUIEntity — function @experimental
+## spawnUIEntity — function @beta
```
(init: UIEntityInit): Entity
```
@@ -11120,7 +11120,7 @@ TextPlugin
(): Record<string, ButtonStateVisual>
```
-## themeColors — function @experimental
+## themeColors — function @beta
```
(): ThemeColors
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 6217af90b..4e77804d2 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: 107 public · 40 beta · 1362 experimental · 3 deprecated
+Symbols: 111 public · 52 beta · 1346 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1701,7 +1701,7 @@ ComponentDef<ChainColliderData>
@internal _filterType: "changed"
```
-## CharacterController — const @experimental
+## CharacterController — const @beta
```
ComponentDef<CharacterControllerData>
```
@@ -2261,13 +2261,13 @@ ignoreEntityNames: readonly string[] | undefined
ignoreMetadataKeys: readonly string[] | undefined
```
-## Dimension — interface @experimental
+## Dimension — interface @public
```
unit: number
value: number
```
-## DimensionUnit — type @experimental
+## DimensionUnit — type @public
```
(typeof DimensionUnit)[keyof typeof DimensionUnit]
```
@@ -4648,7 +4648,7 @@ static prototype: PerceptionPlugin
ComponentDef<{}>
```
-## Physics — const @experimental
+## Physics — const @beta
```
ResourceDef<PhysicsAPI>
```
@@ -4665,7 +4665,7 @@ other: number
typeof PhysicsEventType[keyof typeof PhysicsEventType]
```
-## PhysicsEvents — const @experimental
+## PhysicsEvents — const @beta
```
ResourceDef<PhysicsEventsData>
```
@@ -6463,12 +6463,12 @@ rolloff: number
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
-## Spine — const @experimental
+## Spine — const @beta
```
ResourceDef<SpineManager>
```
-## SpineAnimation — const @experimental
+## SpineAnimation — const @beta
```
BuiltinComponentDef<SpineAnimationData>
```
@@ -7203,7 +7203,7 @@ textureId: number
(typeof TextureWrap)[keyof typeof TextureWrap]
```
-## ThemeColors — interface @experimental
+## ThemeColors — interface @beta
```
backdrop: Color
control: Color
@@ -7824,7 +7824,7 @@ static prototype: TweenSequence
(typeof TweenTarget)[keyof typeof TweenTarget]
```
-## UICameraData — interface @experimental
+## UICameraData — interface @beta
```
screenH: number
screenW: number
@@ -7842,7 +7842,7 @@ worldRight: number
worldTop: number
```
-## UICameraInfo — const @experimental
+## UICameraInfo — const @beta
```
ResourceDef<UICameraData>
```
@@ -8007,7 +8007,7 @@ static new (): UIMaskPlugin
static prototype: UIMaskPlugin
```
-## UINode — const @experimental
+## UINode — const @beta
```
BuiltinComponentDef<UINodeData>
```
@@ -8103,7 +8103,7 @@ static new (): UIVisibilityPlugin
static prototype: UIVisibilityPlugin
```
-## UIVisual — const @experimental
+## UIVisual — const @beta
```
BuiltinComponentDef<UIVisualData>
```
@@ -10167,7 +10167,7 @@ ParticlePlugin
(grid: NavGrid, path: Cell[]): Vec2[]
```
-## percent — const @experimental
+## percent — const @public
```
(n: number) => Dimension
```
@@ -10257,7 +10257,7 @@ PrefabsPlugin
(): string[]
```
-## px — const @experimental
+## px — const @public
```
(n: number) => Dimension
```
@@ -10817,7 +10817,7 @@ ServicesPlugin
(raw: number): TileStamp
```
-## spawnUIEntity — function @experimental
+## spawnUIEntity — function @beta
```
(init: UIEntityInit): Entity
```
@@ -10882,7 +10882,7 @@ TextPlugin
(): Record<string, ButtonStateVisual>
```
-## themeColors — function @experimental
+## themeColors — function @beta
```
(): ThemeColors
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 2ebe114ac..f3374c45e 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: 107 public · 38 beta · 1383 experimental · 3 deprecated
+Symbols: 111 public · 50 beta · 1367 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1701,7 +1701,7 @@ ComponentDef<ChainColliderData>
@internal _filterType: "changed"
```
-## CharacterController — const @experimental
+## CharacterController — const @beta
```
ComponentDef<CharacterControllerData>
```
@@ -2261,13 +2261,13 @@ ignoreEntityNames: readonly string[] | undefined
ignoreMetadataKeys: readonly string[] | undefined
```
-## Dimension — interface @experimental
+## Dimension — interface @public
```
unit: number
value: number
```
-## DimensionUnit — type @experimental
+## DimensionUnit — type @public
```
(typeof DimensionUnit)[keyof typeof DimensionUnit]
```
@@ -4893,7 +4893,7 @@ static prototype: PerceptionPlugin
ComponentDef<{}>
```
-## Physics — const @experimental
+## Physics — const @beta
```
ResourceDef<PhysicsAPI>
```
@@ -4910,7 +4910,7 @@ other: number
typeof PhysicsEventType[keyof typeof PhysicsEventType]
```
-## PhysicsEvents — const @experimental
+## PhysicsEvents — const @beta
```
ResourceDef<PhysicsEventsData>
```
@@ -6708,12 +6708,12 @@ rolloff: number
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
-## Spine — const @experimental
+## Spine — const @beta
```
ResourceDef<SpineManager>
```
-## SpineAnimation — const @experimental
+## SpineAnimation — const @beta
```
BuiltinComponentDef<SpineAnimationData>
```
@@ -7448,7 +7448,7 @@ textureId: number
(typeof TextureWrap)[keyof typeof TextureWrap]
```
-## ThemeColors — interface @experimental
+## ThemeColors — interface @beta
```
backdrop: Color
control: Color
@@ -8069,7 +8069,7 @@ static prototype: TweenSequence
(typeof TweenTarget)[keyof typeof TweenTarget]
```
-## UICameraData — interface @experimental
+## UICameraData — interface @beta
```
screenH: number
screenW: number
@@ -8087,7 +8087,7 @@ worldRight: number
worldTop: number
```
-## UICameraInfo — const @experimental
+## UICameraInfo — const @beta
```
ResourceDef<UICameraData>
```
@@ -8252,7 +8252,7 @@ static new (): UIMaskPlugin
static prototype: UIMaskPlugin
```
-## UINode — const @experimental
+## UINode — const @beta
```
BuiltinComponentDef<UINodeData>
```
@@ -8348,7 +8348,7 @@ static new (): UIVisibilityPlugin
static prototype: UIVisibilityPlugin
```
-## UIVisual — const @experimental
+## UIVisual — const @beta
```
BuiltinComponentDef<UIVisualData>
```
@@ -10417,7 +10417,7 @@ ParticlePlugin
(grid: NavGrid, path: Cell[]): Vec2[]
```
-## percent — const @experimental
+## percent — const @public
```
(n: number) => Dimension
```
@@ -10507,7 +10507,7 @@ PrefabsPlugin
(): string[]
```
-## px — const @experimental
+## px — const @public
```
(n: number) => Dimension
```
@@ -11067,7 +11067,7 @@ ServicesPlugin
(raw: number): TileStamp
```
-## spawnUIEntity — function @experimental
+## spawnUIEntity — function @beta
```
(init: UIEntityInit): Entity
```
@@ -11132,7 +11132,7 @@ TextPlugin
(): Record<string, ButtonStateVisual>
```
-## themeColors — function @experimental
+## themeColors — function @beta
```
(): ThemeColors
```
diff --git a/sdk/etc/physics.api.md b/sdk/etc/physics.api.md
index 74ffb45ca..050a653cf 100644
--- a/sdk/etc/physics.api.md
+++ b/sdk/etc/physics.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/physics
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 0 public · 0 beta · 68 experimental · 0 deprecated
+Symbols: 0 public · 3 beta · 65 experimental · 0 deprecated
## BodyType — enum @experimental
```
@@ -69,7 +69,7 @@ points: Vec2[]
restitution: number
```
-## CharacterController — const @experimental
+## CharacterController — const @beta
```
ComponentDef<CharacterControllerData>
```
@@ -248,7 +248,7 @@ enabled: boolean
normal: Vec2
```
-## Physics — const @experimental
+## Physics — const @beta
```
ResourceDef<PhysicsAPI>
```
@@ -355,7 +355,7 @@ showVelocity: boolean
typeof PhysicsEventType[keyof typeof PhysicsEventType]
```
-## PhysicsEvents — const @experimental
+## PhysicsEvents — const @beta
```
ResourceDef<PhysicsEventsData>
```
diff --git a/sdk/etc/spine.api.md b/sdk/etc/spine.api.md
index 062084adb..b5d3ee913 100644
--- a/sdk/etc/spine.api.md
+++ b/sdk/etc/spine.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/spine
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 0 public · 0 beta · 22 experimental · 0 deprecated
+Symbols: 0 public · 1 beta · 21 experimental · 0 deprecated
## ConstraintList — interface @experimental
```
@@ -62,7 +62,7 @@ resolveRef: ((ref: string) => string) | undefined
textureImportSettings: ((ref: string) => ParsedTextureImportSettings | undefined) | undefined
```
-## Spine — const @experimental
+## Spine — const @beta
```
ResourceDef<SpineManager>
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index fac556933..5940b81e1 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: 107 public · 38 beta · 1373 experimental · 3 deprecated
+Symbols: 111 public · 50 beta · 1357 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1701,7 +1701,7 @@ ComponentDef<ChainColliderData>
@internal _filterType: "changed"
```
-## CharacterController — const @experimental
+## CharacterController — const @beta
```
ComponentDef<CharacterControllerData>
```
@@ -2261,13 +2261,13 @@ ignoreEntityNames: readonly string[] | undefined
ignoreMetadataKeys: readonly string[] | undefined
```
-## Dimension — interface @experimental
+## Dimension — interface @public
```
unit: number
value: number
```
-## DimensionUnit — type @experimental
+## DimensionUnit — type @public
```
(typeof DimensionUnit)[keyof typeof DimensionUnit]
```
@@ -4655,7 +4655,7 @@ static prototype: PerceptionPlugin
ComponentDef<{}>
```
-## Physics — const @experimental
+## Physics — const @beta
```
ResourceDef<PhysicsAPI>
```
@@ -4672,7 +4672,7 @@ other: number
typeof PhysicsEventType[keyof typeof PhysicsEventType]
```
-## PhysicsEvents — const @experimental
+## PhysicsEvents — const @beta
```
ResourceDef<PhysicsEventsData>
```
@@ -6470,12 +6470,12 @@ rolloff: number
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
-## Spine — const @experimental
+## Spine — const @beta
```
ResourceDef<SpineManager>
```
-## SpineAnimation — const @experimental
+## SpineAnimation — const @beta
```
BuiltinComponentDef<SpineAnimationData>
```
@@ -7210,7 +7210,7 @@ textureId: number
(typeof TextureWrap)[keyof typeof TextureWrap]
```
-## ThemeColors — interface @experimental
+## ThemeColors — interface @beta
```
backdrop: Color
control: Color
@@ -7831,7 +7831,7 @@ static prototype: TweenSequence
(typeof TweenTarget)[keyof typeof TweenTarget]
```
-## UICameraData — interface @experimental
+## UICameraData — interface @beta
```
screenH: number
screenW: number
@@ -7849,7 +7849,7 @@ worldRight: number
worldTop: number
```
-## UICameraInfo — const @experimental
+## UICameraInfo — const @beta
```
ResourceDef<UICameraData>
```
@@ -8014,7 +8014,7 @@ static new (): UIMaskPlugin
static prototype: UIMaskPlugin
```
-## UINode — const @experimental
+## UINode — const @beta
```
BuiltinComponentDef<UINodeData>
```
@@ -8110,7 +8110,7 @@ static new (): UIVisibilityPlugin
static prototype: UIVisibilityPlugin
```
-## UIVisual — const @experimental
+## UIVisual — const @beta
```
BuiltinComponentDef<UIVisualData>
```
@@ -10189,7 +10189,7 @@ ParticlePlugin
(grid: NavGrid, path: Cell[]): Vec2[]
```
-## percent — const @experimental
+## percent — const @public
```
(n: number) => Dimension
```
@@ -10279,7 +10279,7 @@ PrefabsPlugin
(): string[]
```
-## px — const @experimental
+## px — const @public
```
(n: number) => Dimension
```
@@ -10839,7 +10839,7 @@ ServicesPlugin
(raw: number): TileStamp
```
-## spawnUIEntity — function @experimental
+## spawnUIEntity — function @beta
```
(init: UIEntityInit): Entity
```
@@ -10904,7 +10904,7 @@ TextPlugin
(): Record<string, ButtonStateVisual>
```
-## themeColors — function @experimental
+## themeColors — function @beta
```
(): ThemeColors
```
diff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.ts
index e7c0d3e03..8f16d42eb 100644
--- a/sdk/src/audio/Audio.ts
+++ b/sdk/src/audio/Audio.ts
@@ -705,4 +705,12 @@ export class AudioAPI {
}
/** Resource handle for the per-app audio API. */
+/**
+ * Playback, buses and mixing, as `Res(Audio)` hands it over.
+ *
+ * Deliberately NOT `@beta`, which would claim the shape is supported: no example
+ * in the repository uses audio at all, so nothing would notice a break in it. It
+ * stays experimental until something certifies it — see the `audio` entry in
+ * KNOWN_GAPS.
+ */
export const Audio = defineResource<AudioAPI>(null!, 'Audio');
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index 69ed9058b..ebdb17d18 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -930,6 +930,12 @@ export const BitmapText = defineBuiltin<BitmapTextData>('BitmapText',
metaDefaults<BitmapTextData>('BitmapText')
);
+/**
+ * A Spine skeleton on an entity — which skeleton and atlas, and what it is
+ * playing. Driving it is {@link Spine}'s job; this is the data it drives.
+ *
+ * @beta
+ */
export const SpineAnimation = defineBuiltin<SpineAnimationData>('SpineAnimation',
metaDefaults<SpineAnimationData>('SpineAnimation')
);
diff --git a/sdk/src/physics/CharacterController.ts b/sdk/src/physics/CharacterController.ts
index 153c29bb3..0c4a25263 100644
--- a/sdk/src/physics/CharacterController.ts
+++ b/sdk/src/physics/CharacterController.ts
@@ -71,6 +71,12 @@ export interface CharacterControllerData {
realVelocity: Vec2;
}
+/**
+ * A kinematic mover for a player or an NPC: it sweeps rather than being pushed,
+ * so it never tunnels and never inherits a rigid body's momentum.
+ *
+ * @beta
+ */
export const CharacterController = defineComponent<CharacterControllerData>('CharacterController', {
velocity: { x: 0, y: 0 },
up: { x: 0, y: 1 },
diff --git a/sdk/src/physics/Physics.ts b/sdk/src/physics/Physics.ts
index eda8111f8..678f9e5d2 100644
--- a/sdk/src/physics/Physics.ts
+++ b/sdk/src/physics/Physics.ts
@@ -541,4 +541,14 @@ export class PhysicsAPI {
* Game code reads it as `Res(Physics)` / `app.getResource(Physics)` to call forces,
* impulses, joint helpers, raycasts, etc.
*/
+/**
+ * The physics world, as `Res(Physics)` hands it over — queries, impulses and the
+ * step's own knobs. Bodies and colliders are components; this is for what has no
+ * component to be.
+ *
+ * `@beta`: the corpus reaches three of thirty-seven physics symbols, so the
+ * vocabulary is settled well ahead of the evidence for it.
+ *
+ * @beta
+ */
export const Physics = defineResource<PhysicsAPI>(null!, 'Physics');
diff --git a/sdk/src/physics/PhysicsTypes.ts b/sdk/src/physics/PhysicsTypes.ts
index aa361d0ef..4650dfd5d 100644
--- a/sdk/src/physics/PhysicsTypes.ts
+++ b/sdk/src/physics/PhysicsTypes.ts
@@ -76,6 +76,13 @@ export interface PhysicsEventsData {
sensorExits: SensorEvent[];
}
+/**
+ * This step's collision and trigger events, as a resource. Drained per fixed
+ * step, so a system reading it must run inside one — a read from `Update` sees
+ * whatever the last step left.
+ *
+ * @beta
+ */
export const PhysicsEvents = defineResource<PhysicsEventsData>({
collisionEnters: [],
collisionExits: [],
diff --git a/sdk/src/spine/SpinePlugin.ts b/sdk/src/spine/SpinePlugin.ts
index 089f06278..2dfd9157f 100644
--- a/sdk/src/spine/SpinePlugin.ts
+++ b/sdk/src/spine/SpinePlugin.ts
@@ -38,6 +38,12 @@ export const SpineEvents = defineResource<SpineEventsData>({ events: [] }, 'Spin
* (a realm with the spine side-module). Read it with `Res(Spine)` to control
* playback — `setAnimation` / `setSkin` / `setMixDuration` / `getAnimations` / etc.
*/
+/**
+ * Spine playback, as `Res(Spine)` hands it over. Reached through the
+ * `esengine/spine` entry, since the runtime is a side module a project opts into.
+ *
+ * @beta
+ */
export const Spine = defineResource<SpineManager>(null!, 'Spine');
const SPINE_TYPE_MAP: Record<number, SpineEventType | null> = {
diff --git a/sdk/src/ui/core/compose.ts b/sdk/src/ui/core/compose.ts
index 4bc0d531c..70c61f2fb 100644
--- a/sdk/src/ui/core/compose.ts
+++ b/sdk/src/ui/core/compose.ts
@@ -179,10 +179,11 @@ export interface UIEntityInit {
}
/**
- * Spawn a UI entity with Transform + UINode, optionally UIVisual and
- * Text, optionally parented. Returns the entity.
+ * Spawn a UI entity — Transform and UINode always, UIVisual and Text when the
+ * init asks for them, parented when it names a parent. Every built-in widget is
+ * composed from this, so a hand-built node and a widget are the same thing.
*
- * Widgets compose with this to avoid repeating the same insert dance.
+ * @beta
*/
export function spawnUIEntity(init: UIEntityInit): Entity {
const { world } = init;
diff --git a/sdk/src/ui/core/dimension.ts b/sdk/src/ui/core/dimension.ts
index c8752467a..d6880dfd1 100644
--- a/sdk/src/ui/core/dimension.ts
+++ b/sdk/src/ui/core/dimension.ts
@@ -11,7 +11,8 @@
* `unit` an integer); these helpers give it a typed, ergonomic authoring API.
*/
-/** How a {@link Dimension}'s `value` is interpreted. Mirrors the C++ u8 unit. */
+/** How a {@link Dimension}'s `value` is interpreted. Mirrors the C++ u8 unit.
+ * @public */
export const DimensionUnit = {
/** Absolute pixels. */
Px: 0,
@@ -20,21 +21,31 @@ export const DimensionUnit = {
/** Content-/layout-driven; `value` is ignored. */
Auto: 2,
} as const;
+/** @public */
export type DimensionUnit = (typeof DimensionUnit)[keyof typeof DimensionUnit];
-/** A CSS-style length. Matches the generated `Dimension` interface (`{ value, unit }`). */
+/**
+ * A CSS-style length. Plain data matching the generated `Dimension` struct, so it
+ * crosses to the engine as memory rather than being converted.
+ *
+ * @public
+ */
export interface Dimension {
value: number;
unit: number;
}
-/** `n` pixels. */
+/** `n` pixels — a design pixel, which at the project's design resolution is one
+ * screen pixel and scales with it thereafter.
+ * @public */
export const px = (n: number): Dimension => ({ value: n, unit: DimensionUnit.Px });
-/** `n` percent of the parent axis (0..100). */
+/** `n` percent of the parent axis (0..100), not a 0..1 fraction.
+ * @public */
export const percent = (n: number): Dimension => ({ value: n, unit: DimensionUnit.Percent });
-/** Content-/layout-driven length (Yoga `auto`). */
+/** Content-/layout-driven length (Yoga `auto`); `value` is ignored. Not frozen
+ * with its two siblings: no certified game asks for one. */
export const auto = (): Dimension => ({ value: 0, unit: DimensionUnit.Auto });
/** True when the dimension is the content-/layout-driven `auto` length. */
diff --git a/sdk/src/ui/core/ui-camera-info.ts b/sdk/src/ui/core/ui-camera-info.ts
index 8342eaf2a..47daa45f2 100644
--- a/sdk/src/ui/core/ui-camera-info.ts
+++ b/sdk/src/ui/core/ui-camera-info.ts
@@ -2,6 +2,12 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { defineResource } from '../../ecs/resource';
+/**
+ * The surface UI lays out against: its pixel size and the scale mapping design
+ * pixels onto it. Written by the camera plugin before layout runs.
+ *
+ * @beta
+ */
export interface UICameraData {
viewProjection: Float32Array;
vpX: number;
@@ -19,6 +25,9 @@ export interface UICameraData {
valid: boolean;
}
+/** The UI surface, as a resource — what a system reads to place something in
+ * screen terms rather than design terms.
+ * @beta */
export const UICameraInfo = defineResource<UICameraData>({
viewProjection: new Float32Array(16),
vpX: 0, vpY: 0, vpW: 0, vpH: 0,
diff --git a/sdk/src/ui/core/ui-node.ts b/sdk/src/ui/core/ui-node.ts
index 3c7db9f92..715c79236 100644
--- a/sdk/src/ui/core/ui-node.ts
+++ b/sdk/src/ui/core/ui-node.ts
@@ -61,6 +61,16 @@ export interface UINodeData {
insetBottom: Dimension;
}
+/**
+ * A layout box. Under a Canvas its size and position come from the flex layout
+ * rather than from Transform, which the layout writes.
+ *
+ * `@beta`: anchors, insets and the theme tokens beside them are the newest part
+ * of the UI, and the corpus reaches thirty-three of a hundred and fifteen UI
+ * symbols.
+ *
+ * @beta
+ */
export const UINode = defineBuiltin<UINodeData>('UINode', {
position: 0,
display: 0,
diff --git a/sdk/src/ui/core/ui-visual.ts b/sdk/src/ui/core/ui-visual.ts
index 0c9c5ec16..39eac28b7 100644
--- a/sdk/src/ui/core/ui-visual.ts
+++ b/sdk/src/ui/core/ui-visual.ts
@@ -56,6 +56,12 @@ export interface UIVisualData {
enabled: boolean;
}
+/**
+ * What a {@link UINode} draws — a colour, a texture, a nine-slice, a tiled fill
+ * or a partial one. The node decides the box; this decides what fills it.
+ *
+ * @beta
+ */
export const UIVisual = defineBuiltin<UIVisualData>('UIVisual', {
visualType: UIVisualType.None,
texture: 0,
diff --git a/sdk/src/ui/theme/tokens.ts b/sdk/src/ui/theme/tokens.ts
index 2d4f73050..8464761e5 100644
--- a/sdk/src/ui/theme/tokens.ts
+++ b/sdk/src/ui/theme/tokens.ts
@@ -13,7 +13,12 @@
*/
import type { Color } from '../../types';
-/** Semantic color roles consumed by widgets. */
+/**
+ * Semantic colour roles widgets read, so a project restyles by naming roles
+ * rather than by reaching into each widget.
+ *
+ * @beta
+ */
export interface ThemeColors {
/** Dialog / panel background. */
surface: Color;
@@ -171,7 +176,9 @@ export function setTheme(tokens: ThemeTokens): void {
activeTheme = tokens;
}
-/** Convenience: the active color palette. */
+/** The active colour palette — what a widget reads at build time, so a theme
+ * swap after that needs a rebuild rather than a repaint.
+ * @beta */
export function themeColors(): ThemeColors {
return activeTheme.colors;
}
diff --git a/tools/check-freeze-bar.mjs b/tools/check-freeze-bar.mjs
index 70e355450..bbf090739 100644
--- a/tools/check-freeze-bar.mjs
+++ b/tools/check-freeze-bar.mjs
@@ -148,9 +148,11 @@ function testedIdentifiers() {
return seen;
}
-const ESENGINE_IMPORT = /import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]esengine['"]/g;
+// Every entry, not just the root one: the SDK ships nine, and a symbol reached
+// through `esengine/spine` is as exercised as one reached through `esengine`.
+const ESENGINE_IMPORT = /import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]esengine(?:\/[^'"]+)?['"]/g;
-/** Symbols each golden project imports from 'esengine', as `name -> [projectId]`. */
+/** Symbols each golden project imports from an `esengine` entry, as `name -> [projectId]`. */
function exercisedByGolden() {
const out = new Map();
for (const g of GOLDEN) {