3D engine that AI agents drive
Load the coplanar detector on demand instead of in core (part of #310)
Nguyen Xuan An859760696e4a
diff --git a/bench/size/budgets.json b/bench/size/budgets.jsonindex 8f4fd6de..818cb080 100644--- a/bench/size/budgets.json+++ b/bench/size/budgets.json@@ -6,7 +6,7 @@"agent-scene": 100000},"budgets": {- "entry:core": 91470,+ "entry:core": 89060,"entry:model": 14400,"entry:nature": 13200,"entry:motion": 15260,@@ -34,22 +34,23 @@"entry:ground-bounce": 9460,"entry:path-tracer": 15960,"entry:texture-set": 900,- "entry:agent-scene": 83620,- "entry:agent-scene+lazy": 266200,- "entry:agent-asset": 115100,- "entry:agent-asset+lazy": 277650,+ "entry:agent-scene": 81310,+ "entry:agent-scene+lazy": 266850,+ "entry:agent-asset": 112690,+ "entry:agent-asset+lazy": 278200,"entry:hdri": 3300,"entry:camera-effects": 8600,"entry:water-reflection": 26580,"entry:render-passes": 1700,+ "entry:coplanar-overlap": 2960,"entry:gaussian-splats": 11023,"entry:material-layer-shaders": 21400,"entry:light-linking": 19720,"entry:cascaded-shadows": 28530,- "scene:lit-box": 68540,- "scene:gltf-box": 92810,- "scene:gltf-box+lazy": 96140,- "scene:agent-scene": 112860,- "scene:agent-scene+lazy": 295440+ "scene:lit-box": 66060,+ "scene:gltf-box": 90320,+ "scene:gltf-box+lazy": 93650,+ "scene:agent-scene": 110330,+ "scene:agent-scene+lazy": 295870}}diff --git a/docs/guide.md b/docs/guide.mdindex 257cd63d..f7fe072f 100644--- a/docs/guide.md+++ b/docs/guide.md@@ -196,7 +196,7 @@ The `surfaces` mode finds triangle contact. The `closed-solids` mode also testsAn index also supports `raycast(matrix, ray)` for a triangle number, hit point and barycentric coordinates.The [mesh query contract](https://github.com/codepawl/67.js/blob/main/docs/mesh-query.md) describes results, solid validation, numerical limits and budget errors.Rebuild indices after geometry edits. Queries reject skin and morph channels.-Contact results do not measure penetration depth or resolve collisions. Z-fighting has its own check: `renderer.diagnostics` and `scene_inspect` report `coplanar-overlap` for two parts that draw the same plane (within 1 mm, same facing, at least 1 cm2 shared). Fix it with `decal: true` on the smaller part (layer 1; `depthLayer` 0 to 4 orders stacked decals), or `environment.resolveCoplanar: 'offset'` to bias the smaller part of every flagged pair. Both draw with a scoped polygon offset in the colour pass and render passes, and never move geometry. Use a real offset along the normal when the gap should be visible in exports or the path tracer. Reversed-Z depth is not implemented yet (#310).+Contact results do not measure penetration depth or resolve collisions. Z-fighting has its own check: `renderer.diagnostics` and `scene_inspect` report `coplanar-overlap` for two parts that draw the same plane (within 1 mm, same facing, at least 1 cm2 shared). Fix it with `decal: true` on the smaller part (layer 1; `depthLayer` 0 to 4 orders stacked decals), or `environment.resolveCoplanar: 'offset'` to bias the smaller part of every flagged pair. Both draw with a scoped polygon offset in the colour pass and render passes, and never move geometry. Use a real offset along the normal when the gap should be visible in exports or the path tracer. The coplanar code is not in the core bundle: call `installCoplanarDiagnostics(renderer)` from `67js/addons/coplanar-overlap` to add the warning to `renderer.diagnostics` (checked once per layout), and `scene_inspect` shows it once `loadAllAgentSceneModules()` (or a recipe with `resolveCoplanar`) has loaded the code. Reversed-Z depth is not implemented yet (#310).## Shrinkwrap and surface patchesdiff --git a/package.json b/package.jsonindex 2ed1dd62..81025d94 100644--- a/package.json+++ b/package.json@@ -83,6 +83,7 @@"./addons/camera-effects": "./build/camera-effects.js","./addons/water-reflection": "./build/water-reflection.js","./addons/render-passes": "./build/render-passes.js",+ "./addons/coplanar-overlap": "./build/coplanar-overlap.js","./addons/material-layer-shaders": "./build/material-layer-shaders.js","./addons/light-linking": "./build/light-linking.js","./addons/cascaded-shadows": "./build/cascaded-shadows.js",diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.jsindex 9006d5ad..f8bd38d0 100644--- a/scripts/agent-preview-browser.js+++ b/scripts/agent-preview-browser.js@@ -5,6 +5,7 @@ import { skyOpenness } from '../src/closed-room.js';import { fogSkyVisibility } from '../src/fog-sky-visibility.js';import { installCameraEffects } from '../src/camera-effects.js';import { installRenderPasses } from '../src/render-passes.js';+import { installCoplanarDiagnostics } from '../src/coplanar-overlap.js';import { applyProjection } from '../src/camera.js';import { mat4 } from 'gl-matrix';import { resolveAgentShadow, agentEnvironmentMap } from '../src/agent-look.js';@@ -218,7 +219,7 @@ function cascadesFor(scene) {function initializeRenderer(scene, { memoryBudgetMiB, backend }) {const placement = agentGroundPlacement(scene.parts, scene.environment);- return installRenderPasses(installCameraEffects(new Renderer67(canvas, scene.parts, {+ return installCoplanarDiagnostics(installRenderPasses(installCameraEffects(new Renderer67(canvas, scene.parts, {ground: placement ? createAgentGround(placement) : false,hdr: true,depth: true,@@ -231,7 +232,7 @@ function initializeRenderer(scene, { memoryBudgetMiB, backend }) {pixelRatio: 1,samples: backend === 'cpu' ? 1 : 4,memoryBudgetMiB,- })));+ }))));}// Camera fields from a timeline shot on top of the sampled camera, checked with the scene's own camera rules.diff --git a/src/agent-scene-modules.js b/src/agent-scene-modules.jsindex 7f6a43eb..322dab7e 100644--- a/src/agent-scene-modules.js+++ b/src/agent-scene-modules.js@@ -21,6 +21,7 @@ const MODULE_LOADERS = {navigation: () => import('./agent-navigation.js'),lightLinking: () => import('./light-linking.js'),cascades: () => import('./cascaded-shadows.js'),+ coplanar: () => import('./coplanar-overlap.js'),};const loadedModules = {};@@ -49,6 +50,8 @@ const MODULE_MARKERS = {navigation: [],lightLinking: ['"affects"', '"keyAffects"'],cascades: ['"shadowCascades"'],+ // The coplanar-overlap warning in scene_inspect appears only once this is loaded, which loadAllAgentSceneModules does; a recipe with resolveCoplanar needs it.+ coplanar: ['"resolveCoplanar"'],};/** Whether a recipe, operation list or edit list contains a boolean edit, which needs loadMeshBooleans() first. */diff --git a/src/agent-scene.js b/src/agent-scene.jsindex 556d5ced..2b9d1564 100644--- a/src/agent-scene.js+++ b/src/agent-scene.js@@ -8,7 +8,7 @@ import { MESH_SMOOTH_ANGLE_DEFAULT, CURVE_TEXT_LIMITS, AGENT_SCENE_CAPABILITIES,import { ALL_LIGHTS_MASK, MATERIAL_LAYER_FIELDS, validateMaterialLayers } from './material-layers.js';import { recipeDiagnostics, closedRoomDiagnostic } from './agent-diagnostics.js';import { closedRoomShare, CLOSED_ROOM_SHARE } from './closed-room.js';-import { coplanarOverlapDiagnostics, depthLayerOf, findCoplanarOverlaps, MAXIMUM_DEPTH_LAYER, resolveCoplanarParts } from './coplanar-overlap.js';+import { depthLayerOf, MAXIMUM_DEPTH_LAYER } from './depth-layer.js';import { armatureNodes, bakeRigExport, bindSkins, createSkinStages, normalizeArmatures, publishSkinPoses, restWorldMatrix, rigReport, stageSkinPoses, transformedBounds, withoutArmatureNodes } from './rig.js';export { AGENT_SCENE_CAPABILITIES, AGENT_SCENE_DEFAULT_LIMITS };export { normalizeAgentLook, resolveAgentShadow } from './agent-look.js';@@ -1177,16 +1177,20 @@ export function createAgentScene(input, inputLimits = {}) {if (coplanarCache?.parts === parts) {return coplanarCache.resolved;}- const resolved = Object.freeze(resolveCoplanarParts(parts));+ const resolved = Object.freeze(agentSceneModule('coplanar').resolveCoplanarParts(parts));coplanarCache = { parts, resolved };return resolved;}- // scene_inspect names coplanar pairs: the check is bounded, runs on inspect only and is kept until the scene changes.+ // scene_inspect names coplanar pairs: the check is bounded, runs on inspect only, once the coplanar code is loaded, and is kept until the scene changes.let coplanarReportCache = null;function coplanarProblems() {+ if (!agentSceneModuleLoaded('coplanar')) {+ return [];+ }if (coplanarReportCache?.revision !== revision) {- coplanarReportCache = { revision, problems: coplanarOverlapDiagnostics(findCoplanarOverlaps(state.parts)) };+ const coplanar = agentSceneModule('coplanar');+ coplanarReportCache = { revision, problems: coplanar.coplanarOverlapDiagnostics(coplanar.findCoplanarOverlaps(state.parts)) };}return coplanarReportCache.problems;}diff --git a/src/coplanar-overlap.js b/src/coplanar-overlap.jsindex 4572c964..2c030179 100644--- a/src/coplanar-overlap.js+++ b/src/coplanar-overlap.js@@ -1,5 +1,8 @@+import { depthLayerOf, MAXIMUM_DEPTH_LAYER } from './depth-layer.js';++// Loaded on demand (renderer diagnostics, scene_inspect, resolveCoplanar), never part of the core bundle.// Finds pairs of parts that draw the same plane in the same place, which z-fight: a sign flush with a wall, a road marking-// on asphalt, two boxes whose visible faces coincide. The work is bounded: a sweep over part bounds, then triangles only+// on asphalt, two boxes whose visible faces coincide. The work is bounded: a grid over part bounds, then triangles only// inside the shared box of a pair, with a fixed budget for the whole scene (`truncated` says it ran out).// Only faces that look the same way count, since a face against a floor looks away from it and is culled. A part with a// double-sided material shows both sides, so there an opposite-facing pair counts too.@@ -8,8 +11,6 @@export const COPLANAR_TOLERANCE = 0.001;/** Overlaps smaller than this (square metres) are edge contact, not a fight. */export const COPLANAR_MINIMUM_AREA = 1e-4;-/** Highest layer `resolveCoplanar` hands out; the draw-time offset grows with the layer. */-export const MAXIMUM_DEPTH_LAYER = 4;/** The distance suggested in the fix text, in metres. */export const SUGGESTED_OFFSET = 0.002;const DEFAULT_WORK_BUDGET = 1_000_000;@@ -159,11 +160,6 @@ function resolvedByLayer(first, second) {return depthLayerOf(first) !== depthLayerOf(second);}-/** The layer a part draws on: `depthLayer` if set, else 1 for `decal: true`, else 0. */-export function depthLayerOf(part) {- return part.depthLayer ?? (part.decal ? 1 : 0);-}-function pairOverlap(first, second, region, tolerance, budget) {const bothSides = first.part.material?.doubleSided === true || second.part.material?.doubleSided === true;const firstTriangles = trianglesInRegion(first.part, region, tolerance);@@ -332,6 +328,23 @@ function diagonalOfPart(part) {return diagonal(worldBounds(part));}+/**+ * Adds the coplanar-overlap warning to `renderer.diagnostics`. The check is bounded (see findCoplanarOverlaps) and runs once+ * per layout, when the renderer's batches change, not per frame, so parts that move later are not rechecked.+ */+export function installCoplanarDiagnostics(renderer) {+ let checkedBatches = null;+ let problems = null;+ renderer.coplanarDiagnostics = batches => {+ if (batches !== checkedBatches) {+ checkedBatches = batches;+ problems = coplanarOverlapDiagnostics(findCoplanarOverlaps(batches.flatMap(batch => batch.parts)));+ }+ return problems;+ };+ return renderer;+}+/** `parts` with `depthLayer` set on the smaller part of each coplanar pair; other parts are returned as they are. */export function resolveCoplanarParts(parts) {const layers = coplanarLayers(findCoplanarOverlaps(parts).overlaps);diff --git a/src/depth-layer.js b/src/depth-layer.jsnew file mode 100644index 00000000..8163d959--- /dev/null+++ b/src/depth-layer.js@@ -0,0 +1,7 @@+/** Highest depth layer; the draw-time polygon offset grows with the layer. */+export const MAXIMUM_DEPTH_LAYER = 4;++/** The layer a part draws on: `depthLayer` if set, else 1 for `decal: true`, else 0. */+export function depthLayerOf(part) {+ return part.depthLayer ?? (part.decal ? 1 : 0);+}diff --git a/src/frame-diagnostics.js b/src/frame-diagnostics.jsindex 6cd5203b..c38fca08 100644--- a/src/frame-diagnostics.js+++ b/src/frame-diagnostics.js@@ -1,5 +1,4 @@import { resolveShadowLight } from './shadow-light.js';-import { coplanarOverlapDiagnostics } from './coplanar-overlap.js';/*** Diagnostics for a frame that renders without error but not as asked. They use the shape of `agent-diagnostics.js`@@ -29,7 +28,7 @@ function shadowDirectionProblem(world, lightDirection, shadowBounds) {'Drop shadowBounds.eye, or point lightDirection from shadowBounds.target to it.');}-export function frameDiagnostics({ world, depth, effects, lightDirection, shadowBounds, coplanarOverlaps = null }) {+export function frameDiagnostics({ world, depth, effects, lightDirection, shadowBounds, coplanarProblems = null }) {const problems = [];if (effects.ambientOcclusion > 0 && !depth) {problems.push(warning('ambient-occlusion-without-depth', 'effects.ambientOcclusion',@@ -40,6 +39,6 @@ export function frameDiagnostics({ world, depth, effects, lightDirection, shadowconst problem = shadowDirectionProblem(world, lightDirection, shadowBounds);if (problem) problems.push(problem);}- if (coplanarOverlaps?.overlaps.length) problems.push(...coplanarOverlapDiagnostics(coplanarOverlaps));+ if (coplanarProblems?.length) problems.push(...coplanarProblems);return problems.length ? problems : NO_DIAGNOSTICS;}diff --git a/src/renderer.js b/src/renderer.jsindex 8064d07a..dae44fd8 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -7,7 +7,7 @@ import { planRenderSize, estimateTextureBytes, estimateFrameBytes } from './budgimport { applyProjection } from './camera.js';import { resolveEffects } from './effects.js';import { frameDiagnostics } from './frame-diagnostics.js';-import { depthLayerOf, findCoplanarOverlaps, MAXIMUM_DEPTH_LAYER } from './coplanar-overlap.js';+import { depthLayerOf } from './depth-layer.js';import { createLightingState, updateLightingState } from './lighting.js';import { SHADOW_ATLAS_WIDTH, SHADOW_ATLAS_HEIGHT, tileViewport, writeShadowTile } from './local-shadows.js';import { resolveVolumeFog, volumeShadowAmbient } from './volumetric.js';@@ -207,14 +207,6 @@ function materialAlphaState(material) {// A decal or depth layer draws with a scoped polygon offset so it wins against the surface it lies on (z-fighting).// Larger layers win over smaller ones; geometry never moves.-const DEPTH_LAYER_UNITS = 4;--function validateDepthLayer(part) {- if (part.decal !== undefined && typeof part.decal !== 'boolean') throw new TypeError('decal must be a boolean');- if (part.depthLayer !== undefined && (!Number.isInteger(part.depthLayer) || part.depthLayer < 0 || part.depthLayer > MAXIMUM_DEPTH_LAYER)) {- throw new RangeError(`depthLayer must be an integer from 0 to ${MAXIMUM_DEPTH_LAYER}`);- }-}// Translucent glass is not a shadow caster unless the part asks for it.function castsShadow(part) {@@ -332,7 +324,6 @@ export function groupParts(parts, batching = true) {const morphInfos = new Map();for (const part of parts) {validateTransform(part);- validateDepthLayer(part);if (part.castShadow !== undefined && typeof part.castShadow !== 'boolean') throw new TypeError('castShadow must be a boolean');validateSkinGeometry(part.geometry, part.skin);if (part.skin) validateSkinPose(part.skin, part.geometry, part.matrix);@@ -486,6 +477,8 @@ export class Renderer67 {this.environment = environment;this.fittedFogDensity = world ? fittedFogDensity(parts) : undefined;this.shadowBounds = shadowBounds;+ /** Set by installCoplanarDiagnostics (coplanar-overlap.js): called with the batches, returns coplanar-overlap warnings. */+ this.coplanarDiagnostics = null;/** Warnings about the last frame drawn, in the shape of `agent-diagnostics.js`; see `frame-diagnostics.js`. */this.diagnostics = [];this.activeLightDirection = environment.lightDirection ?? [-3, 6, 4];@@ -1154,7 +1147,6 @@ export class Renderer67 {this.triangles = parts.reduce((total, part) => total + part.geometry.indices.length / 3, 0);this.updateBatches.clear();this.shadowsDirty = true;- if (this.coplanarState) this.coplanarState.dirty = true;this.updateParts(renderParts);return parts.length;}@@ -1217,8 +1209,7 @@ export class Renderer67 {if (part.skin || part.morph) this.updatePartIdentities.add(part);if (part.castShadow !== undefined && typeof part.castShadow !== 'boolean') throw new TypeError('castShadow must be a boolean');if (castsShadow(part) !== location.batch.castShadow) throw new Error(`Shadow casting changes require a new renderer: ${part.name}`);- validateDepthLayer(part);- if (depthLayerOf(part) !== (location.batch.depthLayer ?? 0)) throw new Error(`Decal and depthLayer changes require replaceParts or a new renderer: ${part.name}`);+ if (depthLayerOf(part) !== (location.batch.depthLayer ?? 0)) throw new Error(`depthLayer changes require replaceParts: ${part.name}`);// A material whose fields still equal the ones that passed the full checks below needs none of them again.const materialUnchanged = location.materialSnapshot?.matches(part.material) === true;if (!materialUnchanged) {@@ -1381,7 +1372,6 @@ export class Renderer67 {this.drawBatch(batch, false, selection, levelSet);}context.disable(context.POLYGON_OFFSET_FILL);- this.activeDepthLayer = 0;context.enable(context.CULL_FACE);}@@ -1947,28 +1937,13 @@ export class Renderer67 {/** Sets the scoped polygon offset of a depth layer for the colour pass; layer 0 is the plain depth test. */applyDepthLayer(layer) {- if (layer === (this.activeDepthLayer ?? 0)) return;const context = this.context;- if (layer > 0) {+ if (layer) {context.enable(context.POLYGON_OFFSET_FILL);- context.polygonOffset(-layer, -layer * DEPTH_LAYER_UNITS);+ context.polygonOffset(-layer, -layer * 4);} else {context.disable(context.POLYGON_OFFSET_FILL);}- this.activeDepthLayer = layer;- }-- /**- * Coplanar-overlap warnings for the parts as first laid out or last replaced. The check is bounded (src/coplanar-overlap.js)- * and runs once per layout, not per frame, so parts that move later are not rechecked.- */- coplanarOverlapReport() {- const state = this.coplanarState ??= { dirty: true, result: null };- if (state.dirty) {- state.result = findCoplanarOverlaps(this.batches.flatMap(batch => batch.parts));- state.dirty = false;- }- return state.result;}/** Reorders a blend batch's instances back to front for this eye; translation columns stand in for object centers. */@@ -2118,7 +2093,7 @@ export class Renderer67 {// The shadow view follows the sun, so a moved sun redraws the map.const lightChanged = String(this.activeLightDirection) !== String(environment.lightDirection);this.activeLightDirection = environment.lightDirection;- this.diagnostics = frameDiagnostics({ world: this.world, depth: this.depth, effects, lightDirection: environment.lightDirection, shadowBounds: this.shadowBounds, coplanarOverlaps: this.benchmark ? null : this.coplanarOverlapReport() });+ this.diagnostics = frameDiagnostics({ world: this.world, depth: this.depth, effects, lightDirection: environment.lightDirection, shadowBounds: this.shadowBounds, coplanarProblems: this.coplanarDiagnostics?.(this.batches) });const start = performance.now();const context = this.context;this.beginGpuTiming();diff --git a/tests/coplanar-overlap.test.js b/tests/coplanar-overlap.test.jsindex c97d2bf3..4bb78695 100644--- a/tests/coplanar-overlap.test.js+++ b/tests/coplanar-overlap.test.js@@ -1,11 +1,15 @@import test from 'node:test';import assert from 'node:assert/strict';import { createAgentScene } from '../src/agent-scene.js';-import { findCoplanarOverlaps, coplanarOverlapDiagnostics, resolveCoplanarParts, depthLayerOf } from '../src/coplanar-overlap.js';+import { findCoplanarOverlaps, coplanarOverlapDiagnostics, installCoplanarDiagnostics, resolveCoplanarParts } from '../src/coplanar-overlap.js';+import { depthLayerOf } from '../src/depth-layer.js';+import { loadAgentSceneModules } from '../src/agent-scene-modules.js';import { frameDiagnostics } from '../src/frame-diagnostics.js';import { groupParts, Renderer67 } from '../src/renderer.js';import { resolveEffects } from '../src/effects.js';+await loadAgentSceneModules({ environment: { resolveCoplanar: 'offset' } });+function node(id, translation, scale, extra = {}) {return { id, geometry: 'box', material: 'paint', translation, scale, ...extra };}@@ -80,8 +84,11 @@ test('node decal and depthLayer are validated', () => {test('renderer diagnostics carry the same warning, and a decal batches apart from its wall', () => {const scene = createAgentScene(recipe([wall, sign]));- const result = findCoplanarOverlaps(scene.parts);- const problems = frameDiagnostics({ world: false, depth: true, effects: resolveEffects({}), coplanarOverlaps: result });+ const renderer = installCoplanarDiagnostics({});+ const batches = [{ parts: scene.parts }];+ const coplanarProblems = renderer.coplanarDiagnostics(batches);+ assert.equal(renderer.coplanarDiagnostics(batches), coplanarProblems, 'the same layout is checked once');+ const problems = frameDiagnostics({ world: false, depth: true, effects: resolveEffects({}), coplanarProblems });assert.deepEqual(problems.map(problem => problem.kind), ['coplanar-overlap']);const resolved = resolveCoplanarParts(scene.parts);assert.equal(groupParts(scene.parts).length, 1);@@ -96,10 +103,7 @@ test('the polygon offset is scoped to the layer and switched off for layer 0', (disable: capability => calls.push(['disable', capability]),polygonOffset: (factor, units) => calls.push(['offset', factor, units]),};- const fake = { context, activeDepthLayer: 0 };- Renderer67.prototype.applyDepthLayer.call(fake, 0);- assert.deepEqual(calls, []);- Renderer67.prototype.applyDepthLayer.call(fake, 2);+ const fake = { context };Renderer67.prototype.applyDepthLayer.call(fake, 2);Renderer67.prototype.applyDepthLayer.call(fake, 0);assert.deepEqual(calls, [['enable', 'fill'], ['offset', -2, -8], ['disable', 'fill']]);diff --git a/vite.lib.config.js b/vite.lib.config.jsindex d4ffbb63..d960e00d 100644--- a/vite.lib.config.js+++ b/vite.lib.config.js@@ -50,6 +50,7 @@ export default defineConfig({'camera-effects': 'src/camera-effects.js','water-reflection': 'src/water-reflection.js','render-passes': 'src/render-passes.js',+ 'coplanar-overlap': 'src/coplanar-overlap.js','material-layer-shaders': 'src/material-layer-shaders.js','light-linking': 'src/light-linking.js','cascaded-shadows': 'src/cascaded-shadows.js',