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): what a model asks for, and what it loses

esenginedc4641283a91
diff --git a/desktop/electron/importModel.ts b/desktop/electron/importModel.ts
index 58dca2213..ed3a3ab4d 100644
--- a/desktop/electron/importModel.ts
+++ b/desktop/electron/importModel.ts
@@ -57,12 +57,22 @@ export async function importModel(root: string, destDir: string, absSource: stri
},
);
+ // 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>>();
+ for (const mesh of meshes) {
+ for (const image of [mesh.material?.baseColorTexture, mesh.material?.normalTexture]) {
+ if (image?.settings) imageSettings.set(image.file, { ...image.settings });
+ }
+ }
+
const products: string[] = [];
const write = async (name: string, bytes: Uint8Array | string): Promise<string> => {
const rel = destDir ? `${destDir}/${name}` : name;
await capture(rel, 'write');
await writeFile(path.join(absDir, name), bytes);
- await adoptOrphan(path.join(absDir, name)); // keeps the uuid a re-import must not change
+ // keeps the uuid a re-import must not change
+ await adoptOrphan(path.join(absDir, name), imageSettings.get(name));
products.push(rel);
return rel;
};
@@ -92,7 +102,7 @@ export async function importModel(root: string, destDir: string, absSource: stri
await capture(rel, 'write');
await mkdir(path.dirname(absDest), { recursive: true });
await copyFile(abs, absDest);
- await adoptOrphan(absDest);
+ await adoptOrphan(absDest, imageSettings.get(uri));
products.push(rel);
externalRefs.set(uri, rel);
}
diff --git a/desktop/tests/gltf-import.test.ts b/desktop/tests/gltf-import.test.ts
index 3aa23d197..948e2597d 100644
--- a/desktop/tests/gltf-import.test.ts
+++ b/desktop/tests/gltf-import.test.ts
@@ -248,6 +248,50 @@ describe('glTF material import', () => {
expect(meshes[0]!.data.aabbMax).toEqual([9, 9, 9]);
});
+ it("carries a sampler's filter and wrap as import settings", () => {
+ const doc = withInlineImage();
+ doc.samplers = [{ magFilter: 9728, wrapS: 33071, wrapT: 33071 }];
+ (doc.textures as { sampler?: number }[])[0]!.sampler = 0;
+ const { meshes, warnings } = importGltfMeshes(gltf(doc), 'model');
+ expect(warnings).toEqual([]);
+ expect(meshes[0]!.material?.baseColorTexture?.settings)
+ .toEqual({ filterMode: 'nearest', wrapMode: 'clamp' });
+ });
+
+ it('says which wrap it kept when the source addresses u and v differently', () => {
+ const doc = withInlineImage();
+ doc.samplers = [{ wrapS: 33071, wrapT: 10497 }];
+ (doc.textures as { sampler?: number }[])[0]!.sampler = 0;
+ const { meshes, warnings } = importGltfMeshes(gltf(doc), 'model');
+ expect(warnings.join('\n')).toContain('wrapS and wrapT differ');
+ expect(meshes[0]!.material?.baseColorTexture?.settings?.wrapMode).toBe('clamp');
+ });
+
+ it('reports deformation it cannot carry: skins, morph targets, animations', () => {
+ const doc = {
+ ...withInlineImage(),
+ skins: [{}], animations: [{}],
+ nodes: [{ mesh: 0, skin: 0 }], scenes: [{ nodes: [0] }], scene: 0,
+ };
+ const { warnings } = importGltfMeshes(gltf(doc, [{
+ attributes: { POSITION: 0, TEXCOORD_0: 1, JOINTS_0: 1 }, indices: 2, material: 0, mode: 4,
+ targets: [{}, {}],
+ }]), 'model');
+ const line = warnings.join('\n');
+ expect(line).toContain('2 morph target(s) not imported');
+ expect(line).toContain('skinning is not imported');
+ expect(line).toContain('1 skin(s) not imported');
+ expect(line).toContain('1 animation(s) not imported');
+ });
+
+ it('reports a uv rewrite it does not apply', () => {
+ const doc = withInlineImage();
+ (doc.materials as { pbrMetallicRoughness: { baseColorTexture: Record<string, unknown> } }[])[0]!
+ .pbrMetallicRoughness.baseColorTexture.extensions = { KHR_texture_transform: { scale: [2, 2] } };
+ const { warnings } = importGltfMeshes(gltf(doc), 'model');
+ expect(warnings.join('\n')).toContain('KHR_texture_transform not imported');
+ });
+
it("flips V, because glTF's uv origin is the image's top-left", () => {
const { meshes } = importGltfMeshes(gltf(withInlineImage()), 'model');
expect(texCoords(meshes[0]!)).toEqual([0, 1, 1, 1, 0, 0]);
diff --git a/desktop/tests/import-model.test.ts b/desktop/tests/import-model.test.ts
index b48b9b5fa..152b44d52 100644
--- a/desktop/tests/import-model.test.ts
+++ b/desktop/tests/import-model.test.ts
@@ -169,6 +169,24 @@ describe('importing a model', () => {
expect(existsSync(path.join(root, 'assets/models/robot_skin.png'))).toBe(false);
});
+ it("mints an image's .meta with the settings its sampler asked for", async () => {
+ writeFileSync(path.join(outside, 'skin.png'), 'PNG');
+ const doc = JSON.parse(gltf('skin.png')) as Record<string, unknown>;
+ doc.samplers = [{ magFilter: 9728, wrapS: 33071, wrapT: 33071 }];
+ doc.textures = [{ source: 0, sampler: 0 }];
+ const src = path.join(outside, 'robot.gltf');
+ writeFileSync(src, JSON.stringify(doc));
+ await importAssets(root, 'assets/models', [src]);
+
+ const meta = JSON.parse(
+ readFileSync(path.join(root, 'assets/models/skin.png.meta'), 'utf8'),
+ ) as { importer: { filterMode: string; wrapMode: string; maxSize: number } };
+ expect(meta.importer.filterMode).toBe('nearest');
+ expect(meta.importer.wrapMode).toBe('clamp');
+ // The rest of the type's defaults survive — this overrides, it does not replace.
+ expect(meta.importer.maxSize).toBe(2048);
+ });
+
it('keeps a product’s identity across a re-import', async () => {
const abs = path.join(root, 'assets/models/robot.gltf');
mkdirSync(path.dirname(abs), { recursive: true });
diff --git a/pipeline/src/assets/assetMeta.ts b/pipeline/src/assets/assetMeta.ts
index f4d1a2b82..e6124f707 100644
--- a/pipeline/src/assets/assetMeta.ts
+++ b/pipeline/src/assets/assetMeta.ts
@@ -57,15 +57,22 @@ export async function metaTypeForFile(absFile: string): Promise<string | null> {
return metaTypeForContent(absFile, await readHead(absFile, CONTENT_SNIFF_BYTES));
}
-/** A fresh `.meta` document for an asset of `type`. */
-export function mintMeta(type: string): Record<string, unknown> {
- return { uuid: randomUUID(), version: META_VERSION, type, importer: importerDefaults(type) };
+/** A fresh `.meta` document for an asset of `type`. `importer` overrides the
+ * type's defaults — what an importing SOURCE asked for (a glTF sampler's filter
+ * and wrap), which is only ever the initial value; the file owns it after that. */
+export function mintMeta(type: string, importer?: Record<string, unknown>): Record<string, unknown> {
+ return {
+ uuid: randomUUID(), version: META_VERSION, type,
+ importer: { ...importerDefaults(type), ...importer },
+ };
}
/** Write `<absFile>.meta` for @p absFile. Pass `type` to override the
* extension-derived one (the create door knows its type explicitly). */
-export async function writeMeta(absFile: string, type: string): Promise<void> {
- await writeFile(absFile + META_EXT, JSON.stringify(mintMeta(type), null, 2) + '\n', 'utf8');
+export async function writeMeta(absFile: string, type: string,
+ importer?: Record<string, unknown>): Promise<void> {
+ await writeFile(absFile + META_EXT,
+ JSON.stringify(mintMeta(type, importer), null, 2) + '\n', 'utf8');
}
/**
@@ -73,10 +80,11 @@ export async function writeMeta(absFile: string, type: string): Promise<void> {
* to a known asset type. Returns what happened, so callers can count adoptions /
* skip unknowns without re-deriving the checks.
*/
-export async function adoptOrphan(absFile: string): Promise<'adopted' | 'has-meta' | 'unknown-type'> {
+export async function adoptOrphan(absFile: string,
+ importer?: Record<string, unknown>): Promise<'adopted' | 'has-meta' | 'unknown-type'> {
if (existsSync(absFile + META_EXT)) return 'has-meta';
const type = await metaTypeForFile(absFile);
if (!type) return 'unknown-type';
- await writeMeta(absFile, type);
+ await writeMeta(absFile, type, importer);
return 'adopted';
}
diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.ts
index 87ecc4ca6..3bd9256eb 100644
--- a/pipeline/src/assets/gltfImport.ts
+++ b/pipeline/src/assets/gltfImport.ts
@@ -32,6 +32,9 @@ export interface ImportedImageRef {
file: string;
/** True for a uri the glTF points at — an existing file is referenced, never copied. */
external: boolean;
+ /** Import settings the source's sampler asks for, in the engine's own words.
+ * Absent where the glTF names no sampler (its defaults are the engine's). */
+ settings?: { filterMode?: 'nearest' | 'linear'; wrapMode?: 'repeat' | 'clamp' | 'mirror' };
}
/**
@@ -96,7 +99,11 @@ const TYPE_COMPONENTS: Record<string, number> = {
SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16,
};
-interface GltfTextureRef { index: number; texCoord?: number }
+interface GltfTextureRef {
+ index: number; texCoord?: number;
+ /** KHR_texture_transform and friends: a uv rewrite this importer does not do. */
+ extensions?: Record<string, unknown>;
+}
/** Per-spec sparse storage: a base of zeroes (or a view) with some values replaced. */
interface GltfSparse {
@@ -116,6 +123,8 @@ interface GltfJson {
meshes?: { name?: string; primitives: {
attributes: Record<string, number>; indices?: number; mode?: number; material?: number;
extensions?: Record<string, unknown>;
+ /** Morph targets — shapes the runtime blends between; not imported. */
+ targets?: unknown[];
}[] }[];
materials?: {
name?: string;
@@ -131,11 +140,14 @@ interface GltfJson {
extensions?: Record<string, unknown>;
}[];
textures?: { source?: number; sampler?: number }[];
+ samplers?: { magFilter?: number; minFilter?: number; wrapS?: number; wrapT?: number }[];
images?: { uri?: string; bufferView?: number; mimeType?: string; name?: string }[];
nodes?: {
- name?: string; children?: number[]; mesh?: number;
+ name?: string; children?: number[]; mesh?: number; skin?: number;
matrix?: number[]; translation?: number[]; rotation?: number[]; scale?: number[];
}[];
+ skins?: unknown[];
+ animations?: unknown[];
scenes?: { nodes?: number[] }[];
scene?: number;
}
@@ -292,15 +304,51 @@ interface MaterialContext {
warnings: string[];
}
+const GL_NEAREST = 9728;
+const WRAP_MODE: Record<number, 'repeat' | 'clamp' | 'mirror'> = {
+ 10497: 'repeat', 33071: 'clamp', 33648: 'mirror',
+};
+
+/**
+ * A glTF sampler as the engine's own import settings. Only what it states is
+ * carried: an absent field means the glTF asked for nothing, and the engine's
+ * default is as good an answer as any.
+ */
+function readSampler(ctx: MaterialContext, index: number | undefined,
+ label: string): ImportedImageRef['settings'] {
+ const sampler = index !== undefined ? ctx.json.samplers?.[index] : undefined;
+ if (!sampler) return undefined;
+ const out: NonNullable<ImportedImageRef['settings']> = {};
+ if (sampler.magFilter !== undefined) {
+ out.filterMode = sampler.magFilter === GL_NEAREST ? 'nearest' : 'linear';
+ }
+ // One wrap mode per texture here; a source that addresses u and v differently
+ // has to lose one of them, so it says which rather than picking silently.
+ if (sampler.wrapS !== undefined && sampler.wrapT !== undefined
+ && sampler.wrapS !== sampler.wrapT) {
+ ctx.warnings.push(`${label}: wrapS and wrapT differ; using wrapS`);
+ }
+ const wrap = WRAP_MODE[sampler.wrapS ?? sampler.wrapT ?? 0];
+ if (wrap) out.wrapMode = wrap;
+ return Object.keys(out).length > 0 ? out : undefined;
+}
+
/** Resolves a glTF texture index to the file a Mesh2D will sample, extracting inline images. */
function readTexture(ctx: MaterialContext, cache: Map<number, ImportedImageRef | null>,
ref: GltfTextureRef, label: string): ImportedImageRef | null {
if (ref.texCoord) ctx.warnings.push(`${label}: TEXCOORD_${ref.texCoord} is not imported (one UV set)`);
+ for (const name of Object.keys(ref.extensions ?? {})) {
+ ctx.warnings.push(`${label}: ${name} not imported (uvs are used as authored)`);
+ }
const cached = cache.get(ref.index);
if (cached !== undefined) return cached;
const resolve = (): ImportedImageRef | null => {
- const source = ctx.json.textures?.[ref.index]?.source;
+ const texture = ctx.json.textures?.[ref.index];
+ const settings = readSampler(ctx, texture?.sampler, label);
+ const withSettings = (r: ImportedImageRef): ImportedImageRef =>
+ settings ? { ...r, settings } : r;
+ const source = texture?.source;
const image = source !== undefined ? ctx.json.images?.[source] : undefined;
if (!image || source === undefined) {
ctx.warnings.push(`${label}: texture ${ref.index} has no image — skipped`);
@@ -309,7 +357,7 @@ function readTexture(ctx: MaterialContext, cache: Map<number, ImportedImageRef |
// An image already on disk is REFERENCED, never copied: a second copy is
// a second thing to keep in sync with the file the artist edits.
if (image.uri && !image.uri.startsWith('data:')) {
- return { file: decodeURIComponent(image.uri), external: true };
+ return withSettings({ file: decodeURIComponent(image.uri), external: true });
}
const bytes = image.uri
? decodeDataUri(image.uri)
@@ -328,7 +376,7 @@ function readTexture(ctx: MaterialContext, cache: Map<number, ImportedImageRef |
}
const name = `${ctx.stem}_${source}${ext}`;
if (!ctx.textures.some(t => t.name === name)) ctx.textures.push({ name, bytes });
- return { file: name, external: false };
+ return withSettings({ file: name, external: false });
};
const resolved = resolve();
@@ -544,6 +592,14 @@ export function importGltfMeshes(
for (const name of Object.keys(prim.extensions ?? {})) {
if (!(name in COMPRESSED_GEOMETRY)) warnings.push(`${label}: ${name} not imported`);
}
+ // Deformation is the difference between a model that moves and one
+ // that does not, so it is never dropped in silence.
+ if (prim.targets?.length) {
+ warnings.push(`${label}: ${prim.targets.length} morph target(s) not imported`);
+ }
+ if (prim.attributes.JOINTS_0 !== undefined) {
+ warnings.push(`${label}: skinning is not imported — the mesh comes in static`);
+ }
const posIndex = prim.attributes.POSITION;
if (posIndex === undefined) {
warnings.push(`${label}: no POSITION — skipped`);
@@ -634,6 +690,12 @@ export function importGltfMeshes(
});
});
+ // A rigged, animated source arrives as still geometry; that is a property of
+ // the import worth stating once for the file rather than per primitive.
+ if (json.skins?.length) warnings.push(`${json.skins.length} skin(s) not imported`);
+ if (json.animations?.length) {
+ warnings.push(`${json.animations.length} animation(s) not imported`);
+ }
if (meshes.length === 0 && warnings.length === 0) {
warnings.push('no triangle geometry found');
}