3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Allocate the hero's bloom targets outside the first draw of a world (#779)
Nguyen Xuan An8772d8ac01c0
diff --git a/changes/779.md b/changes/779.mdnew file mode 100644index 00000000..a8aab3ba--- /dev/null+++ b/changes/779.md@@ -0,0 +1 @@+- The home hero no longer allocates its bloom targets inside the first draw of a world: `prepareFrame` creates them in a task of their own, which removes a 55 to 75 ms main-thread block at every world switch, and `measure-hero-load.mjs` names the functions and build phases behind each long task (`--profile`) (#779)diff --git a/changes/779.size.md b/changes/779.size.mdnew file mode 100644index 00000000..96e753fb--- /dev/null+++ b/changes/779.size.md@@ -0,0 +1,3 @@+- goal:lit-box: 31 bytes gzip for removing a 55 to 75 ms main-thread block at each hero world switch+- goal:gltf-box: 46 bytes gzip for removing a 55 to 75 ms main-thread block at each hero world switch+- goal:agent-scene: 47 bytes gzip for removing a 55 to 75 ms main-thread block at each hero world switchdiff --git a/scripts/measure-hero-load.mjs b/scripts/measure-hero-load.mjsindex 338a8691..8c23b118 100644--- a/scripts/measure-hero-load.mjs+++ b/scripts/measure-hero-load.mjs@@ -4,6 +4,7 @@// [--viewports desktop,phone] [--out directory]// [--cpu 4] CPU slowdown factor (emulated by the DevTools protocol, not a slow device)// [--watch-seconds N] keep each page open N seconds after the swap (the loop changes worlds) and report the main-thread tasks over 50 ms after first paint+// [--profile] sample the JavaScript stack (500 microsecond interval) and name the functions that ran inside each long task// [--origin <url>] measure a deployed site instead of serving --dist (it then needs no folder)// node scripts/measure-hero-load.mjs --dist <folder> --stills <directory> stills before and after the swap, with PSNR// node scripts/measure-hero-load.mjs --dist <folder> --video <file.mp4> CDP screencast of the first 8 s on Fast 4G@@ -40,7 +41,7 @@ const CONTENT_TYPES = { '.html': 'text/html', '.js': 'text/javascript', '.css':const TEXT_TYPES = new Set(['.html', '.js', '.css', '.json', '.svg']);function parseArguments(argv) {- const options = { dist: null, label: 'build', runs: 3, conditions: ['fast4g', 'slow', 'none'], viewports: ['desktop', 'phone'], out: null, cpu: 1, remoteOrigin: null, stills: null, video: null, timeoutSeconds: 120, watchSeconds: 0 };+ const options = { dist: null, label: 'build', runs: 3, conditions: ['fast4g', 'slow', 'none'], viewports: ['desktop', 'phone'], out: null, cpu: 1, remoteOrigin: null, stills: null, video: null, timeoutSeconds: 120, watchSeconds: 0, profile: false };for (let index = 0; index < argv.length; index++) {const flag = argv[index];const value = () => argv[++index];@@ -55,6 +56,7 @@ function parseArguments(argv) {else if (flag === '--stills') options.stills = resolve(value());else if (flag === '--video') options.video = resolve(value());else if (flag === '--timeout') options.timeoutSeconds = Number(value());+ else if (flag === '--profile') options.profile = true;else if (flag === '--watch-seconds') options.watchSeconds = Number(value());else throw new Error(`Unknown argument ${flag}.`);}@@ -110,6 +112,18 @@ function installFrameTimer(marker) {new PerformanceObserver(list => {for (const entry of list.getEntries()) window.__longTasks.push([Math.round(entry.startTime), Math.round(entry.duration)]);}).observe({ type: 'longtask', buffered: true });+ // Long animation frames name the scripts that ran inside a long frame, which says what the main thread was busy with.+ window.__longFrames = [];+ try {+ new PerformanceObserver(list => {+ for (const entry of list.getEntries()) {+ const scripts = entry.scripts.map(script => [script.invoker, script.sourceFunctionName, script.sourceURL.split('/').pop(), script.sourceCharPosition, Math.round(script.duration)]);+ window.__longFrames.push({ start: Math.round(entry.startTime), duration: Math.round(entry.duration), blocking: Math.round(entry.blockingDuration), scripts });+ }+ }).observe({ type: 'long-animation-frame', buffered: true });+ } catch {+ // Chrome older than 123 has no long animation frames; the phases below still attribute the tasks.+ }window.__frameGaps = [];let previousFrameAt = performance.now();const watchFrameGaps = now => {@@ -164,12 +178,39 @@ function bytesAt(state, milliseconds) {return bytes;}+// Functions with the most self time inside each long task, from a CDP sampling profile. The profile clock is the browser's monotonic clock;+// `pageOriginMicroseconds` is the page's performance.now() zero on that clock, which aligns the two.+function topFunctionsInTasks(profile, pageOriginMicroseconds, tasks) {+ const nodes = new Map(profile.nodes.map(node => [node.id, node]));+ let clock = profile.startTime;+ const samples = profile.samples.map((nodeId, index) => {+ clock += profile.timeDeltas[index];+ return { nodeId, at: (clock - pageOriginMicroseconds) / 1000, weight: (profile.timeDeltas[index + 1] ?? 0) / 1000 };+ });+ return tasks.map(task => {+ const selfByFunction = new Map();+ for (const sample of samples) {+ if (sample.at < task.start || sample.at > task.start + task.duration) continue;+ const { functionName, url, lineNumber } = nodes.get(sample.nodeId).callFrame;+ const key = `${functionName || '(anonymous)'} ${url.split('/').pop()}:${lineNumber + 1}`;+ selfByFunction.set(key, (selfByFunction.get(key) ?? 0) + sample.weight);+ }+ return { ...task, topFunctions: [...selfByFunction].sort((first, second) => second[1] - first[1]).slice(0, 4).map(([key, milliseconds]) => `${key} ${Math.round(milliseconds)}ms`) };+ });+}+async function measureOnce(browser, options, viewportName, conditionName) {const condition = CONDITIONS[conditionName];const { context, page, session } = await openPage(browser, VIEWPORTS[viewportName], condition, options.cpu);const bytes = watchBytes(session, page);const errors = [];page.on('pageerror', error => errors.push(error.message));+ if (options.profile) {+ await session.send('Performance.enable');+ await session.send('Profiler.enable');+ await session.send('Profiler.setSamplingInterval', { interval: 500 });+ await session.send('Profiler.start');+ }await page.goto(`${options.origin}/`, { waitUntil: 'commit' });const finished = async () => page.evaluate(() => {const events = window.__loop?.events ?? [];@@ -178,7 +219,14 @@ async function measureOnce(browser, options, viewportName, conditionName) {const swapEnd = detailed?.at ?? Infinity;const swapGaps = (window.__frameGaps ?? []).filter(([at, gap]) => at + gap > swapEnd - (detailed?.ms ?? 0) - 100 && at < swapEnd + 100);const longTasksAfterFirstPaint = (window.__longTasks ?? []).filter(([start]) => window.__firstWorldDraw !== null && start >= window.__firstWorldDraw);- return { longTaskCount: longTasksAfterFirstPaint.length, longestTaskMs: longTasksAfterFirstPaint.reduce((longest, [, duration]) => Math.max(longest, duration), 0), longTasks: longTasksAfterFirstPaint, lcp: window.__largestContentfulPaint, layoutShift: window.__layoutShift, first: window.__firstWorldDraw, detailed: detailed?.at ?? null, swapMs: detailed?.ms ?? null, swapHeldMs: (window.__phases ?? []).filter(phase => phase[0] === "swap").reduce((total, phase) => total + phase[3] - phase[2], 0), swapLongestGapMs: swapGaps.length ? Math.max(...swapGaps.map(([, gap]) => gap)) : 0, failed: failed?.message ?? null, state: window.__loop?.detail?.() ?? null, mode: window.__heroMode };+ const overlaps = (start, duration) => ([phaseStart, phaseEnd]) => phaseStart < start + duration && phaseEnd > start;+ const attributed = longTasksAfterFirstPaint.map(([start, duration]) => ({+ start,+ duration,+ phases: (window.__phases ?? []).filter(phase => overlaps(start, duration)([phase[2], phase[3]])).map(phase => phase.slice(0, 2).join(':')),+ scripts: (window.__longFrames ?? []).filter(frame => overlaps(start, duration)([frame.start, frame.start + frame.duration])).flatMap(frame => frame.scripts).sort((first, second) => second[4] - first[4]).slice(0, 3),+ }));+ return { attributedLongTasks: attributed, longTaskCount: longTasksAfterFirstPaint.length, longestTaskMs: longTasksAfterFirstPaint.reduce((longest, [, duration]) => Math.max(longest, duration), 0), longTasks: longTasksAfterFirstPaint, lcp: window.__largestContentfulPaint, layoutShift: window.__layoutShift, first: window.__firstWorldDraw, detailed: detailed?.at ?? null, swapMs: detailed?.ms ?? null, swapHeldMs: (window.__phases ?? []).filter(phase => phase[0] === "swap").reduce((total, phase) => total + phase[3] - phase[2], 0), swapLongestGapMs: swapGaps.length ? Math.max(...swapGaps.map(([, gap]) => gap)) : 0, failed: failed?.message ?? null, state: window.__loop?.detail?.() ?? null, mode: window.__heroMode };});const deadline = Date.now() + options.timeoutSeconds * 1000;let status = await finished();@@ -190,6 +238,13 @@ async function measureOnce(browser, options, viewportName, conditionName) {await new Promise(resolveWait => setTimeout(resolveWait, options.watchSeconds * 1000));status = await finished();}+ if (options.profile) {+ const pageNowMs = await page.evaluate(() => performance.now());+ const { metrics } = await session.send('Performance.getMetrics');+ const { profile } = await session.send('Profiler.stop');+ const monotonicNowMicroseconds = metrics.find(metric => metric.name === 'Timestamp').value * 1e6;+ status.attributedLongTasks = topFunctionsInTasks(profile, monotonicNowMicroseconds - pageNowMs * 1000, status.attributedLongTasks);+ }const poster = await page.evaluate(() => {const entry = performance.getEntriesByType('resource').find(resource => resource.name.includes('poster-b-port'));return entry ? Math.round(entry.responseEnd) : null;@@ -210,6 +265,7 @@ async function measureOnce(browser, options, viewportName, conditionName) {longTaskCount: status.longTaskCount,longestTaskMs: status.longestTaskMs,longTasks: status.longTasks,+ attributedLongTasks: status.attributedLongTasks,swapHeldMs: status.swapHeldMs,bytesBeforeFirstFrame: bytes.atFirstFrame,bytesAtDetail: detailMs === null ? null : bytesAt(bytes, detailMs),@@ -249,6 +305,7 @@ async function runMatrix(browser, options) {longTasksOver50AfterFirstPaint: runs.map(run => run.longTaskCount),longestTaskMs: Math.max(...runs.map(run => run.longestTaskMs)),longTasks: runs.map(run => run.longTasks),+ attributedLongTasks: runs.map(run => run.attributedLongTasks),detailRangeMs: [Math.min(...runs.map(run => run.detailMs ?? Infinity)), Math.max(...runs.map(run => run.detailMs ?? 0))],bytesBeforeFirstFrame: median(runs.map(run => run.bytesBeforeFirstFrame)),bytesAtDetail: median(runs.map(run => run.bytesAtDetail)),diff --git a/src/renderer.js b/src/renderer.jsindex 872a5825..0b38b6b1 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -974,6 +974,12 @@ export class CrucibleRenderer {async prepareFrame(frame, { timeoutMilliseconds = 6000 } = {}) {await this.programsReady();if (this.disposed) return false;+ // The bloom targets take the driver tens of milliseconds under load: a frame that blooms allocates them in a task of its own, not inside the draw.+ if (!this.benchmark && !this.bloomTargets.length && resolveEffects(frame.effects).bloom.strength > 0) {+ await new Promise(resolve => setTimeout(resolve, 0));+ if (this.disposed) return false;+ this.ensureBloomTargets();+ }const context = this.context;const deadline = performance.now() + timeoutMilliseconds;setPreparing(context, true);diff --git a/tests/prepare-frame-bloom-targets.test.js b/tests/prepare-frame-bloom-targets.test.jsnew file mode 100644index 00000000..85b85818--- /dev/null+++ b/tests/prepare-frame-bloom-targets.test.js@@ -0,0 +1,51 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { CrucibleRenderer } from '../src/renderer.js';++const BLOOM_FRAME = { effects: { bloom: { strength: 0.4 } } };++function fakeRenderer(overrides = {}) {+ const calls = [];+ return {+ calls,+ benchmark: false,+ disposed: false,+ bloomTargets: [],+ context: {},+ programsReady: async () => { calls.push('programsReady'); },+ ensureBloomTargets() { calls.push('ensureBloomTargets'); },+ render: () => { calls.push('render'); },+ ...overrides,+ };+}++const prepare = (renderer, frame) => CrucibleRenderer.prototype.prepareFrame.call(renderer, frame);++test('prepareFrame allocates the bloom targets in a task of their own, after the programs and before the draw (#779)', async () => {+ const renderer = fakeRenderer();+ const preparing = prepare(renderer, BLOOM_FRAME);+ for (let turn = 0; turn < 5; turn++) await Promise.resolve();+ assert.deepEqual(renderer.calls, ['programsReady'], 'the allocation waits for a timer task, it does not run inside the caller');+ assert.equal(await preparing, true);+ assert.deepEqual(renderer.calls, ['programsReady', 'ensureBloomTargets', 'render']);+});++test('prepareFrame allocates no bloom targets for a frame without bloom, a benchmark renderer or existing targets', async () => {+ for (const [renderer, frame] of [+ [fakeRenderer(), { effects: { bloom: { strength: 0 } } }],+ [fakeRenderer(), {}],+ [fakeRenderer({ benchmark: true }), BLOOM_FRAME],+ [fakeRenderer({ bloomTargets: [{}, {}] }), BLOOM_FRAME],+ ]) {+ assert.equal(await prepare(renderer, frame), true);+ assert.deepEqual(renderer.calls, ['programsReady', 'render']);+ }+});++test('prepareFrame on a renderer disposed while the allocation waits builds and draws nothing', async () => {+ const renderer = fakeRenderer();+ const preparing = prepare(renderer, BLOOM_FRAME);+ renderer.disposed = true;+ assert.equal(await preparing, false);+ assert.deepEqual(renderer.calls, ['programsReady']);+});