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): Scene, Prefab and Assets are Beta, and the evidence is why

esenginee5902f6bea16
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 8fb01bc53..1f31337f5 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -2,8 +2,8 @@
"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",
"counts": {
"public": 107,
- "beta": 29,
- "experimental": 1494,
+ "beta": 45,
+ "experimental": 1478,
"deprecated": 3
},
"total": 1630,
@@ -1294,6 +1294,30 @@
}
],
"beta": [
+ {
+ "name": "Assets",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "AssetsData",
+ "kind": "type",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "Camera",
"kind": "const",
@@ -1366,6 +1390,18 @@
"minigame"
]
},
+ {
+ "name": "InstantiatePrefabResult",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "MaterialGraph",
"kind": "interface",
@@ -1470,6 +1506,126 @@
"minigame"
]
},
+ {
+ "name": "PrefabOverride",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "PrefabServer",
+ "kind": "class",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "Prefabs",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "SceneConfig",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "SceneContext",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "SceneLoadProgressCallback",
+ "kind": "type",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "SceneManager",
+ "kind": "const",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "SceneManagerState",
+ "kind": "class",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "SceneStatus",
+ "kind": "type",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "SpawnOverride",
+ "kind": "type",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "TouchPoint",
"kind": "interface",
@@ -1482,6 +1638,30 @@
"minigame"
]
},
+ {
+ "name": "TransitionConfig",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "TransitionOptions",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "addNode",
"kind": "function",
@@ -1613,6 +1793,18 @@
"wechat",
"minigame"
]
+ },
+ {
+ "name": "transitionTo",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
}
]
}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 3681ba980..b9f45bb35 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 · 22 beta · 1379 experimental · 3 deprecated
+Symbols: 107 public · 38 beta · 1363 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -695,12 +695,12 @@ suffixes: string[] | undefined
wechatPackInclude: boolean
```
-## Assets — const @experimental
+## Assets — const @beta
```
ResourceDef<AssetsClass>
```
-## AssetsData — type @experimental
+## AssetsData — type @beta
```
@internal releaseTyped: (type: string, ref: string) => void
@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; trackedRefRows: number; }
@@ -3451,7 +3451,7 @@ overrides: PrefabOverride[] | undefined
parent: number | undefined
```
-## InstantiatePrefabResult — interface @experimental
+## InstantiatePrefabResult — interface @beta
```
entities: Map<number, number>
root: number
@@ -5284,7 +5284,7 @@ prefab: string
removed: string[]
```
-## PrefabOverride — interface @experimental
+## PrefabOverride — interface @beta
```
componentData: ComponentData | undefined
componentType: string | undefined
@@ -5295,14 +5295,14 @@ type: "property" | "component_added" | "component_replaced" | "component_removed
value: unknown
```
-## PrefabServer — class @experimental
+## PrefabServer — class @beta
```
instantiate: (pathOrAddress: string, options?: { baseUrl?: string; parent?: Entity; overrides?: SpawnOverride[]; scene?: boolean; }) => Promise<InstantiatePrefabResult>
static new (world: World, getAssets: () => AssetsClass, getScenes?: () => SceneManagerState | null): PrefabServer
static prototype: PrefabServer
```
-## Prefabs — const @experimental
+## Prefabs — const @beta
```
ResourceDef<PrefabServer>
```
@@ -5987,7 +5987,7 @@ data: Record<string, unknown>
type: string
```
-## SceneConfig — interface @experimental
+## SceneConfig — interface @beta
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
@@ -5997,7 +5997,7 @@ setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
systems: { schedule: Schedule; system: SystemDef; }[] | undefined
```
-## SceneContext — interface @experimental
+## SceneContext — interface @beta
```
adopt: (entity: Entity) => void
bindPostProcess: (camera: Entity, stack: PostProcessStack) => void
@@ -6046,17 +6046,17 @@ onMissingAssets: MissingAssetCallback | undefined
onProgress: SceneLoadProgressCallback | undefined
```
-## SceneLoadProgressCallback — type @experimental
+## SceneLoadProgressCallback — type @beta
```
(loaded: number, total: number) => void
```
-## SceneManager — const @experimental
+## SceneManager — const @beta
```
ResourceDef<SceneManagerState>
```
-## SceneManagerState — class @experimental
+## SceneManagerState — class @beta
```
bringToTop: (name: string) => void
getActive: () => string | null
@@ -6107,7 +6107,7 @@ persistent: boolean
scene: string
```
-## SceneStatus — type @experimental
+## SceneStatus — type @beta
```
'loading' | 'running' | 'paused' | 'sleeping' | 'unloading'
```
@@ -6463,7 +6463,7 @@ refDistance: number
rolloff: number
```
-## SpawnOverride — type @experimental
+## SpawnOverride — type @beta
```
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
@@ -7731,14 +7731,14 @@ worldRotation: Quat
worldScale: Vec3
```
-## TransitionConfig — interface @experimental
+## TransitionConfig — interface @beta
```
color: Color | undefined
duration: number
type: "fade"
```
-## TransitionOptions — interface @experimental
+## TransitionOptions — interface @beta
```
color: Color | undefined
duration: number | undefined
@@ -10942,7 +10942,7 @@ Plugin
TrailPlugin
```
-## transitionTo — function @experimental
+## transitionTo — function @beta
```
(host: App | SceneManagerState, targetScene: string, config: TransitionConfig): Promise<void>
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index d7d250633..54bcfd9f7 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 · 27 beta · 1398 experimental · 3 deprecated
+Symbols: 107 public · 43 beta · 1382 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -695,12 +695,12 @@ suffixes: string[] | undefined
wechatPackInclude: boolean
```
-## Assets — const @experimental
+## Assets — const @beta
```
ResourceDef<AssetsClass>
```
-## AssetsData — type @experimental
+## AssetsData — type @beta
```
@internal releaseTyped: (type: string, ref: string) => void
@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; trackedRefRows: number; }
@@ -3459,7 +3459,7 @@ overrides: PrefabOverride[] | undefined
parent: number | undefined
```
-## InstantiatePrefabResult — interface @experimental
+## InstantiatePrefabResult — interface @beta
```
entities: Map<number, number>
root: number
@@ -5467,7 +5467,7 @@ prefab: string
removed: string[]
```
-## PrefabOverride — interface @experimental
+## PrefabOverride — interface @beta
```
componentData: ComponentData | undefined
componentType: string | undefined
@@ -5478,14 +5478,14 @@ type: "property" | "component_added" | "component_replaced" | "component_removed
value: unknown
```
-## PrefabServer — class @experimental
+## PrefabServer — class @beta
```
instantiate: (pathOrAddress: string, options?: { baseUrl?: string; parent?: Entity; overrides?: SpawnOverride[]; scene?: boolean; }) => Promise<InstantiatePrefabResult>
static new (world: World, getAssets: () => AssetsClass, getScenes?: () => SceneManagerState | null): PrefabServer
static prototype: PrefabServer
```
-## Prefabs — const @experimental
+## Prefabs — const @beta
```
ResourceDef<PrefabServer>
```
@@ -6180,7 +6180,7 @@ data: Record<string, unknown>
type: string
```
-## SceneConfig — interface @experimental
+## SceneConfig — interface @beta
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
@@ -6190,7 +6190,7 @@ setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
systems: { schedule: Schedule; system: SystemDef; }[] | undefined
```
-## SceneContext — interface @experimental
+## SceneContext — interface @beta
```
adopt: (entity: Entity) => void
bindPostProcess: (camera: Entity, stack: PostProcessStack) => void
@@ -6239,17 +6239,17 @@ onMissingAssets: MissingAssetCallback | undefined
onProgress: SceneLoadProgressCallback | undefined
```
-## SceneLoadProgressCallback — type @experimental
+## SceneLoadProgressCallback — type @beta
```
(loaded: number, total: number) => void
```
-## SceneManager — const @experimental
+## SceneManager — const @beta
```
ResourceDef<SceneManagerState>
```
-## SceneManagerState — class @experimental
+## SceneManagerState — class @beta
```
bringToTop: (name: string) => void
getActive: () => string | null
@@ -6300,7 +6300,7 @@ persistent: boolean
scene: string
```
-## SceneStatus — type @experimental
+## SceneStatus — type @beta
```
'loading' | 'running' | 'paused' | 'sleeping' | 'unloading'
```
@@ -6656,7 +6656,7 @@ refDistance: number
rolloff: number
```
-## SpawnOverride — type @experimental
+## SpawnOverride — type @beta
```
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
@@ -7924,14 +7924,14 @@ worldRotation: Quat
worldScale: Vec3
```
-## TransitionConfig — interface @experimental
+## TransitionConfig — interface @beta
```
color: Color | undefined
duration: number
type: "fade"
```
-## TransitionOptions — interface @experimental
+## TransitionOptions — interface @beta
```
color: Color | undefined
duration: number | undefined
@@ -11185,7 +11185,7 @@ Plugin
TrailPlugin
```
-## transitionTo — function @experimental
+## transitionTo — function @beta
```
(host: App | SceneManagerState, targetScene: string, config: TransitionConfig): Promise<void>
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 545e474bf..6217af90b 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 · 24 beta · 1378 experimental · 3 deprecated
+Symbols: 107 public · 40 beta · 1362 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -690,12 +690,12 @@ suffixes: string[] | undefined
wechatPackInclude: boolean
```
-## Assets — const @experimental
+## Assets — const @beta
```
ResourceDef<AssetsClass>
```
-## AssetsData — type @experimental
+## AssetsData — type @beta
```
@internal releaseTyped: (type: string, ref: string) => void
@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; trackedRefRows: number; }
@@ -3446,7 +3446,7 @@ overrides: PrefabOverride[] | undefined
parent: number | undefined
```
-## InstantiatePrefabResult — interface @experimental
+## InstantiatePrefabResult — interface @beta
```
entities: Map<number, number>
root: number
@@ -5279,7 +5279,7 @@ prefab: string
removed: string[]
```
-## PrefabOverride — interface @experimental
+## PrefabOverride — interface @beta
```
componentData: ComponentData | undefined
componentType: string | undefined
@@ -5290,14 +5290,14 @@ type: "property" | "component_added" | "component_replaced" | "component_removed
value: unknown
```
-## PrefabServer — class @experimental
+## PrefabServer — class @beta
```
instantiate: (pathOrAddress: string, options?: { baseUrl?: string; parent?: Entity; overrides?: SpawnOverride[]; scene?: boolean; }) => Promise<InstantiatePrefabResult>
static new (world: World, getAssets: () => AssetsClass, getScenes?: () => SceneManagerState | null): PrefabServer
static prototype: PrefabServer
```
-## Prefabs — const @experimental
+## Prefabs — const @beta
```
ResourceDef<PrefabServer>
```
@@ -5982,7 +5982,7 @@ data: Record<string, unknown>
type: string
```
-## SceneConfig — interface @experimental
+## SceneConfig — interface @beta
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
@@ -5992,7 +5992,7 @@ setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
systems: { schedule: Schedule; system: SystemDef; }[] | undefined
```
-## SceneContext — interface @experimental
+## SceneContext — interface @beta
```
adopt: (entity: Entity) => void
bindPostProcess: (camera: Entity, stack: PostProcessStack) => void
@@ -6041,17 +6041,17 @@ onMissingAssets: MissingAssetCallback | undefined
onProgress: SceneLoadProgressCallback | undefined
```
-## SceneLoadProgressCallback — type @experimental
+## SceneLoadProgressCallback — type @beta
```
(loaded: number, total: number) => void
```
-## SceneManager — const @experimental
+## SceneManager — const @beta
```
ResourceDef<SceneManagerState>
```
-## SceneManagerState — class @experimental
+## SceneManagerState — class @beta
```
bringToTop: (name: string) => void
getActive: () => string | null
@@ -6102,7 +6102,7 @@ persistent: boolean
scene: string
```
-## SceneStatus — type @experimental
+## SceneStatus — type @beta
```
'loading' | 'running' | 'paused' | 'sleeping' | 'unloading'
```
@@ -6458,7 +6458,7 @@ refDistance: number
rolloff: number
```
-## SpawnOverride — type @experimental
+## SpawnOverride — type @beta
```
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
@@ -7726,14 +7726,14 @@ worldRotation: Quat
worldScale: Vec3
```
-## TransitionConfig — interface @experimental
+## TransitionConfig — interface @beta
```
color: Color | undefined
duration: number
type: "fade"
```
-## TransitionOptions — interface @experimental
+## TransitionOptions — interface @beta
```
color: Color | undefined
duration: number | undefined
@@ -10947,7 +10947,7 @@ Plugin
TrailPlugin
```
-## transitionTo — function @experimental
+## transitionTo — function @beta
```
(host: App | SceneManagerState, targetScene: string, config: TransitionConfig): Promise<void>
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 2d4a0747b..2ebe114ac 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 · 22 beta · 1399 experimental · 3 deprecated
+Symbols: 107 public · 38 beta · 1383 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -690,12 +690,12 @@ suffixes: string[] | undefined
wechatPackInclude: boolean
```
-## Assets — const @experimental
+## Assets — const @beta
```
ResourceDef<AssetsClass>
```
-## AssetsData — type @experimental
+## AssetsData — type @beta
```
@internal releaseTyped: (type: string, ref: string) => void
@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; trackedRefRows: number; }
@@ -3446,7 +3446,7 @@ overrides: PrefabOverride[] | undefined
parent: number | undefined
```
-## InstantiatePrefabResult — interface @experimental
+## InstantiatePrefabResult — interface @beta
```
entities: Map<number, number>
root: number
@@ -5524,7 +5524,7 @@ prefab: string
removed: string[]
```
-## PrefabOverride — interface @experimental
+## PrefabOverride — interface @beta
```
componentData: ComponentData | undefined
componentType: string | undefined
@@ -5535,14 +5535,14 @@ type: "property" | "component_added" | "component_replaced" | "component_removed
value: unknown
```
-## PrefabServer — class @experimental
+## PrefabServer — class @beta
```
instantiate: (pathOrAddress: string, options?: { baseUrl?: string; parent?: Entity; overrides?: SpawnOverride[]; scene?: boolean; }) => Promise<InstantiatePrefabResult>
static new (world: World, getAssets: () => AssetsClass, getScenes?: () => SceneManagerState | null): PrefabServer
static prototype: PrefabServer
```
-## Prefabs — const @experimental
+## Prefabs — const @beta
```
ResourceDef<PrefabServer>
```
@@ -6227,7 +6227,7 @@ data: Record<string, unknown>
type: string
```
-## SceneConfig — interface @experimental
+## SceneConfig — interface @beta
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
@@ -6237,7 +6237,7 @@ setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
systems: { schedule: Schedule; system: SystemDef; }[] | undefined
```
-## SceneContext — interface @experimental
+## SceneContext — interface @beta
```
adopt: (entity: Entity) => void
bindPostProcess: (camera: Entity, stack: PostProcessStack) => void
@@ -6286,17 +6286,17 @@ onMissingAssets: MissingAssetCallback | undefined
onProgress: SceneLoadProgressCallback | undefined
```
-## SceneLoadProgressCallback — type @experimental
+## SceneLoadProgressCallback — type @beta
```
(loaded: number, total: number) => void
```
-## SceneManager — const @experimental
+## SceneManager — const @beta
```
ResourceDef<SceneManagerState>
```
-## SceneManagerState — class @experimental
+## SceneManagerState — class @beta
```
bringToTop: (name: string) => void
getActive: () => string | null
@@ -6347,7 +6347,7 @@ persistent: boolean
scene: string
```
-## SceneStatus — type @experimental
+## SceneStatus — type @beta
```
'loading' | 'running' | 'paused' | 'sleeping' | 'unloading'
```
@@ -6703,7 +6703,7 @@ refDistance: number
rolloff: number
```
-## SpawnOverride — type @experimental
+## SpawnOverride — type @beta
```
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
@@ -7971,14 +7971,14 @@ worldRotation: Quat
worldScale: Vec3
```
-## TransitionConfig — interface @experimental
+## TransitionConfig — interface @beta
```
color: Color | undefined
duration: number
type: "fade"
```
-## TransitionOptions — interface @experimental
+## TransitionOptions — interface @beta
```
color: Color | undefined
duration: number | undefined
@@ -11197,7 +11197,7 @@ Plugin
TrailPlugin
```
-## transitionTo — function @experimental
+## transitionTo — function @beta
```
(host: App | SceneManagerState, targetScene: string, config: TransitionConfig): Promise<void>
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 184c07760..fac556933 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 · 22 beta · 1389 experimental · 3 deprecated
+Symbols: 107 public · 38 beta · 1373 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -690,12 +690,12 @@ suffixes: string[] | undefined
wechatPackInclude: boolean
```
-## Assets — const @experimental
+## Assets — const @beta
```
ResourceDef<AssetsClass>
```
-## AssetsData — type @experimental
+## AssetsData — type @beta
```
@internal releaseTyped: (type: string, ref: string) => void
@internal sizes: () => { textureCached: number; pendingLoads: number; refCounts: number; refRows: number; genericCaches: number; genericCached: number; handlePaths: number; invalidateListeners: number; registryEntries: number; trackedRefRows: number; }
@@ -3453,7 +3453,7 @@ overrides: PrefabOverride[] | undefined
parent: number | undefined
```
-## InstantiatePrefabResult — interface @experimental
+## InstantiatePrefabResult — interface @beta
```
entities: Map<number, number>
root: number
@@ -5286,7 +5286,7 @@ prefab: string
removed: string[]
```
-## PrefabOverride — interface @experimental
+## PrefabOverride — interface @beta
```
componentData: ComponentData | undefined
componentType: string | undefined
@@ -5297,14 +5297,14 @@ type: "property" | "component_added" | "component_replaced" | "component_removed
value: unknown
```
-## PrefabServer — class @experimental
+## PrefabServer — class @beta
```
instantiate: (pathOrAddress: string, options?: { baseUrl?: string; parent?: Entity; overrides?: SpawnOverride[]; scene?: boolean; }) => Promise<InstantiatePrefabResult>
static new (world: World, getAssets: () => AssetsClass, getScenes?: () => SceneManagerState | null): PrefabServer
static prototype: PrefabServer
```
-## Prefabs — const @experimental
+## Prefabs — const @beta
```
ResourceDef<PrefabServer>
```
@@ -5989,7 +5989,7 @@ data: Record<string, unknown>
type: string
```
-## SceneConfig — interface @experimental
+## SceneConfig — interface @beta
```
cleanup: ((ctx: SceneContext) => void) | undefined
data: SceneData | undefined
@@ -5999,7 +5999,7 @@ setup: ((ctx: SceneContext) => void | Promise<void>) | undefined
systems: { schedule: Schedule; system: SystemDef; }[] | undefined
```
-## SceneContext — interface @experimental
+## SceneContext — interface @beta
```
adopt: (entity: Entity) => void
bindPostProcess: (camera: Entity, stack: PostProcessStack) => void
@@ -6048,17 +6048,17 @@ onMissingAssets: MissingAssetCallback | undefined
onProgress: SceneLoadProgressCallback | undefined
```
-## SceneLoadProgressCallback — type @experimental
+## SceneLoadProgressCallback — type @beta
```
(loaded: number, total: number) => void
```
-## SceneManager — const @experimental
+## SceneManager — const @beta
```
ResourceDef<SceneManagerState>
```
-## SceneManagerState — class @experimental
+## SceneManagerState — class @beta
```
bringToTop: (name: string) => void
getActive: () => string | null
@@ -6109,7 +6109,7 @@ persistent: boolean
scene: string
```
-## SceneStatus — type @experimental
+## SceneStatus — type @beta
```
'loading' | 'running' | 'paused' | 'sleeping' | 'unloading'
```
@@ -6465,7 +6465,7 @@ refDistance: number
rolloff: number
```
-## SpawnOverride — type @experimental
+## SpawnOverride — type @beta
```
Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string }
```
@@ -7733,14 +7733,14 @@ worldRotation: Quat
worldScale: Vec3
```
-## TransitionConfig — interface @experimental
+## TransitionConfig — interface @beta
```
color: Color | undefined
duration: number
type: "fade"
```
-## TransitionOptions — interface @experimental
+## TransitionOptions — interface @beta
```
color: Color | undefined
duration: number | undefined
@@ -10969,7 +10969,7 @@ Plugin
TrailPlugin
```
-## transitionTo — function @experimental
+## transitionTo — function @beta
```
(host: App | SceneManagerState, targetScene: string, config: TransitionConfig): Promise<void>
```
diff --git a/sdk/src/asset/AssetPlugin.ts b/sdk/src/asset/AssetPlugin.ts
index a99962491..d7d443c6f 100644
--- a/sdk/src/asset/AssetPlugin.ts
+++ b/sdk/src/asset/AssetPlugin.ts
@@ -11,8 +11,25 @@ import { SpriteAnimation, type SpriteAnimationAPI } from '../animation/SpriteAni
import { Localization, type LocalizationAPI } from '../i18n/Localization';
import { log } from '../util/logger';
+/**
+ * The asset loader a system receives from `Res(Assets)`.
+ *
+ * `@beta`, and the evidence says so: of its members the certified corpus calls
+ * four, and a third of the rest is the host wiring a runtime in — resolvers,
+ * registries, the manifest, device-loss recovery — which is the embedding contract
+ * rather than anything a game writes.
+ *
+ * @beta
+ */
export type AssetsData = AssetsClass;
+/**
+ * The asset loader, as a resource. Rarely the door a game uses: scenes preload
+ * what they reference and components resolve their own assets, so this is for the
+ * cases that outlive a scene — hot updates, groups loaded on demand.
+ *
+ * @beta
+ */
export const Assets = defineResource<AssetsData>(
null!,
'Assets'
diff --git a/sdk/src/prefab.ts b/sdk/src/prefab.ts
index 5fae2863e..b95b67d84 100644
--- a/sdk/src/prefab.ts
+++ b/sdk/src/prefab.ts
@@ -42,6 +42,12 @@ export interface InstantiatePrefabOptions {
overrides?: PrefabOverride[];
}
+/**
+ * What instantiating a prefab answers: the root, and every entity the prefab
+ * brought with it.
+ *
+ * @beta
+ */
export interface InstantiatePrefabResult {
root: Entity;
entities: Map<number, Entity>;
diff --git a/sdk/src/prefab/prefabServer.ts b/sdk/src/prefab/prefabServer.ts
index 8ac33c543..2c5ef3754 100644
--- a/sdk/src/prefab/prefabServer.ts
+++ b/sdk/src/prefab/prefabServer.ts
@@ -17,9 +17,20 @@ import {
/**
* An override as written at a SPAWN: the entity id may be left out, and then it
* is the prefab's root — which is the entity a one-sprite prefab has.
+ *
+ * @beta
*/
export type SpawnOverride = Omit<PrefabOverride, 'prefabEntityId'> & { prefabEntityId?: string };
+/**
+ * Prefab instantiation, as `Res(Prefabs)` hands it over.
+ *
+ * `@beta`: `instantiate` is the whole surface and it has not moved, but its result
+ * and override shapes are spelled in the prefab document model, which is also the
+ * on-disk format — so their names are settled ahead of the shapes.
+ *
+ * @beta
+ */
export class PrefabServer {
private readonly world_: World;
private readonly getAssets_: () => AssetsClass;
@@ -116,6 +127,12 @@ function resolveSpawnOverrides(
});
}
+/**
+ * Prefab instantiation, as a resource. Spawning from a prefab is asynchronous
+ * because its assets may not be loaded yet.
+ *
+ * @beta
+ */
export const Prefabs = defineResource<PrefabServer>(null!, 'Prefabs');
export class PrefabsPlugin implements Plugin {
diff --git a/sdk/src/prefab/types.ts b/sdk/src/prefab/types.ts
index ae8e30c41..305179b6a 100644
--- a/sdk/src/prefab/types.ts
+++ b/sdk/src/prefab/types.ts
@@ -96,6 +96,12 @@ export interface NestedPrefabRef {
* - `metadata_removed` — delete one metadata key if present. Requires:
* metadataKey.
*/
+/**
+ * One field of one entity of a prefab, overridden at the instance. Also the
+ * on-disk shape a scene stores an instance's edits as.
+ *
+ * @beta
+ */
export interface PrefabOverride {
prefabEntityId: PrefabEntityId;
type:
diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.ts
index a25eb6e1e..88dcc8525 100644
--- a/sdk/src/scene/scene.ts
+++ b/sdk/src/scene/scene.ts
@@ -76,6 +76,8 @@ export interface LoadedSceneAssets {
spineKeys: Set<string>;
}
+/** Progress during a scene load, in assets: how many are done of how many.
+ * @beta */
export type SceneLoadProgressCallback = (loaded: number, total: number) => void;
export type MissingAssetCallback = (missing: import('../asset/Assets').MissingAsset[]) => void;
diff --git a/sdk/src/scene/sceneManager.ts b/sdk/src/scene/sceneManager.ts
index 2aed1b0b3..b3fbed088 100644
--- a/sdk/src/scene/sceneManager.ts
+++ b/sdk/src/scene/sceneManager.ts
@@ -27,8 +27,18 @@ import { log } from '../util/logger';
// Types
// =============================================================================
+/** Where a loaded scene is in its lifecycle. `paused` still draws; `sleeping`
+ * does not — see {@link SceneManagerState.pause} and `sleep`.
+ * @beta */
export type SceneStatus = 'loading' | 'running' | 'paused' | 'sleeping' | 'unloading';
+/**
+ * A scene as registered: where its data comes from, the systems that run while it
+ * is loaded, and hooks either side of its lifetime. `path` and `data` are
+ * alternatives — a scene either loads from disk or is handed its content.
+ *
+ * @beta
+ */
export interface SceneConfig {
name: string;
path?: string;
@@ -38,6 +48,13 @@ export interface SceneConfig {
cleanup?: (ctx: SceneContext) => void;
}
+/**
+ * A live scene, as `setup` receives it and `load` answers with. Everything it
+ * spawns or adopts is scene-owned and goes away when the scene unloads, which is
+ * why an entity or an asset reference nothing records is one nothing releases.
+ *
+ * @beta
+ */
export interface SceneContext {
readonly name: string;
readonly entities: ReadonlySet<Entity>;
@@ -58,6 +75,12 @@ export interface SceneContext {
setPersistent(entity: Entity, persistent: boolean): void;
}
+/**
+ * How a switch, unload or reload behaves. `keepPersistent` decides whether
+ * entities marked persistent survive it.
+ *
+ * @beta
+ */
export interface TransitionOptions {
keepPersistent?: boolean;
transition?: 'none' | 'fade';
@@ -187,6 +210,16 @@ export class SceneLoadCancelled extends Error {
}
}
+/**
+ * Scene loading and transitions, as `Res(SceneManager)` hands it over. A scene is
+ * a unit of ownership as much as of content: what it spawned is despawned and what
+ * it acquired is released when it unloads.
+ *
+ * `@beta`: the vocabulary is settled, but one certified project drives it against
+ * twenty-six signatures — thin evidence for that breadth of promise.
+ *
+ * @beta
+ */
export class SceneManagerState {
private readonly app_: App;
private readonly configs_ = new Map<string, SceneConfig>();
@@ -751,6 +784,12 @@ export class SceneManagerState {
// Scene Manager Resource
// =============================================================================
+/**
+ * Scene loading, as a resource. Registered by the scene plugin, so a bare `App`
+ * without it has no scenes to manage.
+ *
+ * @beta
+ */
export const SceneManager = defineResource<SceneManagerState>(
null!,
'SceneManager'
diff --git a/sdk/src/scene/sceneTransition.ts b/sdk/src/scene/sceneTransition.ts
index 05520537d..c88b33cd7 100644
--- a/sdk/src/scene/sceneTransition.ts
+++ b/sdk/src/scene/sceneTransition.ts
@@ -9,6 +9,8 @@ import type { App } from '../app/app';
import type { Color } from '../types';
import { SceneManager, SceneManagerState } from './sceneManager';
+/** A cross-scene fade: how long, and what colour it passes through.
+ * @beta */
export interface TransitionConfig {
duration: number;
type: 'fade';
@@ -18,6 +20,8 @@ export interface TransitionConfig {
/**
* Pass the App from host code, or the `Res(SceneManager)` state from inside a
* system.
+ *
+ * @beta
*/
export async function transitionTo(
host: App | SceneManagerState,
diff --git a/tools/check-freeze-bar.mjs b/tools/check-freeze-bar.mjs
index de822729f..70e355450 100644
--- a/tools/check-freeze-bar.mjs
+++ b/tools/check-freeze-bar.mjs
@@ -86,6 +86,10 @@ export const BLOCKED = {
// and the Inspector still offers the dropdown — now labelled as such.
TextOverflow: { needs: 'named by no SDK test', why: 'no layout or render path honours it, so there is no behaviour to pin' },
};
+// Scene, Prefab and Assets are NOT here, and the gate is why: each PASSES the bar,
+// so what holds them at @beta is a judgement it cannot make — thin evidence for the
+// BREADTH of the promise is not a missing criterion. The @beta tag records that,
+// at the declaration, with its reason.
/** Snapshot kinds that a game calls at runtime; the rest are shapes. */
const VALUE_KINDS = new Set(['class', 'enum', 'function', 'const', 'value', 'namespace']);