3D engine that AI agents drive
WIP: plane-keyed coplanar search and flush layers for built parts (issue #593)
Nguyen Xuan Anc7a408abf00c
diff --git a/changes/593.md b/changes/593.mdnew file mode 100644index 00000000..80ffb4f5--- /dev/null+++ b/changes/593.md@@ -0,0 +1 @@+Parts that draw the same plane (a tile on a ceiling, a tread on steel) no longer flicker: the renderer now finds every flush pair when it is built, with no work-budget cutoff on big scenes, and draws the smaller part on a polygon-offset layer; `resolveCoplanar: false` turns it off (#593)diff --git a/changes/593.size.md b/changes/593.size.mdnew file mode 100644index 00000000..a44fb665--- /dev/null+++ b/changes/593.size.md@@ -0,0 +1,11 @@+- entry:core: the renderer runs the coplanar search once at build (src/coplanar-overlap.js is now a core import, 2.5 KB gzip) so every scene with flush parts stops z-fighting without a call from the author; this is a fixed glitch (the metro film showed it on 12 part pairs per run, up to 43000 pixels).+- entry:coplanar-overlap: plane-keyed triangle matching and the flush-layer step replace the capped triangle product.+- entry:reversed-depth: it imports the coplanar module that the core now carries; same code, counted again.+- scene:lit-box: the core import above.+- scene:gltf-box: the core import above.+- scene:gltf-box+lazy: the core import above.+- scene:agent-scene: the core import above; the agent scene loaded the module lazily before.+- scene:agent-scene+lazy: the same module moved from a lazy chunk into the core.+- goal:lit-box: 2.5 KB for default z-fight repair of every scene; needs the lead's trade-off call (functional gain, not a score gain).+- goal:gltf-box: the same 2.5 KB core import.+- goal:agent-scene: the same core import; the lazy chunk it replaces is gone.diff --git a/src/coplanar-overlap.js b/src/coplanar-overlap.jsindex 180a3ca1..cef181ae 100644--- a/src/coplanar-overlap.js+++ b/src/coplanar-overlap.js@@ -1,6 +1,6 @@-import { depthLayerOf, MAXIMUM_DEPTH_LAYER } from './depth-layer.js';+import { depthLayerOf, MAXIMUM_DEPTH_LAYER, setFlushDepthLayers } from './depth-layer.js';-// Loaded on demand (renderer diagnostics, scene_inspect, resolveCoplanar), never part of the core bundle.+// The renderer runs resolveFlushParts once on the parts it is built with; the diagnostics and resolveCoplanar use the same search.// 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 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).@@ -14,7 +14,8 @@ export const COPLANAR_MINIMUM_AREA = 1e-4;/** The distance suggested in the fix text, in metres. */export const SUGGESTED_OFFSET = 0.002;const DEFAULT_WORK_BUDGET = 1_000_000;-const MAXIMUM_TRIANGLES_PER_PART_IN_PAIR = 512;+const PRIORITY_BINS = 12;+const MAXIMUM_LISTED_PAIRS = 3_000_000;const SAME_FACING = Math.cos(Math.PI / 180);const REPORTED_PAIRS = 8;@@ -59,27 +60,37 @@ function determinantSign(matrix) {return determinant < 0 ? -1 : 1;}-// World-space triangles of one part that touch `region`, each as corners (9 numbers) plus a unit normal (3).-function trianglesInRegion(part, region, tolerance) {+// A plane is hashed by its normal (sign folded, 0.01 steps) and its offset (buckets of twice the tolerance), so two+// triangles on one plane meet in a bucket without testing every pair of triangles.+const NORMAL_STEPS = 100;+const OFFSET_BUCKET_RANGE = 2 ** 27;++function planeKey(normal, corners, tolerance) {+ const sign = normal[[0, 1, 2].reduce((best, axis) => (Math.abs(normal[axis]) > Math.abs(normal[best]) ? axis : best), 0)] < 0 ? -1 : 1;+ const [x, y, z] = normal.map(component => Math.round(component * sign * NORMAL_STEPS) + NORMAL_STEPS);+ const offset = (corners[0] * normal[0] + corners[1] * normal[1] + corners[2] * normal[2]) * sign;+ const position = offset / (2 * tolerance);+ const bucket = Math.floor(position);+ const normalKey = (x * (2 * NORMAL_STEPS + 1) + y) * (2 * NORMAL_STEPS + 1) + z;+ const nearer = position - bucket < 0.5 ? bucket - 1 : bucket + 1;+ const toKey = value => normalKey * OFFSET_BUCKET_RANGE + value + OFFSET_BUCKET_RANGE / 2;+ return { own: toKey(bucket), nearer: toKey(nearer) };+}++// Every non-degenerate world-space triangle of a part, each as corners (9 numbers), a unit normal (3) and its plane keys.+function worldTriangles(part, tolerance) {const { positions, indices } = part.geometry;const matrix = part.matrix;const flip = determinantSign(matrix);const triangles = [];- const corners = new Float64Array(9);for (let triangle = 0; triangle < indices.length / 3; triangle++) {- let outside = false;+ const corners = new Float64Array(9);for (let corner = 0; corner < 3; corner++) {const vertex = indices[triangle * 3 + corner] * 3;for (let axis = 0; axis < 3; axis++) {corners[corner * 3 + axis] = matrix[axis] * positions[vertex] + matrix[4 + axis] * positions[vertex + 1] + matrix[8 + axis] * positions[vertex + 2] + matrix[12 + axis];}}- for (let axis = 0; axis < 3 && !outside; axis++) {- const low = Math.min(corners[axis], corners[3 + axis], corners[6 + axis]);- const high = Math.max(corners[axis], corners[3 + axis], corners[6 + axis]);- outside = high < region[axis] - tolerance || low > region[3 + axis] + tolerance;- }- if (outside) continue;const edgeOne = [corners[3] - corners[0], corners[4] - corners[1], corners[5] - corners[2]];const edgeTwo = [corners[6] - corners[0], corners[7] - corners[1], corners[8] - corners[2]];const normal = [@@ -89,12 +100,26 @@ function trianglesInRegion(part, region, tolerance) {];const length = Math.hypot(...normal);if (!(length > 1e-12)) continue;- triangles.push({ corners: Float64Array.from(corners), normal: normal.map(component => component * flip / length) });- if (triangles.length >= MAXIMUM_TRIANGLES_PER_PART_IN_PAIR) break;+ const unitNormal = normal.map(component => component * flip / length);+ triangles.push({ corners, normal: unitNormal, planes: planeKey(unitNormal, corners, tolerance) });}return triangles;}+// The part's triangles that touch `region`; the world-space triangles are built once per part and kept on its entry.+function trianglesInRegion(entry, region, tolerance, budget) {+ entry.triangles ??= worldTriangles(entry.part, tolerance);+ budget.work += entry.triangles.length / 32;+ return entry.triangles.filter(({ corners }) => {+ for (let axis = 0; axis < 3; axis++) {+ const low = Math.min(corners[axis], corners[3 + axis], corners[6 + axis]);+ const high = Math.max(corners[axis], corners[3 + axis], corners[6 + axis]);+ if (high < region[axis] - tolerance || low > region[3 + axis] + tolerance) return false;+ }+ return true;+ });+}+function planeDistance(first, second, corner) {const normal = first.normal;return (second.corners[corner * 3] - first.corners[0]) * normal[0]@@ -160,17 +185,39 @@ function resolvedByLayer(first, second) {return depthLayerOf(first) !== depthLayerOf(second);}+// Whether the boxes of two triangles touch, a cheap test before the plane and area checks.+function trianglesMeet(first, second, tolerance) {+ for (let axis = 0; axis < 3; axis++) {+ const firstLow = Math.min(first.corners[axis], first.corners[3 + axis], first.corners[6 + axis]);+ const firstHigh = Math.max(first.corners[axis], first.corners[3 + axis], first.corners[6 + axis]);+ const secondLow = Math.min(second.corners[axis], second.corners[3 + axis], second.corners[6 + axis]);+ const secondHigh = Math.max(second.corners[axis], second.corners[3 + axis], second.corners[6 + axis]);+ if (firstHigh < secondLow - tolerance || secondHigh < firstLow - tolerance) return false;+ }+ return true;+}+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);- const secondTriangles = trianglesInRegion(second.part, region, tolerance);+ const firstTriangles = trianglesInRegion(first, region, tolerance, budget);+ const secondTriangles = trianglesInRegion(second, region, tolerance, budget);+ const secondByPlane = new Map();+ for (const secondTriangle of secondTriangles) {+ const members = secondByPlane.get(secondTriangle.planes.own);+ if (members) members.push(secondTriangle);+ else secondByPlane.set(secondTriangle.planes.own, [secondTriangle]);+ }let area = 0;let distance = 0;let normal = null;let largestPiece = 0;for (const firstTriangle of firstTriangles) {if (budget.work > budget.limit) break;- for (const secondTriangle of secondTriangles) {+ const sameOffset = secondByPlane.get(firstTriangle.planes.own) ?? [];+ const nearerOffset = secondByPlane.get(firstTriangle.planes.nearer) ?? [];+ for (const secondTriangle of [...sameOffset, ...nearerOffset]) {+ budget.work += 1 / 64;+ if (!trianglesMeet(firstTriangle, secondTriangle, tolerance)) continue;budget.work++;const facing = firstTriangle.normal[0] * secondTriangle.normal[0] + firstTriangle.normal[1] * secondTriangle.normal[1] + firstTriangle.normal[2] * secondTriangle.normal[2];const visibleTogether = facing >= SAME_FACING || (bothSides && facing <= -SAME_FACING);@@ -267,16 +314,31 @@ export function findCoplanarOverlaps(parts, { tolerance = COPLANAR_TOLERANCE, woconst budget = { work: 0, limit: workBudget };const overlaps = [];if (entries.length < 2) return { overlaps, truncated: false, work: 0 };- const test = (first, second) => {- budget.work++;+ // The sweep first lists every pair whose boxes meet (cheap), binned by how much flat contact the shared box offers, so the+ // work budget goes to the pairs that can show a large flush face before it goes to edge contacts and thin slivers.+ const bins = Array.from({ length: PRIORITY_BINS }, () => []);+ let listed = 0;+ const collect = (first, second) => {const region = boundsOverlapRegion(first.bounds, second.bounds, tolerance);- if (!region || resolvedByLayer(first.part, second.part)) return;- const found = pairOverlap(first, second, region, tolerance, budget);- if (!found) return;- const firstIsLarger = diagonal(first.bounds) >= diagonal(second.bounds);- overlaps.push({ smaller: (firstIsLarger ? second : first).part, larger: (firstIsLarger ? first : second).part, ...found });+ if (!region || resolvedByLayer(first.part, second.part) || listed >= MAXIMUM_LISTED_PAIRS) return;+ const extents = [region[3] - region[0], region[4] - region[1], region[5] - region[2]].sort((smallest, largest) => smallest - largest);+ const faceArea = extents[1] * extents[2];+ const flatBonus = extents[0] <= tolerance ? PRIORITY_BINS / 2 : 0;+ const sizeRank = Math.max(0, Math.min(PRIORITY_BINS / 2 - 1, Math.floor(Math.log10(Math.max(faceArea, 1e-6)) + 6)));+ bins[PRIORITY_BINS - 1 - (flatBonus + sizeRank)].push(first, second, region);+ listed++;};- forEachCandidatePair(entries, tolerance, budget, test);+ forEachCandidatePair(entries, tolerance, { work: 0, limit: Infinity }, collect);+ for (const bin of bins) {+ for (let index = 0; index < bin.length && budget.work <= budget.limit; index += 3) {+ const first = bin[index];+ const second = bin[index + 1];+ const found = pairOverlap(first, second, bin[index + 2], tolerance, budget);+ if (!found) continue;+ const firstIsLarger = diagonal(first.bounds) >= diagonal(second.bounds);+ overlaps.push({ smaller: (firstIsLarger ? second : first).part, larger: (firstIsLarger ? first : second).part, ...found });+ }+ }const truncated = budget.work > workBudget;overlaps.sort((first, second) => second.area - first.area || String(first.smaller.name).localeCompare(String(second.smaller.name)));return { overlaps, truncated, work: budget.work };@@ -347,6 +409,16 @@ export function installCoplanarDiagnostics(renderer, onOverlaps = null) {return renderer;}+/**+ * Puts the smaller part of each coplanar pair on the next depth layer (a polygon offset at draw time, geometry never moves),+ * for the parts of one scene. The renderer calls it once when it is built; a part that sets `decal` or `depthLayer` keeps its own.+ */+export function resolveFlushParts(parts) {+ const layers = coplanarLayers(findCoplanarOverlaps(parts).overlaps);+ setFlushDepthLayers(layers);+ return layers.size;+}+/** `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.jsindex 8163d959..cd4f1085 100644--- a/src/depth-layer.js+++ b/src/depth-layer.js@@ -1,7 +1,15 @@/** 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. */+// Layers the renderer gave to parts that draw the same plane as a larger part (coplanar-overlap.js), kept beside the part+// so the part object, and its identity for updateParts, stay as the caller made it.+const flushDepthLayers = new WeakMap();++export function setFlushDepthLayers(layers) {+ for (const [part, layer] of layers) flushDepthLayers.set(part, layer);+}++/** The layer a part draws on: `depthLayer` if set, else 1 for `decal: true`, else the flush layer found for it, else 0. */export function depthLayerOf(part) {- return part.depthLayer ?? (part.decal ? 1 : 0);+ return part.depthLayer ?? (part.decal ? 1 : flushDepthLayers.get(part) ?? 0);}diff --git a/src/renderer.js b/src/renderer.jsindex 78060d5f..739d6f6b 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -9,6 +9,7 @@ import { applyProjection } from './camera.js';import { resolveEffects } from './effects.js';import { frameDiagnostics } from './frame-diagnostics.js';import { depthLayerOf } from './depth-layer.js';+import { resolveFlushParts } from './coplanar-overlap.js';import { createLightingState, updateLightingState } from './lighting.js';import { RenderTargetLedger } from './render-target-ledger.js';import { SHADOW_ATLAS_WIDTH, SHADOW_TILE_SIZE, SHADOW_TILES_PER_ROW, tileViewport, writeShadowTile } from './local-shadows.js';@@ -492,7 +493,7 @@ function allFinite(values) {}export class Renderer67 {- constructor(canvas, parts, { batching = true, pixelRatio = 1.5, benchmark = false, world = false, ground = true, transparent = false, samples = 4, hdr = false, depth = false, memoryBudgetMiB, environment = {}, shadowBounds = {}, shadowCascades = null, culling = true, lodPixelError = 1, createGpuTimer = null, skyOpenness = null, fogSkyVisibility = null, shading = 'full', viewTransform = 'aces', look = null } = {}) {+ constructor(canvas, parts, { batching = true, pixelRatio = 1.5, benchmark = false, world = false, ground = true, transparent = false, samples = 4, hdr = false, depth = false, memoryBudgetMiB, environment = {}, shadowBounds = {}, shadowCascades = null, culling = true, lodPixelError = 1, createGpuTimer = null, skyOpenness = null, fogSkyVisibility = null, shading = 'full', viewTransform = 'aces', look = null, resolveCoplanar = false } = {}) {this.canvas = canvas;this.sceneParts = parts;// `skyOpenness` from closed-room.js is passed in, which keeps the ray code out of scenes without volume fog.@@ -571,6 +572,7 @@ export class Renderer67 {this.windState = { time: 0, strength: 0.3 };// The shadow map the constructor draws uses no assembly, so a first frame with none does not draw it again.this.assemblyAmount = 0;+ if (resolveCoplanar && !benchmark) resolveFlushParts(parts);const groups = groupParts(this.groundPart ? [...parts, this.groundPart] : parts, batching);const textureLimit = this.context.getParameter(this.context.MAX_TEXTURE_SIZE);this.hasSkins = groups.some(group => group[0].skin || group[0].crowd);diff --git a/tests/coplanar-overlap.test.js b/tests/coplanar-overlap.test.jsindex 4bb78695..27cbae42 100644--- a/tests/coplanar-overlap.test.js+++ b/tests/coplanar-overlap.test.js@@ -1,7 +1,7 @@import test from 'node:test';import assert from 'node:assert/strict';import { createAgentScene } from '../src/agent-scene.js';-import { findCoplanarOverlaps, coplanarOverlapDiagnostics, installCoplanarDiagnostics, resolveCoplanarParts } from '../src/coplanar-overlap.js';+import { findCoplanarOverlaps, coplanarOverlapDiagnostics, installCoplanarDiagnostics, resolveCoplanarParts, resolveFlushParts } 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';@@ -115,3 +115,42 @@ test('the check is bounded: a work budget ends the sweep and says so', () => {assert.equal(result.truncated, true);assert.deepEqual(coplanarOverlapDiagnostics({ overlaps: [], truncated: true }), []);});++// A grid of `cells` x `cells` quads on the plane y = height, spanning `size` metres, as one part.+function gridPart(name, size, cells, height) {+ const positions = [];+ const indices = [];+ for (let row = 0; row <= cells; row++) {+ for (let column = 0; column <= cells; column++) positions.push(column * size / cells, height, row * size / cells);+ }+ for (let row = 0; row < cells; row++) {+ for (let column = 0; column < cells; column++) {+ const corner = row * (cells + 1) + column;+ indices.push(corner, corner + cells + 1, corner + 1, corner + 1, corner + cells + 1, corner + cells + 2);+ }+ }+ const matrix = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);+ return { name, geometry: { positions: new Float32Array(positions), indices: new Uint32Array(indices) }, matrix, material: {} };+}++test('a flush pair of finely tessellated parts is found, with no cap on the triangles tested', () => {+ const road = gridPart('road', 20, 40, 0);+ const marking = gridPart('marking', 10, 30, 0.0004);+ const crowd = Array.from({ length: 60 }, (unused, index) => gridPart(`filler${index}`, 20, 40, 5 + index));+ const { overlaps, truncated } = findCoplanarOverlaps([...crowd, road, marking]);+ assert.equal(truncated, false);+ assert.equal(overlaps.length, 1);+ assert.equal(overlaps[0].smaller.name, 'marking');+ assert.ok(overlaps[0].area > 90);+});++test('flush parts get a layer beside the part, so the part objects and updateParts keep working', () => {+ const road = gridPart('roadTwo', 4, 4, 0);+ const marking = gridPart('markingTwo', 2, 2, 0);+ const far = gridPart('farAway', 4, 4, 30);+ assert.equal(resolveFlushParts([road, marking, far]), 1);+ assert.equal(depthLayerOf(marking), 1);+ assert.equal(depthLayerOf(road), 0);+ assert.equal(depthLayerOf(far), 0);+ assert.equal(marking.depthLayer, undefined);+});