threepp

The short version: the Vulkan ocean keeps what boats leave on it (a wake field of foam, bubbles and the waves a hull makes, for up to eight vessels on one sea), Python gets a set of vehicle rigs (three sea drones, an AUV, five aircraft and a car, each built from one spec file with its sources cited), text follows the font's real curves and is UTF-8, a Vulkan process exits in milliseconds instead of 20 seconds, the Vulkan renderer runs on a GPU without ray tracing, and the web build is lit by its environment and plays sound. Three new OpenGL demos load no assets at all: showpiece, MarbleRun and SandTable.

Figures below come from the commits that measured them, on the hardware those commits name. They were not re-benchmarked for this release.

⚠️ Breaking and behaviour changes

API

• type() returns const std::string& on Object3D, Material, BufferGeometry and everything under them. It returned a std::string by value, which cost a heap allocation per call for the longer names, several times per draw. Callers compile unchanged. A class of your own that overrides type() must take the new return type.
• Font::glyphs is keyed by Unicode code point, not by char.
• Removed from VulkanRenderer: setDeferredDenoise / deferredDenoise (use setDenoise / denoise), setVolumetricFog (a no-op since the fog unification; Python's volumetric_fog goes with it), and the VulkanRendererCore.hpp header and alias.
• FireEffect::Params::legacyEmbers and emberRate are gone, with vulkan_fire --legacy-embers. The embers are a ParticleField.
• PhysxVehicle: Settings::stickyDampingLongitudinal and stickyDampingLateral are gone. The vehicle now chooses between stickyDamping and stickyDampingHold each step (see the grade hold below).
• Texture::premultiplyAlpha is removed. Neither renderer read it. The key in an old scene file is ignored on load.
• Material::clipping is gone from the base class. It shadowed MaterialWithClipping::clipping, which is the one that remains.
• PhysxSoftBody::registerGlTexture returns bool, like registerVulkanMemory.
• THREEPP_DLSS_JITTER_SIGN is removed. The per-axis THREEPP_DLSS_JITTER_SIGN_X / _Y stay.
• ABI: many classes changed layout. Rebuild everything that links threepp.

Behaviour

• Canvas::Parameters::fastExit is on by default. A process on its way out leaves its Vulkan device to the OS instead of destroying it, which on NVIDIA drivers could wait about 20 s in vkDestroyDevice. An app that tears its renderer down and builds a new one while the process goes on sets fastExit(false). Python's Canvas(fast_exit=...) keeps its False default, since interpreter exit is covered automatically.
• VulkanRenderer is created on a device without ray tracing. It used to throw there. It now draws a degraded frame (see the no-ray-tracing mode under New). Code that caught the exception to fall back to GLRenderer asks rayTracingSupported() (Python ray_tracing) instead. Where there are several devices, one with ray tracing is still preferred.
• A Vulkan readback inside the frame returns that frame. readRGBPixels(), writeFramebuffer() and Python's save_frame used to copy a swapchain image up to three frames old, so a script that changed the scene and saved a still got the old scene. The readback now ends the open frame first. An ortho HUD pass that arrives after the readback in the same iteration is skipped with a one-time hint: put it before the readback. Baselines captured through this path change once.
• Python: VulkanRenderer draws an OrthographicCamera as a 3D view (orthographic_scene_rendering, on by default). A top-down render used to come out as unlit fills in scene order with a black background. The C++ default is unchanged, but a lit mesh sent down the 2D path now prints a one-time hint that names the call to mak

Fixes

• MinGW shared Debug builds link again. At 2026-09-27, a MinGW-w64 GCC Debug build with BUILD_SHARED_LIBS=ON failed to link libthreepp.dll with relocation truncated to fit: IMAGE_REL_AMD64_SECREL. The same happened when threepp was pulled in with FetchContent. ObjectLoader.cpp compiled to 33,914 COFF sections, which is over the 32,767 a regular object file can hold.

  • ObjectLoader.cpp is now split in two. ObjectLoaderResources.cpp builds the images, textures, materials, geometries and animations, and ObjectLoader.cpp builds the object tree from them. Each half is about 20k sections.
  • GLTFLoader.cpp was next in line at 25,498 sections, so it is now split into three files: GLTFLoader.cpp, gltf/GLTFMaterials.cpp and gltf/GLTFMeshes.cpp. The largest of these is about 16k sections.
  • As a safeguard, MinGW GCC now writes big-object COFF files (-Wa,-mbig-obj), the MinGW equivalent of MSVC's /bigobj. A file that grows past the limit later won't break the build.

  No behaviour changes: the code was moved, not rewritten.

Build

• threepp_editor_core is only built when something needs it. Projects that consume threepp through FetchContent or add_subdirectory no longer compile its 37 sources. The editor, the player, the tests and the Python bindings still build it as a dependency. It was never part of the install.

CI

• New windows-mingw job. It builds threepp as a Debug DLL with MinGW-w64 GCC from MSYS2 and runs the test suite against it. Before this, no CI job built with GCC on Windows or built the shared library at all, which is why the link failure went unnoticed. The job also logs the objects with the most COFF sections, so file growth stays visible now that -mbig-obj keeps the build green.

The short version: the OpenGL backend catches up with three.js r186 (shadows, environment lighting, tone mapping, transparency, GTAO and outline passes), both backends now return the light a physically based material should, the Vulkan frame is one render graph that derives its own barriers and shares its scratch memory, and granular soil can carry a wheel, a rover or a whole car.

Figures below come from the commits that measured them, on the hardware those commits name. They were not re-benchmarked for this release.

⚠️ Breaking and behaviour changes

Read this before upgrading. A few items break at compile time, and many scenes will look different on both backends, mostly because energy that used to be lost or double-counted no longer is.

API

• Texture::texCoord is replaced by Texture::channel (the three.js r152 name): 0 = uv, 1 = uv2, 2 = uv3. Nothing ever read texCoord; the glTF loader now routes texCoord and KHR_texture_transform's override into channel. An aoMap or lightMap left at channel 0 still samples uv2 when the geometry has one.
• ShaderChunk::lights_lambert_vertex() is gone. Lambert is lit per fragment now (lights_lambert_pars_fragment / lights_lambert_fragment). Custom ShaderMaterials that included the vertex chunk need the fragment pair.
• The Vulkan Ids G-buffer AOV is 4× uint32, 16 bytes per pixel (was 4× uint16, 8 bytes). This applies to readGBufferAOV / readViewGBufferAOVs and the Ids frame-interop channel. Entry indices used to wrap past 65,535, so entry 66,000 was shaded with entry 464's material. Stable ids are now 32-bit, capped at 2³¹−1 to match LidarReturn::hitInstanceId. Python decoders read uint32, and cuda_interop exports ids as '<u4', falling back to an int32 view where torch rejects uint32.
• VulkanRenderer refuses a device without VK_KHR_ray_query and throws with the device name. It used to dereference a null shade pass. Some datacenter drivers expose the other KHR ray-tracing extensions but not ray query; use EglContext + GLRenderer there (see below).
• Renderer::checkShaderErrors defaults to true, as in three.js. A shader that fails to compile or link is now reported with the driver log instead of silently drawing nothing. Healthy scenes print nothing.
• The env-sun policy (EnvSunPolicy, envSunFound(), envSunDirection(), envSunColor()) moved to the Renderer base class. VulkanRenderer::EnvSunPolicy is an alias, so existing spellings compile.
• ABI: Texture, Material, BufferGeometry, RenderTarget and InstancedMesh lose a private member, Scene gains five fields, and LightShadow::copy is a new virtual. Rebuild everything that links threepp.

OpenGL: scenes look different

• Tone mapping happens once, on the way to the screen (three.js r154+). Anything rendered into a render target is now scene-linear HDR. EffectComposer appends an implicit OutputPass (new) that tone-maps and encodes at the end, unless your chain already has one. Bloom thresholds real light now: an emitter at 10 blooms far more than one at 1. Reflector, Water and the transmission capture render to half-float targets, so mirrors are no longer washed out and glass no longer tone-maps twice. A target that is the picture can opt back in with RenderTarget::displayTarget; CameraSensor does, so GL sensor captures are byte-identical to before.
• One sun, as on Vulkan. An equirect HDR with a sun baked in used to light every diffuse surface on top of the scene's own DirectionalLight. GL now clamps the disc out of the rough PMREM levels and re-adds the removed energy as one shadowless analytic light, but only while the scene has no visible DirectionalLight. HDRI-lit GL scenes get darker and cooler. On the forest demo, luma went from 77 to 48, close to Vulkan.
• Physically based energy, per three.js r185:
  • Rough metals under an environm

New this release: imaging sonar, ray-traced AO with bent normals, zero-copy frame export to CUDA, splat point clouds and splat scene serialization, PhysX tendons, and the GeoScene terrain stack.

Breaking changes

• Object3D::lookAt() now applies the camera convention (local -Z toward the target) to sensors. New virtual Object3D::usesCameraLookAtConvention() (default false) is overridden by TracedRasterVisionSensor (so DepthSensor and LidarSensor), PathTracedLidarSensor, CameraSensor and SonarSensor. Code that compensated with the mirror point lookAt(2*position - target) now aims backwards and must pass the target itself. Adding a virtual to Object3D changes its vtable layout.
• Imu defaults are the ICM-42688-P datasheet figures: gyroNoise 0.005 → 4.8869e-5 rad/s/√Hz, accelNoise 0.06 → 6.8647e-4 m/s²/√Hz, both random-walk terms → 0. Seeds are unchanged, so seeded replays keep their streams, but existing scenes get different noise magnitudes.
• LidarModel::OS1_64() and OS0_128() step azimuth at 360/1024° (0.3515625) instead of 0.35°: 1024 columns per revolution instead of 1029.
• BVH::intersects() and BVH::intersect(..., accurate=true) run an exact triangle-triangle test instead of the triangle-AABB overlap approximation. Near-miss pairs that previously reported a hit no longer do. BVH::build(positions, indices) throws on malformed input, and getGeometry() returns nullptr after the array build.
• ArticulationLink's constructor gained a leading const PhysxWorld* parameter.
• PhysxGpuBatch::blockFloatsWrite throws std::runtime_error for unhandled write types (including the four tendon types) instead of returning maxDofs.
• ParticleField::submit gained float dtSec = 0.f, and VulkanRenderer::enableVertexInterop gained bool stableCorrespondence = true. Both source-compatible; both ABI-breaking.
• RoadNetwork::buildBridgeMeshes() and buildGroundChunkMeshes() keep their signatures but ignore texWidth/texHeight. Resolution, tile length, UVs, vertex/index counts and materials now come from MarkingRules; materials are shared per (marking class, surface, width, wear, variant), so mutating one returned mesh's material changes every piece of that class; ground chunks gain a child patch-decal mesh. buildMeshes() keeps the legacy path.
• buildGeoBuildingMeshes() emits up to nine named child meshes (geo_buildings_wood, _masonry, _industrial, _roof_slate, …) instead of the three geo_buildings_walls, _walls_plain, _roof. Lookups by name now fail at runtime rather than at compile time.
• terrain::detail::geoBldRoofPalette() was removed from GeoBuildings.hpp. Buildings with no OSM colour tag render in different colours.
• makeNorwegianSplat() emits eight layers instead of six (new shallow and seabed layers; wetland heightLo moved from sea−5 m to sea−0.5 m). Terrain colour below the waterline changes for existing geo scenes.
• makeGeoProvider() tints terrain albedo from land cover by default: GeoTerrainOptions::landCover defaults to true and pack.flow is always computed, so wet-rock and scree tinting apply to every existing pack.
• loadSogWithLod throws when a multi-level SOG asset's tree leaves do not tile a chunk exactly.
• Rendering output changes: the ocean fine-cascade normal runs at full slope (an undocumented 0.5 factor was removed); setDeferredAO(true) now selects the half-res RT AO + bent-normal pass; TAA history invalidation changes frame-0 output; the foam accumulator is capped at 1024 (THREEPP_OCEAN_FOAM_RES=2048 restores the old density); the GL fogColor uniform is encoded at upload.

Added

Sensors

• SonarSensor (new header threepp/helpers/SonarSensor.hpp) — Vulkan-only forward-looking imaging sonar, traced through the renderer's acceleration structure as one dispatch. Synchronous scan() plus the pipelined scanBegin/scanFired/scanReady/scanCollect.
• SonarModel (new head