Publishing a model

Updated 2026-07-31 by webcars2@lantiainen.com

Where a finished car or track goes, and how it reaches players.

There is no export step

This surprises people who have shipped models to other engines. The .bbmodel file is the master, and the game loads it directly. There is no convert, no bake, no .glb, no build artefact.

The workflow is: edit the .bbmodel, reload the page. That is all of it.

Where files live

models/cars/<id>/<id>.bbmodel
models/tracks/<id>/<id>.bbmodel

The <id> is the short name used in URLs and in the roster — lowercase, dashes, no spaces. porsche-safari, night-city, my-first-car.

Two folders are not for your work:

models/generated/ is regenerated by a script and will overwrite you.
backend/src/cars_game/web/ is build output and is not committed at all.

Getting it into the game

A saved file under models/cars/ or models/tracks/ is served automatically in development — the dev server publishes it at /models/<file>.bbmodel and bundles it into production builds. Nothing to register, nothing to copy.

To make it appear in the menus, add one entry to the roster:

cars: game/src/game/builtInCars.ts
tracks: game/src/game/builtInTracks.ts

One line each: id, name, a short blurb, and the URL of the file.

Trying it before you commit

You do not have to add a roster entry to test. Both pickers accept a file straight from disk:

the Garage's + frame opens a file dialog for a car
the track list has a Load Track (.bbmodel)… entry

Drag your file in and drive it. This is the same code path a shipped model takes, so if it works here it will work when installed.

Checks worth running

cd game && npm test              # includes the model-parity goldens
cd game && npm run check:tracks  # drives every track end to end

If you changed a shipped model deliberately, the golden snapshots need regenerating, or the parity test will fail on your intentional change:

cd game && UPDATE_GOLDENS=1 npm test -- modelParity

Only do that when the change was intended. The goldens exist to catch models changing when nobody meant them to.

Textures

Embed them. A .bbmodel whose textures are linked to files on disk opens empty on a machine that does not have those files — which is every machine except yours. Blockbench can embed them, and there is a script in the repo that unlinks an existing model's textures if you forget.

Size

Models are bundled into the deployed application, which has a hard payload limit. A few hundred cubes is comfortable; a few thousand is not. Prefer:

one shape that reads well over five that are technically more accurate
scenery (no collider) for anything the player cannot touch
reusing an existing prop from the prop library rather than modelling a new one

Web Cars 2 wiki