A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(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.jsonindex 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.mdindex 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 (): AssetPluginstatic 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) => voiddespawn: (entity: Entity) => CommandsInstanceentity: (entity: Entity) => EntityCommandsflush: () => void@@ -1842,7 +1855,6 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstancequeueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => voidqueueRemove: (entity: Entity, component: AnyComponentDef) => voidspawn: (name?: string) => EntityCommands-spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => voidstatic new (world: World, resources: ResourceStorage): CommandsInstancestatic prototype: CommandsInstance```@@ -1907,6 +1919,13 @@ skeletalFields: SkeletalFieldMeta | undefinedtransient: boolean | undefined```+## ComponentsData — type @public+```+{+ [K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;+}+```+## CompressorEffectDef — interface @experimental```attack: number | undefined@@ -6378,6 +6397,13 @@ Local = 1World = 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[] | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 (): AssetPluginstatic 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) => voiddespawn: (entity: Entity) => CommandsInstanceentity: (entity: Entity) => EntityCommandsflush: () => void@@ -1842,7 +1855,6 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstancequeueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => voidqueueRemove: (entity: Entity, component: AnyComponentDef) => voidspawn: (name?: string) => EntityCommands-spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => voidstatic new (world: World, resources: ResourceStorage): CommandsInstancestatic prototype: CommandsInstance```@@ -1915,6 +1927,13 @@ skeletalFields: SkeletalFieldMeta | undefinedtransient: boolean | undefined```+## ComponentsData — type @public+```+{+ [K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;+}+```+## CompressorEffectDef — interface @experimental```attack: number | undefined@@ -6571,6 +6590,13 @@ Local = 1World = 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[] | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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 (): AssetPluginstatic 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) => voiddespawn: (entity: Entity) => CommandsInstanceentity: (entity: Entity) => EntityCommandsflush: () => void@@ -1837,7 +1850,6 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstancequeueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => voidqueueRemove: (entity: Entity, component: AnyComponentDef) => voidspawn: (name?: string) => EntityCommands-spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => voidstatic new (world: World, resources: ResourceStorage): CommandsInstancestatic prototype: CommandsInstance```@@ -1902,6 +1914,13 @@ skeletalFields: SkeletalFieldMeta | undefinedtransient: boolean | undefined```+## ComponentsData — type @public+```+{+ [K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;+}+```+## CompressorEffectDef — interface @experimental```attack: number | undefined@@ -6373,6 +6392,13 @@ Local = 1World = 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[] | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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 (): AssetPluginstatic 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) => voiddespawn: (entity: Entity) => CommandsInstanceentity: (entity: Entity) => EntityCommandsflush: () => void@@ -1837,7 +1850,6 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstancequeueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => voidqueueRemove: (entity: Entity, component: AnyComponentDef) => voidspawn: (name?: string) => EntityCommands-spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => voidstatic new (world: World, resources: ResourceStorage): CommandsInstancestatic prototype: CommandsInstance```@@ -1902,6 +1914,13 @@ skeletalFields: SkeletalFieldMeta | undefinedtransient: boolean | undefined```+## ComponentsData — type @public+```+{+ [K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;+}+```+## CompressorEffectDef — interface @experimental```attack: number | undefined@@ -6618,6 +6637,13 @@ Local = 1World = 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[] | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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 (): AssetPluginstatic 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) => voiddespawn: (entity: Entity) => CommandsInstanceentity: (entity: Entity) => EntityCommandsflush: () => void@@ -1837,7 +1850,6 @@ insertResource: <T>(resource: ResourceDef<T>, value: T) => CommandsInstancequeueInsert: (entity: Entity, component: AnyComponentDef, data: unknown) => voidqueueRemove: (entity: Entity, component: AnyComponentDef) => voidspawn: (name?: string) => EntityCommands-spawnImmediate: (components: SpawnComponentEntry[], entityRef: { entity: Entity; }, name?: string) => voidstatic new (world: World, resources: ResourceStorage): CommandsInstancestatic prototype: CommandsInstance```@@ -1902,6 +1914,13 @@ skeletalFields: SkeletalFieldMeta | undefinedtransient: boolean | undefined```+## ComponentsData — type @public+```+{+ [K in keyof C]: ComponentData<UnwrapQueryArg<C[K]>>;+}+```+## CompressorEffectDef — interface @experimental```attack: number | undefined@@ -6380,6 +6399,13 @@ Local = 1World = 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[] | undefineddiff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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.pyindex 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;',