Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

feat(qa): declare parts that rest on an external support (#220) (#234)

Matthew Kissingerdce96f0ad2b7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c8d9ddae..13addfac 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -93,6 +93,13 @@ does not publish a package.
Meshopt decoder reads the GLB, while `KHR_mesh_quantization`, instancing and every
preserved feature stay. The sidecar `delivery.compression` records `{ extension: 'none' }`.
The default output is unchanged.
+- Declare parts that rest on an external support ([#220](https://github.com/instruktlabs/kiln/issues/220)).
+ A requirements binding can list `externalSupport.supports`: named parts and the plane they
+ rest on outside the asset. A named part whose bottom meets that plane moves from the
+ floating-parts warning to an informational line, and its connectivity observation becomes
+ `GEO_PART_EXTERNAL_SUPPORT` naming the declaration. Undeclared parts, parts at another
+ height and every other disposition are unchanged. The declaration is covered by the policy
+ hash.
## 1.3.1 (2026-10-17)
diff --git a/dist/agent-run.mjs b/dist/agent-run.mjs
index 9c44c97a..95d69bfa 100644
--- a/dist/agent-run.mjs
+++ b/dist/agent-run.mjs
@@ -561,7 +561,7 @@ function createAssetRequirementsV1(input = {}) {
...input
});
}
-var text, positive, nonnegative, count, names, marker, roof, structure, effects, requirements, AssetRequirementsV1Schema;
+var text, positive, nonnegative, count, names, marker, supportParts, roof, structure, effects, requirements, AssetRequirementsV1Schema;
var init_requirements = __esm(() => {
init_asset();
init_breadth();
@@ -573,6 +573,9 @@ var init_requirements = __esm(() => {
message: "Values must be unique."
});
marker = z.strictObject({});
+ supportParts = z.array(text).min(1).max(256).refine((values) => new Set(values).size === values.length, {
+ message: "Values must be unique."
+ });
roof = z.strictObject({
type: text.optional(),
ridgeAxis: z.enum(["x", "z"]).optional(),
@@ -692,6 +695,13 @@ var init_requirements = __esm(() => {
precomputedTangents: z.boolean().optional(),
skinned: z.boolean().optional()
})).optional(),
+ externalSupport: statement(z.strictObject({
+ supports: z.array(z.strictObject({
+ parts: supportParts,
+ planeY: z.number().finite(),
+ tolerance: nonnegative.max(0.5).optional()
+ })).min(1).max(32)
+ })).optional(),
access: statement(z.strictObject({ enterable: z.boolean().optional(), driveable: z.boolean().optional() })).optional()
});
AssetRequirementsV1Schema = z.strictObject({
@@ -9929,7 +9939,8 @@ function resolveRequirementsApplicability(requirements) {
grounding: ["planeY"],
bounds: ["units", "x", "y", "z"],
animation: ["clips"],
- representation: ["precomputedTangents"]
+ representation: ["precomputedTangents"],
+ externalSupport: ["supports"]
};
for (const [key, statement] of Object.entries(requirements.requirements)) {
if (statement?.state !== "requested")
@@ -12590,6 +12601,25 @@ var init_solid_diagnostic = __esm(() => {
};
});
+// src/external-support.ts
+function restingSupport(mesh, bottomY, supports) {
+ return declaredSupports(mesh, supports).find((support) => Math.abs(bottomY - support.planeY) <= (support.tolerance ?? EXTERNAL_SUPPORT_TOLERANCE));
+}
+function declaredSupports(mesh, supports) {
+ if (!supports?.length)
+ return [];
+ const names = new Set;
+ for (let node = mesh;node; node = node.parent) {
+ if (!node.name)
+ continue;
+ names.add(node.name);
+ if (node.name.startsWith("Mesh_"))
+ names.add(node.name.slice(5));
+ }
+ return supports.filter((support) => support.parts.some((part) => names.has(part)));
+}
+var EXTERNAL_SUPPORT_TOLERANCE = 0.02;
+
// src/qa/breadth-evidence.ts
import * as THREE6 from "three";
function record7(value) {
@@ -16629,7 +16659,7 @@ var init_lod2 = __esm(() => {
// src/qa/part-connectivity.ts
import * as THREE14 from "three";
-function collectParts2(root, exempt) {
+function collectParts2(root, exempt, supports) {
const parts = [];
let lodExcluded = 0;
root.updateWorldMatrix(true, true);
@@ -16649,7 +16679,8 @@ function collectParts2(root, exempt) {
const box = new THREE14.Box3().setFromObject(mesh);
if (box.isEmpty())
return;
- parts.push({ name, box });
+ const support = restingSupport(mesh, box.min.y, supports);
+ parts.push({ name, box, ...support ? { support } : {} });
});
return { parts, lodExcluded };
}
@@ -16659,9 +16690,9 @@ function boxGap(a, b) {
const dz = Math.max(0, Math.max(a.min.z - b.max.z, b.min.z - a.max.z));
return Math.hypot(dx, dy, dz);
}
-function analyzePartConnectivity(root) {
+function analyzePartConnectivity(root, supports) {
const exempt = [];
- const { parts, lodExcluded } = collectParts2(root, exempt);
+ const { parts, lodExcluded } = collectParts2(root, exempt, supports);
const report = {
partsAnalyzed: parts.length,
mainComponentSize: parts.length,
@@ -16722,22 +16753,48 @@ function analyzePartConnectivity(root) {
gap = Math.min(gap, boxGap(parts[m].box, parts[b].box));
}
}
+ const lowest = members.reduce((a, b) => parts[b].box.min.y < parts[a].box.min.y ? b : a);
+ const support = parts[lowest].support;
report.groups.push({
parts: members.map((m) => parts[m].name),
- gap: Math.round(gap * 1e6) / 1e6
+ gap: Math.round(gap * 1e6) / 1e6,
+ ...support && members.every((m) => parts[m].support) ? {
+ externalSupport: {
+ planeY: support.planeY,
+ bottomY: Math.round(parts[lowest].box.min.y * 1e6) / 1e6,
+ tolerance: support.tolerance ?? CONNECTIVITY_TOLERANCE
+ }
+ } : {}
});
}
report.groups.sort((a, b) => b.parts.length - a.parts.length || a.gap - b.gap);
return report;
}
-function inspectPartConnectivity(scene) {
+function inspectPartConnectivity(scene, supports) {
if (!(scene instanceof THREE14.Object3D))
return [];
- const report = analyzePartConnectivity(scene);
+ const report = analyzePartConnectivity(scene, supports);
const lodNote = report.lodExcluded === 1 ? " 1 part on an LOD level above 0 was not analyzed." : report.lodExcluded > 1 ? ` ${report.lodExcluded} parts on LOD levels above 0 were not analyzed.` : "";
return report.groups.map((group) => {
const listed = group.parts.map((p) => JSON.stringify(p)).join(", ");
const subject = group.parts.length === 1 ? `Part ${listed} is` : `A group of ${group.parts.length} parts (${listed}) is`;
+ const declared = group.externalSupport;
+ if (declared)
+ return {
+ code: "GEO_PART_EXTERNAL_SUPPORT",
+ disposition: "observe",
+ dimension: "visualQuality",
+ profile: "geometry.partConnectivity",
+ message: `${subject} separate from the largest component and rests on the support declared in requirements.externalSupport at Y=${declared.planeY.toFixed(3)} m (bottom at Y=${declared.bottomY.toFixed(3)} m). Information only: the support is composed outside this asset.${lodNote}`,
+ affected: { node: group.parts[0] },
+ measurement: {
+ name: "bottomToSupportPlane",
+ actual: declared.bottomY,
+ expected: declared.planeY,
+ threshold: declared.tolerance
+ },
+ repairText: "No change is needed for a declared support. Remove the part from requirements.externalSupport if it should attach within this asset."
+ };
return {
code: "GEO_PART_CONNECTIVITY",
disposition: "observe",
@@ -22901,7 +22958,7 @@ function runRequirementsSceneQa(context, scene, clips, policy = {}, evidence = {
findings.push(decision.mode === "observe" || decision.mode === "warn" ? { ...finding, disposition: decision.mode } : finding);
continue;
}
- const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({
+ const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene, needs.externalSupport?.state === "requested" ? needs.externalSupport.value.supports : undefined) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({
profile: "asset.requirements.v1",
scope: { schemaVersion: 1, scope: scope.value, explicit: true },
derivedEvidence: { source: "engine-scene-analysis", assetScope: scopeObservation }
@@ -37165,7 +37222,10 @@ async function renderSceneToGLB(root, opts = {}) {
const materialResourceProvenance = collectMaterialResourceProvenance(root);
for (const w of inspectGeneratedAnimation(root, clips))
warnings.push(w);
- for (const w of inspectSceneStructure(root))
+ const externalSupport = requirements.requirements.requirements.externalSupport;
+ for (const w of inspectSceneStructure(root, {
+ ...externalSupport?.state === "requested" ? { externalSupport: externalSupport.value.supports } : {}
+ }))
warnings.push(w);
const atlas = collectAtlasProvenance(root);
const bakedTextures = await bakeSceneTextures(root, warnings);
@@ -37491,6 +37551,7 @@ function collectMeshStats(root) {
box.getCenter(center);
box.getSize(size);
out.push({
+ object: obj,
name: obj.name || "(unnamed)",
triCount: Math.floor(tri),
isPlaneGeo: geo.type === "PlaneGeometry",
@@ -37549,6 +37610,7 @@ function inspectSceneStructure(root, opts = {}) {
}
if (meshes.length > 1) {
const floaters = [];
+ const supported = [];
for (let i = 0;i < meshes.length; i++) {
const a = meshes[i];
const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);
@@ -37564,6 +37626,12 @@ function inspectSceneStructure(root, opts = {}) {
}
if (overlapsAny)
continue;
+ const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);
+ if (support) {
+ supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);
+ continue;
+ }
+ const declared = declaredSupports(a.object, opts.externalSupport)[0];
let nearest;
let nearestGap;
for (let j = 0;j < meshes.length; j++) {
@@ -37576,7 +37644,8 @@ function inspectSceneStructure(root, opts = {}) {
}
}
const fix = nearest && nearestGap ? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.` : "";
- floaters.push({ name: a.name, fix });
+ const mismatch = declared ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.` : "";
+ floaters.push({ name: a.name, fix: fix + mismatch });
}
if (floaters.length > 0) {
const entries = floaters.slice(0, FLOATER_FIXES_SHOWN).map(({ name, fix }) => `${name}${fix ? ` —${fix}` : ""}`);
@@ -37589,6 +37658,12 @@ function inspectSceneStructure(root, opts = {}) {
}
warnings.push(`Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(" | ")}`);
}
+ if (supported.length > 0) {
+ const shown = supported.slice(0, FLOATER_NAMES_SHOWN);
+ if (supported.length > shown.length)
+ shown.push(`+${supported.length - shown.length} more`);
+ warnings.push(`Declared external support (requirements.externalSupport): ${shown.join(", ")} rest on a support composed outside this asset; information only, no action needed.`);
+ }
}
return warnings;
}
diff --git a/dist/build.json b/dist/build.json
index 7f512c67..0e1a4b91 100644
--- a/dist/build.json
+++ b/dist/build.json
@@ -2,10 +2,10 @@
"schemaVersion": 1,
"entries": {
"worker": {
- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",
+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",
+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -37,13 +37,13 @@
},
"target": "node",
"file": "evaluator-worker.mjs",
- "bundleHash": "sha256:eb4c421782d3d96e7f4ba04072ecdca10af471d17299bc42a1e0e2fc4c54c421"
+ "bundleHash": "sha256:326aaf15bc9181bc8ef5b2cf02861c33cc7848347e50830f288330121c0d1f0e"
},
"agent-run": {
- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",
+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",
+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -75,13 +75,13 @@
},
"target": "node",
"file": "agent-run.mjs",
- "bundleHash": "sha256:74d69033c8ffa36f7b060a54845f71a0d7d4cd5e9ec60237d080ec7f5e374d8f"
+ "bundleHash": "sha256:40e510f17106f36cc81195e1ea3309deb743ba601f0081d6744685d4f297a32e"
},
"agent-providers": {
- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",
+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",
+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -116,10 +116,10 @@
"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"
},
"mcp": {
- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",
+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",
+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -154,10 +154,10 @@
"bundleHash": "sha256:a246b2c79d629a332cef4430dbe742b0c4a0d2f04f0281e673c3c60ff22706da"
},
"cli": {
- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",
+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",
+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -189,13 +189,13 @@
},
"target": "node",
"file": "cli.mjs",
- "bundleHash": "sha256:689fbdd3acf0742745c2e579ac399dccd49363113afd474208136ab26bdda194"
+ "bundleHash": "sha256:d81bc1f41df8bae96caa68af5ba692f2414038bb25827ebc3d5d6875fbcd2819"
},
"engine": {
- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",
+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006",
"engineVersion": "1.3.1",
"toolchain": "[email protected]",
- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",
+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3",
"dependencies": {
@@ -227,7 +227,7 @@
},
"target": "node",
"file": "mcp-engine.mjs",
- "bundleHash": "sha256:4aa709eeff1d69fd57dfecf6a3f49c9a0a669484ad8ac40caab4ec1fa850f06e"
+ "bundleHash": "sha256:4c28e9a7f4eb98ff72e5f5592e8b906fcf951034152458b85cbc12aacd2067f8"
}
}
}
diff --git a/dist/cli.mjs b/dist/cli.mjs
index ae0e8f01..7c33e499 100644
--- a/dist/cli.mjs
+++ b/dist/cli.mjs
@@ -11004,6 +11004,25 @@ var init_prop = __esm(() => {
];
});
+// src/external-support.ts
+function restingSupport(mesh, bottomY, supports) {
+ return declaredSupports(mesh, supports).find((support) => Math.abs(bottomY - support.planeY) <= (support.tolerance ?? EXTERNAL_SUPPORT_TOLERANCE));
+}
+function declaredSupports(mesh, supports) {
+ if (!supports?.length)
+ return [];
+ const names = new Set;
+ for (let node = mesh;node; node = node.parent) {
+ if (!node.name)
+ continue;
+ names.add(node.name);
+ if (node.name.startsWith("Mesh_"))
+ names.add(node.name.slice(5));
+ }
+ return supports.filter((support) => support.parts.some((part) => names.has(part)));
+}
+var EXTERNAL_SUPPORT_TOLERANCE = 0.02;
+
// src/delivery.ts
import * as THREE15 from "three";
import { ConvexGeometry } from "three/addons/geometries/ConvexGeometry.js";
@@ -11375,7 +11394,7 @@ var init_lod2 = __esm(() => {
// src/qa/part-connectivity.ts
import * as THREE16 from "three";
-function collectParts2(root, exempt) {
+function collectParts2(root, exempt, supports) {
const parts = [];
let lodExcluded = 0;
root.updateWorldMatrix(true, true);
@@ -11395,7 +11414,8 @@ function collectParts2(root, exempt) {
const box = new THREE16.Box3().setFromObject(mesh);
if (box.isEmpty())
return;
- parts.push({ name, box });
+ const support = restingSupport(mesh, box.min.y, supports);
+ parts.push({ name, box, ...support ? { support } : {} });
});
return { parts, lodExcluded };
}
@@ -11405,9 +11425,9 @@ function boxGap(a, b) {
const dz = Math.max(0, Math.max(a.min.z - b.max.z, b.min.z - a.max.z));
return Math.hypot(dx, dy, dz);
}
-function analyzePartConnectivity(root) {
+function analyzePartConnectivity(root, supports) {
const exempt = [];
- const { parts, lodExcluded } = collectParts2(root, exempt);
+ const { parts, lodExcluded } = collectParts2(root, exempt, supports);
const report = {
partsAnalyzed: parts.length,
mainComponentSize: parts.length,
@@ -11468,22 +11488,48 @@ function analyzePartConnectivity(root) {
gap = Math.min(gap, boxGap(parts[m].box, parts[b].box));
}
}
+ const lowest = members.reduce((a, b) => parts[b].box.min.y < parts[a].box.min.y ? b : a);
+ const support = parts[lowest].support;
report.groups.push({
parts: members.map((m) => parts[m].name),
- gap: Math.round(gap * 1e6) / 1e6
+ gap: Math.round(gap * 1e6) / 1e6,
+ ...support && members.every((m) => parts[m].support) ? {
+ externalSupport: {
+ planeY: support.planeY,
+ bottomY: Math.round(parts[lowest].box.min.y * 1e6) / 1e6,
+ tolerance: support.tolerance ?? CONNECTIVITY_TOLERANCE
+ }
+ } : {}
});
}
report.groups.sort((a, b) => b.parts.length - a.parts.length || a.gap - b.gap);
return report;
}
-function inspectPartConnectivity(scene) {
+function inspectPartConnectivity(scene, supports) {
if (!(scene instanceof THREE16.Object3D))
return [];
- const report = analyzePartConnectivity(scene);
+ const report = analyzePartConnectivity(scene, supports);
const lodNote = report.lodExcluded === 1 ? " 1 part on an LOD level above 0 was not analyzed." : report.lodExcluded > 1 ? ` ${report.lodExcluded} parts on LOD levels above 0 were not analyzed.` : "";
return report.groups.map((group) => {
const listed = group.parts.map((p) => JSON.stringify(p)).join(", ");
const subject = group.parts.length === 1 ? `Part ${listed} is` : `A group of ${group.parts.length} parts (${listed}) is`;
+ const declared = group.externalSupport;
+ if (declared)
+ return {
+ code: "GEO_PART_EXTERNAL_SUPPORT",
+ disposition: "observe",
+ dimension: "visualQuality",
+ profile: "geometry.partConnectivity",
+ message: `${subject} separate from the largest component and rests on the support declared in requirements.externalSupport at Y=${declared.planeY.toFixed(3)} m (bottom at Y=${declared.bottomY.toFixed(3)} m). Information only: the support is composed outside this asset.${lodNote}`,
+ affected: { node: group.parts[0] },
+ measurement: {
+ name: "bottomToSupportPlane",
+ actual: declared.bottomY,
+ expected: declared.planeY,
+ threshold: declared.tolerance
+ },
+ repairText: "No change is needed for a declared support. Remove the part from requirements.externalSupport if it should attach within this asset."
+ };
return {
code: "GEO_PART_CONNECTIVITY",
disposition: "observe",
@@ -14250,7 +14296,7 @@ function createAssetRequirementsV1(input = {}) {
...input
});
}
-var text, positive2, nonnegative, count2, names, marker, roof, structure, effects, requirements, AssetRequirementsV1Schema;
+var text, positive2, nonnegative, count2, names, marker, supportParts, roof, structure, effects, requirements, AssetRequirementsV1Schema;
var init_requirements = __esm(() => {
init_asset();
init_breadth();
@@ -14262,6 +14308,9 @@ var init_requirements = __esm(() => {
message: "Values must be unique."
});
marker = z.strictObject({});
+ supportParts = z.array(text).min(1).max(256).refine((values) => new Set(values).size === values.length, {
+ message: "Values must be unique."
+ });
roof = z.strictObject({
type: text.optional(),
ridgeAxis: z.enum(["x", "z"]).optional(),
@@ -14381,6 +14430,13 @@ var init_requirements = __esm(() => {
precomputedTangents: z.boolean().optional(),
skinned: z.boolean().optional()
})).optional(),
+ externalSupport: statement(z.strictObject({
+ supports: z.array(z.strictObject({
+ parts: supportParts,
+ planeY: z.number().finite(),
+ tolerance: nonnegative.max(0.5).optional()
+ })).min(1).max(32)
+ })).optional(),
access: statement(z.strictObject({ enterable: z.boolean().optional(), driveable: z.boolean().optional() })).optional()
});
AssetRequirementsV1Schema = z.strictObject({
@@ -19776,7 +19832,8 @@ function resolveRequirementsApplicability(requirements) {
grounding: ["planeY"],
bounds: ["units", "x", "y", "z"],
animation: ["clips"],
- representation: ["precomputedTangents"]
+ representation: ["precomputedTangents"],
+ externalSupport: ["supports"]
};
for (const [key, statement] of Object.entries(requirements.requirements)) {
if (statement?.state !== "requested")
@@ -20571,7 +20628,7 @@ function runRequirementsSceneQa(context, scene, clips, policy = {}, evidence = {
findings.push(decision.mode === "observe" || decision.mode === "warn" ? { ...finding, disposition: decision.mode } : finding);
continue;
}
- const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({
+ const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene, needs.externalSupport?.state === "requested" ? needs.externalSupport.value.supports : undefined) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({
profile: "asset.requirements.v1",
scope: { schemaVersion: 1, scope: scope.value, explicit: true },
derivedEvidence: { source: "engine-scene-analysis", assetScope: scopeObservation }
@@ -38270,7 +38327,10 @@ async function renderSceneToGLB(root, opts = {}) {
const materialResourceProvenance = collectMaterialResourceProvenance(root);
for (const w of inspectGeneratedAnimation(root, clips))
warnings.push(w);
- for (const w of inspectSceneStructure(root))
+ const externalSupport = requirements.requirements.requirements.externalSupport;
+ for (const w of inspectSceneStructure(root, {
+ ...externalSupport?.state === "requested" ? { externalSupport: externalSupport.value.supports } : {}
+ }))
warnings.push(w);
const atlas = collectAtlasProvenance(root);
const bakedTextures = await bakeSceneTextures(root, warnings);
@@ -38606,6 +38666,7 @@ function collectMeshStats(root) {
box.getCenter(center);
box.getSize(size);
out.push({
+ object: obj,
name: obj.name || "(unnamed)",
triCount: Math.floor(tri),
isPlaneGeo: geo.type === "PlaneGeometry",
@@ -38664,6 +38725,7 @@ function inspectSceneStructure(root, opts = {}) {
}
if (meshes.length > 1) {
const floaters = [];
+ const supported = [];
for (let i = 0;i < meshes.length; i++) {
const a = meshes[i];
const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);
@@ -38679,6 +38741,12 @@ function inspectSceneStructure(root, opts = {}) {
}
if (overlapsAny)
continue;
+ const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);
+ if (support) {
+ supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);
+ continue;
+ }
+ const declared = declaredSupports(a.object, opts.externalSupport)[0];
let nearest;
let nearestGap;
for (let j = 0;j < meshes.length; j++) {
@@ -38691,7 +38759,8 @@ function inspectSceneStructure(root, opts = {}) {
}
}
const fix = nearest && nearestGap ? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.` : "";
- floaters.push({ name: a.name, fix });
+ const mismatch = declared ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.` : "";
+ floaters.push({ name: a.name, fix: fix + mismatch });
}
if (floaters.length > 0) {
const entries = floaters.slice(0, FLOATER_FIXES_SHOWN).map(({ name, fix }) => `${name}${fix ? ` —${fix}` : ""}`);
@@ -38704,6 +38773,12 @@ function inspectSceneStructure(root, opts = {}) {
}
warnings.push(`Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(" | ")}`);
}
+ if (supported.length > 0) {
+ const shown = supported.slice(0, FLOATER_NAMES_SHOWN);
+ if (supported.length > shown.length)
+ shown.push(`+${supported.length - shown.length} more`);
+ warnings.push(`Declared external support (requirements.externalSupport): ${shown.join(", ")} rest on a support composed outside this asset; information only, no action needed.`);
+ }
}
return warnings;
}
diff --git a/dist/evaluator-worker.mjs b/dist/evaluator-worker.mjs
index 57dbceb8..f9addfc4 100644
--- a/dist/evaluator-worker.mjs
+++ b/dist/evaluator-worker.mjs
@@ -170,6 +170,25 @@ var init_solid_diagnostic = __esm(() => {
};
});
+// src/external-support.ts
+function restingSupport(mesh, bottomY, supports) {
+ return declaredSupports(mesh, supports).find((support) => Math.abs(bottomY - support.planeY) <= (support.tolerance ?? EXTERNAL_SUPPORT_TOLERANCE));
+}
+function declaredSupports(mesh, supports) {
+ if (!supports?.length)
+ return [];
+ const names = new Set;
+ for (let node = mesh;node; node = node.parent) {
+ if (!node.name)
+ continue;
+ names.add(node.name);
+ if (node.name.startsWith("Mesh_"))
+ names.add(node.name.slice(5));
+ }
+ return supports.filter((support) => support.parts.some((part) => names.has(part)));
+}
+var EXTERNAL_SUPPORT_TOLERANCE = 0.02;
+
// src/contracts/breadth.ts
function cloneVfxIntentV1(value) {
return {
@@ -707,7 +726,7 @@ function createAssetRequirementsV1(input = {}) {
...input
});
}
-var text, positive, nonnegative, count2, names, marker, roof, structure, effects, requirements, AssetRequirementsV1Schema;
+var text, positive, nonnegative, count2, names, marker, supportParts, roof, structure, effects, requirements, AssetRequirementsV1Schema;
var init_requirements = __esm(() => {
init_asset();
init_breadth();
@@ -719,6 +738,9 @@ var init_requirements = __esm(() => {
message: "Values must be unique."
});
marker = z.strictObject({});
+ supportParts = z.array(text).min(1).max(256).refine((values) => new Set(values).size === values.length, {
+ message: "Values must be unique."
+ });
roof = z.strictObject({
type: text.optional(),
ridgeAxis: z.enum(["x", "z"]).optional(),
@@ -838,6 +860,13 @@ var init_requirements = __esm(() => {
precomputedTangents: z.boolean().optional(),
skinned: z.boolean().optional()
})).optional(),
+ externalSupport: statement(z.strictObject({
+ supports: z.array(z.strictObject({
+ parts: supportParts,
+ planeY: z.number().finite(),
+ tolerance: nonnegative.max(0.5).optional()
+ })).min(1).max(32)
+ })).optional(),
access: statement(z.strictObject({ enterable: z.boolean().optional(), driveable: z.boolean().optional() })).optional()
});
AssetRequirementsV1Schema = z.strictObject({
@@ -6937,7 +6966,7 @@ var init_lod2 = __esm(() => {
// src/qa/part-connectivity.ts
import * as THREE9 from "three";
-function collectParts2(root, exempt) {
+function collectParts2(root, exempt, supports) {
const parts = [];
let lodExcluded = 0;
root.updateWorldMatrix(true, true);
@@ -6957,7 +6986,8 @@ function collectParts2(root, exempt) {
const box = new THREE9.Box3().setFromObject(mesh);
if (box.isEmpty())
return;
- parts.push({ name, box });
+ const support = restingSupport(mesh, box.min.y, supports);
+ parts.push({ name, box, ...support ? { support } : {} });
});
return { parts, lodExcluded };
}
@@ -6967,9 +6997,9 @@ function boxGap(a, b) {
const dz = Math.max(0, Math.max(a.min.z - b.max.z, b.min.z - a.max.z));
return Math.hypot(dx, dy, dz);
}
-function analyzePartConnectivity(root) {
+function analyzePartConnectivity(root, supports) {
const exempt = [];
- const { parts, lodExcluded } = collectParts2(root, exempt);
+ const { parts, lodExcluded } = collectParts2(root, exempt, supports);
const report = {
partsAnalyzed: parts.length,
mainComponentSize: parts.length,
@@ -7030,22 +7060,48 @@ function analyzePartConnectivity(root) {
gap = Math.min(gap, boxGap(parts[m].box, parts[b].box));
}
}
+ const lowest = members.reduce((a, b) => parts[b].box.min.y < parts[a].box.min.y ? b : a);
+ const support = parts[lowest].support;
report.groups.push({
parts: members.map((m) => parts[m].name),
- gap: Math.round(gap * 1e6) / 1e6
+ gap: Math.round(gap * 1e6) / 1e6,
+ ...support && members.every((m) => parts[m].support) ? {
+ externalSupport: {
+ planeY: support.planeY,
+ bottomY: Math.round(parts[lowest].box.min.y * 1e6) / 1e6,
+ tolerance: support.tolerance ?? CONNECTIVITY_TOLERANCE
+ }
+ } : {}
});
}
report.groups.sort((a, b) => b.parts.length - a.parts.length || a.gap - b.gap);
return report;
}
-function inspectPartConnectivity(scene) {
+function inspectPartConnectivity(scene, supports) {
if (!(scene instanceof THREE9.Object3D))
return [];
- const report = analyzePartConnectivity(scene);
+ const report = analyzePartConnectivity(scene, supports);
const lodNote = report.lodExcluded === 1 ? " 1 part on an LOD level above 0 was not analyzed." : report.lodExcluded > 1 ? ` ${report.lodExcluded} parts on LOD levels above 0 were not analyzed.` : "";
return report.groups.map((group) => {
const listed = group.parts.map((p) => JSON.stringify(p)).join(", ");
const subject = group.parts.length === 1 ? `Part ${listed} is` : `A group of ${group.parts.length} parts (${listed}) is`;
+ const declared = group.externalSupport;
+ if (declared)
+ return {
+ code: "GEO_PART_EXTERNAL_SUPPORT",
+ disposition: "observe",
+ dimension: "visualQuality",
+ profile: "geometry.partConnectivity",
+ message: `${subject} separate from the largest component and rests on the support declared in requirements.externalSupport at Y=${declared.planeY.toFixed(3)} m (bottom at Y=${declared.bottomY.toFixed(3)} m). Information only: the support is composed outside this asset.${lodNote}`,
+ affected: { node: group.parts[0] },
+ measurement: {
+ name: "bottomToSupportPlane",
+ actual: declared.bottomY,
+ expected: declared.planeY,
+ threshold: declared.tolerance
+ },
+ repairText: "No change is needed for a declared support. Remove the part from requirements.externalSupport if it should attach within this asset."
+ };
return {
code: "GEO_PART_CONNECTIVITY",
disposition: "observe",
@@ -13733,7 +13789,8 @@ function resolveRequirementsApplicability(requirements) {
grounding: ["planeY"],
bounds: ["units", "x", "y", "z"],
animation: ["clips"],
- representation: ["precomputedTangents"]
+ representation: ["precomputedTangents"],
+ externalSupport: ["supports"]
};
for (const [key, statement] of Object.entries(requirements.requirements)) {
if (statement?.state !== "requested")
@@ -14186,7 +14243,7 @@ function runRequirementsSceneQa(context, scene, clips, policy = {}, evidence = {
findings.push(decision.mode === "observe" || decision.mode === "warn" ? { ...finding, disposition: decision.mode } : finding);
continue;
}
- const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({
+ const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene, needs.externalSupport?.state === "requested" ? needs.externalSupport.value.supports : undefined) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({
profile: "asset.requirements.v1",
scope: { schemaVersion: 1, scope: scope.value, explicit: true },
derivedEvidence: { source: "engine-scene-analysis", assetScope: scopeObservation }
@@ -33617,7 +33674,10 @@ async function renderSceneToGLB(root, opts = {}) {
const materialResourceProvenance = collectMaterialResourceProvenance(root);
for (const w of inspectGeneratedAnimation(root, clips))
warnings.push(w);
- for (const w of inspectSceneStructure(root))
+ const externalSupport = requirements.requirements.requirements.externalSupport;
+ for (const w of inspectSceneStructure(root, {
+ ...externalSupport?.state === "requested" ? { externalSupport: externalSupport.value.supports } : {}
+ }))
warnings.push(w);
const atlas = collectAtlasProvenance(root);
const bakedTextures = await bakeSceneTextures(root, warnings);
@@ -33943,6 +34003,7 @@ function collectMeshStats(root) {
box.getCenter(center);
box.getSize(size);
out.push({
+ object: obj,
name: obj.name || "(unnamed)",
triCount: Math.floor(tri),
isPlaneGeo: geo.type === "PlaneGeometry",
@@ -34001,6 +34062,7 @@ function inspectSceneStructure(root, opts = {}) {
}
if (meshes.length > 1) {
const floaters = [];
+ const supported = [];
for (let i = 0;i < meshes.length; i++) {
const a = meshes[i];
const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);
@@ -34016,6 +34078,12 @@ function inspectSceneStructure(root, opts = {}) {
}
if (overlapsAny)
continue;
+ const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);
+ if (support) {
+ supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);
+ continue;
+ }
+ const declared = declaredSupports(a.object, opts.externalSupport)[0];
let nearest;
let nearestGap;
for (let j = 0;j < meshes.length; j++) {
@@ -34028,7 +34096,8 @@ function inspectSceneStructure(root, opts = {}) {
}
}
const fix = nearest && nearestGap ? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.` : "";
- floaters.push({ name: a.name, fix });
+ const mismatch = declared ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.` : "";
+ floaters.push({ name: a.name, fix: fix + mismatch });
}
if (floaters.length > 0) {
const entries = floaters.slice(0, FLOATER_FIXES_SHOWN).map(({ name, fix }) => `${name}${fix ? ` —${fix}` : ""}`);
@@ -34041,6 +34110,12 @@ function inspectSceneStructure(root, opts = {}) {
}
warnings.push(`Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(" | ")}`);
}
+ if (supported.length > 0) {
+ const shown = supported.slice(0, FLOATER_NAMES_SHOWN);
+ if (supported.length > shown.length)
+ shown.push(`+${supported.length - shown.length} more`);
+ warnings.push(`Declared external support (requirements.externalSupport): ${shown.join(", ")} rest on a support composed outside this asset; information only, no action needed.`);
+ }
}
return warnings;
}
diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjs
index 4125a899..a735b688 100644
--- a/dist/mcp-engine.mjs
+++ b/dist/mcp-engine.mjs
@@ -16836,6 +16836,25 @@ var init_prop = __esm(() => {
];
});
+// src/external-support.ts
+function restingSupport(mesh, bottomY, supports) {
+ return declaredSupports(mesh, supports).find((support) => Math.abs(bottomY - support.planeY) <= (support.tolerance ?? EXTERNAL_SUPPORT_TOLERANCE));
+}
+function declaredSupports(mesh, supports) {
+ if (!supports?.length)
+ return [];
+ const names = new Set;
+ for (let node = mesh;node; node = node.parent) {
+ if (!node.name)
+ continue;
+ names.add(node.name);
+ if (node.name.startsWith("Mesh_"))
+ names.add(node.name.slice(5));
+ }
+ return supports.filter((support) => support.parts.some((part) => names.has(part)));
+}
+var EXTERNAL_SUPPORT_TOLERANCE = 0.02;
+
// src/lod.ts
function lodName(name) {
const match = LOD_TOKEN.exec(name);
@@ -16989,7 +17008,7 @@ var init_lod2 = __esm(() => {
// src/qa/part-connectivity.ts
import * as THREE22 from "three";
-function collectParts2(root, exempt) {
+function collectParts2(root, exempt, supports) {
const parts = [];
let lodExcluded = 0;
root.updateWorldMatrix(true, true);
@@ -17009,7 +17028,8 @@ function collectParts2(root, exempt) {
const box = new THREE22.Box3().setFromObject(mesh);
if (box.isEmpty())
return;
- parts.push({ name, box });
+ const support = restingSupport(mesh, box.min.y, supports);
+ parts.push({ name, box, ...support ? { support } : {} });
});
return { parts, lodExcluded };
}
@@ -17019,9 +17039,9 @@ function boxGap(a, b) {
const dz = Math.max(0, Math.max(a.min.z - b.max.z, b.min.z - a.max.z));
return Math.hypot(dx, dy, dz);
}
-function analyzePartConnectivity(root) {
+function analyzePartConnectivity(root, supports) {
const exempt = [];
- const { parts, lodExcluded } = collectParts2(root, exempt);
+ const { parts, lodExcluded } = collectParts2(root, exempt, supports);
const report = {
partsAnalyzed: parts.length,
mainComponentSize: parts.length,
@@ -17082,22 +17102,48 @@ function analyzePartConnectivity(root) {
gap = Math.min(gap, boxGap(parts[m].box, parts[b].box));
}
}
+ const lowest = members.reduce((a, b) => parts[b].box.min.y < parts[a].box.min.y ? b : a);
+ const support = parts[lowest].support;
report.groups.push({
parts: members.map((m) => parts[m].name),
- gap: Math.round(gap * 1e6) / 1e6
+ gap: Math.round(gap * 1e6) / 1e6,
+ ...support && members.every((m) => parts[m].support) ? {
+ externalSupport: {
+ planeY: support.planeY,
+ bottomY: Math.round(parts[lowest].box.min.y * 1e6) / 1e6,
+ tolerance: support.tolerance ?? CONNECTIVITY_TOLERANCE
+ }
+ } : {}
});
}
report.groups.sort((a, b) => b.parts.length - a.parts.length || a.gap - b.gap);
return report;
}
-function inspectPartConnectivity(scene) {
+function inspectPartConnectivity(scene, supports) {
if (!(scene instanceof THREE22.Object3D))
return [];
- const report = analyzePartConnectivity(scene);
+ const report = analyzePartConnectivity(scene, supports);
const lodNote = report.lodExcluded === 1 ? " 1 part on an LOD level above 0 was not analyzed." : report.lodExcluded > 1 ? ` ${report.lodExcluded} parts on LOD levels above 0 were not analyzed.` : "";
return report.groups.map((group) => {
const listed = group.parts.map((p) => JSON.stringify(p)).join(", ");
const subject = group.parts.length === 1 ? `Part ${listed} is` : `A group of ${group.parts.length} parts (${listed}) is`;
+ const declared = group.externalSupport;
+ if (declared)
+ return {
+ code: "GEO_PART_EXTERNAL_SUPPORT",
+ disposition: "observe",
+ dimension: "visualQuality",
+ profile: "geometry.partConnectivity",
+ message: `${subject} separate from the largest component and rests on the support declared in requirements.externalSupport at Y=${declared.planeY.toFixed(3)} m (bottom at Y=${declared.bottomY.toFixed(3)} m). Information only: the support is composed outside this asset.${lodNote}`,
+ affected: { node: group.parts[0] },
+ measurement: {
+ name: "bottomToSupportPlane",
+ actual: declared.bottomY,
+ expected: declared.planeY,
+ threshold: declared.tolerance
+ },
+ repairText: "No change is needed for a declared support. Remove the part from requirements.externalSupport if it should attach within this asset."
+ };
return {
code: "GEO_PART_CONNECTIVITY",
disposition: "observe",
@@ -19861,7 +19907,7 @@ function createAssetRequirementsV1(input = {}) {
...input
});
}
-var text2, positive2, nonnegative, count3, names, marker, roof, structure, effects, requirements, AssetRequirementsV1Schema;
+var text2, positive2, nonnegative, count3, names, marker, supportParts, roof, structure, effects, requirements, AssetRequirementsV1Schema;
var init_requirements = __esm(() => {
init_asset();
init_breadth();
@@ -19873,6 +19919,9 @@ var init_requirements = __esm(() => {
message: "Values must be unique."
});
marker = z5.strictObject({});
+ supportParts = z5.array(text2).min(1).max(256).refine((values) => new Set(values).size === values.length, {
+ message: "Values must be unique."
+ });
roof = z5.strictObject({
type: text2.optional(),
ridgeAxis: z5.enum(["x", "z"]).optional(),
@@ -19992,6 +20041,13 @@ var init_requirements = __esm(() => {
precomputedTangents: z5.boolean().optional(),
skinned: z5.boolean().optional()
})).optional(),
+ externalSupport: statement(z5.strictObject({
+ supports: z5.array(z5.strictObject({
+ parts: supportParts,
+ planeY: z5.number().finite(),
+ tolerance: nonnegative.max(0.5).optional()
+ })).min(1).max(32)
+ })).optional(),
access: statement(z5.strictObject({ enterable: z5.boolean().optional(), driveable: z5.boolean().optional() })).optional()
});
AssetRequirementsV1Schema = z5.strictObject({
@@ -20288,7 +20344,8 @@ function resolveRequirementsApplicability(requirements) {
grounding: ["planeY"],
bounds: ["units", "x", "y", "z"],
animation: ["clips"],
- representation: ["precomputedTangents"]
+ representation: ["precomputedTangents"],
+ externalSupport: ["supports"]
};
for (const [key, statement] of Object.entries(requirements.requirements)) {
if (statement?.state !== "requested")
@@ -21001,7 +21058,7 @@ function runRequirementsSceneQa(context, scene, clips, policy = {}, evidence = {
findings.push(decision.mode === "observe" || decision.mode === "warn" ? { ...finding, disposition: decision.mode } : finding);
continue;
}
- const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({
+ const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene, needs.externalSupport?.state === "requested" ? needs.externalSupport.value.supports : undefined) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({
profile: "asset.requirements.v1",
scope: { schemaVersion: 1, scope: scope.value, explicit: true },
derivedEvidence: { source: "engine-scene-analysis", assetScope: scopeObservation }
@@ -37814,7 +37871,10 @@ async function renderSceneToGLB(root, opts = {}) {
const materialResourceProvenance = collectMaterialResourceProvenance(root);
for (const w of inspectGeneratedAnimation(root, clips))
warnings.push(w);
- for (const w of inspectSceneStructure(root))
+ const externalSupport = requirements.requirements.requirements.externalSupport;
+ for (const w of inspectSceneStructure(root, {
+ ...externalSupport?.state === "requested" ? { externalSupport: externalSupport.value.supports } : {}
+ }))
warnings.push(w);
const atlas = collectAtlasProvenance(root);
const bakedTextures = await bakeSceneTextures(root, warnings);
@@ -38150,6 +38210,7 @@ function collectMeshStats(root) {
box.getCenter(center);
box.getSize(size);
out.push({
+ object: obj,
name: obj.name || "(unnamed)",
triCount: Math.floor(tri),
isPlaneGeo: geo.type === "PlaneGeometry",
@@ -38208,6 +38269,7 @@ function inspectSceneStructure(root, opts = {}) {
}
if (meshes.length > 1) {
const floaters = [];
+ const supported = [];
for (let i = 0;i < meshes.length; i++) {
const a = meshes[i];
const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);
@@ -38223,6 +38285,12 @@ function inspectSceneStructure(root, opts = {}) {
}
if (overlapsAny)
continue;
+ const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);
+ if (support) {
+ supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);
+ continue;
+ }
+ const declared = declaredSupports(a.object, opts.externalSupport)[0];
let nearest;
let nearestGap;
for (let j = 0;j < meshes.length; j++) {
@@ -38235,7 +38303,8 @@ function inspectSceneStructure(root, opts = {}) {
}
}
const fix = nearest && nearestGap ? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.` : "";
- floaters.push({ name: a.name, fix });
+ const mismatch = declared ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.` : "";
+ floaters.push({ name: a.name, fix: fix + mismatch });
}
if (floaters.length > 0) {
const entries = floaters.slice(0, FLOATER_FIXES_SHOWN).map(({ name, fix }) => `${name}${fix ? ` —${fix}` : ""}`);
@@ -38248,6 +38317,12 @@ function inspectSceneStructure(root, opts = {}) {
}
warnings.push(`Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(" | ")}`);
}
+ if (supported.length > 0) {
+ const shown = supported.slice(0, FLOATER_NAMES_SHOWN);
+ if (supported.length > shown.length)
+ shown.push(`+${supported.length - shown.length} more`);
+ warnings.push(`Declared external support (requirements.externalSupport): ${shown.join(", ")} rest on a support composed outside this asset; information only, no action needed.`);
+ }
}
return warnings;
}
diff --git a/docs/migration.md b/docs/migration.md
index 6a4a1a06..58208f3d 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -440,6 +440,24 @@ session's policy; start a new session to select a reviewed binding. Each bound
server serves one task/asset lineage. Omit the flag for ordinary neutral authoring.
Tool arguments and source metadata cannot select or replace the host binding.
+A binding can state that named parts rest on a support composed outside the asset,
+such as cushions authored for the seat of a separate structure module:
+
+```json
+"externalSupport": {
+ "state": "requested",
+ "value": { "supports": [{ "parts": ["Cushion_L", "BackCushions"], "planeY": 0.45 }] },
+ "reason": "The seat is a separate module"
+}
+```
+
+A part matches by its name, its name without the `Mesh_` prefix that `createPart`
+adds, or an ancestor's name. When its world bottom lies within `tolerance` (default
+0.02 m) of `planeY`, the floating-parts warning lists it on a separate informational
+line and the connectivity observation becomes `GEO_PART_EXTERNAL_SUPPORT`, naming the
+declaration. A named part at another height stays a floating part with the mismatch
+stated. Other parts and dispositions are unchanged. The declaration is part of the
+policy hash; its `reason` is not.
## Review explicit legacy data conversion
Library callers of `@instruktlabs/kiln/qa` now use `collectRequirementsSceneEvidence`
diff --git a/src/contracts/requirements.ts b/src/contracts/requirements.ts
index 7420c930..32a18cfb 100644
--- a/src/contracts/requirements.ts
+++ b/src/contracts/requirements.ts
@@ -37,6 +37,13 @@ const names = z.array(text).refine((values) => new Set(values).size === values.l
message: 'Values must be unique.',
});
const marker = z.strictObject({});
+const supportParts = z
+ .array(text)
+ .min(1)
+ .max(256)
+ .refine((values) => new Set(values).size === values.length, {
+ message: 'Values must be unique.',
+ });
/** An absent statement is unspecified. Inference is advice, never an enforced demand. */
export type RequirementStatement<T> =
@@ -221,6 +228,24 @@ const requirements = z.strictObject({
skinned: z.boolean().optional(),
}),
).optional(),
+ /**
+ * Named parts rest on a support composed outside this asset, such as cushions on a separate
+ * seat module. A detached part whose bottom meets its plane is reported as information.
+ */
+ externalSupport: statement(
+ z.strictObject({
+ supports: z
+ .array(
+ z.strictObject({
+ parts: supportParts,
+ planeY: z.number().finite(),
+ tolerance: nonnegative.max(0.5).optional(),
+ }),
+ )
+ .min(1)
+ .max(32),
+ }),
+ ).optional(),
/** Preserve explicit functional capabilities without a semantic category. */
access: statement(
z.strictObject({ enterable: z.boolean().optional(), driveable: z.boolean().optional() }),
diff --git a/src/external-support.ts b/src/external-support.ts
new file mode 100644
index 00000000..971ea81b
--- /dev/null
+++ b/src/external-support.ts
@@ -0,0 +1,46 @@
+/**
+ * Requirements-declared external support (`requirements.externalSupport`): named parts rest
+ * on something composed outside this asset, such as cushions on a separate seat module.
+ * The declaration is the host's statement; the part's measured bottom must still meet the
+ * stated plane before a floating observation is reported as information.
+ */
+import type * as THREE from 'three';
+
+export interface ExternalSupportV1 {
+ /** Part or group names; a mesh matches by its name, its `Mesh_`-less name or an ancestor. */
+ parts: string[];
+ /** Asset-frame height of the external contact plane, in metres. */
+ planeY: number;
+ /** Allowed distance between a part's bottom and planeY. Default 0.02 m. */
+ tolerance?: number;
+}
+
+/** Matches the floating-parts and connectivity adjacency tolerance. */
+export const EXTERNAL_SUPPORT_TOLERANCE = 0.02;
+
+/** The support whose parts name this mesh and whose plane its world bottom meets. */
+export function restingSupport(
+ mesh: THREE.Object3D,
+ bottomY: number,
+ supports: readonly ExternalSupportV1[] | undefined,
+): ExternalSupportV1 | undefined {
+ return declaredSupports(mesh, supports).find(
+ (support) =>
+ Math.abs(bottomY - support.planeY) <= (support.tolerance ?? EXTERNAL_SUPPORT_TOLERANCE),
+ );
+}
+
+/** Every support that names this mesh or one of its ancestors. */
+export function declaredSupports(
+ mesh: THREE.Object3D,
+ supports: readonly ExternalSupportV1[] | undefined,
+): ExternalSupportV1[] {
+ if (!supports?.length) return [];
+ const names = new Set<string>();
+ for (let node: THREE.Object3D | null = mesh; node; node = node.parent) {
+ if (!node.name) continue;
+ names.add(node.name);
+ if (node.name.startsWith('Mesh_')) names.add(node.name.slice(5));
+ }
+ return supports.filter((support) => support.parts.some((part) => names.has(part)));
+}
diff --git a/src/qa/external-support.test.ts b/src/qa/external-support.test.ts
new file mode 100644
index 00000000..7e42d7f9
--- /dev/null
+++ b/src/qa/external-support.test.ts
@@ -0,0 +1,148 @@
+import { expect, test } from 'bun:test';
+import * as THREE from 'three';
+import { createAssetRequirementsV1, type AssetRequirementsV1 } from '../contracts/requirements';
+import { renderSceneToGLB, inspectSceneStructure } from '../render';
+import { createAssetRequirementsStore } from '../requirements-store';
+import { resolveRequirementsContext } from '../requirements-context';
+import { runRequirementsSceneQa } from './requirements-run';
+
+/** Cushions authored to rest on the seat of a separate structure module, as in the Cove pass. */
+function cushions() {
+ const root = new THREE.Group();
+ root.name = 'SofaSoft';
+ const box = (name: string, x: number, bottom: number, parent: THREE.Object3D = root) => {
+ const mesh = new THREE.Mesh(
+ new THREE.BoxGeometry(0.5, 0.15, 0.5),
+ new THREE.MeshStandardMaterial(),
+ );
+ mesh.name = name;
+ mesh.position.set(x, bottom + 0.075, 0);
+ parent.add(mesh);
+ return mesh;
+ };
+ box('Throw', 0, 0); // on the floor: the main body of this module
+ box('Mesh_Cushion_L', -1, 0.45); // createPart('Cushion_L') names its mesh Mesh_Cushion_L
+ const back = new THREE.Group();
+ back.name = 'BackCushions';
+ root.add(back);
+ box('Back_A', 1, 0.45, back);
+ box('Pillow', 2, 0.6); // declared, but not at the declared seat height
+ box('Lamp', -2, 1.6); // not declared
+ return root;
+}
+const SUPPORT: AssetRequirementsV1['requirements'] = {
+ externalSupport: {
+ state: 'requested',
+ value: { supports: [{ parts: ['Cushion_L', 'BackCushions', 'Pillow'], planeY: 0.45 }] },
+ reason: 'Seat structure is a separate module',
+ },
+};
+function bind(requirements: AssetRequirementsV1['requirements']) {
+ return createAssetRequirementsStore().host.bind(
+ { taskId: 'cove', lineageId: 'sofa' },
+ createAssetRequirementsV1({ labels: ['prop'], requirements }),
+ { actor: 'owner', source: 'brief', reason: 'Fixture requirement' },
+ );
+}
+/** The parts a floating-parts warning reports, not the siblings its fixes point toward. */
+const floaterNames = (warning: string | undefined) =>
+ (warning ?? '')
+ .slice(warning!.indexOf(': ') + 2)
+ .split(' | ')
+ .map((entry) => entry.split(' —')[0])
+ .sort();
+const findings = (requirements: AssetRequirementsV1['requirements']) => {
+ const report = runRequirementsSceneQa(
+ resolveRequirementsContext(bind(requirements)),
+ cushions(),
+ [],
+ {},
+ );
+ return { report, all: Object.values(report.dimensions).flatMap((d) => d.findings) };
+};
+
+test('a declared external support makes those parts informational and leaves the rest alone', () => {
+ const { report, all } = findings(SUPPORT);
+ expect(report.unevaluatedRequirements).toEqual([]);
+ const supported = all.filter((f) => f.code === 'GEO_PART_EXTERNAL_SUPPORT');
+ expect(supported.map((f) => f.affected?.node).sort()).toEqual(['Back_A', 'Mesh_Cushion_L']);
+ for (const finding of supported) {
+ expect(finding.disposition).toBe('observe');
+ expect(finding.message).toContain('requirements.externalSupport');
+ expect(finding.measurement).toMatchObject({ name: 'bottomToSupportPlane', expected: 0.45 });
+ }
+ const floating = all.filter((f) => f.code === 'GEO_PART_CONNECTIVITY');
+ expect(floating.map((f) => f.affected?.node).sort()).toEqual(['Lamp', 'Pillow']);
+ // Without the declaration every detached part keeps the existing observation.
+ const plain = findings({}).all.filter((f) => f.code === 'GEO_PART_CONNECTIVITY');
+ expect(plain.map((f) => f.affected?.node).sort()).toEqual([
+ 'Back_A',
+ 'Lamp',
+ 'Mesh_Cushion_L',
+ 'Pillow',
+ ]);
+});
+
+test('the floating-parts warning names declared support as information, not as a defect', () => {
+ const supports = [{ parts: ['Cushion_L', 'BackCushions', 'Pillow'], planeY: 0.45 }];
+ const warnings = inspectSceneStructure(cushions(), { externalSupport: supports });
+ const floating = warnings.find((w) => w.startsWith('Floating parts'))!;
+ expect(floating).toContain('Lamp');
+ expect(floating).toContain('Pillow');
+ expect(floating).toContain('declared external support at Y=0.450');
+ expect(floaterNames(floating)).toEqual(['Lamp', 'Pillow', 'Throw']);
+ const declared = warnings.find((w) => w.startsWith('Declared external support'))!;
+ expect(declared).toContain('requirements.externalSupport');
+ expect(declared).toContain('Mesh_Cushion_L');
+ expect(declared).toContain('Back_A');
+ expect(declared).toContain('no action needed');
+ const plain = inspectSceneStructure(cushions());
+ expect(plain.some((w) => w.startsWith('Declared external support'))).toBe(false);
+ expect(floaterNames(plain.find((w) => w.startsWith('Floating parts')))).toEqual([
+ 'Back_A',
+ 'Lamp',
+ 'Mesh_Cushion_L',
+ 'Pillow',
+ 'Throw',
+ ]);
+});
+
+test('render reads the declaration from the bound requirements', async () => {
+ const result = await renderSceneToGLB(cushions(), { requirements: bind(SUPPORT) });
+ expect(result.warnings.find((w) => w.startsWith('Declared external support'))).toContain(
+ 'Mesh_Cushion_L',
+ );
+ expect(floaterNames(result.warnings.find((w) => w.startsWith('Floating parts')))).toEqual([
+ 'Lamp',
+ 'Pillow',
+ 'Throw',
+ ]);
+});
+
+test('the declaration is part of the requirements policy and validated strictly', () => {
+ const hash = (planeY: number, reason: string) =>
+ bind({
+ externalSupport: {
+ state: 'requested',
+ value: { supports: [{ parts: ['Cushion_L'], planeY }] },
+ reason,
+ },
+ }).policyHash;
+ expect(hash(0.45, 'one')).toBe(hash(0.45, 'another wording'));
+ expect(hash(0.45, 'one')).not.toBe(hash(0.5, 'one'));
+ expect(hash(0.45, 'one')).not.toBe(bind({}).policyHash);
+ for (const value of [
+ { supports: [] },
+ { supports: [{ parts: [], planeY: 0 }] },
+ { supports: [{ parts: ['A', 'A'], planeY: 0 }] },
+ { supports: [{ parts: ['A'], planeY: Number.NaN }] },
+ { supports: [{ parts: ['A'], planeY: 0, tolerance: -1 }] },
+ { supports: [{ parts: ['A'], planeY: 0, height: 1 }] },
+ ])
+ expect(() =>
+ createAssetRequirementsV1({
+ labels: ['prop'],
+ requirements: { externalSupport: { state: 'requested', value: value as never } },
+ }),
+ ).toThrow();
+});
diff --git a/src/qa/part-connectivity.ts b/src/qa/part-connectivity.ts
index 2000da99..666a1c86 100644
--- a/src/qa/part-connectivity.ts
+++ b/src/qa/part-connectivity.ts
@@ -34,6 +34,7 @@
*/
import * as THREE from 'three';
+import { type ExternalSupportV1, restingSupport } from '../external-support';
import { lodLevel } from './lod';
import { KILN_ENGINE_QA_OWNER, type QaRule } from './registry';
import type { QaContext, QaFinding } from './types';
@@ -56,6 +57,8 @@ const EXEMPT_NAME = /(?:^|_)(?:leaf|leaves|foliage|frond|card|decal|billboard|pe
interface ConnectivityPart {
name: string;
box: THREE.Box3;
+ /** The requirements-declared external support this part's bottom meets, if any. */
+ support?: ExternalSupportV1;
}
export interface DisconnectedGroupV1 {
@@ -63,6 +66,8 @@ export interface DisconnectedGroupV1 {
parts: string[];
/** Shortest distance from this component to the main one, in meters. */
gap: number;
+ /** Present when every part rests on a requirements-declared external support. */
+ externalSupport?: { planeY: number; bottomY: number; tolerance: number };
}
export interface PartConnectivityReportV1 {
@@ -83,6 +88,7 @@ export interface PartConnectivityReportV1 {
function collectParts(
root: THREE.Object3D,
exempt: string[],
+ supports?: readonly ExternalSupportV1[],
): { parts: ConnectivityPart[]; lodExcluded: number } {
const parts: ConnectivityPart[] = [];
let lodExcluded = 0;
@@ -101,7 +107,8 @@ function collectParts(
}
const box = new THREE.Box3().setFromObject(mesh);
if (box.isEmpty()) return;
- parts.push({ name, box });
+ const support = restingSupport(mesh, box.min.y, supports);
+ parts.push({ name, box, ...(support ? { support } : {}) });
});
return { parts, lodExcluded };
}
@@ -120,9 +127,12 @@ function boxGap(a: THREE.Box3, b: THREE.Box3): number {
* Exported for testing and for anything that wants the structure rather than
* the finding.
*/
-export function analyzePartConnectivity(root: THREE.Object3D): PartConnectivityReportV1 {
+export function analyzePartConnectivity(
+ root: THREE.Object3D,
+ supports?: readonly ExternalSupportV1[],
+): PartConnectivityReportV1 {
const exempt: string[] = [];
- const { parts, lodExcluded } = collectParts(root, exempt);
+ const { parts, lodExcluded } = collectParts(root, exempt, supports);
const report: PartConnectivityReportV1 = {
partsAnalyzed: parts.length,
mainComponentSize: parts.length,
@@ -187,9 +197,21 @@ export function analyzePartConnectivity(root: THREE.Object3D): PartConnectivityR
gap = Math.min(gap, boxGap(parts[m]!.box, parts[b]!.box));
}
}
+ // The lowest part names the plane the group rests on when all of it is declared.
+ const lowest = members.reduce((a, b) => (parts[b]!.box.min.y < parts[a]!.box.min.y ? b : a));
+ const support = parts[lowest]!.support;
report.groups.push({
parts: members.map((m) => parts[m]!.name),
gap: Math.round(gap * 1e6) / 1e6,
+ ...(support && members.every((m) => parts[m]!.support)
+ ? {
+ externalSupport: {
+ planeY: support.planeY,
+ bottomY: Math.round(parts[lowest]!.box.min.y * 1e6) / 1e6,
+ tolerance: support.tolerance ?? CONNECTIVITY_TOLERANCE,
+ },
+ }
+ : {}),
});
}
@@ -205,9 +227,12 @@ export function analyzePartConnectivity(root: THREE.Object3D): PartConnectivityR
* `exact` is reserved for rules already enforcing on frozen conformance
* evidence, so a new gate is `heuristic` however precise its arithmetic.
*/
-export function inspectPartConnectivity(scene: unknown): readonly QaFinding[] {
+export function inspectPartConnectivity(
+ scene: unknown,
+ supports?: readonly ExternalSupportV1[],
+): readonly QaFinding[] {
if (!(scene instanceof THREE.Object3D)) return [];
- const report = analyzePartConnectivity(scene);
+ const report = analyzePartConnectivity(scene, supports);
const lodNote =
report.lodExcluded === 1
? ' 1 part on an LOD level above 0 was not analyzed.'
@@ -220,6 +245,24 @@ export function inspectPartConnectivity(scene: unknown): readonly QaFinding[] {
group.parts.length === 1
? `Part ${listed} is`
: `A group of ${group.parts.length} parts (${listed}) is`;
+ const declared = group.externalSupport;
+ if (declared)
+ return {
+ code: 'GEO_PART_EXTERNAL_SUPPORT',
+ disposition: 'observe' as const,
+ dimension: 'visualQuality' as const,
+ profile: 'geometry.partConnectivity',
+ message: `${subject} separate from the largest component and rests on the support declared in requirements.externalSupport at Y=${declared.planeY.toFixed(3)} m (bottom at Y=${declared.bottomY.toFixed(3)} m). Information only: the support is composed outside this asset.${lodNote}`,
+ affected: { node: group.parts[0]! },
+ measurement: {
+ name: 'bottomToSupportPlane',
+ actual: declared.bottomY,
+ expected: declared.planeY,
+ threshold: declared.tolerance,
+ },
+ repairText:
+ 'No change is needed for a declared support. Remove the part from requirements.externalSupport if it should attach within this asset.',
+ };
return {
code: 'GEO_PART_CONNECTIVITY',
disposition: 'observe' as const,
diff --git a/src/qa/requirements-applicability.ts b/src/qa/requirements-applicability.ts
index 3fb9cb5a..2de004af 100644
--- a/src/qa/requirements-applicability.ts
+++ b/src/qa/requirements-applicability.ts
@@ -187,6 +187,7 @@ export function resolveRequirementsApplicability(
bounds: ['units', 'x', 'y', 'z'],
animation: ['clips'],
representation: ['precomputedTangents'],
+ externalSupport: ['supports'],
};
for (const [key, statement] of Object.entries(requirements.requirements)) {
if (statement?.state !== 'requested') continue;
diff --git a/src/qa/requirements-run.ts b/src/qa/requirements-run.ts
index 8b285dff..4588a3a4 100644
--- a/src/qa/requirements-run.ts
+++ b/src/qa/requirements-run.ts
@@ -274,7 +274,12 @@ export function runRequirementsSceneQa(
decision.ruleId === SWEEP_QA_RULE.id
? inspectSweepGeometry(scene)
: decision.ruleId === PART_CONNECTIVITY_QA_RULE.id
- ? inspectPartConnectivity(scene)
+ ? inspectPartConnectivity(
+ scene,
+ needs.externalSupport?.state === 'requested'
+ ? needs.externalSupport.value.supports
+ : undefined,
+ )
: decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === 'requested'
? inspectAssetScope({
profile: 'asset.requirements.v1',
diff --git a/src/render.ts b/src/render.ts
index b589bb81..ccc2605e 100644
--- a/src/render.ts
+++ b/src/render.ts
@@ -1,4 +1,5 @@
import type { DuckClip } from './views/pose';
+import { declaredSupports, type ExternalSupportV1, restingSupport } from './external-support';
import {
assertNoLegacyRuntimePolicy,
resolveRequirementsContext,
@@ -1791,7 +1792,13 @@ export async function renderSceneToGLB(
// pivot" hint is first; the bridge also emits a briefer "target not
// found - skipped" for each unresolved track (kept for compatibility).
for (const w of inspectGeneratedAnimation(root, clips)) warnings.push(w);
- for (const w of inspectSceneStructure(root)) warnings.push(w);
+ const externalSupport = requirements.requirements.requirements.externalSupport;
+ for (const w of inspectSceneStructure(root, {
+ ...(externalSupport?.state === 'requested'
+ ? { externalSupport: externalSupport.value.supports }
+ : {}),
+ }))
+ warnings.push(w);
// T2.2 — encode in-memory textures to PNG BEFORE QA, so QA judges the file
// that will actually be written. A procedural DataTexture used to reach the
@@ -2752,6 +2759,7 @@ export function inspectGeneratedAnimation(
// =============================================================================
interface MeshStats {
+ object: THREE.Object3D;
name: string;
triCount: number;
isPlaneGeo: boolean;
@@ -2798,6 +2806,7 @@ function collectMeshStats(root: THREE.Object3D): MeshStats[] {
box.getSize(size);
out.push({
+ object: obj,
name: obj.name || '(unnamed)',
triCount: Math.floor(tri),
isPlaneGeo: geo.type === 'PlaneGeometry',
@@ -2837,6 +2846,8 @@ function collectMeshStats(root: THREE.Object3D): MeshStats[] {
export interface InspectStructureOptions {
/** Asset kind for the orientation advisory. Omit to skip it. */
category?: 'vehicle' | 'weapon' | 'boat' | 'aircraft' | (string & {});
+ /** requirements.externalSupport: named parts that rest on a support outside this asset. */
+ externalSupport?: readonly ExternalSupportV1[];
}
/** Floating parts named with their own fix; the rest share one line of names. */
@@ -2900,6 +2911,7 @@ export function inspectSceneStructure(
if (meshes.length > 1) {
const floaters: { name: string; fix: string }[] = [];
+ const supported: string[] = [];
for (let i = 0; i < meshes.length; i++) {
const a = meshes[i]!;
const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);
@@ -2913,6 +2925,13 @@ export function inspectSceneStructure(
}
}
if (overlapsAny) continue;
+ // A declared external support whose plane this part's bottom meets is information.
+ const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);
+ if (support) {
+ supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);
+ continue;
+ }
+ const declared = declaredSupports(a.object, opts.externalSupport)[0];
// Actionable fix: the minimal shift to the NEAREST sibling, plus the
// snapTo call that applies it.
@@ -2930,7 +2949,10 @@ export function inspectSceneStructure(
nearest && nearestGap
? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.`
: '';
- floaters.push({ name: a.name, fix });
+ const mismatch = declared
+ ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.`
+ : '';
+ floaters.push({ name: a.name, fix: fix + mismatch });
}
if (floaters.length > 0) {
// The per-part fix text is 170 characters; a scattered asset repeated it
@@ -2951,6 +2973,13 @@ export function inspectSceneStructure(
`Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(' | ')}`,
);
}
+ if (supported.length > 0) {
+ const shown = supported.slice(0, FLOATER_NAMES_SHOWN);
+ if (supported.length > shown.length) shown.push(`+${supported.length - shown.length} more`);
+ warnings.push(
+ `Declared external support (requirements.externalSupport): ${shown.join(', ')} rest on a support composed outside this asset; information only, no action needed.`,
+ );
+ }
}
return warnings;