How to make vehicle mods in Project Zomboid B42

Vehicles are among the most requested mods in the community, especially since a lot of Build 41 packs were never updated. They're also among the most complicated. This guide collects what we learned with ChileCars (Carabineros police cars, a taxi, a mail truck) and Wanaco (the water cannon truck). Carabineros is Chile's national police; "guanaco" is the Chilean nickname for their water cannon trucks.

The pieces of a vehicle

Piece	Where	What it is
3D model	`media/models_X/vehicles/`	The body (a single mesh with a single UV map)
Texture	`media/textures/Vehicles/`	The paint job, plus a mask for the lights
Model script	`media/scripts/`	`model` with `shader = vehicle`
Vehicle script	`media/scripts/vehicles/`	Physics, wheels, doors, seats, engine, lights
Name	`Translate/<IDIOMA>/IG_UI.json`	`"IGUI_VehicleName<NombreDelScript>": "Display name"`
Map spawning	Lua	`VehicleZoneDistribution`

Start by copying a similar vanilla vehicle. Vehicle scripts are long, and it's much easier to tweak one that works than to write it from scratch. They're in the install folder, under media/scripts/vehicles/.

The "ghost vehicle" bug

Symptom: the vehicle spawns, but all you can see is its shadow.

Cause: in the vehicle script, the model was written without a module (file = Wanaco_GuanacoActros). Without a module, the game only looks for it in the Base module.

Fix: always write the module: file = Wanaco.Wanaco_GuanacoActros.

Physics: don't overdo it

Mass (mass): keep it within vanilla values, up to ~1160. At 2400 the Wanaco revved its engine but didn't move.
Engine force (engineForce): up to ~7000, the vanilla maximum.
Wheels: the game simulates only 4 wheels. If your truck has more axles, the rest are just part of the model. All vanilla wheels use radius = 0.15.
Scale: vehicle models are scaled ×1.82. Keep that factor in mind when positioning wheels, doors and collision boxes.

Text and logos: the game shows them backwards

Vehicles are drawn mirrored left to right compared to how you see them in Blender or your viewer. If you paint "CARABINEROS" on the door, it reads backwards in the game.

Fix: paint the text mirrored on the texture. Multi-word text gets mirrored as a whole block. To check before launching the game, flip your test render horizontally.

Lights

Lights (headlights, brake lights, beacons) are marked on a separate color mask: each area of the texture is painted with an exact color that the shader recognizes. The colors are in the game's shader (media/shaders/vehicle.frag). We used them for the police cars' light bar.

Making it spawn on the map

This is how Wanaco does it (media/lua/shared/Wanaco_VehicleZones.lua), so it spawns at police stations:

lua

require "VehicleZoneDefinition"

local function agregarGuanacos()
    local police = VehicleZoneDistribution and VehicleZoneDistribution.police
    if not police or not police.vehicles then
        print("[Wanaco] VehicleZoneDistribution.police no disponible")
        return
    end
    police.vehicles["Wanaco.GuanacoActros"] = { index = 0, spawnChance = 40 }
    police.vehicles["Wanaco.Guanaco8x8"] = { index = 0, spawnChance = 25 }
end

agregarGuanacos()

There are zones for parking lots, streets, police, firefighters, etc. To see them all, look for VehicleZoneDefinition.lua inside media/lua/ in the game's install folder.

A custom system (the water cannon)

If your vehicle does something special, like shooting water, follow the pattern from Lua for mods: the player asks from the client and the server applies it. Store the state in the modData of one of the vehicle's parts and sync it with vehicle:transmitPartModData(part).