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(assets): a declared import setting has a reader
esengine54535d26f9dc
diff --git a/desktop/src/document/openGraphAsset.ts b/desktop/src/document/openGraphAsset.tsindex 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): Promiawait 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.tsindex 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<voawait 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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?: Tilesawait 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsnew file mode 100644index 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.mjsindex 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' },