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
fix(editor): a prefab ref is a uuid OR a path, in both realms
esenginea529f09da959
diff --git a/desktop/src/project/PrefabCache.ts b/desktop/src/project/PrefabCache.tsindex 599284db9..4620027ca 100644--- a/desktop/src/project/PrefabCache.ts+++ b/desktop/src/project/PrefabCache.ts@@ -20,18 +20,21 @@ import { Toasts } from '@/store/Toasts';import { t } from '@/i18n';class PrefabCacheImpl {- /** ref (`@uuid:`) → the loaded `.esprefab`. */+ /** ref (`@uuid:` or a project path) → the loaded `.esprefab`. */private readonly byRef = new Map<string, PrefabData>();/*** Load a `.esprefab` by ref, cached, warming its base and every nested* reference so {@link resolveSync} can answer for all of them.+ *+ * A ref is a uuid OR a project path — the two spellings every asset ref takes,+ * and what the runtime loader accepts. Refusing the path form here dropped the+ * instance from the editor while the package still had it.*/async load(ref: string): Promise<PrefabData | null> {- if (!ref.startsWith(UUID_PREFIX)) return null;const cached = this.byRef.get(ref);if (cached) return cached;- const path = AssetRegistry.pathForUuid(ref.slice(UUID_PREFIX.length).toLowerCase());+ const path = AssetRegistry.refPath(ref);if (!path) return null;try {const prefab = migratePrefabData(JSON.parse(await window.estella.fs.read(path))).data as PrefabData;diff --git a/desktop/tests/prefab-cache-ref.test.ts b/desktop/tests/prefab-cache-ref.test.tsnew file mode 100644index 000000000..48e74fc6f--- /dev/null+++ b/desktop/tests/prefab-cache-ref.test.ts@@ -0,0 +1,55 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file A prefab ref is a uuid OR a project path.+ *+ * The runtime loader takes both; the editor's cache took only the uuid, so a+ * scene whose instance names its prefab by path opened with the instance+ * missing — and the package, loaded by the runtime, still had it.+ */+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';+import { PrefabCache } from '@/project/PrefabCache';+import { AssetRegistry } from '@/project/AssetRegistry';++const PREFAB = {+ version: '2', name: 'robot', rootEntityId: 'n0',+ entities: [{+ prefabEntityId: 'n0', name: 'Robot', parent: null, children: [],+ visible: true, components: [{ type: 'Transform', data: {} }],+ }],+};++const read = vi.fn(async () => JSON.stringify(PREFAB));++beforeEach(() => {+ (globalThis as { window?: unknown }).window = { estella: { fs: { read } } };+ PrefabCache.clear();+ read.mockClear();+});++afterEach(() => {+ PrefabCache.clear();+ delete (globalThis as { window?: unknown }).window;+});++describe('PrefabCache.load', () => {+ it('loads a prefab named by project path', async () => {+ const prefab = await PrefabCache.load('assets/models/robot.esprefab');+ expect(prefab?.name).toBe('robot');+ expect(read).toHaveBeenCalledWith('assets/models/robot.esprefab');+ });++ it('loads a prefab named by uuid, through the registry', async () => {+ AssetRegistry.rebuild([+ { uuid: '11111111-1111-4111-8111-111111111111', path: 'assets/models/robot.esprefab' },+ ]);+ const prefab = await PrefabCache.load('@uuid:11111111-1111-4111-8111-111111111111');+ expect(prefab?.name).toBe('robot');+ expect(read).toHaveBeenCalledWith('assets/models/robot.esprefab');+ });++ it('answers null for a uuid the registry does not know', async () => {+ expect(await PrefabCache.load('@uuid:22222222-2222-4222-8222-222222222222')).toBeNull();+ expect(read).not.toHaveBeenCalled();+ });+});diff --git a/examples/model-import/.gitignore b/examples/model-import/.gitignorenew file mode 100644index 000000000..359472ac2--- /dev/null+++ b/examples/model-import/.gitignore@@ -0,0 +1,7 @@+node_modules/+dist/+.vscode/+.idea/+.DS_Store+Thumbs.db+.esengine/cache/diff --git a/examples/model-import/assets/models/robot.esprefab b/examples/model-import/assets/models/robot.esprefabnew file mode 100644index 000000000..a25176cd8--- /dev/null+++ b/examples/model-import/assets/models/robot.esprefab@@ -0,0 +1,93 @@+{+ "version": "2",+ "name": "robot",+ "rootEntityId": "n0",+ "entities": [+ {+ "prefabEntityId": "n0",+ "name": "Robot",+ "parent": null,+ "children": [+ "n1",+ "n2"+ ],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": -20,+ "z": 0+ }+ }+ }+ ]+ },+ {+ "prefabEntityId": "n1",+ "name": "Body",+ "parent": "n0",+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {}+ },+ {+ "type": "Mesh2D",+ "data": {+ "mesh": "assets/models/robot_0_0.esmesh",+ "texture": "assets/models/robot_0.png",+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "enabled": true+ }+ }+ ]+ },+ {+ "prefabEntityId": "n2",+ "name": "Banner",+ "parent": "n0",+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 110,+ "z": 0+ },+ "scale": {+ "x": 0.9,+ "y": 0.9,+ "z": 1+ }+ }+ },+ {+ "type": "Mesh2D",+ "data": {+ "mesh": "assets/models/robot_1_0.esmesh",+ "color": {+ "r": 0.32,+ "g": 0.54,+ "b": 0.86,+ "a": 1+ },+ "enabled": true+ }+ }+ ]+ }+ ]+}diff --git a/examples/model-import/assets/models/robot.esprefab.meta b/examples/model-import/assets/models/robot.esprefab.metanew file mode 100644index 000000000..b706b6100--- /dev/null+++ b/examples/model-import/assets/models/robot.esprefab.meta@@ -0,0 +1,8 @@+{+ "uuid": "7b79d2b6-bbdc-43da-904a-70bb46e396a9",+ "version": "2.0",+ "type": "prefab",+ "importer": {+ "autoMigrate": true+ }+}diff --git a/examples/model-import/assets/models/robot.gltf b/examples/model-import/assets/models/robot.gltfnew file mode 100644index 000000000..3b23ae577--- /dev/null+++ b/examples/model-import/assets/models/robot.gltf@@ -0,0 +1,246 @@+{+ "asset": {+ "version": "2.0",+ "generator": "estella example fixture"+ },+ "buffers": [+ {+ "byteLength": 280,+ "uri": "data:application/octet-stream;base64,AADwwgAAcEIAAAAAAADwQgAAcEIAAAAAAADwwgAAcMIAAAAAAADwQgAAcMIAAAAAAAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AACAPwAAgD8AAAIAAQABAAIAAwAAAHDCAACgQQAAAAAAAHBCAACgQQAAAAAAAHDCAACgwQAAAAAAAHBCAACgwQAAAAAAAAAAAAAAAAAAgD8AAAAAAAAAAAAAgD8AAAAAAAAAAAAAgD8AAAAAAAAAAAAAgD8AAAAAAAAAAAAAgD8AAAAAAAAAAAAAgD8AAIA/AACAPwAAAgABAAEAAgADAA=="+ }+ ],+ "bufferViews": [+ {+ "buffer": 0,+ "byteOffset": 0,+ "byteLength": 48+ },+ {+ "buffer": 0,+ "byteOffset": 48,+ "byteLength": 48+ },+ {+ "buffer": 0,+ "byteOffset": 96,+ "byteLength": 32+ },+ {+ "buffer": 0,+ "byteOffset": 128,+ "byteLength": 12+ },+ {+ "buffer": 0,+ "byteOffset": 140,+ "byteLength": 48+ },+ {+ "buffer": 0,+ "byteOffset": 188,+ "byteLength": 48+ },+ {+ "buffer": 0,+ "byteOffset": 236,+ "byteLength": 32+ },+ {+ "buffer": 0,+ "byteOffset": 268,+ "byteLength": 12+ }+ ],+ "accessors": [+ {+ "bufferView": 0,+ "componentType": 5126,+ "count": 4,+ "type": "VEC3",+ "min": [+ -120,+ -60,+ 0+ ],+ "max": [+ 120,+ 60,+ 0+ ]+ },+ {+ "bufferView": 1,+ "componentType": 5126,+ "count": 4,+ "type": "VEC3"+ },+ {+ "bufferView": 2,+ "componentType": 5126,+ "count": 4,+ "type": "VEC2"+ },+ {+ "bufferView": 3,+ "componentType": 5123,+ "count": 6,+ "type": "SCALAR"+ },+ {+ "bufferView": 4,+ "componentType": 5126,+ "count": 4,+ "type": "VEC3",+ "min": [+ -60,+ -20,+ 0+ ],+ "max": [+ 60,+ 20,+ 0+ ]+ },+ {+ "bufferView": 5,+ "componentType": 5126,+ "count": 4,+ "type": "VEC3"+ },+ {+ "bufferView": 6,+ "componentType": 5126,+ "count": 4,+ "type": "VEC2"+ },+ {+ "bufferView": 7,+ "componentType": 5123,+ "count": 6,+ "type": "SCALAR"+ }+ ],+ "images": [+ {+ "mimeType": "image/png",+ "uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAYAAACp8Z5+AAAARElEQVR4AQXBMRHAMAwDQDWhIjjFoVkQAsGzhnLK0sl3gdL+X+9zf6pGTKgac5+xYkLViIkRE6pGTKgac5+xYkLViIkfu8caW04TahcAAAAASUVORK5CYII="+ }+ ],+ "samplers": [+ {+ "magFilter": 9728,+ "wrapS": 33071,+ "wrapT": 33071+ }+ ],+ "textures": [+ {+ "sampler": 0,+ "source": 0+ }+ ],+ "materials": [+ {+ "name": "Body",+ "pbrMetallicRoughness": {+ "baseColorFactor": [+ 1,+ 1,+ 1,+ 1+ ],+ "baseColorTexture": {+ "index": 0+ },+ "metallicFactor": 0,+ "roughnessFactor": 1+ }+ },+ {+ "name": "Banner",+ "pbrMetallicRoughness": {+ "baseColorFactor": [+ 0.32,+ 0.54,+ 0.86,+ 1+ ],+ "metallicFactor": 0,+ "roughnessFactor": 1+ }+ }+ ],+ "meshes": [+ {+ "name": "Body",+ "primitives": [+ {+ "attributes": {+ "POSITION": 0,+ "NORMAL": 1,+ "TEXCOORD_0": 2+ },+ "indices": 3,+ "material": 0,+ "mode": 4+ }+ ]+ },+ {+ "name": "Banner",+ "primitives": [+ {+ "attributes": {+ "POSITION": 4,+ "NORMAL": 5,+ "TEXCOORD_0": 6+ },+ "indices": 7,+ "material": 1,+ "mode": 4+ }+ ]+ }+ ],+ "nodes": [+ {+ "name": "Robot",+ "translation": [+ 0,+ -20,+ 0+ ],+ "children": [+ 1,+ 2+ ]+ },+ {+ "name": "Body",+ "mesh": 0+ },+ {+ "name": "Banner",+ "mesh": 1,+ "translation": [+ 0,+ 110,+ 0+ ],+ "scale": [+ 0.9,+ 0.9,+ 1+ ]+ }+ ],+ "scenes": [+ {+ "nodes": [+ 0+ ]+ }+ ],+ "scene": 0+}diff --git a/examples/model-import/assets/models/robot.gltf.meta b/examples/model-import/assets/models/robot.gltf.metanew file mode 100644index 000000000..4d688be71--- /dev/null+++ b/examples/model-import/assets/models/robot.gltf.meta@@ -0,0 +1,6 @@+{+ "uuid": "dccc7278-c536-477e-8c15-54d76ee1f9c7",+ "version": "2.0",+ "type": "model",+ "importer": {}+}diff --git a/examples/model-import/assets/models/robot_0.png b/examples/model-import/assets/models/robot_0.pngnew file mode 100644index 000000000..ed665660aBinary files /dev/null and b/examples/model-import/assets/models/robot_0.png differdiff --git a/examples/model-import/assets/models/robot_0.png.meta b/examples/model-import/assets/models/robot_0.png.metanew file mode 100644index 000000000..501a4174a--- /dev/null+++ b/examples/model-import/assets/models/robot_0.png.meta@@ -0,0 +1,20 @@+{+ "uuid": "74e75b7a-a23b-4439-9b09-63eb0b28dfb6",+ "version": "2.0",+ "type": "texture",+ "importer": {+ "maxSize": 2048,+ "compress": true,+ "compressFormat": "uastc",+ "filterMode": "nearest",+ "wrapMode": "clamp",+ "premultiplyAlpha": false,+ "sRGB": true,+ "sliceBorder": {+ "left": 0,+ "right": 0,+ "top": 0,+ "bottom": 0+ }+ }+}diff --git a/examples/model-import/assets/models/robot_0_0.esmesh b/examples/model-import/assets/models/robot_0_0.esmeshnew file mode 100644index 000000000..b53b1646dBinary files /dev/null and b/examples/model-import/assets/models/robot_0_0.esmesh differdiff --git a/examples/model-import/assets/models/robot_0_0.esmesh.meta b/examples/model-import/assets/models/robot_0_0.esmesh.metanew file mode 100644index 000000000..a9255dc1d--- /dev/null+++ b/examples/model-import/assets/models/robot_0_0.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "28acc33e-9d06-496f-9bb2-173e9783ac00",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/examples/model-import/assets/models/robot_1_0.esmesh b/examples/model-import/assets/models/robot_1_0.esmeshnew file mode 100644index 000000000..50ef1b866Binary files /dev/null and b/examples/model-import/assets/models/robot_1_0.esmesh differdiff --git a/examples/model-import/assets/models/robot_1_0.esmesh.meta b/examples/model-import/assets/models/robot_1_0.esmesh.metanew file mode 100644index 000000000..22edb03bb--- /dev/null+++ b/examples/model-import/assets/models/robot_1_0.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "5ede9d6d-f87c-490e-9525-82079d1a9040",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/examples/model-import/assets/scenes/main.esscene b/examples/model-import/assets/scenes/main.esscenenew file mode 100644index 000000000..69eba2493--- /dev/null+++ b/examples/model-import/assets/scenes/main.esscene@@ -0,0 +1,36 @@+{+ "version": 1,+ "name": "Main",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 110, "isActive": true, "priority": 0 } }+ ]+ },+ {+ "id": 1,+ "name": "Sun",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },+ { "type": "Light2D", "data": { "type": 1, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "intensity": 1, "direction": { "x": 0, "y": 0 }, "enabled": true } }+ ]+ },+ {+ "id": 2,+ "parent": null,+ "prefab": "assets/models/robot.esprefab",+ "overrides": [],+ "added": [],+ "removed": []+ }+ ]+}diff --git a/examples/model-import/assets/scenes/main.esscene.meta b/examples/model-import/assets/scenes/main.esscene.metanew file mode 100644index 000000000..f7aafe97f--- /dev/null+++ b/examples/model-import/assets/scenes/main.esscene.meta@@ -0,0 +1,8 @@+{+ "uuid": "ea1b778d-e663-4cd0-9b93-70f789a21e5c",+ "version": "2.0",+ "type": "scene",+ "importer": {+ "autoMigrate": true+ }+}diff --git a/examples/model-import/project.esproject b/examples/model-import/project.esprojectnew file mode 100644index 000000000..86334c37e--- /dev/null+++ b/examples/model-import/project.esproject@@ -0,0 +1,13 @@+{+ "formatVersion": "1",+ "name": "Model Import",+ "description": "A glTF brought in as engine assets — mesh, image and prefab — and placed in a scene.",+ "tag": "3D",+ "version": "0.1.0",+ "defaultScene": "assets/scenes/main.esscene",+ "designResolution": {+ "width": 800,+ "height": 600+ },+ "spineVersion": "none"+}diff --git a/examples/model-import/src/main.ts b/examples/model-import/src/main.tsnew file mode 100644index 000000000..494cedcf0--- /dev/null+++ b/examples/model-import/src/main.ts@@ -0,0 +1,3 @@+// The model is placed by the scene: importing a glTF produces a prefab, and the+// scene holds an instance of it. Nothing here has to know about meshes.+export {};diff --git a/examples/model-import/tsconfig.json b/examples/model-import/tsconfig.jsonnew file mode 100644index 000000000..1f11ff310--- /dev/null+++ b/examples/model-import/tsconfig.json@@ -0,0 +1,20 @@+{+ "compilerOptions": {+ "target": "ES2020",+ "module": "ESNext",+ "moduleResolution": "bundler",+ "strict": true,+ "esModuleInterop": true,+ "skipLibCheck": true,+ "forceConsistentCasingInFileNames": true,+ "declaration": false,+ "outDir": "./dist",+ "rootDir": ".",+ "paths": {+ "esengine": ["./.esengine/sdk/index.d.ts"],+ "esengine/wasm": ["./.esengine/sdk/wasm.d.ts"]+ }+ },+ "include": ["src/**/*"],+ "exclude": ["node_modules"]+}diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjsindex fff717dae..036f27bfd 100644--- a/pipeline/bin/estella.mjs+++ b/pipeline/bin/estella.mjs@@ -165,6 +165,11 @@ const opts = parseArgs(process.argv.slice(2));if (opts.command === 'import-gltf') {const { mod: importer, cleanup } = await loadPipeline(path.join(PIPELINE, 'src', 'assets', 'gltfImport.ts'), 'gltfImport.mjs');+ // The products are project assets, so they get their `.meta` here rather than+ // waiting for a scan — which is also the only moment the source's own import+ // settings (a sampler's filter and wrap) are still in hand.+ const { mod: meta, cleanup: cleanupMeta } = await loadPipeline(+ path.join(PIPELINE, 'src', 'assets', 'assetMeta.ts'), 'assetMeta.mjs');let imported = 0;try {const sourceDir = path.dirname(opts.source);@@ -193,21 +198,32 @@ if (opts.command === 'import-gltf') {}const report = (file, what) =>console.log(`${path.relative(process.cwd(), file)}: ${what}`);+ // Settings the source asked for, by product name; only ever the FIRST mint.+ const settings = new Map();+ for (const mesh of meshes) {+ for (const image of [mesh.material?.baseColorTexture, mesh.material?.normalTexture]) {+ if (image?.settings) settings.set(image.file, image.settings);+ }+ }+ const adopt = (file) => meta.adoptOrphan(file, settings.get(path.basename(file)));for (const mesh of meshes) {const outFile = path.join(dir, `${mesh.name}.esmesh`);writeFileSync(outFile, importer.encodeImportedMesh(mesh));+ await adopt(outFile);report(outFile, `${mesh.vertexCount} vertices, ${mesh.triangleCount} triangles`);}for (const texture of textures) {const outFile = path.join(dir, texture.name);writeFileSync(outFile, texture.bytes);+ await adopt(outFile);report(outFile, `${texture.bytes.length} bytes`);}if (meshes.length > 0) {const outFile = path.join(dir, `${stem}.esprefab`);const prefab = importer.assembleGltfPrefab(stem, meshes, { refs, nodes, scale: opts.scale });writeFileSync(outFile, `${JSON.stringify(prefab, null, 2)}\n`);+ await adopt(outFile);report(outFile, `${prefab.entities.length} entit${prefab.entities.length === 1 ? 'y' : 'ies'}`);// A glTF is authored in metres and a world unit is a design pixel, so a@@ -222,6 +238,7 @@ if (opts.command === 'import-gltf') {imported = meshes.length;} finally {cleanup();+ cleanupMeta();}process.exit(imported > 0 ? 0 : 1);}diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjsindex 82032dbdd..c80402d59 100644--- a/tools/goldenProjects.mjs+++ b/tools/goldenProjects.mjs@@ -52,6 +52,7 @@ export const CAPABILITIES = ['ecs', 'particles', 'audio','ui-layout', 'text', 'localization','spine', 'material', 'asset-lifecycle',+ 'model-import','tilemap', 'tile-collision','touch', 'safe-area', 'pause-resume','texture-atlas',@@ -86,6 +87,9 @@ export const EVIDENCE = {localization: /\b(Localization|i18nKey|setLocale)\b/,spine: /\bSpine(Animation)?\b/,material: /\b(Material|material)\b/,+ // The products, not the source: a .gltf in the project proves an import ran,+ // and a scene referencing an .esmesh proves the products are what it draws.+ 'model-import': /\.esmesh\b/,'asset-lifecycle': /\b(Assets|loadGroup|releaseGroup|preload)\b/,tilemap: /\bTilemap(Layer)?\b/,'tile-collision': /\b(collision|Collider|tileCollision)\b/,@@ -170,6 +174,15 @@ export const GOLDEN = [// count is the claim: packing that quietly stops still passes parity.atlas: { packed: 7 },},+ {+ id: 'model-import',+ certifies: ['model-import'],+ targets: ['web'],+ tier: 'pr',+ // Nothing in it responds to input: the scene is a placed model, and the+ // chain it certifies is the import's — products, refs, prefab, package.+ interactGap: 'a placed model has nothing to drive; the import chain is what this certifies',+ },{id: 'ui-controls',certifies: ['ui-layout', 'text'],