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(components): a component declares its stability where it declares everything else
yhhd0109bee3b18
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex b7d5ce1e5..d46fae243 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -1,10 +1,10 @@{"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.","counts": {- "public": 40,+ "public": 54,"beta": 24,- "experimental": 1561,- "deprecated": 1+ "experimental": 1547,+ "deprecated": 3},"total": 1625,"public": [@@ -56,6 +56,42 @@"minigame"]},+ {+ "name": "Children",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ChildrenData",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Color",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "Commands","kind": "function",@@ -272,6 +308,66 @@"minigame"]},+ {+ "name": "Name",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "NameData",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Parent",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ParentData",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Quat",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "Query","kind": "function",@@ -428,6 +524,18 @@"minigame"]},+ {+ "name": "RuntimeOnly",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "SystemDef","kind": "interface",@@ -464,6 +572,66 @@"minigame"]},+ {+ "name": "Transform",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "TransformData",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Vec2",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Vec3",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "Vec4",+ "kind": "interface",+ "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 8602fecaa..4e11aa642 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: 40 public · 17 beta · 1446 experimental · 1 deprecated+Symbols: 54 public · 17 beta · 1432 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1641,12 +1641,12 @@ up: Vec2velocity: Vec2```-## Children — const @experimental+## Children — const @public```BuiltinComponentDef<ChildrenData>```-## ChildrenData — interface @experimental+## ChildrenData — interface @public```entities: number[]```@@ -1735,7 +1735,7 @@ friction: number | undefinedrestitution: number | undefined```-## Color — interface @experimental+## Color — interface @public```a: numberb: number@@ -3723,7 +3723,7 @@ height: number | undefinedwidth: number | undefined```-## LocalTransform — const @experimental+## LocalTransform — const @experimental @deprecated```BuiltinComponentDef<TransformData>```@@ -4120,12 +4120,12 @@ ComponentDef<MotorJointData>Record<GraphNodeType, NodeSpec>```-## Name — const @experimental+## Name — const @public```ComponentDef<NameData>```-## NameData — interface @experimental+## NameData — interface @public```value: string```@@ -4346,12 +4346,12 @@ uiThemeColors: Record<string, string> | undefinedySortLayers: number | undefined```-## Parent — const @experimental+## Parent — const @public```BuiltinComponentDef<ParentData>```-## ParentData — interface @experimental+## ParentData — interface @public```entity: number```@@ -5296,7 +5296,7 @@ fields: readonly PtrFieldDesc[]ptrFn: string```-## Quat — interface @experimental+## Quat — interface @public```w: numberx: number@@ -5746,7 +5746,7 @@ uiTheme: "dark" | "light" | undefineduiThemeOverrides: ThemeOverrides | undefined```-## RuntimeOnly — const @experimental+## RuntimeOnly — const @public```ComponentDef<{}>```@@ -7606,12 +7606,12 @@ forward: () => voidreverse: () => void```-## Transform — const @experimental+## Transform — const @public```BuiltinComponentDef<TransformData>```-## TransformData — interface @experimental+## TransformData — interface @public```position: Vec3rotation: Quat@@ -8085,7 +8085,7 @@ static new (manager: ValueTweenManager, id: number): ValueTweenHandlestatic prototype: ValueTweenHandle```-## Vec2 — interface @experimental+## Vec2 — interface @public```x: numbery: number@@ -8097,14 +8097,14 @@ x: numbery: number```-## Vec3 — interface @experimental+## Vec3 — interface @public```x: numbery: numberz: number```-## Vec4 — interface @experimental+## Vec4 — interface @public```w: numberx: number@@ -8363,7 +8363,7 @@ right: numbertop: number```-## WorldTransform — const @experimental+## WorldTransform — const @experimental @deprecated```BuiltinComponentDef<TransformData>```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 4d22b2996..ecd7258cd 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: 40 public · 22 beta · 1465 experimental · 1 deprecated+Symbols: 54 public · 22 beta · 1451 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -1641,12 +1641,12 @@ up: Vec2velocity: Vec2```-## Children — const @experimental+## Children — const @public```BuiltinComponentDef<ChildrenData>```-## ChildrenData — interface @experimental+## ChildrenData — interface @public```entities: number[]```@@ -1735,7 +1735,7 @@ friction: number | undefinedrestitution: number | undefined```-## Color — interface @experimental+## Color — interface @public```a: numberb: number@@ -3731,7 +3731,7 @@ height: number | undefinedwidth: number | undefined```-## LocalTransform — const @experimental+## LocalTransform — const @experimental @deprecated```BuiltinComponentDef<TransformData>```@@ -4133,12 +4133,12 @@ ComponentDef<MotorJointData>Record<GraphNodeType, NodeSpec>```-## Name — const @experimental+## Name — const @public```ComponentDef<NameData>```-## NameData — interface @experimental+## NameData — interface @public```value: string```@@ -4529,12 +4529,12 @@ uiThemeColors: Record<string, string> | undefinedySortLayers: number | undefined```-## Parent — const @experimental+## Parent — const @public```BuiltinComponentDef<ParentData>```-## ParentData — interface @experimental+## ParentData — interface @public```entity: number```@@ -5479,7 +5479,7 @@ fields: readonly PtrFieldDesc[]ptrFn: string```-## Quat — interface @experimental+## Quat — interface @public```w: numberx: number@@ -5939,7 +5939,7 @@ uiTheme: "dark" | "light" | undefineduiThemeOverrides: ThemeOverrides | undefined```-## RuntimeOnly — const @experimental+## RuntimeOnly — const @public```ComponentDef<{}>```@@ -7799,12 +7799,12 @@ forward: () => voidreverse: () => void```-## Transform — const @experimental+## Transform — const @public```BuiltinComponentDef<TransformData>```-## TransformData — interface @experimental+## TransformData — interface @public```position: Vec3rotation: Quat@@ -8278,7 +8278,7 @@ static new (manager: ValueTweenManager, id: number): ValueTweenHandlestatic prototype: ValueTweenHandle```-## Vec2 — interface @experimental+## Vec2 — interface @public```x: numbery: number@@ -8290,14 +8290,14 @@ x: numbery: number```-## Vec3 — interface @experimental+## Vec3 — interface @public```x: numbery: numberz: number```-## Vec4 — interface @experimental+## Vec4 — interface @public```w: numberx: number@@ -8556,7 +8556,7 @@ right: numbertop: number```-## WorldTransform — const @experimental+## WorldTransform — const @experimental @deprecated```BuiltinComponentDef<TransformData>```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex ffce066e7..ab119002c 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: 40 public · 19 beta · 1445 experimental · 1 deprecated+Symbols: 54 public · 19 beta · 1431 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1636,12 +1636,12 @@ up: Vec2velocity: Vec2```-## Children — const @experimental+## Children — const @public```BuiltinComponentDef<ChildrenData>```-## ChildrenData — interface @experimental+## ChildrenData — interface @public```entities: number[]```@@ -1730,7 +1730,7 @@ friction: number | undefinedrestitution: number | undefined```-## Color — interface @experimental+## Color — interface @public```a: numberb: number@@ -3718,7 +3718,7 @@ height: number | undefinedwidth: number | undefined```-## LocalTransform — const @experimental+## LocalTransform — const @experimental @deprecated```BuiltinComponentDef<TransformData>```@@ -4115,12 +4115,12 @@ ComponentDef<MotorJointData>Record<GraphNodeType, NodeSpec>```-## Name — const @experimental+## Name — const @public```ComponentDef<NameData>```-## NameData — interface @experimental+## NameData — interface @public```value: string```@@ -4341,12 +4341,12 @@ uiThemeColors: Record<string, string> | undefinedySortLayers: number | undefined```-## Parent — const @experimental+## Parent — const @public```BuiltinComponentDef<ParentData>```-## ParentData — interface @experimental+## ParentData — interface @public```entity: number```@@ -5291,7 +5291,7 @@ fields: readonly PtrFieldDesc[]ptrFn: string```-## Quat — interface @experimental+## Quat — interface @public```w: numberx: number@@ -5741,7 +5741,7 @@ uiTheme: "dark" | "light" | undefineduiThemeOverrides: ThemeOverrides | undefined```-## RuntimeOnly — const @experimental+## RuntimeOnly — const @public```ComponentDef<{}>```@@ -7601,12 +7601,12 @@ forward: () => voidreverse: () => void```-## Transform — const @experimental+## Transform — const @public```BuiltinComponentDef<TransformData>```-## TransformData — interface @experimental+## TransformData — interface @public```position: Vec3rotation: Quat@@ -8080,7 +8080,7 @@ static new (manager: ValueTweenManager, id: number): ValueTweenHandlestatic prototype: ValueTweenHandle```-## Vec2 — interface @experimental+## Vec2 — interface @public```x: numbery: number@@ -8092,14 +8092,14 @@ x: numbery: number```-## Vec3 — interface @experimental+## Vec3 — interface @public```x: numbery: numberz: number```-## Vec4 — interface @experimental+## Vec4 — interface @public```w: numberx: number@@ -8358,7 +8358,7 @@ right: numbertop: number```-## WorldTransform — const @experimental+## WorldTransform — const @experimental @deprecated```BuiltinComponentDef<TransformData>```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 96c13cad0..9deec97c9 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: 40 public · 17 beta · 1466 experimental · 1 deprecated+Symbols: 54 public · 17 beta · 1452 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1636,12 +1636,12 @@ up: Vec2velocity: Vec2```-## Children — const @experimental+## Children — const @public```BuiltinComponentDef<ChildrenData>```-## ChildrenData — interface @experimental+## ChildrenData — interface @public```entities: number[]```@@ -1730,7 +1730,7 @@ friction: number | undefinedrestitution: number | undefined```-## Color — interface @experimental+## Color — interface @public```a: numberb: number@@ -3718,7 +3718,7 @@ height: number | undefinedwidth: number | undefined```-## LocalTransform — const @experimental+## LocalTransform — const @experimental @deprecated```BuiltinComponentDef<TransformData>```@@ -4360,12 +4360,12 @@ ComponentDef<MotorJointData>Record<GraphNodeType, NodeSpec>```-## Name — const @experimental+## Name — const @public```ComponentDef<NameData>```-## NameData — interface @experimental+## NameData — interface @public```value: string```@@ -4586,12 +4586,12 @@ uiThemeColors: Record<string, string> | undefinedySortLayers: number | undefined```-## Parent — const @experimental+## Parent — const @public```BuiltinComponentDef<ParentData>```-## ParentData — interface @experimental+## ParentData — interface @public```entity: number```@@ -5536,7 +5536,7 @@ fields: readonly PtrFieldDesc[]ptrFn: string```-## Quat — interface @experimental+## Quat — interface @public```w: numberx: number@@ -5986,7 +5986,7 @@ uiTheme: "dark" | "light" | undefineduiThemeOverrides: ThemeOverrides | undefined```-## RuntimeOnly — const @experimental+## RuntimeOnly — const @public```ComponentDef<{}>```@@ -7846,12 +7846,12 @@ forward: () => voidreverse: () => void```-## Transform — const @experimental+## Transform — const @public```BuiltinComponentDef<TransformData>```-## TransformData — interface @experimental+## TransformData — interface @public```position: Vec3rotation: Quat@@ -8325,7 +8325,7 @@ static new (manager: ValueTweenManager, id: number): ValueTweenHandlestatic prototype: ValueTweenHandle```-## Vec2 — interface @experimental+## Vec2 — interface @public```x: numbery: number@@ -8337,14 +8337,14 @@ x: numbery: number```-## Vec3 — interface @experimental+## Vec3 — interface @public```x: numbery: numberz: number```-## Vec4 — interface @experimental+## Vec4 — interface @public```w: numberx: number@@ -8603,7 +8603,7 @@ right: numbertop: number```-## WorldTransform — const @experimental+## WorldTransform — const @experimental @deprecated```BuiltinComponentDef<TransformData>```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 210350398..d0e8903b7 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: 40 public · 17 beta · 1456 experimental · 1 deprecated+Symbols: 54 public · 17 beta · 1442 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -1636,12 +1636,12 @@ up: Vec2velocity: Vec2```-## Children — const @experimental+## Children — const @public```BuiltinComponentDef<ChildrenData>```-## ChildrenData — interface @experimental+## ChildrenData — interface @public```entities: number[]```@@ -1730,7 +1730,7 @@ friction: number | undefinedrestitution: number | undefined```-## Color — interface @experimental+## Color — interface @public```a: numberb: number@@ -3725,7 +3725,7 @@ height: number | undefinedwidth: number | undefined```-## LocalTransform — const @experimental+## LocalTransform — const @experimental @deprecated```BuiltinComponentDef<TransformData>```@@ -4122,12 +4122,12 @@ ComponentDef<MotorJointData>Record<GraphNodeType, NodeSpec>```-## Name — const @experimental+## Name — const @public```ComponentDef<NameData>```-## NameData — interface @experimental+## NameData — interface @public```value: string```@@ -4348,12 +4348,12 @@ uiThemeColors: Record<string, string> | undefinedySortLayers: number | undefined```-## Parent — const @experimental+## Parent — const @public```BuiltinComponentDef<ParentData>```-## ParentData — interface @experimental+## ParentData — interface @public```entity: number```@@ -5298,7 +5298,7 @@ fields: readonly PtrFieldDesc[]ptrFn: string```-## Quat — interface @experimental+## Quat — interface @public```w: numberx: number@@ -5748,7 +5748,7 @@ uiTheme: "dark" | "light" | undefineduiThemeOverrides: ThemeOverrides | undefined```-## RuntimeOnly — const @experimental+## RuntimeOnly — const @public```ComponentDef<{}>```@@ -7608,12 +7608,12 @@ forward: () => voidreverse: () => void```-## Transform — const @experimental+## Transform — const @public```BuiltinComponentDef<TransformData>```-## TransformData — interface @experimental+## TransformData — interface @public```position: Vec3rotation: Quat@@ -8087,7 +8087,7 @@ static new (manager: ValueTweenManager, id: number): ValueTweenHandlestatic prototype: ValueTweenHandle```-## Vec2 — interface @experimental+## Vec2 — interface @public```x: numbery: number@@ -8099,14 +8099,14 @@ x: numbery: number```-## Vec3 — interface @experimental+## Vec3 — interface @public```x: numbery: numberz: number```-## Vec4 — interface @experimental+## Vec4 — interface @public```w: numberx: number@@ -8385,7 +8385,7 @@ right: numbertop: number```-## WorldTransform — const @experimental+## WorldTransform — const @experimental @deprecated```BuiltinComponentDef<TransformData>```diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex f371c0a12..ea7cb132c 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -914,6 +914,12 @@ export interface CapsuleColliderData {maskBits: number;}+/**+ * The fields of the engine's `Children` component, generated from+ * the C++ struct so the two shapes cannot drift.+ *+ * @public+ */export interface ChildrenData {entities: Entity[];}@@ -987,6 +993,12 @@ export interface Mesh2DData {enabled: boolean;}+/**+ * The fields of the engine's `Parent` component, generated from+ * the C++ struct so the two shapes cannot drift.+ *+ * @public+ */export interface ParentData {entity: Entity;}@@ -1165,6 +1177,12 @@ export interface TrailRendererData {enabled: boolean;}+/**+ * The fields of the engine's `Transform` component, generated from+ * the C++ struct so the two shapes cannot drift.+ *+ * @public+ */export interface TransformData {position: Vec3;rotation: Quat;diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.tsindex 883b38845..34235f11f 100644--- a/sdk/src/ecs/component.ts+++ b/sdk/src/ecs/component.ts@@ -755,6 +755,12 @@ export interface CameraData extends CameraDataCpp {showFrustum: boolean;}+/**+ * {@link Name}'s single field. TS-only: the engine keeps names in its own index+ * rather than as a C++ component.+ *+ * @public+ */export interface NameData {value: string;}@@ -786,10 +792,25 @@ function metaDefaults<T>(name: string, overrides?: Partial<T>): T {// can't be a static annotation — `enum`/`flags` built from a runtime TS constant, or a// TS-only field with no C++ backing — stays here as a per-field override (deep-merged// over the generated base by defineBuiltin).+/**+ * Where an entity is. `position`/`rotation`/`scale` are the authoring inputs,+ * relative to the parent; `worldPosition`/`worldRotation`/`worldScale` are what+ * the engine composed from them and must not be written back.+ *+ * @public+ */export const Transform = defineBuiltin<TransformData>('Transform',metaDefaults<TransformData>('Transform'));+/**+ * @deprecated A legacy spelling of {@link Transform} — the same component. Scene+ * loading normalises the name away, and both spellings will go at 1.0.+ */export const LocalTransform = Transform;+/**+ * @deprecated A legacy spelling of {@link Transform} — the same component, whose+ * world fields it was once separate from. Read `Transform.worldPosition` instead.+ */export const WorldTransform = Transform;// size's authoring default (100×100 vs the {1,1} ctor value) is authored at the@@ -845,10 +866,24 @@ export const Velocity = defineBuiltin<VelocityData>('Velocity',metaDefaults<VelocityData>('Velocity'));+/**+ * An entity's parent. The engine keeps this and {@link Children} in step, so+ * set the relationship through `world.setParent` rather than by writing either+ * side; a transform composes against whatever this names.+ *+ * @public+ */export const Parent = defineBuiltin<ParentData>('Parent',metaDefaults<ParentData>('Parent'));+/**+ * An entity's children, in order. The order is the draw order within a layer+ * for UI, and the engine maintains the list — {@link Parent} is the side to+ * write.+ *+ * @public+ */export const Children = defineBuiltin<ChildrenData>('Children',metaDefaults<ChildrenData>('Children'));@@ -978,6 +1013,10 @@ export const ParticleEmitter = defineBuiltin<ParticleEmitterData>('ParticleEmitt});+/**+ * Marks an entity inactive: it keeps its components and its place in the tree,+ * and the engine's systems skip it. A tag, so it carries no data.+ */export const Disabled = defineTag('Disabled');/**@@ -985,9 +1024,17 @@ export const Disabled = defineTag('Disabled');* (the child layer entities a `Tilemap.source` projects, runtime tile* colliders, …). Scene serialization skips tagged entities entirely:* persisting one would duplicate it against the next derivation.+ *+ * @public*/export const RuntimeOnly = defineTag('RuntimeOnly');+/**+ * An entity's name — what the outliner shows and `findEntityByName` looks up.+ * Not an identity: nothing stops two entities sharing one.+ *+ * @public+ */export const Name = defineComponent<NameData>('Name', { value: '' });export const SceneOwner = defineComponent<SceneOwnerData>('SceneOwner', {diff --git a/sdk/src/types.ts b/sdk/src/types.tsindex cb25b056a..a8f3e875a 100644--- a/sdk/src/types.ts+++ b/sdk/src/types.ts@@ -88,17 +88,35 @@ export const INVALID_MATERIAL = 0;// Math Types// =============================================================================+/**+ * A 2D vector in world units. Plain data, so it is what a component field holds+ * and what crosses to the engine — `v2` builds one, and `scalar`/`v2` carry the+ * operations rather than the value.+ *+ * @public+ */export interface Vec2 {x: number;y: number;}+/**+ * A 3D vector. `z` orders drawing within a layer rather than adding depth: the+ * renderer is 2D, and a Transform's z is a sort key.+ *+ * @public+ */export interface Vec3 {x: number;y: number;z: number;}+/**+ * Four components, for a shader uniform or a rect passed as one value.+ *+ * @public+ */export interface Vec4 {x: number;y: number;@@ -106,6 +124,13 @@ export interface Vec4 {w: number;}+/**+ * A rotation. Stored as a quaternion because the engine composes transforms+ * with it; for 2D work, `quat`'s helpers and `quaternionToAngle2D` are the way+ * in and out of an angle.+ *+ * @public+ */export interface Quat {w: number;x: number;@@ -113,6 +138,11 @@ export interface Quat {z: number;}+/**+ * A colour with straight (non-premultiplied) alpha, each channel 0..1.+ *+ * @public+ */export interface Color {r: number;g: number;diff --git a/sdk/tests/ecs-vocabulary.test.ts b/sdk/tests/ecs-vocabulary.test.tsindex 2c1c8fafd..ecab752cf 100644--- a/sdk/tests/ecs-vocabulary.test.ts+++ b/sdk/tests/ecs-vocabulary.test.ts@@ -12,6 +12,8 @@ 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,+ vec2, vec3, vec4, quat, color,} from '../src/core';import type {AnyComponentDef, BuiltinComponentDef, ComponentDef, ComponentMetadata, FieldMeta,@@ -20,7 +22,8 @@ import type {ResourceDef, ResDescriptor, ResMutDescriptor, CommandsDescriptor, QueryArg,EventReaderDescriptor, EventWriterDescriptor, GetWorldDescriptor,SystemDef, SystemOptions, SystemParam, InferParam, InferParams,- Entity, QueryResult,+ Entity, QueryResult, ChildrenData, ParentData, NameData, TransformData,+ Vec2, Vec3, Vec4, Quat, Color,} from '../src/core';const Position = defineComponent('VocabPosition', { x: 0, y: 0 });@@ -53,6 +56,21 @@ describe('component vocabulary', () => {expect(Health.renderableField).toBeNull();});+ it('the hierarchy and naming components carry the shapes they promise', () => {+ // Their defaults, not a live tree: Parent/Children are engine-backed, so+ // reparenting needs a C++ registry this suite deliberately runs without.+ const parent = getComponentDefaults('Parent') as unknown as ParentData;+ const children = getComponentDefaults('Children') as unknown as ChildrenData;+ // Name is the odd one: a user component, so it lives in the context+ // registry rather than the global builtin one, and makes its own value.+ const name: NameData = Name.create();+ expect(parent).toHaveProperty('entity');+ expect(children).toHaveProperty('entities');+ expect(name.value).toBe('');+ const defs: AnyComponentDef[] = [Parent, Children, Name];+ expect(defs.map((d) => d._name)).toEqual(['Parent', 'Children', 'Name']);+ });+it('an engine component reflects the same way a declared one does', () => {// Both halves of AnyComponentDef answer the reflection tooling reads, so// an editor or a cook never asks which kind it is holding.@@ -60,6 +78,15 @@ describe('component vocabulary', () => {expect(builtin._builtin).toBe(true);expect(Array.isArray(builtin.readonlyFields)).toBe(true);expect(typeof builtin.fieldMeta).toBe('object');+ // The world fields are engine-COMPUTED, and saying so is the contract+ // that stops an editor projecting them back over the composed value.+ expect(builtin.readonlyFields).toEqual(+ expect.arrayContaining(['worldPosition', 'worldRotation', 'worldScale']),+ );+ // No create() on this half of the union — an engine component is made by+ // the registry, so its shape is read from the defaults instead.+ const shape = getComponentDefaults('Transform') as unknown as TransformData;+ expect(Object.keys(shape)).toEqual(expect.arrayContaining(['position', 'rotation', 'scale']));});it('FieldMeta is the per-field policy a definition carries', () => {@@ -69,6 +96,23 @@ describe('component vocabulary', () => {});});+describe('math vocabulary', () => {+ it('the value types a component field holds are plain data', () => {+ const position: Vec3 = vec3(1, 2, 3);+ const uv: Vec2 = vec2(0.5, 0.25);+ const uniform: Vec4 = vec4(1, 0, 0, 1);+ const rotation: Quat = quat(0, 0, 0, 1);+ const tint: Color = color(1, 1, 1, 1);+ // Plain, because they cross to the engine as struct memory: own keys+ // only, and JSON round-trips them unchanged.+ for (const v of [position, uv, uniform, rotation, tint]) {+ expect(JSON.parse(JSON.stringify(v))).toEqual(v);+ }+ expect(Object.keys(position)).toEqual(['x', 'y', 'z']);+ expect(Object.keys(tint)).toEqual(['r', 'g', 'b', 'a']);+ });+});+describe('query vocabulary', () => {it('Query answers a QueryBuilder, which is a usable QueryDescriptor', () => {const builder: QueryBuilder<[typeof Position]> = Query(Position);diff --git a/src/esengine/core/Reflection.hpp b/src/esengine/core/Reflection.hppindex 5c2cbd6fb..b97c0262b 100644--- a/src/esengine/core/Reflection.hpp+++ b/src/esengine/core/Reflection.hpp@@ -31,6 +31,10 @@* of the generated `COMPONENT_META`. `renderable` names the bool gating* this component's drawing — a hard EHT error unless that bool exists.*+ * `stability=public|beta|experimental` is the SDK tier of the generated+ * `<Name>Data` interface, declared here because the generated file is+ * not editable and an untagged symbol is experimental by default.+ ** @code* ES_COMPONENT(renderable=enabled)* struct Sprite {diff --git a/src/esengine/ecs/components/Hierarchy.hpp b/src/esengine/ecs/components/Hierarchy.hppindex 5922dafbc..c99b632ac 100644--- a/src/esengine/ecs/components/Hierarchy.hpp+++ b/src/esengine/ecs/components/Hierarchy.hpp@@ -42,7 +42,7 @@ namespace esengine::ecs {* registry.get<Children>(parent).entities.push_back(child);* @endcode*/-ES_COMPONENT()+ES_COMPONENT(stability=public)struct Parent {/** @brief Parent entity ID */ES_PROPERTY(entity_ref)@@ -62,7 +62,7 @@ struct Parent {* @details Stores references to all child entities. Maintained in sync* with Parent components by the hierarchy management system.*/-ES_COMPONENT()+ES_COMPONENT(stability=public)struct Children {/** @brief List of child entity IDs */ES_PROPERTY(entity_ref)diff --git a/src/esengine/ecs/components/Transform.hpp b/src/esengine/ecs/components/Transform.hppindex 9010a8be3..864f48026 100644--- a/src/esengine/ecs/components/Transform.hpp+++ b/src/esengine/ecs/components/Transform.hpp@@ -38,7 +38,7 @@ namespace esengine::ecs {* // transform.worldPosition contains final world-space position* @endcode*/-ES_COMPONENT()+ES_COMPONENT(stability=public)struct Transform {ES_PROPERTY(animatable, anim_override, replicated, tooltip="Local position in world units, relative to the parent.")glm::vec3 position{0.0f, 0.0f, 0.0f};diff --git a/tools/check-freeze-bar.mjs b/tools/check-freeze-bar.mjsindex 9ff1da22e..8d818a14b 100644--- a/tools/check-freeze-bar.mjs+++ b/tools/check-freeze-bar.mjs@@ -38,6 +38,10 @@ import { GOLDEN, projectDir } from './goldenProjects.mjs';*/const RECEIVED = 'received from a declared parameter, never imported — golden projects run it, no import list names it';export const EXEMPT = {+ // Same shape of blindness: the engine maintains this one from Parent, so a+ // game reads it and every golden project's layout walks it every frame, but+ // nothing imports the name.+ Children: 'engine-maintained from Parent — walked every frame, named in no import list',CommandsInstance: RECEIVED,EntityCommands: RECEIVED,EventReaderInstance: RECEIVED,diff --git a/tools/eht/generators/metadata.py b/tools/eht/generators/metadata.pyindex 4a9858816..526f9dd0d 100644--- a/tools/eht/generators/metadata.py+++ b/tools/eht/generators/metadata.py@@ -261,6 +261,17 @@ class MetadataGenerator:elif base in self.types.CUSTOM_STRUCTS:used_struct.add(base)field_lines.append(f' {prop.name}: {ts};')+ # The SDK's tier, from ES_COMPONENT(stability=). It has to sit on the+ # declaration: a release tag in this file's header would not survive+ # the declaration bundle a project compiles against.+ tier = comp.annotations.get('stability')+ if tier:+ lines.append('/**')+ lines.append(f' * The fields of the engine\'s `{comp.name}` component, generated from')+ lines.append(' * the C++ struct so the two shapes cannot drift.')+ lines.append(' *')+ lines.append(f' * @{tier}')+ lines.append(' */')lines.append(f'export interface {comp.name}Data {{')lines.extend(field_lines)lines.append('}')diff --git a/tools/eht/parser.py b/tools/eht/parser.pyindex 1f1c61714..6a7b0567e 100644--- a/tools/eht/parser.py+++ b/tools/eht/parser.py@@ -70,7 +70,10 @@ class CppParser:# validated by the same rules (unknown key = warning, malformed known key =# hard error). See Reflection.hpp for what each one means.COMPONENT_FLAG_ANNOTATIONS = frozenset({'transient'})- COMPONENT_KV_ANNOTATIONS = frozenset({'renderable'})+ COMPONENT_KV_ANNOTATIONS = frozenset({'renderable', 'stability'})+ #: What `stability=` may say. The SDK's tiers, declared at the component+ #: rather than in the generated file, which nobody may edit.+ STABILITY_TIERS = frozenset({'public', 'beta', 'experimental'})VALID_ASSET_TYPES = frozenset({'texture', 'material', 'font', 'audio',# A skeletal runtime's two halves. Recognised as a PAIR (see@@ -222,6 +225,12 @@ class CppParser:f"{loc}: unknown ES_COMPONENT annotation '{key}' (known: {known})")continue+ # stability names a tier, not a field of this struct.+ if key == 'stability':+ if value not in self.STABILITY_TIERS:+ known = ', '.join(sorted(self.STABILITY_TIERS))+ self.errors.append(f"{loc}: stability='{value}' is not a tier (known: {known})")+ continue# A kv annotation written as a bare flag parses as the string 'true',# which names no field — say what it needs rather than what it got.if value == 'true':