threejs-vehicles
v0.1.0
Published
Procedural animated vehicles for three.js: cars, bicycles, trains, boats, ships, aircraft and rockets on generated networks
Maintainers
Readme
threejs-vehicles
Procedural, animated vehicles for three.js. The package covers cars (sedan, hatchback, SUV, pickup, van, bus), bicycles, trains (a locomotive plus passenger and freight wagons), fishing boats, cruise liners, speedboats, hovercraft, aircraft carriers, airliners and light aircraft, fighter jets and multi-stage rockets.
Every vehicle is a seeded, low-poly generator, so the variety looks random but never is.
Fleets draw thousands of them in a few draw calls:
- Cars and bikes follow a
threejs-cityroad graph. - Trains pull their wagons along rails.
- Boats bob, roll and leave wakes on
threejs-waterwaves. - Planes bank through their turns.
- Rockets launch and drop their stages.
- Carriers host parked jets.
Every vehicle can get wet, snowy, burnt, set on fire and damaged through threejs-weathering's per-instance states. Damage also dents, lists and stops them.
npm i threejs-vehicles threethree.js
import * as THREE from 'three/webgpu'
import { Fleet, Vehicle, circlePoints } from 'threejs-vehicles'
const renderer = new THREE.WebGPURenderer({ antialias: true })
await renderer.init()
const scene = new THREE.Scene()
const fleet = new Fleet({
seed: 7,
groups: [
{ type: 'car', count: 400, route: { kind: 'roads' } }, // random walk on the road graph
{ type: 'bicycle', count: 40, route: { kind: 'roads' } },
{ type: 'train', count: 1, params: { wagons: 8, cargo: 'mixed' }, route: { kind: 'path', points: railPoints } },
{ type: 'fishing-boat', count: 6, route: { kind: 'circle', center: [900, 0, 0], radius: 200 } },
{ type: 'aircraft-carrier', count: 1, route: { kind: 'circle', center: [3000, 0, 0], radius: 1500 } },
{ type: 'fighter-jet', count: 6, route: { kind: 'host', group: 4 } }, // parked on the carrier's deck
{ type: 'airplane', count: 3, route: { kind: 'path', points: circlePoints([0, 700, 0], 2500) } },
{ type: 'rocket', count: 1, route: { kind: 'pad', position: [-400, 0, 800], period: 120 } },
],
waves: ocean.settings.waves, // boats bob on the same waves the ocean draws
}, { roads: city.graph }) // threejs-city's RoadGraph, or any { nodes, edges } graph
scene.add(fleet.object)
renderer.setAnimationLoop(() => {
fleet.update(undefined, { weather, time: sky.clock.time, fire: wildfire, field: stateField }) // all optional
renderer.render(scene, camera)
})
fleet.set({ exposure: { snowfall: 1 } }) // parked cars collect snow, moving ones shed it
fleet.set({ lights: sky.night }) // headlights and lit windows
fleet.ignite(12) // vehicle 12 catches fire, burns, stops
fleet.set({ states: { wetness: 1 } }) // everything soaked at once
const bus = new Vehicle({ type: 'car', params: { style: 'bus' }, seed: 3, speed: 8 }) // one hero vehicle, wheels turning
scene.add(bus.object)Plausible placement, and registering every vehicle in the threejs-worldgen asset registry:
import { planRoute, vehicleAssets, VEHICLE_PLACEMENT } from 'threejs-vehicles'
import { AssetRegistry, isPlausible } from 'threejs-worldgen'
const plausible = (x, z, rule) => isPlausible(world, frame, x, z, rule)
const harbour = planRoute('fishing-boat', world, frame, { center: [x, z], radius: 300, plausible }) // a loop on water ≥ 3 m deep
const skies = planRoute('airplane', world, frame, { center: [x, z], radius: 3000 }) // ≥ 300 m above the highest ground
new AssetRegistry().register(...vehicleAssets())React Three Fiber
import { Fleet, Vehicle } from 'threejs-vehicles/react'
<Fleet roads={city.graph} groups={[{ type: 'car', count: 300, route: { kind: 'roads' } }]} lights={night} exposure={{ rain: 1 }} env={{ fire }} />
<group position={[0, 0, 5]}><Vehicle type="car" params={{ style: 'suv' }} speed={6} states={{ snow: 0.7 }} /></group>react and @react-three/fiber are optional peer dependencies; the core never imports them. Props are the JSON settings: every render calls reset(props), which rebuilds only when groups or seed change. update() runs in useFrame.
What's in the box
| Export | What it does |
|---|---|
| Fleet | Instanced vehicles: one InstancedMesh per model part (bodies, wheels, fans, propellers, rocket stages), one shared single-material TSL shader, plume, flame and wake effects. set/reset, update(dt, env), ignite, setStates, vehicle(i), setRoads |
| Vehicle | One vehicle (a fleet of one) standing in place with its parts animating; for heroes, galleries and spawned assets |
| FleetSim | The GPU-free core: groups → units (trains = locomotive + wagons) → vehicles. Poses, speeds, steering, banking, wave bobbing, damage tilt and weather exposure live in typed arrays |
| buildVehicle, VEHICLE_KINDS, VEHICLE_TYPES | Seeded generators for all 11 types, with JSON parameters, defaults and ranges |
| Path, catmullRom, circlePoints | Arc-length spline paths: closed loops, and open ones driven back and forth |
| RoadNavigator, RoadNetwork | Lane-keeping random walk over a road graph, seeded junction choices and rounded corners. RoadGraph from threejs-city fits as it is |
| rocketAt | Analytic gravity-turn ascent (scrubbable) |
| planRoute, fitsRule, VEHICLE_PLACEMENT | Plausible routes per type (water depth, ground slope, air clearance, flat pads near water). Rules match threejs-worldgen's PlacementRule |
| vehicleAssets | Every type as an AssetDef for threejs-worldgen's AssetRegistry |
| MeshBuilder | The typed-array, flat-shaded low-poly builder behind the models (box, cylinder, tube, ellipsoid, loft, fin, beam) |
| createVehicleMaterial, createFxMaterial, createWakeMaterial | The TSL materials |
Vehicle types
| Type | Parameters (defaults) |
|---|---|
| car | style (mixed, sedan, hatchback, suv, truck, van, bus), size 1 |
| bicycle | style (mixed, road, city, mountain), rider true |
| train | car (locomotive, passenger, freight), freight (mixed, boxcar, tank, hopper, container), wagons 5, cargo (passenger, freight, mixed), size 1 |
| fishing-boat | length 13, outriggers true |
| cruise-liner | length 200, decks 7, funnels 1 |
| speedboat | length 7, cabin false |
| hovercraft | length 20, fans 2 |
| aircraft-carrier | length 300, angledDeck true, spots 8 (parking spots for jets) |
| airplane | style (airliner, light, mixed), length 38, engines 2 |
| fighter-jet | style (mixed, delta, twin-tail), length 16 |
| rocket | height 60, stages 2, boosters 0, fins true, pad true |
Fleet options
| Option | Default | What it does |
|---|---|---|
| seed | 1 | Same seed and groups, same fleet |
| groups | a ring of 16 cars | { type, count, params, variants 4, route, speed, lane, tint }. Routes: path, circle, roads, static, pad, host |
| timeScale | 1 | Simulation speed |
| lights | 0 | Headlights and lit windows, 0…1 (drive it from sky.night) |
| crumple, tilt | 0.12, 1 | Dent depth and list/sink at full damage |
| leftHand | false | Drive on the left on road graphs |
| waves | null | threejs-water WaveOptions boats bob on |
| wakes, exhaust, flames | true | Boat wakes, rocket plumes and afterburners, flames on burning vehicles |
| castShadow, receiveShadow | true | Shadows (every part is single-material, so the shadow pass works) |
| states | all 0 | wetness, snow, burn, damage, heat (on fire), applied to every vehicle when changed |
| exposure | | rain, snowfall (0…1 everywhere when no Weather is given), wetRate, dryRate, snowRate, meltRate, shedSpeed, shedRate, ignition, burnRate, burnTime, fireDamage, douseTime, stopDamage, budget (vehicles sampled per frame) |
| rocket | | accel 9, turn 5000, separation [32, 70] s, fallTime 40 s |
update(dt, env) reacts to an optional environment, all in fleet-local coordinates:
weather: anything withsurfaceAt(x, z, time), such as threejs-weathering'sWeather. It sets wetness and snow.fire: anything withheatAt(x, z), such asWildfire. Vehicles caught in it burn and stop.field: anything withsample(x, z), such asStateField. It applies storm damage.
License
Apache-2.0
