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(assets): a model imports itself, and again when it changes
esengine0d337359fe08
diff --git a/desktop/electron/importModel.ts b/desktop/electron/importModel.tsindex 31bc9edd6..76e5a6c89 100644--- a/desktop/electron/importModel.ts+++ b/desktop/electron/importModel.ts@@ -12,7 +12,7 @@ import { copyFile, mkdir, writeFile } from 'node:fs/promises';import { existsSync, readFileSync } from 'node:fs';import path from 'node:path';import { isInsideRoot } from '../../pipeline/src/fs/pathSandbox';-import { resolveInRoot } from './projectFs';+import { resolveInRoot, META_EXT } from './projectFs';import { capture } from './fileJournal';import { adoptOrphan } from '../../pipeline/src/assets/assetMeta';import {@@ -57,6 +57,10 @@ export async function importModel(root: string, destDir: string, absSource: stri},);+ // The source's own `.meta` says how big the model should arrive; re-importing+ // is how an edited setting reaches the products.+ const scale = modelScale(absSource);+// What each image's sampler asked for, by product name — applied when its// `.meta` is first minted and never after: the file's settings are the user's.const imageSettings = new Map<string, Record<string, unknown>>();@@ -115,8 +119,29 @@ export async function importModel(root: string, destDir: string, absSource: striawait write(`${material.name}.esmaterial`, `${JSON.stringify(material.data, null, 2)}\n`);}if (meshes.length > 0) {- const prefab = assembleGltfPrefab(stem, meshes, { refs, nodes });+ const prefab = assembleGltfPrefab(stem, meshes, { refs, nodes, scale });await write(`${stem}.esprefab`, `${JSON.stringify(prefab, null, 2)}\n`);+ // A glTF is in metres and a world unit is a design pixel, so a real-world+ // model arrives a few pixels across. Said, not guessed at: the scale is the+ // user's, and this is where they find out they have one.+ const extent = Math.max(...meshes.flatMap(+ (m) => m.data.aabbMax.map((v, i) => v - (m.data.aabbMin[i] ?? 0))));+ if (scale === 1 && extent < 8) {+ warnings.push(`the model is ${extent.toFixed(2)} units across — set Scale in its import`+ + ' settings and reimport if it should be bigger');+ }}return { products, warnings };}++/** The `scale` its `.meta` asks for; 1 when there is none, or it is unusable. */+function modelScale(absSource: string): number {+ try {+ const meta = JSON.parse(readFileSync(`${absSource}${META_EXT}`, 'utf8')) as+ { importer?: { scale?: unknown } };+ const scale = meta.importer?.scale;+ return typeof scale === 'number' && scale > 0 ? scale : 1;+ } catch {+ return 1;+ }+}diff --git a/desktop/electron/main.ts b/desktop/electron/main.tsindex 9beb79e26..4b43f2a79 100644--- a/desktop/electron/main.ts+++ b/desktop/electron/main.ts@@ -36,6 +36,7 @@ import { scanAssetDatabase, readCachedAssetIndex, updateAssetIndex } from '../..import { cookAssets } from '../../pipeline/src/assets/cookAssets';import { startProjectWatch, stopProjectWatch } from './projectWatcher';import { importAssets, createAsset, IMPORT_EXTENSIONS } from './importAssets';+import { importModel, isModelSource } from './importModel';import { exportGame } from '../../pipeline/src/export/exportGame';import {iosSourcesFromTemplate, resolveNativeTemplate, installNativeTemplate, listNativeTemplates,@@ -1037,6 +1038,19 @@ ipcMain.handle('project:importFiles', async (_e, destDir: string, sources: strinreturn result;});+// Re-import a model already in the project: same products, same uuids, beside+// the source. This is how an edited `.gltf` — or an edited scale in its `.meta`+// — reaches the assets a scene references.+ipcMain.handle('project:reimportModel', async (_e, file: string) => {+ const root = requireRoot();+ const abs = resolveInRoot(root, file);+ if (!isModelSource(abs)) return { products: [], warnings: [] };+ const dir = file.includes('/') ? file.slice(0, file.lastIndexOf('/')) : '';+ const result = await importModel(root, dir, abs);+ notifyFsChanged(result.products);+ return result;+});+// Create a new asset file (+ .meta) from renderer-supplied content (e.g. New Scene).ipcMain.handle('project:createAsset', async (_e, destDir: string, baseName: string, content: string, type: string) => {const rel = await createAsset(requireRoot(), destDir, baseName, content, type);diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.tsindex 3e2ff359f..dc2bcb5ad 100644--- a/desktop/electron/preload.ts+++ b/desktop/electron/preload.ts@@ -243,6 +243,10 @@ const api = {/** Import already-resolved absolute paths (OS drag-drop) into `destDir`. */importFiles: (destDir: string, sources: string[]): Promise<{ imported: string[]; skipped: string[] } | null> =>ipcRenderer.invoke('project:importFiles', destDir, sources),+ /** Re-run a model's import in place: the door an edited source, or an edited+ * import setting, reaches its products through. */+ reimportModel: (file: string): Promise<{ products: string[]; warnings: string[] }> =>+ ipcRenderer.invoke('project:reimportModel', file),/** Create a new asset file (+ .meta) from `content`; returns its project path. */createAsset: (destDir: string, baseName: string, content: string, type: string): Promise<string> =>ipcRenderer.invoke('project:createAsset', destDir, baseName, content, type),diff --git a/desktop/scripts/editor-checks/model-reimport.mjs b/desktop/scripts/editor-checks/model-reimport.mjsnew file mode 100644index 000000000..cb5ed467c--- /dev/null+++ b/desktop/scripts/editor-checks/model-reimport.mjs@@ -0,0 +1,110 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file model-reimport — a model that lands in the project becomes assets, and+ * keeps doing so when it changes.+ *+ * The import ran once, at the moment a file was dropped: a `.gltf` copied in by+ * git or a re-export from Blender produced nothing, and an import setting had no+ * way to reach the products it decides. Registering the model import as an+ * ordinary importer is what connects the watcher, the Reimport row and the+ * settings to it — none of which a unit test can exercise, because every one of+ * them lives on the other side of the editor's own file plumbing.+ */+import { mkdir, readFile, writeFile } from 'node:fs/promises';+import { existsSync } from 'node:fs';+import { cp } from 'node:fs/promises';+import path from 'node:path';+import { makeProject, checker, DESKTOP } from '../lib/editorDriver.mjs';++const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'sprite-rendering');++const SCENE = JSON.stringify({ version: 1, name: 'Main', entities: [] }, null, 1);++/** One triangle, one unit across — small enough that the import says so. */+function gltf() {+ const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);+ const uvs = new Float32Array([0, 0, 1, 0, 0, 1]);+ const indices = new Uint16Array([0, 1, 2]);+ const bytes = Buffer.concat([+ Buffer.from(positions.buffer), Buffer.from(uvs.buffer), Buffer.from(indices.buffer),+ ]);+ return JSON.stringify({+ asset: { version: '2.0' },+ buffers: [{ byteLength: bytes.length, uri: `data:application/octet-stream;base64,${bytes.toString('base64')}` }],+ bufferViews: [+ { buffer: 0, byteOffset: 0, byteLength: 36 },+ { buffer: 0, byteOffset: 36, byteLength: 24 },+ { buffer: 0, byteOffset: 60, byteLength: 6 },+ ],+ accessors: [+ { bufferView: 0, componentType: 5126, count: 3, type: 'VEC3' },+ { bufferView: 1, componentType: 5126, count: 3, type: 'VEC2' },+ { bufferView: 2, componentType: 5123, count: 3, type: 'SCALAR' },+ ],+ meshes: [{ primitives: [{ attributes: { POSITION: 0, TEXCOORD_0: 1 }, indices: 2, mode: 4 }] }],+ nodes: [{ name: 'Body', mesh: 0 }],+ scenes: [{ nodes: [0] }],+ scene: 0,+ });+}++export const name = 'model-reimport';+export const describes = 'a model in the project imports itself, and re-imports when it changes';++/** Poll until `test()` of the file's content passes, up to `ms`. */+async function until(ed, file, test, ms = 12000) {+ const deadline = Date.now() + ms;+ while (Date.now() < deadline) {+ if (existsSync(file)) {+ try {+ if (test(JSON.parse(await readFile(file, 'utf8')))) return true;+ } catch { /* half-written or not JSON yet */ }+ }+ await ed.sleep(250);+ }+ return false;+}++export async function run(ed) {+ const root = await makeProject({ 'assets/scenes/main.esscene': SCENE });+ await cp(path.join(EXAMPLE, 'project.esproject'), path.join(root, 'project.esproject'));+ await cp(path.join(EXAMPLE, 'src'), path.join(root, 'src'), { recursive: true });+ const check = checker();+ await ed.open(root, 'assets/scenes/main.esscene');++ // Arriving the way a checkout or a Blender re-export does: written into the+ // project with the editor already open, never through the import dialog.+ const source = path.join(root, 'assets/models/robot.gltf');+ await mkdir(path.dirname(source), { recursive: true });+ await writeFile(source, gltf());++ const prefab = path.join(root, 'assets/models/robot.esprefab');+ if (!check(await until(ed, prefab, (p) => p.entities?.length > 0),+ 'a model written into the project produced no prefab — nothing imported it')) {+ return check.failures;+ }+ check(existsSync(path.join(root, 'assets/models/robot.esmesh')),+ 'the prefab exists but the mesh it references does not');++ // Its `.meta` carries the import settings, minted from the schema — without+ // them there is nothing for a user to edit.+ const meta = `${source}.meta`;+ if (!check(await until(ed, meta, (m) => m.importer?.scale === 1),+ 'the source has no `scale` import setting, so its size cannot be authored')) {+ return check.failures;+ }++ const doc = JSON.parse(await readFile(meta, 'utf8'));+ doc.importer.scale = 64;+ await writeFile(meta, JSON.stringify(doc, null, 2));+ // The setting decides a product, so the product is re-made: touching the+ // source is what a user's Reimport does through the same door.+ await writeFile(source, gltf());+ check(+ await until(ed, prefab, (p) => p.entities?.[0]?.components?.[0]?.data?.scale?.x === 64),+ 'the edited scale never reached the prefab — the re-import does not read the settings',+ );++ return check.failures;+}diff --git a/desktop/src/plugins/importers.ts b/desktop/src/plugins/importers.tsindex f41f4a3e1..12163934a 100644--- a/desktop/src/plugins/importers.ts+++ b/desktop/src/plugins/importers.ts@@ -8,6 +8,7 @@* registry, the inspector, cooking, the shipped build — learns a second format.*/import { ContributionRegistry, type Disposable, type Owner } from '@/contrib/ContributionRegistry';+import { Toasts } from '@/store/Toasts';/** An importer as the host holds it: the declaration, plus the already-guarded* call, so a failure is attributed to its plugin wherever it is run from. */@@ -60,3 +61,17 @@ export async function runImporters(paths: readonly string[]): Promise<void> {}}}++// The model import is the editor's own, but it is an importer like any other and+// is registered rather than special-cased — Reimport and the source watcher then+// reach it by the one rule, not by a second test for model extensions.+importerRegistry.register('core', {+ id: 'core:model',+ extensions: ['gltf', 'glb'],+ run: async (path: string): Promise<void> => {+ const result = await window.estella.project.reimportModel(path);+ // The same notes a first import shows: what the source says that the engine+ // cannot draw, and how big it arrived.+ for (const warning of result.warnings) Toasts.push(`${path}: ${warning}`, 'warn');+ },+});diff --git a/desktop/tests/import-model.test.ts b/desktop/tests/import-model.test.tsindex b029d72fa..1d1ca237d 100644--- a/desktop/tests/import-model.test.ts+++ b/desktop/tests/import-model.test.ts@@ -62,7 +62,12 @@ function gltf(image?: string): string {});}-const prefabOf = (abs: string): { entities: { components: { type: string; data: Record<string, string> }[] }[] } =>+/** The fixture is a 1-unit triangle, so every import notes its size; these are+ * the notes that would mean something went wrong. */+const notSizeNotes = (warnings: string[] | undefined): string[] =>+ (warnings ?? []).filter((w) => !w.includes('units across'));++const prefabOf = (abs: string): { entities: { components: { type: string; data: Record<string, unknown> }[] }[] } =>JSON.parse(readFileSync(abs, 'utf8'));describe('importing a model', () => {@@ -106,6 +111,32 @@ describe('importing a model', () => {.toBe('assets/models/robot_m0.esmaterial');});+ it('arrives at the size its import settings ask for', async () => {+ // A glTF is in metres and a world unit is a design pixel, so the scale is on+ // the prefab's root rather than baked into the geometry — the product stays+ // faithful to the source and the number stays editable.+ const abs = path.join(root, 'assets/models/robot.gltf');+ mkdirSync(path.dirname(abs), { recursive: true });+ writeFileSync(abs, gltf());+ const plain = await importAssets(root, 'assets/models', [abs]);+ expect((plain.warnings ?? []).some((w) => w.includes('units across'))).toBe(true);+ const before = prefabOf(path.join(root, 'assets/models/robot.esprefab'));+ expect(before.entities[0]!.components[0]!.data.scale).toBeUndefined();++ const metaPath = `${abs}.meta`;+ const doc = JSON.parse(readFileSync(metaPath, 'utf8')) as { importer: { scale?: number } };+ expect(doc.importer.scale).toBe(1); // minted from the schema, editable in place+ doc.importer.scale = 64;+ writeFileSync(metaPath, JSON.stringify(doc, null, 2));++ const scaled = await importAssets(root, 'assets/models', [abs]);+ // Sized as asked, and the note about being small is gone with it.+ expect((scaled.warnings ?? []).some((w) => w.includes('units across'))).toBe(false);+ const after = prefabOf(path.join(root, 'assets/models/robot.esprefab'));+ expect(after.entities[0]!.components[0]!.data.scale)+ .toEqual({ x: 64, y: 64, z: 64 });+ });+it('produces beside an in-project source, not in the browser’s folder', async () => {const abs = path.join(root, 'assets/sub/tree.gltf');mkdirSync(path.dirname(abs), { recursive: true });@@ -146,14 +177,14 @@ describe('importing a model', () => {const first = await importAssets(root, 'assets/models', [src]);expect(first.imported).toContain('assets/models/robot.bin');- expect(first.warnings ?? []).toEqual([]);+ expect(notSizeNotes(first.warnings)).toEqual([]);// The copy, imported on its own terms: the geometry has to come out again.rmSync(outside, { recursive: true, force: true });const again = await importAssets(root, 'assets/models',[path.join(root, 'assets/models/robot.gltf')]);expect(again.imported).toContain('assets/models/robot.esmesh');- expect(again.warnings ?? []).toEqual([]);+ expect(notSizeNotes(again.warnings)).toEqual([]);});it('says so when a dependency cannot keep its shape inside the project', async () => {diff --git a/desktop/tests/plugin-importers.test.ts b/desktop/tests/plugin-importers.test.tsindex 20da86053..8b417fafb 100644--- a/desktop/tests/plugin-importers.test.ts+++ b/desktop/tests/plugin-importers.test.ts@@ -12,7 +12,7 @@*/import { describe, it, expect, afterEach } from 'vitest';import { buildPluginContext } from '@/plugins/context';-import { hasImporter, runImporters } from '@/plugins/importers';+import { hasImporter, importerRegistry, runImporters } from '@/plugins/importers';import type { PluginManifest } from '@/plugins/manifest';const MANIFEST: PluginManifest = {@@ -139,3 +139,13 @@ describe('a contributed importer', () => {expect(seen).toEqual(['levels/w.ldtk']);});});++describe('the model importer is one of them', () => {+ it('claims .gltf and .glb, so Reimport and the watcher reach it', () => {+ // Registered rather than special-cased: the Content Browser row and the+ // source watcher both ask `hasImporter`, and a model has to answer yes.+ expect(hasImporter('assets/models/robot.gltf')).toBe(true);+ expect(hasImporter('assets/models/robot.glb')).toBe(true);+ expect(importerRegistry.forPath('assets/models/robot.glb')[0]?.id).toBe('core:model');+ });+});diff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.tsindex b4ca34927..e29d94cb3 100644--- a/pipeline/src/project/importSettings.ts+++ b/pipeline/src/project/importSettings.ts@@ -157,9 +157,19 @@ const SCENELIKE: ImporterFieldSpec[] = [},];+const MODEL: ImporterFieldSpec[] = [+ {+ key: 'scale', label: 'Scale', type: 'number', default: 1, min: 0.0001, step: 0.1,+ category: 'Import',+ tooltip: 'Uniform scale on the imported prefab\u0027s root. A glTF is authored in metres '+ + 'and a world unit is a design pixel, so a real-world model arrives a few pixels across.',+ },+];+/** type → its import-setting field specs. Types absent here have no import* settings (only metadata) and get an empty defaults object. */export const IMPORTER_SCHEMAS: Record<string, ImporterFieldSpec[]> = {+ model: MODEL,texture: TEXTURE,sprite: TEXTURE,spine: SPINE,