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): 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.jsonindex 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.mdindex 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> | undefinedtarget: 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 (): EventRegistrystatic 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.mdindex 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> | undefinedtarget: 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 (): EventRegistrystatic 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.mdindex 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> | undefinedtarget: 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 (): EventRegistrystatic 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.mdindex 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> | undefinedtarget: 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 (): EventRegistrystatic 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.mdindex 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> | undefinedtarget: 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 (): EventRegistrystatic 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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', () => {