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.

feat(assets): the shapes a model was authored to blend between arrive with it

esenginefa0a595c33ef
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 0ab42ceca..14c142a0c 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 114,
"beta": 101,
- "experimental": 1880,
+ "experimental": 1881,
"deprecated": 3
},
- "total": 2095,
+ "total": 2096,
"subsystems": [
{
"id": "ecs",
diff --git a/pipeline/src/assets/gltfImport.ts b/pipeline/src/assets/gltfImport.ts
index 0ad735a24..f9936f405 100644
--- a/pipeline/src/assets/gltfImport.ts
+++ b/pipeline/src/assets/gltfImport.ts
@@ -11,7 +11,8 @@
* the cook then ships them as the engine format they already are.
*/
/// <reference path="./draco3dgltf.d.ts" />
-import { MESH_MAX_BONES, MeshChannel, MeshChannelType, packChannels } from 'esengine';
+import { MESH_MAX_BONES, MeshChannel, MeshChannelType, packChannels,
+ type MeshMorphData } from 'esengine';
import { MeshoptDecoder } from 'meshoptimizer/decoder';
import {
ANIMATED_PATHS, alignQuaternionSigns, animationProductName, disambiguateNodes,
@@ -72,12 +73,22 @@ interface GltfJson {
/** A meshopt fallback buffer has no uri: nothing reads it once the views decode. */
extensions?: { EXT_meshopt_compression?: { fallback?: boolean } };
}[];
- meshes?: { name?: string; primitives: {
- attributes: Record<string, number>; indices?: number; mode?: number; material?: number;
- extensions?: { KHR_draco_mesh_compression?: DracoPrimitive } & Record<string, unknown>;
- /** Morph targets — shapes the runtime blends between; not imported. */
- targets?: unknown[];
- }[] }[];
+ meshes?: {
+ name?: string;
+ /** The weights each target starts at, when the file states them. */
+ weights?: number[];
+ /** Where an exporter writes the target names; the spec gives them no home
+ * of their own, so the convention is this one. */
+ extras?: { targetNames?: string[] };
+ primitives: {
+ attributes: Record<string, number>; indices?: number; mode?: number; material?: number;
+ extensions?: { KHR_draco_mesh_compression?: DracoPrimitive } & Record<string, unknown>;
+ extras?: { targetNames?: string[] };
+ /** Morph targets — the shapes the runtime blends towards, as deltas
+ * off the attributes beside them. */
+ targets?: Record<string, number>[];
+ }[];
+ }[];
materials?: {
name?: string;
pbrMetallicRoughness?: {
@@ -97,6 +108,8 @@ interface GltfJson {
nodes?: {
name?: string; children?: number[]; mesh?: number; skin?: number;
matrix?: number[]; translation?: number[]; rotation?: number[]; scale?: number[];
+ /** Overrides the mesh's own starting weights for this instance of it. */
+ weights?: number[];
}[];
skins?: { name?: string; joints: number[]; inverseBindMatrices?: number; skeleton?: number }[];
animations?: {
@@ -660,6 +673,62 @@ function bindMatrices(src: GltfBytes, skin: NonNullable<GltfJson['skins']>[numbe
return out;
}
+type GltfMesh = NonNullable<GltfJson['meshes']>[number];
+type GltfPrimitive = GltfMesh['primitives'][number];
+
+/**
+ * The shapes this primitive can be blended towards, as deltas off the vertices
+ * beside them. A target whose accessor does not cover every vertex is kept and
+ * left at zero rather than dropped: weights address targets by position, so
+ * removing one would renumber every target behind it.
+ */
+function morphTargets(src: GltfBytes, mesh: GltfMesh, prim: GltfPrimitive,
+ vertexCount: number, hasNormals: boolean,
+ label: string, warnings: string[]): MeshMorphData | undefined {
+ const targets = prim.targets ?? [];
+ if (!targets.length) return undefined;
+ if (targets.some(t => t.TANGENT !== undefined)) {
+ warnings.push(`${label}: morph target tangents are not imported`
+ + ' (the tangent frame is derived per pixel, from the surface as deformed)');
+ }
+ // Normals deform only where there are any: geometry without them is shaded
+ // off a constant normal, which no delta can bend.
+ const carriesNormals = hasNormals && targets.some(t => t.NORMAL !== undefined);
+ const comps = carriesNormals ? 6 : 3;
+ const deltas = new Float32Array(targets.length * vertexCount * comps);
+ const declared = mesh.extras?.targetNames ?? prim.extras?.targetNames ?? [];
+ const names = targets.map((_, t) => declared[t] ?? `target ${t}`);
+
+ for (let t = 0; t < targets.length; t++) {
+ for (const [semantic, at] of [['POSITION', 0], ['NORMAL', 3]] as const) {
+ if (semantic === 'NORMAL' && !carriesNormals) continue;
+ const index = targets[t]![semantic];
+ if (index === undefined) continue;
+ const acc = src.json.accessors?.[index];
+ // Zeroes are a legal accessor, and for a morph delta they are a target
+ // that does nothing — which is exactly what a Draco blob leaves behind,
+ // since the extension compresses the attributes and not the targets.
+ if (acc && acc.bufferView === undefined && !acc.sparse) {
+ warnings.push(`${label}: morph target "${names[t]}" declares ${semantic}`
+ + ' deltas with no data — that target moves nothing');
+ continue;
+ }
+ const values = readAccessor(src, index);
+ if (values.length !== vertexCount * 3) {
+ warnings.push(`${label}: morph target "${names[t]}" carries`
+ + ` ${values.length / 3} ${semantic} deltas for ${vertexCount} vertices`
+ + ' — that target moves nothing');
+ continue;
+ }
+ const base = t * vertexCount * comps + at;
+ for (let i = 0; i < vertexCount; i++) {
+ for (let c = 0; c < 3; c++) deltas[base + i * comps + c] = values[i * 3 + c] ?? 0;
+ }
+ }
+ }
+ return { names, hasNormals: carriesNormals, deltas };
+}
+
/** glTF's sampler interpolation → the engine's, which spells the same curves. */
const INTERPOLATION: Record<string, string> = {
LINEAR: 'linear', STEP: 'step', CUBICSPLINE: 'hermite',
@@ -848,11 +917,6 @@ export async function importGltfMeshes(
for (const name of Object.keys(prim.extensions ?? {})) {
if (name !== 'KHR_draco_mesh_compression') 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`);
- }
const posIndex = prim.attributes.POSITION;
if (posIndex === undefined) {
warnings.push(`${label}: no POSITION — skipped`);
@@ -992,12 +1056,15 @@ export async function importGltfMeshes(
}
}
+ const morph = morphTargets(src, mesh, prim, vertexCount, !!normals, label, warnings);
+
meshIndexOf.set(`${meshIndex}_${primIndex}`, meshes.length);
meshes.push({
name: single ? stem : `${stem}_${meshIndex}_${primIndex}`,
data: {
channels, vertexStride, vertexCount, vertices, indices, aabbMin: min, aabbMax: max,
...(skinned ? { inverseBindMatrices: bindMatrices(src, skin!, warnings) } : {}),
+ ...(morph ? { morph } : {}),
},
vertexCount,
triangleCount: indices.length / 3,
diff --git a/pipeline/tests/gltf-import.test.ts b/pipeline/tests/gltf-import.test.ts
index e148c64a6..6d45f62ab 100644
--- a/pipeline/tests/gltf-import.test.ts
+++ b/pipeline/tests/gltf-import.test.ts
@@ -339,7 +339,7 @@ describe('glTF material import', () => {
expect(meshes[0]!.material?.baseColorTexture?.settings?.wrapMode).toBe('clamp');
});
- it('reports deformation it cannot carry: morph targets, and joints nothing binds', async () => {
+ it('reports deformation it cannot carry: joints nothing binds', async () => {
const doc = {
...withInlineImage(),
skins: [{}],
@@ -347,11 +347,8 @@ describe('glTF material import', () => {
};
const { warnings } = await 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('a skin naming joints');
+ expect(warnings.join('\n')).toContain('a skin naming joints');
});
it('reports a uv rewrite it does not apply', async () => {
@@ -947,3 +944,98 @@ describe('a second UV set', () => {
expect(uvsOf(mesh, MeshChannel.TexCoord1)).toEqual([]);
});
});
+
+/**
+ * A triangle with two shapes to blend towards: the first moves one vertex, the
+ * second moves another AND turns its normal. The two differ on purpose — a
+ * reader that mixed the targets up would still find deltas, just the wrong ones.
+ */
+function morphGltf(opts: { names?: string[]; badCount?: boolean } = {}): Uint8Array {
+ const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+ const normals = new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]);
+ const uv = new Float32Array([0, 0, 1, 0, 0, 1]);
+ const indices = new Uint16Array([0, 1, 2]);
+ const shape0 = new Float32Array([0, 0, 0, 0, 2, 0, 0, 0, 0]);
+ const shape1 = new Float32Array([0, 0, 0, 0, 0, 0, 3, 0, 0]);
+ const shape1Normals = new Float32Array([0, 0, 0, 0, 0, 0, 0, 1, -1]);
+ const parts = [positions, normals, uv, indices, shape0, shape1, shape1Normals];
+ const bytes = Buffer.concat(parts.map((a) => Buffer.from(a.buffer)));
+ const offsets: number[] = [];
+ let at = 0;
+ for (const part of parts) { offsets.push(at); at += part.byteLength; }
+
+ const doc = {
+ asset: { version: '2.0' },
+ buffers: [{ byteLength: bytes.length, uri: `data:application/octet-stream;base64,${bytes.toString('base64')}` }],
+ bufferViews: parts.map((part, i) => ({
+ buffer: 0, byteOffset: offsets[i], byteLength: part.byteLength,
+ })),
+ accessors: [
+ { bufferView: 0, componentType: 5126, count: 3, type: 'VEC3' },
+ { bufferView: 1, componentType: 5126, count: 3, type: 'VEC3' },
+ { bufferView: 2, componentType: 5126, count: 3, type: 'VEC2' },
+ { bufferView: 3, componentType: 5123, count: 3, type: 'SCALAR' },
+ { bufferView: 4, componentType: 5126, count: opts.badCount ? 2 : 3, type: 'VEC3' },
+ { bufferView: 5, componentType: 5126, count: 3, type: 'VEC3' },
+ { bufferView: 6, componentType: 5126, count: 3, type: 'VEC3' },
+ ],
+ meshes: [{
+ name: 'Face',
+ ...(opts.names ? { extras: { targetNames: opts.names } } : {}),
+ primitives: [{
+ attributes: { POSITION: 0, NORMAL: 1, TEXCOORD_0: 2 }, indices: 3, mode: 4,
+ targets: [{ POSITION: 4 }, { POSITION: 5, NORMAL: 6 }],
+ }],
+ }],
+ nodes: [{ mesh: 0 }], scenes: [{ nodes: [0] }], scene: 0,
+ };
+ return new TextEncoder().encode(JSON.stringify(doc));
+}
+
+describe('glTF morph targets', () => {
+ it('carries the deltas each target moves its vertices by', async () => {
+ const { meshes, warnings } = await importGltfMeshes(
+ morphGltf({ names: ['Smile', 'Blink'] }), 'face');
+
+ const morph = meshes[0]!.data.morph!;
+ expect(morph.names).toEqual(['Smile', 'Blink']);
+ expect(warnings.join('\n')).not.toMatch(/morph target/);
+
+ // Six floats per vertex — the geometry has normals and the second target
+ // bends them, so every target is stored with room for one.
+ expect(morph.hasNormals).toBe(true);
+ expect(morph.deltas).toHaveLength(2 * 3 * 6);
+ // Target 0 lifts vertex 1 by 2 along y and touches nothing else.
+ expect(morph.deltas[1 * 6 + 1]).toBe(2);
+ expect([...morph.deltas.subarray(0, 18)].filter((d) => d !== 0)).toHaveLength(1);
+ // Target 1 moves vertex 2 along x and turns its normal.
+ expect(morph.deltas[18 + 2 * 6]).toBe(3);
+ expect(morph.deltas[18 + 2 * 6 + 4]).toBe(1);
+ expect(morph.deltas[18 + 2 * 6 + 5]).toBe(-1);
+ });
+
+ it('names a target the file left unnamed by its position', async () => {
+ const { meshes } = await importGltfMeshes(morphGltf(), 'face');
+ // Positional because a weight is: an unnamed target still has to be
+ // addressable, and calling it nothing would renumber the ones behind it.
+ expect(meshes[0]!.data.morph?.names).toEqual(['target 0', 'target 1']);
+ });
+
+ it('keeps a target whose deltas do not cover every vertex, saying it moves nothing', async () => {
+ const { meshes, warnings } = await importGltfMeshes(
+ morphGltf({ names: ['Smile', 'Blink'], badCount: true }), 'face');
+
+ const morph = meshes[0]!.data.morph!;
+ expect(warnings.join('\n')).toContain('"Smile" carries 2 POSITION deltas for 3 vertices');
+ // Kept, not dropped: weights address targets by position, so removing one
+ // would re-aim every weight behind it at the wrong shape.
+ expect(morph.names).toEqual(['Smile', 'Blink']);
+ expect([...morph.deltas.subarray(0, 18)]).toEqual(new Array(18).fill(0));
+ expect(morph.deltas[18 + 2 * 6]).toBe(3);
+ });
+
+ it('leaves geometry with no targets without a morph section', async () => {
+ const { meshes } = await importGltfMeshes(gltf(withInlineImage()), 'model');
+ expect(meshes[0]!.data.morph).toBeUndefined();
+ });
+});
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index a80ecd0eb..43330e086 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 94 beta · 1719 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1720 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -5095,11 +5095,19 @@ aabbMin: [number, number, number]
channels: MeshChannelDesc[]
indices: Uint32Array<ArrayBufferLike>
inverseBindMatrices: Float32Array<ArrayBufferLike> | undefined
+morph: MeshMorphData | undefined
vertexCount: number
vertexStride: number
vertices: Uint8Array<ArrayBufferLike>
```
+## MeshMorphData — interface @experimental
+```
+deltas: Float32Array<ArrayBufferLike>
+hasNormals: boolean
+names: string[]
+```
+
## MeshRenderer — const @experimental
```
BuiltinComponentDef<MeshRendererData>
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 8c496e792..1690633cb 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 99 beta · 1738 experimental · 3 deprecated
+Symbols: 114 public · 99 beta · 1739 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -5108,11 +5108,19 @@ aabbMin: [number, number, number]
channels: MeshChannelDesc[]
indices: Uint32Array<ArrayBufferLike>
inverseBindMatrices: Float32Array<ArrayBufferLike> | undefined
+morph: MeshMorphData | undefined
vertexCount: number
vertexStride: number
vertices: Uint8Array<ArrayBufferLike>
```
+## MeshMorphData — interface @experimental
+```
+deltas: Float32Array<ArrayBufferLike>
+hasNormals: boolean
+names: string[]
+```
+
## MeshRenderer — const @experimental
```
BuiltinComponentDef<MeshRendererData>
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index d6076f554..477698b31 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 96 beta · 1718 experimental · 3 deprecated
+Symbols: 114 public · 96 beta · 1719 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5090,11 +5090,19 @@ aabbMin: [number, number, number]
channels: MeshChannelDesc[]
indices: Uint32Array<ArrayBufferLike>
inverseBindMatrices: Float32Array<ArrayBufferLike> | undefined
+morph: MeshMorphData | undefined
vertexCount: number
vertexStride: number
vertices: Uint8Array<ArrayBufferLike>
```
+## MeshMorphData — interface @experimental
+```
+deltas: Float32Array<ArrayBufferLike>
+hasNormals: boolean
+names: string[]
+```
+
## MeshRenderer — const @experimental
```
BuiltinComponentDef<MeshRendererData>
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 8d3889d85..78679b76a 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 94 beta · 1740 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1741 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5090,11 +5090,19 @@ aabbMin: [number, number, number]
channels: MeshChannelDesc[]
indices: Uint32Array<ArrayBufferLike>
inverseBindMatrices: Float32Array<ArrayBufferLike> | undefined
+morph: MeshMorphData | undefined
vertexCount: number
vertexStride: number
vertices: Uint8Array<ArrayBufferLike>
```
+## MeshMorphData — interface @experimental
+```
+deltas: Float32Array<ArrayBufferLike>
+hasNormals: boolean
+names: string[]
+```
+
## MeshRenderer — const @experimental
```
BuiltinComponentDef<MeshRendererData>
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 79a469830..39ebf36dc 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 114 public · 94 beta · 1730 experimental · 3 deprecated
+Symbols: 114 public · 94 beta · 1731 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -5097,11 +5097,19 @@ aabbMin: [number, number, number]
channels: MeshChannelDesc[]
indices: Uint32Array<ArrayBufferLike>
inverseBindMatrices: Float32Array<ArrayBufferLike> | undefined
+morph: MeshMorphData | undefined
vertexCount: number
vertexStride: number
vertices: Uint8Array<ArrayBufferLike>
```
+## MeshMorphData — interface @experimental
+```
+deltas: Float32Array<ArrayBufferLike>
+hasNormals: boolean
+names: string[]
+```
+
## MeshRenderer — const @experimental
```
BuiltinComponentDef<MeshRendererData>
diff --git a/sdk/src/asset/meshFormat.ts b/sdk/src/asset/meshFormat.ts
index 9a235ff07..733a18a6a 100644
--- a/sdk/src/asset/meshFormat.ts
+++ b/sdk/src/asset/meshFormat.ts
@@ -12,10 +12,12 @@
/** Magic 'ESMH', little-endian. */
const MAGIC = 0x484d5345;
-const VERSION = 2;
+const VERSION = 3;
/** v1 had no joint count; a file that predates skinning reads with the shorter one. */
const HEADER_BYTES_V1 = 44;
-const HEADER_BYTES = 48;
+/** v2 ended at the joint count; a file that predates morph targets reads with that. */
+const HEADER_BYTES_V2 = 48;
+const HEADER_BYTES = 56;
const CHANNEL_BYTES = 8;
/** One inverse bind matrix: 16 floats. */
const MATRIX_BYTES = 64;
@@ -72,6 +74,27 @@ export interface MeshChannelDesc {
offset: number;
}
+/**
+ * The shapes a mesh can be blended towards, as offsets from the vertices it
+ * carries. Deltas rather than whole positions because a target usually moves a
+ * fraction of the mesh, and what is stored is then zero wherever it says nothing.
+ */
+export interface MeshMorphData {
+ /** One name per target, in the order weights address them. */
+ names: string[];
+ /** Whether each target carries a normal delta behind its position delta.
+ * A mesh-wide fact, not a per-target one: the deltas are one packed array
+ * and a reader cannot find target `i` without a fixed stride. */
+ hasNormals: boolean;
+ /**
+ * `targets * vertexCount * (hasNormals ? 6 : 3)` floats: for each target,
+ * for each vertex, the position delta and — when carried — the normal delta.
+ * Float32 and not half: half is what the GPU wants, and narrowing here would
+ * make every other reader (a collider, an editor preview) inherit that choice.
+ */
+ deltas: Float32Array;
+}
+
export interface MeshData {
channels: MeshChannelDesc[];
vertexStride: number;
@@ -88,6 +111,13 @@ export interface MeshData {
* geometry that is not skinned.
*/
inverseBindMatrices?: Float32Array;
+ /**
+ * The shapes this geometry can be blended towards. Like the bind pose, it
+ * lives with the vertices because it is indexed BY them — one delta per
+ * vertex per target, so a file carrying the two apart could not say which
+ * vertex a delta moves.
+ */
+ morph?: MeshMorphData;
}
/** Bytes one component of a channel type occupies. */
@@ -118,11 +148,20 @@ export function packChannels(semantics: { semantic: number; components: number;
return { channels, vertexStride: offset };
}
+/** Bytes the target names occupy: each carries its own length, the whole padded
+ * to 4 so the deltas behind it start where a float may be written. */
+function morphNameBytes(names: Uint8Array[]): number {
+ return (names.reduce((n, b) => n + 2 + b.length, 0) + 3) & ~3;
+}
+
export function encodeMesh(data: MeshData): Uint8Array {
const jointCount = (data.inverseBindMatrices?.length ?? 0) / 16;
+ const names = (data.morph?.names ?? []).map(n => new TextEncoder().encode(n));
+ const nameBytes = morphNameBytes(names);
+ const deltaFloats = data.morph?.deltas.length ?? 0;
const size = HEADER_BYTES + data.channels.length * CHANNEL_BYTES
+ data.vertexCount * data.vertexStride + data.indices.length * 4
- + jointCount * MATRIX_BYTES;
+ + jointCount * MATRIX_BYTES + nameBytes + deltaFloats * 4;
const out = new Uint8Array(size);
const view = new DataView(out.buffer);
@@ -137,6 +176,9 @@ export function encodeMesh(data: MeshData): Uint8Array {
view.setFloat32(32 + i * 4, data.aabbMax[i], true);
}
view.setUint32(44, jointCount, true);
+ view.setUint16(48, names.length, true);
+ view.setUint16(50, data.morph?.hasNormals ? 1 : 0, true);
+ view.setUint32(52, nameBytes, true);
let at = HEADER_BYTES;
for (const c of data.channels) {
@@ -159,6 +201,19 @@ export function encodeMesh(data: MeshData): Uint8Array {
view.setFloat32(at + i * 4, data.inverseBindMatrices[i]!, true);
}
}
+ at += jointCount * MATRIX_BYTES;
+ if (data.morph) {
+ let nameAt = at;
+ for (const name of names) {
+ view.setUint16(nameAt, name.length, true);
+ out.set(name, nameAt + 2);
+ nameAt += 2 + name.length;
+ }
+ at += nameBytes;
+ for (let i = 0; i < data.morph.deltas.length; i++) {
+ view.setFloat32(at + i * 4, data.morph.deltas[i]!, true);
+ }
+ }
return out;
}
@@ -190,8 +245,13 @@ export function decodeMesh(bytes: Uint8Array): MeshData {
const aabbMax: [number, number, number] = [
view.getFloat32(32, true), view.getFloat32(36, true), view.getFloat32(40, true)];
- const headerBytes = version >= 2 ? HEADER_BYTES : HEADER_BYTES_V1;
+ const headerBytes = version >= 3 ? HEADER_BYTES
+ : version >= 2 ? HEADER_BYTES_V2 : HEADER_BYTES_V1;
const jointCount = version >= 2 ? view.getUint32(44, true) : 0;
+ const morphCount = version >= 3 ? view.getUint16(48, true) : 0;
+ const morphNormals = version >= 3 && view.getUint16(50, true) !== 0;
+ const nameBytes = version >= 3 ? view.getUint32(52, true) : 0;
+ const morphComponents = morphNormals ? 6 : 3;
const channels: MeshChannelDesc[] = [];
let at = headerBytes;
@@ -210,7 +270,9 @@ export function decodeMesh(bytes: Uint8Array): MeshData {
}
const vertexBytes = vertexCount * vertexStride;
- const expected = at + vertexBytes + indexCount * 4 + jointCount * MATRIX_BYTES;
+ const deltaFloats = morphCount * vertexCount * morphComponents;
+ const expected = at + vertexBytes + indexCount * 4 + jointCount * MATRIX_BYTES
+ + nameBytes + deltaFloats * 4;
if (bytes.byteLength < expected) {
throw new Error(`.esmesh is truncated: ${bytes.byteLength} bytes, header describes ${expected}`);
}
@@ -222,12 +284,35 @@ export function decodeMesh(bytes: Uint8Array): MeshData {
for (let i = 0; i < indexCount; i++) indices[i] = view.getUint32(indexBase + i * 4, true);
const out: MeshData = { channels, vertexStride, vertexCount, vertices, indices, aabbMin, aabbMax };
+ const bindBase = indexBase + indexCount * 4;
if (jointCount > 0) {
- const base = indexBase + indexCount * 4;
const matrices = new Float32Array(jointCount * 16);
- for (let i = 0; i < matrices.length; i++) matrices[i] = view.getFloat32(base + i * 4, true);
+ for (let i = 0; i < matrices.length; i++) {
+ matrices[i] = view.getFloat32(bindBase + i * 4, true);
+ }
out.inverseBindMatrices = matrices;
}
+ if (morphCount > 0) {
+ const nameBase = bindBase + jointCount * MATRIX_BYTES;
+ const names: string[] = [];
+ let nameAt = nameBase;
+ for (let i = 0; i < morphCount; i++) {
+ const length = view.getUint16(nameAt, true);
+ // Read against the section's own size rather than the file's: a length
+ // that runs past it names bytes that belong to the deltas, and the
+ // string that comes back would look like a target this mesh has.
+ if (nameAt + 2 + length > nameBase + nameBytes) {
+ throw new Error(`.esmesh morph target ${i} names ${length} bytes,`
+ + ' which runs past the name section');
+ }
+ names.push(new TextDecoder().decode(bytes.subarray(nameAt + 2, nameAt + 2 + length)));
+ nameAt += 2 + length;
+ }
+ const deltaBase = nameBase + nameBytes;
+ const deltas = new Float32Array(deltaFloats);
+ for (let i = 0; i < deltas.length; i++) deltas[i] = view.getFloat32(deltaBase + i * 4, true);
+ out.morph = { names, hasNormals: morphNormals, deltas };
+ }
return out;
}
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index f2f8b62f9..9769229ef 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -130,7 +130,7 @@ export { setTextureBudget, getResourceStats, trimTextureCache, type ResourceStat
*/
export {
MeshChannel, MeshChannelType, MESH_MAX_BONES, packChannels, encodeMesh, decodeMesh,
- encodeChannelTable, type MeshChannelDesc, type MeshData,
+ encodeChannelTable, type MeshChannelDesc, type MeshData, type MeshMorphData,
} from './asset/meshFormat';
export type { MeshResult } from './asset/loaders/MeshAssetLoader';
/**
diff --git a/sdk/tests/mesh-format-channels.test.ts b/sdk/tests/mesh-format-channels.test.ts
index b707ba45f..820d0b207 100644
--- a/sdk/tests/mesh-format-channels.test.ts
+++ b/sdk/tests/mesh-format-channels.test.ts
@@ -32,8 +32,8 @@ function mesh(): Uint8Array {
});
}
-/** Where the channel table starts: the v2 header is 48 bytes. */
-const TABLE = 48;
+/** Where the channel table starts: the v3 header is 56 bytes. */
+const TABLE = 56;
describe('decodeMesh channel table', () => {
it('refuses a semantic the format does not define', () => {
diff --git a/sdk/tests/mesh-format-morph.test.ts b/sdk/tests/mesh-format-morph.test.ts
new file mode 100644
index 000000000..c45f64bf7
--- /dev/null
+++ b/sdk/tests/mesh-format-morph.test.ts
@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file The shapes a morphable `.esmesh` carries, beside the pose it may also
+ * carry, and the older files that have neither.
+ *
+ * A delta is addressed by (target, vertex), so what this pins is that the two
+ * indices come back meaning the same thing they went in meaning — a stride read
+ * one target off is geometry that deforms into the wrong shape.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ encodeMesh, decodeMesh, packChannels, MeshChannel, MeshChannelType, type MeshData,
+} from '../src/asset/meshFormat';
+
+const POSITION_ONLY = packChannels([
+ { semantic: MeshChannel.Position, components: 3, type: MeshChannelType.Float32 },
+]);
+
+/** Three vertices and whatever the caller morphs or poses them by. */
+function mesh(extra: Partial<MeshData>): MeshData {
+ return {
+ ...POSITION_ONLY, vertexCount: 3,
+ vertices: new Uint8Array(3 * POSITION_ONLY.vertexStride),
+ indices: Uint32Array.from([0, 1, 2]),
+ aabbMin: [0, 0, 0], aabbMax: [1, 1, 0],
+ ...extra,
+ };
+}
+
+/** Two targets over three vertices: the first lifts vertex 1, the second vertex 2. */
+function twoTargets(): Float32Array {
+ const deltas = new Float32Array(2 * 3 * 3);
+ deltas[1 * 3 + 1] = 4; // target 0, vertex 1, y
+ deltas[9 + 2 * 3 + 1] = 7; // target 1, vertex 2, y
+ return deltas;
+}
+
+describe('.esmesh morph targets', () => {
+ it('round-trips the names and the deltas each one addresses', () => {
+ const decoded = decodeMesh(encodeMesh(mesh({
+ morph: { names: ['Smile', 'Blink'], hasNormals: false, deltas: twoTargets() },
+ })));
+
+ expect(decoded.morph?.names).toEqual(['Smile', 'Blink']);
+ expect(decoded.morph?.hasNormals).toBe(false);
+ expect(decoded.morph?.deltas).toHaveLength(18);
+ expect(decoded.morph!.deltas[1 * 3 + 1]).toBe(4);
+ expect(decoded.morph!.deltas[9 + 2 * 3 + 1]).toBe(7);
+ // The rest is untouched geometry: a target says nothing where it is zero.
+ expect([...decoded.morph!.deltas].filter((d) => d !== 0)).toHaveLength(2);
+ });
+
+ it('carries a normal delta behind each position delta when the targets have one', () => {
+ const deltas = new Float32Array(1 * 3 * 6);
+ deltas[0] = 1; // vertex 0, position.x
+ deltas[3] = -1; // vertex 0, normal.x
+ deltas[6 + 4] = 0.5; // vertex 1, normal.y
+ const decoded = decodeMesh(encodeMesh(mesh({
+ morph: { names: ['Pucker'], hasNormals: true, deltas },
+ })));
+
+ expect(decoded.morph?.hasNormals).toBe(true);
+ // Six floats per vertex, not three: the stride is what tells a reader which
+ // vertex a delta belongs to, and it is the flag above that sets it.
+ expect(decoded.morph?.deltas).toHaveLength(18);
+ expect(decoded.morph!.deltas[3]).toBe(-1);
+ expect(decoded.morph!.deltas[10]).toBe(0.5);
+ });
+
+ it('keeps the bind pose and the shapes apart when a mesh has both', () => {
+ const bind = new Float32Array(16);
+ for (let c = 0; c < 4; c++) bind[c * 5] = 1;
+ bind[12] = 9;
+ const decoded = decodeMesh(encodeMesh(mesh({
+ inverseBindMatrices: bind,
+ morph: { names: ['Jaw'], hasNormals: false, deltas: Float32Array.from(
+ { length: 9 }, (_, i) => i + 1) },
+ })));
+
+ expect(decoded.inverseBindMatrices![12]).toBe(9);
+ expect([...decoded.morph!.deltas]).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+ });
+
+ it('leaves geometry with no shapes without a morph section', () => {
+ expect(decodeMesh(encodeMesh(mesh({}))).morph).toBeUndefined();
+ });
+
+ it('reads a file written before the morph section existed', () => {
+ const bytes = encodeMesh(mesh({}));
+ // The same file as a v2 writer would have produced: a 48-byte header that
+ // ends at the joint count, so the channel table starts eight bytes earlier.
+ const older = new Uint8Array(bytes.byteLength - 8);
+ older.set(bytes.subarray(0, 48));
+ older.set(bytes.subarray(56), 48);
+ new DataView(older.buffer).setUint16(4, 2, true);
+
+ const decoded = decodeMesh(older);
+ expect(decoded.vertexCount).toBe(3);
+ expect([...decoded.indices]).toEqual([0, 1, 2]);
+ expect(decoded.morph).toBeUndefined();
+ });
+
+ it('refuses a name that runs past the section it lives in', () => {
+ const bytes = encodeMesh(mesh({
+ morph: { names: ['Smile'], hasNormals: false, deltas: new Float32Array(9) },
+ }));
+ // The name length alone, raised past the section: the bytes behind it are
+ // deltas, and a reader that took them would hand back a target name made of
+ // float bits — a shape the mesh does not have, under a name nothing wrote.
+ const view = new DataView(bytes.buffer, bytes.byteOffset);
+ const nameAt = bytes.byteLength - 8 - 9 * 4;
+ view.setUint16(nameAt, 40, true);
+
+ expect(() => decodeMesh(bytes)).toThrow(/runs past the name section/);
+ });
+});