2026-08-08

[markaren]

This release turns threepp from a three.js-style C++ rendering library into something closer to a simulation platform. It adds two standalone applications (a scene editor and a headless-capable player), a Python package with an owned GPU-vectorized RL stack, a PhysX robotics layer (articulations, URDF/xacro, joints, direct-GPU batching), a proprioceptive sensor suite, and Gaussian-splat rendering — while the OpenGL backend gained post-processing and four PBR features it previously advertised but never shaded, and the Vulkan backend collapsed to a single deferred renderer that doubles as a synthetic-perception instrument. Two entire backends were deleted in the process: the WebGPU renderer and the Vulkan path tracer. Performance figures below come from the developer's own machine (an RTX 4070 unless stated otherwise) and are quoted as measured there, not as properties of the library.

Highlights

• A scene editor ships. threepp_editor is a full authoring application — viewport, hierarchy, inspector, undo/redo, Play mode, Python behaviour scripting — saving plain three.js "Object" JSON so an authored scene runs in a plain threepp program with no editor present. Built by default when threepp is the top-level project; see doc/editor.md (2,618 lines).
• A headless player for CI. threepp_player runs an editor-authored scene.json as independent episodes, records sensor CSVs, and exits nonzero if any script raised or the document would not play.
• threepp is a Python package. import threepp as tp gives the scene graph plus headless render-to-numpy, PhysX bindings, and threepp.rl (GpuSim + VecTask + PPO) with no rl_games, rsl_rl or Gym dependency. Wheels for Windows and Linux (CPython 3.10–3.14) publish to PyPI on every date tag — pip install threepp — carrying the GL renderer, the deferred Vulkan renderer and CPU PhysX; the editor ships separately as pip install threepp-editor (Windows).
• Robotics simulation. PhysX reduced-coordinate articulations built from a URDF or xacro in one call, maximal-coordinate joints, V-HACD convex decomposition, and a zero-copy direct-GPU batch path for vectorized RL.
• Reproducible synthetic perception. IMU, joint encoder, contact and 6-axis force/torque sensors driven from the PhysX substep, plus depth/LIDAR/event cameras — all on one seeded-PRNG, sim-clock contract, so a recorded run replays bit-for-bit across processes and both backends.
• Gaussian splatting. SplatCloud renders on GL 3.3 and through a deterministic Vulkan compute tile rasterizer, with two scan loaders (INRIA .ply, PlayCanvas SOG) and dynamic LOD.
• Two backends, not four. WebGPU and the Vulkan path tracer were both removed (~43,000 lines). OpenGL 3.3 is the portable and Emscripten/WebGL2 baseline; the deferred Vulkan renderer is the perception path.
• Presets are the front door. cmake --preset gl, --preset vulkan, --preset vulkan-aaa, --preset python, --preset wasm, and nine ci-* presets, all tracked in CMakePresets.json and used by CI itself.

Scene editor and player

• threepp_editor covers viewport with orbit/pick/TransformControls (local-world space, snapping), hierarchy with drag-reparent, an inspector for object flags/transform/material/geometry/lights/cameras, a bottom panel (console, asset browser, live sensor readout, script tabs), a first-party ImGui file browser, and drag-and-drop for scenes, HDRIs, models, scripts and textures. Behind -DTHREEPP_BUILD_EDITOR=ON, which defaults to a top-level GLFW build.
• Documents are ordinary three.js "Object" JSON 4.5. Physics, sensors, scripts, joints, vehicles, splines, trees, conveyors, sound, robots and render settings each serialize as one flat key=value;… string under a userData key through a shared codec — deterministic, so unchanged values stay byte-identical and saved files diff cleanly.
• Play mode snapshots the document, starts every registered session, and on Stop tears them down in reverse order and rebuilds from the snapshot, so no session has to be individually reversible. Adding your own runtime is three methods: start(Scene&), update(float), stop().
• Python behaviour scripting, MonoBehaviour-style: attach a .py class to an object and get start/update/fixed_update/stop, collision and trigger callbacks, coroutines with wait()/until(), six debug-draw calls, and handles onto the running PhysX world and sensors. The bindings are the same translation units the wheel is built from, so one pybind11 type registry serves both. Requires THREEPP_EDITOR_WITH_PYTHON (ON by default, self-disabling when Python or pybind11 is missing).
• threepp_player runs the same document headlessly. --episodes=N plays it back to back (each a full play/stop cycle, so episodes are independent by construction), --record=DIR writes one CSV per sensor per episode, --headless creates but does not show the window so vision sensors still scan, and --seconds counts simulated seconds read off the physics world's clock rather than summed wall-clock deltas.
• The player registers the same six sessions as the editor, in the same order — physics, conveyor, animation, audio, sensors, scripts — each gated on the same build macro. That parity is the point: a document that runs under Play runs in CI. Verified end to end on the Timber Yard scene, which saws all 8 logs under threepp_player --headless; with the conveyor session removed, logs reach the bay and none is ever cut. The per-episode line reports the conveyor count when a document has any.
• Undo/redo is bounded by entry count (200) and by bytes (3 GiB default). Commands report the subtrees they hold; the stack ignores roots the scene still co-owns and weighs only the detached remainder. Pruning drops whole prefixes and reports what went by name ("dropped Delete Sanctuaire to free 2.84 GiB").
• Save can reference models and textures instead of inlining them. Measured on a 667-node scene of three GLBs: export 15.0 s → 5.4 ms, parse 5.0 s → 1.46 s, document 268 MB → 0.12 MB. The cost was geometry written as JSON number arrays, not base64 textures. Default is still Embed; Reference is a File-menu choice.
• Two complete example scenes are compiled into the binary. Hover Arena is a physics drone flown through trigger rings with a seeded noisy IMU and a VLP-16 LIDAR; Timber Yard is a sawmill — gravity rack, conveyor, motorised blade cutting logs on breakable joints, a breakable stop bar with a load cell — run by six inline Python scripts and two coroutines. Both are regenerated by author programs kept in apps/editor/tools/, and timber_yard_author --check authors twice and compares bytes.
• --selftest drives the editor through its acceptance passes and prints PASS/FAIL per assertion (730 check sites), compiled unconditionally. --screenshot=, --shot=, --keys=, --bench=N, --play, --frames=N cover headless capture and timing.
• Stated limitations, from the manual's own list: single selection only, the viewport is the whole window, texture previews are 12×12 mosaics, Vulkan is best-effort while OpenGL is the tested path, one script per object, the script editor is a text box with a compile check, and deleting derived geometry is destructive to that node's material and physics.

Vulkan renderer

• One renderer. VulkanPathTracer (RT megakernel, ReSTIR DI/GI, photon caustics, à-trous denoiser) was retired; the deferred G-buffer renderer is the sole Vulkan path, split from one monolith into nine translation units behind a single pImpl. Behind -DTHREEPP_WITH_VULKAN=ON or the vulkan preset.
• Multi-view. addView/removeView/setViewCamera attach persistent extra views; every render() produces the primary and each added view from one scene build in one queue submission. Measured at 640×400 primary: 0 secondary views 5.699 ms/frame, 3 secondary views 18.157 ms — 2.25× the pixels for 2.19× the frame time. Secondary views are deliberately plainer: native resolution, built-in temporal resolve only, no DLSS/FSR, occlusion culling, DoF, lens model or splats.
• Lossless AOVs with stable segmentation. readGBufferAOV copies a G-buffer attachment in its native format — Depth (float32 reversed-Z), Normal (fp16×4, roughness in w), Motion (fp16×4), Ids (uint16×4), Albedo (unorm8×4), SplatDepth (float32 view distance). The Ids .y channel is a per-object instance id stable across add/remove/hide/LOD; .z is an 8-bit semantic class. readViewGBufferAOV gives the same for each camera, so N viewpoints yield depth, instance and semantic ground truth for one simulated instant.
• Physical camera, lens and sensor. setPhysicalCamera derives exposure from aperture/shutter/ISO via EV100; setPhysicalLightUnits makes DirectionalLight lux, Point/Spot lumens, RectArea nits. cameraIntrinsics() reports fx/fy/cx/cy in OpenCV convention, setLensDistortion implements Brown-Conrady and Kannala-Brandt fisheye applied to both the display and the AOV readback (integer and depth AOVs resample NEAREST), and sensor noise is modelled in the electron domain (full-well, read noise, dark current, PRNU), deterministic under a seed. Caveat: the default sunny-16 triplet is an exposure multiplier of 2.6e-5, correct only when the scene is lit in photometric units — a scene lit at intensity 1–5 goes black. Use setPhysicalLightUnits and real light values together. Barrel distortion also needs setLensOverscan (1.15–1.3) or frame corners clamp and smear. All of it is off by default and byte-identical when off.
• One fog knob. Setting scene.fog now drives a froxel volume (128×72×64, exponential [0.25, 512] slices) that replaced two per-pixel marches: directional lights get one RT shadow ray per froxel, and clustered point/spot lights scatter in fog for the first time. Sun shafts and aerial perspective follow automatically. setVolumetricFog is a no-op kept for compilation. Clustered light culling removed the 8-per-type caps. setClouds adds an analytic Perlin-Worley cloud deck with ground shadows in a half-res compute pass (a dense overhead view went from ~6–7 ms in-shade to ~2.2 ms); off by default and image-identical when off.
• Temporal stability. The systemic tremble on jittered paths had one root cause: jitter applied in GL y-up clip space with no consumer compensating correctly. taa_resolve re-anchors current-frame reads at the unjittered pixel center, and DLSS/FSR jitter is converted per axis. Measured on a static camera by 16-frame phase correlation: ±0.9 px / frame-diff 3.2/255 down to TAA 0.037 px / 0.72, DLSS 0.012 / 0.28, FSR 0.008 / 0.23. setGbufferMsaa(1|2|4) rasterizes the G-buffer at N samples and resolves by dominant sample; the load-bearing part is that the raster runs unjittered above 1 sample. Default 1 is byte-identical to the old path. Material textures now use 16× anisotropic filtering in every mode; setTextureAnisotropy(1) forces isotropic.
• A separate family of fixes addresses artifacts on moving content — stale reflections, occlusion residue around movers, ghost outlines from moving shadow casters — via a sticky per-entry moved flag with a 30-frame countdown, a GI-reproject trailing-edge guard, and shadow-visibility flagging of hits on moving meshes. A 65-element descriptor array indexed to 66 in the deferred shade pass (a stack smash) was fixed alongside.
• VRAM. A first-party BC7 encoder transcodes material textures at upload: Bistro live VRAM 7,976.9 → 2,760.9 MB (−65%) at +25 s load time, goldens passing unregenerated. DDS BC blocks now pass through with no decode/re-encode. Static-BLAS vertex attributes narrow end-to-end (normals oct-snorm16x2, UV unorm16x2, colour unorm8x4) for another −114.7 MiB on Bistro, and index buffers become uint16 under 65,536 vertices. THREEPP_NO_BC=1 and THREEPP_NO_PACK=1 are same-binary escape hatches.
• Probe GI on by default. A 32×16×32 SH-L1 world-space irradiance grid refreshed round-robin (~0.3 ms) supplies bounce-2+ and through-the-opening sky light, and switches the ambient model from cosmetic to sky-visibility-gated — enclosed interiors go dark. Chebyshev visibility (8×8 octahedral depth moments per probe) stops wall leaking: a sealed 5 cm-wall room with a sun-lit exterior went from 2.59 to 0.0016 mean luminance. setDenoise is documented as an A/B pipeline selector that changes material appearance, not a quality dial.
• Occlusion culling (off by default): draw last frame's visible set, build a farthest-depth HiZ pyramid, test every world AABB on the GPU, draw the newly visible in phase 2 of the same frame. At maximum occlusion (1,200 hidden high-poly knots, ~20M verts) the raster G-buffer went 1.20 → 0.12 ms. Honest limit stated with it: on Bistro (2,809 draw records) FPS was flat, because that scene is not geometry-bound.
• Automatic mesh LOD, on by default. Per-geometry chains of simplified index buffers (vertex data untouched) generated in the background with meshoptimizer, selected by projected screen-space error at a 0.75-pixel budget. Fjord flythrough +32% FPS; per-pixel-bound Bistro neutral. The header states plainly that it does not meaningfully reduce TAA edge shimmer. Skinned, displaced, grass, morphed and tet meshes stay at level 0.
• Post stack. Jimenez progressive bloom pyramid (the halo radius no longer shrinks as resolution grows — a rim halo at 25% peak went 54 → 110 px), half-res scatter-as-gather depth of field with a camera-derived circle of confusion, McGuire tile-max motion blur, and log2-luma auto-exposure with an asymmetric EMA. All off or zero by default.
• Frame pacing. A frame-serial deferred-deletion queue plus per-frame-in-flight descriptor rewrites replaced device-wide stalls on runtime resource swaps: on a 300-frame churn harness p99 5.09 → 3.37 ms. Structural rebuild spikes on terrain-tile swaps were traced to a per-entry dynamic_cast storm (~89 ms) and per-tile queue drains (~37 ms); memoizing by Material* and batching one-shot command buffers took a 1,200-frame fjord flight from p95 ~94 → 35 ms and max ~150 → 62 ms. A tet-skinning upload race, TLAS scratch use-after-free and texture-cache address recycling were fixed alongside.
• DLSS and FSR 3.1 are compile-time swaps of the built-in TAA upsampler with a runtime fallback chain (DLSS outranks FSR, which falls back to TAA), frame-to-frame switchable with a history reset on the flip. Behind -DTHREEPP_WITH_DLSS=ON / -DTHREEPP_WITH_FSR=ON (Windows + Vulkan only) or the vulkan-aaa preset. Known open issue: emitter/fog silhouette artifacts appear on both and not on TAA, suspected to be an exposure-domain split.
• FFT ocean. The mid cascade's axis-aligned plaid was broken by rotating its sample domain and making the default tile trio non-commensurate (1000/127/9.3 m); cascade FFT sizes are now derived from band content ({128,256,512} instead of {1024,512,512}), removing roughly 85% of per-frame FFT texel work at unchanged amplitude since the IFFT is un-normalised. Wind is live (Phillips re-dispatch on a parameter diff, phase-correlated so the sea morphs rather than pops), and the host height readback is lazy behind a sticky sampleHeight() opt-in.
• Debuggability. THREEPP_VULKAN_VALIDATION now overrides the Debug/Release default in both directions — RelWithDebInfo previously could never report a VUID. FrameTimings covers twelve GPU stages and three CPU ones, including a three-way splat split. THREEPP_VK_MEMDUMP, THREEPP_VK_SPLAT_CHECKSUM, THREEPP_DENOISE=0, THREEPP_NO_BC, THREEPP_NO_PACK and THREEPP_VK_ANISO are same-binary A/B switches. One unresolved item: the Vulkan editor selftest exits -1 under conditions that were never pinned down.

OpenGL backend and core

• Post-processing. A new threepp/postprocessing/ module ports r129's addon framework: Pass, the composer's ping-pong pair, RenderPass, ShaderPass, ClearPass, MaskPass/ClearMaskPass, TexturePass, SavePass, UnrealBloomPass and BokehPass. Two deliberate departures from three.js: the composer always owns the final draw to screen so the sRGB encode happens once, and ShaderPass suppresses its implicit clear while a stencil mask is active. Outline and SSAO passes are explicitly deferred. Built unconditionally.
• Multisampled render targets. RenderTarget::Options::samples allocates a multisampled framebuffer and resolves on unbind, clamped to GL_MAX_SAMPLES, with glReadPixels redirected to the resolve framebuffer. Two defects fixed on the way: setSize released resources through the latching dispose(), so a second resize was a no-op; and the depth renderbuffer format is now sized GL_DEPTH24_STENCIL8 in one place for both sides of a target, since a depth resolve blit requires matching formats.
• Four features that were public API with no shader now shade on GL. Sheen is an additive Charlie lobe with its own roughness and IBLSheenBRDF (it previously sat in an #else against GGX and replaced base specular, gated on an optional loaders never wrote). specularIntensity/specularColor reach the shader via a pbrSpecular flag. Iridescence gets a Belcour & Barla chunk. ToneMapping::AgX was a selectable enum that fell through default: and emitted Linear. glTF assets carrying KHR_materials_sheen or KHR_materials_specular render differently on GL now — that is the fix, not a regression.
• F_Schlick switched from Epic's exp2 fit to exact pow5 everywhere, because Schlick_to_F0 (needed by iridescence) is the algebraic inverse of the pow5 form only. Only two call sites read it and the error peaks around 0.003 absolute at mid angles.
• VSM shadows produce a shadow instead of interference fringes. Moments are now full-float rather than RGBA8-packed (the packed form requires a shadow camera fitted to the scene, which nothing fits), and the map is mipmapped storing E[z] and E[z²] rather than mean and deviation, since standard deviations do not average. Measured per-pixel alternation on the editor's scene: 12.5M before, 77k after, against PCF's 82k. Opt-in via shadowMap().type = ShadowMap::VSM.
• Toggling shadowMap().enabled now rebuilds material programs — previously disabling shadows froze the last-rendered ones on screen and enabling from a disabled start did nothing, and switching to VSM after the first frame null-dereferenced. Alpha-tested casters now get their own MeshDepthMaterial, so a leaf card shadows its silhouette instead of a rectangle.
• Shaders drawing into a render target now encode into the target's colour space, not the renderer's. Measured: a plain render target reads back 128 for linear 0.5 (was 188), and a target tagged sRGB gives 188 where it gave 127 — the request was inverted, not ignored. Water reflections stop being washed out.
• Narrow vertex attributes end-to-end. BufferAttribute gains an AttributeType enum with Uint8/Int8/Uint16/Int16 aliases and a denormalize() matching GL/Vulkan UNORM/SNORM rules; FloatAttributeView reads any attribute as float (zero-copy when already float). compressAttributes()/compressSceneAttributes() narrow normals and tangents to snorm16, UVs to unorm16 when inside [0,1], colours to unorm8, skipping anything lossy and skipping skinned/displaced/morph/tet geometry. GL uploads all of them natively, removing three throw std::runtime_error("TODO") paths.
• Matrix4::multiplyMatrices is SSE2 on x86: 16.0 ns → ~4 ns per multiply under MSVC /O2, bit-exact against the scalar path (160k products compared byte-wise, zero differences). THREEPP_NO_SIMD forces scalar; NEON is deliberately not done because FMA would make it 1-ulp rather than bit-exact.
• Object3D stores matrix/matrixWorld by value with the public shared_ptr handles as non-owning aliases — same source API, 2 heap allocations and 2 control blocks per node gone. At 100k nodes: build −8%, dirty-subtree traversal −8..10%, teardown −10%; the honest trade is a matrixWorld-only linear sweep ~30% slower and sizeof(Object3D) 984 → 1112. Object3D also now derives std::enable_shared_from_this<Object3D>, which fixed a deterministic segfault where pybind11 wrapped C++-created children in non-owning instances — and which means shared_from_this() must never be called on a stack-allocated Object3D.
• Lifetime fixes: the destructor unlinks from its parent and clears the parent pointer of children it does not own; remove()/removeFromParent() route through one detachChild() that moves the owning reference to a local first; add()/addRef() reject null, self and ancestor insertion (a self-cycle used to recurse forever); the move constructor no longer leaves null matrix pointers in the parent's child list.
• EventDispatcher::subscribe(type, fn) returns a Subscription whose destruction removes the listener, with the registry owning the callable. Listeners removed during dispatch are no longer called (three.js still calls them; here that would be a use-after-free).
• Thread safety: Object3D::id, Material::id and BufferGeometry::id are atomic — loaders detach worker threads, and a torn read-modify-write handed two materials the same id, which made GLRenderer skip the second one's uniform upload. Raycast and triangle scratch moved from 17 file-scope statics to thread_local; BufferAttribute's two shared scratch vectors became function locals.
• Orthographic cameras see the environment map: the unit background box is scaled to 4× the frustum half-extent and an orthoDirection uniform makes every pixel sample the camera's forward. Measured before the fix on a 64×64 target, 4,080 of 4,096 pixels were clear colour with an env map set. three.js has the same gap.
• threepp/extras/DataUtils.hpp ports toHalfFloat, and ImageData gained a uint16_t alternative plus Image::isHalfFloat(), so half-float textures can take CPU pixels. The port saturates on overflow rather than reproducing r129's expression, which turns 70000.0f into negative infinity. Known gap: the Vulkan material-texture path does not accept half-float DataTextures and now says so.
• Animation fixes: Interpolant::settings was never initialised and getSettings_() dereferenced it; CubicInterpolant ported three.js's out-of-range-index idiom literally, which in C++ is an out-of-bounds read at both ends; KeyframeTrack::setInterpolation never assigned; AnimationMixer::clipAction wrote to a local copy and so allocated a fresh action every call. Multi-primitive glTF meshes now fan mesh-level morph weights to all primitives.
• Smaller correctness fixes: GLUniforms vec2/3/4 caching used && where it needed ||, leaving stale uniforms; a mipmap min filter on a texture that can never have mips made it GL-incomplete and every sample black (RoadNetwork, FacadeTexture, DetailTexture); BufferGeometry::applyMatrix4 had its bounds test inverted; Mesh::raycast read vertex B's UV from index c; renderOrder is now int, so a negative order no longer wraps and sorts last; TransformControlsGizmo set renderOrder to numeric_limits<int>::infinity(), which for an integral type is 0.
• Canvas/GLFW process-global state. GLFW window hints are sticky, so a GL canvas created after a Vulkan canvas in the same process got a window with no OpenGL context and the glad loader's bare exit(EXIT_FAILURE) killed the process — inside the Python module, a dead interpreter with no traceback. Hints are now reset explicitly, and the canvas/glad path throws instead of calling exit(). The same leak affected GLFW_SAMPLES. An app that grabbed the pointer also left the OS cursor hidden after a clean exit; CURSOR_NORMAL is restored before window destruction.

Gaussian splatting

• threepp::SplatCloud is a Mesh over a new public InstancedBufferGeometry, with per-splat data in three DataTextures (mean+opacity, covariance, SH). It draws on the GL backend with no renderer edits — though making it a plain Mesh required filling in three if (false) placeholders in the GL renderer, so InstancedBufferGeometry/InstancedBufferAttribute and glVertexAttribDivisor are now generally available.
• Two loaders, both clean-room. SplatLoader reads INRIA 3DGS .ply driven by the header's property table, handling channel-major f_rest_*, pre-sigmoid opacity, pre-exp scale and w-first unnormalised quaternions, and preserving unconsumed properties as named per-splat float arrays. SogLoader reads PlayCanvas SOG v2 / SuperSplat from a directory, a meta.json, or a .zip/.sog recognised by PK magic — with its own central-directory reader accepting stored entries only.
• SOG is a large distribution win: the reference 5.0M-splat scan is 89.9 MB as SOG against 1,124.9 MB as the .ply it decodes to bit-for-bit (~92% smaller), loading in 1.64 s versus 1.43 s warm / 2.97 s cold. Both decode to ~1.2 GB resident, so this is disk and cold-open, not decode speed.
• The Vulkan SplatPass is a 12-stage compute pipeline (project → prefix-sum scan → deterministic expand → 8 radix passes → tile ranges → 16×16 tile composite) that read-modify-writes the HDR scene buffer between deferred shade and DoF, so splats get DoF, bloom, tone mapping and TAA through the same code as everything else. Determinism is by construction (prefix-sum expansion, stable LSD radix, no subgroup ops) and gated by a test asserting bit-identical keys, payloads and pixels across processes.
• Measured at 960×600: 216k ATLAS scan 1.93–2.01 ms GL vs 3.47–3.61 ms Vulkan (the tile rasterizer loses on small clouds), 5.0M Sanctuaire 53.1–55.4 ms GL vs 25.1–28.9 ms Vulkan. Quality against GL as oracle: 39.8 dB on the ATLAS scan, 47.2 dB on a sky-heavy framing.
• Dynamic LOD via submission ranges picks the coarsest level covering the projected footprint at ~1 splat/pixel with 25% hysteresis, then frustum-culls chunks. The 5.0M scan framed: 23.97 ms at static level 0 (41 fps) vs 7.29 ms dynamic (136 fps); zoomed 8× it selects level 0 and matches it. Vulkan only — GL ignores submit ranges and draws every splat.
• Host memory per splat fell from 606 to 423 bytes at SH degree 3. SplatQuat replaced std::vector<Quaternion> (Quaternion carries float_view components and a std::function, costing 80–112 bytes per splat of unused change-notification depending on standard library — 128 B total on MSVC, 96 B on libstdc++), and SplatCloud stopped deriving from InstancedMesh, shedding a 64 B host + 64 B VRAM identity instanceMatrix. The GL render is byte-identical across both changes.
• Splats integrate with the frame: per-pixel motion vectors derived from alpha-weighted expected depth (36.92 → 39.34 dB against GL over a 150-frame orbit), re-derived height fog and underwater murk with a closed-form sun single-scattering term checked against the surface path's 16-step march (worst difference 0.94%), and compositing in the display-referred domain the coefficients were fitted in rather than linear light (+9.6 dB on ATLAS, +8.9 dB on Sanctuaire).
• setSplatDepthAov(true) adds an expected-depth AOV in world units, written where coverage exceeds 0.5. It is an expected value, not a surface — it sits behind the visible front of a cloud by roughly its own thickness, localizing a wall well and a canopy poorly. Off by default because a full-res r32f per frame in flight is ~25 MB at 1080p, and toggling reallocates render targets.
• Sort sizing moved to indirect dispatch: on the 5.0M scan, camera pointed at empty space went 9.81 → 1.77 ms (the sort alone 8.50 → 0.16), because the old path spent 7.9 ms sorting zero entries. Byte-identical output.
• SplatData::removeOutliers() and reorderMorton() are opt-in, deterministic and scale-free (every threshold a ratio against the cloud's own percentiles). Neither loader calls them. Morton is off by default because it measured worse on the GL draw-order path (82–87 ms vs 50.9 ms in file order on the 5M scan) and made no difference on Vulkan.
• The editor imports scans by drag and drop, dispatching on content rather than extension, with removeOutliers() and a half-turn about X applied by default (COLMAP-derived captures are +Y down, including SOG). SplatCloud is not serialized: ObjectExporter refuses the type by name with a warning, and the editor warns before Save, Play and Stop that the cloud will not survive.
• Known open limits, all measured: zoomed 16× out of the 5.0M scan costs 66.1 ms because the whole scan lands in a few dozen tiles that each blend serially in one workgroup, and LOD cannot reach it; and SplatPass::record() runs per cloud, so a second cloud costs ~1.3 ms flat (1/2/4/8 clouds at constant total splats: 7.1 / 9.6 / 13.2 / 16.4 ms). Splats cast no shadows, appear in no reflection, contribute to no probe GI, are invisible to the RT sensors, and secondary views skip the pass entirely. Python bindings landed late in the range: SplatLoader / SplatData / SplatCloud on both backends, with submit_ranges exposing the LOD mechanism.
• libwebp 1.6.0's decoder subset is vendored (SOG stores its planes as WebP), and ImageLoader sniffs the format, so every existing image caller inherits it. Decoder only — nothing in the tree can write a WebP.

PhysX and robotics

• Articulations. Articulation/ArticulationLink build PhysX reduced-coordinate robots: add the root, then children with inbound revolute or prismatic joints, then finalize(). Handles limits, PD drives, joint friction (defaulted to frictionless — PhysX's default silently faked balancing tasks by holding a pole against its own gravity torque), episode reset(), and batched joint I/O that collapses roughly 36 pybind calls per robot per step to 3. dofOrder() maps CPU add-order onto the GPU/cache DOF order so a GPU-trained policy reconciles with CPU deploy.
• loadArticulation() imports a URDF or xacro straight into a simulated robot, through the same parser URDFLoader uses. Box/sphere/cylinder collisions map directly and <mesh> collisions cook to one convex hull (they used to become a bounding box — a chair leg collided as a solid slab). renderVisuals=false skips loading visual meshes, which dominates a large batch build. URDFArticulationOptions::scale folds a uniform length scale into the description before a single actor exists, deliberately not scaling mass (URDF states kilograms whatever unit the geometry was drawn in) or revolute limits.
• Joint is one PxD6-backed maximal-coordinate type covering fixed, revolute, prismatic and spherical (plus distance), with limits, a force-mode PD drive, a break force/torque, and joint-space readout that JointEncoder and ForceTorqueSensor read. breakWrench() exists because after a break, PxConstraint::getForce freezes on the breaking step's value rather than returning zero — reactionForce() now returns zero once broken and the failure load is latched separately.
• Contact, trigger and constraint-break events. watchContacts, watchTriggers and watchConstraintBreaks are handle-based; contacts are off until watched, so a world with no watchers pays nothing. The trigger-shape flip is guarded by canBeTrigger() before the flag is set, because PhysX refuses triangle-mesh and heightfield triggers via an error-stream message rather than a return value, and the two flags are mutually exclusive — a naive raise leaves a shape that neither collides nor triggers.
• PhysxGpuBatch wraps PhysX's direct-GPU API: one call reads all articulations' joint positions/velocities, root pose or per-link poses into a CUDA device buffer, or writes all drive targets from one — hand a torch CUDA tensor's data_ptr() straight in, with writeSubset() for partial episode resets. Settings::cudaContext lets PhysX adopt the host framework's context, which is required for correctness (a separate PhysX context leaves cuBLAS/cuDNN unable to launch). Under direct-GPU mode the per-actor CPU getters throw with a message pointing at PhysxGpuBatch rather than returning stale state. Behind enableDirectGpu, off by default.
• V-HACD convex decomposition ships in-tree: decomposeConvex() returns one vertex array per hull behind an interface free of both PhysX and VHACD headers, and PhysxWorld::addCompound() builds one rigid actor carrying several convex shapes with mass and inertia computed once from the union. Deliberately synchronous — V-HACD's async mode returns before the hulls exist, which is wrong behind a Play button. Behind the vcpkg physx feature, which now also pulls v-hacd.
• Parented meshes now place and size rigid bodies correctly. Every creation path used updateMatrixWorld() and read the cached parent world matrix — stale for a body added before the first render, so the actor spawned at local coordinates. add()/addStatic() also decomposed the world scale and then dropped it, so a scaled mesh collided at unscaled size.
• Soft-body skinning binds every visual vertex to the tet it really sits in. Two defects: the tet-AABB pre-filter was treated as a correctness bound, so an unmatched vertex kept the centroid of tet 0 and teleported into the body (a rotated box's corners land ~0.06 m outside the cooked hull, past the 0.02 m pad); and the direct-mapping fast path trusted a vertex-count match, so a rotated sphere was skinned through an arbitrary permutation and rendered its south pole at the north. Worst rest-pose error on a 1 m body: rotated box 1.296 → ~1e-6 m, rotated sphere 1.008 → <1e-3 m.
• Five confirmed use-after-frees fixed: removeActor scrubbed object bindings but not instanced ones; onPreSubstep/onPostSubstep had no unregister and both vehicle types register a callback capturing this; ~PhysxWorld left registered sensors holding a dangling world pointer; and a PhysxWorld whose constructor threw leaked its PxFoundation, so every later world in the process failed with "Foundation object exists already" and poisoned the rest of the test binary.
• PhysxVehicleBase<SettingsT> factors the shared PxVehicle2 stack out of both drive types (2,050 → 1,445 lines across three headers), with telemetry bit-identical over 900 fixed-dt frames. Separately, every heap-allocated vehicle NaN'd within one frame on Linux/GCC: PxVec3/PxQuat/PxTransform have user-provided default constructors that deliberately leave data uninitialised, so {} member initialisers on the state arrays were a lie. Proven by filling the heap with 0xFF and finding matching poison runs; MSVC's young heap handed out benign pages, which is why Windows looked fine.
• smoothTimestep exists as an opt-in and is defaulted off after measurement: low-passing dt advances the accumulator on a fictional timeline while the frame is displayed at real wall-clock time, so on a chase-cammed vehicle under vsync the per-frame velocity jerk went up roughly an order of magnitude. enableTgsPcm turns on the GPU contact model (TGS + PCM + stabilization) for a CPU world, so a GPU-trained policy deploys onto CPU against the same physics.

Sensors and kinematics

• Proprioceptive suite. Imu reports body-frame angular velocity and true specific force including lever-arm terms (a level sensor at rest reads +g, free fall reads ~0). JointEncoder adds tick quantization and differentiates velocity from the quantized reading, so standstill chatter is reproduced. ContactSensor keeps a refcounted per-shape-pair latch that survives PhysX putting a resting pair to sleep. ForceTorqueSensor reads the solver's incoming joint force from an articulation cache, or PxConstraint::getForce on a plain joint. Header-only under threepp/extras/sensors/, sampled from inside the fixed substep; the four body/joint sensors need the PhysX SDK on the include path.
• One reproducibility contract. Depth/LIDAR range noise came from a function-local static std::mt19937 seeded by random_device at four sites — OS-seeded, shared across every sensor instance in the process, and using a distribution that is not portable across standard libraries. Every sensor now owns a SplitMix64 stream seeded from a declarative model, and every measurement is stamped with sim time. All-zero noise passes the clean value through bit-for-bit and draws no random numbers.
• Near/far now bounds range identically on GL and Vulkan. The raster path clipped on the camera's near/far planes (perpendicular view-space Z) while the traced path bounded the ray's Euclidean range — differing by the pixel's slant ratio, up to √3 at a 90° cube face corner. In the shipped Hover Arena the drone's rotor rings reach 1.46 m from a near=1.2 m LIDAR: Vulkan ranged 1,460 points of its own airframe, GL reported none. Both now use the sphere; self-returns went 1,460 → 0 on Vulkan and 905 → 0 on GL, with the backends' totals within 1.4%.
• Pipelined scanning. A Vulkan scan ended in vkDeviceWaitIdle, which does not cost the trace but costs every frame queued behind the fence: a 10 Hz VLP-16 cost 30.1 ms per scan of which the trace was 1.2 ms and the wait 28.5 ms. scanBegin/scanReady/scanCollect over a ring of four slots replaced it — p95 33.75 → 16.28 ms, max 36.3 → 17.1 ms, and interleaved against a sensor-stripped control the LIDAR now costs 15.29 vs 15.01 ms median. The synchronous scan() keeps its blocking contract; a raster backend delivers on the frame it fired, so code written against the pair works on both.
• LidarSensor used to crash on Vulkan: it called setRenderTarget (a warn-and-ignore no-op there), rendered nowhere, then read back six never-filled cube faces. It now builds a traced backend from the same model. The two sensors' duplicated protocol was hoisted into TracedRasterVisionSensor<PointT>. Honest gap: on a raster backend a LidarReturn carries only position and distance — intensity 0, normal 0, instance id −1.
• Inverse kinematics is in the library. threepp/extras/kinematics/InverseKinematics.hpp is a header-only, dependency-free damped-least-squares solver (finite-differenced Jacobian, Cholesky on the 6×6 normal system) with Position, AxisAlign and Pose tasks, tool offset, joint limits, a null-space rest posture and a speed cap, solving over chainDofs() only. Writing tests for it exposed three latent defects carried over from the demo code: anti-parallel tool axes were a converged fixed point with zero reported error; the null-space projector leaked posture bias so the arm never converged with a rest posture enabled; and the first step was not trust-region clamped. Not exposed to Python.
• Robot is a tree. Analytic FK multiplied the flat joint vector in document order, so a gripper's branch was multiplied into the tool pose (IK could "reach" a target by squeezing); getEndEffectorTransform() returned the last declared joint, which for the shipped KUKA iiwa is a base-plate joint — the robot's own pedestal; and finalize() assumed the first link is the root, which xacro-expanded URDFs violate. Robot now names a tip, walks the real root-to-tip path, and exposes chainDofs(). Prismatic joints also slid along the wrong axis, with the scene-graph and analytic paths disagreeing.
• Native xacro. A ~3,600-line engine replaces the previous 496-line single-header processor: expressions are a Python subset over None/bool/int/float/str/list/dict with **////%, comparisons, in, ternaries, subscripting, math.* and xacro.load_yaml; a bundled YAML reader handles block and flow collections, typed scalars and !degrees/!radians; $(find pkg) resolves through an explicit registry, then a package.xml walk, then ROS_PACKAGE_PATH/AMENT_PREFIX_PATH. Nothing is silently skipped — the first unevaluable thing ends the run with the offending file and text. Verified against the Universal Robots and Franka ROS 2 descriptions (those clones are not vendored, so those tests skip without an env var). Documented as unsupported: YAML anchors and block scalars, namespaced includes, <xacro:element>/<xacro:attribute>, and the $(eval) parts needing a real interpreter.
• Sensors are authorable data: editor::SensorConfig writes a rig into userData["sensor"] as one flat string, covering IMU, depth, LIDAR (Dense plus VLP16 / HDL32E / OS1-64 / OS0-128), encoder, contact and force/torque. Sensors are play-time constructs built from userData at Play and dropped at Stop, which is the determinism story. SensorPlaySession is PhysX-free and splits by class rather than #ifdef, so a build without the SDK still authors, plays, overlays and records the vision sensors.
• URDF loader fixes: a <collision><cylinder> is Z-aligned per spec (the visual path already honoured this; the collision path produced a collider rotated 90° across its own axis), getMaterial no longer indexes an empty rgba split, meshes referenced by both visual and collision load once and clone, and diagnostics()/lastError() expose why a load went the way it did.
• Point clouds and SLAM. VoxelGrid::nearest walked a fixed 3×3×3 neighbourhood, inexact for any maxDist larger than one cell; it now visits exactly the voxels the query ball's AABB spans, pruning each by squared corner distance. marchingCubes classifies before computing corner positions and gradients, so only crossed cubes pay; icpPointToPoint exploits the Jacobian's sparsity and gained translation/rotation tolerances. On the lidar SLAM example, ICP went 13.7 → 4.7 ms per frame and loop drift 0.121 → 0.024 m, because registering against the dense display map had been pulling the pose toward the map's own accumulated error.

Python

• The whole python/ tree, pyproject.toml and the wheels workflow are new: 30 binding translation units covering math, scene graph, geometries, materials, cameras, lights, textures, loaders, animation, curves, text, helpers, audio, controls, splats, terrain, vegetation and the Vulkan renderer. Behind -DTHREEPP_WITH_PYTHON=ON, the python preset, or pip install ..
• tp.Canvas(..., headless=True) opens a hidden GLFW window with a real GL context and read_pixels() returns an (H, W, 3) uint8 NumPy array; save_frame(path) writes a PNG. No display, Vulkan SDK, PhysX or CUDA needed.
• Typed AOVs read to NumPy on a Vulkan build: read_depth (float32 metric), read_instance_ids and read_class_ids (uint32, no hashing, 0 = sky), read_normals_float, read_motion, and read_aovs_typed which renders once and reads every requested AOV from that frame.
• Roughly 55 Vulkan renderer properties are scriptable — physical camera, lens and sensor model, white balance and colour grade, FSR, render scale, denoise, probe GI, G-buffer MSAA, occlusion culling, DoF, auto-LOD, auto-exposure, fog and clouds, the one-sun policy, and a read-only frame_timings dict.
• threepp.rl is three layers of a few hundred readable lines each: GpuSim hides CUDA-context adoption, the direct-GPU batch and the DOF-order remap (state tensors refresh in place, so a stashed reference stays live); VecTask owns the step/reset choreography including capturing terminal_obs before a partial reset and named reward terms logged per episode; PPO does running observation and return normalization, GAE, LR anneal and target-KL early stopping. pip install threepp[rl] pulls torch. Note sim.py reads the CUDA context through nvcuda.dll and is Windows-only as written.
• Policy bundles let a trained policy run inside the editor with NumPy alone: export_bundle.py writes weights plus a spec.json declaring the observation terms, action decoding, control rate and plant gains; policy_runner.py evaluates it (ELU only, raising on anything else). Checked against the torch checkpoint at max |action diff| 4.768e-07. Deployed as an editor behaviour script, the Spot terrain policy walked 8.03 m in 10.04 s at a commanded 0.8 m/s.
• The same binding sources compile into threepp_editor_scripting, deliberately, so one pybind11 type registry serves both. Three translation units are editor-only — their RigidBody/SoftBody/Articulation/Joint/Vehicle handles point at a live play session — so the wheel's threepp.editor contains only SplinePath and authoring-data readers.
• PEP 561 stubs ship as a package (__init__.pyi, imgui.pyi, editor.pyi). The generator wraps a pinned pybind11-stubgen and fails when the emitted stub does not parse or when regeneration dropped symbols the committed stubs declare — the bare CLI exits 0 either way, which is how the previous flat stub silently rotted to 84 VulkanRenderer lines against today's 365. editor.pyi is hand-written and restored after each run.
• Wheels ship on PyPI. wheels.yml builds cp310–cp314 wheels for Linux and Windows plus an sdist, rehearses the upload against TestPyPI on workflow_dispatch as a unique .devN version, and publishes both threepp and threepp-editor to PyPI on a date tag via OIDC trusted publishing — no tokens anywhere. macOS has no prebuilt wheel; pip install compiles from source there (GL-only).
• The distributed wheel ships GL + Vulkan + CPU PhysX in under 6 MB: the Vulkan loader is delay-loaded on Windows and vendored on Linux, so the wheel imports cleanly on machines with no Vulkan runtime and tp.vulkan_available() reports which world you are in; PhysX is CPU-only (the 238 MB GPU runtime stays out — dropping the two GPU DLLs beside the module enables gpu_dynamics=True). No audio or FBX. Scripts should branch on tp.HAS_VULKAN / HAS_PHYSX / HAS_IMGUI / HAS_AUDIO. Dear ImGui is compiled in.
• Known gaps: LIDAR is bound as value types only (DepthSensor.scan is bound; the LIDAR scan is renderer-side and unbound), Vulkan secondary views have no bindings, and there is no HAS_FBX flag.

Loaders and serialization

• Scene serialization both ways. ObjectLoader/ObjectExporter read and write three.js "Object" JSON 4.5 — the object tree with matrices, layers, visibility, shadow flags, render order and userData; scene fog, background and environment; every object and light type; geometries in parametric and universal form; textures as base64 data-URIs; skeletons; animation clips. Output is deterministic and every serialized uuid is adopted verbatim on load, so identity round-trips. Documents authored by the three.js editor load as-is. Not exposed to Python.
• Documents can reference models and textures instead of inlining them (see the editor section for measurements). Model references replay a table of per-node edits validated by node name, so a changed asset drops what it cannot match rather than misapplying it, and a missing asset leaves a correctly-placed placeholder. Material edits inside a linked subtree are not saved.
• EXR reading, first-party. Single-part scanline OpenEXR with NONE, RLE, ZIPS, ZIP and PIZ compression and HALF/FLOAT/UINT channels, decoding to the same linear float RGBA texture RGBELoader returns. No OpenEXR dependency and no extra zlib — EXR ZIP chunks are ordinary zlib streams. The PIZ decoder treats input as hostile (every table index, pointer step and run length bounds-checked) and was verified bit-exact against OpenEXR on four files. PXR24, B44, DWAA/DWAB and tiled/deep/multi-part files are rejected by name rather than decoded into garbage. TextureLoader now routes .exr and .hdr to the HDR loaders — a .hdr previously fell through to stb's LDR path and came back tonemapped and clipped.
• glTF overhaul. Geometry cached by (mesh, primitive, hasSkin) so a primitive referenced by several nodes decodes once; texture cache re-keyed by (texture, colorSpace); KHR_texture_transform results and animation input accessors memoized. Bulk memcpy fast paths for packed FLOAT/uint32, file reads sized from file length, and move-aware attribute/index APIs. Added: sparse accessors, the normalized flag, bounds validation, sampler filters, multi-scene independence, and KHR_meshopt_compression under both the draft and ratified extension names. Fixed: KHR_lights_punctual spot lights (a typo plus nested cone angles), animation clip start times normalized to zero, and a crash on points/lines primitives. Every phase was validated against a structurally byte-identical dump across 13–14 baseline assets, produced by the in-tree gltf_dump tool.
• Hardening: DDSLoader computed mip data size in uint32, so a crafted 262144×262144 header wrapped to 0, passed the truncation check, and wrote far outside a zero-byte allocation (now uint64 with dimension and mip caps). ColladaLoader gained bounds-checked source reads, indexed geometry via tuple dedup (−28% vertices on the youbot model) and from_chars parsing (~2× faster). FBXLoader guards truncated files and matches image extensions case-insensitively. TextureLoader's cache is keyed on path|colorSpace|flipY, so an image used as both an sRGB colour map and a linear data map gets the right interpretation for each.
• tests/loaders went from a font test to 17 executables (~7,000 lines) covering Collada, DDS, EXR, glTF, images, OBJ, STL, object JSON, SOG, splat PLY, URDF and xacro. Several suites synthesize fixtures rather than vendoring assets.
• threepp/utils/GeometryLod.hpp is a renderer-agnostic index-only LOD chain generator over meshoptimizer: vertex data is never touched, so every returned index still refers into the caller's original array and a consumer swaps levels by rebinding the index buffer alone — in both the raster path and the BLAS.
• A new THIRD_PARTY.md maps every vendored, fetched and vcpkg-resolved dependency to its license, reproducing the three.js MIT notice and the embedded typeface license in full. It names the two that are not open MIT: threepp_data's Spot URDF (Boston Dynamics SDK License, simulation use only) and the NVIDIA DLSS SDK (proprietary, and the build copies nvngx_dlss.dll next to executables).

Procedural content

• TileTerrain is a quadtree-LOD terrain system (header-only) where tiles subdivide by camera distance with hysteresis and everything is pulled through a three-function TerrainProvider, so procedural noise, eroded generator output and real DEMs drive the same machinery. Each bake makes one provider sweep into a height lattice and derives positions, normals, splat, band weights, normal map, height AABB and error metric from it. LOD borders are watertight (neighbour level delta ≤ 1, border verts conformed, skirts as backstop), bakes run on bounded async workers, and a split only applies once every replacement is ready.
• Real-world geodata. A documented "region pack" format plus an included Python fetcher builds one from Norwegian open data: Kartverket national DTM via WCS, NVDB road polylines, and OSM building footprints. Building heights are measured from the Kartverket surface model — 95% of Ålesund gets lidar-derived heights versus 0.4% from OSM height tags. Packs are ~64 MB each and are not committed; you must run the fetcher.
• Roads: road::RoadNetwork composes per-polyline corridor flattenings into one ground-height function, carveRoads bakes the cut into the DEM at load so tile splits cannot reveal sub-quad road humps, and painting asphalt into the splat turned a distant road from sub-pixel geometry into mip-filtered texture (island frame-diff 1.4 → 0.05–0.13 /255 at the MSAA2 default). Spans are classified from NVDB point heights before conforming, so bridges get decks and tunnels and ferry legs are excluded rather than submerged.
• threepp::Ocean is a first-class object type: scene->add(Ocean::create()) gives a three-cascade Phillips-spectrum sea with rectangular extents, decoupled mesh and FFT resolution, live wind, and a Look enum pinning ocean versus pond material recipes. The header is explicit that the surface animates only under Vulkan; on GL it is an inert flat plane wearing the water material. Compiled only when THREEPP_WITH_VULKAN=ON.
• Vegetation: BranchingMode::Whorl gives monopodial conifers with drooping branch rings instead of pancake stacks; the leaf atlas is now a branchlet of ~30 leaflets with per-species blade outlines, so canopy density comes from the texture rather than from stacking giant quads; BarkStyle covers furrowed, plated and papery with birch lenticels. A voxel field over leaf-bearing nodes bakes sky-occlusion into vertex colour so canopies shade as a volume with a dark core. Card winding was made to agree with the shading normal, cutting grey view-dependent canopy patches from 8.7% to 1.7% of canopy pixels. Defaults are unchanged — the conifer look is opt-in via preset or by setting the modes directly.
• Grass: GrassTiles splits a field into world-space tiles so the Vulkan renderer can cull off-screen tiles and freeze wind on far ones, with sway seamless across boundaries because phase derives from world XZ. The tapered blade template existed three times with drifted colour constants and now routes through one function, verified as a pixel-identical GL capture. GrassField's shader also now applies tonemap and output encoding before fog, so blades stop rendering near-black on GL.
• A texture bakery: matched detail albedo/normal/roughness pairs from one shared heightfield, a four-band terrain set (grass/rock/scree/snow) with Voronoi plates, clumps, packed scree and snow glints at metre-scale periods, and tileable building facades where a tile spans exactly one window bay by one floor so window rows never cut at the roofline. All asset-free.
• architecture::createLogCabin emits a complete Scandinavian log cabin as ~10 merged geometries with every texture generated in-engine: courses alternate direction so crossing logs overlap by half a diameter, openings snap to course joints and are subtracted from the runs, gable walls stack under the roof plane, and the porch roof springs from the main eave as a broken pitch. Wall dormer, covered porch, divided-light windows, panelled door, rubble foundation and flue are parametric.
• TerrainScatter places camera-following ground-cover tufts through the same provider the tiles bake from, so props match their ground and painted roads are excluded automatically; cells build deterministically from hashed coordinates. The radius is deliberately short (55 m) because centimetre blades are sub-pixel past ~60 m and sparkle under jitter. A stone species was built and then removed — a stone on the provider surface floats or sinks wherever the rendered tile mesh deviates.
• TerrainGenerator's baked AO was a single-cell Laplacian, i.e. a band-pass that stippled noise bumps into dark dots and rang at slope breaks. It now takes the Laplacian at 1 and 2 cells and keeps the weaker magnitude only when both agree the sample is concave, with five new knobs. The scale of aoStrength changed as a result.

Conveyors, vehicles and examples

• threepp::conveyor is a first-party subsystem: waypoint paths with exact circular-arc corner fillets whose radius self-clamps to what the neighbouring segments allow, per-segment flat/roller/cleat surfaces, watertight belt and wall ribbons with arc-length UVs, roller and cleat layout, a support frame derived from belt width, and a procedural scrolling belt texture. Compiled into the library unconditionally.
• Belt physics builds colliders from the same resampled path the visuals use. Straight runs are kinematic boxes advanced along travel and teleported back, so the surface never moves but everything resting on it inherits its velocity — which works for rigid bodies and GPU soft bodies. A bend is one body rotating about the vertical axis through its arc centre, tiled with shared-face annular convex wedges cooked GPU-compatible, so soft bodies convey around corners. A roller span builds no drag box at all: each roller is a kinematic capsule spun at speed / radius, so every contact reads the true rolling surface velocity. Requires the PhysX SDK.
• Conveyors work without the editor: config, waypoints and generated meshes are plain scene content, every generated part is role-tagged, and an external consumer rebuilds belt physics in a few lines. A test holds that whole path green — author, save, load with no editor, rebuild physics, convey a box.
• Vehicle authoring: point at four wheel meshes and chassis dimensions, wheel radius, track, wheelbase, suspension height and the facing direction are all derived from the picks (including static-settle compensation, so the car rests at ride height on the first Play). Picks may be Groups and duplicate names resolve ordinally, which is the normal shape of an imported asset. WASD teleop or a Python Vehicle handle. Automatic transmission and four wheels only — the runtime is a fixed array of four.
• New example projects: fps_demo (procedural arena with real colliders, animated viewmodel, flow-field enemies that hand their skeleton to physics on death, pooled casings/decals/rigs — pooling took a 600-frame firing run from four ~240 ms spikes to a 10.3 ms max), Spot (a walking policy in pure C++ with a std-only MLP loader, both the weights and a golden reference committed so it runs from a fresh checkout; parity to 2.9e-06 over 64 golden pairs, walking 8.04 m at a commanded 1.0 m/s), and NorwayDrive (a PhysX car on Kartverket/NVDB geodata, driving a re-cooked terrain window that already is the road surface because roads are carved into the DEM at load).
• RobotCell moved to a Franka FR3 with a real two-finger gripper — none of the four robots the repo shipped previously had an actuated end effector. Two defects surfaced: articulation drive-target order is topological while Robot's DOF order is document order, so setDriveTargets silently drove the wrong axis (now mapped by name), and the motion planner's guard() never actually arced around the base. Honest caveat stated in the source: tryGrab() is still a distance test that flips the crate kinematic, so a fully open gripper would still carry.
• Demo code promoted into the library: terrain::makeRockGeometry (existed three times, and only two copies carried the pole-flicker fix, so the artefact was live in the third), audio::synth primitives, and a shared Mustang rig. Eight hand-rolled smoothstep copies collapsed onto math::smoothstep.

Build, CI and dependencies

• CMakePresets.json ships 7 user presets (gl, gl-debug, vulkan, vulkan-aaa, python, no-glfw, wasm) plus 9 ci-* ones, each building into build/<preset-name>. CI runs the same presets, so the CI configuration and the documented one are one object. CMakeUserPresets.json is gitignored for machine-local presets.
• CI grew from 6 jobs to 8. New: linux-asan (ASan + UBSan, leak detection deliberately off because the GL driver leaks per-process allocations) and python-bindings (3.10/3.12 matrix, pytest under Xvfb on software GL). The main Linux job now uses ci-linux-physx, which adds the vcpkg toolchain and the physx feature — unlocking 14 test executables and 8 example directories that had never been compiled in CI. vcpkg is pinned with its binary cache persisted, and a guard step greps ctest -N for a known PhysX test so a silent fall-back to the "physx not found" branch cannot leave the job green. GPU paths remain untested — the runners have no device.
• Two new workflows: pages.yml publishes the WASM examples to GitHub Pages on every push to master, and wheels.yml builds release wheels and an sdist and publishes them to PyPI on a date tag, with TestPyPI rehearsals on workflow_dispatch (see the Python section).
• THREEPP_BUILD_EXAMPLES and THREEPP_BUILD_TESTS now default to PROJECT_IS_TOP_LEVEL rather than ON, so a FetchContent consumer no longer pulls in 116 executables, Catch2 and the threepp_data asset repo. This is what moved cmake_minimum_required from 3.19 to 3.21.
• Editing a GL shader now rebuilds the binary. embed.cmake read and wrote shader headers at configure time, so nothing in the build graph depended on shader sources — editing one and building rebuilt nothing, and the binary kept running whatever was embedded when CMake last configured. Each shader now has an add_custom_command depending on its .glsl. The Vulkan shader step likewise tracks sibling .glsl/.h includes, and deferred_shade.comp was split into topical includes with the SPIR-V verified bit-identical.
• Link-order and translation-unit fixes for the non-default configurations: stbi_write_png_to_func lived only inside GLRenderer.cpp, dragging Canvas::initWindow into a test that touches no renderer and breaking the no-GLFW job; BC7Encode.cpp sat inside the Vulkan source block while its test was registered unconditionally; and cmake/PhysxStaticLinkFix.cmake wraps the static PhysX archives in a $<LINK_GROUP:RESCAN,...> because single-pass GNU ld cannot resolve PhysXExtensions' backward references, and appends libPhysXVehicle2_static_64.a, which the vcpkg port installs on Linux but only links on Windows.
• The test suite went from 37 to 128 test files, with new animation, geometries, materials, objects and splats directories. Vulkan-side tests use exit-code + SKIP_RETURN_CODE 42 so they self-skip without a GPU; golden references are GPU-specific and documented as a local pre-push check, not a cross-hardware gate. .gitattributes marks *.ppm binary after core.autocrlf rewrote a golden's header LFs and rotated its colour channels.
• meshoptimizer moved 1.0 → 1.1 with the compression decoders vendored (which is what enables KHR_meshopt_compression). libwebp 1.6.0's decoder subset is vendored and compiled in unconditionally, pinned at ≥1.3.2 because CVE-2023-4863 is reachable from an ordinary .webp. threepp_data moved from GIT_TAG main to a pinned commit, so example and test assets are reproducible.
• A top-level build with no CMAKE_BUILD_TYPE on a single-config generator now defaults to Release — deliberately only when top-level, since a consumer owns its own build type.

Removed

• The WebGPU backend, in full: WgpuRenderer, CrossRenderer, 30 files under renderers/wgpu/, GraphicsAPI::WebGPU and ::Cross, the THREEPP_WITH_WGPU/THREEPP_WGPU_GLSL_COMPAT options and their fetch modules, imgui_impl_wgpu, examples/wgpu/, the WebTide example project and doc/wgpu-feature-parity.md — a net −32,332 lines. No CI job ever built it, and the largest test in the suite (3,281 lines) exercised a backend that never compiled. Salvaged rather than deleted: 29 GL and analytic furnace test cases that only ever built under THREEPP_WITH_WGPU now run by default.
• The Vulkan path tracer: the RT megakernel, ReSTIR DI/GI, photon caustics and the à-trous denoiser — 39 files, −10,626 lines, including a 2,125-line raygen shader and a 1,087-line shading header. VulkanRendererCore.hpp survives as a four-line shim.
• Hybrid SSR reflections were added and removed inside this window: perf-neutral at landing, then broken as the hit-distance gloss footprint read SSR hits as unknown distance (full-width blur on every glossy reflection) and camera-path fog got pasted into reflections and fogged again. RT owns the reflection channel. setTaaHdrInput was likewise added and removed.
• The material-anisotropy jitter policy — 16× when unjittered, isotropic when jittered — shipped and was then withdrawn: it bought nothing measurable and cost mip-blurred ground and facade textures at grazing angles on every upscaled frame. 16× is now the default in every mode. (The header comment still describes the retired policy; that is a documentation bug.)
• Road authoring in the editor went through four designs (offset ribbon, straight+arc chain, trimmed offsets, biarc) and all four were rejected; RibbonGeometry, RoadPath, RoadAlignment, RoadGeometry, the Road spline mesh kind and the road hull collider are gone. SplineConfig::MeshKind is {None, Tube}. Kept from that work: the Tube geometry, the physics-collider overlay, Shape::Auto resolving to a triangle mesh or hull, and --screenshot. None of it was ever on master.
• examples/libs/kine (Kine, KineLink, KineLimit, CCD/DLS IK solvers, Angle.hpp) and the Crane3R example, superseded by Robot + extras/kinematics/InverseKinematics.hpp; urdf_loader_obj and urdf_loader_simple, folded into urdf_loader; the Python spider and turret RL demos.
• MaterialWithSheen::sheen (the legacy r129 optional colour), the masked-FXAA overlay path, bloom_blur.comp and composite.comp, src/threepp/loaders/XacroProcessor.hpp, EventCameraSensor's wall-clock epoch, the per-vehicle duplicated PxVehicle2 stacks, and TerrainScatter's stone species.
• THREEPP_WITH_INFERENCE survives (Vulkan-only now) but its tests were deleted with the WGPU backend, so the feature is example-only with no automated coverage.
• The PhysX and Gaussian-splat domains report no public API removals — both are pure additions on top of what master shipped.

Breaking changes

Backends and build

• GraphicsAPI::WebGPU and GraphicsAPI::Cross are gone from the Canvas/RendererFactory enum; WgpuRenderer.hpp, CrossRenderer.hpp and all of renderers/wgpu/ (including the old wgpu/EffectComposer.hpp — the replacement is threepp/postprocessing/) are deleted.
• CMake options THREEPP_WITH_WGPU, THREEPP_WGPU_GLSL_COMPAT and THREEPP_FETCH_ASSIMP removed; THREEPP_WITH_INFERENCE now depends on THREEPP_WITH_VULKAN alone. cmake_minimum_required is 3.21.
• THREEPP_BUILD_EXAMPLES and THREEPP_BUILD_TESTS default to PROJECT_IS_TOP_LEVEL — a subproject consumer that relied on the old ON default now gets only the library.
• install(TARGETS glslang SPIRV glslang-default-resource-limits) dropped from the export set.

Vulkan renderer

• Path-tracer-era setters removed: setRenderMode, setSamplesPerPixel, setMaxBounces, setRestirGIEnabled, setRestirDIVisibilityReuse, setSerEnabled, setPerSppJitterHybrid, setMeasurePrimaryTraceOnly, setSilhouetteMsaaExtra (superseded by setGbufferMsaa).
• setVolumetricFog(bool) is a no-op kept only so callers compile — shafts and aerial perspective are always on when a fog medium exists, so passing false no longer disables them. setDeferredDenoise/deferredDenoise are deprecated aliases.
• VulkanRendererCore is now an alias of VulkanRenderer, not an abstract base — source-compatible for calls and dynamic_cast, but a type that inherited from or forward-declared it as a distinct class will not compile.

Core and OpenGL

• Object3D::renderOrder changed from unsigned int to int (as did RenderItem::renderOrder/groupOrder and the RenderList push/unshift chain).
• Object3D::removeFromParent() returns std::shared_ptr<Object3D> instead of void. Source-compatible for callers that ignore it — but discarding the result still destroys a solely-owned child.
• Object3D now publicly derives std::enable_shared_from_this<Object3D>. Do not call shared_from_this() on a stack-allocated object.
• BufferAttribute gained four pure virtuals (type(), data(), byteLength(), cloneUntyped()); any subclass not deriving from TypedBufferAttribute<T> no longer compiles.
• MaterialWithSheen::sheen removed — use sheenColor/sheenRoughness. MaterialWithReflectivity now inherits MaterialWithRefractionRatio virtually, so every concrete material deriving from it must name that base in its own init-list. (With two copies, material->refractionRatio was ambiguous, the dynamic_cast returned null so serialization skipped the field, and the renderer read a different copy than setValues() wrote.)
• BufferGeometry::uuid and Object3D::uuid are no longer const; ProgramParameters::sheen is now bool and ProgramParameters::from() gained a trailing ColorSpace outputColorSpace; Renderer gained a virtual getCurrentViewport(Vector4&) const; EventDispatcher::hasEventListener is now const and the class gained user-declared copy/move operations; TorusKnotGeometry's protected constructor takes a const Params&.
• KeyframeTrack's constructor throws std::invalid_argument on empty times or a value count that is not a positive multiple of the time count — previously accepted, with the divide-by-zero deferred to playback. Texture::image() const throws on an empty image vector instead of calling front().
• Scene, PerspectiveCamera and OrthographicCamera return their three.js names from type() instead of inheriting "Object3D".
• ImageData gained a std::vector<uint16_t> alternative — an exhaustive std::visit over it no longer compiles until the new case is handled.
• GLTFLoader::preserveNarrowAttributes defaults true, so normalized uint8/uint16 COLOR_0 loads narrow; getAttribute<float>("color") returns null on such meshes. Read through FloatAttributeView or set the flag false.
• Rendering behaviour changes on GL: glTF assets using KHR_materials_sheen or KHR_materials_specular render differently, and F_Schlick switched to exact pow5 for every material (peak ~0.003 absolute).

PhysX

• PhysxWorld::Settings gained fields in the middle of the struct. Designated initializers are fine; positional aggregate init now assigns to different members.
• PhysxVehicle::Settings / PhysxVehicleEngineDrive::Settings are aliases of types deriving from PhysxVehicleBaseSettings — the names still resolve, but designated initialization of an inherited member is ill-formed for a derived aggregate and will not compile.
• onPreSubstep/onPostSubstep return a SubstepHandle instead of void. Ignoring it still compiles, but anything registering a callback capturing this must now unregister in its destructor.
• removeActor nulls slots inside InstancedMesh bindings, so an instance whose actor was removed freezes rather than following a neighbouring body. Soft-body geometry that previously took the direct-mapping fast path by coincidence now takes the correct skinned path, changing its rendered rest pose.

Robotics

• Robot's default end effector changed from "the last declared joint" to "the deepest leaf link", and computeEndEffectorTransform now walks only the root-to-tip path. Any branched robot gets a different — and correct — answer; call setEndEffector(linkName) to be explicit.
• Robot::setJointValue on a prismatic joint rotates the slide axis by the joint's own orientation, not the robot's euler rotation.
• URDF <collision><cylinder> is treated as Z-aligned per spec, and <collision><mesh> cooks to a convex hull rather than a bounding box. A URDF hand-authored against the old Y-aligned behaviour must be re-authored — the repo's own Spot description was.
• src/threepp/loaders/XacroProcessor.hpp was deleted; move to include/threepp/loaders/Xacro.hpp, whose Processor is default-constructed then configured with setArgs/addPackagePath.

Python

• Blending.None → Blending.NoBlending (the old name is a Python syntax error and made the whole type stub unparseable); damp(..., lambda=) → damp(..., lambda_=); the flat threepp.pyi is replaced by a stub package. None of these can break a released API — the module is new in this range.

Editor, player, conveyors, splats

• No source-breaking changes: apps/, threepp/extras/editor/, threepp/extras/conveyor/ and the splat headers did not exist at the previous release, so everything there is additive. Conveyor authoring did migrate from arc-centre waypoints to derived corner fillets mid-cycle, which only affects anyone tracking dev.

Getting started note: threepp/threepp.hpp was not touched in this range, so none of the new subsystems — post-processing, SplatCloud, Ocean, sensors, kinematics, conveyors, AttributeView, InstancedBufferGeometry — is reachable through the umbrella header. Include them explicitly.

---

This discussion was created from the release 2026-08-08.