Designing a track
How to build a drivable course. Tracks are Blockbench models like cars, loaded directly with no export step, but the parts mean different things.
What a track is made of
| Group name | What it does |
|---|---|
ground | the drivable surface — solid, the car rolls on it |
spawn | where the car starts |
prop | objects the car can hit, push or knock over |
scenery | looks only, no collider — backdrop, buildings, trees behind the road |
parallax | scrolling background layers |
death | a zone that resets the car (pits, spikes, water) |
finish | the finish line that stops the timer |
Only ground and spawn are required. A flat strip with a spawn point on it is a valid track, and a good thing to load first to check your naming works before you build anything interesting.
Build the road as a continuous surface
This is the single most important thing on the page.
Lay ground cubes so that consecutive pieces share their top edge. Do not hand-place rotated boxes to make a slope. A rotated box leaves a step at the seam where it meets its neighbour, and that step becomes an invisible wall the car slams into at speed.
The symptom is unmistakable once you know it: the car is driving fine, then stops dead at a spot that looks like flat ground. If that happens, you have a seam, not a physics bug.
The track generators in the repository build ground from a surface polyline for exactly this reason. If you are authoring by hand, keep your ground pieces flush and axis-aligned, and make slopes out of many short pieces rather than one long tilted one.
Surfaces
Put a surface on a ground group and the grip changes:
ground;surface=ice| Surface | Feel |
|---|---|
tarmac | full grip, the default |
dirt | slightly loose |
sand | heavy drag, hard to accelerate |
snow | slippery, moderate drag |
ice | almost no grip |
Wheel slip is not scripted — it falls out of the friction. An ice section is genuinely hard to climb because the tyres cannot bite, which is what makes it interesting to drive.
Making a course rather than a strip
A track that is fun usually has a shape to it:
- Open easy. Give the player 50–100 m of flat ground to get up to speed and learn the car before anything is asked of them.
- One idea at a time. A jump, then a climb, then a narrow bridge — not all three at once.
- Escalate. Repeat an obstacle later, bigger.
- Land somewhere generous. A jump whose landing is a wall is a trap, not a challenge. Give the landing a downslope.
- Finish visibly. Put the
finishgroup somewhere the player can see coming.
Hazards
deathgroups reset the car where they touch it — use them under gaps, in spike pits and below the whole course as a floor of last resort.- Props with
explodes=truedetonate on a hard hit. - Props with
crumbles=truecollapse when driven into. - Props with
shatters=truebreak apart.
A death floor running the whole length of the track, well below the road, is worth adding to every course. Without one, a car that falls off the world just keeps falling and the player has to restart manually.
Trying it
Reload the page and open ?screen=tracks. Yours appears in the list once it is in the roster.
Two automated checks are worth running:
?screen=tracktestsdrives every track end to end and reports how far the car got. If yours stops early, there is a wall, a trap or a dead spawn at that distance.npm run check:tracksis the same thing from the command line.
These are playability checks, not a guarantee the track can be completed — they tell you the course is not broken, not that it is good.
Common problems
The car crashes into flat ground. A ground seam. See above; this is almost always it.
The car falls through the world at one spot. A gap between ground pieces.
Everything looks like it is floating. Scenery stands behind the drivable strip, so without ground behind it there is nothing under the trees. The repo's generators add an "apron" of visual-only ground for this.
The track loads but the car will not move. The spawn is inside geometry.