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): what a model asks for, and what it loses
esenginedc4641283a91
diff --git a/desktop/electron/importModel.ts b/desktop/electron/importModel.tsindex 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: striawait 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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');}