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(prefab): repo-wide v2 migration + format gate + Resave All (P2)

yhh2226978c1906
diff --git a/build-tools/tasks/validate-prefabs.js b/build-tools/tasks/validate-prefabs.js
index 02c845871..e27019897 100644
--- a/build-tools/tasks/validate-prefabs.js
+++ b/build-tools/tasks/validate-prefabs.js
@@ -43,7 +43,7 @@ export async function validatePrefabs(rootDir) {
logger.error('SDK dist not found. Build SDK first: pnpm --filter ./sdk build');
process.exit(1);
}
- const { validatePrefab, migratePrefabData } = await import(pathToFileURL(sdkNode).href);
+ const { validatePrefab, migratePrefabData, PREFAB_FORMAT_VERSION } = await import(pathToFileURL(sdkNode).href);
const files = [];
for (const rel of PREFAB_ROOTS) walkPrefabs(path.join(rootDir, rel), files);
@@ -55,11 +55,15 @@ export async function validatePrefabs(rootDir) {
// Parse + migrate every prefab up-front, and index by asset uuid (from the
// sibling .meta) so nested/variant `@uuid:` refs resolve for the loader.
const parsed = new Map(); // absolute file → migrated PrefabData
+ const rawVersions = new Map(); // absolute file → raw (pre-migration) version
const byUuid = new Map(); // asset uuid → migrated PrefabData
let errors = 0;
for (const file of files) {
+ const rel = path.relative(rootDir, file);
try {
- const data = migratePrefabData(JSON.parse(readFileSync(file, 'utf8'))).data;
+ const raw = JSON.parse(readFileSync(file, 'utf8'));
+ rawVersions.set(file, raw && raw.version != null ? String(raw.version) : '(none)');
+ const data = migratePrefabData(raw).data;
parsed.set(file, data);
const metaPath = `${file}.meta`;
if (existsSync(metaPath)) {
@@ -67,7 +71,7 @@ export async function validatePrefabs(rootDir) {
if (meta.uuid) byUuid.set(meta.uuid, data);
}
} catch (err) {
- logger.error(` ${path.relative(rootDir, file)} [parse] ${err.message}`);
+ logger.error(` ${rel} [parse] ${err.message}`);
errors++;
}
}
@@ -84,17 +88,30 @@ export async function validatePrefabs(rootDir) {
const data = parsed.get(file);
if (!data) continue; // already counted as a parse error
const rel = path.relative(rootDir, file);
- const diags = validatePrefab(data, { loadPrefab: (ref) => resolveRef(ref, file) });
- if (diags.length === 0) {
- logger.success(rel);
- continue;
+
+ // Repo assets must already be current format — legacy v1 loads via
+ // auto-migration for USERS, but our own examples/templates/widgets model
+ // best practice. Re-save with the editor's "Resave All Prefabs".
+ const fileErrors = [];
+ const fileWarnings = [];
+ const rawVersion = rawVersions.get(file);
+ if (rawVersion !== PREFAB_FORMAT_VERSION) {
+ fileErrors.push(` ${rel} [outdated-format] version "${rawVersion}" is not the current "${PREFAB_FORMAT_VERSION}" — re-save it`);
}
- for (const d of diags) {
+ for (const d of validatePrefab(data, { loadPrefab: (ref) => resolveRef(ref, file) })) {
const at = d.entityId ? ` @${d.entityId}${d.field ? `.${d.field}` : ''}` : '';
const line = ` ${rel} [${d.code}]${at} ${d.message}`;
- if (d.severity === 'error') { logger.error(line); errors++; }
- else { logger.warn(line); warnings++; }
+ (d.severity === 'error' ? fileErrors : fileWarnings).push(line);
+ }
+
+ if (fileErrors.length === 0 && fileWarnings.length === 0) {
+ logger.success(rel);
+ continue;
}
+ for (const line of fileErrors) logger.error(line);
+ for (const line of fileWarnings) logger.warn(line);
+ errors += fileErrors.length;
+ warnings += fileWarnings.length;
}
logger.step(`Prefab validation: ${files.length} files, ${errors} error(s), ${warnings} warning(s)`);
diff --git a/desktop/src/commands/editorCommands.ts b/desktop/src/commands/editorCommands.ts
index 67f037b0b..4d3b62c7d 100644
--- a/desktop/src/commands/editorCommands.ts
+++ b/desktop/src/commands/editorCommands.ts
@@ -394,3 +394,12 @@ commands.register({
.then(() => Toasts.push(t('toast.builtScripts'), 'success'))
.catch(() => Toasts.push(t('toast.buildFailed'), 'error')),
});
+
+// — Assets —
+commands.register({
+ id: 'project.resavePrefabs',
+ label: t('cmd.project.resavePrefabs'),
+ category: t('cat.file'),
+ isEnabled: () => !!ProjectStore.getSnapshot(),
+ run: () => void ProjectStore.resaveAllPrefabs(),
+});
diff --git a/desktop/src/i18n/messages/commands.ts b/desktop/src/i18n/messages/commands.ts
index 81de73d3f..75caf3ec2 100644
--- a/desktop/src/i18n/messages/commands.ts
+++ b/desktop/src/i18n/messages/commands.ts
@@ -17,6 +17,7 @@ export const commandMessages = defineMessages({
'cmd.project.saveAs': { en: 'Save Scene As…', zh: '场景另存为…' },
'cmd.project.export': { en: 'Build…', zh: '构建…' },
'cmd.project.close': { en: 'Close Project', zh: '关闭项目' },
+ 'cmd.project.resavePrefabs': { en: 'Resave All Prefabs', zh: '重新保存所有预制体' },
// — Edit / history —
'cmd.edit.undo': { en: 'Undo', zh: '撤销' },
diff --git a/desktop/src/i18n/messages/project.ts b/desktop/src/i18n/messages/project.ts
index 9c2c5bb78..de80debd6 100644
--- a/desktop/src/i18n/messages/project.ts
+++ b/desktop/src/i18n/messages/project.ts
@@ -113,6 +113,9 @@ export const projectMessages = defineMessages({
'proj.prefabExternalRefsTitle': { en: 'Clear external references?', zh: '清除外部引用?' },
'proj.prefabExternalRefsBody': { en: '{count} component reference(s) point to entities outside this selection and will be cleared in the prefab.', zh: '有 {count} 处组件引用指向所选之外的实体,将在预制体中被清除。' },
'proj.prefabExternalRefsConfirm': { en: 'Create anyway', zh: '仍然创建' },
+ 'proj.resaveNone': { en: 'No prefabs to re-save', zh: '没有可重新保存的预制体' },
+ 'proj.resaveDone': { en: 'Re-saved {count} prefab(s) to the current format', zh: '已将 {count} 个预制体重新保存为当前格式' },
+ 'proj.resaveFailed': { en: 'Re-saved {upgraded}, {failed} failed', zh: '已重新保存 {upgraded} 个,{failed} 个失败' },
'proj.prefabCreateFailed': { en: 'Failed to create prefab: {name}', zh: '创建预制体失败:{name}' },
'proj.prefabCreated': { en: 'Created prefab: {name}', zh: '已创建预制体:{name}' },
'proj.saveSortingLayersFailed': { en: 'Failed to save sorting layers', zh: '保存排序层失败' },
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 4079b2b40..36325c0a5 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -1172,6 +1172,37 @@ class ProjectStoreImpl {
await this.buildAssetRegistry();
}
+ /**
+ * Re-save every project `.esprefab` in the current format — the bulk "Resave
+ * All Prefabs" upgrade. Each prefab is run through `migratePrefabData` (which
+ * upgrades legacy numeric ids AND a merely-stale version) and only rewritten
+ * when it actually changed. Instances re-derive from the upgraded assets on
+ * next load. Reports how many were upgraded.
+ */
+ async resaveAllPrefabs(): Promise<void> {
+ const paths = [...this.pathToUuid.keys()].filter((p) => p.endsWith('.esprefab'));
+ if (paths.length === 0) {
+ Toasts.push(t('proj.resaveNone'), 'info');
+ return;
+ }
+ let upgraded = 0;
+ let failed = 0;
+ for (const path of paths) {
+ try {
+ const { data, migrated } = migratePrefabData(JSON.parse(await window.estella.fs.read(path)));
+ if (!migrated) continue;
+ await window.estella.fs.write(path, JSON.stringify(data, null, 2) + '\n');
+ upgraded++;
+ } catch (err) {
+ console.warn('[project] resave prefab failed', path, err);
+ failed++;
+ }
+ }
+ this.prefabCache.clear(); // rewritten assets must reload fresh
+ if (failed > 0) Toasts.push(t('proj.resaveFailed', { upgraded, failed }), 'error');
+ else Toasts.push(t('proj.resaveDone', { count: upgraded }), 'success');
+ }
+
/** A tracked asset's portable `@uuid:` ref for a project-relative path (Copy
* Reference), or null if the path isn't an indexed asset. */
assetRef(path: string): string | null {
diff --git a/examples/space-shooter/assets/prefabs/EnemyA.esprefab b/examples/space-shooter/assets/prefabs/EnemyA.esprefab
index eed448434..c9ccdebc1 100644
--- a/examples/space-shooter/assets/prefabs/EnemyA.esprefab
+++ b/examples/space-shooter/assets/prefabs/EnemyA.esprefab
@@ -1,10 +1,10 @@
{
- "version": "1.0",
+ "version": "2",
"name": "EnemyA",
- "rootEntityId": 0,
+ "rootEntityId": "0",
"entities": [
{
- "prefabEntityId": 0,
+ "prefabEntityId": "0",
"name": "EnemyA",
"parent": null,
"children": [],
@@ -17,7 +17,10 @@
"type": "Sprite",
"data": {
"texture": "@uuid:25e60610-c126-48bf-9b14-85c4699dc912",
- "size": { "x": 52, "y": 47 }
+ "size": {
+ "x": 52,
+ "y": 47
+ }
}
},
{
diff --git a/examples/space-shooter/assets/prefabs/EnemyB.esprefab b/examples/space-shooter/assets/prefabs/EnemyB.esprefab
index 2b5348833..75bdaf57e 100644
--- a/examples/space-shooter/assets/prefabs/EnemyB.esprefab
+++ b/examples/space-shooter/assets/prefabs/EnemyB.esprefab
@@ -1,10 +1,10 @@
{
- "version": "1.0",
+ "version": "2",
"name": "EnemyB",
- "rootEntityId": 0,
+ "rootEntityId": "0",
"entities": [
{
- "prefabEntityId": 0,
+ "prefabEntityId": "0",
"name": "EnemyB",
"parent": null,
"children": [],
@@ -17,7 +17,10 @@
"type": "Sprite",
"data": {
"texture": "@uuid:d429cf7d-d52c-42eb-823e-9b775b6249b6",
- "size": { "x": 58, "y": 47 }
+ "size": {
+ "x": 58,
+ "y": 47
+ }
}
},
{
diff --git a/examples/space-shooter/assets/prefabs/EnemyBullet.esprefab b/examples/space-shooter/assets/prefabs/EnemyBullet.esprefab
index 62be9b922..d57f33ee2 100644
--- a/examples/space-shooter/assets/prefabs/EnemyBullet.esprefab
+++ b/examples/space-shooter/assets/prefabs/EnemyBullet.esprefab
@@ -1,10 +1,10 @@
{
- "version": "1.0",
+ "version": "2",
"name": "EnemyBullet",
- "rootEntityId": 0,
+ "rootEntityId": "0",
"entities": [
{
- "prefabEntityId": 0,
+ "prefabEntityId": "0",
"name": "EnemyBullet",
"parent": null,
"children": [],
@@ -17,7 +17,10 @@
"type": "Sprite",
"data": {
"texture": "@uuid:97a221a6-85bd-49e7-9af5-2880960fecda",
- "size": { "x": 8, "y": 30 }
+ "size": {
+ "x": 8,
+ "y": 30
+ }
}
},
{
diff --git a/examples/space-shooter/assets/prefabs/Explosion.esprefab b/examples/space-shooter/assets/prefabs/Explosion.esprefab
index 675b5af6d..e95d7ad40 100644
--- a/examples/space-shooter/assets/prefabs/Explosion.esprefab
+++ b/examples/space-shooter/assets/prefabs/Explosion.esprefab
@@ -1,10 +1,10 @@
{
- "version": "1.0",
+ "version": "2",
"name": "Explosion",
- "rootEntityId": 0,
+ "rootEntityId": "0",
"entities": [
{
- "prefabEntityId": 0,
+ "prefabEntityId": "0",
"name": "Explosion",
"parent": null,
"children": [],
@@ -17,7 +17,10 @@
"type": "Sprite",
"data": {
"texture": "@uuid:4e16b7e8-3ba1-455b-ab3c-1cfbf5a97e0c",
- "size": { "x": 76, "y": 76 }
+ "size": {
+ "x": 76,
+ "y": 76
+ }
}
},
{
diff --git a/examples/space-shooter/assets/prefabs/PlayerBullet.esprefab b/examples/space-shooter/assets/prefabs/PlayerBullet.esprefab
index 77dd58df5..1b950afe6 100644
--- a/examples/space-shooter/assets/prefabs/PlayerBullet.esprefab
+++ b/examples/space-shooter/assets/prefabs/PlayerBullet.esprefab
@@ -1,10 +1,10 @@
{
- "version": "1.0",
+ "version": "2",
"name": "PlayerBullet",
- "rootEntityId": 0,
+ "rootEntityId": "0",
"entities": [
{
- "prefabEntityId": 0,
+ "prefabEntityId": "0",
"name": "PlayerBullet",
"parent": null,
"children": [],
@@ -17,7 +17,10 @@
"type": "Sprite",
"data": {
"texture": "@uuid:c643c566-1859-460a-8029-4568951787f8",
- "size": { "x": 8, "y": 40 }
+ "size": {
+ "x": 8,
+ "y": 40
+ }
}
},
{
diff --git a/examples/space-shooter/assets/prefabs/Star.esprefab b/examples/space-shooter/assets/prefabs/Star.esprefab
index c0a67d178..91f705b02 100644
--- a/examples/space-shooter/assets/prefabs/Star.esprefab
+++ b/examples/space-shooter/assets/prefabs/Star.esprefab
@@ -1,17 +1,48 @@
{
- "version": "1.0",
+ "version": "2",
"name": "Star",
- "rootEntityId": 0,
+ "rootEntityId": "0",
"entities": [
{
- "prefabEntityId": 0,
+ "prefabEntityId": "0",
"name": "Star",
"parent": null,
"children": [],
"components": [
- { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": -0.5 } } },
- { "type": "Sprite", "data": { "texture": "@uuid:8f56c884-0439-47f1-86d9-05839abfa6e0", "size": { "x": 9, "y": 9 }, "color": { "r": 1, "g": 1, "b": 1, "a": 0.7 }, "layer": -1 } },
- { "type": "Star", "data": { "speed": 30, "layer": 0 } }
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": -0.5
+ }
+ }
+ },
+ {
+ "type": "Sprite",
+ "data": {
+ "texture": "@uuid:8f56c884-0439-47f1-86d9-05839abfa6e0",
+ "size": {
+ "x": 9,
+ "y": 9
+ },
+ "color": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 0.7
+ },
+ "layer": -1
+ }
+ },
+ {
+ "type": "Star",
+ "data": {
+ "speed": 30,
+ "layer": 0
+ }
+ }
],
"visible": true
}
diff --git a/sdk/src/prefab.ts b/sdk/src/prefab.ts
index 7d4b30bd2..57fb78ef8 100644
--- a/sdk/src/prefab.ts
+++ b/sdk/src/prefab.ts
@@ -3,7 +3,7 @@
import type { World } from './world';
import type { Entity } from './types';
import type { Assets } from './asset/Assets';
-import { loadSceneWithAssets, type SceneData } from './scene';
+import { loadSceneWithAssets, SCENE_FORMAT_VERSION, type SceneData } from './scene';
import {
flattenPrefab,
preloadNestedPrefabs,
@@ -88,7 +88,9 @@ export async function instantiatePrefab(
);
const sceneData: SceneData = {
- version: normalized.version,
+ // The produced value is a SCENE, so it carries the scene format version —
+ // not the prefab's format version (which `normalized` just migrated).
+ version: SCENE_FORMAT_VERSION,
name: normalized.name,
entities: processed.map(e => ({
id: e.id,
diff --git a/sdk/src/prefab/migrate.ts b/sdk/src/prefab/migrate.ts
index d521eeb66..51839b4a5 100644
--- a/sdk/src/prefab/migrate.ts
+++ b/sdk/src/prefab/migrate.ts
@@ -41,7 +41,10 @@ export function migratePrefabData(raw: unknown): MigrationResult {
}
const fromVersion = typeof obj['version'] === 'string' ? obj['version'] : '1.0';
- const isLegacy = needsMigration(obj);
+ // Upgrade when ids are legacy-numeric OR the declared version is simply stale
+ // (a file authored as an old version but already string-id'd must still bump
+ // to current, so "re-save" truly lands on the latest format).
+ const isLegacy = needsMigration(obj) || fromVersion !== PREFAB_FORMAT_VERSION;
if (!isLegacy) {
return {
diff --git a/sdk/tests/prefab-rigor.test.ts b/sdk/tests/prefab-rigor.test.ts
index f3f5b1dd0..558c77060 100644
--- a/sdk/tests/prefab-rigor.test.ts
+++ b/sdk/tests/prefab-rigor.test.ts
@@ -159,6 +159,21 @@ describe('migratePrefabData', () => {
expect(data).toBe(current);
});
+ it('upgrades a stale-version file even when its ids are already strings', () => {
+ const staleButStringIds = {
+ version: '1.0',
+ name: 'Stale',
+ rootEntityId: '0',
+ entities: [{ prefabEntityId: '0', name: 'R', parent: null, children: [], components: [], visible: true }],
+ };
+ const { data, migrated, toVersion } = migratePrefabData(staleButStringIds);
+ expect(migrated).toBe(true);
+ expect(toVersion).toBe(PREFAB_FORMAT_VERSION);
+ expect(data.version).toBe(PREFAB_FORMAT_VERSION);
+ expect(data.rootEntityId).toBe('0'); // string ids preserved, not re-numbered
+ expect(data.entities[0].prefabEntityId).toBe('0');
+ });
+
it('round-trips through JSON without drift', () => {
const original = uuidPrefab();
const serialized = JSON.stringify(original);