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(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.ts
index 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.json
index 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.md
index 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 | undefined
to: 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: string
animatableFields: readonly string[]
assetFields: readonly AssetFieldMeta[]
colorKeys: readonly string[]
@@ -1818,7 +1818,7 @@ skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
```
-## ComponentMetadata — interface @experimental
+## ComponentMetadata — interface @public
```
animatableFields: string[] | undefined
assetFields: 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 | undefined
textureWidth: 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 | undefined
runAfter: string[] | undefined
runBefore: 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.md
index 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 | undefined
to: 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: string
animatableFields: 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[] | undefined
assetFields: 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 | undefined
textureWidth: 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 | undefined
runAfter: string[] | undefined
runBefore: 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.md
index 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 | undefined
to: 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: string
animatableFields: readonly string[]
assetFields: readonly AssetFieldMeta[]
colorKeys: readonly string[]
@@ -1813,7 +1813,7 @@ skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
```
-## ComponentMetadata — interface @experimental
+## ComponentMetadata — interface @public
```
animatableFields: string[] | undefined
assetFields: 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 | undefined
textureWidth: 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 | undefined
runAfter: string[] | undefined
runBefore: 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.md
index 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 | undefined
to: 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: string
animatableFields: readonly string[]
assetFields: readonly AssetFieldMeta[]
colorKeys: readonly string[]
@@ -1813,7 +1813,7 @@ skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
```
-## ComponentMetadata — interface @experimental
+## ComponentMetadata — interface @public
```
animatableFields: string[] | undefined
assetFields: 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 | undefined
textureWidth: 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 | undefined
runAfter: string[] | undefined
runBefore: 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.md
index 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 | undefined
to: 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: string
animatableFields: readonly string[]
assetFields: readonly AssetFieldMeta[]
colorKeys: readonly string[]
@@ -1813,7 +1813,7 @@ skeletalFields: SkeletalFieldMeta | undefined
transient: boolean
```
-## ComponentMetadata — interface @experimental
+## ComponentMetadata — interface @public
```
animatableFields: string[] | undefined
assetFields: 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 | undefined
textureWidth: 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 | undefined
runAfter: string[] | undefined
runBefore: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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 };