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(ecs): wave two freezes the vocabulary the frozen calls are spelled in
yhh751b410c27da
diff --git a/desktop/tests/api-baseline.test.ts b/desktop/tests/api-baseline.test.tsindex fec3956ed..78afcd216 100644--- a/desktop/tests/api-baseline.test.ts+++ b/desktop/tests/api-baseline.test.ts@@ -91,4 +91,18 @@ describe('baselineFindings', () => {expect(failures).toEqual([]);expect(notes).toEqual([]);});++ it('lets an @internal member change, because none was promised', () => {+ const was = snapshot(sig('Handle — class @public', 'get(): number\n@internal _raw: string'));+ const now = snapshot(sig('Handle — class @public', 'get(): number\n@internal _raw: number'));+ expect(baselineFindings(was, now).failures).toEqual([]);+ });++ it('still fails when a promised member beside an @internal one changes', () => {+ const was = snapshot(sig('Handle — class @public', 'get(): number\n@internal _raw: string'));+ const now = snapshot(sig('Handle — class @public', 'get(): string\n@internal _raw: string'));+ expect(baselineFindings(was, now).failures).toEqual([+ expect.stringContaining('@public signature changed'),+ ]);+ });});diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex a0cd572f7..f9d6c2267 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -1,13 +1,25 @@{"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.","counts": {- "public": 6,+ "public": 20,"beta": 24,- "experimental": 1595,+ "experimental": 1581,"deprecated": 1},"total": 1625,"public": [+ {+ "name": "AnyComponentDef",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "Commands","kind": "function",@@ -20,6 +32,54 @@"minigame"]},+ {+ "name": "CommandsDescriptor",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ComponentDef",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ComponentMetadata",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "InferParams",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "Mut","kind": "function",@@ -32,6 +92,18 @@"minigame"]},+ {+ "name": "MutWrapper",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "Query","kind": "function",@@ -44,6 +116,42 @@"minigame"]},+ {+ "name": "QueryArg",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "QueryBuilder",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "QueryDescriptor",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "Res","kind": "function",@@ -56,6 +164,66 @@"minigame"]},+ {+ "name": "ResDescriptor",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ResourceDef",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "SystemDef",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "SystemOptions",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "SystemParam",+ "kind": "type",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "defineComponent","kind": "function",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 7c60e66e7..41283c6c6 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: 6 public · 17 beta · 1480 experimental · 1 deprecated+Symbols: 20 public · 17 beta · 1466 experimental · 1 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -491,7 +491,7 @@ hasExitTime: boolean | undefinedto: string```-## AnyComponentDef — type @experimental+## AnyComponentDef — type @public```ComponentDef<any> | BuiltinComponentDef<any>```@@ -1753,9 +1753,9 @@ keyof ThemeColors(): CommandsDescriptor```-## CommandsDescriptor — interface @experimental+## CommandsDescriptor — interface @public```-_type: "commands"+@internal _type: "commands"```## CommandsInstance — class @experimental@@ -1798,12 +1798,12 @@ C extends BuiltinComponentDef<infer T> ? T :never```-## ComponentDef — interface @experimental+## ComponentDef — interface @public```-_builtin: false-_default: T-_id: symbol-_name: string+@internal _builtin: false+@internal _default: T+@internal _id: symbol+@internal _name: stringanimatableFields: readonly string[]assetFields: readonly AssetFieldMeta[]colorKeys: readonly string[]@@ -1818,7 +1818,7 @@ skeletalFields: SkeletalFieldMeta | undefinedtransient: boolean```-## ComponentMetadata — interface @experimental+## ComponentMetadata — interface @public```animatableFields: string[] | undefinedassetFields: AssetFieldMeta[] | undefined@@ -3201,7 +3201,7 @@ P extends QueryDescriptor<infer C> ? QueryInstance<C> :never```-## InferParams — type @experimental+## InferParams — type @public```{[K in keyof P]: InferParam<P[K]>;@@ -4108,10 +4108,10 @@ ComponentDef<MotorJointData><T extends AnyComponentDef>(component: T): MutWrapper<T>```-## MutWrapper — interface @experimental+## MutWrapper — interface @public```-_component: T-_type: "mut"+@internal _component: T+@internal _type: "mut"```## NODE_SPECS — const @beta@@ -5308,36 +5308,36 @@ z: number<C extends QueryArg[]>(...components: C): QueryBuilder<C>```-## QueryArg — type @experimental+## QueryArg — type @public```AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>```-## QueryBuilder — interface @experimental+## QueryBuilder — interface @public```-_addedFilters: { index: number; component: AnyComponentDef; }[]-_changedFilters: { index: number; component: AnyComponentDef; }[]-_components: C-_filter: FilterExpr | null-_mutIndices: number[]-_type: "query"-_with: AnyComponentDef[]-_without: AnyComponentDef[]+@internal _addedFilters: { index: number; component: AnyComponentDef; }[]+@internal _changedFilters: { index: number; component: AnyComponentDef; }[]+@internal _components: C+@internal _filter: FilterExpr | null+@internal _mutIndices: number[]+@internal _type: "query"+@internal _with: AnyComponentDef[]+@internal _without: AnyComponentDef[]filter: (expr: FilterExpr) => QueryBuilder<C>with: (...components: AnyComponentDef[]) => QueryBuilder<C>without: (...components: AnyComponentDef[]) => QueryBuilder<C>```-## QueryDescriptor — interface @experimental+## QueryDescriptor — interface @public```-_addedFilters: { index: number; component: AnyComponentDef; }[]-_changedFilters: { index: number; component: AnyComponentDef; }[]-_components: C-_filter: FilterExpr | null-_mutIndices: number[]-_type: "query"-_with: AnyComponentDef[]-_without: AnyComponentDef[]+@internal _addedFilters: { index: number; component: AnyComponentDef; }[]+@internal _changedFilters: { index: number; component: AnyComponentDef; }[]+@internal _components: C+@internal _filter: FilterExpr | null+@internal _mutIndices: number[]+@internal _type: "query"+@internal _with: AnyComponentDef[]+@internal _without: AnyComponentDef[]```## QueryInstance — class @experimental@@ -5570,10 +5570,10 @@ static prototype: ReplicationServer<T>(resource: ResourceDef<T>): ResDescriptor<T>```-## ResDescriptor — interface @experimental+## ResDescriptor — interface @public```-_resource: ResourceDef<T>-_type: "res"+@internal _resource: ResourceDef<T>+@internal _type: "res"```## ResMut — function @experimental@@ -5628,11 +5628,11 @@ textureHeight: number | undefinedtextureWidth: number | undefined```-## ResourceDef — interface @experimental+## ResourceDef — interface @public```-_default: T-_id: symbol-_name: string+@internal _default: T+@internal _id: symbol+@internal _name: string```## ResourceStats — interface @experimental@@ -6704,24 +6704,24 @@ phaseAgeMs: number(path: string) => PrefabData | null```-## SystemDef — interface @experimental+## SystemDef — interface @public```-_fn: (...args: never[]) => void | Promise<void>-_id: symbol-_name: string-_params: readonly SystemParam[]-_runAfter: readonly string[] | undefined-_runBefore: readonly string[] | undefined+@internal _fn: (...args: never[]) => void | Promise<void>+@internal _id: symbol+@internal _name: string+@internal _params: readonly SystemParam[]+@internal _runAfter: readonly string[] | undefined+@internal _runBefore: readonly string[] | undefined```-## SystemOptions — interface @experimental+## SystemOptions — interface @public```name: string | undefinedrunAfter: string[] | undefinedrunBefore: string[] | undefined```-## SystemParam — type @experimental+## SystemParam — type @public```| QueryDescriptor<readonly QueryArg[]>| ResDescriptor<unknown>diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex cefc42dd1..c1bfae585 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: 6 public · 22 beta · 1499 experimental · 1 deprecated+Symbols: 20 public · 22 beta · 1485 experimental · 1 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -491,7 +491,7 @@ hasExitTime: boolean | undefinedto: string```-## AnyComponentDef — type @experimental+## AnyComponentDef — type @public```ComponentDef<any> | BuiltinComponentDef<any>```@@ -1753,9 +1753,9 @@ keyof ThemeColors(): CommandsDescriptor```-## CommandsDescriptor — interface @experimental+## CommandsDescriptor — interface @public```-_type: "commands"+@internal _type: "commands"```## CommandsInstance — class @experimental@@ -1798,12 +1798,12 @@ C extends BuiltinComponentDef<infer T> ? T :never```-## ComponentDef — interface @experimental+## ComponentDef — interface @public```-_builtin: false-_default: T-_id: symbol-_name: string+@internal _builtin: false+@internal _default: T+@internal _id: symbol+@internal _name: stringanimatableFields: readonly string[]assetFields: readonly AssetFieldMeta[]colorKeys: readonly string[]@@ -1826,7 +1826,7 @@ u32: Uint32Array<ArrayBufferLike>u8: Uint8Array<ArrayBufferLike>```-## ComponentMetadata — interface @experimental+## ComponentMetadata — interface @public```animatableFields: string[] | undefinedassetFields: AssetFieldMeta[] | undefined@@ -3209,7 +3209,7 @@ P extends QueryDescriptor<infer C> ? QueryInstance<C> :never```-## InferParams — type @experimental+## InferParams — type @public```{[K in keyof P]: InferParam<P[K]>;@@ -4121,10 +4121,10 @@ ComponentDef<MotorJointData><T extends AnyComponentDef>(component: T): MutWrapper<T>```-## MutWrapper — interface @experimental+## MutWrapper — interface @public```-_component: T-_type: "mut"+@internal _component: T+@internal _type: "mut"```## NODE_SPECS — const @beta@@ -5491,36 +5491,36 @@ z: number<C extends QueryArg[]>(...components: C): QueryBuilder<C>```-## QueryArg — type @experimental+## QueryArg — type @public```AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>```-## QueryBuilder — interface @experimental+## QueryBuilder — interface @public```-_addedFilters: { index: number; component: AnyComponentDef; }[]-_changedFilters: { index: number; component: AnyComponentDef; }[]-_components: C-_filter: FilterExpr | null-_mutIndices: number[]-_type: "query"-_with: AnyComponentDef[]-_without: AnyComponentDef[]+@internal _addedFilters: { index: number; component: AnyComponentDef; }[]+@internal _changedFilters: { index: number; component: AnyComponentDef; }[]+@internal _components: C+@internal _filter: FilterExpr | null+@internal _mutIndices: number[]+@internal _type: "query"+@internal _with: AnyComponentDef[]+@internal _without: AnyComponentDef[]filter: (expr: FilterExpr) => QueryBuilder<C>with: (...components: AnyComponentDef[]) => QueryBuilder<C>without: (...components: AnyComponentDef[]) => QueryBuilder<C>```-## QueryDescriptor — interface @experimental+## QueryDescriptor — interface @public```-_addedFilters: { index: number; component: AnyComponentDef; }[]-_changedFilters: { index: number; component: AnyComponentDef; }[]-_components: C-_filter: FilterExpr | null-_mutIndices: number[]-_type: "query"-_with: AnyComponentDef[]-_without: AnyComponentDef[]+@internal _addedFilters: { index: number; component: AnyComponentDef; }[]+@internal _changedFilters: { index: number; component: AnyComponentDef; }[]+@internal _components: C+@internal _filter: FilterExpr | null+@internal _mutIndices: number[]+@internal _type: "query"+@internal _with: AnyComponentDef[]+@internal _without: AnyComponentDef[]```## QueryInstance — class @experimental@@ -5763,10 +5763,10 @@ static prototype: ReplicationServer<T>(resource: ResourceDef<T>): ResDescriptor<T>```-## ResDescriptor — interface @experimental+## ResDescriptor — interface @public```-_resource: ResourceDef<T>-_type: "res"+@internal _resource: ResourceDef<T>+@internal _type: "res"```## ResMut — function @experimental@@ -5821,11 +5821,11 @@ textureHeight: number | undefinedtextureWidth: number | undefined```-## ResourceDef — interface @experimental+## ResourceDef — interface @public```-_default: T-_id: symbol-_name: string+@internal _default: T+@internal _id: symbol+@internal _name: string```## ResourceStats — interface @experimental@@ -6897,24 +6897,24 @@ phaseAgeMs: number(path: string) => PrefabData | null```-## SystemDef — interface @experimental+## SystemDef — interface @public```-_fn: (...args: never[]) => void | Promise<void>-_id: symbol-_name: string-_params: readonly SystemParam[]-_runAfter: readonly string[] | undefined-_runBefore: readonly string[] | undefined+@internal _fn: (...args: never[]) => void | Promise<void>+@internal _id: symbol+@internal _name: string+@internal _params: readonly SystemParam[]+@internal _runAfter: readonly string[] | undefined+@internal _runBefore: readonly string[] | undefined```-## SystemOptions — interface @experimental+## SystemOptions — interface @public```name: string | undefinedrunAfter: string[] | undefinedrunBefore: string[] | undefined```-## SystemParam — type @experimental+## SystemParam — type @public```| QueryDescriptor<readonly QueryArg[]>| ResDescriptor<unknown>diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 29c4e8cae..896267a42 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: 6 public · 19 beta · 1479 experimental · 1 deprecated+Symbols: 20 public · 19 beta · 1465 experimental · 1 deprecated## ANCHOR_AXES — const @experimental```@@ -486,7 +486,7 @@ hasExitTime: boolean | undefinedto: string```-## AnyComponentDef — type @experimental+## AnyComponentDef — type @public```ComponentDef<any> | BuiltinComponentDef<any>```@@ -1748,9 +1748,9 @@ keyof ThemeColors(): CommandsDescriptor```-## CommandsDescriptor — interface @experimental+## CommandsDescriptor — interface @public```-_type: "commands"+@internal _type: "commands"```## CommandsInstance — class @experimental@@ -1793,12 +1793,12 @@ C extends BuiltinComponentDef<infer T> ? T :never```-## ComponentDef — interface @experimental+## ComponentDef — interface @public```-_builtin: false-_default: T-_id: symbol-_name: string+@internal _builtin: false+@internal _default: T+@internal _id: symbol+@internal _name: stringanimatableFields: readonly string[]assetFields: readonly AssetFieldMeta[]colorKeys: readonly string[]@@ -1813,7 +1813,7 @@ skeletalFields: SkeletalFieldMeta | undefinedtransient: boolean```-## ComponentMetadata — interface @experimental+## ComponentMetadata — interface @public```animatableFields: string[] | undefinedassetFields: AssetFieldMeta[] | undefined@@ -3196,7 +3196,7 @@ P extends QueryDescriptor<infer C> ? QueryInstance<C> :never```-## InferParams — type @experimental+## InferParams — type @public```{[K in keyof P]: InferParam<P[K]>;@@ -4103,10 +4103,10 @@ ComponentDef<MotorJointData><T extends AnyComponentDef>(component: T): MutWrapper<T>```-## MutWrapper — interface @experimental+## MutWrapper — interface @public```-_component: T-_type: "mut"+@internal _component: T+@internal _type: "mut"```## NODE_SPECS — const @beta@@ -5303,36 +5303,36 @@ z: number<C extends QueryArg[]>(...components: C): QueryBuilder<C>```-## QueryArg — type @experimental+## QueryArg — type @public```AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>```-## QueryBuilder — interface @experimental+## QueryBuilder — interface @public```-_addedFilters: { index: number; component: AnyComponentDef; }[]-_changedFilters: { index: number; component: AnyComponentDef; }[]-_components: C-_filter: FilterExpr | null-_mutIndices: number[]-_type: "query"-_with: AnyComponentDef[]-_without: AnyComponentDef[]+@internal _addedFilters: { index: number; component: AnyComponentDef; }[]+@internal _changedFilters: { index: number; component: AnyComponentDef; }[]+@internal _components: C+@internal _filter: FilterExpr | null+@internal _mutIndices: number[]+@internal _type: "query"+@internal _with: AnyComponentDef[]+@internal _without: AnyComponentDef[]filter: (expr: FilterExpr) => QueryBuilder<C>with: (...components: AnyComponentDef[]) => QueryBuilder<C>without: (...components: AnyComponentDef[]) => QueryBuilder<C>```-## QueryDescriptor — interface @experimental+## QueryDescriptor — interface @public```-_addedFilters: { index: number; component: AnyComponentDef; }[]-_changedFilters: { index: number; component: AnyComponentDef; }[]-_components: C-_filter: FilterExpr | null-_mutIndices: number[]-_type: "query"-_with: AnyComponentDef[]-_without: AnyComponentDef[]+@internal _addedFilters: { index: number; component: AnyComponentDef; }[]+@internal _changedFilters: { index: number; component: AnyComponentDef; }[]+@internal _components: C+@internal _filter: FilterExpr | null+@internal _mutIndices: number[]+@internal _type: "query"+@internal _with: AnyComponentDef[]+@internal _without: AnyComponentDef[]```## QueryInstance — class @experimental@@ -5565,10 +5565,10 @@ static prototype: ReplicationServer<T>(resource: ResourceDef<T>): ResDescriptor<T>```-## ResDescriptor — interface @experimental+## ResDescriptor — interface @public```-_resource: ResourceDef<T>-_type: "res"+@internal _resource: ResourceDef<T>+@internal _type: "res"```## ResMut — function @experimental@@ -5623,11 +5623,11 @@ textureHeight: number | undefinedtextureWidth: number | undefined```-## ResourceDef — interface @experimental+## ResourceDef — interface @public```-_default: T-_id: symbol-_name: string+@internal _default: T+@internal _id: symbol+@internal _name: string```## ResourceStats — interface @experimental@@ -6699,24 +6699,24 @@ phaseAgeMs: number(path: string) => PrefabData | null```-## SystemDef — interface @experimental+## SystemDef — interface @public```-_fn: (...args: never[]) => void | Promise<void>-_id: symbol-_name: string-_params: readonly SystemParam[]-_runAfter: readonly string[] | undefined-_runBefore: readonly string[] | undefined+@internal _fn: (...args: never[]) => void | Promise<void>+@internal _id: symbol+@internal _name: string+@internal _params: readonly SystemParam[]+@internal _runAfter: readonly string[] | undefined+@internal _runBefore: readonly string[] | undefined```-## SystemOptions — interface @experimental+## SystemOptions — interface @public```name: string | undefinedrunAfter: string[] | undefinedrunBefore: string[] | undefined```-## SystemParam — type @experimental+## SystemParam — type @public```| QueryDescriptor<readonly QueryArg[]>| ResDescriptor<unknown>diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 37c6e8e29..3c0e08933 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: 6 public · 17 beta · 1500 experimental · 1 deprecated+Symbols: 20 public · 17 beta · 1486 experimental · 1 deprecated## ANCHOR_AXES — const @experimental```@@ -486,7 +486,7 @@ hasExitTime: boolean | undefinedto: string```-## AnyComponentDef — type @experimental+## AnyComponentDef — type @public```ComponentDef<any> | BuiltinComponentDef<any>```@@ -1748,9 +1748,9 @@ keyof ThemeColors(): CommandsDescriptor```-## CommandsDescriptor — interface @experimental+## CommandsDescriptor — interface @public```-_type: "commands"+@internal _type: "commands"```## CommandsInstance — class @experimental@@ -1793,12 +1793,12 @@ C extends BuiltinComponentDef<infer T> ? T :never```-## ComponentDef — interface @experimental+## ComponentDef — interface @public```-_builtin: false-_default: T-_id: symbol-_name: string+@internal _builtin: false+@internal _default: T+@internal _id: symbol+@internal _name: stringanimatableFields: readonly string[]assetFields: readonly AssetFieldMeta[]colorKeys: readonly string[]@@ -1813,7 +1813,7 @@ skeletalFields: SkeletalFieldMeta | undefinedtransient: boolean```-## ComponentMetadata — interface @experimental+## ComponentMetadata — interface @public```animatableFields: string[] | undefinedassetFields: AssetFieldMeta[] | undefined@@ -3196,7 +3196,7 @@ P extends QueryDescriptor<infer C> ? QueryInstance<C> :never```-## InferParams — type @experimental+## InferParams — type @public```{[K in keyof P]: InferParam<P[K]>;@@ -4348,10 +4348,10 @@ ComponentDef<MotorJointData><T extends AnyComponentDef>(component: T): MutWrapper<T>```-## MutWrapper — interface @experimental+## MutWrapper — interface @public```-_component: T-_type: "mut"+@internal _component: T+@internal _type: "mut"```## NODE_SPECS — const @beta@@ -5548,36 +5548,36 @@ z: number<C extends QueryArg[]>(...components: C): QueryBuilder<C>```-## QueryArg — type @experimental+## QueryArg — type @public```AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>```-## QueryBuilder — interface @experimental+## QueryBuilder — interface @public```-_addedFilters: { index: number; component: AnyComponentDef; }[]-_changedFilters: { index: number; component: AnyComponentDef; }[]-_components: C-_filter: FilterExpr | null-_mutIndices: number[]-_type: "query"-_with: AnyComponentDef[]-_without: AnyComponentDef[]+@internal _addedFilters: { index: number; component: AnyComponentDef; }[]+@internal _changedFilters: { index: number; component: AnyComponentDef; }[]+@internal _components: C+@internal _filter: FilterExpr | null+@internal _mutIndices: number[]+@internal _type: "query"+@internal _with: AnyComponentDef[]+@internal _without: AnyComponentDef[]filter: (expr: FilterExpr) => QueryBuilder<C>with: (...components: AnyComponentDef[]) => QueryBuilder<C>without: (...components: AnyComponentDef[]) => QueryBuilder<C>```-## QueryDescriptor — interface @experimental+## QueryDescriptor — interface @public```-_addedFilters: { index: number; component: AnyComponentDef; }[]-_changedFilters: { index: number; component: AnyComponentDef; }[]-_components: C-_filter: FilterExpr | null-_mutIndices: number[]-_type: "query"-_with: AnyComponentDef[]-_without: AnyComponentDef[]+@internal _addedFilters: { index: number; component: AnyComponentDef; }[]+@internal _changedFilters: { index: number; component: AnyComponentDef; }[]+@internal _components: C+@internal _filter: FilterExpr | null+@internal _mutIndices: number[]+@internal _type: "query"+@internal _with: AnyComponentDef[]+@internal _without: AnyComponentDef[]```## QueryInstance — class @experimental@@ -5810,10 +5810,10 @@ static prototype: ReplicationServer<T>(resource: ResourceDef<T>): ResDescriptor<T>```-## ResDescriptor — interface @experimental+## ResDescriptor — interface @public```-_resource: ResourceDef<T>-_type: "res"+@internal _resource: ResourceDef<T>+@internal _type: "res"```## ResMut — function @experimental@@ -5868,11 +5868,11 @@ textureHeight: number | undefinedtextureWidth: number | undefined```-## ResourceDef — interface @experimental+## ResourceDef — interface @public```-_default: T-_id: symbol-_name: string+@internal _default: T+@internal _id: symbol+@internal _name: string```## ResourceStats — interface @experimental@@ -6944,24 +6944,24 @@ phaseAgeMs: number(path: string) => PrefabData | null```-## SystemDef — interface @experimental+## SystemDef — interface @public```-_fn: (...args: never[]) => void | Promise<void>-_id: symbol-_name: string-_params: readonly SystemParam[]-_runAfter: readonly string[] | undefined-_runBefore: readonly string[] | undefined+@internal _fn: (...args: never[]) => void | Promise<void>+@internal _id: symbol+@internal _name: string+@internal _params: readonly SystemParam[]+@internal _runAfter: readonly string[] | undefined+@internal _runBefore: readonly string[] | undefined```-## SystemOptions — interface @experimental+## SystemOptions — interface @public```name: string | undefinedrunAfter: string[] | undefinedrunBefore: string[] | undefined```-## SystemParam — type @experimental+## SystemParam — type @public```| QueryDescriptor<readonly QueryArg[]>| ResDescriptor<unknown>diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 131d82712..3cde40ba6 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: 6 public · 17 beta · 1490 experimental · 1 deprecated+Symbols: 20 public · 17 beta · 1476 experimental · 1 deprecated## ANCHOR_AXES — const @experimental```@@ -486,7 +486,7 @@ hasExitTime: boolean | undefinedto: string```-## AnyComponentDef — type @experimental+## AnyComponentDef — type @public```ComponentDef<any> | BuiltinComponentDef<any>```@@ -1748,9 +1748,9 @@ keyof ThemeColors(): CommandsDescriptor```-## CommandsDescriptor — interface @experimental+## CommandsDescriptor — interface @public```-_type: "commands"+@internal _type: "commands"```## CommandsInstance — class @experimental@@ -1793,12 +1793,12 @@ C extends BuiltinComponentDef<infer T> ? T :never```-## ComponentDef — interface @experimental+## ComponentDef — interface @public```-_builtin: false-_default: T-_id: symbol-_name: string+@internal _builtin: false+@internal _default: T+@internal _id: symbol+@internal _name: stringanimatableFields: readonly string[]assetFields: readonly AssetFieldMeta[]colorKeys: readonly string[]@@ -1813,7 +1813,7 @@ skeletalFields: SkeletalFieldMeta | undefinedtransient: boolean```-## ComponentMetadata — interface @experimental+## ComponentMetadata — interface @public```animatableFields: string[] | undefinedassetFields: AssetFieldMeta[] | undefined@@ -3203,7 +3203,7 @@ P extends QueryDescriptor<infer C> ? QueryInstance<C> :never```-## InferParams — type @experimental+## InferParams — type @public```{[K in keyof P]: InferParam<P[K]>;@@ -4110,10 +4110,10 @@ ComponentDef<MotorJointData><T extends AnyComponentDef>(component: T): MutWrapper<T>```-## MutWrapper — interface @experimental+## MutWrapper — interface @public```-_component: T-_type: "mut"+@internal _component: T+@internal _type: "mut"```## NODE_SPECS — const @beta@@ -5310,36 +5310,36 @@ z: number<C extends QueryArg[]>(...components: C): QueryBuilder<C>```-## QueryArg — type @experimental+## QueryArg — type @public```AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>```-## QueryBuilder — interface @experimental+## QueryBuilder — interface @public```-_addedFilters: { index: number; component: AnyComponentDef; }[]-_changedFilters: { index: number; component: AnyComponentDef; }[]-_components: C-_filter: FilterExpr | null-_mutIndices: number[]-_type: "query"-_with: AnyComponentDef[]-_without: AnyComponentDef[]+@internal _addedFilters: { index: number; component: AnyComponentDef; }[]+@internal _changedFilters: { index: number; component: AnyComponentDef; }[]+@internal _components: C+@internal _filter: FilterExpr | null+@internal _mutIndices: number[]+@internal _type: "query"+@internal _with: AnyComponentDef[]+@internal _without: AnyComponentDef[]filter: (expr: FilterExpr) => QueryBuilder<C>with: (...components: AnyComponentDef[]) => QueryBuilder<C>without: (...components: AnyComponentDef[]) => QueryBuilder<C>```-## QueryDescriptor — interface @experimental+## QueryDescriptor — interface @public```-_addedFilters: { index: number; component: AnyComponentDef; }[]-_changedFilters: { index: number; component: AnyComponentDef; }[]-_components: C-_filter: FilterExpr | null-_mutIndices: number[]-_type: "query"-_with: AnyComponentDef[]-_without: AnyComponentDef[]+@internal _addedFilters: { index: number; component: AnyComponentDef; }[]+@internal _changedFilters: { index: number; component: AnyComponentDef; }[]+@internal _components: C+@internal _filter: FilterExpr | null+@internal _mutIndices: number[]+@internal _type: "query"+@internal _with: AnyComponentDef[]+@internal _without: AnyComponentDef[]```## QueryInstance — class @experimental@@ -5572,10 +5572,10 @@ static prototype: ReplicationServer<T>(resource: ResourceDef<T>): ResDescriptor<T>```-## ResDescriptor — interface @experimental+## ResDescriptor — interface @public```-_resource: ResourceDef<T>-_type: "res"+@internal _resource: ResourceDef<T>+@internal _type: "res"```## ResMut — function @experimental@@ -5630,11 +5630,11 @@ textureHeight: number | undefinedtextureWidth: number | undefined```-## ResourceDef — interface @experimental+## ResourceDef — interface @public```-_default: T-_id: symbol-_name: string+@internal _default: T+@internal _id: symbol+@internal _name: string```## ResourceStats — interface @experimental@@ -6706,24 +6706,24 @@ phaseAgeMs: number(path: string) => PrefabData | null```-## SystemDef — interface @experimental+## SystemDef — interface @public```-_fn: (...args: never[]) => void | Promise<void>-_id: symbol-_name: string-_params: readonly SystemParam[]-_runAfter: readonly string[] | undefined-_runBefore: readonly string[] | undefined+@internal _fn: (...args: never[]) => void | Promise<void>+@internal _id: symbol+@internal _name: string+@internal _params: readonly SystemParam[]+@internal _runAfter: readonly string[] | undefined+@internal _runBefore: readonly string[] | undefined```-## SystemOptions — interface @experimental+## SystemOptions — interface @public```name: string | undefinedrunAfter: string[] | undefinedrunBefore: string[] | undefined```-## SystemParam — type @experimental+## SystemParam — type @public```| QueryDescriptor<readonly QueryArg[]>| ResDescriptor<unknown>diff --git a/sdk/src/ecs/commands.ts b/sdk/src/ecs/commands.tsindex 84e285217..7fdd7e08b 100644--- a/sdk/src/ecs/commands.ts+++ b/sdk/src/ecs/commands.ts@@ -15,7 +15,15 @@ import { log } from '../util/logger';// Commands Descriptor (for system parameters)// =============================================================================+/**+ * A request for a command queue in a system's parameter list, as+ * {@link Commands} returns it. Opaque — the system body receives a+ * `CommandsInstance`, which is the thing with methods.+ *+ * @public+ */export interface CommandsDescriptor {+ /** @internal */readonly _type: 'commands';}diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.tsindex f99f0e1bf..85e752ff6 100644--- a/sdk/src/ecs/component.ts+++ b/sdk/src/ecs/component.ts@@ -91,6 +91,13 @@ export interface FieldMeta {advanced?: boolean;}+/**+ * What a component declares about its fields beyond their default values: which+ * are assets, which the editor may keyframe, which replicate. Optional+ * throughout — a component that says nothing gets the derived defaults.+ *+ * @public+ */export interface ComponentMetadata {assetFields?: AssetFieldMeta[];skeletalFields?: SkeletalFieldMeta;@@ -164,10 +171,22 @@ export function enumOptions(// Component Definition// =============================================================================+/**+ * A component type, as {@link defineComponent} returns it. Pass it to queries,+ * `world.get`/`world.insert` and `Commands`; the reflection members below are+ * what the editor and the asset cook read, derived from the metadata given at+ * definition. The underscored members are engine plumbing.+ *+ * @public+ */export interface ComponentDef<T> {+ /** @internal */readonly _id: symbol;+ /** @internal */readonly _name: string;+ /** @internal */readonly _default: T;+ /** @internal */readonly _builtin: false;readonly assetFields: readonly AssetFieldMeta[];readonly skeletalFields?: SkeletalFieldMeta;@@ -448,6 +467,13 @@ export interface BuiltinComponentDef<T> {// Component Type Union// =============================================================================+/**+ * Either kind of component type: one a project declared, or one the engine+ * ships. Everything that takes "a component" takes this, so a query or a+ * command reads a built-in and a user component the same way.+ *+ * @public+ */export type AnyComponentDef = ComponentDef<any> | BuiltinComponentDef<any>;export function isBuiltinComponent(comp: AnyComponentDef): comp is BuiltinComponentDef<any> {diff --git a/sdk/src/ecs/query.ts b/sdk/src/ecs/query.tsindex 7055b408d..f4454a7f8 100644--- a/sdk/src/ecs/query.ts+++ b/sdk/src/ecs/query.ts@@ -14,8 +14,16 @@ import { computeQueryCacheKey } from './world';// Mutable Component Wrapper// =============================================================================+/**+ * A query argument asking for write access, as {@link Mut} returns it. Opaque —+ * the query yields the component's data, not this.+ *+ * @public+ */export interface MutWrapper<T extends AnyComponentDef> {+ /** @internal */readonly _type: 'mut';+ /** @internal */readonly _component: T;}@@ -73,6 +81,13 @@ export function isChangedWrapper(value: unknown): value is ChangedWrapper<AnyCom* or a component wrapped for mutation / change detection. Exported so `system.ts`* can constrain `SystemParam` against the exact same set — the two must never drift.*/+/**+ * Anything {@link Query} accepts: a component for read access, or one wrapped in+ * {@link Mut} to write, `Added()` to match only entities that just gained it, or+ * `Changed()` to match only those whose copy was written since the last run.+ *+ * @public+ */export type QueryArg = AnyComponentDef | MutWrapper<AnyComponentDef> | AddedWrapper<AnyComponentDef> | ChangedWrapper<AnyComponentDef>;// =============================================================================@@ -182,19 +197,42 @@ function compileFilter(expr: FilterExpr, world: World): (entity: Entity) => bool// Query Descriptor// =============================================================================+/**+ * A settled query request in a system's parameter list. Opaque — the system body+ * receives a `QueryInstance` to iterate.+ *+ * @public+ */export interface QueryDescriptor<C extends readonly QueryArg[]> {+ /** @internal */readonly _type: 'query';+ /** @internal */readonly _components: C;+ /** @internal */readonly _mutIndices: number[];+ /** @internal */readonly _with: AnyComponentDef[];+ /** @internal */readonly _without: AnyComponentDef[];+ /** @internal */readonly _addedFilters: Array<{ index: number; component: AnyComponentDef }>;+ /** @internal */readonly _changedFilters: Array<{ index: number; component: AnyComponentDef }>;+ /** @internal */readonly _filter: FilterExpr | null;}+/**+ * A {@link Query} before it is handed to a system, narrowable by components the+ * match must or must not have. Each call returns a NEW builder, so narrowing a+ * shared query does not disturb it, and any of them is a valid parameter.+ *+ * @public+ */export interface QueryBuilder<C extends readonly QueryArg[]> extends QueryDescriptor<C> {+ /** Match only entities that also carry all of these; their data is not yielded. */with(...components: AnyComponentDef[]): QueryBuilder<C>;+ /** Exclude entities carrying any of these. */without(...components: AnyComponentDef[]): QueryBuilder<C>;/** Attach a composable filter expression. Replaces any prior call. */filter(expr: FilterExpr): QueryBuilder<C>;diff --git a/sdk/src/ecs/resource.ts b/sdk/src/ecs/resource.tsindex c28ae6af9..04884291a 100644--- a/sdk/src/ecs/resource.ts+++ b/sdk/src/ecs/resource.ts@@ -11,9 +11,19 @@ import { deepClone } from '../util/deepClone';// Resource Definition// =============================================================================+/**+ * A resource type, as {@link defineResource} returns it: the world holds one+ * value per definition. Opaque — pass it to `Res`/`ResMut`, `insertResource` or+ * `getResource` rather than reading it.+ *+ * @public+ */export interface ResourceDef<T> {+ /** @internal */readonly _id: symbol;+ /** @internal */readonly _name: string;+ /** @internal */readonly _default: T;}@@ -32,8 +42,16 @@ export function defineResource<T>(defaultValue: T, name?: string): ResourceDef<T// Resource Descriptors (for system parameters)// =============================================================================+/**+ * A request for read access to a resource, as {@link Res} returns it. Opaque —+ * the system body receives the resource value itself.+ *+ * @public+ */export interface ResDescriptor<T> {+ /** @internal */readonly _type: 'res';+ /** @internal */readonly _resource: ResourceDef<T>;}diff --git a/sdk/src/ecs/system.ts b/sdk/src/ecs/system.tsindex dc04ac90f..cdffd7305 100644--- a/sdk/src/ecs/system.ts+++ b/sdk/src/ecs/system.ts@@ -49,6 +49,13 @@ export function GetWorld(): GetWorldDescriptor {// System Parameter Types// =============================================================================+/**+ * Anything that may appear in a system's parameter list — what {@link Query},+ * {@link Res}, {@link Commands} and their siblings return. Each is a request for+ * access, resolved to a live value by {@link InferParams} when the system runs.+ *+ * @public+ */export type SystemParam =| QueryDescriptor<readonly QueryArg[]>| ResDescriptor<unknown>@@ -74,6 +81,13 @@ export type InferParam<P> =P extends GetWorldDescriptor ? World :never;+/**+ * The values a system body receives, derived from the parameters it declared —+ * a `Query(...)` becomes a `QueryInstance`, a `Res(X)` becomes the resource+ * value. Inferred, so a system body's arguments are typed without annotation.+ *+ * @public+ */export type InferParams<P extends readonly SystemParam[]> = {[K in keyof P]: InferParam<P[K]>;};@@ -85,17 +99,37 @@ export type InferParams<P extends readonly SystemParam[]> = {/** Predicate evaluated per-frame; returning false skips the system for that tick. */export type RunCondition = () => boolean;+/**+ * A declared system, as {@link defineSystem} returns it. Opaque: hand it to+ * `addSystem`, a {@link SystemSet} or a schedule rather than reading it — every+ * member is engine plumbing and may change.+ *+ * @public+ */export interface SystemDef {+ /** @internal */readonly _id: symbol;+ /** @internal */readonly _params: readonly SystemParam[];+ /** @internal */readonly _fn: (...args: never[]) => void | Promise<void>;+ /** @internal */readonly _name: string;+ /** @internal */readonly _runBefore?: readonly string[];+ /** @internal */readonly _runAfter?: readonly string[];}let templateCounter_ = 0;+/**+ * Ordering a system carries with it. The names are matched against other+ * systems' names and against {@link SystemSet} names, so a set can be ordered+ * against without knowing which systems are in it.+ *+ * @public+ */export interface SystemOptions {/** Name other systems reference in their ordering edges. */name?: string;diff --git a/sdk/tests/ecs-vocabulary.test.ts b/sdk/tests/ecs-vocabulary.test.tsnew file mode 100644index 000000000..2bd2cd4f1--- /dev/null+++ b/sdk/tests/ecs-vocabulary.test.ts@@ -0,0 +1,132 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file ecs-vocabulary.test.ts — the types the frozen ECS calls are spelled in.+ *+ * Freezing defineComponent/defineSystem/Query/Mut/Res/Commands freezes the+ * vocabulary their signatures are written in, so each of those types is pinned+ * here: annotated (which is the compile-time half) and asserted (the other one).+ */+import { describe, it, expect } from 'vitest';+import {+ defineComponent, defineSystem, defineResource, Query, Mut, Res, Commands, With, Added, Changed,+} from '../src/core';+import type {+ AnyComponentDef, ComponentDef, ComponentMetadata,+ QueryBuilder, QueryDescriptor, MutWrapper,+ ResourceDef, ResDescriptor, CommandsDescriptor, QueryArg,+ SystemDef, SystemOptions, SystemParam, InferParams,+} from '../src/core';++const Position = defineComponent('VocabPosition', { x: 0, y: 0 });+const Health = defineComponent('VocabHealth', { hp: 100 });++describe('component vocabulary', () => {+ it('defineComponent answers a ComponentDef that is also AnyComponentDef', () => {+ const def: ComponentDef<{ x: number; y: number }> = Position;+ const any: AnyComponentDef = def;+ expect(any).toBe(Position);+ expect(def.create()).toEqual({ x: 0, y: 0 });+ expect(def.create({ x: 5 })).toEqual({ x: 5, y: 0 });+ });++ it('carries the reflection a ComponentMetadata declared', () => {+ const meta: ComponentMetadata = {+ entityFields: ['target'],+ replicatedFields: ['hp'],+ transient: true,+ };+ const def = defineComponent('VocabMetaCarrier', { hp: 1, target: 0 }, meta);+ expect(def.entityFields).toEqual(['target']);+ expect(def.replicatedFields).toEqual(['hp']);+ expect(def.transient).toBe(true);+ });++ it('defaults the reflection when the metadata says nothing', () => {+ expect(Health.transient).toBe(false);+ expect(Health.replicatedFields).toEqual([]);+ expect(Health.renderableField).toBeNull();+ });+});++describe('query vocabulary', () => {+ it('Query answers a QueryBuilder, which is a usable QueryDescriptor', () => {+ const builder: QueryBuilder<[typeof Position]> = Query(Position);+ const descriptor: QueryDescriptor<[typeof Position]> = builder;+ expect(descriptor._components).toEqual([Position]);+ });++ it('with/without answer a NEW builder, leaving the one they narrowed alone', () => {+ const q = Query(Position);+ const narrowed = q.with(Health).without(Position);+ expect(narrowed).not.toBe(q);+ expect(narrowed._with).toEqual([Health]);+ expect(narrowed._without).toEqual([Position]);+ expect(q._with).toEqual([]);+ expect(q._without).toEqual([]);+ });++ it('filter replaces a prior expression rather than adding to it', () => {+ const q = Query(Position).filter(With(Health)).filter(With(Position));+ expect(q._filter).toEqual({ kind: 'with', component: Position });+ });++ it('QueryArg admits a bare component and each of the wrappers', () => {+ const args: QueryArg[] = [Position, Mut(Health), Added(Position), Changed(Health)];+ // Whatever the wrapper, the query matches on the component inside it.+ expect(Query(...args)._components).toHaveLength(4);+ expect(Query(Added(Position))._addedFilters).toEqual([{ index: 0, component: Position }]);+ expect(Query(Changed(Health))._changedFilters).toEqual([{ index: 0, component: Health }]);+ });++ it('Mut answers a MutWrapper the query records as a written index', () => {+ const wrapped: MutWrapper<typeof Position> = Mut(Position);+ expect(wrapped._component).toBe(Position);+ expect(Query(Health, wrapped)._mutIndices).toEqual([1]);+ });+});++describe('resource vocabulary', () => {+ it('defineResource answers a ResourceDef and Res a descriptor over it', () => {+ const Score: ResourceDef<{ points: number }> = defineResource({ points: 0 }, 'VocabScore');+ const descriptor: ResDescriptor<{ points: number }> = Res(Score);+ expect(descriptor._resource).toBe(Score);+ });+});++describe('system vocabulary', () => {+ it('every parameter factory answers something that is a SystemParam', () => {+ const commands: CommandsDescriptor = Commands();+ const params: SystemParam[] = [Query(Position), Res(defineResource(0)), commands];+ expect(params).toHaveLength(3);+ // Two calls are equal but not the same object — a descriptor is a request,+ // not a handle, so nothing may key off its identity.+ expect(Commands()).not.toBe(commands);+ expect(Commands()).toEqual(commands);+ });++ it('defineSystem answers a SystemDef carrying its declared parameters', () => {+ const def: SystemDef = defineSystem([Query(Position)], () => {});+ expect(def._params).toHaveLength(1);+ });++ it('SystemOptions ordering travels with the definition', () => {+ const options: SystemOptions = { name: 'vocab', runAfter: ['physics'] };+ const def = defineSystem([Commands()], () => {}, options);+ expect(def._name).toBe('vocab');+ expect(def._runAfter).toEqual(['physics']);+ });++ it('InferParams resolves a declaration to what the body is handed', () => {+ // The annotation is the assertion: a body typed against InferParams of+ // its own parameter list must accept the values the runner passes.+ const params = [Query(Position), Commands()] as const;+ const body = (...args: InferParams<typeof params>) => {+ const [q, commands] = args;+ return typeof q.forEach === 'function' && typeof commands.spawn === 'function';+ };+ let ran = false;+ defineSystem([...params], (q, commands) => { ran = body(q, commands); });+ expect(ran).toBe(false);+ });+});diff --git a/tools/api-surface.mjs b/tools/api-surface.mjsindex 69061f7e1..0b030718a 100644--- a/tools/api-surface.mjs+++ b/tools/api-surface.mjs@@ -14,7 +14,8 @@* @public frozen — 1.0 is expected not to break it* @beta may still adjust* @experimental no compatibility claim (the default)- * @internal must not be exported from a public entry+ * @internal must not be exported from a public entry; on a MEMBER it is+ * allowed and marked, and carries no promise** --check exit 1 on drift or policy violation* --update accept surface changes@@ -226,16 +227,11 @@ function memberLines(type, location, owner) {for (const member of type.getProperties()) {if (isPrivateMember(member)) continue;if (isAmbientMember(member)) continue;- // R1 only ever saw top-level exports, so an @internal member rode out in the- // public .d.ts with nothing to stop a creator autocompleting it.- const internal = tagNames(member).has('internal');- if (owner.tier === 'public' && internal) {- errors.push(`R3: '${owner.name}' is @public but its member '${member.name}' is @internal`);- }const memberType = checker.getTypeOfSymbolAtLocation(member, location);- // Kept in the snapshot because it is in the shipped .d.ts, marked because- // it carries no promise — what it names does not constrain the type's.- const mark = internal ? '@internal ' : '';+ // R1 only ever saw top-level exports, so an @internal member rode out in the+ // public .d.ts unannounced. Marked here, in the shipped .d.ts, and skipped by+ // the leak and baseline rules: it is present, and it promises nothing.+ const mark = tagNames(member).has('internal') ? '@internal ' : '';lines.push(`${mark}${member.name}: ${normalizeType(checker.typeToString(memberType, location, FMT))}`);}return lines.sort();diff --git a/tools/check-freeze-bar.mjs b/tools/check-freeze-bar.mjsindex 5fb760fe7..9afa6ed0a 100644--- a/tools/check-freeze-bar.mjs+++ b/tools/check-freeze-bar.mjs@@ -22,6 +22,7 @@* hole stays visible instead of passing for coverage.** node tools/check-freeze-bar.mjs+ * node tools/check-freeze-bar.mjs --why A,B,C what freezing these would cost*/import { readFileSync, readdirSync, existsSync } from 'node:fs';import { join, relative } from 'node:path';@@ -117,7 +118,28 @@ function exercisedByGolden() {// Report// ----------------------------------------------------------------------------const frozen = frozenSymbols();+const askFlag = process.argv.find((a) => a.startsWith('--why'));+const asked = askFlag+ ? (askFlag.includes('=') ? askFlag.split('=')[1] : process.argv[process.argv.indexOf(askFlag) + 1] ?? '')+ .split(',').map((s) => s.trim()).filter(Boolean)+ : [];++const frozen = asked.length ? new Map() : frozenSymbols();+if (asked.length) {+ // Planning a wave asks the bar about symbols that are not tagged yet, so the+ // kind comes from the snapshot the same way it does for a frozen one.+ const all = new Map();+ for (const entryName of Object.keys(ENTRIES)) {+ const file = join(ETC, `${entryName}.api.md`);+ if (!existsSync(file)) continue;+ for (const [name, s] of parseSnapshot(readFileSync(file, 'utf8'))) if (!all.has(name)) all.set(name, s.kind);+ }+ for (const name of asked) {+ if (all.has(name)) frozen.set(name, all.get(name));+ else console.error(` ${name} — not an exported symbol`);+ }+}+if (frozen.size === 0) {console.log('check-freeze-bar: nothing is @public yet — no promise to hold up.');process.exit(0);@@ -165,6 +187,16 @@ for (const [name, why] of Object.entries(EXEMPT)) {if (!frozen.has(name)) failures.push({ name, say: `is exempt from the freeze bar but is not @public — ${why}` });}+if (asked.length) {+ const short = (n) => `${n}${' '.repeat(Math.max(0, 22 - n.length))}`;+ for (const [name, kind] of frozen) {+ const f = failures.find((x) => x.name === name);+ console.log(` ${short(name)} ${kind.padEnd(10)} ${f ? f.say : 'meets the bar'}`);+ }+ console.log(`\n${frozen.size} asked, ${frozen.size - failures.length} would pass as they stand.`);+ process.exit(0);+}+const values = [...frozen].filter(([, k]) => VALUE_KINDS.has(k)).length;if (failures.length === 0) {const exempt = Object.keys(EXEMPT).length;diff --git a/tools/check-tier-leaks.mjs b/tools/check-tier-leaks.mjsindex e5d24bbe4..b1c6bdbc8 100644--- a/tools/check-tier-leaks.mjs+++ b/tools/check-tier-leaks.mjs@@ -28,12 +28,13 @@ import { parseSnapshot } from './lib/apiSnapshot.mjs';* defs and the parameter union — none of which has been through the freeze bar.*/export const ACCEPTED = {- Commands: 'the descriptor it returns is unfrozen ECS vocabulary',- Mut: 'the component-def union and wrapper are unfrozen ECS vocabulary',- Query: 'the argument union and builder are unfrozen ECS vocabulary',- Res: 'the resource def and descriptor are unfrozen ECS vocabulary',- defineComponent: 'the component def and its metadata are unfrozen ECS vocabulary',- defineSystem: 'the system def, params and options are unfrozen ECS vocabulary',+ AnyComponentDef: 'BuiltinComponentDef, the engine-side half of the union, is not frozen yet',+ ComponentDef: 'FieldMeta, the per-field editor policy it reflects, is not frozen yet',+ ComponentMetadata: 'FieldMeta, the per-field editor policy it declares, is not frozen yet',+ InferParams: 'InferParam, the per-parameter mapping it maps over, is not frozen yet',+ QueryArg: 'the Added and Changed wrappers it admits are not frozen yet',+ QueryBuilder: 'FilterExpr, the composable filter it accepts, is not frozen yet',+ SystemParam: 'the event, removed-query, res-mut and get-world descriptors are not frozen yet',};/** Every symbol across every entry, keeping the strongest tier any entry gives it. */diff --git a/tools/lib/apiSnapshot.mjs b/tools/lib/apiSnapshot.mjsindex 37b0098a7..c5d3bfa2b 100644--- a/tools/lib/apiSnapshot.mjs+++ b/tools/lib/apiSnapshot.mjs@@ -37,6 +37,15 @@ export function parseSnapshot(text) {return out;}+/**+ * The part of a body that carries a promise. An `@internal` member is in the+ * shipped `.d.ts` and in the snapshot so it is visible, but it is not something+ * a release promised, so changing one is not breaking one.+ */+export function promisedBody(body) {+ return body.split('\n').filter((l) => !l.startsWith('@internal ')).join('\n');+}+/*** Compare one entry against its released self. Only @public carries a promise,* so only @public produces a failure; @beta is noted because "may adjust" should@@ -56,12 +65,14 @@ export function baselineFindings(was, now) {failures.push(`${name} — @public at baseline, now @${after.tier}; a freeze does not thaw`);} else if (after.kind !== before.kind) {failures.push(`${name} — @public ${before.kind} became a ${after.kind}`);- } else if (after.body !== before.body) {+ } else if (promisedBody(after.body) !== promisedBody(before.body)) {failures.push(`${name} — @public signature changed`);}} else if (before.tier === 'beta') {if (!after) notes.push(`${name} — @beta removed`);- else if (after.body !== before.body) notes.push(`${name} — @beta signature changed`);+ else if (promisedBody(after.body) !== promisedBody(before.body)) {+ notes.push(`${name} — @beta signature changed`);+ }}}return { failures, notes };