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.

fix(assets): a declared import setting has a reader

esengine54535d26f9dc
diff --git a/desktop/src/document/openGraphAsset.ts b/desktop/src/document/openGraphAsset.ts
index f07aa12cc..d26a45ed7 100644
--- a/desktop/src/document/openGraphAsset.ts
+++ b/desktop/src/document/openGraphAsset.ts
@@ -73,7 +73,7 @@ export async function createGraphAsset(kind: GraphAssetKind, dir: string): Promi
await window.estella.fs.write(rel, JSON.stringify(kind.emptyDef(), null, 2) + '\n');
await window.estella.fs.write(
rel + '.meta',
- JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: kind.metaType, importer: { autoMigrate: true } }, null, 2) + '\n',
+ JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: kind.metaType, importer: {} }, null, 2) + '\n',
);
} catch (e) {
Toasts.push(t(kind.toast.createFailed, { error: String(e) }), 'error');
diff --git a/desktop/src/flipbook/openFlipbook.ts b/desktop/src/flipbook/openFlipbook.ts
index 01270731c..bb17101d8 100644
--- a/desktop/src/flipbook/openFlipbook.ts
+++ b/desktop/src/flipbook/openFlipbook.ts
@@ -77,7 +77,7 @@ export async function createFlipbookFromTexture(texturePath: string): Promise<vo
await window.estella.fs.write(rel, JSON.stringify(serializeAnimClip(asset), null, 2) + '\n');
await window.estella.fs.write(
rel + '.meta',
- JSON.stringify({ uuid, version: '1.0', type: 'animclip', importer: { autoMigrate: true } }, null, 2) + '\n',
+ JSON.stringify({ uuid, version: '1.0', type: 'animclip', importer: {} }, null, 2) + '\n',
);
} catch (e) {
Toasts.push(t('fb.toast.createFailed', { error: String(e) }), 'error');
diff --git a/desktop/src/material/openMaterial.ts b/desktop/src/material/openMaterial.ts
index 8d53ab32b..3a7ff11a1 100644
--- a/desktop/src/material/openMaterial.ts
+++ b/desktop/src/material/openMaterial.ts
@@ -38,7 +38,7 @@ function uniqueMaterialPath(dir: string, base: string): string {
async function writeMeta(rel: string): Promise<void> {
await window.estella.fs.write(
rel + '.meta',
- JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'material', importer: { autoMigrate: true } }, null, 2) + '\n',
+ JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'material', importer: {} }, null, 2) + '\n',
);
}
diff --git a/desktop/src/material/openMaterialGraph.ts b/desktop/src/material/openMaterialGraph.ts
index 896e83aa1..0c1e908dc 100644
--- a/desktop/src/material/openMaterialGraph.ts
+++ b/desktop/src/material/openMaterialGraph.ts
@@ -73,7 +73,7 @@ export async function createMaterialGraph(dir: string): Promise<void> {
await window.estella.fs.write(shaderPathOf(rel), compileMaterialGraph(graph));
await window.estella.fs.write(
rel + '.meta',
- JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'materialgraph', importer: { autoMigrate: true } }, null, 2) + '\n',
+ JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'materialgraph', importer: {} }, null, 2) + '\n',
);
} catch (e) {
Toasts.push(t('mat.createGraphFailed', { error: String(e) }), 'error');
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index f1dd41e3f..caf1130a9 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -1301,7 +1301,7 @@ class ProjectStoreImpl {
await window.estella.fs.write(rel, JSON.stringify(prefab, null, 2) + '\n');
await window.estella.fs.write(
rel + '.meta',
- JSON.stringify({ uuid, version: '2.0', type: 'prefab', importer: { autoMigrate: true } }, null, 2) + '\n',
+ JSON.stringify({ uuid, version: '2.0', type: 'prefab', importer: {} }, null, 2) + '\n',
);
} catch (err) {
console.warn('[project] prefab write failed', rel, err);
diff --git a/desktop/src/tileset/openTileset.ts b/desktop/src/tileset/openTileset.ts
index d7e857286..2180a79f7 100644
--- a/desktop/src/tileset/openTileset.ts
+++ b/desktop/src/tileset/openTileset.ts
@@ -65,7 +65,7 @@ export async function createTilesetFromTexture(texturePath: string, grid?: Tiles
await window.estella.fs.write(rel, JSON.stringify(serializeTileset(asset), null, 2) + '\n');
await window.estella.fs.write(
rel + '.meta',
- JSON.stringify({ uuid, version: '1.0', type: 'tileset', importer: { autoMigrate: true } }, null, 2) + '\n',
+ JSON.stringify({ uuid, version: '1.0', type: 'tileset', importer: {} }, null, 2) + '\n',
);
} catch (e) {
Toasts.push(t('tile.toast.createFailed', { error: String(e) }), 'error');
diff --git a/desktop/src/timeline/openClip.ts b/desktop/src/timeline/openClip.ts
index 7382871b3..6db8a5832 100644
--- a/desktop/src/timeline/openClip.ts
+++ b/desktop/src/timeline/openClip.ts
@@ -59,7 +59,7 @@ export async function createAnimationClip(dir: string): Promise<void> {
await window.estella.fs.write(rel, JSON.stringify(BLANK_CLIP, null, 2) + '\n');
await window.estella.fs.write(
rel + '.meta',
- JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'animation', importer: { autoMigrate: true } }, null, 2) + '\n',
+ JSON.stringify({ uuid: crypto.randomUUID(), version: '1.0', type: 'animation', importer: {} }, null, 2) + '\n',
);
} catch (e) {
Toasts.push(t('seq.toast.createFailed', { error: String(e) }), 'error');
diff --git a/desktop/tests/asset-importer.test.ts b/desktop/tests/asset-importer.test.ts
index 96c7bf1ca..4779d8165 100644
--- a/desktop/tests/asset-importer.test.ts
+++ b/desktop/tests/asset-importer.test.ts
@@ -23,16 +23,16 @@ describe('importerDefaults (import-time .meta)', () => {
compressFormat: 'uastc',
filterMode: 'linear',
wrapMode: 'repeat',
- premultiplyAlpha: false,
sRGB: true,
sliceBorder: { left: 0, right: 0, top: 0, bottom: 0 },
});
});
- it('reproduces spine + scene-like defaults, and is empty for unknown types', () => {
- expect(importerDefaults('spine')).toEqual({ scale: 1, defaultSkin: 'default', premultiplyAlpha: false });
- expect(importerDefaults('scene')).toEqual({ autoMigrate: true });
- expect(importerDefaults('prefab')).toEqual({ autoMigrate: true });
+ it('is empty for a type with no import settings, and for an unknown one', () => {
+ expect(importerDefaults('spine')).toEqual({ scale: 1, defaultSkin: 'default' });
expect(importerDefaults('audio')).toEqual({ compress: true, bitrateKbps: 128 });
+ // A scene is authored, not imported: it has metadata and no settings.
+ expect(importerDefaults('scene')).toEqual({});
+ expect(importerDefaults('nonesuch')).toEqual({});
});
});
diff --git a/desktop/tests/video-asset.test.ts b/desktop/tests/video-asset.test.ts
index 544b0cbb6..c84f97998 100644
--- a/desktop/tests/video-asset.test.ts
+++ b/desktop/tests/video-asset.test.ts
@@ -28,11 +28,10 @@ describe('video asset type', () => {
expect(metaTypeFor('sound.webm')).toBe('audio');
});
- it('exposes video import settings (playback defaults + cook fields)', () => {
+ it('exposes the cook settings, and leaves playback to the component', () => {
+ // loop / autoplay / muted are Video component fields; an import-time copy of
+ // them was read by nothing.
expect(hasImporterSettings('video')).toBe(true);
- expect(importerDefaults('video')).toEqual({
- loop: true, autoplay: true, muted: true,
- quality: 4, audioBitrateKbps: 128,
- });
+ expect(importerDefaults('video')).toEqual({ quality: 4, audioBitrateKbps: 128 });
});
});
diff --git a/pipeline/src/project/importSettings.ts b/pipeline/src/project/importSettings.ts
index e29d94cb3..aa6304fb1 100644
--- a/pipeline/src/project/importSettings.ts
+++ b/pipeline/src/project/importSettings.ts
@@ -77,10 +77,6 @@ const TEXTURE: ImporterFieldSpec[] = [
selectOptions: ['repeat', 'clamp', 'mirror'],
tooltip: 'How UVs outside [0,1] are addressed.',
},
- {
- key: 'premultiplyAlpha', label: 'Premultiply Alpha', type: 'bool', default: false,
- category: 'Texture', advanced: true,
- },
{
key: 'sRGB', label: 'sRGB Color', type: 'bool', default: true, category: 'Texture', advanced: true,
tooltip: 'The image stores sRGB-encoded color (albedo/UI). Disable for authored-linear '
@@ -95,7 +91,6 @@ const TEXTURE: ImporterFieldSpec[] = [
const SPINE: ImporterFieldSpec[] = [
{ key: 'scale', label: 'Scale', type: 'number', default: 1, min: 0, step: 0.01, category: 'Spine' },
{ key: 'defaultSkin', label: 'Default Skin', type: 'string', default: 'default', category: 'Spine' },
- { key: 'premultiplyAlpha', label: 'Premultiply Alpha', type: 'bool', default: false, category: 'Spine', advanced: true },
];
// A DragonBones file is a project: it can hold several armatures, so which one an
@@ -126,16 +121,9 @@ const AUDIO: ImporterFieldSpec[] = [
},
];
+// Playback (loop / autoplay / muted) belongs to the Video COMPONENT, which
+// carries all three: an import-time copy of them was read by nothing.
const VIDEO: ImporterFieldSpec[] = [
- {
- key: 'loop', label: 'Loop', type: 'bool', default: true, category: 'Video',
- tooltip: 'Suggested loop state when this clip is assigned to a Video component.',
- },
- { key: 'autoplay', label: 'Autoplay', type: 'bool', default: true, category: 'Video' },
- {
- key: 'muted', label: 'Muted', type: 'bool', default: true, category: 'Video',
- tooltip: 'Muted clips can autoplay; unmuted autoplay is blocked until a user gesture.',
- },
{
key: 'quality', label: 'Cook Quality', type: 'number', default: 4, min: 2, max: 31, step: 1,
category: 'Video', advanced: true,
@@ -150,13 +138,6 @@ const VIDEO: ImporterFieldSpec[] = [
},
];
-const SCENELIKE: ImporterFieldSpec[] = [
- {
- key: 'autoMigrate', label: 'Auto Migrate', type: 'bool', default: true, category: 'Import',
- tooltip: 'Upgrade this asset to the current schema version when it loads.',
- },
-];
-
const MODEL: ImporterFieldSpec[] = [
{
key: 'scale', label: 'Scale', type: 'number', default: 1, min: 0.0001, step: 0.1,
@@ -176,8 +157,6 @@ export const IMPORTER_SCHEMAS: Record<string, ImporterFieldSpec[]> = {
dragonbones: DRAGONBONES,
audio: AUDIO,
video: VIDEO,
- scene: SCENELIKE,
- prefab: SCENELIKE,
};
/** Cook-facing audio import settings, tolerant of hand-edited `.meta` blocks. */
diff --git a/tools/check-import-settings.mjs b/tools/check-import-settings.mjs
new file mode 100644
index 000000000..b00b76a3e
--- /dev/null
+++ b/tools/check-import-settings.mjs
@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-import-settings.mjs — a declared import setting has a reader.
+ *
+ * The sibling of check-component-fields, one layer out: an `IMPORTER_SCHEMAS`
+ * entry is a knob in the asset inspector, written into every fresh `.meta`, and
+ * one nothing reads looks exactly like one that works. A model's `scale` was the
+ * first that did anything after being saved; the ones this found had never been
+ * read at all.
+ *
+ * A reader is a file that mentions the key AND the importer block it comes from
+ * — `importer?.maxSize`, a `readXxxSettings` destructure, an import that reads
+ * its own `.meta`. That pairing is what keeps `Transform.scale` from passing as
+ * a reader of a model's `scale`.
+ */
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SPECS = path.join('pipeline', 'src', 'project', 'importSettings.ts');
+
+/**
+ * Settings with no reader because the feature behind them is not built. Each
+ * entry says what is missing, so the list reads as work rather than permission.
+ */
+const DECLARED_GAPS = {
+ 'spine.defaultSkin': 'nothing applies it when a SpineAnimation is created from the asset',
+ 'dragonbones.defaultArmature': 'nothing applies it when a DragonBonesAnimation is created',
+ 'dragonbones.defaultAnimation': 'nothing applies it when a DragonBonesAnimation is created',
+};
+
+const source = readFileSync(path.join(ROOT, SPECS), 'utf8');
+
+/** type → the keys its schema declares, read off the one file that defines them. */
+function schemas() {
+ const arrays = new Map();
+ for (const match of source.matchAll(/const (\w+): ImporterFieldSpec\[\] = \[([\s\S]*?)\n\];/g)) {
+ arrays.set(match[1], [...match[2].matchAll(/key: '([^']+)'/g)].map((m) => m[1]));
+ }
+ const table = source.match(/IMPORTER_SCHEMAS: Record<string, ImporterFieldSpec\[\]> = \{([\s\S]*?)\n\};/);
+ const out = new Map();
+ for (const [, type, name] of (table?.[1] ?? '').matchAll(/(\w+): (\w+),/g)) {
+ out.set(type, arrays.get(name) ?? []);
+ }
+ return out;
+}
+
+// Every place a setting can be READ: the pipeline (cook + import), the SDK
+// (loaders) and the editor. The file that declares them is not a reader.
+const files = execFileSync('git', ['ls-files', 'pipeline/src', 'sdk/src', 'desktop/src', 'desktop/electron'],
+ { cwd: ROOT, encoding: 'utf8' }).split('\n').filter(Boolean);
+const readers = files
+ .filter((f) => /\.(ts|tsx)$/.test(f) && !f.includes('generated') && f !== SPECS.split(path.sep).join('/'))
+ .map((f) => readFileSync(path.join(ROOT, f), 'utf8'))
+ .filter((text) => /\bimporter\b/i.test(text))
+ .join('\n');
+
+const problems = [];
+const unusedGaps = new Set(Object.keys(DECLARED_GAPS));
+let declared = 0;
+for (const [type, keys] of schemas()) {
+ for (const key of keys) {
+ declared++;
+ const name = `${type}.${key}`;
+ // The leaf of a dotted path is what a reader names (`sliceBorder.left`).
+ const leaf = key.slice(key.lastIndexOf('.') + 1);
+ if (new RegExp(`[.>'"\\[]${leaf}\\b`).test(readers)) {
+ if (DECLARED_GAPS[name]) {
+ problems.push(`${name} is listed as a gap but something reads it — drop the entry`);
+ unusedGaps.delete(name);
+ }
+ continue;
+ }
+ unusedGaps.delete(name);
+ if (DECLARED_GAPS[name]) continue;
+ problems.push(`${name} has no reader — an import knob that does nothing`);
+ }
+}
+for (const name of unusedGaps) {
+ problems.push(`${name} is listed as a gap but is not a setting any more — drop the entry`);
+}
+
+if (problems.length) {
+ console.error('check-import-settings: a declared import setting has no reader.\n');
+ for (const p of problems) console.error(` ${p}`);
+ console.error('\nGive it one, remove the setting, or record it in DECLARED_GAPS with what is missing.');
+ process.exit(1);
+}
+
+console.log(`check-import-settings: ${declared} setting(s) across ${schemas().size} asset type(s)`
+ + ` all have a reader; ${Object.keys(DECLARED_GAPS).length} declared gap(s).`);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 71b387fc9..9c426108f 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -74,6 +74,7 @@ export const GATES = [
{ id: 'capabilities', run: 'node tools/check-capabilities.mjs' },
{ id: 'inspector-door', run: 'node tools/check-inspector-door.mjs' },
{ id: 'component-fields', run: 'node tools/check-component-fields.mjs' },
+ { id: 'import-settings', run: 'node tools/check-import-settings.mjs' },
{ id: 'dirty-source', run: 'node tools/check-dirty-source.mjs' },
{ id: 'path-sandbox', run: 'node tools/check-path-sandbox.mjs' },
{ id: 'key-codes', run: 'node tools/check-key-codes.mjs' },