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 What a model becomes, and how its products go together — the half of
* the import that has nothing to do with the format it arrived in.
*
* A reader (glTF, FBX) produces a {@link ModelImportResult}; everything
* below that — the `.esmesh` bytes, the `.esmaterial` documents, the
* `.estimeline` tracks and the `.esprefab` that assembles them — is
* written here, once. A second format that wrote its own would be a
* second set of rules for what a model IS in this engine.
*/
import {
MeshChannel, MeshChannelType, encodeMesh, unwrapLightmapUV, PREFAB_FORMAT_VERSION, TIMELINE_FORMAT_VERSION,
MATERIAL_FORMAT_VERSION, BlendMode, CullMode,
type MeshData, type MaterialAssetData, type PrefabData, type PrefabEntityData,
type PrefabComponentData as ComponentData,
} from 'esengine';
import { canSimplify, simplifyMesh, type SimplifierFlag } from './meshSimplify';
import { SPARSE_LIGHTMAP_UV, OVERLAPPING_LIGHTMAP_UV } from '../../../sdk/src/lightmap/atlas';
import type { CompoundColliderPart3D } from 'esengine/physics3d';
/** One primitive's worth of geometry, named for the file it will be written to. */
export interface ImportedMesh {
/** `<file stem>` for a single primitive, `<stem>_<mesh>_<primitive>` otherwise. */
name: string;
data: MeshData;
vertexCount: number;
triangleCount: number;
/** The primitive's baseColor, absent when it names no material. */
material?: ImportedMaterial;
/** Source node indices of the joints its `Joints` channel indexes, in order.
* Absent for geometry nothing skins. */
skinJoints?: number[];
/** The weight each morph target starts at, where the source states them. */
morphWeights?: number[];
/** Cheaper stand-ins, finest first, written as `<name>_lod<n>.esmesh` (@ref generateLods). */
lods?: GeneratedLod[];
}
/** One cheaper level of a mesh, and the screen height below which it replaces the one above. */
export interface GeneratedLod {
data: MeshData;
triangleCount: number;
/** Fraction of the viewport height — the unit a `LODGroup` threshold is in. */
size: number;
}
/** Where a material's image comes from: a product this import writes, or a file already on disk. */
export interface ImportedImageRef {
/** Product name (no directory) when written, else the source's own uri. */
file: string;
/** True for a uri the source 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 source names no sampler (its defaults are the engine's). */
settings?: {
filterMode?: 'nearest' | 'linear'; wrapMode?: 'repeat' | 'clamp' | 'mirror'; sRGB?: boolean; mipCoverage?: number;
};
}
/**
* A material, split by what can carry it: baseColor is `texture(uv) *
* vertexColor * tint`, which a MeshRenderer's own fields say, and the shading around
* it becomes an `.esmaterial` (@ref materialProducts). What neither can express
* is reported, not dropped.
*/
export interface ImportedMaterial {
/** The source's own material index — what its product is named after. */
index: number;
name: string;
/** The tint multiplied into the vertex colors. */
baseColor: [number, number, number, number];
/** KHR_materials_unlit: base colour and alpha only, independent of lighting. */
unlit?: boolean;
blendMode?: BlendMode;
baseColorTexture?: ImportedImageRef;
/** Tangent-space normal map, read against the mesh's own tangent frame where it has one (see meshTangents.ts). */
normalTexture?: ImportedImageRef;
/** Tangent-space X/Y scale, applied before renormalizing the sampled normal. */
normalScale?: number;
/** Light the surface makes, unaffected by the scene's lights. */
emissive?: [number, number, number];
emissiveTexture?: ImportedImageRef;
/** Ambient occlusion in the map's red channel, scaled by @ref occlusionStrength. */
occlusionTexture?: ImportedImageRef;
/** Hair's strand-direction and highlight-shift maps, which glTF has no slot for: a material states them in its extras (`flow_map`, `shift_map`, paths from the model). */
flowTexture?: ImportedImageRef;
shiftTexture?: ImportedImageRef;
/** How far in from the cutoff a hair card's edge fades (`extras.suggested_tipSoftness`). */
tipSoftness?: number;
occlusionStrength?: number;
/** Where every map is read: the UV scaled, turned (radians) and moved — glTF's KHR_texture_transform, the Model shader's
* Tiling, Offset and Rotation — in the ENGINE's uv (V up), not the source's. Absent when the maps are read where the
* mesh's UVs say. */
uvTransform?: { tiling: [number, number]; offset: [number, number]; rotation: number };
/** How metal and how rough the surface is, as constants. */
metallic?: number;
roughness?: number;
/** glTF's packing: roughness in green, metal in blue, multiplying the factors. */
metallicRoughnessTexture?: ImportedImageRef;
/** Legacy glTF specular/glossiness: diffuse uses baseColor; specular is linear RGB and gloss is linear alpha. */
specularGlossiness?: { specular: [number, number, number]; glossiness: number };
specularGlossinessTexture?: ImportedImageRef;
/**
* Metalness, roughness and occlusion as the source wrote them: a separate image each, the value in its red channel (roughness
* inverted when the source gave glossiness). Image preparation packs them into the one map above, glTF's way, and removes this.
*/
separateMaps?: {
metalness?: ImportedImageRef; roughness?: ImportedImageRef; roughnessIsGlossiness?: boolean; occlusion?: ImportedImageRef;
};
/**
* What the surface has beyond a metal/rough pair, one field per glTF extension that says it — the values are
* the extension's own factors, absent where the source says nothing (the engine's defaults are glTF's).
*/
/** KHR_materials_clearcoat: a smooth lacquer over the surface. */
clearcoat?: number;
clearcoatRoughness?: number;
/** KHR_materials_sheen: the soft rim light of cloth. */
sheenColor?: [number, number, number];
sheenRoughness?: number;
/** KHR_materials_anisotropy: a highlight stretched along grooves, turned by `anisotropyRotation` radians. */
anisotropy?: number;
anisotropyRotation?: number;
/** KHR_materials_ior and KHR_materials_specular's factor. */
ior?: number;
specular?: number;
/** KHR_materials_diffuse_transmission: light that scatters through a thin surface, tinted. */
translucency?: number;
translucencyColor?: [number, number, number];
/** KHR_materials_transmission, and KHR_materials_volume's thickness and tint. */
transmission?: number;
thickness?: number;
attenuationColor?: [number, number, number];
/** KHR_materials_iridescence: a thin film over the surface. */
iridescence?: number;
iridescenceIor?: number;
iridescenceThickness?: number;
/** A fragment below this alpha is discarded. */
alphaCutoff?: number;
/** Drawn without blending, and taking part in depth. */
opaque: boolean;
/** Back faces are not drawn. */
cullBackfaces: boolean;
}
/** A material product: the shading a MeshRenderer's own fields cannot say. */
export interface ImportedMaterialAsset {
/** `<stem>_m<material index>` — stable across re-imports, so overrides keep matching. */
name: string;
/** The `.esmaterial` document. */
data: MaterialAssetData;
/** Every image it references, so the caller can carry the sampler settings over. */
images: ImportedImageRef[];
}
/** Every image reference carried by an imported material, shared by preparation, copying and missing-file cleanup. */
export const IMPORTED_MATERIAL_IMAGE_SLOTS = [
'baseColorTexture', 'normalTexture', 'emissiveTexture', 'occlusionTexture',
'metallicRoughnessTexture', 'specularGlossinessTexture', 'flowTexture', 'shiftTexture',
] as const;
/** An image the source carries inline, to be written beside the meshes. */
export interface ImportedTexture {
/** `<stem>_<image index>.<ext>` — named for the source, since an inline image has no name. */
name: string;
bytes: Uint8Array;
}
/**
* A node of the source's own hierarchy: where its geometry sits, and what hangs
* off it. Without this every primitive of a model lands on the origin.
*/
export interface ImportedNode {
/** The node's own index in the source, so a re-import addresses the same entity. */
index: number;
name: string;
translation: [number, number, number];
/** Quaternion in (x, y, z, w) order — the same components a Transform holds. */
rotation: [number, number, number, number];
scale: [number, number, number];
/** Indices into @ref ModelImportResult.meshes; one node can draw several primitives. */
meshes: number[];
children: ImportedNode[];
/** A light the node carries, shining along its local -Z. */
light?: ImportedLight;
/** A camera the node carries, looking along its local -Z with +Y up. */
camera?: ImportedCamera;
/** Hierarchical visual visibility, independent of simulation and cameras. */
visibility?: boolean;
particle?: { emitter: Record<string, unknown>; units: Record<string, unknown>; texture?: ImportedImageRef };
billboard?: 0 | 1;
physics?: { bodyType: 0 | 1 | 2; mass: number; isSensor: boolean;
parts: CompoundColliderPart3D[]; triangleMesh?: number; settings?: Record<string, unknown> };
/** This node is the root of a spring chain: the bones below it are the strand. Lengths are the model's metres. */
springBone?: ImportedSpringBone;
/** Colliders this node hosts, each an entity of its own below it so one bone can carry several. */
springColliders?: ImportedSpringCollider[];
}
/** What a source states about a spring chain; a field it leaves out keeps the component's default (or the name rule's, for a chain found by name). */
export interface ImportedSpringBone {
stiffness?: number;
drag?: number;
gravity?: [number, number, number];
radius?: number;
endLength?: number;
/** Prefab entity ids of the colliders the chain is kept out of; left out, every collider in the model. */
colliders?: string[];
}
/** A sphere (`shape` 0) or capsule (1) placed relative to its host node: `offset` and `rotation` (x, y, z, w) put its centre and its Y axis. */
export interface ImportedSpringCollider {
shape: 0 | 1;
radius: number;
height?: number;
offset?: [number, number, number];
rotation?: [number, number, number, number];
}
/**
* A light as a source states it. Intensity is carried over as it is, the way
* Godot's glTF import does: the engine's is a multiplier with no photometric unit.
*/
export interface ImportedLight {
type: 'point' | 'directional' | 'spot';
color: [number, number, number];
intensity: number;
/** Where it stops reaching, in metres; absent is unbounded. */
range?: number;
/** Full cone angles in degrees. */
innerAngle?: number;
outerAngle?: number;
}
export interface ImportedCamera {
projection: 'perspective' | 'orthographic';
/** Vertical field of view in degrees. */
yfov?: number;
/** Half the visible height, for an orthographic camera. */
halfHeight?: number;
near: number;
far?: number;
aspect?: number;
}
/** One of the source's animations as the `.estimeline` document it will be written to. */
export interface ImportedAnimation {
/** `<stem>_<animation name>` — named for the file it will be written to. */
name: string;
document: Record<string, unknown>;
}
/**
* What a source's specular map means. `color` is what the name says — a tint on the
* highlight, which the engine's metal/rough model has no slot for. `orm` is the
* packing Falcor-era scenes (Bistro, Sun Temple) store there: occlusion in red,
* roughness in green, metalness in blue.
*/
export type SpecularMapReading = 'color' | 'orm';
/** What a reader hands over: one file's worth of model, in the engine's terms. */
export interface ModelImportResult {
meshes: ImportedMesh[];
/** Images extracted from the file itself; external ones stay where they are. */
textures: ImportedTexture[];
/** Every uri the source points OUT to (buffers and images), in file order.
* Bringing a model into a project means bringing these with it. */
externalFiles: string[];
/** The scene's node roots. Empty for a file with no nodes, whose meshes then sit flat. */
nodes: ImportedNode[];
/** The file's animations, each addressing nodes by their path under the prefab. */
animations: ImportedAnimation[];
/** What was skipped and why — a silent drop is how half a model goes missing. */
warnings: string[];
}
export type Trs = Pick<ImportedNode, 'translation' | 'rotation' | 'scale'>;
/**
* Make sibling names unique. An animation channel addresses its node by the path
* of names from the root, so two siblings called "Arm" would leave a track
* driving whichever the walk reached first — the wrong half of the model. Both
* formats allow the duplicate, so the import settles it and the products agree.
*/
export function disambiguateNodes(nodes: ImportedNode[]): void {
const used = new Set<string>();
for (const node of nodes) {
if (used.has(node.name)) node.name = `${node.name}_${node.index}`;
used.add(node.name);
disambiguateNodes(node.children);
}
}
/**
* Each node's path of names from the prefab root, matching what
* {@link assembleModelPrefab} builds: a lone root node IS the prefab root (empty
* path), while several roots hang under a holder and so carry their own name.
*/
export function nodeChildPaths(nodes: ImportedNode[]): Map<number, string> {
const paths = new Map<number, string>();
const walk = (node: ImportedNode, prefix: string): void => {
const path = prefix ? `${prefix}/${node.name}` : node.name;
paths.set(node.index, path);
for (const child of node.children) walk(child, path);
};
if (nodes.length === 1 && nodes[0]) {
paths.set(nodes[0].index, '');
for (const child of nodes[0].children) walk(child, '');
} else {
for (const node of nodes) walk(node, '');
}
return paths;
}
/** A node's own name, for the track label. */
export function nodeNameFor(nodes: ImportedNode[], index: number): string {
for (const node of nodes) {
if (node.index === index) return node.name;
const hit = nodeNameFor(node.children, index);
if (hit) return hit;
}
return '';
}
/* -- Animation ---------------------------------------------------------- */
export interface OutKeyframe {
time: number; value: number; inTangent: number; outTangent: number; interpolation: string;
}
/** Which Transform channels a source's animation path writes, in component order. */
export const ANIMATED_PATHS: Record<string, { property: string; channels: string[] }> = {
translation: { property: 'position', channels: ['position.x', 'position.y', 'position.z'] },
scale: { property: 'scale', channels: ['scale.x', 'scale.y', 'scale.z'] },
// A rotation is stored as (x, y, z, w) — the components, in that order.
rotation: { property: 'rotation', channels: ['rotation.x', 'rotation.y', 'rotation.z', 'rotation.w'] },
};
/**
* A quaternion and its negation are the same rotation, and interpolating the
* four numbers takes the LONG way round whenever consecutive keyframes point
* apart. Flipping the sign here means the products already describe the short
* arc, so nothing downstream has to decide it per frame.
*/
export function alignQuaternionSigns(frames: OutKeyframe[][]): void {
if (frames.length !== 4) return;
for (let k = 1; k < (frames[0]?.length ?? 0); k++) {
let dot = 0;
for (let c = 0; c < 4; c++) dot += frames[c]![k]!.value * frames[c]![k - 1]!.value;
if (dot >= 0) continue;
for (let c = 0; c < 4; c++) {
const kf = frames[c]![k]!;
kf.value = -kf.value;
kf.inTangent = -kf.inTangent;
kf.outTangent = -kf.outTangent;
}
}
}
/**
* One sampler's keyframes, split into one list per component. CUBICSPLINE stores
* each key as `[inTangent, value, outTangent]`, and its tangents are already per
* second — the units the evaluator multiplies by the segment length — so the
* three land in the three fields a keyframe has with no conversion.
*/
export function samplerKeyframes(times: ArrayLike<number>, values: ArrayLike<number>,
comps: number, interpolation: string): OutKeyframe[][] {
const cubic = interpolation === 'hermite';
const out: OutKeyframe[][] = Array.from({ length: comps }, () => []);
for (let k = 0; k < times.length; k++) {
for (let c = 0; c < comps; c++) {
const at = cubic ? (3 * k + 1) * comps + c : k * comps + c;
out[c]!.push({
time: times[k] ?? 0,
value: values[at] ?? 0,
inTangent: cubic ? (values[3 * k * comps + c] ?? 0) : 0,
outTangent: cubic ? (values[(3 * k + 2) * comps + c] ?? 0) : 0,
interpolation: cubic ? 'hermite' : interpolation,
});
}
}
return out;
}
/** One animated node: the entity a track addresses, and the channels driving it. */
export interface AnimatedNode {
/** The node's own name — the track's label. */
node: string;
/** The entity the track writes, under the prefab root. */
childPath: string;
/** The component whose fields the channels below name. */
component: string;
channels: Map<string, OutKeyframe[]>;
}
/**
* An animation as an `.estimeline` document. Channels are grouped per target
* entity AND component, since a track drives one component on one entity and the
* runtime reads and writes that component once per track — a node whose shape
* and placement both move is two tracks.
*
* @param byNode childPath → the node's channels, in the order tracks are written.
*/
export function timelineDocument(duration: number,
byNode: Map<string, AnimatedNode>): Record<string, unknown> {
return {
version: TIMELINE_FORMAT_VERSION,
type: 'timeline',
duration,
// Neither format says anything about looping, and the import does not guess.
wrapMode: 'once',
tracks: [...byNode.values()].map((entry) => ({
type: 'property', name: entry.node, childPath: entry.childPath,
component: entry.component,
channels: [...entry.channels].map(([property, keyframes]) => ({ property, keyframes })),
})),
};
}
/** A source's animation name is whatever the tool wrote (spaces, dots, a slash),
* and it becomes a file name here. */
export function animationProductName(stem: string, name: string): string {
return `${stem}_${name.replace(/[^\w.-]+/g, '_')}`;
}
/* -- Products ----------------------------------------------------------- */
/** Cells per side of the grid a lightmap UV set is judged on. */
const LAYOUT_GRID = 256;
/**
* How a mesh's TexCoord1 triangles sit in their square: the share of it they
* cover, and how many layers deep they lie on themselves (1 = none overlap).
* Counted on one grid for both, so a sliver that misses every cell centre
* weighs on neither. Zero coverage without the channel.
*/
export function lightmapUVLayout(data: ImportedMesh['data']): { coverage: number; overlap: number } {
const channel = data.channels.find((c) => c.semantic === MeshChannel.TexCoord1);
if (!channel) return { coverage: 0, overlap: 1 };
const view = new DataView(data.vertices.buffer, data.vertices.byteOffset, data.vertices.byteLength);
const G = LAYOUT_GRID;
const u = (v: number) => view.getFloat32(v * data.vertexStride + channel.offset, true) * G;
const w = (v: number) => view.getFloat32(v * data.vertexStride + channel.offset + 4, true) * G;
const cells = new Uint8Array(G * G);
let hits = 0, covered = 0;
const idx = data.indices;
for (let i = 0; i + 2 < idx.length; i += 3) {
const x = [u(idx[i]!), u(idx[i + 1]!), u(idx[i + 2]!)];
const y = [w(idx[i]!), w(idx[i + 1]!), w(idx[i + 2]!)];
const area = (x[1]! - x[0]!) * (y[2]! - y[0]!) - (x[2]! - x[0]!) * (y[1]! - y[0]!);
if (Math.abs(area) < 1e-12) continue;
const x0 = Math.max(0, Math.floor(Math.min(...x))), x1 = Math.min(G - 1, Math.ceil(Math.max(...x)));
const y0 = Math.max(0, Math.floor(Math.min(...y))), y1 = Math.min(G - 1, Math.ceil(Math.max(...y)));
for (let cy = y0; cy <= y1; cy++) {
for (let cx = x0; cx <= x1; cx++) {
const px = cx + 0.5, py = cy + 0.5;
const w0 = ((x[1]! - px) * (y[2]! - py) - (x[2]! - px) * (y[1]! - py)) / area;
const w1 = ((x[2]! - px) * (y[0]! - py) - (x[0]! - px) * (y[2]! - py)) / area;
if (w0 < 0 || w1 < 0 || w0 + w1 > 1) continue;
hits++;
if (cells[cy * G + cx] === 0) { cells[cy * G + cx] = 1; covered++; }
}
}
}
return { coverage: covered / (G * G), overlap: covered > 0 ? hits / covered : 1 };
}
/**
* Gives every mesh a bake can be read on a lightmap UV set, and says who it
* skipped. Mutates in place: the caller holds the products it is about to write.
* Skinned is skipped because bones move it and a bake cannot follow; one that
* already carries a usable layout keeps it, since its art may be painted against it.
*/
export function applyLightmapUV(meshes: ImportedMesh[]): string[] {
const warnings: string[] = [];
for (const mesh of meshes) {
if (mesh.skinJoints && mesh.skinJoints.length > 0) {
warnings.push(`${mesh.name}: skinned, so it gets no lightmap UV — bones move it and`
+ ' a bake cannot');
continue;
}
if (mesh.data.channels.some((c) => c.semantic === MeshChannel.TexCoord1)) {
const { coverage, overlap } = lightmapUVLayout(mesh.data);
if (overlap > OVERLAPPING_LIGHTMAP_UV) {
warnings.push(`${mesh.name}: its second UV set lies ${overlap.toFixed(1)} layers deep on`
+ ' itself, so parts of it would share light — a lightmap UV is unwrapped in its place');
} else if (coverage < SPARSE_LIGHTMAP_UV) {
warnings.push(`${mesh.name}: its second UV set covers ${(coverage * 100).toFixed(1)}% of its`
+ ' square, too little to bake into — a lightmap UV is unwrapped in its place');
} else {
warnings.push(`${mesh.name}: already carries a second UV set, which is kept`);
continue;
}
}
try {
const { mesh: unwrapped, charts, coverage } = unwrapLightmapUV(mesh.data);
mesh.data = unwrapped;
mesh.vertexCount = unwrapped.vertexCount;
if (coverage < 0.15) {
warnings.push(`${mesh.name}: ${charts} chart(s) fill only`
+ ` ${Math.round(coverage * 100)}% of its atlas — a wider chart angle packs`
+ ' tighter, at the cost of more stretch');
}
} catch (err) {
warnings.push(`${mesh.name}: no lightmap UV (${(err as Error).message})`);
}
}
return warnings;
}
/** What a generated level keeps and where it takes over — each level is cheaper than the last. */
const LOD_RATIOS = [0.5, 0.2, 0.07];
const LOD_SIZES = [0.4, 0.18, 0.07];
/** A level that sheds less than this share of the one above is not worth a draw swap. */
const LOD_MIN_SAVING = 0.15;
/** The collapse may move the surface this far, relative to the mesh's extent. */
const LOD_ERROR = [0.01, 0.03, 0.08];
/** What each level may do to the surface: the near one keeps its borders; the far ones, seen small, may collapse across them and shed specks. */
const LOD_FLAGS: SimplifierFlag[][] = [['LockBorder'], ['Prune', 'Permissive'], ['Prune', 'Permissive']];
export interface LodOptions {
/** How many levels to make below the original, 1–3. */
levels: number;
/** A mesh with fewer triangles than this has nothing worth swapping. */
minTriangles: number;
}
/** The file a mesh's level `n` is written to, by product name (no extension). */
export function lodName(mesh: Pick<ImportedMesh, 'name'>, level: number): string {
return `${mesh.name}_lod${level}`;
}
/**
* Makes the cheaper stand-ins a `LODGroup` swaps in, and says what it left alone.
* Mutates in place, after any unwrap: a level is a collapse of the mesh as it will
* be written, lightmap UV included. Skinned and morphing meshes keep one level.
*/
export async function generateLods(meshes: ImportedMesh[], options: LodOptions): Promise<string[]> {
const warnings: string[] = [];
const levels = Math.min(LOD_RATIOS.length, Math.max(0, Math.floor(options.levels)));
if (levels === 0) return warnings;
for (const mesh of meshes) {
if (mesh.triangleCount < options.minTriangles) continue;
if (!canSimplify(mesh.data)) {
if (mesh.skinJoints?.length || mesh.data.morph) {
warnings.push(`${mesh.name}: skinned or morphing, so it keeps a single level of detail`);
}
continue;
}
const out: GeneratedLod[] = [];
let above = mesh.triangleCount;
for (let level = 0; level < levels; level++) {
// Collapse from the ORIGINAL each time: stacking collapses compounds their error.
const made = await simplifyMesh(mesh.data, { ratio: LOD_RATIOS[level]!, maxError: LOD_ERROR[level]!, flags: LOD_FLAGS[level]! });
if (!made || made.triangles > above * (1 - LOD_MIN_SAVING)) break;
out.push({ data: made.data, triangleCount: made.triangles, size: LOD_SIZES[level]! });
above = made.triangles;
}
if (out.length > 0) mesh.lods = out;
}
return warnings;
}
/** The bytes to write for a generated level. */
export function encodeGeneratedLod(lod: GeneratedLod): Uint8Array {
return encodeMesh(lod.data);
}
/** The bytes to write for an imported mesh. */
export function encodeImportedMesh(mesh: ImportedMesh): Uint8Array {
return encodeMesh(mesh.data);
}
/** How a product is spelled where a component refers to it. */
export interface ProductRefs {
/** Prepended to every product name, e.g. `assets/models/` — the project-relative dir. */
prefix?: string;
/** Canonical geometry product stems. Nodes, materials, skin bindings and animation paths keep their own identity. */
meshNames?: ReadonlyMap<ImportedMesh, string>;
/** An external image uri (relative to the source) → the ref a component carries. */
external?: (uri: string) => string;
/** Give a skin, hair or eye material the engine's character shader instead of the Model shader (see {@link characterShading}). */
characters?: boolean;
/** Turn the bones a model names as hair chains, and the empties it names as colliders, into SpringBone and SpringBoneCollider (see {@link springBoneComponents}). */
springBones?: boolean;
}
/** How the products go together. */
export interface PrefabAssembly {
refs?: ProductRefs;
/** The source's hierarchy; without it every mesh sits at the origin. */
nodes?: ImportedNode[];
/** Uniform scale on the root: a model is authored in metres, a world unit is
* a design pixel. */
scale?: number;
/** The clip the root's player points at — the products say what they have,
* and it is left stopped because what to play is the scene's decision. */
timeline?: string;
}
/** How a component spells a reference to an image: a project-relative path. */
function imageRef(image: ImportedImageRef, refs: ProductRefs): string {
return image.external
? refs.external?.(image.file) ?? image.file
: (refs.prefix ?? '') + image.file;
}
/**
* How a MATERIAL spells the same reference. It resolves a relative ref against
* its own directory, and every product lands beside it, so a product is its bare
* name; a file already in the project takes a logical path instead — the one
* other spelling that resolver passes through (as `rewriteMaterialRefs` writes).
*/
function materialImageRef(image: ImportedImageRef, refs: ProductRefs): string {
const dir = refs.prefix ?? '';
const ref = imageRef(image, refs);
if (ref.startsWith(dir)) {
const beside = ref.slice(dir.length);
if (beside.length > 0 && !beside.includes('/')) return beside;
}
return ref.startsWith('assets/') || ref.startsWith('/') ? ref : `/${ref}`;
}
/**
* The Model shader's parameter each layer field becomes. A colour is a `{r, g, b, a}` object and a number is itself,
* so one table carries them all and a field the source did not state is simply not written.
*/
const MATERIAL_LAYER_PROPERTIES: readonly [keyof ImportedMaterial, string][] = [
['clearcoat', 'u_clearcoat'], ['clearcoatRoughness', 'u_clearcoatRoughness'],
['sheenColor', 'u_sheenColor'], ['sheenRoughness', 'u_sheenRoughness'],
['anisotropy', 'u_anisotropy'], ['anisotropyRotation', 'u_anisotropyRotation'],
['ior', 'u_ior'], ['specular', 'u_specular'],
['translucency', 'u_translucency'], ['translucencyColor', 'u_translucencyColor'],
['transmission', 'u_transmission'], ['thickness', 'u_thickness'], ['attenuationColor', 'u_attenuationColor'],
['iridescence', 'u_iridescence'], ['iridescenceIor', 'u_iridescenceIor'],
['iridescenceThickness', 'u_iridescenceThickness'],
];
/**
* Whether this material says anything a MeshRenderer's own fields cannot: shading is
* per-material constants and samplers, and the component has neither. A metal-
* roughness pair the engine's defaults already are needs nothing written — but
* glTF defaults both factors to 1, so most materials do.
*/
function needsMaterial(material: ImportedMaterial | undefined): material is ImportedMaterial {
return !!material && !!(material.unlit || material.normalTexture || material.emissive || material.emissiveTexture
|| material.occlusionTexture || material.alphaCutoff || material.metallicRoughnessTexture || material.specularGlossiness
|| (material.normalScale ?? 1) !== 1 || material.uvTransform
|| (material.metallic ?? 0) !== 0 || (material.roughness ?? 1) !== 1
|| MATERIAL_LAYER_PROPERTIES.some(([field]) => material[field] !== undefined));
}
/** The character shader a material's name asks for, when it names skin, hair or an eye. */
export type CharacterShading = 'skin' | 'hair' | 'eye';
const CHARACTER_TOKENS: readonly [CharacterShading, readonly string[]][] = [
['eye', ['eye', 'eyes', 'eyeball', 'eyeballs', 'iris', 'cornea']],
['hair', ['hair', 'hairs', 'ponytail', 'bangs', 'fringe']],
['skin', ['skin', 'face', 'head', 'neck']],
];
/**
* What a material is, read from its name and its colour texture's file name, split into words (`T_C004_BodySkin` is c, body, skin):
* a word has to BE `eye` or `hair`, so `Eyelashes` and `Headband` are neither. A name is a convention and not a fact, which is why
* the import asks for this by setting and never assumes it.
*/
export function characterShading(material: ImportedMaterial): CharacterShading | undefined {
const file = material.baseColorTexture?.file ?? '';
const words = `${material.name} ${file.slice(file.lastIndexOf('/') + 1)}`
.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z]+/);
for (const [shading, names] of CHARACTER_TOKENS) {
if (words.some((word) => names.includes(word))) return shading;
}
return undefined;
}
/**
* Put the triangles of every hair mesh in the order a blended draw wants them: the ones nearest the middle of the hair first, the outermost
* last. A hair model is a shell of cards around a head, and seen from outside a card nearer the middle is behind one further out, from
* whichever side the camera looks, so one fixed order is the back-to-front order for all of them. Draws go through the index buffer in
* order, which is what makes this an ordering at all. It is an approximation and says so: a ponytail that leaves the shell is not ordered
* by it. Only meshes whose material {@link characterShading} calls hair; the levels of detail are ordered too.
*/
export function orderHairTriangles(meshes: ImportedMesh[]): void {
for (const mesh of meshes) {
if (!mesh.material || characterShading(mesh.material) !== 'hair') continue;
const centre = hairCentre(mesh.data);
if (!centre) continue;
sortTriangles(mesh.data, centre);
for (const lod of mesh.lods ?? []) sortTriangles(lod.data, centre);
}
}
function positionsOf(data: MeshData): Float32Array | undefined {
const channel = data.channels.find((c) => c.semantic === MeshChannel.Position && c.type === MeshChannelType.Float32 && c.components >= 3);
if (!channel) return undefined;
const view = new DataView(data.vertices.buffer, data.vertices.byteOffset, data.vertices.byteLength);
const out = new Float32Array(data.vertexCount * 3);
for (let i = 0; i < data.vertexCount; i++) {
for (let k = 0; k < 3; k++) out[i * 3 + k] = view.getFloat32(i * data.vertexStride + channel.offset + k * 4, true);
}
return out;
}
/** The middle of the mesh's bounding box. */
function hairCentre(data: MeshData): [number, number, number] | undefined {
const [lx, ly, lz] = data.aabbMin, [hx, hy, hz] = data.aabbMax;
return [(lx + hx) / 2, (ly + hy) / 2, (lz + hz) / 2];
}
function sortTriangles(data: MeshData, centre: [number, number, number]): void {
const positions = positionsOf(data);
const count = Math.floor(data.indices.length / 3);
if (!positions || count < 2) return;
const key = new Float64Array(count);
for (let t = 0; t < count; t++) {
let x = 0, y = 0, z = 0;
for (let k = 0; k < 3; k++) {
const v = data.indices[t * 3 + k]! * 3;
x += positions[v]!; y += positions[v + 1]!; z += positions[v + 2]!;
}
key[t] = Math.hypot(x / 3 - centre[0], y / 3 - centre[1], z / 3 - centre[2]);
}
const order = Array.from({ length: count }, (_, t) => t).sort((a, b) => key[a]! - key[b]! || a - b);
const sorted = new Uint32Array(data.indices.length);
order.forEach((from, to) => { sorted.set(data.indices.subarray(from * 3, from * 3 + 3), to * 3); });
data.indices = sorted;
}
/** Whether a material gets a product: it says something a MeshRenderer cannot, or its name asks for a character shader. */
function hasProduct(material: ImportedMaterial, refs: ProductRefs): boolean {
return needsMaterial(material) || (!!refs.characters && characterShading(material) !== undefined);
}
/**
* How much of the Hair shader's strand highlight the lamps draw for a glTF's specular factor. The factor scales a Fresnel reflectance of 0.04,
* which `u_specular` carries into the reflection of the environment; the engine's strand highlight is an authored lobe with a peak of about
* half the light, so under a lamp it is far too bright unless it is turned down on its own. Measured against Blender's Principled at roughness
* 0.43 and a specular level of 0.3 (tools/render-align in the star-neighbors game).
*/
const HAIR_LOBE_GAIN = 0.1;
const HAIR_ENV_GAIN = 0.65;
const HAIR_SHADOW_DENSITY = 400;
/**
* What the character shaders read, from what the source says: the maps they share, and the cutout hair needs. What a glTF does not say it
* does not have: it carries no subsurface scattering and no second strand highlight, so those are written as off (they stay on the shader
* for a hand-made material), and the import shades like the Principled shader the model was authored against.
*/
function characterProperties(shading: CharacterShading, material: ImportedMaterial, properties: Record<string, unknown>,
bind: (name: string, image?: ImportedImageRef) => void): void {
// Skin and hair read the glTF packing (occlusion, roughness, metalness) as their `u_ormMap`; their roughness is a SCALE on it,
// so a factor of 0 (what an FBX without one writes) would be a mirror, and is left out.
const rough = material.roughness !== undefined && material.roughness > 0 ? material.roughness : undefined;
for (const key of ['u_metallic', 'u_roughness', 'u_metallicRoughnessMap', 'u_occlusionMap', 'u_occlusionStrength']) delete properties[key];
if (shading !== 'eye') {
bind('u_ormMap', material.metallicRoughnessTexture);
if (rough !== undefined && !material.metallicRoughnessTexture) properties.u_roughness = rough;
}
if (shading === 'skin') {
properties.u_sssWrap = 0; properties.u_translucency = 0; properties.u_lobe2 = 0; properties.u_fuzz = 0;
properties.u_blurRed = 0; properties.u_blurGreen = 0;
}
if (shading === 'hair') {
// A little of the shader's own strand character is kept (a per-strand shift of the highlight and a tinted second lobe, at a third of their
// strength): without it the cards read as plates, not locks of hair.
properties.u_translucency = 0; properties.u_shiftAmount = 0.3; properties.u_rootDark = 0;
properties.u_secondaryTint = { r: 0.12, g: 0.07, b: 0.04, a: 1 };
// The Hair shader has no use for the packed roughness (a strand's width is its own), so the factor is the whole answer.
if (rough !== undefined) properties.u_roughness = rough;
// Principled reflects F0 = 0.04 x the factor; the Hair shader's F0 is 0.046, so u_specular is the ratio, and its reflection of the environment at
// this roughness comes out about half as bright again as Blender's, which HAIR_ENV_GAIN takes back.
properties.u_specular = ((material.specular ?? 1) * 0.04 / 0.046) * HAIR_ENV_GAIN;
properties.u_lobeGain = HAIR_LOBE_GAIN;
// The Principled shader's diffuse, which goes dark where a card turns from the light (the strand's own diffuse keeps it lit edge-on and flattens the locks), and
// a density of hair for the light to pass through, with the cascade the frame fits to it: what Blender gets from tracing the layers.
properties.u_strandDiffuse = 0; properties.u_hairShadow = HAIR_SHADOW_DENSITY;
// A card the source gave an anisotropy (KHR_materials_anisotropy, which Blender exports from its Principled anisotropy) keeps the
// highlight it was authored with: Principled's GGX stretched along the strand, the specular factor as F0 = 0.04 x it. The strand lobes
// above are what a card without one gets.
if (material.anisotropy !== undefined && material.anisotropy > 0) {
properties.u_anisotropy = material.anisotropy;
properties.u_specular = material.specular ?? 1;
}
// Cards cut from one strand texture read as combed plates; drawing them as a few locks, each a little lighter or darker with its own break in the highlight
// and a shadowed seam, gives the layers the depth Blender gets from hundreds of overlapping cards.
properties.u_clumpCount = 7; properties.u_clumpTone = 0.4; properties.u_clumpShift = 0.5; properties.u_clumpGap = 0.55;
properties.u_alphaCutoff = material.alphaCutoff ?? 0.5;
bind('u_flowMap', material.flowTexture);
bind('u_shiftMap', material.shiftTexture);
if (material.tipSoftness !== undefined) properties.u_tipSoftness = material.tipSoftness;
} else delete properties.u_alphaCutoff;
if (shading === 'eye') {
delete properties.u_normalMap;
// What a glTF says of an eye is a painted texture and a roughness: the Principled shader it was authored against. So the Eye shader's
// own additions are written as off (a tinted white, light wrapping past the terminator in a warm colour, which turned a painted iris
// red, and lids darkening it), and both its glossy layers take the source's roughness instead of a near-mirror cornea. An eye given
// a depth map and an iris normal map by hand gets them back by setting these.
properties.u_scleraColor = { r: 1, g: 1, b: 1, a: 1 };
properties.u_scleraWrap = 0;
properties.u_lidShadow = 0;
const eyeRough = rough ?? 0.5;
properties.u_corneaRoughness = Math.max(eyeRough, 0.01);
properties.u_scleraRoughness = Math.max(eyeRough, 0.1);
properties.u_specular = material.specular ?? 1;
}
}
/** `<stem>_m<source material index>` — the product a material becomes. */
function materialName(stem: string, material: ImportedMaterial): string {
return `${stem}_m${material.index}`;
}
/**
* The `.esmaterial` documents an import writes, one per source material that
* needs one. The render state is written out because a material REPLACES the
* draw's own — a model told to occlude itself would start blending the moment
* it gained a material.
*/
/**
* Every image the materials reference, with the import settings its references ask
* for, merged: two materials sharing a texture (a cutout's leaves and a blended
* wing on one atlas) each add their keys, the first to name a key keeping it.
* Keyed by the ref's `file` as the reader spelled it.
*/
export function importedImageSettings(meshes: ImportedMesh[]):
Map<string, { external: boolean; settings: NonNullable<ImportedImageRef['settings']> }> {
const out = new Map<string, { external: boolean; settings: NonNullable<ImportedImageRef['settings']> }>();
for (const mesh of meshes) {
const m = mesh.material;
for (const slot of IMPORTED_MATERIAL_IMAGE_SLOTS) {
const image = m?.[slot];
if (!image) continue;
const seen = out.get(image.file);
out.set(image.file, { external: image.external, settings: { ...image.settings, ...seen?.settings } });
}
}
return out;
}
export function materialProducts(meshes: ImportedMesh[], stem: string,
refs: ProductRefs = {}): ImportedMaterialAsset[] {
const out: ImportedMaterialAsset[] = [];
const seen = new Set<number>();
for (const mesh of meshes) {
const material = mesh.material;
if (!material || !hasProduct(material, refs) || seen.has(material.index)) continue;
seen.add(material.index);
if (material.unlit) {
out.push({
name: materialName(stem, material),
data: {
version: MATERIAL_FORMAT_VERSION, type: 'material', shader: 'builtin:sprite-unlit',
blendMode: material.blendMode ?? (material.opaque ? BlendMode.None : BlendMode.Normal),
depthTest: true, depthWrite: material.opaque,
cull: material.cullBackfaces ? CullMode.Back : CullMode.None,
properties: { u_alphaCutoff: material.alphaCutoff ?? 0 },
},
images: [],
});
continue;
}
// A name-based character preset cannot express specular/glossiness. Keep
// that authored BRDF on the general Model shader instead of losing it.
const shading = refs.characters && !material.specularGlossiness ? characterShading(material) : undefined;
const images: ImportedImageRef[] = [];
const properties: Record<string, unknown> = {};
const bind = (name: string, image?: ImportedImageRef): void => {
if (!image) return;
images.push(image);
properties[name] = materialImageRef(image, refs);
};
bind('u_normalMap', material.normalTexture);
bind('u_emissiveMap', material.emissiveTexture);
bind('u_occlusionMap', material.occlusionTexture);
bind('u_metallicRoughnessMap', material.specularGlossiness ? material.specularGlossinessTexture : material.metallicRoughnessTexture);
if (material.normalScale !== undefined) properties.u_normalScale = material.normalScale;
if (material.specularGlossiness) {
const [r, g, b] = material.specularGlossiness.specular;
properties.u_specularColor = { r, g, b, a: 1 };
properties.u_glossiness = material.specularGlossiness.glossiness;
}
// Written even at the engine's own defaults: glTF's are 1 and 1, so a
// product that left them out would read as a surface it is not.
if (material.metallic !== undefined) properties.u_metallic = material.metallic;
if (material.roughness !== undefined) properties.u_roughness = material.roughness;
if (material.emissive) {
const [r, g, b] = material.emissive;
properties.u_emissive = { r, g, b, a: 1 };
}
if (material.occlusionStrength !== undefined) {
properties.u_occlusionStrength = material.occlusionStrength;
}
if (material.alphaCutoff !== undefined) properties.u_alphaCutoff = material.alphaCutoff;
if (material.uvTransform && !shading) {
const { tiling, offset, rotation } = material.uvTransform;
properties.u_uvTiling = { x: tiling[0], y: tiling[1] };
properties.u_uvOffset = { x: offset[0], y: offset[1] };
if (rotation !== 0) properties.u_uvRotation = rotation;
}
if (shading) characterProperties(shading, material, properties, bind);
else for (const [field, parameter] of MATERIAL_LAYER_PROPERTIES) {
const value = material[field];
if (value === undefined) continue;
properties[parameter] = Array.isArray(value)
? { r: value[0], g: value[1], b: value[2], a: 1 } : value;
}
out.push({
name: materialName(stem, material),
data: {
version: MATERIAL_FORMAT_VERSION,
type: 'material',
shader: shading ? `builtin:${shading}` : 'builtin:model',
...(material.specularGlossiness ? { switches: { ES_SPECULAR_GLOSSINESS: true } } : {}),
// Hair is cut out and feathered by coverage, which only an unblended draw gets.
blendMode: material.opaque || shading === 'hair' ? BlendMode.None : BlendMode.Normal,
// Blended surfaces still test against opaque geometry in front.
depthTest: true,
depthWrite: material.opaque || shading === 'hair',
cull: material.cullBackfaces ? CullMode.Back : CullMode.None,
properties,
},
images,
});
}
return out;
}
/** The `LODGroup` that points at a mesh's generated levels; none when it made none. */
function lodComponent(mesh: ImportedMesh, refs: ProductRefs): ComponentData[] {
if (!mesh.lods || mesh.lods.length === 0) return [];
const prefix = refs.prefix ?? '';
const data: Record<string, unknown> = {};
const product = { name: refs.meshNames?.get(mesh) ?? mesh.name };
mesh.lods.forEach((lod, i) => {
data[`lod${i + 1}`] = `${prefix}${lodName(product, i + 1)}.esmesh`;
data[`lod${i + 1}Size`] = lod.size;
});
return [{ type: 'LODGroup', data }];
}
function meshComponent(mesh: ImportedMesh, stem: string, refs: ProductRefs): ComponentData {
const prefix = refs.prefix ?? '';
const texture = mesh.material?.baseColorTexture
? imageRef(mesh.material.baseColorTexture, refs) : null;
const hasNormals = mesh.data.channels.some(c => c.semantic === MeshChannel.Normal);
const color = mesh.material?.baseColor;
// Shading moves WHOLE to the material when there is one: a material shader
// reads its own samplers, so a normal map left on the component would be a
// map nothing samples.
const material = mesh.material && hasProduct(mesh.material, refs)
? `${prefix}${materialName(stem, mesh.material)}.esmaterial` : null;
// A normal map needs normals to perturb; without them the engine draws the
// unlit variant and the map would be a reference to nothing.
const normalMap = !material && hasNormals && mesh.material?.normalTexture
? imageRef(mesh.material.normalTexture, refs) : null;
return { type: 'MeshRenderer', data: {
mesh: `${prefix}${refs.meshNames?.get(mesh) ?? mesh.name}.esmesh`,
// Geometry that carries normals was authored to be shaded, so the product
// says so. Written rather than assumed: `lit` is a field a user can turn
// off, and an import that left it out would be one the engine had to guess.
...(mesh.material?.unlit ? { lit: false } : hasNormals ? { lit: true } : {}),
...(texture ? { texture } : {}),
...(normalMap ? { normalMap } : {}),
...(material ? { material } : {}),
...(color ? { color: { r: color[0], g: color[1], b: color[2], a: color[3] } } : {}),
...(mesh.material?.opaque ? { opaque: true } : {}),
...(mesh.material?.cullBackfaces ? { cullBackfaces: true } : {}),
enabled: true,
} };
}
/**
* The joints that deform this mesh, named by the prefab entity each source node
* became — the same `n<index>` ids {@link assembleModelPrefab} emits, so a
* re-import keeps pointing at the same entities.
*/
function skinComponent(mesh: ImportedMesh): ComponentData[] {
if (!mesh.skinJoints) return [];
return [{ type: 'MeshSkin', data: { joints: mesh.skinJoints.map(i => `n${i}`) } }];
}
/**
* The shape this mesh starts in. Written whenever it HAS shapes, even at rest:
* the component is what a clip and the inspector address, and a mesh whose
* weights arrive only once something moves them is one an author cannot open.
*/
function morphComponent(mesh: ImportedMesh): ComponentData[] {
const targets = mesh.data.morph?.names.length ?? 0;
if (targets === 0) return [];
const authored = mesh.morphWeights ?? [];
return [{ type: 'MeshMorph', data: {
weights: Array.from({ length: targets }, (_, i) => authored[i] ?? 0),
} }];
}
/** Only what differs from a Transform's defaults, so a diff shows the placement. */
function transformComponent(trs?: Trs, scale?: number): ComponentData {
const s = trs?.scale ?? [1, 1, 1];
const k = scale ?? 1;
const [x, y, z] = trs?.translation ?? [0, 0, 0];
const [rx, ry, rz, rw] = trs?.rotation ?? [0, 0, 0, 1];
return { type: 'Transform', data: {
...(x || y || z ? { position: { x, y, z } } : {}),
...(rx || ry || rz || rw !== 1 ? { rotation: { w: rw, x: rx, y: ry, z: rz } } : {}),
...(s[0] * k !== 1 || s[1] * k !== 1 || s[2] * k !== 1
? { scale: { x: s[0] * k, y: s[1] * k, z: s[2] * k } } : {}),
} };
}
/** An unbounded light's reach, as Godot clamps one: far enough to be no reach at all. */
const UNBOUNDED_LIGHT_RANGE = 4096;
const LIGHT_TYPE = { point: 0, directional: 1, spot: 3 } as const;
/**
* A KHR_lights_punctual light. A point or spot one is in candela and falls off as the inverse square of the distance, so
* it is an inverse-square Light at candela over pi (a Light's intensity is what reaches a surface over pi, the unit a
* directional one's is in); its range is in metres, so it is scaled with the model.
*/
function lightComponent(light: ImportedLight, scale = 1): ComponentData {
const [r, g, b] = light.color;
const positional = light.type !== 'directional';
return { type: 'Light', data: {
type: LIGHT_TYPE[light.type],
color: { r, g, b, a: 1 },
intensity: positional ? light.intensity / Math.PI : light.intensity,
...(positional ? { radius: (light.range ?? UNBOUNDED_LIGHT_RANGE) * scale, inverseSquare: true } : {}),
...(light.type === 'spot' ? { innerAngle: light.innerAngle ?? 0, outerAngle: light.outerAngle ?? 90 } : {}),
} };
}
/** Never active: a model's camera must not take over the scene it is placed in. */
function cameraComponent(camera: ImportedCamera): ComponentData {
return { type: 'Camera', data: {
projectionType: camera.projection === 'perspective' ? 0 : 1,
...(camera.yfov !== undefined && camera.yfov > 0 ? { fov: camera.yfov } : {}),
...(camera.halfHeight !== undefined ? { orthoSize: camera.halfHeight } : {}),
// A plane the file leaves at 0 is one it did not state.
...(camera.near > 0 ? { nearPlane: camera.near } : {}),
...(camera.far !== undefined && camera.far > camera.near ? { farPlane: camera.far } : {}),
...(camera.aspect ? { aspectRatio: camera.aspect } : {}),
isActive: false,
} };
}
function entity(id: string, name: string, parent: string | null,
components: ComponentData[]): PrefabEntityData {
return { prefabEntityId: id, name, parent, children: [], visible: true, components };
}
/** The spring data a source stated for this node: a SpringBone on it, and an entity below it for each collider it hosts. Lengths are the model's metres times the import scale. */
function addExplicitSpringBones(node: ImportedNode, self: PrefabEntityData, entities: PrefabEntityData[], scale: number): void {
(node.springColliders ?? []).forEach((c, i) => {
const id = `${self.prefabEntityId}_sbc${i}`;
const [x, y, z] = c.offset ?? [0, 0, 0];
const [rx, ry, rz, rw] = c.rotation ?? [0, 0, 0, 1];
self.children.push(id);
entities.push(entity(id, `${node.name}_collider${i}`, self.prefabEntityId, [
{ type: 'Transform', data: {
...(x || y || z ? { position: { x, y, z } } : {}),
...(rx || ry || rz || rw !== 1 ? { rotation: { w: rw, x: rx, y: ry, z: rz } } : {}),
} },
{ type: 'SpringBoneCollider', data: { shape: c.shape, radius: c.radius, ...(c.shape === 1 ? { height: c.height ?? 0 } : {}) } },
]));
});
const s = node.springBone;
if (!s) return;
self.components.push({ type: 'SpringBone', data: {
...(s.stiffness !== undefined ? { stiffness: s.stiffness } : {}),
...(s.drag !== undefined ? { drag: s.drag } : {}),
...(s.gravity ? { gravity: { x: s.gravity[0] * scale, y: s.gravity[1] * scale, z: s.gravity[2] * scale } } : {}),
...(s.radius !== undefined ? { radius: s.radius * scale } : {}),
...(s.endLength !== undefined ? { endLength: s.endLength * scale } : {}),
...(s.colliders ? { colliders: [...s.colliders] } : {}),
} });
}
/** A hair chain's root bone: `Hair_<region>_<chain>_00`, the joint the body or the animation drives and the chain hangs from. */
const HAIR_CHAIN_ROOT = /^Hair_([A-Za-z]+(?:_[A-Za-z]+)*)_(\d{2})_00$/;
/** A collider an artist left in the model: `SBC_Sphere_<name>_r<cm>` or `SBC_Capsule_<name>_r<cm>_h<cm>`; the node's own transform places it, a capsule runs along its local +Y. */
const SPRING_COLLIDER = /^SBC_(Sphere|Capsule)_(.+?)_r(\d+)(?:_h(\d+))?$/;
/** How loose each kind of strand hangs. A fringe is held close, a ponytail swings; the numbers are the starting point an artist adjusts in Details, not a claim about hair. */
const HAIR_FEEL: Record<string, { stiffness: number; drag: number }> = {
Ponytail: { stiffness: 0.06, drag: 0.35 },
Temple: { stiffness: 0.12, drag: 0.4 },
Fringe: { stiffness: 0.2, drag: 0.45 },
Crest: { stiffness: 0.15, drag: 0.3 },
Crown: { stiffness: 0.2, drag: 0.5 },
};
/**
* Builds hair motion from names: a `Hair_<region>_<chain>_00` bone with a child is a SpringBone, an `SBC_` node a SpringBoneCollider,
* and every chain is kept out of every collider the model has. Sizes are the model's metres times the import scale; gravity is Earth's.
* Returns the counts it made.
*/
export function springBoneComponents(entities: PrefabEntityData[], scale = 1): { chains: number; colliders: number } {
const has = (e: PrefabEntityData, type: string): boolean => e.components.some(c => c.type === type);
// What the file stated outright is already on the entities; names only fill in what it did not.
const colliders: string[] = entities.filter(e => has(e, 'SpringBoneCollider')).map(e => e.prefabEntityId);
for (const e of entities) {
for (const c of e.components) {
if (c.type === 'SpringBone' && c.data.colliders === undefined) c.data.colliders = [...colliders];
}
}
for (const e of entities) {
if (has(e, 'SpringBoneCollider')) continue;
const m = SPRING_COLLIDER.exec(e.name);
if (!m) continue;
const radius = Number(m[3]) / 100;
const capsule = m[1] === 'Capsule';
if (capsule && m[4] === undefined) continue;
e.components.push({ type: 'SpringBoneCollider', data: {
shape: capsule ? 1 : 0, radius, ...(capsule ? { height: Number(m[4]) / 100 } : {}),
} });
colliders.push(e.prefabEntityId);
}
let chains = 0;
for (const e of entities) {
const m = HAIR_CHAIN_ROOT.exec(e.name);
if (!m || e.children.length === 0 || has(e, 'SpringBone')) continue;
const feel = HAIR_FEEL[m[1]!.split('_')[0]!] ?? { stiffness: 0.1, drag: 0.5 };
e.components.push({ type: 'SpringBone', data: {
stiffness: feel.stiffness, drag: feel.drag,
gravity: { x: 0, y: -9.8 * scale, z: 0 },
endLength: 0.04 * scale, radius: 0.005 * scale,
colliders: [...colliders],
} });
chains++;
}
return { chains, colliders: colliders.length };
}
/**
* The import's assembly: where each piece of geometry sits, and which image and
* tint it is drawn with. The products are separate files and nothing else
* records how they go together, so without this a model arrives as a pile of
* parts to be re-connected by hand.
*/
export function assembleModelPrefab(name: string, meshes: ImportedMesh[],
options: PrefabAssembly = {}): PrefabData {
const refs = options.refs ?? {};
const entities: PrefabEntityData[] = [];
const nodes = options.nodes ?? [];
const emitNode = (node: ImportedNode, parent: string | null, rootScale?: number): string => {
const id = `n${node.index}`;
const drawn = node.meshes.map(i => meshes[i]).filter((m): m is ImportedMesh => !!m);
// One primitive rides the node itself; several cannot, since a MeshRenderer
// draws one mesh — they become its children, at its own origin.
const own = drawn.length === 1 && drawn[0]
? [meshComponent(drawn[0], name, refs), ...lodComponent(drawn[0], refs), ...skinComponent(drawn[0]),
...morphComponent(drawn[0])] : [];
const self = entity(id, node.name, parent, [
transformComponent(node, rootScale), ...own,
...(node.light ? [lightComponent(node.light, options.scale ?? 1)] : []),
...(node.camera ? [cameraComponent(node.camera)] : []),
...(node.visibility !== undefined ? [{ type: 'NodeVisibility', data: { visible: node.visibility } }] : []),
]);
entities.push(self);
if (node.billboard !== undefined) self.components.push({ type: 'Billboard', data: { mode: node.billboard, enabled: true } });
if (node.particle) self.components.push({ type: 'ParticleEmitter', data: { ...node.particle.emitter,
...(node.particle.texture ? { texture: imageRef(node.particle.texture, options.refs ?? {}) } : {}) } },
{ type: 'ParticleModelUnits', data: node.particle.units });
if (node.physics) {
const physics = node.physics;
if (physics.parts.length) self.components.push(
{ type: 'RigidBody3D', data: { bodyType: physics.bodyType, ...physics.settings } },
{ type: 'CompoundCollider3D', data: { parts: physics.parts, mass: physics.mass, isSensor: physics.isSensor, enabled: true } },
);
if (physics.triangleMesh !== undefined) {
const mesh = meshes[physics.triangleMesh]!;
const collisionId = `${id}_collision`;
self.children.push(collisionId);
entities.push(entity(collisionId, `${node.name}_Collision`, id, [transformComponent(),
{ type: 'RigidBody3D', data: { bodyType: 0 } },
{ type: 'MeshCollider3D', data: { mesh: `${refs.prefix ?? ''}${refs.meshNames?.get(mesh) ?? mesh.name}.esmesh`, enabled: true } },
]));
}
}
if (refs.springBones) addExplicitSpringBones(node, self, entities, options.scale ?? 1);
if (own.length === 0) {
drawn.forEach((mesh, i) => {
const childId = `${id}_p${i}`;
self.children.push(childId);
entities.push(entity(childId, mesh.name, id,
[transformComponent(), meshComponent(mesh, name, refs),
...lodComponent(mesh, refs), ...skinComponent(mesh), ...morphComponent(mesh)]));
});
}
for (const child of node.children) self.children.push(emitNode(child, id));
return id;
};
if (nodes.length === 1 && nodes[0]) {
emitNode(nodes[0], null, options.scale);
} else if (nodes.length > 1) {
// Several roots are one model all the same, so they get a holder to be
// placed by — and it is where the import's own scale belongs.
const root = entity('root', name, null, [transformComponent(undefined, options.scale)]);
entities.push(root);
for (const node of nodes) root.children.push(emitNode(node, 'root'));
} else {
// No node tree: the meshes are all there is to place.
const root = entity('root', name, null, [transformComponent(undefined, options.scale)]);
entities.push(root);
meshes.forEach((mesh, i) => {
const id = `m${i}`;
root.children.push(id);
entities.push(entity(id, mesh.name, 'root',
[transformComponent(), meshComponent(mesh, name, refs),
...lodComponent(mesh, refs)]));
});
}
if (refs.springBones) springBoneComponents(entities, options.scale ?? 1);
// The player rides the root, which is the entity a clip's childPaths are
// resolved from — the same root the tracks were addressed against.
if (options.timeline && entities[0]) {
entities[0].components.push({ type: 'TimelinePlayer', data: {
timeline: options.timeline, playing: false,
} });
}
return {
version: PREFAB_FORMAT_VERSION, name,
rootEntityId: entities[0]!.prefabEntityId, entities,
};
}