Skip to content

3D engine that AI agents drive

Bind surface attachments to healthy triangles and name asset characters with no clips (#2503)

Nguyen Xuan An72c20a2f4b59
diff --git a/changes/2503.md b/changes/2503.md
new file mode 100644
index 00000000..0dfaef7c
--- /dev/null
+++ b/changes/2503.md
@@ -0,0 +1 @@
+- Surface attachments reject only a zero-area bound triangle, not any zero-area triangle of the mesh (#2503)
diff --git a/changes/2504.md b/changes/2504.md
new file mode 100644
index 00000000..2c87dfe1
--- /dev/null
+++ b/changes/2504.md
@@ -0,0 +1 @@
+- An asset character whose file has no animation clips now throws a message that says so, not an index range from 0 to -1 (#2504)
diff --git a/docs/surface-attachment.md b/docs/surface-attachment.md
index 07cbc969..bb7bfc85 100644
--- a/docs/surface-attachment.md
+++ b/docs/surface-attachment.md
@@ -53,7 +53,7 @@ Its nonempty triangle index buffer must use `Uint32Array`.
The retained target matrix must use `Float32Array(16)`.
It must remain finite, affine, and nonsingular.
Binding checks all target vertices and triangle indices within the supplied budgets.
-It rejects degenerate base triangles.
+It rejects a zero-area bound triangle; other triangles of the target may be degenerate.
Morph and skin bindings use the renderer's existing geometry validators.
These validators check all declared channels and the initial deformation pose once at binding.
diff --git a/src/game-animation.js b/src/game-animation.js
index 9f43b5e1..99e3d380 100644
--- a/src/game-animation.js
+++ b/src/game-animation.js
@@ -141,9 +141,11 @@ function assetCharacterClips(animation, ownId, assets, path) {
for (const [name, definition] of Object.entries(animation.clips)) {
const sourceId = definition.from.asset ?? ownId;
const source = decodedAsset(assets, sourceId, `${path}.clips.${name}.from.asset`);
+ const clipCount = source.animations?.length ?? 0;
+ if (clipCount === 0) fail(`${path}.clips.${name}.from`, `names asset ${sourceId.slice(0, 12)}, which has no animation clips. Pass an asset that has clips.`);
const gltfAnimation = source.animations[definition.from.clip];
if (!gltfAnimation) {
- fail(`${path}.clips.${name}.from.clip`, `is ${definition.from.clip}, but asset ${sourceId.slice(0, 12)} has ${source.animations.length} clips. Use an index from 0 to ${source.animations.length - 1}.`);
+ fail(`${path}.clips.${name}.from.clip`, `is ${definition.from.clip}, but asset ${sourceId.slice(0, 12)} has ${clipCount} clips. Use an index from 0 to ${clipCount - 1}.`);
}
if (sourceId === ownId) {
clips[name] = clipFromGltfAnimation(gltfAnimation, { loop: definition.loop });
diff --git a/src/surface-attachment.js b/src/surface-attachment.js
index 774a719a..0ecb3989 100644
--- a/src/surface-attachment.js
+++ b/src/surface-attachment.js
@@ -62,23 +62,24 @@ function validateGeometry(geometry, maxVertices, maxTriangles) {
if (!Number.isFinite(length) || Math.abs(length - 1) > 0.001) throw new RangeError('Target normals must remain finite unit vectors.');
}
for (const index of indices) if (index >= vertexCount) throw new RangeError('Target triangle index exceeds the vertex count.');
- for (let offset = 0; offset < indices.length; offset += 3) {
- const first = indices[offset] * 3;
- const second = indices[offset + 1] * 3;
- const third = indices[offset + 2] * 3;
- const edgeFirstX = positions[second] - positions[first];
- const edgeFirstY = positions[second + 1] - positions[first + 1];
- const edgeFirstZ = positions[second + 2] - positions[first + 2];
- const edgeSecondX = positions[third] - positions[first];
- const edgeSecondY = positions[third + 1] - positions[first + 1];
- const edgeSecondZ = positions[third + 2] - positions[first + 2];
- if (Math.hypot(edgeFirstY * edgeSecondZ - edgeFirstZ * edgeSecondY, edgeFirstZ * edgeSecondX - edgeFirstX * edgeSecondZ, edgeFirstX * edgeSecondY - edgeFirstY * edgeSecondX) === 0) {
- throw new RangeError('Attachment target contains a degenerate triangle.');
- }
- }
return { vertexCount, triangleCount };
}
+function requireAreaTriangle(positions, indices, triangle) {
+ const first = indices[triangle * 3] * 3;
+ const second = indices[triangle * 3 + 1] * 3;
+ const third = indices[triangle * 3 + 2] * 3;
+ const edgeFirstX = positions[second] - positions[first];
+ const edgeFirstY = positions[second + 1] - positions[first + 1];
+ const edgeFirstZ = positions[second + 2] - positions[first + 2];
+ const edgeSecondX = positions[third] - positions[first];
+ const edgeSecondY = positions[third + 1] - positions[first + 1];
+ const edgeSecondZ = positions[third + 2] - positions[first + 2];
+ if (Math.hypot(edgeFirstY * edgeSecondZ - edgeFirstZ * edgeSecondY, edgeFirstZ * edgeSecondX - edgeFirstX * edgeSecondZ, edgeFirstX * edgeSecondY - edgeFirstY * edgeSecondX) === 0) {
+ throw new RangeError('Attachment triangle is degenerate; pass a triangle with nonzero area.');
+ }
+}
+
function rounded(value) {
const result = Math.fround(value);
if (!Number.isFinite(result)) throw new RangeError('Attachment deformation exceeds finite Float32 arithmetic.');
@@ -96,6 +97,7 @@ export function createSurfaceAttachment(target, options = {}) {
const counts = validateGeometry(geometry, maxVertices, maxTriangles);
const triangle = options.triangle;
if (!Number.isSafeInteger(triangle) || triangle < 0 || triangle >= counts.triangleCount) throw new RangeError('Attachment triangle must reference an original target triangle.');
+ requireAreaTriangle(geometry.positions, geometry.indices, triangle);
const inputWeights = options.barycentric;
if ((!Array.isArray(inputWeights) && !ArrayBuffer.isView(inputWeights)) || inputWeights.length !== 3) throw new TypeError('Attachment barycentric coordinates require three components.');
const barycentric = new Float64Array(3);
diff --git a/tests/game-animation.test.js b/tests/game-animation.test.js
index 0c5afd4e..832522e8 100644
--- a/tests/game-animation.test.js
+++ b/tests/game-animation.test.js
@@ -297,3 +297,15 @@ test('clearing the game removes the animation with it', () => {
scene.apply([{ type: 'set-game', game: null }], { expectedRevision: scene.revision });
assert.equal(scene.exportRecipe().game, undefined);
});
+
+test('an asset character whose file has no clips says so instead of offering an index from 0 to -1', async () => {
+ const { createGameAnimation } = await import('../src/game-animation.js');
+ const { assetCopyKey } = await import('../src/agent-scene-assets.js');
+ const assetId = 'ab'.repeat(32);
+ const animation = { clips: { walk: { from: { clip: 0 } } }, layers: [{ name: 'base', states: [{ name: 'walk', clip: 'walk' }] }] };
+ const nodes = [{ id: 'hero', asset: { id: assetId } }];
+ for (const asset of [{ animations: [], nodes: [] }, { nodes: [] }]) {
+ const assets = new Map([[assetCopyKey(assetId, 0), asset]]);
+ assert.throws(() => createGameAnimation(animation, nodes, 'hero', { assets }), error => error instanceof RangeError && /has no animation clips/.test(error.message));
+ }
+});
diff --git a/tests/surface-attachment.test.js b/tests/surface-attachment.test.js
index bc868285..92626383 100644
--- a/tests/surface-attachment.test.js
+++ b/tests/surface-attachment.test.js
@@ -267,3 +267,13 @@ test('world clearance must remain outward and nonzero after Float32 rounding', (
const attachment = createSurfaceAttachment(part, { ...bind, clearance: 1 });
assert.equal(attachment.matrix[14], 1e6 + 1);
});
+
+test('a zero-area triangle elsewhere in the mesh does not block binding to a healthy triangle', () => {
+ const part = target();
+ part.geometry.positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0, 2, 2, 2]);
+ part.geometry.normals = new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]);
+ part.geometry.indices = new Uint32Array([0, 1, 2, 3, 3, 3]);
+ const attachment = createSurfaceAttachment(part, bind);
+ assert.equal(attachment.matrix.length, 16);
+ assert.throws(() => createSurfaceAttachment(part, { ...bind, triangle: 1 }), /triangle is degenerate/);
+});