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(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.json
index 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.md
index 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: Vec2
velocity: Vec2
```
-## Children — const @experimental
+## Children — const @public
```
BuiltinComponentDef<ChildrenData>
```
-## ChildrenData — interface @experimental
+## ChildrenData — interface @public
```
entities: number[]
```
@@ -1735,7 +1735,7 @@ friction: number | undefined
restitution: number | undefined
```
-## Color — interface @experimental
+## Color — interface @public
```
a: number
b: number
@@ -3723,7 +3723,7 @@ height: number | undefined
width: 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> | undefined
ySortLayers: 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: number
x: number
@@ -5746,7 +5746,7 @@ uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
```
-## RuntimeOnly — const @experimental
+## RuntimeOnly — const @public
```
ComponentDef<{}>
```
@@ -7606,12 +7606,12 @@ forward: () => void
reverse: () => void
```
-## Transform — const @experimental
+## Transform — const @public
```
BuiltinComponentDef<TransformData>
```
-## TransformData — interface @experimental
+## TransformData — interface @public
```
position: Vec3
rotation: Quat
@@ -8085,7 +8085,7 @@ static new (manager: ValueTweenManager, id: number): ValueTweenHandle
static prototype: ValueTweenHandle
```
-## Vec2 — interface @experimental
+## Vec2 — interface @public
```
x: number
y: number
@@ -8097,14 +8097,14 @@ x: number
y: number
```
-## Vec3 — interface @experimental
+## Vec3 — interface @public
```
x: number
y: number
z: number
```
-## Vec4 — interface @experimental
+## Vec4 — interface @public
```
w: number
x: number
@@ -8363,7 +8363,7 @@ right: number
top: 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.md
index 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: Vec2
velocity: Vec2
```
-## Children — const @experimental
+## Children — const @public
```
BuiltinComponentDef<ChildrenData>
```
-## ChildrenData — interface @experimental
+## ChildrenData — interface @public
```
entities: number[]
```
@@ -1735,7 +1735,7 @@ friction: number | undefined
restitution: number | undefined
```
-## Color — interface @experimental
+## Color — interface @public
```
a: number
b: number
@@ -3731,7 +3731,7 @@ height: number | undefined
width: 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> | undefined
ySortLayers: 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: number
x: number
@@ -5939,7 +5939,7 @@ uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
```
-## RuntimeOnly — const @experimental
+## RuntimeOnly — const @public
```
ComponentDef<{}>
```
@@ -7799,12 +7799,12 @@ forward: () => void
reverse: () => void
```
-## Transform — const @experimental
+## Transform — const @public
```
BuiltinComponentDef<TransformData>
```
-## TransformData — interface @experimental
+## TransformData — interface @public
```
position: Vec3
rotation: Quat
@@ -8278,7 +8278,7 @@ static new (manager: ValueTweenManager, id: number): ValueTweenHandle
static prototype: ValueTweenHandle
```
-## Vec2 — interface @experimental
+## Vec2 — interface @public
```
x: number
y: number
@@ -8290,14 +8290,14 @@ x: number
y: number
```
-## Vec3 — interface @experimental
+## Vec3 — interface @public
```
x: number
y: number
z: number
```
-## Vec4 — interface @experimental
+## Vec4 — interface @public
```
w: number
x: number
@@ -8556,7 +8556,7 @@ right: number
top: 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.md
index 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: Vec2
velocity: Vec2
```
-## Children — const @experimental
+## Children — const @public
```
BuiltinComponentDef<ChildrenData>
```
-## ChildrenData — interface @experimental
+## ChildrenData — interface @public
```
entities: number[]
```
@@ -1730,7 +1730,7 @@ friction: number | undefined
restitution: number | undefined
```
-## Color — interface @experimental
+## Color — interface @public
```
a: number
b: number
@@ -3718,7 +3718,7 @@ height: number | undefined
width: 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> | undefined
ySortLayers: 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: number
x: number
@@ -5741,7 +5741,7 @@ uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
```
-## RuntimeOnly — const @experimental
+## RuntimeOnly — const @public
```
ComponentDef<{}>
```
@@ -7601,12 +7601,12 @@ forward: () => void
reverse: () => void
```
-## Transform — const @experimental
+## Transform — const @public
```
BuiltinComponentDef<TransformData>
```
-## TransformData — interface @experimental
+## TransformData — interface @public
```
position: Vec3
rotation: Quat
@@ -8080,7 +8080,7 @@ static new (manager: ValueTweenManager, id: number): ValueTweenHandle
static prototype: ValueTweenHandle
```
-## Vec2 — interface @experimental
+## Vec2 — interface @public
```
x: number
y: number
@@ -8092,14 +8092,14 @@ x: number
y: number
```
-## Vec3 — interface @experimental
+## Vec3 — interface @public
```
x: number
y: number
z: number
```
-## Vec4 — interface @experimental
+## Vec4 — interface @public
```
w: number
x: number
@@ -8358,7 +8358,7 @@ right: number
top: number
```
-## WorldTransform — const @experimental
+## WorldTransform — const @experimental @deprecated
```
BuiltinComponentDef<TransformData>
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: Vec2
velocity: Vec2
```
-## Children — const @experimental
+## Children — const @public
```
BuiltinComponentDef<ChildrenData>
```
-## ChildrenData — interface @experimental
+## ChildrenData — interface @public
```
entities: number[]
```
@@ -1730,7 +1730,7 @@ friction: number | undefined
restitution: number | undefined
```
-## Color — interface @experimental
+## Color — interface @public
```
a: number
b: number
@@ -3718,7 +3718,7 @@ height: number | undefined
width: 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> | undefined
ySortLayers: 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: number
x: number
@@ -5986,7 +5986,7 @@ uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
```
-## RuntimeOnly — const @experimental
+## RuntimeOnly — const @public
```
ComponentDef<{}>
```
@@ -7846,12 +7846,12 @@ forward: () => void
reverse: () => void
```
-## Transform — const @experimental
+## Transform — const @public
```
BuiltinComponentDef<TransformData>
```
-## TransformData — interface @experimental
+## TransformData — interface @public
```
position: Vec3
rotation: Quat
@@ -8325,7 +8325,7 @@ static new (manager: ValueTweenManager, id: number): ValueTweenHandle
static prototype: ValueTweenHandle
```
-## Vec2 — interface @experimental
+## Vec2 — interface @public
```
x: number
y: number
@@ -8337,14 +8337,14 @@ x: number
y: number
```
-## Vec3 — interface @experimental
+## Vec3 — interface @public
```
x: number
y: number
z: number
```
-## Vec4 — interface @experimental
+## Vec4 — interface @public
```
w: number
x: number
@@ -8603,7 +8603,7 @@ right: number
top: number
```
-## WorldTransform — const @experimental
+## WorldTransform — const @experimental @deprecated
```
BuiltinComponentDef<TransformData>
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: Vec2
velocity: Vec2
```
-## Children — const @experimental
+## Children — const @public
```
BuiltinComponentDef<ChildrenData>
```
-## ChildrenData — interface @experimental
+## ChildrenData — interface @public
```
entities: number[]
```
@@ -1730,7 +1730,7 @@ friction: number | undefined
restitution: number | undefined
```
-## Color — interface @experimental
+## Color — interface @public
```
a: number
b: number
@@ -3725,7 +3725,7 @@ height: number | undefined
width: 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> | undefined
ySortLayers: 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: number
x: number
@@ -5748,7 +5748,7 @@ uiTheme: "dark" | "light" | undefined
uiThemeOverrides: ThemeOverrides | undefined
```
-## RuntimeOnly — const @experimental
+## RuntimeOnly — const @public
```
ComponentDef<{}>
```
@@ -7608,12 +7608,12 @@ forward: () => void
reverse: () => void
```
-## Transform — const @experimental
+## Transform — const @public
```
BuiltinComponentDef<TransformData>
```
-## TransformData — interface @experimental
+## TransformData — interface @public
```
position: Vec3
rotation: Quat
@@ -8087,7 +8087,7 @@ static new (manager: ValueTweenManager, id: number): ValueTweenHandle
static prototype: ValueTweenHandle
```
-## Vec2 — interface @experimental
+## Vec2 — interface @public
```
x: number
y: number
@@ -8099,14 +8099,14 @@ x: number
y: number
```
-## Vec3 — interface @experimental
+## Vec3 — interface @public
```
x: number
y: number
z: number
```
-## Vec4 — interface @experimental
+## Vec4 — interface @public
```
w: number
x: number
@@ -8385,7 +8385,7 @@ right: number
top: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.hpp
index 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.hpp
index 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.hpp
index 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.mjs
index 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.py
index 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.py
index 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':