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(assets): a model imports itself, and again when it changes

esengine0d337359fe08
diff --git a/desktop/electron/importModel.ts b/desktop/electron/importModel.ts
index 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: stri
await 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.ts
index 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: strin
return 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.ts
index 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.mjs
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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,