Phaser home
Log inCreate a game

← Expansion packsArcade

Phaser AE

Vehicle handling

Pro packv3.0.0-32DArcade

How an arcade car, bike, kart or boat moves: the engine and gears, boosts, steering, grip, skids and spins, surfaces, bike lean, jumps and the response to every collision. It runs on a road or on a flat top-down plane with the same parameters, so one model serves every kind of racer.

This is a Pro pack. Upgrade to Phaser Pro to use it in your games.See Phaser Pro →

Released October 14, 2026 · updated October 19, 2026

Vehicle handling: a screenshot of its demo
A note about these graphics

Expansion packs don't come with graphics. This screenshot is one way of drawing what the pack does, made for its demo: none of the sprites, tiles or backgrounds in it are in the pack.

That's by design. A pack is a game's logic, mechanics and effects, and it works with whatever art you give it. Some packs draw effects, backdrops or 3D scenes of their own, but none carries a game's sprites.

So the look is yours. Make the art on phaser.io, bring your own, or let your agent draw it in code: the same pack can look like anything.

What it does

You create a vehicle from a spec and step it each frame with the driver's input, the throttle, brake, steering, gear and boost, and what lies under it: the surface, and on a road the curve, the hill and the edges. The vehicle answers with its new state and a list of events (gear, skid-start, spin-start, offroad, boost-start, airborne, landed, fall and more) for the sound and effects. It does not own the track. Geometry, collision detection, laps, timers and traffic belong to the rules pack or your game, which tells the vehicle what it touched and lets it decide how to respond.

It works in two frames with one set of parameters. In the road frame a vehicle has a distance along the road and an offset across it, and curves push it outward with speed, which is what a behind-the-car pseudo-3D racer or a scrolling road needs. In the planar frame it has a position, a heading, a velocity and a yaw rate, so a top-down car rotates and its momentum lags behind, sliding round the bend. Grip, skids, surfaces, boosts and collisions mean the same thing in both.

Surfaces are data. Each has grip, traction, drag, a speed cap, steering and rumble, and can spin a car on entry or stay on its tyres for a while, as oil does. A vehicle can override any of them, so a boat drives on water that a car treats as a hazard. Gravity drives hills, banked roads, ridable walls and jumps through one airborne model, and a landing bounces, spins or crashes depending on how hard and how crooked it was. The whole thing is deterministic, fixed-step and snapshot-able.

Features

  • Engines and gears — throttle and brake curves, acceleration by speed per gear, automatic, two-speed LOW/HIGH and multi-gear manual boxes with shift time and engine braking, and a pedal that sets a target speed.
  • Boosts — a turbo held above a minimum speed, or timed nitros with charges and a cooldown, with steering made heavier while they burn.
  • Grip and slides — steering by speed, understeer and oversteer, drifts that keep momentum, skids that scrub speed, and spin-outs from a slide, from oil or on demand.
  • Surfaces as data — tarmac, kerb, grass, sand, gravel, dirt, mud, water, oil, ice, snow and your own, with per-vehicle overrides.
  • Bikes — lean with rate and speed limits, counter-steer, and falls when the lean goes too far, or none.
  • Jumps and gravity — ramps, crests and launches into one airborne model, landings described as data, banked roads, ridable walls, tunnel roofs and two-wheel tips.
  • Collisions — restitution and friction against walls and other vehicles, knock-back between two vehicles with resolveVehicles, and every impact classified as a scrape, bump, sideswipe, wall slide or crash.
  • Seventeen presets — car, bike, kart, truck and boat specs in PRESETS, among them the neutral arcadeCar and arcadeBike starting points.
  • Difficulty and upgrades — withAssist for Easy, Normal and Arcade handling, and upgradeSpec for levels of grip, acceleration and top speed bought in a shop.
  • Helpers for drivers and units — cornerSpeed, stoppingDistance and steerToward for computer drivers, and scaleSpec to put a spec in metres into your game's units.

Good for

  • Behind-the-car road racers with gears, curves and off-road verges, in the style of Out Run or Pole Position.
  • Motorbike racers where the rider leans into bends and can come off, in the style of Hang-On.
  • Top-down circuit racers where cars rotate and slide round bends, in the style of Super Sprint.
  • Road combat games that ram cars off a scrolling road and swap the car for a boat, in the style of Spy Hunter.
  • Off-road buggy racing over logs, rocks and banked sides, with jumps and two-wheel tips, in the style of Buggy Boy.
  • Karts, jet-skis and sleds — a high-grip kart with a timed boost, a course where water is the road, or a downhill run with no engine.
  • Traffic and rivals in any driving game, using the same model as the player's car.

Make it yours

Everything is per vehicle, through its spec and createVehicle. The gearbox, its gears and their acceleration curves, the throttle mode, boosts, steering, grip, spin thresholds, surfaces, bike lean and falls, airborne behaviour and landings, banking and collision response are all fields of the spec. Start from a preset, give it an assist level, scale it to your units, and change what you need. Surfaces can be added for the whole game or overridden for one vehicle, and an unknown surface id can map to a fallback rather than throw.

Two very different uses: a road-frame motorbike with lean steering, a held turbo above its top speed and falls when it leans too far, racing down a pseudo-3D road whose curvature the road renderer supplies; and a planar top-down car on a single screen, upgraded by its rules pack with extra grip and top speed, spinning out on oil and bouncing off walls the track reports. A police chase on ice everywhere, or a downhill sled on a road-frame hill with no engine, are a change of surface and spec rather than new code.

A quick look

A top-down car scaled to six pixels a metre, stepped over the surface beneath it:

const H = game.vehicleHandling;
const spec = H.scaleSpec(H.withAssist(H.presets.superSprintCar(), 'normal'), 6);
const car = H.createVehicle({ frame: 'planar', spec, at: { x: 120, y: 300, heading: -Math.PI / 2 } });
const events = car.step({ throttle: 1, steer: -0.6 }, { surface: track.surfaceAt(car.state.x, car.state.y) });
car.contact({ normal, depth, kind: 'wall' });   // a scrape, bump, sideswipe, wall slide or crash
car.setSpec(H.upgradeSpec(spec, { grip: 2, top: 1 }));

Works with

  • road-racer — behind-the-car racing rules on the road frame, with traffic and crashes.
  • track-racer — top-down circuit racing rules on the planar frame, with computer drivers and upgrades.
  • road-combat — a scrolling road with rams, bands of water, ice and oil, and the boat swap.
  • road-view-pseudo3d and road-view-topdown — draw what the vehicle's state describes.
  • road-data — road files whose samples pass straight into the road frame.
  • thrust-craft — for rotate-and-thrust flight rather than driving.
  • physics-box2d — for general rigid bodies rather than arcade handling.

Good to know

  • A vehicle is a point with a heading: hitboxes and overlap tests are your game's or the rules pack's, which pass in the contact normal.
  • Planar collisions change velocity only, with no angular impulse, so a hit spins a car only through a slide or a call to spin().
  • The vertical model is a point too, with no suspension or pitch and roll dynamics; pitch and roll are reported for drawing.
  • Some preset numbers are estimates tuned by feel rather than taken from a source, and the presets' docs mark them.
  • It is arcade handling, not a driving simulation of tyres and suspension.

More Arcade packs

Show all →