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
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.jsonindex 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.tsindex 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']>[numbereturn 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.tsindex 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.mdindex 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 | undefinedvertexCount: numbervertexStride: numbervertices: 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.mdindex 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 | undefinedvertexCount: numbervertexStride: numbervertices: 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.mdindex 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 | undefinedvertexCount: numbervertexStride: numbervertices: 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.mdindex 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 | undefinedvertexCount: numbervertexStride: numbervertices: 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.mdindex 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 | undefinedvertexCount: numbervertexStride: numbervertices: 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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/);+ });+});