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(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.jsindex 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) versionconst byUuid = new Map(); // asset uuid → migrated PrefabDatalet 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 errorconst 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.esprefabindex 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.esprefabindex 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.esprefabindex 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.esprefabindex 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.esprefabindex 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.esprefabindex 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.tsindex 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.tsindex 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.tsindex 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);