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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { PrefabData, PrefabEntityData, PrefabOverride } from './types';
import {
needsComponentUpgrade,
upgradeEntityComponents,
type UpgradableEntity,
} from '../scene/legacyComponents';
/**
* Result of a migration pass over a prefab JSON blob. `migrated` is true
* when at least one field was upgraded; callers can choose to log/warn so
* users know to re-save in the new format.
*/
export interface MigrationResult {
data: PrefabData;
migrated: boolean;
fromVersion: string;
toVersion: string;
}
export const PREFAB_FORMAT_VERSION = '2';
/**
* Upgrade a parsed `.esprefab` JSON value to the current format.
*
* The historical format used numeric entity ids; current format uses
* opaque strings (UUIDs for editor-authored prefabs). Numeric ids are
* stringified with `String(n)` so cross-references — `parent`, `children`,
* `rootEntityId`, `PrefabOverride.prefabEntityId`, `nestedPrefab.overrides`
* — remain consistent.
*
* The function is total: it accepts already-migrated data and returns it
* with `migrated: false`. Throws on shapes that can't be reconciled.
*/
export function migratePrefabData(raw: unknown): MigrationResult {
if (typeof raw !== 'object' || raw === null) {
throw new Error('Prefab data must be an object');
}
const obj = raw as Record<string, unknown>;
if (!Array.isArray(obj['entities'])) {
throw new Error('Prefab data must have an "entities" array');
}
if (typeof obj['rootEntityId'] !== 'string' && typeof obj['rootEntityId'] !== 'number') {
throw new Error('Prefab data must have a "rootEntityId" string or number');
}
const fromVersion = typeof obj['version'] === 'string' ? obj['version'] : '1.0';
// 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;
// A prefab current in every other way can still hold component data written
// for an older engine, and upgrading that rewrites records the caller owns —
// so the copy is made here rather than editing under them.
const staleComponents = !isLegacy
&& (obj['entities'] as UpgradableEntity[]).some(needsComponentUpgrade);
if (!isLegacy && !staleComponents) {
return {
data: obj as unknown as PrefabData,
migrated: false,
fromVersion,
toVersion: fromVersion,
};
}
const upgraded = isLegacy
? upgradeNumericIds(obj)
: (JSON.parse(JSON.stringify(obj)) as PrefabData);
// The same door a scene's components come through: a prefab holds the same
// records, and an upgrade that ran on only one of the two is half an upgrade.
for (const entity of upgraded.entities) upgradeEntityComponents(entity);
if (isLegacy) upgraded.version = PREFAB_FORMAT_VERSION;
return {
data: upgraded,
migrated: true,
fromVersion,
toVersion: isLegacy ? PREFAB_FORMAT_VERSION : fromVersion,
};
}
function needsMigration(obj: Record<string, unknown>): boolean {
if (typeof obj['rootEntityId'] === 'number') return true;
const entities = obj['entities'] as unknown[];
for (const e of entities) {
if (typeof e !== 'object' || e === null) continue;
const er = e as Record<string, unknown>;
if (typeof er['prefabEntityId'] === 'number') return true;
if (typeof er['parent'] === 'number') return true;
const children = er['children'];
if (Array.isArray(children) && children.some(c => typeof c === 'number')) return true;
}
const overrides = obj['overrides'];
if (Array.isArray(overrides)) {
for (const o of overrides) {
if (typeof o !== 'object' || o === null) continue;
const or = o as Record<string, unknown>;
if (typeof or['prefabEntityId'] === 'number') return true;
}
}
return false;
}
function upgradeNumericIds(obj: Record<string, unknown>): PrefabData {
const stringify = (v: unknown): string => {
if (typeof v === 'string') return v;
if (typeof v === 'number') return String(v);
throw new Error(`Cannot stringify prefab id of type ${typeof v}`);
};
const entities = (obj['entities'] as unknown[]).map((e): PrefabEntityData => {
const er = e as Record<string, unknown>;
const out: PrefabEntityData = {
prefabEntityId: stringify(er['prefabEntityId']),
name: typeof er['name'] === 'string' ? er['name'] : '',
parent: er['parent'] === null || er['parent'] === undefined
? null
: stringify(er['parent']),
children: Array.isArray(er['children'])
? (er['children'] as unknown[]).map(stringify)
: [],
components: Array.isArray(er['components'])
? (er['components'] as PrefabEntityData['components'])
: [],
visible: er['visible'] !== false,
};
if (er['metadata'] && typeof er['metadata'] === 'object') {
out.metadata = er['metadata'] as Record<string, unknown>;
}
if (er['nestedPrefab'] && typeof er['nestedPrefab'] === 'object') {
const np = er['nestedPrefab'] as Record<string, unknown>;
out.nestedPrefab = {
prefabPath: typeof np['prefabPath'] === 'string' ? np['prefabPath'] : '',
overrides: Array.isArray(np['overrides'])
? upgradeOverrides(np['overrides'])
: [],
};
}
return out;
});
const result: PrefabData = {
version: PREFAB_FORMAT_VERSION,
name: typeof obj['name'] === 'string' ? obj['name'] : '',
rootEntityId: stringify(obj['rootEntityId']),
entities,
};
if (typeof obj['basePrefab'] === 'string') {
result.basePrefab = obj['basePrefab'];
}
if (Array.isArray(obj['overrides'])) {
result.overrides = upgradeOverrides(obj['overrides']);
}
return result;
}
function upgradeOverrides(raw: unknown[]): PrefabOverride[] {
return raw.map((o): PrefabOverride => {
const or = o as Record<string, unknown>;
const id = or['prefabEntityId'];
const upgraded: PrefabOverride = {
...(or as unknown as PrefabOverride),
prefabEntityId: typeof id === 'number' ? String(id) : (id as string),
};
return upgraded;
});
}