diff --git a/examples/projects/CMakeLists.txt b/examples/projects/CMakeLists.txt
index 345df017..32641b51 100644
--- a/examples/projects/CMakeLists.txt
+++ b/examples/projects/CMakeLists.txt
@@ -9,6 +9,7 @@ if (TARGET unofficial::omniverse-physx-sdk::sdk)
     add_subdirectory(Physics)
     add_subdirectory(RobotCell)
     add_subdirectory(Vehicle)
+    add_subdirectory(Drive)
     add_subdirectory(Shooter)
 endif ()
 
diff --git a/examples/projects/Drive/CMakeLists.txt b/examples/projects/Drive/CMakeLists.txt
new file mode 100644
index 00000000..5df51aea
--- /dev/null
+++ b/examples/projects/Drive/CMakeLists.txt
@@ -0,0 +1,2 @@
+
+add_example(NAME "drive" SOURCES main.cpp LINK_IMGUI LINK_PHYSX)
diff --git a/examples/projects/Drive/CarRig.hpp b/examples/projects/Drive/CarRig.hpp
new file mode 100644
index 00000000..8c8a3609
--- /dev/null
+++ b/examples/projects/Drive/CarRig.hpp
@@ -0,0 +1,392 @@
+
+#ifndef THREEPP_DRIVE_CARRIG_HPP
+#define THREEPP_DRIVE_CARRIG_HPP
+
+// A car built from scratch out of threepp primitives — no imported model.
+//
+//   - body : stacked / tapered boxes (lower body, greenhouse cabin, bonnet,
+//            bumpers) + chrome trim + emissive lamp lenses.
+//   - wheels: cylinder tyre + rim + hub, one Group per corner, driven each frame
+//            by the vehicle's per-wheel local pose (steer + spin + jounce baked in).
+//   - struts: a visible coil-over per corner — a helical spring tube + damper rod
+//            spanning a fixed chassis mount to the moving wheel hub. The spring is
+//            modelled at unit height and scaled to the live strut length, so the
+//            coils visibly bunch under compression (the "shock absorbers").
+//   - lights: two headlight SpotLights (+ glowing lenses) for night driving, plus
+//            brake / reverse / indicator lamps driven from vehicle telemetry.
+//
+// All visuals live under one root Group that the demo binds to the PhysX chassis
+// actor, so the whole car follows the simulation.
+
+#include "threepp/threepp.hpp"
+
+#include "threepp/extras/physx/PhysxVehicleEngineDrive.hpp"
+
+#include <array>
+#include <cmath>
+#include <memory>
+#include <vector>
+
+namespace drive {
+
+    using namespace threepp;
+
+    class CarRig {
+    public:
+        struct Config {
+            float bodyWidth = 1.9f;
+            float bodyHeight = 1.3f;
+            float bodyLength = 4.4f;
+            float wheelRadius = 0.36f;
+            float wheelHalfWidth = 0.16f;
+            float trackWidth = 1.65f;
+            float wheelbase = 2.7f;
+            float suspensionAttachmentY = -0.35f;
+            float suspensionTravelDist = 0.32f;
+            Color paint = Color(0xb8412e);// warm rally red
+        };
+
+        explicit CarRig(const Config& cfg) : cfg_(cfg) {
+            root_ = Group::create();
+            buildBody();
+            buildWheels();
+            buildStruts();
+            buildLights();
+        }
+
+        [[nodiscard]] std::shared_ptr<Group> root() const { return root_; }
+
+        void setHeadlights(bool on) {
+            headlightsOn_ = on;
+            for (auto& sl : headlights_)
+                if (sl) sl->intensity = on ? headlightIntensity_ : 0.f;
+            if (headlampMat_) {
+                headlampMat_->emissiveIntensity = on ? 6.f : 0.4f;
+                headlampMat_->needsUpdate();
+            }
+        }
+        [[nodiscard]] bool headlightsOn() const { return headlightsOn_; }
+
+        // Update visuals from the vehicle. turnSignal: -1 left, 0 none, +1 right.
+        void update(const PhysxVehicleEngineDrive& v, float dt,
+                    float brakeCmd, int turnSignal) {
+
+            // ── Wheels: copy the per-wheel local pose straight from the vehicle ──
+            for (int i = 0; i < 4; ++i) {
+                const auto wp = v.wheelLocalPose(i);
+                wheelRigs_[i]->position.set(wp.p.x, wp.p.y, wp.p.z);
+                wheelRigs_[i]->quaternion.set(wp.q.x, wp.q.y, wp.q.z, wp.q.w);
+            }
+
+            // ── Struts: stretch each coil-over from its chassis mount to the live
+            //    hub position (translation only — the strut doesn't spin). ────────
+            const Vector3 yAxis{0.f, 1.f, 0.f};
+            for (int i = 0; i < 4; ++i) {
+                const auto wp = v.wheelLocalPose(i);
+                Vector3 hub(wp.p.x, wp.p.y, wp.p.z);
+                Vector3 dir = hub.clone().sub(strutMount_[i]);
+                float len = dir.length();
+                if (len < 1e-4f) len = 1e-4f;
+                dir.multiplyScalar(1.f / len);
+                struts_[i]->position.copy(strutMount_[i]);
+                struts_[i]->quaternion.setFromUnitVectors(yAxis, dir);
+                struts_[i]->scale.set(1.f, len, 1.f);
+            }
+
+            // ── Lamps ────────────────────────────────────────────────────────
+            const bool brakeOn = brakeCmd > 0.05f;
+            const bool reverseOn = v.direction() == PhysxVehicleEngineDrive::Direction::Reverse;
+            setEmissive(brakeMat_, brakeOn ? 6.f : (headlightsOn_ ? 1.4f : 0.25f));
+            setEmissive(reverseMat_, reverseOn ? 5.f : 0.0f);
+
+            // Indicators: ~1.5 Hz square-wave blink.
+            blinkPhase_ += dt;
+            if (blinkPhase_ > 1.f) blinkPhase_ -= 1.f;
+            const bool blinkOn = blinkPhase_ < 0.33f;
+            setEmissive(blinkerLMat_, (turnSignal < 0 && blinkOn) ? 6.f : 0.f);
+            setEmissive(blinkerRMat_, (turnSignal > 0 && blinkOn) ? 6.f : 0.f);
+        }
+
+    private:
+        // ── Body ──────────────────────────────────────────────────────────────
+        void buildBody() {
+            auto paintMat = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(cfg_.paint).metalness(0.55f).roughness(0.38f));
+            auto glassMat = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(Color(0x10141b)).metalness(0.2f).roughness(0.08f));
+            auto trimMat = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(Color(0x0a0a0a)).metalness(0.3f).roughness(0.6f));
+            auto chromeMat = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(Color(0xc8ccd0)).metalness(0.9f).roughness(0.22f));
+
+            const float W = cfg_.bodyWidth, H = cfg_.bodyHeight, L = cfg_.bodyLength;
+
+            // Lower body: the main mass, sitting around the chassis centre.
+            auto lower = Mesh::create(BoxGeometry::create(W, H * 0.5f, L * 0.96f), paintMat);
+            lower->position.y = -0.05f;
+            lower->castShadow = lower->receiveShadow = true;
+            root_->add(lower);
+
+            // Sill/rocker (darker) to break the slab and read as a separate volume.
+            auto sill = Mesh::create(BoxGeometry::create(W * 1.01f, H * 0.18f, L * 0.7f), trimMat);
+            sill->position.y = -H * 0.27f;
+            root_->add(sill);
+
+            // Bonnet + boot: thin slabs front and rear, a touch lower than the cabin.
+            auto bonnet = Mesh::create(BoxGeometry::create(W * 0.96f, H * 0.16f, L * 0.30f), paintMat);
+            bonnet->position.set(0.f, H * 0.22f, L * 0.30f);
+            bonnet->castShadow = true;
+            root_->add(bonnet);
+            auto boot = Mesh::create(BoxGeometry::create(W * 0.96f, H * 0.16f, L * 0.22f), paintMat);
+            boot->position.set(0.f, H * 0.22f, -L * 0.34f);
+            boot->castShadow = true;
+            root_->add(boot);
+
+            // Greenhouse / cabin: a narrower, taller glass box set back a little.
+            auto cabin = Mesh::create(BoxGeometry::create(W * 0.82f, H * 0.42f, L * 0.42f), glassMat);
+            cabin->position.set(0.f, H * 0.42f, -L * 0.02f);
+            cabin->castShadow = true;
+            root_->add(cabin);
+            // Roof cap (painted) on top of the glass.
+            auto roof = Mesh::create(BoxGeometry::create(W * 0.78f, H * 0.06f, L * 0.36f), paintMat);
+            roof->position.set(0.f, H * 0.63f, -L * 0.02f);
+            root_->add(roof);
+
+            // Bumpers.
+            auto fBumper = Mesh::create(BoxGeometry::create(W * 0.98f, H * 0.16f, L * 0.06f), trimMat);
+            fBumper->position.set(0.f, -H * 0.12f, L * 0.49f);
+            root_->add(fBumper);
+            auto rBumper = Mesh::create(BoxGeometry::create(W * 0.98f, H * 0.16f, L * 0.06f), trimMat);
+            rBumper->position.set(0.f, -H * 0.12f, -L * 0.49f);
+            root_->add(rBumper);
+
+            // Front grille trim.
+            auto grille = Mesh::create(BoxGeometry::create(W * 0.5f, H * 0.12f, 0.04f), chromeMat);
+            grille->position.set(0.f, 0.0f, L * 0.5f);
+            root_->add(grille);
+
+            // ── Emissive lamp lenses ──
+            const float lampZf = L * 0.49f;// front face
+            const float lampZr = -L * 0.49f;// rear face
+            const float lampX = W * 0.34f;
+
+            headlampMat_ = makeEmissive(Color(0xfff4d6), 0.4f);
+            addLens(headlampMat_, {+lampX, 0.05f, lampZf}, {0.34f, 0.20f, 0.05f});
+            addLens(headlampMat_, {-lampX, 0.05f, lampZf}, {0.34f, 0.20f, 0.05f});
+
+            brakeMat_ = makeEmissive(Color(0xff2a17), 0.25f);
+            addLens(brakeMat_, {+lampX, 0.08f, lampZr}, {0.40f, 0.16f, 0.05f});
+            addLens(brakeMat_, {-lampX, 0.08f, lampZr}, {0.40f, 0.16f, 0.05f});
+
+            reverseMat_ = makeEmissive(Color(0xf2f5ff), 0.0f);
+            addLens(reverseMat_, {+lampX * 0.45f, 0.05f, lampZr}, {0.16f, 0.10f, 0.05f});
+            addLens(reverseMat_, {-lampX * 0.45f, 0.05f, lampZr}, {0.16f, 0.10f, 0.05f});
+
+            blinkerLMat_ = makeEmissive(Color(0xff8a00), 0.0f);
+            blinkerRMat_ = makeEmissive(Color(0xff8a00), 0.0f);
+            // Left side (-X) front + rear; right side (+X) front + rear.
+            addLens(blinkerLMat_, {-W * 0.46f, -0.02f, lampZf * 0.97f}, {0.06f, 0.10f, 0.14f});
+            addLens(blinkerLMat_, {-W * 0.46f, -0.02f, lampZr * 0.97f}, {0.06f, 0.10f, 0.14f});
+            addLens(blinkerRMat_, {+W * 0.46f, -0.02f, lampZf * 0.97f}, {0.06f, 0.10f, 0.14f});
+            addLens(blinkerRMat_, {+W * 0.46f, -0.02f, lampZr * 0.97f}, {0.06f, 0.10f, 0.14f});
+        }
+
+        // ── Wheels ──────────────────────────────────────────────────────────────
+        void buildWheels() {
+            auto tyreMat = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(Color(0x0c0d0f)).metalness(0.f).roughness(0.92f));
+            auto rimMat = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(Color(0xb9bdc4)).metalness(0.85f).roughness(0.30f));
+            auto hubMat = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(Color(0x2a2d31)).metalness(0.7f).roughness(0.4f));
+
+            const float r = cfg_.wheelRadius;
+            const float hw = cfg_.wheelHalfWidth;
+
+            // Cylinder axis is Y by default; rotate so the wheel spins about local X
+            // (the vehicle's lateral axis), matching the wheel local pose convention.
+            auto tyreGeo = CylinderGeometry::create(r, r, hw * 2.f, 28);
+            tyreGeo->rotateZ(math::PI * 0.5f);
+            auto rimGeo = CylinderGeometry::create(r * 0.6f, r * 0.6f, hw * 2.04f, 18);
+            rimGeo->rotateZ(math::PI * 0.5f);
+            auto hubGeo = CylinderGeometry::create(r * 0.22f, r * 0.22f, hw * 2.1f, 10);
+            hubGeo->rotateZ(math::PI * 0.5f);
+
+            for (int i = 0; i < 4; ++i) {
+                auto rig = Group::create();
+                auto tyre = Mesh::create(tyreGeo, tyreMat);
+                tyre->castShadow = true;
+                auto rim = Mesh::create(rimGeo, rimMat);
+                auto hub = Mesh::create(hubGeo, hubMat);
+                // A couple of spoke bars so the wheel spin reads clearly.
+                for (int s = 0; s < 4; ++s) {
+                    auto spoke = Mesh::create(BoxGeometry::create(hw * 1.6f, r * 1.05f, r * 0.10f), rimMat);
+                    spoke->rotation.x = math::PI * 0.5f;// lay the bar across the wheel face
+                    spoke->rotation.y = 0.f;
+                    spoke->rotation.z = static_cast<float>(s) * math::PI * 0.25f;
+                    rim->add(spoke);
+                }
+                rig->add(tyre);
+                rig->add(rim);
+                rig->add(hub);
+                wheelRigs_[i] = rig;
+                root_->add(rig);
+            }
+        }
+
+        // ── Suspension struts (visible coil-overs) ───────────────────────────────
+        void buildStruts() {
+            auto springMat = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(Color(0xd24b2a)).metalness(0.6f).roughness(0.4f));
+            auto rodMat = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(Color(0x9aa0a8)).metalness(0.9f).roughness(0.25f));
+
+            const float halfTrack = cfg_.trackWidth * 0.5f;
+            const float halfBase = cfg_.wheelbase * 0.5f;
+            // Mount the top of each strut a little above the wheel's compressed rest
+            // height, near the chassis — the spring tower.
+            const float mountY = cfg_.suspensionAttachmentY + cfg_.suspensionTravelDist + 0.12f;
+            const Vector3 mounts[4] = {
+                    {+halfTrack, mountY, +halfBase},
+                    {-halfTrack, mountY, +halfBase},
+                    {+halfTrack, mountY, -halfBase},
+                    {-halfTrack, mountY, -halfBase},
+            };
+
+            const float coilR = cfg_.wheelRadius * 0.32f;
+            auto springGeo = makeCoilSpring(6.0f, coilR, coilR * 0.16f, 160, 6);
+            auto rodGeo = CylinderGeometry::create(coilR * 0.28f, coilR * 0.28f, 1.f, 8);
+            rodGeo->translate(0.f, 0.5f, 0.f);// base at y=0, tip at y=1 (matches spring)
+
+            for (int i = 0; i < 4; ++i) {
+                strutMount_[i] = mounts[i];
+                auto strut = Group::create();
+                strut->add(Mesh::create(springGeo, springMat));
+                strut->add(Mesh::create(rodGeo, rodMat));
+                struts_[i] = strut;
+                root_->add(strut);
+            }
+        }
+
+        // ── Lights ────────────────────────────────────────────────────────────
+        void buildLights() {
+            const float W = cfg_.bodyWidth, L = cfg_.bodyLength;
+            const float lampX = W * 0.34f;
+            const float lampZ = L * 0.49f;
+
+            for (int i = 0; i < 2; ++i) {
+                const float sx = (i == 0) ? +lampX : -lampX;
+                // SpotLight(color, intensity, distance, angle, penumbra, decay).
+                auto sl = SpotLight::create(Color(0xfff2d8), 0.f, 70.f,
+                                            math::degToRad(34.f), 0.45f, 1.4f);
+                sl->position.set(sx, 0.05f, lampZ);
+                sl->castShadow = false;// keep cheap; PT lights the cone regardless
+                // Aim forward (+Z) and slightly down via a target parented to the car.
+                auto tgt = Object3D::create();
+                tgt->position.set(sx, -0.5f, lampZ + 12.f);
+                root_->add(tgt);
+                sl->setTarget(*tgt);// target is owned by root_, outlives the light
+                root_->add(sl);
+                headlights_[i] = sl;
+            }
+            setHeadlights(false);
+        }
+
+        // ── small builders / helpers ─────────────────────────────────────────
+        std::shared_ptr<MeshStandardMaterial> makeEmissive(const Color& c, float intensity) {
+            auto m = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(Color(0x080808)).metalness(0.f).roughness(0.5f));
+            m->emissive = c;
+            m->emissiveIntensity = intensity;
+            return m;
+        }
+        static void setEmissive(const std::shared_ptr<MeshStandardMaterial>& m, float intensity) {
+            if (!m) return;
+            if (std::abs(m->emissiveIntensity - intensity) > 1e-3f) {
+                m->emissiveIntensity = intensity;
+                m->needsUpdate();
+            }
+        }
+        void addLens(const std::shared_ptr<MeshStandardMaterial>& mat,
+                     const Vector3& pos, const Vector3& size) {
+            auto lens = Mesh::create(BoxGeometry::create(size.x, size.y, size.z), mat);
+            lens->position.copy(pos);
+            root_->add(lens);
+        }
+
+        // Build a helical spring tube of unit height (y in [0,1]) so it can be scaled
+        // to the live strut length — the coils bunch up as the strut compresses.
+        static std::shared_ptr<BufferGeometry> makeCoilSpring(
+                float turns, float coilRadius, float wireRadius,
+                int tubularSegments, int radialSegments) {
+            std::vector<float> pos, nrm;
+            std::vector<unsigned int> idx;
+
+            const float twoPi = 6.28318530718f;
+            auto centre = [&](float t, Vector3& c, Vector3& tan) {
+                const float ang = t * turns * twoPi;
+                c.set(coilRadius * std::cos(ang), t, coilRadius * std::sin(ang));
+                // dC/dt
+                tan.set(-coilRadius * turns * twoPi * std::sin(ang), 1.f,
+                        coilRadius * turns * twoPi * std::cos(ang));
+                tan.normalize();
+            };
+
+            const Vector3 ref{0.f, 1.f, 0.f};
+            Vector3 c{}, tan{}, n{}, b{};
+            for (int i = 0; i <= tubularSegments; ++i) {
+                const float t = static_cast<float>(i) / static_cast<float>(tubularSegments);
+                centre(t, c, tan);
+                // Orthonormal ring frame perpendicular to the tangent.
+                n.copy(ref).cross(tan);
+                if (n.length() < 1e-4f) n.set(1.f, 0.f, 0.f);
+                n.normalize();
+                b.copy(tan).cross(n).normalize();
+                for (int j = 0; j <= radialSegments; ++j) {
+                    const float a = static_cast<float>(j) / static_cast<float>(radialSegments) * twoPi;
+                    const float ca = std::cos(a), sa = std::sin(a);
+                    Vector3 off(n.x * ca + b.x * sa, n.y * ca + b.y * sa, n.z * ca + b.z * sa);
+                    pos.push_back(c.x + off.x * wireRadius);
+                    pos.push_back(c.y + off.y * wireRadius);
+                    pos.push_back(c.z + off.z * wireRadius);
+                    nrm.push_back(off.x);
+                    nrm.push_back(off.y);
+                    nrm.push_back(off.z);
+                }
+            }
+            const int ring = radialSegments + 1;
+            for (int i = 0; i < tubularSegments; ++i) {
+                for (int j = 0; j < radialSegments; ++j) {
+                    const auto a = static_cast<unsigned int>(i * ring + j);
+                    const auto b2 = static_cast<unsigned int>((i + 1) * ring + j);
+                    idx.push_back(a);
+                    idx.push_back(b2);
+                    idx.push_back(a + 1);
+                    idx.push_back(a + 1);
+                    idx.push_back(b2);
+                    idx.push_back(b2 + 1);
+                }
+            }
+            auto geo = BufferGeometry::create();
+            geo->setIndex(idx);
+            geo->setAttribute("position", FloatBufferAttribute::create(pos, 3));
+            geo->setAttribute("normal", FloatBufferAttribute::create(nrm, 3));
+            return geo;
+        }
+
+        Config cfg_;
+        std::shared_ptr<Group> root_;
+        std::array<std::shared_ptr<Group>, 4> wheelRigs_{};
+        std::array<std::shared_ptr<Group>, 4> struts_{};
+        std::array<Vector3, 4> strutMount_{};
+
+        std::shared_ptr<MeshStandardMaterial> headlampMat_, brakeMat_, reverseMat_, blinkerLMat_, blinkerRMat_;
+        std::array<std::shared_ptr<SpotLight>, 2> headlights_{};
+        float headlightIntensity_ = 48.f;
+        bool headlightsOn_ = false;
+        float blinkPhase_ = 0.f;
+    };
+
+}// namespace drive
+
+#endif//THREEPP_DRIVE_CARRIG_HPP
diff --git a/examples/projects/Drive/DriveSounds.hpp b/examples/projects/Drive/DriveSounds.hpp
new file mode 100644
index 00000000..e7cdbda1
--- /dev/null
+++ b/examples/projects/Drive/DriveSounds.hpp
@@ -0,0 +1,209 @@
+
+#ifndef THREEPP_DRIVE_SOUNDS_HPP
+#define THREEPP_DRIVE_SOUNDS_HPP
+
+// Procedural audio for the engine-drive driving demo. Reuses the synthesis
+// toolkit (filters, WAV writer, road/wind/horn/reverse/thud/crash loops) from
+// the existing Vehicle example's VehicleSounds, and adds the one thing the
+// direct-drive demo couldn't do honestly: an ENGINE drone pitched by the real
+// PxVehicle2 engine speed. The engine loop is a band-limited buzz synthesised
+// once at idle pitch, then resampled per frame by (rpm / idleRpm) so the note
+// climbs and falls with the tacho — plus a clutch-slip flare on gear changes.
+
+#include "../Vehicle/VehicleSounds.hpp"// reuses threepp::vehiclesound::detail
+
+#include "threepp/extras/physx/PhysxVehicleEngineDrive.hpp"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <filesystem>
+#include <iostream>
+#include <memory>
+#include <vector>
+
+namespace drive {
+
+    using namespace threepp;
+
+    namespace detail {
+
+        // Band-limited engine buzz, loop-exact at f0 = 100 Hz over 0.2 s (20 cycles).
+        // A saw-ish stack of harmonics (uneven weights = lumpy combustion order) plus
+        // a touch of low-passed noise for grit. Pitched at runtime via playback rate.
+        inline std::vector<float> synthEngineLoop(int sr = 44100) {
+            namespace vd = threepp::vehiclesound::detail;
+            const float f0 = 100.f;
+            const float dur = 0.2f;
+            const int n = static_cast<int>(sr * dur);
+            const int extra = sr / 20;
+            std::mt19937 r(29);
+            auto rn = [&] { return std::uniform_real_distribution<float>(-1.f, 1.f)(r); };
+            vd::OnePole lp;
+            const float a = vd::lpAlpha(900.f, sr);
+            std::vector<float> s(n + extra);
+            // Per-harmonic weights — emphasise the low orders for a torquey idle.
+            const float w[8] = {1.0f, 0.85f, 0.5f, 0.62f, 0.3f, 0.22f, 0.16f, 0.1f};
+            for (int i = 0; i < n + extra; ++i) {
+                const float t = static_cast<float>(i) / sr;
+                float v = 0.f;
+                for (int k = 1; k <= 8; ++k)
+                    v += w[k - 1] * std::sin(2.f * math::PI * static_cast<float>(k) * f0 * t) / static_cast<float>(k);
+                v += lp(rn(), a) * 0.25f;// combustion grit
+                s[i] = v;
+            }
+            return vd::normalized(vd::loopable(s, n, extra), 0.6f);
+        }
+
+    }// namespace detail
+
+    // Owns every source and drives them from PxVehicle2 telemetry once per frame.
+    // Degrades to a no-op when no audio device is available.
+    struct DriveSounds {
+        std::unique_ptr<AudioListener> listener;
+        std::unique_ptr<Audio> road, wind, engine, reverseBeep, horn, thud, crash;
+        bool ok = false;
+
+        float rpmFraction() const { return rpmFrac_; }
+        float skidLevel() const { return skid_; }
+
+        void init() {
+            namespace vd = threepp::vehiclesound::detail;
+            try {
+                const auto dir = std::filesystem::temp_directory_path() / "threepp_drive_sounds";
+                std::filesystem::create_directories(dir);
+                auto wav = [&](const char* name, const std::vector<float>& s) {
+                    const auto p = dir / name;
+                    vd::writeWav(p, s);
+                    return p;
+                };
+                const auto roadPath = wav("road.wav", vd::synthRoadLoop());
+                const auto windPath = wav("wind.wav", vd::synthWindLoop());
+                const auto engPath = wav("engine.wav", detail::synthEngineLoop());
+                const auto revPath = wav("reverse.wav", vd::synthReverseLoop());
+                const auto hornPath = wav("horn.wav", vd::synthHornLoop());
+                const auto thudPath = wav("thud.wav", vd::synthThud());
+                const auto crashPath = wav("crash.wav", vd::synthCrash());
+
+                listener = std::make_unique<AudioListener>();
+                auto loop = [&](std::unique_ptr<Audio>& a, const std::filesystem::path& p) {
+                    a = std::make_unique<Audio>(*listener, p);
+                    a->setLooping(true);
+                    a->setVolume(0.f);
+                    a->play();
+                };
+                loop(road, roadPath);
+                loop(wind, windPath);
+                loop(engine, engPath);
+                loop(reverseBeep, revPath);
+                loop(horn, hornPath);
+                thud = std::make_unique<Audio>(*listener, thudPath);
+                crash = std::make_unique<Audio>(*listener, crashPath);
+                ok = true;
+            } catch (const std::exception& e) {
+                std::cerr << "[audio] disabled: " << e.what() << "\n";
+            }
+        }
+
+        void update(float dt, const PhysxVehicleEngineDrive& vehicle, float throttle,
+                    bool hornDown, const Camera& cam, float masterVolume) {
+            if (!ok || dt <= 0.f) return;
+            listener->setMasterVolume(masterVolume);
+
+            const auto& s = vehicle.settings();
+            const float speedAbs = std::abs(vehicle.forwardSpeed());
+
+            // ── Engine: pitch tracks real engine revs; volume blends idle bed +
+            //    load (throttle) + revs. A clutch-slip flare adds a moment of
+            //    flutter on gear changes.
+            const float rpm = vehicle.engineRpm();
+            rpmFrac_ += (vehicle.engineRpmFraction() - rpmFrac_) * (1.f - std::exp(-dt / 0.08f));
+            const float idle = std::max(vehicle.engineIdleRpm(), 1.f);
+            // Loop was synthesised at 100 Hz ≈ idle; map revs onto playback rate.
+            const float rate = std::clamp(rpm / idle, 0.5f, 7.f);
+            engine->setPlaybackRate(rate);
+            const float load = std::clamp(0.35f + 0.65f * throttle, 0.f, 1.f);
+            engine->setVolume((0.22f + 0.5f * rpmFrac_) * load * 0.9f);
+
+            // ── RPM/skid HUD telemetry.
+            float skidRaw = 0.f;
+            bool anyGrounded = false;
+            for (int i = 0; i < 4; ++i) {
+                if (!vehicle.wheelGrounded(i)) continue;
+                anyGrounded = true;
+                const float lng = std::max(0.f, std::abs(vehicle.tireLongitudinalSlip(i)) - 0.20f);
+                const float lat = std::max(0.f, std::abs(vehicle.tireLateralSlip(i)) - 0.12f);
+                skidRaw = std::max(skidRaw, lng * 1.2f + lat * 2.5f);
+            }
+            if (speedAbs < 1.5f) skidRaw = 0.f;
+            skidRaw = std::clamp(skidRaw, 0.f, 1.f);
+            const float skidTau = skidRaw > skid_ ? 0.06f : 0.22f;
+            skid_ += (skidRaw - skid_) * (1.f - std::exp(-dt / skidTau));
+
+            // ── Road rumble + wind.
+            const float roadNorm = std::clamp(speedAbs / 25.f, 0.f, 1.f);
+            road->setVolume(anyGrounded ? 0.5f * roadNorm : 0.f);
+            road->setPlaybackRate(0.8f + 0.5f * roadNorm);
+            const float windNorm = std::clamp(speedAbs / 45.f, 0.f, 1.f);
+            wind->setVolume(windNorm * windNorm * 0.8f);
+
+            // ── Suspension thuds on compression-rate spikes.
+            float worstJounce = 0.f;
+            for (int i = 0; i < 4; ++i) {
+                thudCooldown_[i] = std::max(0.f, thudCooldown_[i] - dt);
+                const float js = std::abs(vehicle.suspensionJounceSpeed(i));
+                if (vehicle.wheelGrounded(i) && js > 0.8f && thudCooldown_[i] <= 0.f) {
+                    worstJounce = std::max(worstJounce, js);
+                    thudCooldown_[i] = 0.20f;
+                }
+            }
+            if (worstJounce > 0.f) {
+                thud->setVolume(std::clamp(worstJounce / 3.f, 0.25f, 1.f) * 0.8f);
+                thudPitchFlip_ = !thudPitchFlip_;
+                thud->setPlaybackRate(thudPitchFlip_ ? 0.92f : 1.08f);
+                thud->seekToStart();
+                thud->play();
+            }
+
+            // ── Crash on chassis Δv spikes.
+            crashCooldown_ = std::max(0.f, crashCooldown_ - dt);
+            Vector3 vel;
+            {
+                const auto v = vehicle.chassisActor()->getLinearVelocity();
+                vel.set(v.x, v.y, v.z);
+            }
+            if (haveVel_) {
+                const float jerk = vel.distanceTo(prevVel_) / dt;
+                if (jerk > 60.f && crashCooldown_ <= 0.f) {
+                    crash->setVolume(std::clamp(jerk / 300.f, 0.3f, 1.f));
+                    crash->seekToStart();
+                    crash->play();
+                    crashCooldown_ = 0.5f;
+                }
+            }
+            prevVel_ = vel;
+            haveVel_ = true;
+
+            // ── Horn + reverse beeper.
+            horn->setVolume(hornDown ? 0.8f : 0.f);
+            const bool backing = vehicle.direction() == PhysxVehicleEngineDrive::Direction::Reverse && speedAbs > 0.3f;
+            reverseBeep->setVolume(backing ? 0.4f : 0.f);
+
+            listener->position.copy(cam.position);
+            listener->quaternion.copy(cam.quaternion);
+            listener->updateMatrixWorld(true);
+        }
+
+    private:
+        float rpmFrac_ = 0.f;
+        float skid_ = 0.f;
+        std::array<float, 4> thudCooldown_{};
+        float crashCooldown_ = 0.f;
+        Vector3 prevVel_;
+        bool haveVel_ = false;
+        bool thudPitchFlip_ = false;
+    };
+
+}// namespace drive
+
+#endif//THREEPP_DRIVE_SOUNDS_HPP
diff --git a/examples/projects/Drive/main.cpp b/examples/projects/Drive/main.cpp
new file mode 100644
index 00000000..68d940c5
--- /dev/null
+++ b/examples/projects/Drive/main.cpp
@@ -0,0 +1,849 @@
+// Procedural driving demo.
+//
+// A car designed from the ground up (CarRig.hpp — primitives, visible coil-over
+// shock absorbers, working lights) on the full PxVehicle2 engine-drive stack
+// (PhysxVehicleEngineDrive — engine + clutch + gearbox + autobox + differential),
+// driving a procedurally generated world: rolling terrain (TerrainGenerator) cut
+// through by a point-to-point road (RoadGenerator), lined with an instanced
+// forest, grass and wildflowers. Backend-flexible via createRenderer; looks best
+// on the Vulkan path tracer (aerial haze + real headlight cones at night).
+//
+// Controls:
+//   W / S      throttle / brake        A / D   steer
+//   SPACE      handbrake               R       toggle Drive / Reverse
+//   N          neutral                 T       auto / manual gearbox
+//   Q / E      shift down / up (manual)
+//   Z / C      left / right indicator  L       headlights
+//   H          horn                    F       day / night
+//   V          driver view             Backspace  respawn
+
+#include "threepp/threepp.hpp"
+
+#include "threepp/extras/imgui/ImguiContext.hpp"
+#include "threepp/extras/physx/PhysxDebugRenderer.hpp"
+#include "threepp/extras/physx/PhysxVehicleEngineDrive.hpp"
+#include "threepp/extras/physx/PhysxWorld.hpp"
+#include "threepp/extras/road/RoadGenerator.hpp"
+#include "threepp/extras/terrain/TerrainGenerator.hpp"
+#include "threepp/extras/vegetation/TreeGenerator.hpp"
+#include "threepp/extras/vegetation/TreeTextures.hpp"
+#include "threepp/loaders/RGBELoader.hpp"
+#include "threepp/textures/DataTexture.hpp"
+
+#include "CarRig.hpp"
+#include "DriveSounds.hpp"
+
+#ifdef THREEPP_WITH_VULKAN
+#include "threepp/renderers/VulkanRenderer.hpp"
+#endif
+
+#include <PxPhysicsAPI.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstdlib>
+#include <cstring>
+#include <iostream>
+#include <memory>
+#include <random>
+#include <string>
+#include <vector>
+
+using namespace threepp;
+using namespace ::physx;
+
+namespace {
+
+    // ── Vegetation prototypes (same recipe as the forest demo) ────────────────
+    struct TreeVariant {
+        std::shared_ptr<BufferGeometry> trunkGeo, leafGeo;
+        std::shared_ptr<MeshStandardMaterial> barkMat, leafMat;
+    };
+
+    TreeVariant makeVariant(int preset, unsigned int seed) {
+        vegetation::TreeParams tp;
+        vegetation::applyPreset(preset, tp);
+        tp.seed = seed;
+        if (preset == 2) {
+            tp.barkColor = {0.70f, 0.69f, 0.66f};
+            tp.leafDensity = 0.97f;
+            tp.leafClumping = 0.35f;
+        }
+        vegetation::TreeGenerator gen(seed);
+        gen.buildSkeleton(tp);
+        TreeVariant v;
+        v.trunkGeo = gen.makeTrunkGeometry(tp);
+        v.leafGeo = gen.makeLeafGeometry(tp);
+        auto bark = vegetation::makeBarkTextures(256, seed, tp.barkColor);
+        bark.first->repeat.set(3.f, 0.5f);
+        bark.second->repeat.set(3.f, 0.5f);
+        v.barkMat = MeshStandardMaterial::create(
+                MeshStandardMaterial::Params{}.color(Color::white).roughness(0.92f).metalness(0.f));
+        v.barkMat->map = bark.first;
+        v.barkMat->normalMap = bark.second;
+        v.leafMat = MeshStandardMaterial::create(
+                MeshStandardMaterial::Params{}.color(Color::white).roughness(0.85f).metalness(0.f));
+        v.leafMat->map = vegetation::makeLeafClusterTexture(256, seed, tp.leafColor);
+        v.leafMat->alphaTest = 0.5f;
+        v.leafMat->side = Side::Double;
+        v.leafMat->vertexColors = true;
+        return v;
+    }
+
+    std::shared_ptr<BufferGeometry> makeGrassBlade() {
+        constexpr int seg = 4;
+        constexpr float wBase = 0.05f;
+        const Vector3 bottom{0.06f, 0.13f, 0.04f};
+        const Vector3 top{0.20f, 0.34f, 0.11f};
+        std::vector<float> pos, nrm, uv, col;
+        std::vector<unsigned int> idx;
+        for (int i = 0; i <= seg; ++i) {
+            const float t = static_cast<float>(i) / seg;
+            const float y = t, w = wBase * (1.f - t);
+            const float r = bottom.x + (top.x - bottom.x) * t;
+            const float g = bottom.y + (top.y - bottom.y) * t;
+            const float b = bottom.z + (top.z - bottom.z) * t;
+            for (int s = 0; s < 2; ++s) {
+                pos.push_back(s == 0 ? -w : w);
+                pos.push_back(y);
+                pos.push_back(0.f);
+                nrm.push_back(0.f); nrm.push_back(0.85f); nrm.push_back(0.53f);
+                uv.push_back(s == 0 ? 0.f : 1.f); uv.push_back(t);
+                col.push_back(r); col.push_back(g); col.push_back(b);
+            }
+        }
+        for (int i = 0; i < seg; ++i) {
+            const auto a = static_cast<unsigned int>(i * 2);
+            const unsigned int b = a + 1, c = a + 2, d = a + 3;
+            idx.push_back(a); idx.push_back(b); idx.push_back(c);
+            idx.push_back(b); idx.push_back(d); idx.push_back(c);
+        }
+        auto geo = BufferGeometry::create();
+        geo->setIndex(idx);
+        geo->setAttribute("position", FloatBufferAttribute::create(pos, 3));
+        geo->setAttribute("normal", FloatBufferAttribute::create(nrm, 3));
+        geo->setAttribute("uv", FloatBufferAttribute::create(uv, 2));
+        geo->setAttribute("color", FloatBufferAttribute::create(col, 3));
+        return geo;
+    }
+
+    std::shared_ptr<BufferGeometry> makeFlowerCard() {
+        std::vector<float> pos, nrm, uv;
+        std::vector<unsigned int> idx;
+        const float hw = 0.5f;
+        const Vector3 up{0.f, 1.f, 0.f};
+        auto addQuad = [&](const Vector3& right, const Vector3& face) {
+            const auto base = static_cast<unsigned int>(pos.size() / 3);
+            Vector3 n;
+            n.copy(face).multiplyScalar(0.4f).add(up).normalize();
+            Vector3 c[4];
+            c[0].set(0.f, 0.f, 0.f).addScaledVector(right, -hw);
+            c[1].set(0.f, 0.f, 0.f).addScaledVector(right, hw);
+            c[2].set(0.f, 1.f, 0.f).addScaledVector(right, hw);
+            c[3].set(0.f, 1.f, 0.f).addScaledVector(right, -hw);
+            const float us[4] = {0.f, 1.f, 1.f, 0.f};
+            const float vs[4] = {0.f, 0.f, 1.f, 1.f};
+            for (int i = 0; i < 4; ++i) {
+                pos.push_back(c[i].x); pos.push_back(c[i].y); pos.push_back(c[i].z);
+                nrm.push_back(n.x); nrm.push_back(n.y); nrm.push_back(n.z);
+                uv.push_back(us[i]); uv.push_back(vs[i]);
+            }
+            idx.push_back(base); idx.push_back(base + 1); idx.push_back(base + 2);
+            idx.push_back(base); idx.push_back(base + 2); idx.push_back(base + 3);
+        };
+        addQuad(Vector3(1.f, 0.f, 0.f), Vector3(0.f, 0.f, 1.f));
+        addQuad(Vector3(0.f, 0.f, 1.f), Vector3(1.f, 0.f, 0.f));
+        auto geo = BufferGeometry::create();
+        geo->setIndex(idx);
+        geo->setAttribute("position", FloatBufferAttribute::create(pos, 3));
+        geo->setAttribute("normal", FloatBufferAttribute::create(nrm, 3));
+        geo->setAttribute("uv", FloatBufferAttribute::create(uv, 2));
+        return geo;
+    }
+
+    std::shared_ptr<BufferGeometry> makeRock(unsigned int seed) {
+        constexpr int latSegs = 5, lonSegs = 7;
+        constexpr float PI = 3.14159265358979f;
+        std::mt19937 rng(seed);
+        std::uniform_real_distribution<float> u(-PI, PI);
+        const float p1 = u(rng), p2 = u(rng), p3 = u(rng);
+        std::vector<float> pos, nrm, uv;
+        std::vector<unsigned int> idx;
+        for (int lat = 0; lat <= latSegs; ++lat) {
+            const float theta = static_cast<float>(lat) / latSegs * PI;
+            const float sinT = std::sin(theta), cosT = std::cos(theta);
+            for (int lon = 0; lon <= lonSegs; ++lon) {
+                const float phi = static_cast<float>(lon) / lonSegs * 2.f * PI;
+                const float nx = sinT * std::cos(phi), ny = cosT, nz = sinT * std::sin(phi);
+                float disp = 1.f + 0.30f * std::sin(2.f * phi + p1) * sinT +
+                             0.24f * std::cos(3.f * phi + p2) +
+                             0.22f * std::sin(3.f * theta + p3);
+                disp = std::clamp(disp, 0.6f, 1.5f);
+                pos.push_back(nx * disp); pos.push_back(ny * disp); pos.push_back(nz * disp);
+                nrm.push_back(nx); nrm.push_back(ny); nrm.push_back(nz);
+                uv.push_back(static_cast<float>(lon) / lonSegs);
+                uv.push_back(static_cast<float>(lat) / latSegs);
+            }
+        }
+        const int rowVerts = lonSegs + 1;
+        for (int lat = 0; lat < latSegs; ++lat)
+            for (int lon = 0; lon < lonSegs; ++lon) {
+                const auto a = static_cast<unsigned int>(lat * rowVerts + lon);
+                const auto b = static_cast<unsigned int>(a + rowVerts);
+                idx.push_back(a); idx.push_back(a + 1); idx.push_back(b);
+                idx.push_back(a + 1); idx.push_back(b + 1); idx.push_back(b);
+            }
+        auto geo = BufferGeometry::create();
+        geo->setIndex(idx);
+        geo->setAttribute("position", FloatBufferAttribute::create(pos, 3));
+        geo->setAttribute("normal", FloatBufferAttribute::create(nrm, 3));
+        geo->setAttribute("uv", FloatBufferAttribute::create(uv, 2));
+        return geo;
+    }
+
+    float smooth01(float e0, float e1, float x) {
+        const float t = std::clamp((x - e0) / (e1 - e0), 0.f, 1.f);
+        return t * t * (3.f - 2.f * t);
+    }
+
+}// namespace
+
+int main(int argc, char** argv) {
+
+    // Headless capture: `drive --shot out.png [--frames N] [--night]` auto-drives
+    // for N frames, writes one PNG, and exits. Used for verification screenshots.
+    std::string shotPath;
+    int shotFrames = 200;
+    bool shotNight = false;
+    for (int i = 1; i < argc; ++i) {
+        if (std::strcmp(argv[i], "--shot") == 0 && i + 1 < argc) shotPath = argv[++i];
+        else if (std::strcmp(argv[i], "--frames") == 0 && i + 1 < argc) shotFrames = std::atoi(argv[++i]);
+        else if (std::strcmp(argv[i], "--night") == 0) shotNight = true;
+    }
+    const bool capturing = !shotPath.empty();
+    int shotFrame = 0;
+
+    Canvas canvas("Procedural Drive", {{"vsync", true}, {"aa", 4}});
+    auto renderer = createRenderer(canvas);
+
+    bool vulkanBackend = false;
+#ifdef THREEPP_WITH_VULKAN
+    auto* vk = dynamic_cast<VulkanRenderer*>(renderer.get());
+    if (vk) {
+        vulkanBackend = true;
+        vk->setRenderScale(0.8f);
+    }
+#endif
+    const bool isGL = !vulkanBackend && dynamic_cast<GLRenderer*>(renderer.get()) != nullptr;
+
+    renderer->setClearColor(Color(0.62f, 0.72f, 0.84f));
+    renderer->toneMapping = ToneMapping::ACESFilmic;
+    renderer->toneMappingExposure = 1.0f;
+    renderer->shadowMap().enabled = true;
+    renderer->shadowMap().type = ShadowMap::PFCSoft;
+
+    auto scene = Scene::create();
+
+    // ── Sky + sun ─────────────────────────────────────────────────────────
+    RGBELoader hdrLoader;
+    std::shared_ptr<Texture> hdr =
+            hdrLoader.load(std::string(DATA_FOLDER) + "/textures/env/autumn_field_puresky_2k.hdr");
+    if (hdr) {
+        scene->background = hdr;
+        scene->environment = hdr;
+    }
+
+    auto sun = DirectionalLight::create(Color(1.0f, 0.97f, 0.90f), 2.8f);
+    sun->position.set(180.f, 220.f, 120.f);
+    sun->castShadow = true;
+    {
+        auto* cam = sun->shadow->camera->as<OrthographicCamera>();
+        cam->left = cam->bottom = -120.f;
+        cam->right = cam->top = 120.f;
+        cam->nearPlane = 1.f;
+        cam->farPlane = 700.f;
+        sun->shadow->mapSize.set(4096, 4096);
+        sun->shadow->bias = -0.0005f;
+    }
+    scene->add(sun);
+
+    auto ambient = AmbientLight::create(Color::white, 0.25f);
+    if (!vulkanBackend) scene->add(ambient);
+
+    // ── Physics ───────────────────────────────────────────────────────────
+    PhysxWorld world;
+
+    // ── Terrain ───────────────────────────────────────────────────────────
+    terrain::TerrainParams terr;
+    terr.seed = 4242u;
+    terr.worldSize = 620.f;
+    terr.resolution = 240;
+    terr.noiseType = terrain::NoiseType::fBm;// no erosion => heightAt matches mesh
+    terr.featureScale = 260.f;
+    terr.octaves = 6;
+    terr.amplitude = 26.f;
+    terr.warp = 0.3f;
+    terr.heightExponent = 1.0f;
+    terr.erosion = terrain::ErosionType::None;
+    terr.grassColor = {0.26f, 0.33f, 0.16f};
+    terr.screeColor = {0.45f, 0.42f, 0.34f};
+    terr.rockColor = {0.40f, 0.37f, 0.33f};
+    terr.snowLine = 3.0f;// effectively no snow
+    terr.slopeGrassMax = 0.5f;
+
+    terrain::TerrainGenerator terrainGen(terr.seed);
+    terrainGen.buildField(terr);// populate field for heightAt + splat bake
+
+    // ── Road: a point-to-point route wandering across the terrain ──────────
+    road::RoadParams roadParams;
+    roadParams.laneWidth = 3.4f;
+    roadParams.laneCount = 2;
+    roadParams.shoulderWidth = 2.6f;
+    roadParams.surfaceRaise = 0.12f;
+    roadParams.maxBanking = 0.03f;// keep < raise/pavedHalf so curves don't poke terrain
+    roadParams.samplesPerSegment = 26;
+
+    std::vector<Vector3> roadPoints;
+    {
+        const float half = terr.worldSize * 0.5f * 0.82f;
+        const Vector3 a(-half, 0.f, -half * 0.85f);
+        const Vector3 b(half, 0.f, half * 0.75f);
+        const int N = 7;
+        // Perpendicular to the a→b direction, in XZ.
+        Vector3 dir = b.clone().sub(a);
+        dir.y = 0.f;
+        dir.normalize();
+        const Vector3 perp(-dir.z, 0.f, dir.x);
+        std::mt19937 rng(7u);
+        std::uniform_real_distribution<float> j(-1.f, 1.f);
+        for (int i = 0; i < N; ++i) {
+            const float t = static_cast<float>(i) / static_cast<float>(N - 1);
+            Vector3 base = a.clone().lerp(b, t);
+            const float wander = std::sin(t * math::PI * 1.7f) * (terr.worldSize * 0.14f) +
+                                 j(rng) * (terr.worldSize * 0.04f);
+            base.add(perp.clone().multiplyScalar(wander));
+            roadPoints.push_back(base);
+        }
+    }
+
+    road::RoadGenerator roadGen(roadPoints, roadParams);
+    roadGen.conformTo([&](float x, float z) { return terrainGen.heightAt(x, z, terr); }, 16);
+
+    const float corridorHalf = roadGen.corridorHalfWidth();
+    const float flattenMargin = 8.f;
+    // Unified ground height: flatten the full road corridor to the road
+    // elevation, then grade back to natural terrain over `flattenMargin`.
+    auto groundHeight = [&](float x, float z, float th) {
+        const float d = roadGen.distanceToCenter(x, z);
+        if (d >= corridorHalf + flattenMargin) return th;
+        const float ch = roadGen.centerHeightAt(x, z);
+        const float w = 1.f - smooth01(corridorHalf, corridorHalf + flattenMargin, d);
+        return th + (ch - th) * w;
+    };
+    // Placement height = ground (terrain blended into the road corridor).
+    auto gh = [&](float x, float z) { return groundHeight(x, z, terrainGen.heightAt(x, z, terr)); };
+    // A degenerate (zero-scale) matrix to hide unused instances off-screen.
+    Matrix4 hiddenMatrix;
+    hiddenMatrix.compose(Vector3(0.f, -9999.f, 0.f), Quaternion(), Vector3(0.f, 0.f, 0.f));
+
+    // Terrain mesh, displaced by the unified ground height.
+    auto terrainMat = MeshStandardMaterial::create(
+            MeshStandardMaterial::Params{}.color(Color::white).roughness(0.97f).metalness(0.f));
+    std::shared_ptr<BufferGeometry> terrainGeo =
+            PlaneGeometry::create(terr.worldSize, terr.worldSize,
+                                  static_cast<unsigned int>(terr.resolution),
+                                  static_cast<unsigned int>(terr.resolution));
+    terrainGeo->rotateX(-math::PI * 0.5f);
+    {
+        auto* pos = terrainGeo->getAttribute<float>("position");
+        auto& a = pos->array();
+        for (int i = 0; i < pos->count(); ++i) {
+            const float x = a[i * 3 + 0], z = a[i * 3 + 2];
+            a[i * 3 + 1] = groundHeight(x, z, terrainGen.heightAt(x, z, terr));
+        }
+        pos->needsUpdate();
+        terrainGeo->computeVertexNormals();
+        terrainGeo->computeBoundingBox();
+        terrainGeo->computeBoundingSphere();
+    }
+    {
+        auto tex = DataTexture::create(ImageData{terrainGen.bakeSplatColors(terr)},
+                                       static_cast<unsigned int>(terrainGen.dim()),
+                                       static_cast<unsigned int>(terrainGen.dim()));
+        tex->colorSpace = ColorSpace::sRGB;
+        tex->magFilter = Filter::Linear;
+        tex->minFilter = Filter::Linear;
+        terrainMat->map = tex;
+    }
+    auto terrainMesh = Mesh::create(terrainGeo, terrainMat);
+    terrainMesh->receiveShadow = true;
+    scene->add(terrainMesh);
+    world.addStaticTrimesh(*terrainGeo);// drivable collider
+
+    // ── Road surface ───────────────────────────────────────────────────────
+    auto roadGeo = roadGen.buildSurface();
+    auto roadMat = MeshStandardMaterial::create(
+            MeshStandardMaterial::Params{}.color(Color::white).roughness(0.92f).metalness(0.f));
+    {
+        const int rw = 128, rh = 256;
+        auto tex = DataTexture::create(ImageData{roadGen.bakeSurfaceTexture(rw, rh)},
+                                       static_cast<unsigned int>(rw), static_cast<unsigned int>(rh));
+        tex->colorSpace = ColorSpace::sRGB;
+        tex->magFilter = Filter::Linear;
+        tex->minFilter = Filter::Linear;
+        tex->wrapS = TextureWrapping::ClampToEdge;
+        tex->wrapT = TextureWrapping::Repeat;// road tiles along its length
+        roadMat->map = tex;
+    }
+    auto roadMesh = Mesh::create(roadGeo, roadMat);
+    roadMesh->receiveShadow = true;
+    scene->add(roadMesh);
+    world.addStaticTrimesh(*roadGeo);
+
+    // ── Vehicle (engine drive) ──────────────────────────────────────────────
+    PhysxVehicleEngineDrive::Settings vs;
+    vs.chassisWidth = 1.9f;
+    vs.chassisHeight = 1.3f;
+    vs.chassisLength = 4.4f;
+    vs.wheelRadius = 0.36f;
+    vs.wheelHalfWidth = 0.16f;
+    vs.trackWidth = 1.66f;
+    vs.wheelbase = 2.7f;
+    vs.suspensionAttachmentY = -0.35f;
+    vs.suspensionTravelDist = 0.32f;
+    {
+        const Vector3 startP = roadGen.startPoint();
+        Vector3 fwd = roadGen.startForward();
+        vs.spawnPosition = {startP.x, startP.y + 1.4f, startP.z};
+        Quaternion q;
+        q.setFromUnitVectors(Vector3(0.f, 0.f, 1.f), fwd);
+        vs.spawnRotation = q;
+    }
+    PhysxVehicleEngineDrive vehicle(world, vs);
+
+    drive::CarRig::Config carCfg;
+    carCfg.bodyWidth = vs.chassisWidth;
+    carCfg.bodyHeight = vs.chassisHeight;
+    carCfg.bodyLength = vs.chassisLength;
+    carCfg.wheelRadius = vs.wheelRadius;
+    carCfg.wheelHalfWidth = vs.wheelHalfWidth;
+    carCfg.trackWidth = vs.trackWidth;
+    carCfg.wheelbase = vs.wheelbase;
+    carCfg.suspensionAttachmentY = vs.suspensionAttachmentY;
+    carCfg.suspensionTravelDist = vs.suspensionTravelDist;
+    auto carRig = std::make_unique<drive::CarRig>(carCfg);
+    scene->add(carRig->root());
+    world.bind(*carRig->root(), *vehicle.chassisActor());
+
+    // Driver POV camera, parented to the car body.
+    auto povCamera = PerspectiveCamera::create(72.f, canvas.aspect(), 0.05f, 2000.f);
+    povCamera->position.set(0.34f, 0.55f, -0.15f);
+    povCamera->rotation.y = math::PI;// car forward is +Z; flip to look ahead
+    carRig->root()->add(povCamera);
+
+    auto physxDebug = std::make_shared<PhysxDebugRenderer>(world);
+    physxDebug->enableDefaults();
+    physxDebug->visible = false;
+    scene->add(physxDebug);
+
+    // ── Scatter: forest over the terrain, minus the road corridor ───────────
+    auto slopeNy = [&](float x, float z) {
+        const float e = 1.5f;
+        const float hx = terrainGen.heightAt(x + e, z, terr) - terrainGen.heightAt(x - e, z, terr);
+        const float hz = terrainGen.heightAt(x, z + e, terr) - terrainGen.heightAt(x, z - e, terr);
+        return (2.f * e) / std::sqrt(hx * hx + hz * hz + (2.f * e) * (2.f * e));
+    };
+    const float treeClear = corridorHalf + 5.f;// keep trunks off the verge
+
+    std::vector<TreeVariant> variants{
+            makeVariant(0, 101u), makeVariant(0, 202u),
+            makeVariant(1, 303u), makeVariant(1, 505u), makeVariant(2, 404u)};
+    {
+        const float half = terr.worldSize * 0.5f * 0.94f;
+        const float spacing = 13.f;
+        const int cells = std::max(1, static_cast<int>((2.f * half) / spacing));
+        std::vector<std::vector<Matrix4>> xf(variants.size());
+        std::mt19937 rng(1u);
+        std::uniform_real_distribution<float> u01(0.f, 1.f);
+        Quaternion q;
+        const Vector3 up{0.f, 1.f, 0.f};
+        for (int cz = 0; cz < cells; ++cz)
+            for (int cx = 0; cx < cells; ++cx) {
+                if (u01(rng) > 0.72f) continue;
+                const float jx = (u01(rng) - 0.5f) * spacing * 0.8f;
+                const float jz = (u01(rng) - 0.5f) * spacing * 0.8f;
+                const float x = -half + (cx + 0.5f) * (2.f * half / cells) + jx;
+                const float z = -half + (cz + 0.5f) * (2.f * half / cells) + jz;
+                if (roadGen.distanceToCenter(x, z) < treeClear) continue;
+                if (slopeNy(x, z) < 0.86f) continue;
+                const size_t vi = static_cast<size_t>(u01(rng) * variants.size()) % variants.size();
+                const float s = 1.1f + u01(rng) * 1.1f;
+                q.setFromAxisAngle(up, u01(rng) * 6.2831853f);
+                const float gy = gh(x, z);
+                Matrix4 m;
+                m.compose(Vector3(x, gy - 0.2f, z), q, Vector3(s, s, s));
+                xf[vi].push_back(m);
+                // Trunk collider (tall thin box rising from the ground) so the
+                // car bumps into trees instead of driving through them.
+                world.addStatic(PxBoxGeometry(0.22f * s, 1.5f * s, 0.22f * s),
+                                toPxTransform(Vector3(x, gy + 1.5f * s - 0.2f, z)));
+            }
+        for (size_t vi = 0; vi < variants.size(); ++vi) {
+            if (xf[vi].empty()) continue;
+            auto trunks = InstancedMesh::create(variants[vi].trunkGeo, variants[vi].barkMat, xf[vi].size());
+            auto leaves = InstancedMesh::create(variants[vi].leafGeo, variants[vi].leafMat, xf[vi].size());
+            trunks->castShadow = trunks->receiveShadow = true;
+            leaves->castShadow = true;
+            for (size_t i = 0; i < xf[vi].size(); ++i) {
+                trunks->setMatrixAt(i, xf[vi][i]);
+                leaves->setMatrixAt(i, xf[vi][i]);
+            }
+            trunks->instanceMatrix()->needsUpdate();
+            leaves->instanceMatrix()->needsUpdate();
+            scene->add(trunks);
+            scene->add(leaves);
+        }
+    }
+
+    // ── Grass + wildflowers, banded along the road (cheap, lines the route) ──
+    const auto& centerline = roadGen.centerlineSamples();
+    auto scatterAlongRoad = [&](int count, unsigned seed, float bandInner, float bandOuter,
+                                const std::function<void(float, float, float)>& place) {
+        std::mt19937 rng(seed);
+        std::uniform_real_distribution<float> u01(0.f, 1.f);
+        if (centerline.size() < 2) return;
+        for (int i = 0; i < count; ++i) {
+            const size_t si = static_cast<size_t>(u01(rng) * (centerline.size() - 1));
+            const Vector3& c = centerline[si];
+            const float side = (u01(rng) < 0.5f) ? -1.f : 1.f;
+            const float dist = bandInner + u01(rng) * (bandOuter - bandInner);
+            // Local perpendicular from the polyline segment.
+            const Vector3& c2 = centerline[std::min(si + 1, centerline.size() - 1)];
+            Vector3 t = c2.clone().sub(c);
+            t.y = 0.f;
+            if (t.length() < 1e-4f) t = Vector3(0.f, 0.f, 1.f);
+            t.normalize();
+            const float px = c.x - t.z * side * dist;
+            const float pz = c.z + t.x * side * dist;
+            place(px, pz, gh(px, pz));
+        }
+    };
+
+    {
+        auto grassMat = MeshStandardMaterial::create(
+                MeshStandardMaterial::Params{}.color(Color::white).roughness(0.97f).metalness(0.f));
+        grassMat->vertexColors = true;
+        grassMat->side = Side::Double;
+        grassMat->envMapIntensity = 0.45f;
+        const int bladeCount = vulkanBackend ? 14000 : 42000;
+        auto grass = InstancedMesh::create(makeGrassBlade(), grassMat, static_cast<size_t>(bladeCount));
+        std::mt19937 rng(7u);
+        std::uniform_real_distribution<float> u01(0.f, 1.f);
+        const Vector3 up{0.f, 1.f, 0.f};
+        Quaternion q;
+        Matrix4 m;
+        int idx = 0;
+        scatterAlongRoad(bladeCount, 7u, corridorHalf + 0.3f, corridorHalf + 22.f,
+                         [&](float x, float z, float h) {
+                             if (idx >= bladeCount) return;
+                             const float s = 0.5f + u01(rng) * 0.5f;
+                             const float hgt = 0.3f + u01(rng) * 0.4f;
+                             q.setFromAxisAngle(up, u01(rng) * 6.2831853f);
+                             m.compose(Vector3(x, h - 0.05f, z), q, Vector3(s, hgt, s));
+                             grass->setMatrixAt(static_cast<size_t>(idx++), m);
+                         });
+        for (; idx < bladeCount; ++idx) grass->setMatrixAt(static_cast<size_t>(idx), hiddenMatrix);
+        grass->instanceMatrix()->needsUpdate();
+        scene->add(grass);
+    }
+
+    {
+        const int perVariant = vulkanBackend ? 500 : 1100;
+        const Vector3 up{0.f, 1.f, 0.f};
+        for (int fv = 0; fv < 3; ++fv) {
+            auto mat = MeshStandardMaterial::create(
+                    MeshStandardMaterial::Params{}.color(Color::white).roughness(0.9f).metalness(0.f));
+            mat->map = vegetation::makeFlowerTexture(128, static_cast<unsigned int>(1 + fv));
+            mat->alphaTest = 0.5f;
+            mat->side = Side::Double;
+            mat->envMapIntensity = 0.6f;
+            auto fm = InstancedMesh::create(makeFlowerCard(), mat, static_cast<size_t>(perVariant));
+            std::mt19937 rng(static_cast<unsigned>(200 + fv));
+            std::uniform_real_distribution<float> u01(0.f, 1.f);
+            Quaternion q;
+            Matrix4 m;
+            int idx = 0;
+            scatterAlongRoad(perVariant, static_cast<unsigned>(200 + fv), corridorHalf + 0.5f, corridorHalf + 18.f,
+                             [&](float x, float z, float h) {
+                                 if (idx >= perVariant) return;
+                                 const float s = 0.25f + u01(rng) * 0.25f;
+                                 q.setFromAxisAngle(up, u01(rng) * 6.2831853f);
+                                 m.compose(Vector3(x, h - 0.03f, z), q, Vector3(s, s * (1.f + u01(rng) * 0.6f), s));
+                                 fm->setMatrixAt(static_cast<size_t>(idx++), m);
+                             });
+            for (; idx < perVariant; ++idx) fm->setMatrixAt(static_cast<size_t>(idx), hiddenMatrix);
+            fm->instanceMatrix()->needsUpdate();
+            scene->add(fm);
+        }
+    }
+
+    // ── Rocks ───────────────────────────────────────────────────────────────
+    {
+        auto rockMat = MeshStandardMaterial::create(
+                MeshStandardMaterial::Params{}.color(Color(0.30f, 0.28f, 0.25f)).roughness(1.f).metalness(0.f));
+        rockMat->flatShading = true;
+        rockMat->envMapIntensity = 0.3f;
+        std::vector<std::shared_ptr<BufferGeometry>> rgeos{makeRock(1u), makeRock(2u), makeRock(3u)};
+        std::vector<std::vector<Matrix4>> xf(rgeos.size());
+        std::mt19937 rng(99u);
+        std::uniform_real_distribution<float> u01(0.f, 1.f);
+        const float half = terr.worldSize * 0.5f * 0.9f;
+        Quaternion q;
+        Vector3 axis;
+        Matrix4 m;
+        for (int i = 0; i < 120; ++i) {
+            const float x = (u01(rng) - 0.5f) * 2.f * half;
+            const float z = (u01(rng) - 0.5f) * 2.f * half;
+            if (roadGen.distanceToCenter(x, z) < corridorHalf + 1.5f) continue;
+            const float sc = 0.5f + u01(rng) * 1.6f;
+            const float gy = gh(x, z);
+            axis.set(u01(rng) - 0.5f, u01(rng) - 0.5f, u01(rng) - 0.5f).normalize();
+            q.setFromAxisAngle(axis, u01(rng) * 6.2831853f);
+            m.compose(Vector3(x, gy - sc * 0.25f, z), q,
+                      Vector3(sc, sc * (0.75f + u01(rng) * 0.35f), sc));
+            xf[static_cast<size_t>(u01(rng) * rgeos.size()) % rgeos.size()].push_back(m);
+            // Boulder collider — a sphere the car hits (big rocks block, small ride over).
+            world.addStatic(PxSphereGeometry(sc * 0.72f), toPxTransform(Vector3(x, gy - sc * 0.05f, z)));
+        }
+        for (size_t gi = 0; gi < rgeos.size(); ++gi) {
+            if (xf[gi].empty()) continue;
+            auto rocks = InstancedMesh::create(rgeos[gi], rockMat, xf[gi].size());
+            rocks->castShadow = rocks->receiveShadow = true;
+            for (size_t i = 0; i < xf[gi].size(); ++i) rocks->setMatrixAt(i, xf[gi][i]);
+            rocks->instanceMatrix()->needsUpdate();
+            scene->add(rocks);
+        }
+    }
+
+    // ── Fog ─────────────────────────────────────────────────────────────────
+    Color dayFog(0.66f, 0.75f, 0.86f);
+    Color nightFog(0.04f, 0.05f, 0.09f);
+    scene->fog = Fog(dayFog, terr.worldSize * 0.3f, terr.worldSize * 0.95f);
+
+    // ── Cameras ─────────────────────────────────────────────────────────────
+    auto camera = PerspectiveCamera::create(60.f, canvas.aspect(), 0.1f, 2000.f);
+    camera->position.set(0, 6, -12);
+
+    // ── Audio ───────────────────────────────────────────────────────────────
+    drive::DriveSounds sounds;
+    sounds.init();
+    bool audioOn = true;
+    float audioVol = 0.7f;
+
+    // ── Input state ─────────────────────────────────────────────────────────
+    bool throttleDown = false, brakeDown = false, handbrakeDown = false;
+    bool steerLeftDown = false, steerRightDown = false;
+    bool hornDown = false, driverView = false, respawn = false, night = shotNight;
+    int turnSignal = 0;// -1 left, 0 none, +1 right
+
+    auto keyToggle = [&](Key key, bool down) {
+        switch (key) {
+            case Key::W: case Key::UP: throttleDown = down; break;
+            case Key::S: case Key::DOWN: brakeDown = down; break;
+            case Key::A: case Key::LEFT: steerLeftDown = down; break;
+            case Key::D: case Key::RIGHT: steerRightDown = down; break;
+            case Key::SPACE: handbrakeDown = down; break;
+            case Key::H: hornDown = down; break;
+            default: break;
+        }
+    };
+
+    KeyAdapter pressAdapter(KeyAdapter::KEY_PRESSED, [&](KeyEvent evt) {
+        if (ImGui::GetIO().WantCaptureKeyboard) return;
+        switch (evt.key) {
+            case Key::R:
+                vehicle.setDirection(vehicle.direction() == PhysxVehicleEngineDrive::Direction::Reverse
+                                             ? PhysxVehicleEngineDrive::Direction::Drive
+                                             : PhysxVehicleEngineDrive::Direction::Reverse);
+                break;
+            case Key::N: vehicle.setDirection(PhysxVehicleEngineDrive::Direction::Neutral); break;
+            case Key::T:
+                vehicle.setTransmissionMode(
+                        vehicle.transmissionMode() == PhysxVehicleEngineDrive::TransmissionMode::Automatic
+                                ? PhysxVehicleEngineDrive::TransmissionMode::Manual
+                                : PhysxVehicleEngineDrive::TransmissionMode::Automatic);
+                break;
+            case Key::E: vehicle.shiftUp(); break;
+            case Key::Q: vehicle.shiftDown(); break;
+            case Key::L: carRig->setHeadlights(!carRig->headlightsOn()); break;
+            case Key::Z: turnSignal = (turnSignal == -1) ? 0 : -1; break;
+            case Key::C: turnSignal = (turnSignal == 1) ? 0 : 1; break;
+            case Key::V: driverView = !driverView; break;
+            case Key::F: night = !night; break;
+            case Key::BACKSPACE: respawn = true; break;
+            default: break;
+        }
+        keyToggle(evt.key, true);
+    });
+    KeyAdapter releaseAdapter(KeyAdapter::KEY_RELEASED, [&](KeyEvent evt) { keyToggle(evt.key, false); });
+    canvas.addKeyListener(pressAdapter);
+    canvas.addKeyListener(releaseAdapter);
+
+    IOCapture capture{};
+    capture.preventMouseEvent = [] { return ImGui::GetIO().WantCaptureMouse; };
+    capture.preventKeyboardEvent = [] { return ImGui::GetIO().WantCaptureKeyboard; };
+    canvas.setIOCapture(&capture);
+
+    // ── HUD ─────────────────────────────────────────────────────────────────
+    float steerCmd = 0.f, throttleCmd = 0.f, brakeCmd = 0.f;
+    float fps = 0.f, fpsAccum = 0.f;
+    int fpsFrames = 0;
+    ImguiFunctionalContext ui(canvas, *renderer, [&] {
+        const float w = 290 * ui.dpiScale();
+        ImGui::SetNextWindowPos({static_cast<float>(canvas.size().width()) - w, 0}, 0, {0, 0});
+        ImGui::SetNextWindowSize({w, 0}, 0);
+        ImGui::Begin("Procedural Drive");
+        ImGui::Text("W/S throttle/brake  A/D steer");
+        ImGui::Text("R Drive/Rev  N neutral  SPACE handbrake");
+        ImGui::Text("T auto/manual  Q/E shift  L lights");
+        ImGui::Text("Z/C blinkers  H horn  F day/night  V POV");
+        ImGui::Separator();
+        ImGui::Text("FPS   : %.0f", fps);
+        ImGui::Text("Speed : %.0f km/h", std::abs(vehicle.forwardSpeed()) * 3.6f);
+        ImGui::Text("Gear  : %s   Engine: %.0f rpm", vehicle.gearLabel().c_str(), vehicle.engineRpm());
+        const char* dirTxt = vehicle.direction() == PhysxVehicleEngineDrive::Direction::Drive ? "DRIVE"
+                             : vehicle.direction() == PhysxVehicleEngineDrive::Direction::Reverse ? "REVERSE"
+                                                                                                  : "NEUTRAL";
+        ImGui::Text("Mode  : %s  %s", dirTxt,
+                    vehicle.transmissionMode() == PhysxVehicleEngineDrive::TransmissionMode::Automatic ? "(auto)" : "(manual)");
+        ImGui::ProgressBar(vehicle.engineRpmFraction(), {-1, 0}, "RPM");
+        ImGui::ProgressBar(throttleCmd, {-1, 0}, "Throttle");
+        ImGui::ProgressBar(brakeCmd, {-1, 0}, "Brake");
+        ImGui::Separator();
+        ImGui::Checkbox("PhysX debug", &physxDebug->visible);
+        if (sounds.ok) {
+            ImGui::Checkbox("Audio", &audioOn);
+            ImGui::SliderFloat("Volume", &audioVol, 0.f, 1.f, "%.2f");
+        }
+        ImGui::End();
+    });
+
+    canvas.onWindowResize([&](WindowSize size) {
+        camera->aspect = size.aspect();
+        camera->updateProjectionMatrix();
+        povCamera->aspect = size.aspect();
+        povCamera->updateProjectionMatrix();
+        renderer->setSize(size);
+    });
+
+    // ── Chase camera state ──────────────────────────────────────────────────
+    Vector3 camPos{0, 6, -12}, camTarget{0, 1, 0};
+
+    bool prevNight = false;
+    auto applyDayNight = [&] {
+        if (night) {
+            sun->intensity = 0.18f;
+            sun->color = Color(0.5f, 0.6f, 0.85f);
+            if (ambient) ambient->intensity = 0.05f;
+            scene->background = nightFog;
+            if (scene->fog) std::get<Fog>(*scene->fog) = Fog(nightFog, terr.worldSize * 0.18f, terr.worldSize * 0.7f);
+            carRig->setHeadlights(true);
+        } else {
+            sun->intensity = 2.8f;
+            sun->color = Color(1.0f, 0.97f, 0.90f);
+            if (ambient) ambient->intensity = 0.25f;
+            if (hdr) scene->background = hdr; else scene->background = dayFog;
+            if (scene->fog) std::get<Fog>(*scene->fog) = Fog(dayFog, terr.worldSize * 0.3f, terr.worldSize * 0.95f);
+        }
+    };
+
+    Clock clock;
+    canvas.animate([&] {
+        const float dt = clock.getDelta();
+
+        fpsAccum += dt;
+        if (++fpsFrames >= 30 || fpsAccum >= 0.5f) {
+            fps = static_cast<float>(fpsFrames) / std::max(fpsAccum, 1e-4f);
+            fpsAccum = 0.f;
+            fpsFrames = 0;
+        }
+
+        if (night != prevNight) {
+            applyDayNight();
+            prevNight = night;
+        }
+
+        // Headless capture auto-drives forward so the shot shows the car rolling.
+        if (capturing) {
+            throttleDown = true;
+            if (shotNight) carRig->setHeadlights(true);
+        }
+
+        // Build commands.
+        const float steerInput = (steerLeftDown ? 1.f : 0.f) - (steerRightDown ? 1.f : 0.f);
+        const float speedKmhAbs = std::abs(vehicle.forwardSpeed()) * 3.6f;
+        const float steerScale = 1.f / (1.f + speedKmhAbs * 0.015f);
+        const float steerSlew = std::min(1.f, dt * 2.f);
+        steerCmd += (steerInput * steerScale - steerCmd) * steerSlew;
+        throttleCmd = throttleDown ? 1.f : 0.f;
+        brakeCmd = brakeDown ? 1.f : 0.f;
+
+        vehicle.setThrottle(throttleCmd);
+        vehicle.setBrake(brakeCmd);
+        vehicle.setHandbrake(handbrakeDown ? 1.f : 0.f);
+        vehicle.setSteer(steerCmd);
+
+        if (respawn) {
+            respawn = false;
+            auto* actor = vehicle.chassisActor();
+            actor->setGlobalPose(toPxTransform(vs.spawnPosition, vs.spawnRotation));
+            actor->setLinearVelocity(PxVec3(0));
+            actor->setAngularVelocity(PxVec3(0));
+            actor->wakeUp();
+            vehicle.setThrottle(0.f);
+            vehicle.setBrake(0.f);
+            vehicle.setSteer(0.f);
+            vehicle.setDirection(PhysxVehicleEngineDrive::Direction::Drive);
+            steerCmd = 0.f;
+        }
+
+        world.step(dt);
+        physxDebug->update();
+        carRig->update(vehicle, dt, brakeCmd, turnSignal);
+
+        // Chase / POV camera.
+        carRig->root()->updateMatrixWorld();
+        const Matrix4& chassisMat = *carRig->root()->matrixWorld;
+        Vector3 desiredCam(0.f, 4.2f, -11.f);
+        desiredCam.applyMatrix4(chassisMat);
+        Vector3 desiredTarget(0.f, 1.2f, 3.f);
+        desiredTarget.applyMatrix4(chassisMat);
+        const float lerp = std::min(1.f, dt * 5.f);
+        camPos.lerp(desiredCam, lerp);
+        camTarget.lerp(desiredTarget, lerp);
+        camera->position.copy(camPos);
+        camera->lookAt(camTarget);
+
+        Camera& activeCamera = driverView ? static_cast<Camera&>(*povCamera) : static_cast<Camera&>(*camera);
+
+        sounds.update(dt, vehicle, throttleCmd, hornDown, activeCamera, audioOn ? audioVol : 0.f);
+
+        renderer->render(*scene, activeCamera);
+
+        if (capturing) {
+            if (shotFrame % 60 == 0 || shotFrame + 1 >= shotFrames)
+                std::cout << "[t=" << shotFrame << "] speed=" << std::abs(vehicle.forwardSpeed()) * 3.6f
+                          << " km/h  rpm=" << vehicle.engineRpm()
+                          << "  gear=" << vehicle.gearLabel() << "\n";
+            if (++shotFrame >= shotFrames) {
+                renderer->writeFramebuffer(shotPath);
+                std::cout << "wrote " << shotPath << "\n";
+                std::exit(0);
+            }
+        }
+
+        ui.render();
+    });
+
+    return 0;
+}
diff --git a/include/threepp/extras/physx/PhysxVehicleEngineDrive.hpp b/include/threepp/extras/physx/PhysxVehicleEngineDrive.hpp
new file mode 100644
index 00000000..4fa43bce
--- /dev/null
+++ b/include/threepp/extras/physx/PhysxVehicleEngineDrive.hpp
@@ -0,0 +1,1107 @@
+
+#ifndef THREEPP_PHYSX_VEHICLE_ENGINE_DRIVE_HPP
+#define THREEPP_PHYSX_VEHICLE_ENGINE_DRIVE_HPP
+
+#include "threepp/extras/physx/PhysxWorld.hpp"
+
+#include <PxPhysicsAPI.h>
+#include <vehicle2/PxVehicleAPI.h>
+
+#include <array>
+#include <cstring>
+#include <stdexcept>
+#include <string>
+
+namespace threepp {
+
+    // Engine-driven 4-wheel vehicle built on the full PxVehicle2 component stack:
+    // engine (torque curve + revs) → clutch → multi-ratio gearbox (+ autobox) →
+    // differential → wheels. This is the "fully featured" sibling of PhysxVehicle
+    // (which is direct-drive, no engine). It produces real engine RPM, automatic or
+    // manual gear shifts, clutch slip, and engine braking — telemetry the HUD and
+    // procedural audio can read directly instead of synthesising.
+    //
+    // Structurally it mirrors PhysxVehicle: it creates its own PxRigidDynamic chassis
+    // + 4 wheel shapes, wires the standard component sequence, and steps via
+    // PhysxWorld::onPreSubstep so the substep cadence stays in sync with PhysX. Only
+    // the drive components differ — DirectDrive{CommandResponse,ActuationState,
+    // Drivetrain} are replaced by EngineDrive{CommandResponse,ActuationState,
+    // Drivetrain} and a MultiWheelDriveDifferential is inserted between command
+    // response and actuation (both downstream components consume the differential
+    // torque split).
+    //
+    // Frame convention is threepp-native: lng=+Z (forward), lat=+X (right), vrt=+Y (up).
+    // SI units: meters, kg, seconds. Engine speeds are radians/second internally;
+    // engineRPM() converts for display.
+    class PhysxVehicleEngineDrive final
+        : public ::physx::vehicle2::PxVehiclePhysXActorBeginComponent,
+          public ::physx::vehicle2::PxVehiclePhysXRoadGeometrySceneQueryComponent,
+          public ::physx::vehicle2::PxVehicleSuspensionComponent,
+          public ::physx::vehicle2::PxVehicleTireComponent,
+          public ::physx::vehicle2::PxVehicleEngineDriveCommandResponseComponent,
+          public ::physx::vehicle2::PxVehicleMultiWheelDriveDifferentialStateComponent,
+          public ::physx::vehicle2::PxVehicleEngineDriveActuationStateComponent,
+          public ::physx::vehicle2::PxVehicleEngineDrivetrainComponent,
+          public ::physx::vehicle2::PxVehicleWheelComponent,
+          public ::physx::vehicle2::PxVehicleRigidBodyComponent,
+          public ::physx::vehicle2::PxVehiclePhysXConstraintComponent,
+          public ::physx::vehicle2::PxVehiclePhysXActorEndComponent {
+
+    public:
+        struct Settings {
+            // ── Chassis ──────────────────────────────────────────────────────
+            float chassisWidth = 1.9f;
+            float chassisHeight = 1.3f;
+            float chassisLength = 4.4f;
+            float chassisMass = 1600.f;
+
+            // ── Wheels ───────────────────────────────────────────────────────
+            float wheelRadius = 0.36f;
+            float wheelHalfWidth = 0.16f;
+            float wheelMass = 25.f;
+
+            float trackWidth = 1.65f;
+            float wheelbase = 2.7f;
+
+            // ── Suspension (the shock absorbers) ─────────────────────────────
+            float suspensionTravelDist = 0.32f;
+            float suspensionStiffness = 38'000.f;
+            float suspensionDamping = 5000.f;
+            // Wheel pose at maximum compression, chassis-frame Y. Negative => below center.
+            float suspensionAttachmentY = -0.35f;
+
+            // ── Brakes / steering ────────────────────────────────────────────
+            float maxBrakeTorque = 6000.f; // N*m at full brake, all wheels
+            float maxHandbrakeTorque = 9000.f;// N*m, rear wheels only
+            float maxSteerAngleRad = 0.6f; // ~34 deg, front wheels (must be <= PI)
+
+            // ── Engine ───────────────────────────────────────────────────────
+            float enginePeakTorque = 520.f;  // N*m at the torque-curve peak
+            float engineMoi = 1.0f;          // kg*m^2 — engine rotational inertia
+            float engineIdleRpm = 900.f;     // rpm
+            float engineMaxRpm = 6200.f;     // rpm (redline)
+            float engineDampingFullThrottle = 0.15f;
+            float engineDampingZeroThrottleClutchEngaged = 2.0f;
+            float engineDampingZeroThrottleClutchDisengaged = 0.35f;
+
+            // ── Clutch ───────────────────────────────────────────────────────
+            float clutchStrength = 10.f;     // max clutch coupling torque*time
+            unsigned clutchEstimateIterations = 5;
+
+            // ── Gearbox ──────────────────────────────────────────────────────
+            // ratios[0] reverse (negative), [1] neutral (0), [2..] forward (descending).
+            // The applied ratio is ratios[gear] * finalRatio.
+            std::vector<float> gearRatios = {-4.0f, 0.0f, 4.2f, 2.6f, 1.7f, 1.25f, 0.95f, 0.78f};
+            float finalDriveRatio = 4.0f;
+            float gearSwitchTime = 0.5f;     // seconds to change gear
+
+            // ── Autobox (automatic transmission) ─────────────────────────────
+            // Normalised engine-rev thresholds (engineRev/maxRev) to shift up / down.
+            float autoboxUpRatio = 0.65f;
+            float autoboxDownRatio = 0.25f;
+            float autoboxLatency = 0.4f;     // min seconds between automatic shifts
+
+            // ── Differential ─────────────────────────────────────────────────
+            // Which wheels receive engine torque. Default = all-wheel drive.
+            // Indices: 0 = front-right, 1 = front-left, 2 = rear-right, 3 = rear-left.
+            std::array<bool, 4> drivenWheels{true, true, true, true};
+
+            // ── Tire ─────────────────────────────────────────────────────────
+            float tireFriction = 2.0f;
+            float lateralStiffness = 90'000.f;
+            float longitudinalStiffness = 100'000.f;
+            float wheelDampingRate = 0.25f;  // lower than direct-drive: the engine/
+                                             // gearbox now provide the coasting drag
+
+            float chassisLinearDamping = 0.1f;
+            float chassisAngularDamping = 0.5f;
+
+            // ── Spawn ────────────────────────────────────────────────────────
+            Vector3 spawnPosition{0, 1.0f, 0};
+            Quaternion spawnRotation;
+
+            // ── Sticky tire (decisive low-speed stops) — see PhysxVehicle docs ─
+            float stickySpeedThreshold = 0.2f;
+            float stickyTimeThreshold = 0.1f;
+            float stickyDampingLongitudinal = 1.0f;
+            float stickyDampingLateral = 1.0f;
+
+            // ── Vehicle sub-stepping (stiff wheel-spin ODE) — see PhysxVehicle docs ─
+            unsigned subStepCountLowSpeed = 8;
+            unsigned subStepCountHighSpeed = 2;
+            float subStepThresholdSpeed = 6.f;// m/s
+
+            // ── Tire-slip denominator floors — see PhysxVehicle docs ─────────
+            float minLongSlipDenominatorActive = 2.0f;
+            float minLongSlipDenominatorPassive = 4.0f;
+            float minLatSlipDenominator = 1.0f;
+        };
+
+        enum class TransmissionMode { Automatic,
+                                      Manual };
+
+        // Driver-facing gear selector (like P/R/N/D). In Drive with Automatic mode
+        // the autobox picks the forward gear; in Manual it uses shiftUp/shiftDown.
+        enum class Direction { Reverse,
+                               Neutral,
+                               Drive };
+
+        explicit PhysxVehicleEngineDrive(PhysxWorld& world, const Settings& s = Settings())
+            : world_(&world), settings_(s) {
+
+            using namespace ::physx;
+            using namespace ::physx::vehicle2;
+
+            if (settings_.gearRatios.size() < 3) {
+                throw std::runtime_error("PhysxVehicleEngineDrive: need at least reverse+neutral+1 forward gear");
+            }
+
+            if (!PxInitVehicleExtension(world.foundation())) {
+                throw std::runtime_error("PxInitVehicleExtension failed");
+            }
+            initialised_ = true;
+
+            buildAxleDescription();
+            buildRigidBodyParams();
+            buildWheelParams();
+            buildSuspensionParams();
+            buildTireParams();
+            buildEngineDriveParams();
+            buildCommandResponseParams();
+            buildSimContext();
+
+            createPhysxActor();
+            createPhysxConstraints();
+            buildComponentSequence();
+
+            stepCallback_ = [this](float dt) { stepVehicle(dt); };
+            world_->onPreSubstep(stepCallback_);
+        }
+
+        ~PhysxVehicleEngineDrive() {
+            using namespace ::physx;
+
+            if (constraintsCreated_) {
+                ::physx::vehicle2::PxVehicleConstraintsDestroy(physxConstraints_);
+                constraintsCreated_ = false;
+            }
+            if (chassisActor_) {
+                chassisActor_->getScene()->removeActor(*chassisActor_);
+                chassisActor_->release();
+                chassisActor_ = nullptr;
+            }
+            if (wheelShapeMaterial_) {
+                wheelShapeMaterial_->release();
+                wheelShapeMaterial_ = nullptr;
+            }
+            if (initialised_) {
+                ::physx::vehicle2::PxCloseVehicleExtension();
+                initialised_ = false;
+            }
+        }
+
+        PhysxVehicleEngineDrive(const PhysxVehicleEngineDrive&) = delete;
+        PhysxVehicleEngineDrive& operator=(const PhysxVehicleEngineDrive&) = delete;
+
+        // ── Inputs ───────────────────────────────────────────────────────────
+
+        void setThrottle(float v) { commands_.throttle = std::clamp(v, 0.f, 1.f); }
+        void setBrake(float v) { commands_.brakes[0] = std::clamp(v, 0.f, 1.f); }
+        void setHandbrake(float v) { commands_.brakes[1] = std::clamp(v, 0.f, 1.f); }
+        void setSteer(float v) { commands_.steer = std::clamp(v, -1.f, 1.f); }
+        // Clutch pedal: 0 = engaged (driving), 1 = disengaged (decoupled). The
+        // automatic mode keeps this at 0 and lets the gearbox switch-time model shifts.
+        void setClutch(float v) { transmissionCommands_.clutch = std::clamp(v, 0.f, 1.f); }
+
+        void setTransmissionMode(TransmissionMode m) {
+            mode_ = m;
+            applyTransmissionCommand();
+        }
+        TransmissionMode transmissionMode() const { return mode_; }
+
+        void setDirection(Direction d) {
+            direction_ = d;
+            applyTransmissionCommand();
+        }
+        Direction direction() const { return direction_; }
+
+        // Manual shifting (only takes effect in Manual mode + Drive). Clamps within
+        // the forward-gear range.
+        void shiftUp() {
+            manualForwardGear_ = std::min<::physx::PxU32>(manualForwardGear_ + 1, lastForwardGearIndex());
+            applyTransmissionCommand();
+        }
+        void shiftDown() {
+            manualForwardGear_ = std::max<::physx::PxU32>(manualForwardGear_ - 1, firstForwardGearIndex());
+            applyTransmissionCommand();
+        }
+
+        // ── Readouts ───────────────────────────────────────────────────────────
+
+        ::physx::PxRigidDynamic* chassisActor() const { return chassisActor_; }
+        ::physx::PxTransform chassisPose() const { return rigidBodyState_.pose; }
+
+        ::physx::PxTransform wheelLocalPose(int i) const { return wheelLocalPoses_[i].localPose; }
+
+        // Forward speed in chassis longitudinal direction (m/s).
+        float forwardSpeed() const { return rigidBodyState_.getLongitudinalSpeed(simContext_.frame); }
+
+        float wheelRotationAngle(int i) const { return wheelRigidBody1dStates_[i].rotationAngle; }
+        float wheelAngularSpeed(int i) const { return wheelRigidBody1dStates_[i].rotationSpeed; }
+
+        float tireLongitudinalSlip(int i) const {
+            return tireSlipStates_[i].slips[::physx::vehicle2::PxVehicleTireDirectionModes::eLONGITUDINAL];
+        }
+        float tireLateralSlip(int i) const {
+            return tireSlipStates_[i].slips[::physx::vehicle2::PxVehicleTireDirectionModes::eLATERAL];
+        }
+
+        // Suspension compression (m): 0 = full droop … suspensionTravelDist = bottomed.
+        float suspensionJounce(int i) const { return suspensionStates_[i].jounce; }
+        float suspensionJounceSpeed(int i) const { return suspensionStates_[i].jounceSpeed; }
+        bool wheelGrounded(int i) const { return roadGeometryStates_[i].hitState; }
+
+        // ── Engine / transmission telemetry ──────────────────────────────────
+
+        // Engine rotation speed (rad/s) and its rpm equivalent.
+        float engineRotationSpeed() const { return engineState_.rotationSpeed; }
+        float engineRpm() const { return engineState_.rotationSpeed * (60.f / kTwoPi); }
+        float engineIdleRpm() const { return settings_.engineIdleRpm; }
+        float engineMaxRpm() const { return settings_.engineMaxRpm; }
+        // Normalised tacho needle in [0,1].
+        float engineRpmFraction() const {
+            return std::clamp(engineRpm() / std::max(settings_.engineMaxRpm, 1.f), 0.f, 1.f);
+        }
+
+        // Raw gearbox index (0 = reverse, neutralGear = neutral, higher = forward).
+        int currentGearIndex() const { return static_cast<int>(gearboxState_.currentGear); }
+        int targetGearIndex() const { return static_cast<int>(gearboxState_.targetGear); }
+        bool gearShiftInProgress() const { return gearboxState_.currentGear != gearboxState_.targetGear; }
+        int neutralGearIndex() const { return static_cast<int>(gearboxParams_.neutralGear); }
+
+        // Human-facing label: "R", "N", "1".."N".
+        std::string gearLabel() const {
+            const ::physx::PxU32 g = gearboxState_.currentGear;
+            if (g < gearboxParams_.neutralGear) return "R";
+            if (g == gearboxParams_.neutralGear) return "N";
+            return std::to_string(g - gearboxParams_.neutralGear);
+        }
+
+        // Clutch slip (rad/s) — engine/wheel speed mismatch; spikes on shifts.
+        float clutchSlip() const { return clutchSlipState_.clutchSlip; }
+
+        const Settings& settings() const { return settings_; }
+
+    private:
+        static constexpr float kTwoPi = 6.28318530717958647692f;
+        static constexpr float kRpmToRadPerSec = kTwoPi / 60.f;
+
+        ::physx::PxU32 firstForwardGearIndex() const { return gearboxParams_.neutralGear + 1; }
+        ::physx::PxU32 lastForwardGearIndex() const { return gearboxParams_.nbRatios - 1; }
+
+        // Translate the (mode, direction, manual gear) selector into the PhysX
+        // transmission command's target gear. Drive+Automatic uses the special
+        // eAUTOMATIC_GEAR sentinel so the autobox drives the shifts.
+        void applyTransmissionCommand() {
+            using TCS = ::physx::vehicle2::PxVehicleEngineDriveTransmissionCommandState;
+            switch (direction_) {
+                case Direction::Reverse:
+                    transmissionCommands_.targetGear = 0;// reverse gear index
+                    break;
+                case Direction::Neutral:
+                    transmissionCommands_.targetGear = gearboxParams_.neutralGear;
+                    break;
+                case Direction::Drive:
+                    transmissionCommands_.targetGear =
+                            (mode_ == TransmissionMode::Automatic)
+                                    ? static_cast<::physx::PxU32>(TCS::eAUTOMATIC_GEAR)
+                                    : manualForwardGear_;
+                    break;
+            }
+        }
+
+        // Autobox is only consulted when cruising forward under automatic control.
+        bool useAutobox() const {
+            return mode_ == TransmissionMode::Automatic && direction_ == Direction::Drive;
+        }
+
+        // ── Construction helpers ──────────────────────────────────────────────
+
+        void buildAxleDescription() {
+            using namespace ::physx;
+            const PxU32 frontIds[2] = {0, 1};
+            const PxU32 rearIds[2] = {2, 3};
+            axleDesc_.setToDefault();
+            axleDesc_.addAxle(2, frontIds);
+            axleDesc_.addAxle(2, rearIds);
+        }
+
+        void buildRigidBodyParams() {
+            using namespace ::physx;
+            rigidBodyParams_.mass = settings_.chassisMass;
+            const float W = settings_.chassisWidth;
+            const float H = settings_.chassisHeight;
+            const float L = settings_.chassisLength;
+            const float m = settings_.chassisMass;
+            rigidBodyParams_.moi = PxVec3(
+                    m / 12.f * (H * H + L * L),
+                    m / 12.f * (W * W + L * L),
+                    m / 12.f * (W * W + H * H));
+            rigidBodyState_ = ::physx::vehicle2::PxVehicleRigidBodyState();
+            rigidBodyState_.pose = toPxTransform(settings_.spawnPosition, settings_.spawnRotation);
+        }
+
+        void buildWheelParams() {
+            using namespace ::physx;
+            for (PxU32 i = 0; i < 4; ++i) {
+                wheelParams_[i].radius = settings_.wheelRadius;
+                wheelParams_[i].halfWidth = settings_.wheelHalfWidth;
+                wheelParams_[i].mass = settings_.wheelMass;
+                wheelParams_[i].moi = 0.5f * settings_.wheelMass * settings_.wheelRadius * settings_.wheelRadius;
+                wheelParams_[i].dampingRate = settings_.wheelDampingRate;
+            }
+        }
+
+        void buildSuspensionParams() {
+            using namespace ::physx;
+            const float halfTrack = settings_.trackWidth * 0.5f;
+            const float halfBase = settings_.wheelbase * 0.5f;
+            const float ay = settings_.suspensionAttachmentY;
+
+            const PxVec3 wheelPos[4] = {
+                    PxVec3(+halfTrack, ay, +halfBase),// 0 front-right
+                    PxVec3(-halfTrack, ay, +halfBase),// 1 front-left
+                    PxVec3(+halfTrack, ay, -halfBase),// 2 rear-right
+                    PxVec3(-halfTrack, ay, -halfBase),// 3 rear-left
+            };
+
+            for (PxU32 i = 0; i < 4; ++i) {
+                suspensionParams_[i].suspensionAttachment = PxTransform(wheelPos[i]);
+                suspensionParams_[i].suspensionTravelDir = PxVec3(0, -1, 0);
+                suspensionParams_[i].suspensionTravelDist = settings_.suspensionTravelDist;
+                suspensionParams_[i].wheelAttachment = PxTransform(PxIdentity);
+
+                suspensionForceParams_[i].stiffness = settings_.suspensionStiffness;
+                suspensionForceParams_[i].damping = settings_.suspensionDamping;
+                suspensionForceParams_[i].sprungMass = settings_.chassisMass * 0.25f;
+
+                suspensionComplianceParams_[i].wheelToeAngle.clear();
+                suspensionComplianceParams_[i].wheelCamberAngle.clear();
+                suspensionComplianceParams_[i].suspForceAppPoint.clear();
+                suspensionComplianceParams_[i].tireForceAppPoint.clear();
+
+                suspensionLimitParams_[i].restitution = 0.f;
+                suspensionLimitParams_[i].directionForSuspensionLimitConstraint =
+                        ::physx::vehicle2::PxVehiclePhysXSuspensionLimitConstraintParams::eROAD_GEOMETRY_NORMAL;
+            }
+
+            suspensionStateCalcParams_.suspensionJounceCalculationType =
+                    ::physx::vehicle2::PxVehicleSuspensionJounceCalculationType::eRAYCAST;
+            suspensionStateCalcParams_.limitSuspensionExpansionVelocity = false;
+        }
+
+        void buildTireParams() {
+            using namespace ::physx;
+            for (PxU32 i = 0; i < 4; ++i) {
+                tireForceParams_[i].latStiffX = 0.f;
+                tireForceParams_[i].latStiffY = settings_.lateralStiffness;
+                tireForceParams_[i].longStiff = settings_.longitudinalStiffness;
+                tireForceParams_[i].camberStiff = 0.f;
+                tireForceParams_[i].restLoad = settings_.chassisMass * 0.25f * 9.81f;
+
+                tireForceParams_[i].frictionVsSlip[0][0] = 0.f;
+                tireForceParams_[i].frictionVsSlip[0][1] = 1.f;
+                tireForceParams_[i].frictionVsSlip[1][0] = 0.1f;
+                tireForceParams_[i].frictionVsSlip[1][1] = 1.f;
+                tireForceParams_[i].frictionVsSlip[2][0] = 1.f;
+                tireForceParams_[i].frictionVsSlip[2][1] = 1.f;
+
+                tireForceParams_[i].loadFilter[0][0] = 0.f;
+                tireForceParams_[i].loadFilter[0][1] = 0.23f;
+                tireForceParams_[i].loadFilter[1][0] = 3.f;
+                tireForceParams_[i].loadFilter[1][1] = 3.f;
+            }
+
+            materialFriction_.material = &world_->defaultMaterial();
+            materialFriction_.friction = settings_.tireFriction;
+            for (PxU32 i = 0; i < 4; ++i) {
+                perWheelMaterialFriction_[i].materialFrictions = &materialFriction_;
+                perWheelMaterialFriction_[i].nbMaterialFrictions = 1;
+                perWheelMaterialFriction_[i].defaultFriction = settings_.tireFriction;
+            }
+        }
+
+        void buildEngineDriveParams() {
+            using namespace ::physx;
+            using namespace ::physx::vehicle2;
+
+            // Engine: a simple flat-topped torque curve (normalised torque vs
+            // normalised revs). Peak in the mid range, tailing off toward idle and
+            // redline so the autobox has a reason to keep revs in the meat of the band.
+            engineParams_.torqueCurve.clear();
+            engineParams_.torqueCurve.addPair(0.0f, 0.72f);
+            engineParams_.torqueCurve.addPair(0.33f, 1.0f);
+            engineParams_.torqueCurve.addPair(0.66f, 0.96f);
+            engineParams_.torqueCurve.addPair(1.0f, 0.74f);
+            engineParams_.moi = settings_.engineMoi;
+            engineParams_.peakTorque = settings_.enginePeakTorque;
+            engineParams_.idleOmega = settings_.engineIdleRpm * kRpmToRadPerSec;
+            engineParams_.maxOmega = settings_.engineMaxRpm * kRpmToRadPerSec;
+            engineParams_.dampingRateFullThrottle = settings_.engineDampingFullThrottle;
+            engineParams_.dampingRateZeroThrottleClutchEngaged = settings_.engineDampingZeroThrottleClutchEngaged;
+            engineParams_.dampingRateZeroThrottleClutchDisengaged = settings_.engineDampingZeroThrottleClutchDisengaged;
+
+            engineState_.setToDefault();
+            engineState_.rotationSpeed = engineParams_.idleOmega;
+
+            // Clutch. Fully qualify the accuracy mode — the enum name also exists in
+            // the legacy `physx::` vehicle API, so the bare name is ambiguous here.
+            clutchParams_.accuracyMode = ::physx::vehicle2::PxVehicleClutchAccuracyMode::eESTIMATE;
+            clutchParams_.estimateIterations = std::max(1u, settings_.clutchEstimateIterations);
+            clutchResponseParams_.maxResponse = settings_.clutchStrength;
+            clutchResponseState_.setToDefault();
+            clutchSlipState_.setToDefault();
+            throttleResponseState_.setToDefault();
+
+            // Gearbox. neutralGear is index 1 (ratios[0] = reverse, [1] = neutral).
+            const PxU32 nb = static_cast<PxU32>(std::min<size_t>(settings_.gearRatios.size(),
+                                                                 PxVehicleGearboxParams::eMAX_NB_GEARS));
+            gearboxParams_.neutralGear = 1;
+            gearboxParams_.nbRatios = nb;
+            gearboxParams_.finalRatio = settings_.finalDriveRatio;
+            gearboxParams_.switchTime = settings_.gearSwitchTime;
+            for (PxU32 i = 0; i < nb; ++i) gearboxParams_.ratios[i] = settings_.gearRatios[i];
+
+            gearboxState_.setToDefault();
+            // Start in first forward gear so the car is immediately drivable.
+            gearboxState_.currentGear = firstForwardGearIndex();
+            gearboxState_.targetGear = firstForwardGearIndex();
+
+            // Autobox: per-gear up/down rev thresholds. Indices match gear indices.
+            for (PxU32 i = 0; i < PxVehicleGearboxParams::eMAX_NB_GEARS; ++i) {
+                autoboxParams_.upRatios[i] = settings_.autoboxUpRatio;
+                autoboxParams_.downRatios[i] = settings_.autoboxDownRatio;
+            }
+            // Never auto-upshift out of the top gear; never auto-downshift below first.
+            autoboxParams_.upRatios[lastForwardGearIndex()] = 1.0f;// unreachable => no upshift
+            autoboxParams_.downRatios[firstForwardGearIndex()] = 0.0f;// => no downshift below 1st
+            autoboxParams_.latency = settings_.autoboxLatency;
+            autoboxState_.setToDefault();
+
+            // Differential: split torque equally across the driven wheels.
+            diffParams_.setToDefault();
+            int nDriven = 0;
+            for (bool d : settings_.drivenWheels) nDriven += d ? 1 : 0;
+            if (nDriven == 0) {// guard: default to AWD if mis-configured
+                settings_.drivenWheels = {true, true, true, true};
+                nDriven = 4;
+            }
+            const float each = 1.f / static_cast<float>(nDriven);
+            for (PxU32 i = 0; i < 4; ++i) {
+                const float r = settings_.drivenWheels[i] ? each : 0.f;
+                diffParams_.torqueRatios[i] = r;
+                diffParams_.aveWheelSpeedRatios[i] = r;
+            }
+            diffState_.setToDefault();
+            constraintGroupState_.setToDefault();
+        }
+
+        void buildCommandResponseParams() {
+            using namespace ::physx;
+            using namespace ::physx::vehicle2;
+
+            // Brake command 0: foot brake (all wheels). Brake command 1: handbrake
+            // (rear wheels only). Two separate brake response params, one per command.
+            std::memset(&brakeResponseParams_, 0, sizeof(brakeResponseParams_));
+            brakeResponseParams_.maxResponse = settings_.maxBrakeTorque;
+            for (PxU32 i = 0; i < 4; ++i) brakeResponseParams_.wheelResponseMultipliers[i] = 1.f;
+
+            std::memset(&handbrakeResponseParams_, 0, sizeof(handbrakeResponseParams_));
+            handbrakeResponseParams_.maxResponse = settings_.maxHandbrakeTorque;
+            handbrakeResponseParams_.wheelResponseMultipliers[0] = 0.f;
+            handbrakeResponseParams_.wheelResponseMultipliers[1] = 0.f;
+            handbrakeResponseParams_.wheelResponseMultipliers[2] = 1.f;
+            handbrakeResponseParams_.wheelResponseMultipliers[3] = 1.f;
+
+            // Pack both into the contiguous array actually handed to the command-
+            // response component (index 0 = foot brake, 1 = handbrake). Without this
+            // the array stays zero-initialised and NEITHER brake produces torque.
+            brakeResponseParamArray_[0] = brakeResponseParams_;
+            brakeResponseParamArray_[1] = handbrakeResponseParams_;
+
+            std::memset(&steerResponseParams_, 0, sizeof(steerResponseParams_));
+            steerResponseParams_.maxResponse = settings_.maxSteerAngleRad;
+            steerResponseParams_.wheelResponseMultipliers[0] = 1.f;
+            steerResponseParams_.wheelResponseMultipliers[1] = 1.f;
+            steerResponseParams_.wheelResponseMultipliers[2] = 0.f;
+            steerResponseParams_.wheelResponseMultipliers[3] = 0.f;
+
+            commands_.brakes[0] = 0.f;
+            commands_.brakes[1] = 0.f;
+            commands_.nbBrakes = 2;
+            commands_.throttle = 0.f;
+            commands_.steer = 0.f;
+
+            transmissionCommands_.clutch = 0.f;
+            manualForwardGear_ = firstForwardGearIndex();
+            applyTransmissionCommand();
+
+            physxSteerState_.setToDefault();
+            physxConstraints_.setToDefault();
+            physxRoadGeomQueryParams_.defaultFilterData = PxQueryFilterData(
+                    PxQueryFlag::eSTATIC | PxQueryFlag::eDYNAMIC | PxQueryFlag::ePREFILTER);
+            physxRoadGeomQueryParams_.filterDataEntries = nullptr;
+            physxRoadGeomQueryParams_.filterCallback = &queryFilter_;
+            physxRoadGeomQueryParams_.roadGeometryQueryType =
+                    ::physx::vehicle2::PxVehiclePhysXRoadGeometryQueryType::eRAYCAST;
+        }
+
+        void buildSimContext() {
+            using namespace ::physx;
+            using namespace ::physx::vehicle2;
+            simContext_.setToDefault();
+            simContext_.frame.lngAxis = PxVehicleAxes::ePosZ;
+            simContext_.frame.latAxis = PxVehicleAxes::ePosX;
+            simContext_.frame.vrtAxis = PxVehicleAxes::ePosY;
+            simContext_.scale.scale = 1.f;
+            simContext_.gravity = PxVec3(0, -9.81f, 0);
+            simContext_.physxScene = &world_->scene();
+            simContext_.physxUnitCylinderSweepMesh = nullptr;
+            simContext_.physxActorUpdateMode = ::physx::vehicle2::PxVehiclePhysXActorUpdateMode::eAPPLY_VELOCITY;
+
+            auto& sticky = simContext_.tireStickyParams;
+            sticky.stickyParams[PxVehicleTireDirectionModes::eLONGITUDINAL].thresholdSpeed = settings_.stickySpeedThreshold;
+            sticky.stickyParams[PxVehicleTireDirectionModes::eLONGITUDINAL].thresholdTime = settings_.stickyTimeThreshold;
+            sticky.stickyParams[PxVehicleTireDirectionModes::eLONGITUDINAL].damping = settings_.stickyDampingLongitudinal;
+            sticky.stickyParams[PxVehicleTireDirectionModes::eLATERAL].thresholdSpeed = settings_.stickySpeedThreshold;
+            sticky.stickyParams[PxVehicleTireDirectionModes::eLATERAL].thresholdTime = settings_.stickyTimeThreshold;
+            sticky.stickyParams[PxVehicleTireDirectionModes::eLATERAL].damping = settings_.stickyDampingLateral;
+
+            auto& slip = simContext_.tireSlipParams;
+            slip.minActiveLongSlipDenominator = settings_.minLongSlipDenominatorActive;
+            slip.minPassiveLongSlipDenominator = settings_.minLongSlipDenominatorPassive;
+            slip.minLatSlipDenominator = settings_.minLatSlipDenominator;
+        }
+
+        void createPhysxActor() {
+            using namespace ::physx;
+            auto& physics = world_->physics();
+
+            chassisActor_ = physics.createRigidDynamic(rigidBodyState_.pose);
+            chassisActor_->setActorFlag(PxActorFlag::eDISABLE_GRAVITY, true);
+            chassisActor_->setRigidBodyFlag(PxRigidBodyFlag::eENABLE_CCD, false);
+            chassisActor_->setLinearDamping(settings_.chassisLinearDamping);
+            chassisActor_->setAngularDamping(settings_.chassisAngularDamping);
+
+            const PxBoxGeometry chassisGeom(
+                    settings_.chassisWidth * 0.5f,
+                    settings_.chassisHeight * 0.5f,
+                    settings_.chassisLength * 0.5f);
+            PxShape* chassisShape = physics.createShape(chassisGeom, world_->defaultMaterial(), true);
+            chassisActor_->attachShape(*chassisShape);
+            chassisShape->release();
+
+            wheelShapeMaterial_ = physics.createMaterial(0.f, 0.f, 0.f);
+            const float halfTrack = settings_.trackWidth * 0.5f;
+            const float halfBase = settings_.wheelbase * 0.5f;
+            const float ay = settings_.suspensionAttachmentY;
+            const PxVec3 wheelInitial[4] = {
+                    PxVec3(+halfTrack, ay, +halfBase),
+                    PxVec3(-halfTrack, ay, +halfBase),
+                    PxVec3(+halfTrack, ay, -halfBase),
+                    PxVec3(-halfTrack, ay, -halfBase),
+            };
+            const PxSphereGeometry wheelGeom(settings_.wheelRadius);
+            for (PxU32 i = 0; i < 4; ++i) {
+                PxShape* ws = physics.createShape(wheelGeom, *wheelShapeMaterial_, true);
+                ws->setLocalPose(PxTransform(wheelInitial[i]));
+                ws->setFlag(PxShapeFlag::eSCENE_QUERY_SHAPE, false);
+                ws->setFlag(PxShapeFlag::eSIMULATION_SHAPE, false);
+                chassisActor_->attachShape(*ws);
+                wheelShapeLocalPoses_[i] = ws->getLocalPose();
+                physxActor_.wheelShapes[i] = ws;
+                ws->release();
+            }
+            physxActor_.rigidBody = chassisActor_;
+
+            PxRigidBodyExt::setMassAndUpdateInertia(*chassisActor_, settings_.chassisMass);
+            world_->scene().addActor(*chassisActor_);
+
+            queryFilter_.ignored = chassisActor_;
+        }
+
+        void createPhysxConstraints() {
+            ::physx::vehicle2::PxVehicleConstraintsCreate(
+                    axleDesc_, world_->physics(), *chassisActor_, physxConstraints_);
+            constraintsCreated_ = true;
+        }
+
+        void buildComponentSequence() {
+            using namespace ::physx::vehicle2;
+            componentSequence_.add(static_cast<PxVehiclePhysXActorBeginComponent*>(this));
+            componentSequence_.add(static_cast<PxVehiclePhysXRoadGeometrySceneQueryComponent*>(this));
+
+            // Sub-step the integration-heavy components (suspension … rigid body),
+            // exactly as PhysxVehicle does. The engine-drive command response +
+            // differential sit inside the group between tire and actuation: the
+            // differential output (torque split) is consumed by both actuation and
+            // drivetrain, so it must run before them.
+            substepGroupHandle_ = componentSequence_.beginSubstepGroup(
+                    static_cast<::physx::PxU8>(std::max(1u, settings_.subStepCountLowSpeed)));
+            componentSequence_.add(static_cast<PxVehicleSuspensionComponent*>(this));
+            componentSequence_.add(static_cast<PxVehicleTireComponent*>(this));
+            componentSequence_.add(static_cast<PxVehicleEngineDriveCommandResponseComponent*>(this));
+            componentSequence_.add(static_cast<PxVehicleMultiWheelDriveDifferentialStateComponent*>(this));
+            componentSequence_.add(static_cast<PxVehicleEngineDriveActuationStateComponent*>(this));
+            componentSequence_.add(static_cast<PxVehicleEngineDrivetrainComponent*>(this));
+            componentSequence_.add(static_cast<PxVehicleWheelComponent*>(this));
+            componentSequence_.add(static_cast<PxVehicleRigidBodyComponent*>(this));
+            componentSequence_.endSubstepGroup();
+
+            componentSequence_.add(static_cast<PxVehiclePhysXConstraintComponent*>(this));
+            componentSequence_.add(static_cast<PxVehiclePhysXActorEndComponent*>(this));
+        }
+
+        void stepVehicle(float dt) {
+            const float fwdSpeed = std::abs(rigidBodyState_.getLongitudinalSpeed(simContext_.frame));
+            const unsigned nSub = fwdSpeed < settings_.subStepThresholdSpeed
+                                          ? settings_.subStepCountLowSpeed
+                                          : settings_.subStepCountHighSpeed;
+            componentSequence_.setSubsteps(substepGroupHandle_,
+                                           static_cast<::physx::PxU8>(std::max(1u, nSub)));
+            componentSequence_.update(dt, simContext_);
+            for (::physx::PxU32 i = 0; i < 4; ++i) {
+                if (auto* shape = physxActor_.wheelShapes[i]) {
+                    shape->setLocalPose(wheelLocalPoses_[i].localPose);
+                }
+            }
+        }
+
+        // ── Component getDataFor* overrides ───────────────────────────────────
+
+        void getDataForPhysXActorBeginComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                const ::physx::vehicle2::PxVehicleCommandState*& commands,
+                const ::physx::vehicle2::PxVehicleEngineDriveTransmissionCommandState*& transmissionCommands,
+                const ::physx::vehicle2::PxVehicleGearboxParams*& gearParams,
+                const ::physx::vehicle2::PxVehicleGearboxState*& gearState,
+                const ::physx::vehicle2::PxVehicleEngineParams*& engineParams,
+                ::physx::vehicle2::PxVehiclePhysXActor*& physxActor,
+                ::physx::vehicle2::PxVehiclePhysXSteerState*& physxSteerState,
+                ::physx::vehicle2::PxVehiclePhysXConstraints*& physxConstraints,
+                ::physx::vehicle2::PxVehicleRigidBodyState*& rigidBodyState,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleWheelRigidBody1dState>& wheelRigidBody1dStates,
+                ::physx::vehicle2::PxVehicleEngineState*& engineState) override {
+            axleDescription = &axleDesc_;
+            commands = &commands_;
+            transmissionCommands = &transmissionCommands_;
+            gearParams = &gearboxParams_;
+            gearState = &gearboxState_;
+            engineParams = &engineParams_;
+            physxActor = &physxActor_;
+            physxSteerState = &physxSteerState_;
+            physxConstraints = &physxConstraints_;
+            rigidBodyState = &rigidBodyState_;
+            wheelRigidBody1dStates.setData(wheelRigidBody1dStates_.data());
+            engineState = &engineState_;
+        }
+
+        void getDataForPhysXRoadGeometrySceneQueryComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                const ::physx::vehicle2::PxVehiclePhysXRoadGeometryQueryParams*& roadGeomParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::PxReal>& steerResponseStates,
+                const ::physx::vehicle2::PxVehicleRigidBodyState*& rigidBodyState,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelParams>& wheelParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionParams>& suspensionParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehiclePhysXMaterialFrictionParams>& materialFrictionParams,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleRoadGeometryState>& roadGeometryStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehiclePhysXRoadGeometryQueryState>& physxRoadGeometryStates) override {
+            axleDescription = &axleDesc_;
+            roadGeomParams = &physxRoadGeomQueryParams_;
+            steerResponseStates.setData(steerResponseStates_.data());
+            rigidBodyState = &rigidBodyState_;
+            wheelParams.setData(wheelParams_.data());
+            suspensionParams.setData(suspensionParams_.data());
+            materialFrictionParams.setData(perWheelMaterialFriction_.data());
+            roadGeometryStates.setData(roadGeometryStates_.data());
+            physxRoadGeometryStates.setEmpty();
+        }
+
+        void getDataForSuspensionComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                const ::physx::vehicle2::PxVehicleRigidBodyParams*& rigidBodyParams,
+                const ::physx::vehicle2::PxVehicleSuspensionStateCalculationParams*& suspensionStateCalculationParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::PxReal>& steerResponseStates,
+                const ::physx::vehicle2::PxVehicleRigidBodyState*& rigidBodyState,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelParams>& wheelParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionParams>& suspensionParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionComplianceParams>& suspensionComplianceParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionForceParams>& suspensionForceParams,
+                ::physx::vehicle2::PxVehicleSizedArrayData<const ::physx::vehicle2::PxVehicleAntiRollForceParams>& antiRollForceParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleRoadGeometryState>& wheelRoadGeomStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleSuspensionState>& suspensionStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleSuspensionComplianceState>& suspensionComplianceStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleSuspensionForce>& suspensionForces,
+                ::physx::vehicle2::PxVehicleAntiRollTorque*& antiRollTorque) override {
+            axleDescription = &axleDesc_;
+            rigidBodyParams = &rigidBodyParams_;
+            suspensionStateCalculationParams = &suspensionStateCalcParams_;
+            steerResponseStates.setData(steerResponseStates_.data());
+            rigidBodyState = &rigidBodyState_;
+            wheelParams.setData(wheelParams_.data());
+            suspensionParams.setData(suspensionParams_.data());
+            suspensionComplianceParams.setData(suspensionComplianceParams_.data());
+            suspensionForceParams.setData(suspensionForceParams_.data());
+            antiRollForceParams.setEmpty();
+            wheelRoadGeomStates.setData(roadGeometryStates_.data());
+            suspensionStates.setData(suspensionStates_.data());
+            suspensionComplianceStates.setData(suspensionComplianceStates_.data());
+            suspensionForces.setData(suspensionForces_.data());
+            antiRollTorque = nullptr;
+        }
+
+        void getDataForTireComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::PxReal>& steerResponseStates,
+                const ::physx::vehicle2::PxVehicleRigidBodyState*& rigidBodyState,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelActuationState>& actuationStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelParams>& wheelParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionParams>& suspensionParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleTireForceParams>& tireForceParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleRoadGeometryState>& roadGeomStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionState>& suspensionStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionComplianceState>& suspensionComplianceStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionForce>& suspensionForces,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelRigidBody1dState>& wheelRigidBody1DStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleTireGripState>& tireGripStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleTireDirectionState>& tireDirectionStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleTireSpeedState>& tireSpeedStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleTireSlipState>& tireSlipStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleTireCamberAngleState>& tireCamberAngleStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleTireStickyState>& tireStickyStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleTireForce>& tireForces) override {
+            axleDescription = &axleDesc_;
+            steerResponseStates.setData(steerResponseStates_.data());
+            rigidBodyState = &rigidBodyState_;
+            actuationStates.setData(actuationStates_.data());
+            wheelParams.setData(wheelParams_.data());
+            suspensionParams.setData(suspensionParams_.data());
+            tireForceParams.setData(tireForceParams_.data());
+            roadGeomStates.setData(roadGeometryStates_.data());
+            suspensionStates.setData(suspensionStates_.data());
+            suspensionComplianceStates.setData(suspensionComplianceStates_.data());
+            suspensionForces.setData(suspensionForces_.data());
+            wheelRigidBody1DStates.setData(wheelRigidBody1dStates_.data());
+            tireGripStates.setData(tireGripStates_.data());
+            tireDirectionStates.setData(tireDirectionStates_.data());
+            tireSpeedStates.setData(tireSpeedStates_.data());
+            tireSlipStates.setData(tireSlipStates_.data());
+            tireCamberAngleStates.setData(tireCamberAngleStates_.data());
+            tireStickyStates.setData(tireStickyStates_.data());
+            tireForces.setData(tireForces_.data());
+        }
+
+        void getDataForEngineDriveCommandResponseComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                ::physx::vehicle2::PxVehicleSizedArrayData<const ::physx::vehicle2::PxVehicleBrakeCommandResponseParams>& brakeResponseParams,
+                const ::physx::vehicle2::PxVehicleSteerCommandResponseParams*& steerResponseParams,
+                ::physx::vehicle2::PxVehicleSizedArrayData<const ::physx::vehicle2::PxVehicleAckermannParams>& ackermannParams,
+                const ::physx::vehicle2::PxVehicleGearboxParams*& gearboxParams,
+                const ::physx::vehicle2::PxVehicleClutchCommandResponseParams*& clutchResponseParams,
+                const ::physx::vehicle2::PxVehicleEngineParams*& engineParams,
+                const ::physx::vehicle2::PxVehicleRigidBodyState*& rigidBodyState,
+                const ::physx::vehicle2::PxVehicleEngineState*& engineState,
+                const ::physx::vehicle2::PxVehicleAutoboxParams*& autoboxParams,
+                const ::physx::vehicle2::PxVehicleCommandState*& commands,
+                const ::physx::vehicle2::PxVehicleEngineDriveTransmissionCommandState*& transmissionCommands,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::PxReal>& brakeResponseStates,
+                ::physx::vehicle2::PxVehicleEngineDriveThrottleCommandResponseState*& throttleResponseState,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::PxReal>& steerResponseStates,
+                ::physx::vehicle2::PxVehicleGearboxState*& gearboxResponseState,
+                ::physx::vehicle2::PxVehicleClutchCommandResponseState*& clutchResponseState,
+                ::physx::vehicle2::PxVehicleAutoboxState*& autoboxState) override {
+            axleDescription = &axleDesc_;
+            brakeResponseParams.setDataAndCount(brakeResponseParamArray_.data(),
+                                                static_cast<::physx::PxU32>(brakeResponseParamArray_.size()));
+            steerResponseParams = &steerResponseParams_;
+            ackermannParams.setEmpty();
+            gearboxParams = &gearboxParams_;
+            clutchResponseParams = &clutchResponseParams_;
+            engineParams = &engineParams_;
+            rigidBodyState = &rigidBodyState_;
+            engineState = &engineState_;
+            autoboxParams = useAutobox() ? &autoboxParams_ : nullptr;
+            commands = &commands_;
+            transmissionCommands = &transmissionCommands_;
+            brakeResponseStates.setData(brakeResponseStates_.data());
+            throttleResponseState = &throttleResponseState_;
+            steerResponseStates.setData(steerResponseStates_.data());
+            gearboxResponseState = &gearboxState_;
+            clutchResponseState = &clutchResponseState_;
+            autoboxState = useAutobox() ? &autoboxState_ : nullptr;
+        }
+
+        void getDataForMultiWheelDriveDifferentialStateComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                const ::physx::vehicle2::PxVehicleMultiWheelDriveDifferentialParams*& differentialParams,
+                ::physx::vehicle2::PxVehicleDifferentialState*& differentialState) override {
+            axleDescription = &axleDesc_;
+            differentialParams = &diffParams_;
+            differentialState = &diffState_;
+        }
+
+        void getDataForEngineDriveActuationStateComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                const ::physx::vehicle2::PxVehicleGearboxParams*& gearboxParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::PxReal>& brakeResponseStates,
+                const ::physx::vehicle2::PxVehicleEngineDriveThrottleCommandResponseState*& throttleResponseState,
+                const ::physx::vehicle2::PxVehicleGearboxState*& gearboxState,
+                const ::physx::vehicle2::PxVehicleDifferentialState*& differentialState,
+                const ::physx::vehicle2::PxVehicleClutchCommandResponseState*& clutchResponseState,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleWheelActuationState>& actuationStates) override {
+            axleDescription = &axleDesc_;
+            gearboxParams = &gearboxParams_;
+            brakeResponseStates.setData(brakeResponseStates_.data());
+            throttleResponseState = &throttleResponseState_;
+            gearboxState = &gearboxState_;
+            differentialState = &diffState_;
+            clutchResponseState = &clutchResponseState_;
+            actuationStates.setData(actuationStates_.data());
+        }
+
+        void getDataForEngineDrivetrainComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelParams>& wheelParams,
+                const ::physx::vehicle2::PxVehicleEngineParams*& engineParams,
+                const ::physx::vehicle2::PxVehicleClutchParams*& clutchParams,
+                const ::physx::vehicle2::PxVehicleGearboxParams*& gearboxParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::PxReal>& brakeResponseStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelActuationState>& actuationStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleTireForce>& tireForces,
+                const ::physx::vehicle2::PxVehicleEngineDriveThrottleCommandResponseState*& throttleResponseState,
+                const ::physx::vehicle2::PxVehicleClutchCommandResponseState*& clutchResponseState,
+                const ::physx::vehicle2::PxVehicleDifferentialState*& differentialState,
+                const ::physx::vehicle2::PxVehicleWheelConstraintGroupState*& constraintGroupState,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleWheelRigidBody1dState>& wheelRigidBody1dStates,
+                ::physx::vehicle2::PxVehicleEngineState*& engineState,
+                ::physx::vehicle2::PxVehicleGearboxState*& gearboxState,
+                ::physx::vehicle2::PxVehicleClutchSlipState*& clutchState) override {
+            axleDescription = &axleDesc_;
+            wheelParams.setData(wheelParams_.data());
+            engineParams = &engineParams_;
+            clutchParams = &clutchParams_;
+            gearboxParams = &gearboxParams_;
+            brakeResponseStates.setData(brakeResponseStates_.data());
+            actuationStates.setData(actuationStates_.data());
+            tireForces.setData(tireForces_.data());
+            throttleResponseState = &throttleResponseState_;
+            clutchResponseState = &clutchResponseState_;
+            differentialState = &diffState_;
+            constraintGroupState = nullptr;// MultiWheel differential has no wheel constraint groups
+            wheelRigidBody1dStates.setData(wheelRigidBody1dStates_.data());
+            engineState = &engineState_;
+            gearboxState = &gearboxState_;
+            clutchState = &clutchSlipState_;
+        }
+
+        void getDataForWheelComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::PxReal>& steerResponseStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelParams>& wheelParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionParams>& suspensionParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelActuationState>& actuationStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionState>& suspensionStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionComplianceState>& suspensionComplianceStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleTireSpeedState>& tireSpeedStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleWheelRigidBody1dState>& wheelRigidBody1dStates,
+                ::physx::vehicle2::PxVehicleArrayData<::physx::vehicle2::PxVehicleWheelLocalPose>& wheelLocalPoses) override {
+            axleDescription = &axleDesc_;
+            steerResponseStates.setData(steerResponseStates_.data());
+            wheelParams.setData(wheelParams_.data());
+            suspensionParams.setData(suspensionParams_.data());
+            actuationStates.setData(actuationStates_.data());
+            suspensionStates.setData(suspensionStates_.data());
+            suspensionComplianceStates.setData(suspensionComplianceStates_.data());
+            tireSpeedStates.setData(tireSpeedStates_.data());
+            wheelRigidBody1dStates.setData(wheelRigidBody1dStates_.data());
+            wheelLocalPoses.setData(wheelLocalPoses_.data());
+        }
+
+        void getDataForRigidBodyComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                const ::physx::vehicle2::PxVehicleRigidBodyParams*& rigidBodyParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionForce>& suspensionForces,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleTireForce>& tireForces,
+                const ::physx::vehicle2::PxVehicleAntiRollTorque*& antiRollTorque,
+                ::physx::vehicle2::PxVehicleRigidBodyState*& rigidBodyState) override {
+            axleDescription = &axleDesc_;
+            rigidBodyParams = &rigidBodyParams_;
+            suspensionForces.setData(suspensionForces_.data());
+            tireForces.setData(tireForces_.data());
+            antiRollTorque = nullptr;
+            rigidBodyState = &rigidBodyState_;
+        }
+
+        void getDataForPhysXConstraintComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                const ::physx::vehicle2::PxVehicleRigidBodyState*& rigidBodyState,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionParams>& suspensionParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehiclePhysXSuspensionLimitConstraintParams>& suspensionLimitParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionState>& suspensionStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleSuspensionComplianceState>& suspensionComplianceStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleRoadGeometryState>& wheelRoadGeomStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleTireDirectionState>& tireDirectionStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleTireStickyState>& tireStickyStates,
+                ::physx::vehicle2::PxVehiclePhysXConstraints*& constraints) override {
+            axleDescription = &axleDesc_;
+            rigidBodyState = &rigidBodyState_;
+            suspensionParams.setData(suspensionParams_.data());
+            suspensionLimitParams.setData(suspensionLimitParams_.data());
+            suspensionStates.setData(suspensionStates_.data());
+            suspensionComplianceStates.setData(suspensionComplianceStates_.data());
+            wheelRoadGeomStates.setData(roadGeometryStates_.data());
+            tireDirectionStates.setData(tireDirectionStates_.data());
+            tireStickyStates.setData(tireStickyStates_.data());
+            constraints = &physxConstraints_;
+        }
+
+        void getDataForPhysXActorEndComponent(
+                const ::physx::vehicle2::PxVehicleAxleDescription*& axleDescription,
+                const ::physx::vehicle2::PxVehicleRigidBodyState*& rigidBodyState,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelParams>& wheelParams,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::PxTransform>& wheelShapeLocalPoses,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelRigidBody1dState>& wheelRigidBody1dStates,
+                ::physx::vehicle2::PxVehicleArrayData<const ::physx::vehicle2::PxVehicleWheelLocalPose>& wheelLocalPoses,
+                const ::physx::vehicle2::PxVehicleGearboxState*& gearState,
+                const ::physx::PxReal*& throttle,
+                ::physx::vehicle2::PxVehiclePhysXActor*& physxActor) override {
+            axleDescription = &axleDesc_;
+            rigidBodyState = &rigidBodyState_;
+            wheelParams.setData(wheelParams_.data());
+            wheelShapeLocalPoses.setData(wheelShapeLocalPoses_.data());
+            wheelRigidBody1dStates.setData(wheelRigidBody1dStates_.data());
+            wheelLocalPoses.setData(wheelLocalPoses_.data());
+            gearState = &gearboxState_;
+            throttle = &commands_.throttle;
+            physxActor = &physxActor_;
+        }
+
+        // ── Internal types ────────────────────────────────────────────────────
+
+        struct ChassisQueryFilter : public ::physx::PxQueryFilterCallback {
+            ::physx::PxRigidActor const* ignored = nullptr;
+
+            ::physx::PxQueryHitType::Enum preFilter(
+                    const ::physx::PxFilterData&,
+                    const ::physx::PxShape*,
+                    const ::physx::PxRigidActor* actor,
+                    ::physx::PxHitFlags&) override {
+                return actor == ignored ? ::physx::PxQueryHitType::eNONE : ::physx::PxQueryHitType::eBLOCK;
+            }
+
+            ::physx::PxQueryHitType::Enum postFilter(
+                    const ::physx::PxFilterData&,
+                    const ::physx::PxQueryHit&,
+                    const ::physx::PxShape*,
+                    const ::physx::PxRigidActor*) override {
+                return ::physx::PxQueryHitType::eBLOCK;
+            }
+        };
+
+        // ── State ─────────────────────────────────────────────────────────────
+
+        PhysxWorld* world_ = nullptr;
+        Settings settings_;
+        bool initialised_ = false;
+
+        std::function<void(float)> stepCallback_;
+
+        ::physx::PxRigidDynamic* chassisActor_ = nullptr;
+        ::physx::PxMaterial* wheelShapeMaterial_ = nullptr;
+
+        TransmissionMode mode_ = TransmissionMode::Automatic;
+        Direction direction_ = Direction::Drive;
+        ::physx::PxU32 manualForwardGear_ = 2;// set properly in buildCommandResponseParams
+
+        ::physx::vehicle2::PxVehicleAxleDescription axleDesc_{};
+        ::physx::vehicle2::PxVehicleRigidBodyParams rigidBodyParams_{};
+        ::physx::vehicle2::PxVehicleRigidBodyState rigidBodyState_{};
+
+        std::array<::physx::vehicle2::PxVehicleWheelParams, 4> wheelParams_{};
+        std::array<::physx::vehicle2::PxVehicleSuspensionParams, 4> suspensionParams_{};
+        std::array<::physx::vehicle2::PxVehicleSuspensionComplianceParams, 4> suspensionComplianceParams_{};
+        std::array<::physx::vehicle2::PxVehicleSuspensionForceParams, 4> suspensionForceParams_{};
+        std::array<::physx::vehicle2::PxVehiclePhysXSuspensionLimitConstraintParams, 4> suspensionLimitParams_{};
+        ::physx::vehicle2::PxVehicleSuspensionStateCalculationParams suspensionStateCalcParams_{};
+        std::array<::physx::vehicle2::PxVehicleTireForceParams, 4> tireForceParams_{};
+
+        std::array<::physx::vehicle2::PxVehicleSuspensionState, 4> suspensionStates_{};
+        std::array<::physx::vehicle2::PxVehicleSuspensionComplianceState, 4> suspensionComplianceStates_{};
+        std::array<::physx::vehicle2::PxVehicleSuspensionForce, 4> suspensionForces_{};
+        std::array<::physx::vehicle2::PxVehicleTireDirectionState, 4> tireDirectionStates_{};
+        std::array<::physx::vehicle2::PxVehicleTireSpeedState, 4> tireSpeedStates_{};
+        std::array<::physx::vehicle2::PxVehicleTireSlipState, 4> tireSlipStates_{};
+        std::array<::physx::vehicle2::PxVehicleTireGripState, 4> tireGripStates_{};
+        std::array<::physx::vehicle2::PxVehicleTireCamberAngleState, 4> tireCamberAngleStates_{};
+        std::array<::physx::vehicle2::PxVehicleTireStickyState, 4> tireStickyStates_{};
+        std::array<::physx::vehicle2::PxVehicleTireForce, 4> tireForces_{};
+
+        std::array<::physx::vehicle2::PxVehicleWheelActuationState, 4> actuationStates_{};
+        std::array<::physx::vehicle2::PxVehicleWheelRigidBody1dState, 4> wheelRigidBody1dStates_{};
+        std::array<::physx::vehicle2::PxVehicleWheelLocalPose, 4> wheelLocalPoses_{};
+        std::array<::physx::PxTransform, 4> wheelShapeLocalPoses_{
+                ::physx::PxTransform(::physx::PxIdentity),
+                ::physx::PxTransform(::physx::PxIdentity),
+                ::physx::PxTransform(::physx::PxIdentity),
+                ::physx::PxTransform(::physx::PxIdentity)};
+
+        std::array<::physx::PxReal, 4> brakeResponseStates_{};
+        std::array<::physx::PxReal, 4> steerResponseStates_{};
+
+        // ── Engine-drive params + state ──
+        ::physx::vehicle2::PxVehicleEngineParams engineParams_{};
+        ::physx::vehicle2::PxVehicleClutchParams clutchParams_{};
+        ::physx::vehicle2::PxVehicleClutchCommandResponseParams clutchResponseParams_{};
+        ::physx::vehicle2::PxVehicleGearboxParams gearboxParams_{};
+        ::physx::vehicle2::PxVehicleAutoboxParams autoboxParams_{};
+        ::physx::vehicle2::PxVehicleMultiWheelDriveDifferentialParams diffParams_{};
+
+        ::physx::vehicle2::PxVehicleEngineState engineState_{};
+        ::physx::vehicle2::PxVehicleGearboxState gearboxState_{};
+        ::physx::vehicle2::PxVehicleClutchCommandResponseState clutchResponseState_{};
+        ::physx::vehicle2::PxVehicleClutchSlipState clutchSlipState_{};
+        ::physx::vehicle2::PxVehicleAutoboxState autoboxState_{};
+        ::physx::vehicle2::PxVehicleDifferentialState diffState_{};
+        ::physx::vehicle2::PxVehicleEngineDriveThrottleCommandResponseState throttleResponseState_{};
+        ::physx::vehicle2::PxVehicleWheelConstraintGroupState constraintGroupState_{};
+
+        // Foot brake (cmd 0) + handbrake (cmd 1) response params, packed contiguously
+        // so they can be handed to the command-response component as a sized array.
+        ::physx::vehicle2::PxVehicleBrakeCommandResponseParams brakeResponseParams_{};
+        ::physx::vehicle2::PxVehicleBrakeCommandResponseParams handbrakeResponseParams_{};
+        std::array<::physx::vehicle2::PxVehicleBrakeCommandResponseParams, 2> brakeResponseParamArray_{};
+
+        ::physx::vehicle2::PxVehicleSteerCommandResponseParams steerResponseParams_{};
+
+        ::physx::vehicle2::PxVehicleCommandState commands_{};
+        ::physx::vehicle2::PxVehicleEngineDriveTransmissionCommandState transmissionCommands_{};
+
+        ::physx::vehicle2::PxVehiclePhysXActor physxActor_{};
+        ::physx::vehicle2::PxVehiclePhysXSteerState physxSteerState_{};
+        ::physx::vehicle2::PxVehiclePhysXConstraints physxConstraints_{};
+        bool constraintsCreated_ = false;
+        ::physx::vehicle2::PxVehiclePhysXRoadGeometryQueryParams physxRoadGeomQueryParams_;
+        ::physx::vehicle2::PxVehiclePhysXMaterialFriction materialFriction_{};
+        std::array<::physx::vehicle2::PxVehiclePhysXMaterialFrictionParams, 4> perWheelMaterialFriction_{};
+        std::array<::physx::vehicle2::PxVehicleRoadGeometryState, 4> roadGeometryStates_{};
+
+        ChassisQueryFilter queryFilter_{};
+
+        ::physx::vehicle2::PxVehiclePhysXSimulationContext simContext_{};
+        ::physx::vehicle2::PxVehicleComponentSequence componentSequence_{};
+        ::physx::PxU8 substepGroupHandle_ = 0;
+    };
+
+}// namespace threepp
+
+#endif//THREEPP_PHYSX_VEHICLE_ENGINE_DRIVE_HPP
diff --git a/include/threepp/extras/road/RoadGenerator.hpp b/include/threepp/extras/road/RoadGenerator.hpp
new file mode 100644
index 00000000..ca5cd85e
--- /dev/null
+++ b/include/threepp/extras/road/RoadGenerator.hpp
@@ -0,0 +1,606 @@
+// Procedural road ribbon generator (CPU).
+//
+// Pipeline:
+//   1. ctor          — sample a centripetal CatmullRomCurve3 through the supplied
+//                      control points into a dense centerline polyline (XZ
+//                      positions + cumulative arc length), and build a uniform
+//                      spatial hash so lateral "how far from the road?" queries
+//                      only scan the local 3×3 cells.
+//   2. conformTo()   — evaluate a ground-height function along the centerline,
+//                      then LONGITUDINALLY smooth it (1-2-1 passes) so the road
+//                      grade is gentle rather than tracing terrain noise. After
+//                      this the per-sample frame (smoothed height + unit tangent
+//                      + right vector) is complete; centerHeightAt/corridorWeight
+//                      /buildSurface all depend on it.
+//   3. buildSurface()/bakeSurfaceTexture() — bake the paved ribbon plus graded
+//                      shoulder strips into one indexed BufferGeometry, and bake a
+//                      matching sRGB albedo (asphalt + verge gravel + lane
+//                      markings) for the surface.
+//
+// Header-only, dependency-free beyond threepp core, so it can be reused from
+// examples and as the CPU reference for a later GPU port.
+//
+// Coordinate convention (matches TerrainGenerator): the geometry lies in the XZ
+// plane, +Y up, metres. Control-point Y is ignored — elevations come from the
+// ground function supplied to conformTo(). The road conforms to whatever terrain
+// it is draped over; corridorWeight()/groundHeight() let a demo flatten the
+// terrain into the road so the two meet seamlessly.
+
+#ifndef THREEPP_EXTRAS_ROAD_ROADGENERATOR_HPP
+#define THREEPP_EXTRAS_ROAD_ROADGENERATOR_HPP
+
+#include "threepp/core/BufferGeometry.hpp"
+#include "threepp/extras/curves/CatmullRomCurve3.hpp"
+#include "threepp/math/Vector3.hpp"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <functional>
+#include <limits>
+#include <memory>
+#include <unordered_map>
+#include <vector>
+
+namespace threepp::road {
+
+    // Configurator-facing knobs. Plain data, copyable, with sane defaults that
+    // produce a two-lane country road with gravel verges.
+    struct RoadParams {
+        float laneWidth = 3.5f;             // metres per lane
+        int   laneCount = 2;                // paved width = laneWidth * laneCount
+        float shoulderWidth = 2.5f;         // graded verge each side, beyond paved edge
+        float surfaceRaise = 0.05f;         // ribbon sits this far above conformed ground (anti z-fight)
+        float maxBanking = 0.10f;           // radians, max camber roll on tight curves
+        float bankingCurvatureScale = 30.f; // larger => need tighter curve for same banking
+        int   samplesPerSegment = 20;       // centerline tessellation between consecutive control points
+        float markingWidth = 0.16f;         // painted line width (metres)
+        bool  dashedCenter = true;          // dashed centre line vs solid
+        float textureTileLength = 12.f;     // metres of road per vertical texture tile (UV v scale)
+        std::array<float, 3> asphaltColor = {0.055f, 0.055f, 0.06f};
+        std::array<float, 3> markingColor = {0.82f, 0.78f, 0.5f};  // warm off-white
+        std::array<float, 3> shoulderColor = {0.32f, 0.30f, 0.24f};// gravel verge
+    };
+
+    class RoadGenerator {
+
+    public:
+        // controlPoints: world-space path. Their Y is ignored — elevations come
+        // from conformTo(). Needs at least two points to form a curve; with fewer
+        // the centerline degenerates to the points themselves.
+        explicit RoadGenerator(std::vector<Vector3> controlPoints, RoadParams params = {})
+            : params_(params), controlPoints_(std::move(controlPoints)) {
+            buildCenterline();
+            buildSpatialHash();
+        }
+
+        // Sample the supplied ground-height function along the centerline, store a
+        // longitudinally-SMOOTHED elevation per centerline sample (gentle grades,
+        // not terrain noise), and complete the per-sample ribbon frame. MUST be
+        // called once before buildSurface()/centerHeightAt()/corridorWeight().
+        void conformTo(const std::function<float(float, float)>& groundHeight, int smoothingPasses = 12) {
+            const size_t n = samples_.size();
+            if (n == 0) return;
+
+            // Raw ground sample at each centerline point.
+            for (size_t i = 0; i < n; ++i) {
+                samples_[i].height = groundHeight(samples_[i].pos.x, samples_[i].pos.z);
+            }
+
+            // Longitudinal 1-2-1 smoothing so the road grade is gentle. Endpoints
+            // are pinned to their sampled ground height (the road must still meet
+            // the terrain where it starts/ends); interior samples relax toward the
+            // running average of their neighbours.
+            std::vector<float> tmp(n);
+            for (int pass = 0; pass < std::max(smoothingPasses, 0); ++pass) {
+                tmp[0] = samples_[0].height;
+                tmp[n - 1] = samples_[n - 1].height;
+                for (size_t i = 1; i + 1 < n; ++i) {
+                    tmp[i] = 0.25f * samples_[i - 1].height +
+                             0.5f * samples_[i].height +
+                             0.25f * samples_[i + 1].height;
+                }
+                for (size_t i = 0; i < n; ++i) samples_[i].height = tmp[i];
+            }
+
+            conformed_ = true;
+        }
+
+        // ── geometry of the corridor ─────────────────────────────────────────
+        [[nodiscard]] float pavedHalfWidth() const {
+            return params_.laneWidth * static_cast<float>(std::max(params_.laneCount, 1)) * 0.5f;
+        }
+        [[nodiscard]] float corridorHalfWidth() const {
+            return pavedHalfWidth() + std::max(params_.shoulderWidth, 0.f);
+        }
+
+        // Lateral distance (m) from world (x,z) to the nearest point on the
+        // centerline polyline (point-to-SEGMENT, so the band is smooth).
+        [[nodiscard]] float distanceToCenter(float x, float z) const {
+            int nearest = nearestSampleIndex(x, z);
+            if (nearest < 0) return std::numeric_limits<float>::max();
+
+            // Test the segments incident to the nearest candidate sample (and its
+            // hash neighbours, gathered by nearestSampleIndex) for the true
+            // point-to-segment distance, not just point-to-point.
+            float best = std::numeric_limits<float>::max();
+            for (int idx : scratchCandidates_) {
+                // segment (idx-1, idx) and (idx, idx+1)
+                if (idx > 0) best = std::min(best, distPointToSegmentSq(x, z, idx - 1, idx));
+                if (idx + 1 < static_cast<int>(samples_.size()))
+                    best = std::min(best, distPointToSegmentSq(x, z, idx, idx + 1));
+            }
+            if (best == std::numeric_limits<float>::max()) {
+                // Degenerate: single-sample centerline — fall back to point dist.
+                const auto& p = samples_[nearest].pos;
+                const float dx = x - p.x, dz = z - p.z;
+                best = dx * dx + dz * dz;
+            }
+            return std::sqrt(best);
+        }
+
+        // 1.0 on the paved road, smoothstep down to 0.0 across the shoulder band,
+        // 0 beyond. Argument order of smoothstep gives 1 near the road, 0 at the
+        // corridor edge (so it can weight a terrain→road height blend).
+        [[nodiscard]] float corridorWeight(float x, float z) const {
+            const float d = distanceToCenter(x, z);
+            const float paved = pavedHalfWidth();
+            const float corridor = corridorHalfWidth();
+            if (d <= paved) return 1.f;
+            if (d >= corridor) return 0.f;
+            return smoothstep(corridor, paved, d);
+        }
+
+        // Smoothed centerline elevation of the nearest centerline sample to (x,z).
+        [[nodiscard]] float centerHeightAt(float x, float z) const {
+            const int nearest = nearestSampleIndex(x, z);
+            if (nearest < 0) return 0.f;
+            return samples_[nearest].height;
+        }
+
+        // Convenience blend the demo uses for its unified ground height:
+        //   mix(terrainHeight, centerHeightAt(x,z), corridorWeight(x,z))
+        [[nodiscard]] float groundHeight(float terrainHeight, float x, float z) const {
+            const float w = corridorWeight(x, z);
+            return lerp(terrainHeight, centerHeightAt(x, z), w);
+        }
+
+        // Build the paved ribbon plus graded shoulder strips as one indexed
+        // BufferGeometry. Each centerline sample emits a 4-vertex cross-section
+        //   [-corridorHalf, -pavedHalf, +pavedHalf, +corridorHalf]
+        // giving three quads per segment (left shoulder, paved, right shoulder).
+        // Paved vertices sit at height+surfaceRaise; shoulder-outer vertices sit
+        // flush at the conformed ground height. Curves bank INTO the turn (outer
+        // edge higher) by camber roll about the tangent.
+        // UV: u = 0..1 across the FULL geometry width; v = arcLength/textureTileLength.
+        [[nodiscard]] std::shared_ptr<BufferGeometry> buildSurface() const {
+            auto geo = std::make_shared<BufferGeometry>();
+            const size_t n = samples_.size();
+            if (n < 2) return geo;
+
+            const float pavedHalf = pavedHalfWidth();
+            const float corridorHalf = corridorHalfWidth();
+            const float raise = params_.surfaceRaise;
+            const float tile = std::max(params_.textureTileLength, 1e-3f);
+
+            // Lateral offsets of the four cross-section vertices, and which are
+            // paved (raised). u runs 0..1 across the full width.
+            const std::array<float, 4> off = {-corridorHalf, -pavedHalf, pavedHalf, corridorHalf};
+            const std::array<bool, 4> paved = {false, true, true, false};
+            const float fullWidth = 2.f * corridorHalf;
+            std::array<float, 4> uCoord{};
+            for (int k = 0; k < 4; ++k)
+                uCoord[k] = (fullWidth > 1e-6f) ? (off[k] + corridorHalf) / fullWidth : 0.f;
+
+            std::vector<float> positions;
+            std::vector<float> normals;
+            std::vector<float> uvs;
+            positions.reserve(n * 4 * 3);
+            normals.reserve(n * 4 * 3);
+            uvs.reserve(n * 4 * 2);
+
+            const Vector3 up{0.f, 1.f, 0.f};
+            for (size_t i = 0; i < n; ++i) {
+                const Sample& s = samples_[i];
+                // Banking: roll the cross-section about the tangent by an amount
+                // proportional to curvature, clamped to ±maxBanking. Sign chosen so
+                // the road banks into the curve (outer edge lifts).
+                const float bank = bankingAngle(i);
+                // Rotate the (right, up) basis about the tangent by `bank`. The
+                // right vector tilts toward up; the per-vertex Y gets the camber.
+                const float cb = std::cos(bank), sb = std::sin(bank);
+                // Tilted lateral & vertical basis (in the plane spanned by right & up).
+                const Vector3& right = s.right;
+                const float vScale = s.arcLength / tile;
+
+                for (int k = 0; k < 4; ++k) {
+                    const float lat = off[k];
+                    // Lateral displacement: right rotated about tangent by `bank`.
+                    // right' = right*cos(bank) + up*sin(bank)  (a roll in the cross
+                    // plane). The vertex sits at center + lat * right'.
+                    const float px = s.pos.x + lat * (right.x * cb);
+                    const float pz = s.pos.z + lat * (right.z * cb);
+                    // Camber raises the outer edge: height contribution = lat*sin(bank)
+                    // (lat sign distinguishes left/right of centerline).
+                    float py = s.height + lat * sb;
+                    if (paved[k]) py += raise;
+
+                    positions.push_back(px);
+                    positions.push_back(py);
+                    positions.push_back(pz);
+
+                    // Provisional normal (recomputed below); seed with up.
+                    normals.push_back(0.f);
+                    normals.push_back(1.f);
+                    normals.push_back(0.f);
+
+                    uvs.push_back(uCoord[k]);
+                    uvs.push_back(vScale);
+                }
+            }
+
+            // Index: 3 quads per segment, 2 triangles per quad. Cross-section of
+            // sample i occupies vertices [i*4 .. i*4+3].
+            std::vector<unsigned int> indices;
+            indices.reserve((n - 1) * 3 * 6);
+            for (size_t i = 0; i + 1 < n; ++i) {
+                const unsigned int a = static_cast<unsigned int>(i * 4);
+                const unsigned int b = static_cast<unsigned int>((i + 1) * 4);
+                for (int q = 0; q < 3; ++q) {
+                    const unsigned int v0 = a + q;       // this section, lateral k=q
+                    const unsigned int v1 = a + q + 1;   // this section, lateral k=q+1
+                    const unsigned int v2 = b + q;       // next section, lateral k=q
+                    const unsigned int v3 = b + q + 1;   // next section, lateral k=q+1
+                    // Two triangles wound so the surface normal points UP (+Y).
+                    // The cross-section `right` vector is tangent×up (the left side
+                    // for a +Z heading), so this order — not its reverse — yields the
+                    // upward face; the reverse leaves the road back-face-culled
+                    // (invisible from above) on rasterisers and lit-from-below on PT.
+                    indices.push_back(v0);
+                    indices.push_back(v1);
+                    indices.push_back(v2);
+                    indices.push_back(v1);
+                    indices.push_back(v3);
+                    indices.push_back(v2);
+                }
+            }
+
+            geo->setIndex(indices);
+            geo->setAttribute("position", FloatBufferAttribute::create(positions, 3));
+            geo->setAttribute("normal", FloatBufferAttribute::create(normals, 3));
+            geo->setAttribute("uv", FloatBufferAttribute::create(uvs, 2));
+            geo->computeVertexNormals();// recompute smooth normals from the final mesh
+            geo->computeBoundingBox();
+            geo->computeBoundingSphere();
+            return geo;
+        }
+
+        // Bake an sRGB RGBA8 albedo (row-major, `width` across road = U, `height`
+        // along road = V). Layers: gravel shoulders at the U edges, asphalt in the
+        // middle, solid edge lines just inside the paved edges, and a centre line
+        // (dashed if params.dashedCenter) down U=0.5. Subtle multi-scale noise on
+        // the asphalt keeps it from reading as flat plastic. Returns the byte buffer.
+        [[nodiscard]] std::vector<unsigned char> bakeSurfaceTexture(int width, int height) const {
+            const int W = std::max(width, 1);
+            const int H = std::max(height, 1);
+            std::vector<unsigned char> out(static_cast<size_t>(W) * H * 4, 255u);
+
+            const float corridorHalf = corridorHalfWidth();
+            const float pavedHalf = pavedHalfWidth();
+            const float fullWidth = 2.f * corridorHalf;
+            // U fractions where the paved band starts/ends (gravel outside these).
+            const float pavedFracLo = (fullWidth > 1e-6f) ? (corridorHalf - pavedHalf) / fullWidth : 0.f;
+            const float pavedFracHi = 1.f - pavedFracLo;
+            // Marking widths expressed as U fractions.
+            const float markFrac = (fullWidth > 1e-6f) ? params_.markingWidth / fullWidth : 0.f;
+            // Centres of the two solid edge lines (just inside the paved edges).
+            const float edgeLineLo = pavedFracLo + markFrac;
+            const float edgeLineHi = pavedFracHi - markFrac;
+            // Dash pattern along V (in texel rows): ~3 m on, 6 m of gap per tile.
+            const float dashPeriod = std::max(static_cast<float>(H) * 0.18f, 2.f);
+
+            const auto setPx = [&](int x, int y, float r, float g, float b) {
+                const size_t o = (static_cast<size_t>(y) * W + x) * 4;
+                out[o + 0] = toByte(r);
+                out[o + 1] = toByte(g);
+                out[o + 2] = toByte(b);
+                out[o + 3] = 255u;
+            };
+
+            for (int y = 0; y < H; ++y) {
+                const float v = static_cast<float>(y);
+                for (int x = 0; x < W; ++x) {
+                    const float u = (W > 1) ? static_cast<float>(x) / static_cast<float>(W - 1) : 0.5f;
+
+                    float r, g, b;
+                    if (u < pavedFracLo || u > pavedFracHi) {
+                        // Gravel shoulder — noisy verge colour.
+                        const float n = fbm(static_cast<float>(x) * 0.18f, v * 0.18f, 4, 2.f, 0.5f);
+                        const float k = std::clamp(1.f + 0.22f * n, 0.6f, 1.35f);
+                        r = params_.shoulderColor[0] * k;
+                        g = params_.shoulderColor[1] * k;
+                        b = params_.shoulderColor[2] * k;
+                    } else {
+                        // Asphalt base + multi-scale grain (de-plastic idiom).
+                        const float n1 = fbm(static_cast<float>(x) * 0.22f, v * 0.22f, 4, 2.f, 0.5f);
+                        const float n2 = noise2(static_cast<float>(x) * 0.9f, v * 0.9f);
+                        const float k = std::clamp(1.f + 0.18f * n1 + 0.10f * n2, 0.7f, 1.3f);
+                        r = params_.asphaltColor[0] * k;
+                        g = params_.asphaltColor[1] * k;
+                        b = params_.asphaltColor[2] * k;
+
+                        // Solid edge lines.
+                        const bool onEdgeLo = std::abs(u - edgeLineLo) <= markFrac * 0.5f;
+                        const bool onEdgeHi = std::abs(u - edgeLineHi) <= markFrac * 0.5f;
+                        // Centre line at U=0.5 (dashed if requested).
+                        bool onCenter = std::abs(u - 0.5f) <= markFrac * 0.5f;
+                        if (onCenter && params_.dashedCenter) {
+                            const float phase = std::fmod(v, dashPeriod) / dashPeriod;
+                            onCenter = phase < 0.4f;// ~40% duty cycle => dash
+                        }
+                        if (onEdgeLo || onEdgeHi || onCenter) {
+                            // Slightly noisy paint so it isn't a flat stripe.
+                            const float pn = noise2(static_cast<float>(x) * 0.6f, v * 0.6f);
+                            const float pk = std::clamp(1.f + 0.06f * pn, 0.85f, 1.1f);
+                            r = params_.markingColor[0] * pk;
+                            g = params_.markingColor[1] * pk;
+                            b = params_.markingColor[2] * pk;
+                        }
+                    }
+                    setPx(x, y, r, g, b);
+                }
+            }
+            return out;
+        }
+
+        // ── spawn helpers ────────────────────────────────────────────────────
+        // First centerline sample position (with conformed elevation).
+        [[nodiscard]] Vector3 startPoint() const {
+            if (samples_.empty()) return Vector3::ZEROS();
+            const Sample& s = samples_.front();
+            return Vector3(s.pos.x, s.height, s.pos.z);
+        }
+        // Unit tangent at the start (XZ, Y=0).
+        [[nodiscard]] Vector3 startForward() const {
+            if (samples_.empty()) return Vector3(0.f, 0.f, 1.f);
+            return samples_.front().tangent;
+        }
+        // Dense centerline polyline with conformed elevations (debug / markers).
+        [[nodiscard]] const std::vector<Vector3>& centerlineSamples() const {
+            // Lazily refresh the cached Vector3 view (positions + conformed Y).
+            centerlineView_.resize(samples_.size());
+            for (size_t i = 0; i < samples_.size(); ++i)
+                centerlineView_[i] = Vector3(samples_[i].pos.x, samples_[i].height, samples_[i].pos.z);
+            return centerlineView_;
+        }
+
+    private:
+        // Per-centerline-sample frame.
+        struct Sample {
+            Vector3 pos{};      // XZ position (Y unused; height stored separately)
+            float arcLength = 0.f;// cumulative arc length from the start
+            float height = 0.f; // smoothed centerline elevation (after conformTo)
+            Vector3 tangent{0.f, 0.f, 1.f};// unit forward (XZ)
+            Vector3 right{1.f, 0.f, 0.f};  // unit right = tangent × up, normalised (XZ)
+        };
+
+        // ── centerline construction ──────────────────────────────────────────
+        void buildCenterline() {
+            samples_.clear();
+            if (controlPoints_.empty()) return;
+
+            if (controlPoints_.size() == 1) {
+                Sample s;
+                s.pos = controlPoints_[0];
+                s.pos.y = 0.f;
+                samples_.push_back(s);
+                return;
+            }
+
+            // Flatten control points onto Y=0 for the curve (elevations come later).
+            std::vector<Vector3> flat;
+            flat.reserve(controlPoints_.size());
+            for (const auto& cp : controlPoints_) flat.emplace_back(cp.x, 0.f, cp.z);
+
+            CatmullRomCurve3 curve(flat, /*closed*/ false, CatmullRomCurve3::centripetal);
+
+            const int sps = std::max(params_.samplesPerSegment, 1);
+            const int total = static_cast<int>(controlPoints_.size() - 1) * sps + 1;
+
+            samples_.reserve(static_cast<size_t>(total));
+            Vector3 p{};
+            for (int i = 0; i < total; ++i) {
+                const float t = (total > 1) ? static_cast<float>(i) / static_cast<float>(total - 1) : 0.f;
+                curve.getPoint(t, p);
+                Sample s;
+                s.pos = Vector3(p.x, 0.f, p.z);
+                samples_.push_back(s);
+            }
+
+            // Cumulative arc length along the XZ polyline.
+            samples_[0].arcLength = 0.f;
+            for (size_t i = 1; i < samples_.size(); ++i) {
+                const Vector3& a = samples_[i - 1].pos;
+                const Vector3& b = samples_[i].pos;
+                const float dx = b.x - a.x, dz = b.z - a.z;
+                samples_[i].arcLength = samples_[i - 1].arcLength + std::sqrt(dx * dx + dz * dz);
+            }
+
+            // Unit tangent (central difference) and right vector (tangent × up).
+            const Vector3 up{0.f, 1.f, 0.f};
+            const size_t n = samples_.size();
+            for (size_t i = 0; i < n; ++i) {
+                const size_t im = (i == 0) ? 0 : i - 1;
+                const size_t ip = (i + 1 < n) ? i + 1 : n - 1;
+                Vector3 tan(samples_[ip].pos.x - samples_[im].pos.x, 0.f,
+                            samples_[ip].pos.z - samples_[im].pos.z);
+                if (tan.length() < 1e-6f) tan = Vector3(0.f, 0.f, 1.f);
+                tan.normalize();
+                samples_[i].tangent = tan;
+                // right = tangent × up  (points to the +X side of a +Z heading).
+                Vector3 right = tan.clone().cross(up);
+                if (right.length() < 1e-6f) right = Vector3(1.f, 0.f, 0.f);
+                right.normalize();
+                samples_[i].right = right;
+            }
+        }
+
+        // ── spatial hash for nearest-sample queries ──────────────────────────
+        void buildSpatialHash() {
+            cellSize_ = std::max(corridorHalfWidth(), 0.5f);
+            hash_.clear();
+            for (size_t i = 0; i < samples_.size(); ++i) {
+                const auto key = cellKey(samples_[i].pos.x, samples_[i].pos.z);
+                hash_[key].push_back(static_cast<int>(i));
+            }
+        }
+
+        [[nodiscard]] long long cellKey(float x, float z) const {
+            const int cx = static_cast<int>(std::floor(x / cellSize_));
+            const int cz = static_cast<int>(std::floor(z / cellSize_));
+            return packKey(cx, cz);
+        }
+        static long long packKey(int cx, int cz) {
+            // Pack two 32-bit cell coords into one 64-bit key.
+            return (static_cast<long long>(static_cast<unsigned int>(cx)) << 32) |
+                   static_cast<unsigned int>(cz);
+        }
+
+        // Gather candidate sample indices from the 3×3 neighbour cells and return
+        // the nearest-by-point index. Populates scratchCandidates_ for the caller
+        // (distanceToCenter uses it for point-to-segment). Falls back to scanning
+        // every sample if the local cells are empty (correctness over speed).
+        [[nodiscard]] int nearestSampleIndex(float x, float z) const {
+            scratchCandidates_.clear();
+            if (samples_.empty()) return -1;
+
+            const int cx = static_cast<int>(std::floor(x / cellSize_));
+            const int cz = static_cast<int>(std::floor(z / cellSize_));
+            for (int dz = -1; dz <= 1; ++dz)
+                for (int dx = -1; dx <= 1; ++dx) {
+                    auto it = hash_.find(packKey(cx + dx, cz + dz));
+                    if (it == hash_.end()) continue;
+                    for (int idx : it->second) scratchCandidates_.push_back(idx);
+                }
+
+            if (scratchCandidates_.empty()) {
+                // No populated neighbour cells — scan all samples.
+                scratchCandidates_.resize(samples_.size());
+                for (size_t i = 0; i < samples_.size(); ++i)
+                    scratchCandidates_[i] = static_cast<int>(i);
+            }
+
+            int best = -1;
+            float bestSq = std::numeric_limits<float>::max();
+            for (int idx : scratchCandidates_) {
+                const auto& p = samples_[idx].pos;
+                const float ddx = x - p.x, ddz = z - p.z;
+                const float dSq = ddx * ddx + ddz * ddz;
+                if (dSq < bestSq) {
+                    bestSq = dSq;
+                    best = idx;
+                }
+            }
+            return best;
+        }
+
+        // Squared point-to-segment distance against segment (i0, i1) in XZ.
+        [[nodiscard]] float distPointToSegmentSq(float x, float z, int i0, int i1) const {
+            const Vector3& a = samples_[i0].pos;
+            const Vector3& b = samples_[i1].pos;
+            const float abx = b.x - a.x, abz = b.z - a.z;
+            const float apx = x - a.x, apz = z - a.z;
+            const float abLenSq = abx * abx + abz * abz;
+            float t = (abLenSq > 1e-12f) ? (apx * abx + apz * abz) / abLenSq : 0.f;
+            t = std::clamp(t, 0.f, 1.f);
+            const float cx = a.x + t * abx, cz = a.z + t * abz;
+            const float dx = x - cx, dz = z - cz;
+            return dx * dx + dz * dz;
+        }
+
+        // ── banking ──────────────────────────────────────────────────────────
+        // Signed camber roll (radians) at sample i, banked INTO the curve so the
+        // outer edge lifts. Curvature is estimated from the turn of the tangent
+        // between the neighbouring samples (the signed XZ cross product).
+        [[nodiscard]] float bankingAngle(size_t i) const {
+            const size_t n = samples_.size();
+            if (n < 3 || i == 0 || i + 1 >= n) return 0.f;
+            const Vector3& t0 = samples_[i - 1].tangent;
+            const Vector3& t1 = samples_[i + 1].tangent;
+            // Signed turn: cross.y of the two XZ tangents (>0 = left turn).
+            const float cross = t0.z * t1.x - t0.x * t1.z;
+            // Normalise the turn by an arc-length span so it reads as curvature.
+            const float ds = std::max(samples_[i + 1].arcLength - samples_[i - 1].arcLength, 1e-3f);
+            const float curvature = cross / ds;// signed (1/m)-ish
+            const float t = std::clamp(curvature * params_.bankingCurvatureScale, -1.f, 1.f);
+            // Sign: a left turn (cross>0) should lift the right (+lat) edge so the
+            // road banks into the curve. lat*sin(bank) is the per-vertex camber, so
+            // bank>0 lifts +lat. Left turn => outer edge is +lat => bank>0. Matches t.
+            return t * params_.maxBanking;
+        }
+
+        // ── small numeric helpers (mirrors TerrainGenerator) ─────────────────
+        static float lerp(float a, float b, float t) { return a + t * (b - a); }
+        static float smoothstep(float e0, float e1, float x) {
+            const float t = std::clamp((x - e0) / (e1 - e0), 0.f, 1.f);
+            return t * t * (3.f - 2.f * t);
+        }
+        static unsigned char toByte(float v) {
+            return static_cast<unsigned char>(std::clamp(v, 0.f, 1.f) * 255.f + 0.5f);
+        }
+
+        // ── value-noise / fBm for asphalt grain (deterministic, hash-based) ──
+        // Self-contained integer hash so the generator needs no permutation table
+        // and the texture is reproducible across runs.
+        static float hash2(int x, int y) {
+            unsigned int h = static_cast<unsigned int>(x) * 374761393u +
+                             static_cast<unsigned int>(y) * 668265263u;
+            h = (h ^ (h >> 13)) * 1274126177u;
+            h ^= h >> 16;
+            return static_cast<float>(h & 0xFFFFFFu) / static_cast<float>(0xFFFFFF) * 2.f - 1.f;
+        }
+        static float fade(float t) { return t * t * t * (t * (t * 6.f - 15.f) + 10.f); }
+        // 2D value noise, output ~[-1, 1].
+        static float noise2(float x, float y) {
+            const int xi = static_cast<int>(std::floor(x));
+            const int yi = static_cast<int>(std::floor(y));
+            const float xf = x - static_cast<float>(xi);
+            const float yf = y - static_cast<float>(yi);
+            const float u = fade(xf), v = fade(yf);
+            const float n00 = hash2(xi, yi);
+            const float n10 = hash2(xi + 1, yi);
+            const float n01 = hash2(xi, yi + 1);
+            const float n11 = hash2(xi + 1, yi + 1);
+            const float x1 = lerp(n00, n10, u);
+            const float x2 = lerp(n01, n11, u);
+            return lerp(x1, x2, v);
+        }
+        static float fbm(float x, float y, int oct, float lac, float gain) {
+            float f = 1.f, a = 1.f, sum = 0.f, norm = 0.f;
+            for (int i = 0; i < oct; ++i) {
+                sum += a * noise2(x * f, y * f);
+                norm += a;
+                f *= lac;
+                a *= gain;
+            }
+            return norm > 0.f ? sum / norm : 0.f;
+        }
+
+        RoadParams params_;
+        std::vector<Vector3> controlPoints_;
+        std::vector<Sample> samples_;
+        bool conformed_ = false;
+
+        // Spatial hash (cell == corridorHalfWidth so a query scans 3×3 cells).
+        float cellSize_ = 1.f;
+        std::unordered_map<long long, std::vector<int>> hash_;
+
+        // Mutable scratch reused by the const query path (no per-call allocation
+        // on the hot path; not part of the logical const state).
+        mutable std::vector<int> scratchCandidates_;
+        mutable std::vector<Vector3> centerlineView_;
+    };
+
+}// namespace threepp::road
+
+#endif//THREEPP_EXTRAS_ROAD_ROADGENERATOR_HPP