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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file Importing one model file into a project: the meshes, the images it carries, the materials, the clips and the prefab that
* assembles them.
*
* The editor imports a model dropped into the project, and the Cocos importer imports the models a Cocos project uses; both ask for the
* same thing, so the writing is here and each caller says only where the source is, where the products go and what to do just before
* a file is written (the editor journals it for undo).
*/
import { copyFile, mkdir, writeFile } from 'node:fs/promises';
import { existsSync, readFileSync } from 'node:fs';
import { createHash } from 'node:crypto';
import path from 'node:path';
import { isInsideRoot, resolveInside } from '../fs/pathSandbox';
import { adoptOrphan } from './assetMeta';
import {
encodeImportedMesh, assembleModelPrefab, materialProducts, applyLightmapUV, importedImageSettings,
generateLods, lodName, encodeGeneratedLod, orderHairTriangles, IMPORTED_MATERIAL_IMAGE_SLOTS,
type ImportedMesh, type ImportedNode, type SpecularMapReading,
} from './modelImport';
import { modelStem, readModelSource } from './readModelSource';
import { bakeMeshSdf, encodeMeshSdf } from './meshSdf';
import { bakeMeshCards } from './meshCards';
import { encodeMeshCards } from '../../../sdk/src/gi/cardFormat';
import { parseManifest } from '../project/format';
export interface ModelImportSettings {
scale: number;
lightmapUV: boolean;
specularMap: SpecularMapReading;
lodLevels: number;
lodMinTriangles: number;
characters: boolean;
springBones: boolean;
/** Bake what the dynamic GI reads of each mesh: its distance field (`<name>.esmeshsdf`) and its surface cards (`<name>.esmeshcards`). */
dynamicGI: boolean;
}
export interface ImportedModel {
/** Project-relative paths of everything written, in the order it was produced. */
products: string[];
/** What the source says that this engine cannot draw — reported, never dropped. */
warnings: string[];
/** The name the prefab and the products are stemmed from. */
stem: string;
/** Project-relative path of the prefab that assembles the model; absent when the file held no mesh. */
prefab?: string;
/** Each node of the source's hierarchy by its name, with the project-relative `.esmesh` of every primitive it draws. */
nodeMeshes: Map<string, string[]>;
/** The clips written, by the animation's own name (the product name without the `<stem>_` prefix). */
clips: Map<string, string>;
}
export interface ImportModelOptions {
/** The project root; every product lands inside it. */
root: string;
/** Project-relative folder for the products. */
destDir: string;
/** The model file. It may lie outside the project (a source being taken over), in which case it is only read. */
absSource: string;
/** Where the source's own relative uris resolve from, when it is not beside the source. */
originDir?: string;
/** Overrides for what the source's `.meta` says. */
settings?: Partial<ModelImportSettings>;
/** Called with the project-relative path just before a file is written. */
beforeWrite?(rel: string): Promise<void> | void;
}
const DEFAULTS: ModelImportSettings = {
scale: 1, lightmapUV: false, specularMap: 'color', lodLevels: 0, lodMinTriangles: 256, characters: false, springBones: false, dynamicGI: false,
};
/** What a model's `.meta` asks of the import; the schema's defaults where it is silent or unreadable. One read, because two would be two chances to disagree. */
export function modelSettings(absSource: string): ModelImportSettings {
try {
const meta = JSON.parse(readFileSync(`${absSource}.meta`, 'utf8')) as
{ importer?: { scale?: unknown; lightmapUV?: unknown; specularMap?: unknown;
lodLevels?: unknown; lodMinTriangles?: unknown; characterMaterials?: unknown; springBones?: unknown; dynamicGI?: unknown } };
const imp = meta.importer;
const scale = imp?.scale;
const levels = imp?.lodLevels;
const minTriangles = imp?.lodMinTriangles;
return {
scale: typeof scale === 'number' && scale > 0 ? scale : 1,
lightmapUV: imp?.lightmapUV === true,
specularMap: imp?.specularMap === 'orm' ? 'orm' : 'color',
lodLevels: typeof levels === 'number' ? Math.min(3, Math.max(0, Math.floor(levels))) : 0,
lodMinTriangles: typeof minTriangles === 'number' && minTriangles >= 0 ? minTriangles : 256,
characters: imp?.characterMaterials === 'auto',
springBones: imp?.springBones === 'auto',
dynamicGI: imp?.dynamicGI === true,
};
} catch {
return { ...DEFAULTS };
}
}
function collectNodeMeshes(nodes: ImportedNode[], meshFiles: string[], out: Map<string, string[]>): void {
for (const node of nodes) {
if (node.meshes.length > 0) {
const files = node.meshes.map((i) => meshFiles[i]).filter((f): f is string => f !== undefined);
out.set(node.name, [...(out.get(node.name) ?? []), ...files]);
}
collectNodeMeshes(node.children, meshFiles, out);
}
}
/**
* Import `absSource` into `destDir` of the project at `root`, writing the meshes, the images it carries, the materials, the clips and the
* prefab that assembles them.
*/
/** The project's units per metre (`features.physics.world3d.unitsPerMeter`), or the engine's 100 when it states none or is no project. */
function projectUnitsPerMeter(root: string): number {
try {
const file = path.join(root, 'project.esproject');
if (!existsSync(file)) return 100;
const text = readFileSync(file, 'utf8');
return parseManifest(JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text)).features?.physics?.world3d?.unitsPerMeter ?? 100;
} catch {
return 100;
}
}
export async function importModelFile(opts: ImportModelOptions): Promise<ImportedModel> {
const { root, destDir, absSource } = opts;
const absDir = destDir ? resolveInside(root, destDir, 'model destination') : path.resolve(root);
await mkdir(absDir, { recursive: true });
const sourceDir = opts.originDir ?? path.dirname(absSource);
const stem = modelStem(absSource);
const projectRef = (abs: string): string => path.relative(path.resolve(root), abs).split(path.sep).join('/');
const { scale, lightmapUV, specularMap, lodLevels, lodMinTriangles, characters, springBones, dynamicGI } = { ...modelSettings(absSource), ...opts.settings };
const { meshes, textures, nodes, animations, externalFiles, warnings } = await readModelSource(
new Uint8Array(readFileSync(absSource)), stem,
{
filename: absSource,
externalBuffers: (uri) => {
const abs = path.join(sourceDir, decodeURIComponent(uri));
return existsSync(abs) ? new Uint8Array(readFileSync(abs)) : null;
},
specularMap,
},
);
// A model exported with the path its artist had on their machine (`E:/props/road/wall.png`) names an image that is not there, and which sits
// beside the model in the project it was brought into: the name alone finds it, as a DCC tool's own import does.
const beside = new Map<string, string>();
for (const [i, uri] of externalFiles.entries()) {
if (existsSync(path.join(sourceDir, uri))) continue;
const name = uri.split(/[\\/]/).pop() ?? '';
if (name === '' || name === uri || !existsSync(path.join(sourceDir, name))) continue;
beside.set(uri, name);
externalFiles[i] = name;
}
if (beside.size > 0) {
for (const mesh of meshes) {
const material = mesh.material as Record<string, unknown> | undefined;
if (!material) continue;
for (const slot of IMPORTED_MATERIAL_IMAGE_SLOTS) {
const image = material[slot] as { external?: boolean; file?: string } | undefined;
const found = image?.external && image.file !== undefined ? beside.get(image.file) : undefined;
if (image && found !== undefined) image.file = found;
}
}
}
// Before anything is written, because it splits vertices: every product below is built from the mesh data this leaves behind.
if (lightmapUV) warnings.push(...applyLightmapUV(meshes));
// After it, because a level is a collapse of the mesh as it will be written.
warnings.push(...await generateLods(meshes, { levels: lodLevels, minTriangles: lodMinTriangles }));
if (characters) orderHairTriangles(meshes);
// 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>>(
[...importedImageSettings(meshes)].map(([file, { settings }]) => [file, { ...settings }]));
const products: string[] = [];
const write = async (name: string, bytes: Uint8Array | string): Promise<string> => {
const rel = destDir ? `${destDir}/${name}` : name;
await opts.beforeWrite?.(rel);
await writeFile(path.join(absDir, name), bytes);
// keeps the uuid a re-import must not change
await adoptOrphan(path.join(absDir, name), imageSettings.get(name));
products.push(rel);
return rel;
};
// A file already in the project is left where it lies; one from outside comes WITH the model, at the same relative path. That is what
// keeps the copied .gltf pointing at its own .bin, so re-importing it still works.
const externalRefs = new Map<string, string>();
const external = (uri: string): string => externalRefs.get(uri) ?? uri;
for (const uri of externalFiles) {
const abs = path.join(sourceDir, uri);
if (!existsSync(abs)) continue;
if (isInsideRoot(root, abs)) {
// Minted only if it has no `.meta` yet: a data map must not arrive as colour.
await adoptOrphan(abs, imageSettings.get(uri));
externalRefs.set(uri, projectRef(abs));
continue;
}
// A uri that reaches outside the model's own folder cannot keep its shape in the project: it lands beside the model, and the
// source's link to it stays broken — said out loud rather than silently rewritten.
const keepsShape = isInsideRoot(absDir, path.resolve(absDir, uri));
if (!keepsShape) warnings.push(`${uri} came from outside the model's folder; the copy is beside it`);
const name = keepsShape ? uri : path.basename(uri);
const rel = destDir ? `${destDir}/${name}` : name;
const absDest = path.join(absDir, name);
await opts.beforeWrite?.(rel);
await mkdir(path.dirname(absDest), { recursive: true });
await copyFile(abs, absDest);
await adoptOrphan(absDest, imageSettings.get(uri));
products.push(rel);
externalRefs.set(uri, rel);
}
// A texture the model names whose file is not there is left off the material, and said: a reference that resolves to nothing fails to
// load every time the model is used, and the material is no better for it (a model exported from a tool that kept its own paths names a
// `.psd` the project never had).
const lost = new Set(externalFiles.filter((uri) => !externalRefs.has(uri) && !existsSync(path.join(sourceDir, uri))));
if (lost.size > 0) {
for (const mesh of meshes) {
const material = mesh.material as Record<string, unknown> | undefined;
if (!material) continue;
for (const slot of IMPORTED_MATERIAL_IMAGE_SLOTS) {
const image = material[slot] as { external?: boolean; file?: string } | undefined;
if (image?.external && image.file !== undefined && lost.has(image.file)) delete material[slot];
}
}
for (const uri of lost) warnings.push(`${uri} is not there; the material is left without that texture`);
}
const meshFiles: string[] = [];
const meshNames = new Map<ImportedMesh, string>();
const geometryProducts = new Map<string, string>();
for (const mesh of meshes) {
const bytes = encodeImportedMesh(mesh);
const levels = (mesh.lods ?? []).map(encodeGeneratedLod);
// Exporters can repeat a mesh definition for every placed grid cell. Distinct
// paths give identical geometry distinct GPU handles and prevent instancing.
// Compare the complete encoded geometry (UVs, skin/morph data and every LOD),
// not its name, bounds or vertex count. Per-instance bindings stay on the node.
const hash = createHash('sha256');
for (const part of [bytes, ...levels]) {
const length = Buffer.allocUnsafe(4);
length.writeUInt32LE(part.byteLength);
hash.update(length).update(part);
}
const signature = hash.digest('hex');
const previous = geometryProducts.get(signature);
const name = previous ?? mesh.name;
geometryProducts.set(signature, name);
meshNames.set(mesh, name);
meshFiles.push(destDir ? `${destDir}/${name}.esmesh` : `${name}.esmesh`);
// Keep old standalone references and UUIDs working when reimporting a model
// first imported before sharing was supported. New imports write only the
// canonical product; the prefab always references it, including its LODs.
if (previous === undefined || existsSync(path.join(absDir, `${mesh.name}.esmesh`))) {
await write(`${mesh.name}.esmesh`, bytes);
for (const [i, lodBytes] of levels.entries()) {
await write(`${lodName(mesh, i + 1)}.esmesh`, lodBytes);
}
// A skinned or morphing mesh moves its surface: a field baked from the bind pose would be a wrong wall.
if (dynamicGI && !mesh.data.inverseBindMatrices && !mesh.data.morph) {
const field = bakeMeshSdf(mesh.data, { cellSize: (0.1 * projectUnitsPerMeter(root)) / Math.max(scale, 1e-6) });
if (field) await write(`${mesh.name}.esmeshsdf`, encodeMeshSdf(field));
const m = mesh.material;
const cards = bakeMeshCards(mesh.data, {
cell: (0.25 * projectUnitsPerMeter(root)) / Math.max(scale, 1e-6),
baseColor: m ? [m.baseColor[0], m.baseColor[1], m.baseColor[2]] : undefined, emissive: m?.emissive,
});
if (cards) await write(`${mesh.name}.esmeshcards`, encodeMeshCards(cards));
}
}
}
for (const texture of textures) await write(texture.name, texture.bytes);
const refs = { prefix: destDir ? `${destDir}/` : '', external, characters, springBones, meshNames };
for (const material of materialProducts(meshes, stem, refs)) {
await write(`${material.name}.esmaterial`, `${JSON.stringify(material.data, null, 2)}\n`);
}
let firstClip: string | undefined;
const clips = new Map<string, string>();
for (const animation of animations) {
const rel = await write(`${animation.name}.estimeline`, `${JSON.stringify(animation.document, null, 2)}\n`);
firstClip ??= rel;
clips.set(animation.name.startsWith(`${stem}_`) ? animation.name.slice(stem.length + 1) : animation.name, rel);
}
let prefabRef: string | undefined;
if (meshes.length > 0) {
const prefab = assembleModelPrefab(stem, meshes, { refs, nodes, scale, timeline: firstClip });
prefabRef = await write(`${stem}.esprefab`, `${JSON.stringify(prefab, null, 2)}\n`);
// A model is authored in metres; what it measures in this project depends on the project's units per metre (Project Settings →
// Physics → 3D: 100 unless set, 1 in a metre project). Under 8 cm in real terms, it is almost always a model whose Scale does not
// match the project — 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))));
const unitsPerMeter = projectUnitsPerMeter(root);
const metres = (extent * scale) / unitsPerMeter;
if (metres < 0.08 && scale !== unitsPerMeter) {
warnings.push(`the model is ${metres.toFixed(3)} m across in this project (${unitsPerMeter} units a metre) — `
+ `set Scale to ${unitsPerMeter} in its import settings and reimport if it is a real-world size`);
}
}
const nodeMeshes = new Map<string, string[]>();
collectNodeMeshes(nodes, meshFiles, nodeMeshes);
return { products, warnings, stem, prefab: prefabRef, nodeMeshes, clips };
}