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.

fix(gates): a renamed component is not a lost one

esengine5bf6fc1e5ef2
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index bd353533c..e349ac144 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 71,
- "experimental": 1648,
+ "experimental": 1649,
"deprecated": 3
},
- "total": 1832,
+ "total": 1833,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index f17b878cc..1a73662fc 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: 113 public · 64 beta · 1511 experimental · 3 deprecated
+Symbols: 113 public · 64 beta · 1512 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -6185,6 +6185,11 @@ static prototype: QueryInstance<any>
]
```
+## RENAMED_COMPONENT_TYPES — const @experimental
+```
+ReadonlyMap<string, string>
+```
+
## REPLICATION_CHANNEL — const @experimental
```
1
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 6e5fc1ba5..a7a52c696 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: 113 public · 69 beta · 1530 experimental · 3 deprecated
+Symbols: 113 public · 69 beta · 1531 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -6373,6 +6373,11 @@ static prototype: QueryInstance<any>
{ readonly createEntity: "es_createEntity"; readonly destroyEntity: "es_destroyEntity"; readonly setParent: "es_setParent"; readonly hasParent: "es_hasParent"; readonly getParent: "es_getParent"; readonly removeParent: "es_removeParent"; readonly hasChildren: "es_hasChildren"; readonly getChildren: "es_getChildren"; readonly getMeshSkinJoints: "es_getMeshSkinJoints"; readonly setMeshSkinJoints: "es_setMeshSkinJoints"; }
```
+## RENAMED_COMPONENT_TYPES — const @experimental
+```
+ReadonlyMap<string, string>
+```
+
## REPLICATION_CHANNEL — const @experimental
```
1
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 1280cf89a..04dccb621 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: 113 public · 66 beta · 1510 experimental · 3 deprecated
+Symbols: 113 public · 66 beta · 1511 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6180,6 +6180,11 @@ static prototype: QueryInstance<any>
]
```
+## RENAMED_COMPONENT_TYPES — const @experimental
+```
+ReadonlyMap<string, string>
+```
+
## REPLICATION_CHANNEL — const @experimental
```
1
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index d66df7637..e54d578b7 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: 113 public · 64 beta · 1532 experimental · 3 deprecated
+Symbols: 113 public · 64 beta · 1533 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6425,6 +6425,11 @@ static prototype: QueryInstance<any>
]
```
+## RENAMED_COMPONENT_TYPES — const @experimental
+```
+ReadonlyMap<string, string>
+```
+
## REPLICATION_CHANNEL — const @experimental
```
1
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 7a191437f..1a2e25628 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: 113 public · 64 beta · 1522 experimental · 3 deprecated
+Symbols: 113 public · 64 beta · 1523 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -6187,6 +6187,11 @@ static prototype: QueryInstance<any>
]
```
+## RENAMED_COMPONENT_TYPES — const @experimental
+```
+ReadonlyMap<string, string>
+```
+
## REPLICATION_CHANNEL — const @experimental
```
1
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index e90261f20..60cc6bf6a 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -143,6 +143,7 @@ export {
serializeScene,
migrateSceneData,
RETIRED_COMPONENT_TYPES,
+ RENAMED_COMPONENT_TYPES,
SCENE_FORMAT_VERSION,
registerSceneComponentCodec,
getComponentAssetFields,
diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.ts
index 2353a0c4e..589428993 100644
--- a/sdk/src/scene/scene.ts
+++ b/sdk/src/scene/scene.ts
@@ -353,6 +353,14 @@ export function parseSceneFormatVersion(v: unknown): number {
*/
export { RETIRED_COMPONENT_TYPES } from './legacyComponents';
+/**
+ * Components an engine upgrade renamed, old name to new. Exported because a
+ * rename is not a loss, and anything comparing a released file against what
+ * opening it yields has to be able to tell the two apart from one table rather
+ * than a copy of it.
+ */
+export { RENAMED_COMPONENT_TYPES } from './legacyComponents';
+
/**
* Upgrade a SceneData to the current format. Total + idempotent: already-current
* data returns `migrated: false`; migrations are shape-driven so they no-op on
diff --git a/tools/verify-legacy.mjs b/tools/verify-legacy.mjs
index 7e288fea4..47ade3b21 100644
--- a/tools/verify-legacy.mjs
+++ b/tools/verify-legacy.mjs
@@ -12,8 +12,9 @@
* "It opened" is the weak claim. The strong one is that nothing was quietly
* dropped: the editor's model is documented as lossless over unknown component
* types, so every entity and every component in the released file must still be
- * there afterwards. A component the editor no longer understands must survive as
- * data, not vanish because nothing renders it.
+ * there afterwards — under whatever name the migration gives it. A component the
+ * editor no longer understands must survive as data, not vanish because nothing
+ * renders it.
*
* node tools/verify-legacy.mjs --tier pr
* node tools/verify-legacy.mjs --tag v0.20.0 --id platformer
@@ -25,6 +26,12 @@ import path from 'node:path';
import { legacyAtTier, ROOT } from './goldenProjects.mjs';
import { runTool } from './lib/runTool.mjs';
+// The migration's own tables, not a copy: a renamed component is not a lost one
+// and a retired one is deliberately dropped, so comparing released spellings
+// against opened ones without them reads every rename as content loss.
+const { RENAMED_COMPONENT_TYPES, RETIRED_COMPONENT_TYPES } =
+ await import(path.join(ROOT, 'sdk', 'dist', 'index.js'));
+
const argv = process.argv.slice(2);
const flag = (n, d) => {
const i = argv.indexOf(`--${n}`);
@@ -71,11 +78,18 @@ function releasedScenes(dir) {
return out;
}
-/** Entity id → sorted component types, the shape a lossless open must preserve. */
+/**
+ * Entity id → sorted component types, the shape a lossless open must preserve —
+ * each name carried through the rename the engine would apply, and the retired
+ * ones left out, since dropping those is the documented behaviour.
+ */
function shapeOf(scene) {
const out = {};
for (const e of scene.entities ?? []) {
- out[e.id] = (e.components ?? []).map((c) => c.type).sort();
+ out[e.id] = (e.components ?? [])
+ .map((c) => RENAMED_COMPONENT_TYPES.get(c.type) ?? c.type)
+ .filter((t) => !RETIRED_COMPONENT_TYPES.has(t))
+ .sort();
}
return out;
}