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): the parameter factories are frozen as a set, not six of nine

esenginedd532017392d
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 49ea7c4c2..21bafa3c9 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -1,9 +1,9 @@
{
"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.",
"counts": {
- "public": 64,
+ "public": 71,
"beta": 24,
- "experimental": 1537,
+ "experimental": 1530,
"deprecated": 3
},
"total": 1625,
@@ -176,6 +176,30 @@
"minigame"
]
},
+ {
+ "name": "EventDef",
+ "kind": "interface",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "EventReader",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "EventReaderDescriptor",
"kind": "interface",
@@ -200,6 +224,18 @@
"minigame"
]
},
+ {
+ "name": "EventWriter",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "EventWriterDescriptor",
"kind": "interface",
@@ -488,6 +524,18 @@
"minigame"
]
},
+ {
+ "name": "ResMut",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "ResMutDescriptor",
"kind": "interface",
@@ -752,6 +800,30 @@
"minigame"
]
},
+ {
+ "name": "defineEvent",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
+ {
+ "name": "defineResource",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
+ },
{
"name": "defineSystem",
"kind": "function",
@@ -775,6 +847,18 @@
"wechat",
"minigame"
]
+ },
+ {
+ "name": "defineTag",
+ "kind": "function",
+ "deprecated": false,
+ "entries": [
+ "index",
+ "index.node",
+ "index.native",
+ "wechat",
+ "minigame"
+ ]
}
],
"beta": [
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 36ea2a4ba..2751856d5 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: 64 public · 17 beta · 1422 experimental · 3 deprecated
+Symbols: 71 public · 17 beta · 1415 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -2573,14 +2573,14 @@ params: Record<string, AiParamValue> | undefined
target: string | undefined
```
-## EventDef — interface @experimental
+## EventDef — interface @public
```
-_id: symbol
-_name: string
-_phantom: T | undefined
+@internal _id: symbol
+@internal _name: string
+@internal _phantom: T | undefined
```
-## EventReader — function @experimental
+## EventReader — function @public
```
<T>(event: EventDef<T>): EventReaderDescriptor<T>
```
@@ -2609,7 +2609,7 @@ static new (): EventRegistry
static prototype: EventRegistry
```
-## EventWriter — function @experimental
+## EventWriter — function @public
```
<T>(event: EventDef<T>): EventWriterDescriptor<T>
```
@@ -5579,7 +5579,7 @@ static prototype: ReplicationServer
@internal _type: "res"
```
-## ResMut — function @experimental
+## ResMut — function @public
```
<T>(resource: ResourceDef<T>): ResMutDescriptor<T>
```
@@ -9033,7 +9033,7 @@ PluralSelector
<T extends object>(name: string, defaults: T, metadata?: ComponentMetadata): ComponentDef<T>
```
-## defineEvent — function @experimental
+## defineEvent — function @public
```
<T>(name: string): EventDef<T>
```
@@ -9043,7 +9043,7 @@ PluralSelector
(actions: Record<string, ActionDef>): InputMap
```
-## defineResource — function @experimental
+## defineResource — function @public
```
<T>(defaultValue: T, name?: string): ResourceDef<T>
```
@@ -9058,7 +9058,7 @@ PluralSelector
(name: string, options: SystemSetOptions): SystemSet
```
-## defineTag — function @experimental
+## defineTag — function @public
```
(name: string): ComponentDef<{}>
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 94efbbe2d..6a046e5a6 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: 64 public · 22 beta · 1441 experimental · 3 deprecated
+Symbols: 71 public · 22 beta · 1434 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -2581,14 +2581,14 @@ params: Record<string, AiParamValue> | undefined
target: string | undefined
```
-## EventDef — interface @experimental
+## EventDef — interface @public
```
-_id: symbol
-_name: string
-_phantom: T | undefined
+@internal _id: symbol
+@internal _name: string
+@internal _phantom: T | undefined
```
-## EventReader — function @experimental
+## EventReader — function @public
```
<T>(event: EventDef<T>): EventReaderDescriptor<T>
```
@@ -2617,7 +2617,7 @@ static new (): EventRegistry
static prototype: EventRegistry
```
-## EventWriter — function @experimental
+## EventWriter — function @public
```
<T>(event: EventDef<T>): EventWriterDescriptor<T>
```
@@ -5772,7 +5772,7 @@ static prototype: ReplicationServer
@internal _type: "res"
```
-## ResMut — function @experimental
+## ResMut — function @public
```
<T>(resource: ResourceDef<T>): ResMutDescriptor<T>
```
@@ -9266,7 +9266,7 @@ PluralSelector
<T extends object>(name: string, defaults: T, metadata?: ComponentMetadata): ComponentDef<T>
```
-## defineEvent — function @experimental
+## defineEvent — function @public
```
<T>(name: string): EventDef<T>
```
@@ -9276,7 +9276,7 @@ PluralSelector
(actions: Record<string, ActionDef>): InputMap
```
-## defineResource — function @experimental
+## defineResource — function @public
```
<T>(defaultValue: T, name?: string): ResourceDef<T>
```
@@ -9291,7 +9291,7 @@ PluralSelector
(name: string, options: SystemSetOptions): SystemSet
```
-## defineTag — function @experimental
+## defineTag — function @public
```
(name: string): ComponentDef<{}>
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 5a5b25c46..4744a437b 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: 64 public · 19 beta · 1421 experimental · 3 deprecated
+Symbols: 71 public · 19 beta · 1414 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2568,14 +2568,14 @@ params: Record<string, AiParamValue> | undefined
target: string | undefined
```
-## EventDef — interface @experimental
+## EventDef — interface @public
```
-_id: symbol
-_name: string
-_phantom: T | undefined
+@internal _id: symbol
+@internal _name: string
+@internal _phantom: T | undefined
```
-## EventReader — function @experimental
+## EventReader — function @public
```
<T>(event: EventDef<T>): EventReaderDescriptor<T>
```
@@ -2604,7 +2604,7 @@ static new (): EventRegistry
static prototype: EventRegistry
```
-## EventWriter — function @experimental
+## EventWriter — function @public
```
<T>(event: EventDef<T>): EventWriterDescriptor<T>
```
@@ -5574,7 +5574,7 @@ static prototype: ReplicationServer
@internal _type: "res"
```
-## ResMut — function @experimental
+## ResMut — function @public
```
<T>(resource: ResourceDef<T>): ResMutDescriptor<T>
```
@@ -9028,7 +9028,7 @@ PluralSelector
<T extends object>(name: string, defaults: T, metadata?: ComponentMetadata): ComponentDef<T>
```
-## defineEvent — function @experimental
+## defineEvent — function @public
```
<T>(name: string): EventDef<T>
```
@@ -9038,7 +9038,7 @@ PluralSelector
(actions: Record<string, ActionDef>): InputMap
```
-## defineResource — function @experimental
+## defineResource — function @public
```
<T>(defaultValue: T, name?: string): ResourceDef<T>
```
@@ -9053,7 +9053,7 @@ PluralSelector
(name: string, options: SystemSetOptions): SystemSet
```
-## defineTag — function @experimental
+## defineTag — function @public
```
(name: string): ComponentDef<{}>
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index a5b139a57..da4d28309 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: 64 public · 17 beta · 1442 experimental · 3 deprecated
+Symbols: 71 public · 17 beta · 1435 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2568,14 +2568,14 @@ params: Record<string, AiParamValue> | undefined
target: string | undefined
```
-## EventDef — interface @experimental
+## EventDef — interface @public
```
-_id: symbol
-_name: string
-_phantom: T | undefined
+@internal _id: symbol
+@internal _name: string
+@internal _phantom: T | undefined
```
-## EventReader — function @experimental
+## EventReader — function @public
```
<T>(event: EventDef<T>): EventReaderDescriptor<T>
```
@@ -2604,7 +2604,7 @@ static new (): EventRegistry
static prototype: EventRegistry
```
-## EventWriter — function @experimental
+## EventWriter — function @public
```
<T>(event: EventDef<T>): EventWriterDescriptor<T>
```
@@ -5819,7 +5819,7 @@ static prototype: ReplicationServer
@internal _type: "res"
```
-## ResMut — function @experimental
+## ResMut — function @public
```
<T>(resource: ResourceDef<T>): ResMutDescriptor<T>
```
@@ -9278,7 +9278,7 @@ PluralSelector
<T extends object>(name: string, defaults: T, metadata?: ComponentMetadata): ComponentDef<T>
```
-## defineEvent — function @experimental
+## defineEvent — function @public
```
<T>(name: string): EventDef<T>
```
@@ -9288,7 +9288,7 @@ PluralSelector
(actions: Record<string, ActionDef>): InputMap
```
-## defineResource — function @experimental
+## defineResource — function @public
```
<T>(defaultValue: T, name?: string): ResourceDef<T>
```
@@ -9303,7 +9303,7 @@ PluralSelector
(name: string, options: SystemSetOptions): SystemSet
```
-## defineTag — function @experimental
+## defineTag — function @public
```
(name: string): ComponentDef<{}>
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 03f9db3c8..e52f86238 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: 64 public · 17 beta · 1432 experimental · 3 deprecated
+Symbols: 71 public · 17 beta · 1425 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -2568,14 +2568,14 @@ params: Record<string, AiParamValue> | undefined
target: string | undefined
```
-## EventDef — interface @experimental
+## EventDef — interface @public
```
-_id: symbol
-_name: string
-_phantom: T | undefined
+@internal _id: symbol
+@internal _name: string
+@internal _phantom: T | undefined
```
-## EventReader — function @experimental
+## EventReader — function @public
```
<T>(event: EventDef<T>): EventReaderDescriptor<T>
```
@@ -2604,7 +2604,7 @@ static new (): EventRegistry
static prototype: EventRegistry
```
-## EventWriter — function @experimental
+## EventWriter — function @public
```
<T>(event: EventDef<T>): EventWriterDescriptor<T>
```
@@ -5581,7 +5581,7 @@ static prototype: ReplicationServer
@internal _type: "res"
```
-## ResMut — function @experimental
+## ResMut — function @public
```
<T>(resource: ResourceDef<T>): ResMutDescriptor<T>
```
@@ -9055,7 +9055,7 @@ PluralSelector
<T extends object>(name: string, defaults: T, metadata?: ComponentMetadata): ComponentDef<T>
```
-## defineEvent — function @experimental
+## defineEvent — function @public
```
<T>(name: string): EventDef<T>
```
@@ -9065,7 +9065,7 @@ PluralSelector
(actions: Record<string, ActionDef>): InputMap
```
-## defineResource — function @experimental
+## defineResource — function @public
```
<T>(defaultValue: T, name?: string): ResourceDef<T>
```
@@ -9080,7 +9080,7 @@ PluralSelector
(name: string, options: SystemSetOptions): SystemSet
```
-## defineTag — function @experimental
+## defineTag — function @public
```
(name: string): ComponentDef<{}>
```
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index 34235f11f..3fb648456 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -373,6 +373,14 @@ export function defineComponent<T extends object>(
return def;
}
+/**
+ * Declare a component with no fields — a marker a query filters on. Returning
+ * the existing definition for a name already declared is deliberate: a tag
+ * carries no data, so re-declaring one cannot conflict with itself the way
+ * {@link defineComponent} can.
+ *
+ * @public
+ */
export function defineTag(name: string): ComponentDef<{}> {
const existing = userComponents().get(name);
if (existing) return existing as ComponentDef<{}>;
diff --git a/sdk/src/ecs/event.ts b/sdk/src/ecs/event.ts
index 5c15e6f50..4d19bf94e 100644
--- a/sdk/src/ecs/event.ts
+++ b/sdk/src/ecs/event.ts
@@ -9,12 +9,28 @@
// Event Definition
// =============================================================================
+/**
+ * An event type, as {@link defineEvent} returns it. Opaque — pass it to
+ * {@link EventWriter} / {@link EventReader} rather than reading it.
+ *
+ * @public
+ */
export interface EventDef<T> {
+ /** @internal */
readonly _id: symbol;
+ /** @internal */
readonly _name: string;
+ /** @internal */
readonly _phantom?: T;
}
+/**
+ * Declare an event type. The bus is double-buffered: an event sent this frame is
+ * readable for exactly the next one, so a reader that misses a frame misses the
+ * event — events are for this-frame signalling, not a queue.
+ *
+ * @public
+ */
export function defineEvent<T>(name: string): EventDef<T> {
return {
_id: Symbol(`Event_${name}`),
@@ -105,10 +121,23 @@ export interface EventReaderDescriptor<T> {
readonly _event: EventDef<T>;
}
+/**
+ * Ask a system for send access to an event. The body receives an
+ * {@link EventWriterInstance}; what it sends is readable next frame.
+ *
+ * @public
+ */
export function EventWriter<T>(event: EventDef<T>): EventWriterDescriptor<T> {
return { _type: 'event_writer', _event: event };
}
+/**
+ * Ask a system for receive access to an event. Each declaring system keeps its
+ * own cursor, so two readers both see every event rather than consuming it from
+ * each other.
+ *
+ * @public
+ */
export function EventReader<T>(event: EventDef<T>): EventReaderDescriptor<T> {
return { _type: 'event_reader', _event: event };
}
diff --git a/sdk/src/ecs/resource.ts b/sdk/src/ecs/resource.ts
index 378917669..481f864a7 100644
--- a/sdk/src/ecs/resource.ts
+++ b/sdk/src/ecs/resource.ts
@@ -29,6 +29,13 @@ export interface ResourceDef<T> {
let resourceCounter = 0;
+/**
+ * Declare a resource: one value the whole world shares, addressed by the
+ * definition rather than by a name. `name` is for diagnostics and the editor
+ * only — two calls answer two distinct resources however they are named.
+ *
+ * @public
+ */
export function defineResource<T>(defaultValue: T, name?: string): ResourceDef<T> {
const id = ++resourceCounter;
return {
@@ -82,6 +89,13 @@ export function Res<T>(resource: ResourceDef<T>): ResDescriptor<T> {
return { _type: 'res', _resource: resource };
}
+/**
+ * Ask a system for write access to a resource. The body receives a
+ * {@link ResMutInstance}, not the value: `set` or `modify` is what stores it back
+ * and stamps the change tick a `Changed` filter reads.
+ *
+ * @public
+ */
export function ResMut<T>(resource: ResourceDef<T>): ResMutDescriptor<T> {
return { _type: 'res_mut', _resource: resource };
}
diff --git a/sdk/tests/ecs-vocabulary.test.ts b/sdk/tests/ecs-vocabulary.test.ts
index ecab752cf..707da14df 100644
--- a/sdk/tests/ecs-vocabulary.test.ts
+++ b/sdk/tests/ecs-vocabulary.test.ts
@@ -12,7 +12,7 @@ import {
defineComponent, defineSystem, defineResource, defineEvent, Query, Mut, Res, ResMut,
Commands, With, Without, And, Or, Not, Added, Changed, Removed,
EventReader, EventWriter, GetWorld, Transform, World, QueryInstance,
- Parent, Children, Name, getComponentDefaults,
+ Parent, Children, Name, getComponentDefaults, defineTag,
vec2, vec3, vec4, quat, color,
} from '../src/core';
import type {
@@ -20,7 +20,7 @@ import type {
QueryBuilder, QueryDescriptor, MutWrapper, AddedWrapper, ChangedWrapper,
FilterExpr, RemovedQueryDescriptor,
ResourceDef, ResDescriptor, ResMutDescriptor, CommandsDescriptor, QueryArg,
- EventReaderDescriptor, EventWriterDescriptor, GetWorldDescriptor,
+ EventDef, EventReaderDescriptor, EventWriterDescriptor, GetWorldDescriptor,
SystemDef, SystemOptions, SystemParam, InferParam, InferParams,
Entity, QueryResult, ChildrenData, ParentData, NameData, TransformData,
Vec2, Vec3, Vec4, Quat, Color,
@@ -184,6 +184,33 @@ describe('resource vocabulary', () => {
const descriptor: ResDescriptor<{ points: number }> = Res(Score);
expect(descriptor._resource).toBe(Score);
});
+
+ it('two definitions are two resources however they are named', () => {
+ // The name is diagnostics, not identity: a project that reuses one must
+ // still get its own value rather than silently sharing.
+ const a = defineResource(0, 'VocabDuplicate');
+ const b = defineResource(0, 'VocabDuplicate');
+ expect(a._id).not.toBe(b._id);
+ });
+});
+
+describe('event vocabulary', () => {
+ it('defineEvent answers an EventDef both descriptors are built over', () => {
+ const Hit: EventDef<{ damage: number }> = defineEvent('VocabHit');
+ const writer: EventWriterDescriptor<{ damage: number }> = EventWriter(Hit);
+ const reader: EventReaderDescriptor<{ damage: number }> = EventReader(Hit);
+ expect(writer._event).toBe(Hit);
+ expect(reader._event).toBe(Hit);
+ });
+});
+
+describe('tag vocabulary', () => {
+ it('defineTag answers a fieldless ComponentDef, and the same one twice', () => {
+ const Frozen: ComponentDef<{}> = defineTag('VocabFrozen');
+ expect(Frozen.create()).toEqual({});
+ // A tag carries no data, so re-declaring one cannot conflict with itself.
+ expect(defineTag('VocabFrozen')).toBe(Frozen);
+ });
});
describe('system vocabulary', () => {