3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Warn when a part hangs off its support (#2210)
Nguyen Xuan An32316a2d7be5
diff --git a/changes/2210.md b/changes/2210.mdnew file mode 100644index 00000000..65b6239c--- /dev/null+++ b/changes/2210.md@@ -0,0 +1 @@+- Warn when a whole part hangs off its support: `scene_inspect`, `scene_apply` and `scene_review` list an `unsupported-part` warning with the unsupported share when under 70 percent of a part's footprint has a surface within 2 cm below it (#2210)diff --git a/changes/2210.size.md b/changes/2210.size.mdnew file mode 100644index 00000000..07eb9428--- /dev/null+++ b/changes/2210.size.md@@ -0,0 +1,2 @@+- scene:agent-scene+lazy: the unsupported-part check is one on-demand module (about 2.6 KB gzip) that only the MCP preview and hosts that load every module pay for; it catches a building hanging off a rock, which no existing lint saw.+- goal:agent-scene: the core entry gains one call to the on-demand module (a few dozen bytes gzip); the check itself stays out of the core bundle.diff --git a/docs/mcp.md b/docs/mcp.mdindex 7ab11baf..3ca26cef 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -193,6 +193,8 @@ Every tool schema is read on every turn, so `node scripts/measure-tool-cost.mjs``mesh_inspect` lint adds warnings for `intersecting-parts`, `self-intersection`, `thin-wall`, `floating-part` and `asymmetric`. They never set `ok` to false, run within face budgets, and list any check they skipped in `skippedChecks`. `scene_inspect` returns a `diagnostics` list only when there is something to say: ignored material fields, blended transmission, unused materials or geometries, and for imported assets the decoder's not-drawn features, rigs with no joints or no skin, and assets with no clips. Each item has `kind`, `severity`, `target`, `message` and `fix`.+`scene_inspect` (and so `scene_apply` and `scene_review`) adds an `unsupported-part` warning when a part hangs off what it rests on: a building with half its footprint past the edge of a rock. It casts 16 rays up from a grid over the part's footprint, at its lowest point; a ray is held up when another part has a surface within 2 cm of that point, or inside the part's own height (a building sunk into terrain). The warning names the part, the support and the unsupported share, and fires when under 70 percent of the footprint is held up. It stays quiet for a part with nothing under it at all (hovering on purpose), a part whose supports all sit inside its own footprint (a roof over walls, a table top on one pedestal), the lowest parts of the scene (they rest on the floor), animated, simulated and particle nodes, clouds and blended or additive parts. It checks the 64 largest footprints, skips parts under 10 cm wide and skips scenes over 400,000 triangles. The check lives in `src/unsupported-part.js`, loads on demand and reads the parts as drawn at the rest pose.+`scene_look` keeps the PNG under the 1 MiB response budget by itself: when a busy picture (planks, bricks, emissive text) encodes over it, the preview renders again at 0.75 of the size, up to four times with the aspect kept, and the metadata names the size that came back (`returnedWidth`, `returnedHeight`, `note`). It fails only when the smallest step still does not fit.`scene_look` returns the same kind of `diagnostics` list next to the picture, so an agent can check a frame without reading it. The findings carry the part names and the numbers in fields, and each list is capped (8 parts per finding, 8 findings per kind, with `nodeCount` or `droppedCount` saying how many were left out):diff --git a/src/agent-scene-modules.js b/src/agent-scene-modules.jsindex 99c29a23..268b3b28 100644--- a/src/agent-scene-modules.js+++ b/src/agent-scene-modules.js@@ -41,6 +41,7 @@ const MODULE_LOADERS = {lineArt: () => import('./line-art.js'),viewTransform: () => import('./view-transform-shader.js'),coplanar: () => import('./coplanar-overlap.js'),+ unsupportedPart: () => import('./unsupported-part.js'),physicalSky: () => import('./physical-sky.js'),floorSky: () => import('./floor-sky-visibility.js'),userPass: () => import('./user-pass.js'),@@ -103,6 +104,8 @@ const MODULE_MARKERS = {// and so does a recipe that names resolveCoplanar or places an asset, since glTF models nest facades a few millimetres apart.// A recipe of plain primitives in a host without it stays free of the 85 KB of flush code, so it needs no on-demand module.coplanar: ['"resolveCoplanar"', '"asset":{'],+ // The support check needs no recipe text: the MCP preview and loadAllAgentSceneModules load it, and a plain host stays free of it.+ unsupportedPart: [],// A closed room a sun lights gets the floor sky trace by default. The recipe text can not say whether a room is closed, so a recipe that names its sun loads it and the module skips an open scene.floorSky: ['"keyColor"', '"keyIntensity"'],physicalSky: ['"type":"physical"', '"type":"gradient"'],diff --git a/src/agent-scene.js b/src/agent-scene.jsindex ab95198a..ef37716d 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -2398,7 +2398,7 @@ export function createAgentScene(input, inputLimits = {}, options = {}) {return result;});const resident = geometryStats(ownedGeometryRecords());- const diagnostics = [...recipeDiagnostics(state.recipe), ...closedRoomProblems(), ...staleBakeProblems(), ...(state.bakeSkipped ? [agentSceneModule('bake').bakeSkippedDiagnostic(state.bakeSkipped)] : []),...coplanarProblems(), ...(state.particleSampler?.diagnostics() ?? [])];+ const diagnostics = [...recipeDiagnostics(state.recipe), ...closedRoomProblems(), ...staleBakeProblems(), ...(state.bakeSkipped ? [agentSceneModule('bake').bakeSkippedDiagnostic(state.bakeSkipped)] : []),...coplanarProblems(), ...(agentSceneModuleLoaded('unsupportedPart') ? agentSceneModule('unsupportedPart').unsupportedPartProblems(state.parts, state.recipe, revision) : []), ...(state.particleSampler?.diagnostics() ?? [])];return {revision, topologyRevision,...(state.recipe.motion?.ik?.length ? { motionIk: agentSceneModule('motion').compileAgentMotion(state.recipe.motion, state.recipe).sweepIk() } : {}),diff --git a/src/unsupported-part.js b/src/unsupported-part.jsnew file mode 100644index 00000000..c9d8cb30--- /dev/null+++ b/src/unsupported-part.js@@ -0,0 +1,247 @@+// Warns when a whole part hangs off the surface it rests on, such as a building with half its footprint past the edge of a+// rock. mesh_inspect's floating-part check only looks inside one mesh; this one looks across the parts of the scene.+//+// Each candidate part gets a grid of probe points over its footprint (its bounds seen from above). A probe is supported when+// a surface of another part lies within SUPPORT_TOLERANCE of the part's lowest point, or inside the part's own height (a+// building sunk into terrain). A part is reported only when it is partly supported, under SUPPORT_SHARE, and the support+// reaches past the part on some side: a roof over its walls or a table top on one pedestal has supports that sit inside its+// footprint, and a part with nothing under it at all is taken to hover on purpose. Both stay quiet.+// The check is deterministic, bounded (see the limits below) and reads no clock.+import { diagnostic } from './agent-diagnostics.js';+import { buildTriangleBvh } from './triangle-bvh.js';+import { createTracer } from './ray-query.js';++/** How far a surface may be from the part's lowest point, in metres, and still hold it up. */+export const SUPPORT_TOLERANCE = 0.02;+/** A part with a smaller supported share of its footprint is reported. */+export const SUPPORT_SHARE = 0.7;+/** Probes per side of the footprint grid: 16 probes, each the centre of a cell, so an edge never sits on a probe. */+export const PROBES_PER_SIDE = 4;+/** The largest footprint first, so a scene past this many parts still gets its biggest parts checked. */+export const MAXIMUM_CHECKED_PARTS = 64;+/** Parts narrower than this on either horizontal side are props, not buildings or objects that need a base. */+export const MINIMUM_FOOTPRINT = 0.1;+/** A scene with more triangles than this is not checked: the check builds one hierarchy over all of them. */+export const MAXIMUM_TRIANGLES = 400_000;+// Rays that pass through a part's own family (itself, its parents and children) before reaching another part.+const MAXIMUM_SELF_HITS = 6;+// The support must reach past the part by this share of the part's size to count as a base the part is perched on.+const OVERHANG_SHARE = 0.05;+const REPORTED_PARTS = 8;++function nodeIdsThatMove(recipe) {+ const ids = new Set();+ for (const track of recipe.motion?.tracks ?? []) {+ if (track.kind === 'node') ids.add(track.id);+ }+ for (const system of recipe.particles?.systems ?? []) {+ ids.add(system.node);+ ids.add(system.emitter?.mesh);+ }+ for (const entry of [...(recipe.cloth?.sheets ?? []), ...(recipe.cloth?.colliders ?? [])]) {+ ids.add(entry.node);+ }+ for (const body of recipe.physics?.bodies ?? []) {+ ids.add(body.node);+ }+ ids.delete(undefined);+ return ids;+}++/** Maps each node to the ids of its parents, nearest first. */+function ancestorLookup(nodes) {+ const parentOf = new Map(nodes.map(node => [node.id, node.parent ?? null]));+ const lookup = new Map();+ for (const node of nodes) {+ const chain = [];+ let current = parentOf.get(node.id);+ while (current && !chain.includes(current)) {+ chain.push(current);+ current = parentOf.get(current);+ }+ lookup.set(node.id, chain);+ }+ return lookup;+}++/** Part names that stand for something meant to float or move: animated, simulated, an emitter, a cloud, or a child of one. */+function partsMeantToFloat(recipe, ancestors) {+ const moving = nodeIdsThatMove(recipe);+ const cloudGeometries = new Set(recipe.geometries.filter(geometry => geometry.type === 'cloud').map(geometry => geometry.id));+ const floating = new Set();+ for (const node of recipe.nodes) {+ const isCloud = cloudGeometries.has(node.geometry);+ if (isCloud || moving.has(node.id) || ancestors.get(node.id).some(parent => moving.has(parent))) {+ floating.add(node.id);+ }+ }+ return floating;+}++function isTranslucent(part) {+ return ['blend', 'add'].includes(part.material?.alphaMode);+}++/** All parts as one triangle soup in world space, with the part each triangle belongs to and each part's bounds. */+function buildSupportWorld(parts) {+ let vertexTotal = 0;+ let indexTotal = 0;+ for (const part of parts) {+ vertexTotal += part.geometry.positions.length / 3;+ indexTotal += part.geometry.indices.length;+ }+ if (indexTotal === 0 || indexTotal / 3 > MAXIMUM_TRIANGLES) {+ return null;+ }+ const positions = new Float64Array(vertexTotal * 3);+ const indices = new Uint32Array(indexTotal);+ const triangleOwner = new Uint32Array(indexTotal / 3);+ const bounds = [];+ let vertexOffset = 0;+ let triangleOffset = 0;+ parts.forEach((part, partIndex) => {+ const { matrix } = part;+ const source = part.geometry.positions;+ const minimum = [Infinity, Infinity, Infinity];+ const maximum = [-Infinity, -Infinity, -Infinity];+ for (let vertex = 0; vertex < source.length / 3; vertex++) {+ const x = source[vertex * 3];+ const y = source[vertex * 3 + 1];+ const z = source[vertex * 3 + 2];+ for (let axis = 0; axis < 3; axis++) {+ const value = matrix[axis] * x + matrix[4 + axis] * y + matrix[8 + axis] * z + matrix[12 + axis];+ positions[(vertexOffset + vertex) * 3 + axis] = value;+ minimum[axis] = Math.min(minimum[axis], value);+ maximum[axis] = Math.max(maximum[axis], value);+ }+ }+ for (let slot = 0; slot < part.geometry.indices.length; slot++) {+ indices[triangleOffset * 3 + slot] = part.geometry.indices[slot] + vertexOffset;+ }+ triangleOwner.fill(partIndex, triangleOffset, triangleOffset + part.geometry.indices.length / 3);+ bounds.push({ minimum, maximum });+ vertexOffset += source.length / 3;+ triangleOffset += part.geometry.indices.length / 3;+ });+ return { triangleOwner, bounds, tracer: createTracer({ positions, indices, bvh: buildTriangleBvh(positions, indices) }) };+}++/**+ * The first surface straight up from a probe point that belongs to another family of parts, as a part index, or -1.+ * `family` holds the part indices that may not count: the part itself, its parents and its children.+ */+function supportAbove(world, family, x, y, z, reach) {+ let originY = y;+ for (let attempt = 0; attempt < MAXIMUM_SELF_HITS; attempt++) {+ const hit = world.tracer.trace(x, originY, z, 0, 1, 0, reach - (originY - y), false);+ if (hit.nearestTriangle < 0) {+ return -1;+ }+ const owner = world.triangleOwner[hit.nearestTriangle];+ if (!family.has(owner)) {+ return owner;+ }+ originY += hit.nearestDistance + 1e-6;+ }+ return -1;+}++function overhangs(supportBounds, partBounds) {+ return [0, 2].some(axis => {+ const margin = OVERHANG_SHARE * (partBounds.maximum[axis] - partBounds.minimum[axis]);+ return supportBounds.minimum[axis] < partBounds.minimum[axis] - margin || supportBounds.maximum[axis] > partBounds.maximum[axis] + margin;+ });+}++function footprintArea(bounds) {+ return (bounds.maximum[0] - bounds.minimum[0]) * (bounds.maximum[2] - bounds.minimum[2]);+}++function familyOf(part, parts, ancestors) {+ const parents = new Set(ancestors.get(part.name) ?? []);+ const family = new Set();+ parts.forEach((other, index) => {+ const otherParents = ancestors.get(other.name) ?? [];+ if (other === part || parents.has(other.name) || otherParents.includes(part.name)) {+ family.add(index);+ }+ });+ return family;+}++/**+ * Parts whose footprint is partly held up by another part and partly in the air, as+ * `{ part, supportedShare, supporters }` in the order of the scene's parts.+ */+export function findUnsupportedParts(parts, recipe) {+ const ancestors = ancestorLookup(recipe.nodes);+ const floating = partsMeantToFloat(recipe, ancestors);+ const solid = parts.filter(part => part.geometry?.indices.length > 0 && !isTranslucent(part));+ const world = buildSupportWorld(solid);+ if (!world) {+ return [];+ }+ const lowest = Math.min(...world.bounds.map(bounds => bounds.minimum[1]));+ const candidates = solid+ .map((part, index) => ({ part, index, bounds: world.bounds[index] }))+ .filter(({ part, bounds }) => !floating.has(part.name)+ && bounds.minimum[1] > lowest + SUPPORT_TOLERANCE+ && bounds.maximum[0] - bounds.minimum[0] >= MINIMUM_FOOTPRINT+ && bounds.maximum[2] - bounds.minimum[2] >= MINIMUM_FOOTPRINT)+ .sort((first, second) => footprintArea(second.bounds) - footprintArea(first.bounds))+ .slice(0, MAXIMUM_CHECKED_PARTS);+ const findings = [];+ for (const { part, index, bounds } of candidates) {+ const family = familyOf(part, solid, ancestors);+ const reach = bounds.maximum[1] - bounds.minimum[1] + 2 * SUPPORT_TOLERANCE;+ const supporters = new Set();+ let supported = 0;+ for (let row = 0; row < PROBES_PER_SIDE; row++) {+ for (let column = 0; column < PROBES_PER_SIDE; column++) {+ const x = bounds.minimum[0] + (column + 0.5) / PROBES_PER_SIDE * (bounds.maximum[0] - bounds.minimum[0]);+ const z = bounds.minimum[2] + (row + 0.5) / PROBES_PER_SIDE * (bounds.maximum[2] - bounds.minimum[2]);+ const owner = supportAbove(world, family, x, bounds.minimum[1] - SUPPORT_TOLERANCE, z, reach);+ if (owner >= 0) {+ supported++;+ supporters.add(owner);+ }+ }+ }+ const supportedShare = supported / (PROBES_PER_SIDE * PROBES_PER_SIDE);+ if (supported > 0 && supportedShare < SUPPORT_SHARE && [...supporters].some(owner => overhangs(world.bounds[owner], bounds))) {+ findings.push({ part, index, supportedShare, supporters: [...supporters].map(owner => solid[owner].name) });+ }+ }+ return findings.sort((first, second) => first.index - second.index);+}++function percent(share) {+ return Math.round(share * 100);+}++/** Warnings in the shape of `agent-diagnostics.js`, the least supported first, plus one line for the rest. */+export function unsupportedPartDiagnostics(findings) {+ const ranked = [...findings].sort((first, second) => first.supportedShare - second.supportedShare);+ const problems = ranked.slice(0, REPORTED_PARTS).map(({ part, supportedShare, supporters }) => ({+ ...diagnostic(+ 'unsupported-part', 'warning', part.name,+ `${part.name} has ${percent(1 - supportedShare)} percent of its footprint with nothing under it (within ${SUPPORT_TOLERANCE * 100} cm of its base); ${percent(supportedShare)} percent rests on ${supporters.join(', ')}. From a low side view it hangs off the edge.`,+ `Move ${part.name} toward the middle of ${supporters[0]} until at least ${percent(SUPPORT_SHARE)} percent of its footprint sits on it, or make ${supporters[0]} wider. Leave it as is when it is meant to overhang (a balcony or an eave).`),+ unsupportedShare: Math.round((1 - supportedShare) * 100) / 100,+ nodes: [part.name, ...supporters],+ }));+ if (ranked.length > REPORTED_PARTS) {+ problems.push(diagnostic('unsupported-part', 'warning', 'scene', `${ranked.length - REPORTED_PARTS} more parts hang off their support.`, 'Fix the listed parts first, then inspect the scene again.'));+ }+ return problems;+}++let cache = null;++/** The warnings for a scene, computed once per revision of the scene and kept until it changes. */+export function unsupportedPartProblems(parts, recipe, revision) {+ if (cache?.parts !== parts || cache.revision !== revision) {+ cache = { parts, revision, problems: unsupportedPartDiagnostics(findUnsupportedParts(parts, recipe)) };+ }+ return cache.problems;+}diff --git a/tests/unsupported-part.test.js b/tests/unsupported-part.test.jsnew file mode 100644index 00000000..840c98c1--- /dev/null+++ b/tests/unsupported-part.test.js@@ -0,0 +1,66 @@+import test from 'node:test';+import assert from 'node:assert/strict';+import { createAgentScene, loadAllAgentSceneModules } from '../src/agent-scene.js';++await loadAllAgentSceneModules();++function recipe(nodes, extra = {}) {+ return {+ format: 'crucible.scene', schemaVersion: 1,+ geometries: [{ id: 'box', type: 'box', bevel: 0 }, { id: 'speck', type: 'box', bevel: 0 }],+ materials: [{ id: 'stone', color: [0.5, 0.5, 0.5] }],+ nodes,+ ...extra,+ };+}++function unsupportedWarnings(nodes, extra) {+ const inspection = createAgentScene(recipe(nodes, extra)).inspect();+ return (inspection.diagnostics ?? []).filter(entry => entry.kind === 'unsupported-part');+}++// The rock spans x -2..2, y -1..1, z -2..2; the building's base is at y = 1.+const rock = { id: 'rock', geometry: 'box', material: 'stone', scale: [4, 2, 4] };++function building(centreX, extra = {}) {+ return { id: 'building', geometry: 'box', material: 'stone', translation: [centreX, 2, 0], scale: [2, 2, 2], ...extra };+}++test('a building with half its footprint past the rock edge warns with about 50 percent unsupported', () => {+ const warnings = unsupportedWarnings([rock, building(2)]);+ assert.equal(warnings.length, 1);+ assert.equal(warnings[0].target, 'building');+ assert.equal(warnings[0].unsupportedShare, 0.5);+ assert.match(warnings[0].message, /building has 50 percent of its footprint with nothing under it/);+ assert.match(warnings[0].message, /rests on rock/);+ assert.deepEqual(warnings[0].nodes, ['building', 'rock']);+});++test('a building fully on the rock does not warn', () => {+ assert.deepEqual(unsupportedWarnings([rock, building(0)]), []);+});++test('a box on the lowest surface of the scene does not warn', () => {+ const stackedOnGround = [{ id: 'ground', geometry: 'box', material: 'stone', translation: [0, -0.05, 0], scale: [10, 0.1, 10] },+ { id: 'crate', geometry: 'box', material: 'stone', translation: [4.5, 0.5, 0], scale: [2, 1, 2] }];+ assert.deepEqual(unsupportedWarnings(stackedOnGround), []);+ assert.deepEqual(unsupportedWarnings([{ id: 'crate', geometry: 'box', material: 'stone', translation: [0, 0.5, 0] }]), []);+});++test('a roof wider than its walls, a part with nothing under it and a light do not warn', () => {+ const walls = [rock, { id: 'walls', geometry: 'box', material: 'stone', translation: [0, 2, 0], scale: [2, 2, 2] }];+ const roof = { id: 'roof', geometry: 'box', material: 'stone', translation: [0, 3.25, 0], scale: [3, 0.5, 3] };+ assert.deepEqual(unsupportedWarnings([...walls, roof]), []);+ const hovering = { id: 'drone', geometry: 'box', material: 'stone', translation: [0, 6, 0], scale: [1, 0.3, 1] };+ const lights = { environment: { pointLights: [{ position: [2.5, 2, 0], intensity: 1 }] } };+ assert.deepEqual(unsupportedWarnings([rock, hovering], lights), []);+});++test('an animated part and a particle emitter that hang off the edge do not warn', () => {+ const moving = unsupportedWarnings([rock, building(2)], { motion: { duration: 1, tracks: [{ kind: 'node', id: 'building', property: 'translation', keyframes: [{ time: 0, value: [2, 2, 0] }, { time: 1, value: [2, 3, 0] }] }] } });+ assert.deepEqual(moving, []);+ const emitter = { id: 'sparks', geometry: 'speck', material: 'stone', translation: [2, 1.5, 0], scale: [2, 1, 2] };+ const particles = { particles: { gravity: [0, 0, 0], systems: [{ node: 'sparks', seed: 2, count: 20, lifetime: 3, speed: 1, size: 0.05 }] } };+ assert.deepEqual(unsupportedWarnings([rock, emitter], particles), []);+ assert.equal(unsupportedWarnings([rock, { ...emitter, id: 'crate' }]).length, 1);+});