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): a frozen signature may only name types a creator can spell

esengine0ce38c4d20f6
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index e563488f4..8fb01bc53 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -1,12 +1,12 @@
{
"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",
"counts": {
- "public": 101,
+ "public": 107,
"beta": 29,
- "experimental": 1495,
+ "experimental": 1494,
"deprecated": 3
},
- "total": 1625,
+ "total": 1630,
"public": [
{
"name": "ActionDef",
@@ -56,6 +56,42 @@
"minigame"
]
},
+ {
+ "name": "AssetFieldMeta",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "AssetFieldType",
+ "kind": "type",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "AssetRef",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "Axis1D",
"kind": "const",
@@ -236,6 +272,18 @@
"minigame"
]
},
+ {
+ "name": "ComponentsData",
+ "kind": "type",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "Entity",
"kind": "type",
@@ -836,6 +884,18 @@
"minigame"
]
},
+ {
+ "name": "SkeletalFieldMeta",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "Sprite",
"kind": "const",
@@ -1040,6 +1100,18 @@
"minigame"
]
},
+ {
+ "name": "UnwrapQueryArg",
+ "kind": "type",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "Vec2",
"kind": "interface",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 5656dde1e..3681ba980 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: 101 public · 22 beta · 1380 experimental · 3 deprecated
+Symbols: 107 public · 22 beta · 1379 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -605,7 +605,13 @@ static prototype: ArrayDataSource<any>
'json' | 'text' | 'binary' | 'image' | 'audio'
```
-## AssetFieldType — type @experimental
+## AssetFieldMeta — interface @public
+```
+field: string
+type: AssetFieldType
+```
+
+## AssetFieldType — type @public
```
'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller'
```
@@ -639,6 +645,12 @@ static new (): AssetPlugin
static prototype: AssetPlugin
```
+## AssetRef — interface @public
+```
+path: string
+type: string
+```
+
## AssetRefCounter — class @experimental
```
addFontRef: (path: string, entity: number) => void
@@ -1835,6 +1847,7 @@ keyof ThemeColors
## CommandsInstance — class @public
```
+@internal spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => void
despawn: (entity: Entity) => CommandsInstance
entity: (entity: Entity) => EntityCommands
flush: () => void
@@ -1842,7 +1855,6 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstance
queueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => void
queueRemove: (entity: Entity, component: AnyComponentDef) => void
spawn: (name?: string) => EntityCommands
-spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => void
static new (world: World, resources: ResourceStorage): CommandsInstance
static prototype: CommandsInstance
```
@@ -1907,6 +1919,13 @@ skeletalFields: SkeletalFieldMeta | undefined
transient: boolean | undefined
```
+## ComponentsData — type @public
+```
+{
+ [K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;
+}
+```
+
## CompressorEffectDef — interface @experimental
```
attack: number | undefined
@@ -6378,6 +6397,13 @@ Local = 1
World = 0
```
+## SkeletalFieldMeta — interface @public
+```
+atlasField: string
+runtime: string
+skeletonField: string
+```
+
## SliceBorder — interface @experimental
```
bottom: number
@@ -8141,6 +8167,14 @@ number | Vec2 | Vec3 | Vec4 | number[] | TextureRef
() => void
```
+## UnwrapQueryArg — type @public
+```
+T extends MutWrapper<infer C> ? C :
+ T extends AddedWrapper<infer C> ? C :
+ T extends ChangedWrapper<infer C> ? C :
+ T
+```
+
## ValidatePrefabOptions — interface @experimental
```
instanceOverrides: readonly PrefabOverride[] | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 354736e1d..d7d250633 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: 101 public · 27 beta · 1399 experimental · 3 deprecated
+Symbols: 107 public · 27 beta · 1398 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -605,7 +605,13 @@ static prototype: ArrayDataSource<any>
'json' | 'text' | 'binary' | 'image' | 'audio'
```
-## AssetFieldType — type @experimental
+## AssetFieldMeta — interface @public
+```
+field: string
+type: AssetFieldType
+```
+
+## AssetFieldType — type @public
```
'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller'
```
@@ -639,6 +645,12 @@ static new (): AssetPlugin
static prototype: AssetPlugin
```
+## AssetRef — interface @public
+```
+path: string
+type: string
+```
+
## AssetRefCounter — class @experimental
```
addFontRef: (path: string, entity: number) => void
@@ -1835,6 +1847,7 @@ keyof ThemeColors
## CommandsInstance — class @public
```
+@internal spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => void
despawn: (entity: Entity) => CommandsInstance
entity: (entity: Entity) => EntityCommands
flush: () => void
@@ -1842,7 +1855,6 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstance
queueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => void
queueRemove: (entity: Entity, component: AnyComponentDef) => void
spawn: (name?: string) => EntityCommands
-spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => void
static new (world: World, resources: ResourceStorage): CommandsInstance
static prototype: CommandsInstance
```
@@ -1915,6 +1927,13 @@ skeletalFields: SkeletalFieldMeta | undefined
transient: boolean | undefined
```
+## ComponentsData — type @public
+```
+{
+ [K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;
+}
+```
+
## CompressorEffectDef — interface @experimental
```
attack: number | undefined
@@ -6571,6 +6590,13 @@ Local = 1
World = 0
```
+## SkeletalFieldMeta — interface @public
+```
+atlasField: string
+runtime: string
+skeletonField: string
+```
+
## SliceBorder — interface @experimental
```
bottom: number
@@ -8334,6 +8360,14 @@ number | Vec2 | Vec3 | Vec4 | number[] | TextureRef
() => void
```
+## UnwrapQueryArg — type @public
+```
+T extends MutWrapper<infer C> ? C :
+ T extends AddedWrapper<infer C> ? C :
+ T extends ChangedWrapper<infer C> ? C :
+ T
+```
+
## ValidatePrefabOptions — interface @experimental
```
instanceOverrides: readonly PrefabOverride[] | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index a051dd06b..545e474bf 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: 101 public · 24 beta · 1379 experimental · 3 deprecated
+Symbols: 107 public · 24 beta · 1378 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -600,7 +600,13 @@ static prototype: ArrayDataSource<any>
'json' | 'text' | 'binary' | 'image' | 'audio'
```
-## AssetFieldType — type @experimental
+## AssetFieldMeta — interface @public
+```
+field: string
+type: AssetFieldType
+```
+
+## AssetFieldType — type @public
```
'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller'
```
@@ -634,6 +640,12 @@ static new (): AssetPlugin
static prototype: AssetPlugin
```
+## AssetRef — interface @public
+```
+path: string
+type: string
+```
+
## AssetRefCounter — class @experimental
```
addFontRef: (path: string, entity: number) => void
@@ -1830,6 +1842,7 @@ keyof ThemeColors
## CommandsInstance — class @public
```
+@internal spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => void
despawn: (entity: Entity) => CommandsInstance
entity: (entity: Entity) => EntityCommands
flush: () => void
@@ -1837,7 +1850,6 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstance
queueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => void
queueRemove: (entity: Entity, component: AnyComponentDef) => void
spawn: (name?: string) => EntityCommands
-spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => void
static new (world: World, resources: ResourceStorage): CommandsInstance
static prototype: CommandsInstance
```
@@ -1902,6 +1914,13 @@ skeletalFields: SkeletalFieldMeta | undefined
transient: boolean | undefined
```
+## ComponentsData — type @public
+```
+{
+ [K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;
+}
+```
+
## CompressorEffectDef — interface @experimental
```
attack: number | undefined
@@ -6373,6 +6392,13 @@ Local = 1
World = 0
```
+## SkeletalFieldMeta — interface @public
+```
+atlasField: string
+runtime: string
+skeletonField: string
+```
+
## SliceBorder — interface @experimental
```
bottom: number
@@ -8136,6 +8162,14 @@ number | Vec2 | Vec3 | Vec4 | number[] | TextureRef
() => void
```
+## UnwrapQueryArg — type @public
+```
+T extends MutWrapper<infer C> ? C :
+ T extends AddedWrapper<infer C> ? C :
+ T extends ChangedWrapper<infer C> ? C :
+ T
+```
+
## ValidatePrefabOptions — interface @experimental
```
instanceOverrides: readonly PrefabOverride[] | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index d1e6b676b..2d4a0747b 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: 101 public · 22 beta · 1400 experimental · 3 deprecated
+Symbols: 107 public · 22 beta · 1399 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -600,7 +600,13 @@ static prototype: ArrayDataSource<any>
'json' | 'text' | 'binary' | 'image' | 'audio'
```
-## AssetFieldType — type @experimental
+## AssetFieldMeta — interface @public
+```
+field: string
+type: AssetFieldType
+```
+
+## AssetFieldType — type @public
```
'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller'
```
@@ -634,6 +640,12 @@ static new (): AssetPlugin
static prototype: AssetPlugin
```
+## AssetRef — interface @public
+```
+path: string
+type: string
+```
+
## AssetRefCounter — class @experimental
```
addFontRef: (path: string, entity: number) => void
@@ -1830,6 +1842,7 @@ keyof ThemeColors
## CommandsInstance — class @public
```
+@internal spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => void
despawn: (entity: Entity) => CommandsInstance
entity: (entity: Entity) => EntityCommands
flush: () => void
@@ -1837,7 +1850,6 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstance
queueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => void
queueRemove: (entity: Entity, component: AnyComponentDef) => void
spawn: (name?: string) => EntityCommands
-spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => void
static new (world: World, resources: ResourceStorage): CommandsInstance
static prototype: CommandsInstance
```
@@ -1902,6 +1914,13 @@ skeletalFields: SkeletalFieldMeta | undefined
transient: boolean | undefined
```
+## ComponentsData — type @public
+```
+{
+ [K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;
+}
+```
+
## CompressorEffectDef — interface @experimental
```
attack: number | undefined
@@ -6618,6 +6637,13 @@ Local = 1
World = 0
```
+## SkeletalFieldMeta — interface @public
+```
+atlasField: string
+runtime: string
+skeletonField: string
+```
+
## SliceBorder — interface @experimental
```
bottom: number
@@ -8381,6 +8407,14 @@ number | Vec2 | Vec3 | Vec4 | number[] | TextureRef
() => void
```
+## UnwrapQueryArg — type @public
+```
+T extends MutWrapper<infer C> ? C :
+ T extends AddedWrapper<infer C> ? C :
+ T extends ChangedWrapper<infer C> ? C :
+ T
+```
+
## ValidatePrefabOptions — interface @experimental
```
instanceOverrides: readonly PrefabOverride[] | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index b4f02c3e4..184c07760 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: 101 public · 22 beta · 1390 experimental · 3 deprecated
+Symbols: 107 public · 22 beta · 1389 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -600,7 +600,13 @@ static prototype: ArrayDataSource<any>
'json' | 'text' | 'binary' | 'image' | 'audio'
```
-## AssetFieldType — type @experimental
+## AssetFieldMeta — interface @public
+```
+field: string
+type: AssetFieldType
+```
+
+## AssetFieldType — type @public
```
'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller'
```
@@ -634,6 +640,12 @@ static new (): AssetPlugin
static prototype: AssetPlugin
```
+## AssetRef — interface @public
+```
+path: string
+type: string
+```
+
## AssetRefCounter — class @experimental
```
addFontRef: (path: string, entity: number) => void
@@ -1830,6 +1842,7 @@ keyof ThemeColors
## CommandsInstance — class @public
```
+@internal spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => void
despawn: (entity: Entity) => CommandsInstance
entity: (entity: Entity) => EntityCommands
flush: () => void
@@ -1837,7 +1850,6 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstance
queueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => void
queueRemove: (entity: Entity, component: AnyComponentDef) => void
spawn: (name?: string) => EntityCommands
-spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => void
static new (world: World, resources: ResourceStorage): CommandsInstance
static prototype: CommandsInstance
```
@@ -1902,6 +1914,13 @@ skeletalFields: SkeletalFieldMeta | undefined
transient: boolean | undefined
```
+## ComponentsData — type @public
+```
+{
+ [K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;
+}
+```
+
## CompressorEffectDef — interface @experimental
```
attack: number | undefined
@@ -6380,6 +6399,13 @@ Local = 1
World = 0
```
+## SkeletalFieldMeta — interface @public
+```
+atlasField: string
+runtime: string
+skeletonField: string
+```
+
## SliceBorder — interface @experimental
```
bottom: number
@@ -8143,6 +8169,14 @@ number | Vec2 | Vec3 | Vec4 | number[] | TextureRef
() => void
```
+## UnwrapQueryArg — type @public
+```
+T extends MutWrapper<infer C> ? C :
+ T extends AddedWrapper<infer C> ? C :
+ T extends ChangedWrapper<infer C> ? C :
+ T
+```
+
## ValidatePrefabOptions — interface @experimental
```
instanceOverrides: readonly PrefabOverride[] | undefined
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 477b4ce04..7757f85fb 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -80,6 +80,12 @@ export {
type ComponentData,
type ComponentMetadata,
type FieldMeta,
+ // The three shapes ComponentMetadata is BUILT from. Exported because a project
+ // that declares one has to name them, and a frozen signature may only name
+ // types a creator can spell.
+ type AssetRef,
+ type AssetFieldMeta,
+ type SkeletalFieldMeta,
Transform,
LocalTransform,
WorldTransform,
@@ -271,6 +277,10 @@ export {
type QueryBuilder,
type QueryDescriptor,
type QueryResult,
+ // What QueryResult is spelled with — computed, never supplied, but a frozen
+ // signature may only name types a reader can look up.
+ type ComponentsData,
+ type UnwrapQueryArg,
type MutWrapper,
type AddedWrapper,
type ChangedWrapper,
diff --git a/sdk/src/ecs/commands.ts b/sdk/src/ecs/commands.ts
index 648b9a166..a5a6878e0 100644
--- a/sdk/src/ecs/commands.ts
+++ b/sdk/src/ecs/commands.ts
@@ -204,6 +204,8 @@ export class CommandsInstance {
this.pending_.push({ type: 'remove', entity, component });
}
+ /** @internal How EntityCommands applies a deferred spawn — `entityRef` is the
+ * handle it already gave the caller, filled in once the entity exists. */
spawnImmediate(components: SpawnComponentEntry[], entityRef: { entity: Entity }, name?: string): void {
const entity = this.world_.spawn(name);
entityRef.entity = entity;
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index 102bb89cb..3d1a0be92 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -17,11 +17,24 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';
*/
export const ABI_LAYOUT_HASH = '7b8797b9ae911eeb';
+/**
+ * One asset-valued field of a component: which field, and what kind of
+ * asset it holds. Declaring it is what gives the field dependency
+ * tracking, cook inclusion, `@uuid:` refs and hot-update.
+ *
+ * @public
+ */
export interface AssetFieldMeta {
field: string;
type: AssetFieldType;
}
+/**
+ * A skeleton/atlas field PAIR, which has to be declared together: the two
+ * files are one asset, and loading either alone yields nothing to draw.
+ *
+ * @public
+ */
export interface SkeletalFieldMeta {
skeletonField: string;
atlasField: string;
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index eb77213c7..69ed9058b 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -8,6 +8,7 @@
import { Entity, Vec2, Vec3, Color, Quat } from '../types';
import { deepClone } from '../util/deepClone';
import { COMPONENT_META, type AssetFieldMeta, type SkeletalFieldMeta } from './component.generated';
+export type { AssetFieldMeta, SkeletalFieldMeta };
// C++-backed component data shapes, generated from the ES_COMPONENT structs (single
// source — a TS field can no longer drift from C++). Re-exported below so the public
// `esengine` import site is unchanged; Camera/ParticleEmitter add TS-only fields by
@@ -35,6 +36,12 @@ import type {
// Self-Describing Component Types
// =============================================================================
+/**
+ * An asset a component's data points at, as scene preload discovery reports one.
+ * `type` is the loader's kind and `path` the project-relative reference.
+ *
+ * @public
+ */
export interface AssetRef {
type: string;
path: string;
diff --git a/sdk/src/ecs/query.ts b/sdk/src/ecs/query.ts
index 9ca9c99cb..c6c60ef36 100644
--- a/sdk/src/ecs/query.ts
+++ b/sdk/src/ecs/query.ts
@@ -334,12 +334,27 @@ export function Query<C extends QueryArg[]>(...components: C): QueryBuilder<C> {
// Query Result Type
// =============================================================================
-type UnwrapQueryArg<T> =
+/**
+ * The component a {@link QueryArg} asks for, with any wrapper taken off — `Mut(X)`,
+ * `Added(X)` and `Changed(X)` all read as `X`, because a wrapper says how the
+ * component is accessed and not which one it is.
+ *
+ * @public
+ */
+export type UnwrapQueryArg<T> =
T extends MutWrapper<infer C> ? C :
T extends AddedWrapper<infer C> ? C :
T extends ChangedWrapper<infer C> ? C :
T;
-type ComponentsData<C extends readonly QueryArg[]> = {
+
+/**
+ * The data tuple a query's arguments resolve to, in the order they were asked
+ * for. Computed, never supplied — but {@link QueryResult} is spelled with it, so
+ * it carries a name a reader can look up.
+ *
+ * @public
+ */
+export type ComponentsData<C extends readonly QueryArg[]> = {
[K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;
};
diff --git a/sdk/src/input/inputMap.ts b/sdk/src/input/inputMap.ts
index 198509e5a..dc7d75cf1 100644
--- a/sdk/src/input/inputMap.ts
+++ b/sdk/src/input/inputMap.ts
@@ -16,6 +16,7 @@ import { Schedule, defineSystem, addSystemToSchedule } from '../ecs/system';
import { Res } from '../ecs/resource';
import { Input, InputState, GamepadAxis, GamepadButton } from './input';
import { Storage } from '../util/storage';
+import type { Vec2 } from '../types';
// =============================================================================
// Binding model (plain, serializable — also the rebind / persistence format)
@@ -126,7 +127,6 @@ export const Axis2D = (...bindings: Binding[]): ActionDef => ({ type: 'axis2d',
/** An action reads as "down" once its magnitude reaches this (digital + analog). */
const DOWN_THRESHOLD = 0.5;
-interface Vec2 { x: number; y: number; }
interface ActionState {
value: number; // button: [0,1]; axis: [-1,1]; axis2d: magnitude [0,1]
diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.ts
index 27478d813..a25eb6e1e 100644
--- a/sdk/src/scene/scene.ts
+++ b/sdk/src/scene/scene.ts
@@ -112,6 +112,12 @@ export class MissingAssetsError extends Error {
// Asset Field Types
// =============================================================================
+/**
+ * The asset kinds a component field may hold — a closed set, because each one
+ * names a registered loader. Adding one means adding the loader too.
+ *
+ * @public
+ */
export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'video' | 'tilemap' | 'tileset' | 'timeline' | 'statemachine' | 'behaviortree' | 'animatorcontroller';
// =============================================================================
diff --git a/sdk/tests/ecs-vocabulary.test.ts b/sdk/tests/ecs-vocabulary.test.ts
index f3df14968..a56ad60eb 100644
--- a/sdk/tests/ecs-vocabulary.test.ts
+++ b/sdk/tests/ecs-vocabulary.test.ts
@@ -17,12 +17,13 @@ import {
} from '../src/core';
import type {
AnyComponentDef, BuiltinComponentDef, ComponentDef, ComponentMetadata, FieldMeta,
+ AssetRef, AssetFieldMeta, AssetFieldType, SkeletalFieldMeta,
QueryBuilder, QueryDescriptor, MutWrapper, AddedWrapper, ChangedWrapper,
FilterExpr, RemovedQueryDescriptor,
ResourceDef, ResDescriptor, ResMutDescriptor, CommandsDescriptor, QueryArg,
EventDef, EventReaderDescriptor, EventWriterDescriptor, GetWorldDescriptor,
SystemDef, SystemOptions, SystemParam, InferParam, InferParams, ComponentData,
- Entity, QueryResult, ChildrenData, ParentData, NameData, TransformData,
+ Entity, QueryResult, ComponentsData, UnwrapQueryArg, ChildrenData, ParentData, NameData, TransformData,
Vec2, Vec3, Vec4, Quat, Color,
} from '../src/core';
@@ -89,6 +90,24 @@ describe('component vocabulary', () => {
expect(Object.keys(shape)).toEqual(expect.arrayContaining(['position', 'rotation', 'scale']));
});
+ it('a component declares its asset fields, and that is what discovery reads', () => {
+ // The three shapes ComponentMetadata is built from, each named here because
+ // a project writing one has to name it too.
+ const assetFields: AssetFieldMeta[] = [{ field: 'icon', type: 'texture' satisfies AssetFieldType }];
+ const skeletalFields: SkeletalFieldMeta = {
+ skeletonField: 'skeleton', atlasField: 'atlas', runtime: 'spine',
+ };
+ const discovered: AssetRef[] = [{ type: 'texture', path: 'art/icon.png' }];
+ const def = defineComponent('VocabAssetFields', { icon: '', skeleton: '', atlas: '' }, {
+ assetFields, skeletalFields, discoverAssets: () => discovered,
+ });
+ expect(def.assetFields).toEqual(assetFields);
+ expect(def.skeletalFields).toEqual(skeletalFields);
+ // discoverAssets is authoritative when present — assetFields are then NOT
+ // walked for discovery, which is the whole reason a component may declare it.
+ expect(def.discoverAssets?.({})).toEqual(discovered);
+ });
+
it('FieldMeta is the per-field policy a definition carries', () => {
const meta: Record<string, FieldMeta> = { hp: { min: 0, max: 100 } };
const def = defineComponent('VocabFieldMeta', { hp: 1 }, { fields: meta });
@@ -176,6 +195,18 @@ describe('query vocabulary', () => {
expect(wrapped._component).toBe(Position);
expect(Query(Health, wrapped)._mutIndices).toEqual([1]);
});
+
+ it('a wrapper changes the access, not which component the row carries', () => {
+ // What QueryResult is spelled with: UnwrapQueryArg takes the wrapper off, so
+ // Mut(Position) and Position yield the same data type. The annotations are
+ // the assertions — a wrapper leaking into the row would not compile.
+ const unwrapped: UnwrapQueryArg<MutWrapper<typeof Position>> = Position;
+ expect(unwrapped).toBe(Position);
+ const row: ComponentsData<[typeof Position, MutWrapper<typeof Health>]> =
+ [{ x: 1, y: 2 }, { hp: 3 }];
+ const full: QueryResult<[typeof Position, MutWrapper<typeof Health>]> = [1 as Entity, ...row];
+ expect(full).toEqual([1, { x: 1, y: 2 }, { hp: 3 }]);
+ });
});
describe('resource vocabulary', () => {
diff --git a/tools/api-surface.mjs b/tools/api-surface.mjs
index d34a2c942..42f085f6b 100644
--- a/tools/api-surface.mjs
+++ b/tools/api-surface.mjs
@@ -248,6 +248,54 @@ function isPrivateMember(member) {
return false;
}
+const IS_MEMBER = (n) => ts.isPropertySignature(n) || ts.isMethodSignature(n) || ts.isPropertyDeclaration(n)
+ || ts.isMethodDeclaration(n) || ts.isGetAccessor(n) || ts.isSetAccessor(n) || ts.isConstructorDeclaration(n);
+
+/**
+ * Whether the promised body carries this node. A private or `@internal` member is
+ * in the `.d.ts` and promises nothing, so what its types name does not constrain
+ * the promise; a constructor is the same — no snapshot line records it.
+ */
+function inUnpromisedMember(node) {
+ for (let n = node; n; n = n.parent) {
+ if (!IS_MEMBER(n)) continue;
+ if (ts.isConstructorDeclaration(n)) return true;
+ if (n.name && ts.isPrivateIdentifier(n.name)) return true;
+ const mods = ts.canHaveModifiers(n) ? ts.getModifiers(n) : undefined;
+ if (mods?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword)) return true;
+ if (/@internal\b/.test(leadingDoc(n))) return true;
+ }
+ return false;
+}
+
+/**
+ * R6 — types a frozen declaration names that no entry exports.
+ *
+ * check-tier-leaks compares tiers between snapshot entries, so a type absent from
+ * the surface is invisible to it, and a @public signature can promise a shape whose
+ * name a creator cannot write. Read from the AST: the checker prints an
+ * out-of-scope type as a bare name, indistinguishable from an exported one.
+ */
+function unnameableTypes(decl) {
+ const out = new Set();
+ const walk = (node) => {
+ if (ts.isTypeReferenceNode(node) && !inUnpromisedMember(node)) {
+ const at = checker.getSymbolAtLocation(node.typeName);
+ const target = at && (at.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(at) : at);
+ if (target && !(target.flags & ts.SymbolFlags.TypeParameter) && !exportedSymbols.has(target)) {
+ const from = target.declarations?.[0]?.getSourceFile().fileName.replace(/\\/g, '/');
+ // Ours only: a lib or @types shape is not ours to export.
+ if (from && from.startsWith(SDK.replace(/\\/g, '/')) && !from.includes('/node_modules/')) {
+ out.add(target.name);
+ }
+ }
+ }
+ ts.forEachChild(node, walk);
+ };
+ walk(decl);
+ return [...out].sort();
+}
+
function memberLines(type, location, owner) {
const lines = [];
for (const sig of type.getCallSignatures()) {
@@ -293,6 +341,11 @@ function describeSymbol(name, symbol) {
return null;
}
const { tier, deprecated } = releaseTag(resolved);
+ if (tier === 'public') {
+ for (const t of unnameableTypes(decl)) {
+ errors.push(`R6: '${name}' is @public but names '${t}', which no entry exports — a creator cannot spell it`);
+ }
+ }
const owner = { name, tier };
const flags = resolved.flags;
const body = [];
diff --git a/tools/eht/generators/metadata.py b/tools/eht/generators/metadata.py
index 526f9dd0d..d5c7dbfe9 100644
--- a/tools/eht/generators/metadata.py
+++ b/tools/eht/generators/metadata.py
@@ -306,11 +306,24 @@ class MetadataGenerator:
' */',
f"export const ABI_LAYOUT_HASH = '{self.abi_hash}';",
'',
+ '/**',
+ ' * One asset-valued field of a component: which field, and what kind of',
+ ' * asset it holds. Declaring it is what gives the field dependency',
+ ' * tracking, cook inclusion, `@uuid:` refs and hot-update.',
+ ' *',
+ ' * @public',
+ ' */',
'export interface AssetFieldMeta {',
' field: string;',
' type: AssetFieldType;',
'}',
'',
+ '/**',
+ ' * A skeleton/atlas field PAIR, which has to be declared together: the two',
+ ' * files are one asset, and loading either alone yields nothing to draw.',
+ ' *',
+ ' * @public',
+ ' */',
'export interface SkeletalFieldMeta {',
' skeletonField: string;',
' atlasField: string;',