Files
hyperframes/registry/examples/path-traced-3d/source
James RussoandClaude Opus 5.5 d452a6fad4 feat(registry): add path-traced-3d example with raster preview and path-traced export (#7219)
* feat(registry): add path-traced-3d example with raster preview and path-traced export

An opt-in Three.js starter: previews with raster rendering and exports with
three-gpu-pathtracer, from one scene file. three 0.180.0, three-gpu-pathtracer
0.0.24 and three-mesh-bvh 0.9.5 ship as one local, pinned ES module with their
licences and a rebuild recipe, so renders make no network requests and 2D
projects never load the tracer.

Setup is one buildReady promise that awaits library readiness promises only
and ends with a throwaway frame and a one-pixel readback. Frames are drawn in
the hf-seek listener through waitUntil, each time from zero with a fixed
sample count. Math.random is seeded while the scene and tracer are built,
because object ids order light sampling and the tracer's noise textures come
from it.

Adds a skill reference and a docs guide for the setup and seek contract, the
frozen clock, why scheduler.yield() waits hang, and sample/bounce cost.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* fix(registry): list path-traced-3d in CLI docs and tighten its notes

Add the example's section to the CLI examples doc, which docs.test.ts
requires for every registry example. Throw if the tracer reports compiling
but exposes no compile promise, instead of spinning renderSample(). Say that
three's object uuids set the tracer's sort order, that later-created objects
need the seed too, and that Date and performance.now read the current seek
time during a render rather than staying at 0.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-11-05 06:40:37 +00:00
..

Source for the path-traced-3d example

These files stay in the repository; hyperframes init --example path-traced-3d installs only the files listed in ../registry-item.json.

Rebuild the vendored bundle

build.mjs bundles vendor-entry.js with the versions pinned in package.json and package-lock.json into ../assets/vendor/three-path-tracer.min.js, and copies the three licence files beside it.

npm ci
npm run build

Update the versions and the SHA-256 in ../assets/vendor/README.md when they change.

Check what reaches the pixels

verify-render.mjs copies the example to a temporary folder at 320x180, then uses the HyperFrames CLI and ffmpeg to check, in raster and in path mode (2 samples per pixel):

  • hyperframes check passes in path mode, so setup (including the first, slowest tracing run) resolves its buildReady promise;
  • stills taken at 4 s, 0 s, then 4 s again in one page are byte-identical at 4 s, differ from 0 s, and are not blank;
  • a new page draws the same 4 s still (no grain that changes per page load);
  • path mode draws different pixels from raster mode;
  • every frame of an exported MP4 (raster: 1 s at 30 fps; path: 0.8 s at 10 fps on two workers) is not blank, the clip moves, and no step between neighbouring frames is more than 3x the typical step.
node verify-render.mjs
# or, from a HyperFrames checkout, with the CLI built from source:
HYPERFRAMES_CLI=packages/cli/bin/hyperframes.mjs node registry/examples/path-traced-3d/source/verify-render.mjs

Every command gets a 170 s readiness wait, because on a software GPU the tracer's first shader run takes about a minute. It prints a JSON report with the wall time of every step. Set KEEP_VERIFY_OUTPUT=1 to keep the renders. path-traced-3d.test.mjs is the fast check that runs with the repository's script tests.