File format
One file per vehicle in vehicles/<type>/, in HJSON (or JSON). The file name does not matter: the id field is what counts.
In HJSON an unquoted string runs to the end of the line. To write several fields on one line use JSON with quotes (as the editor does): { "type": "skin", "xoffset": 0 }.
Main fields
| Field | Type | Req. | Description |
|---|---|---|---|
id | text | yes | Unique identifier. It appears in permissions (ev.spawn.<id>) and commands. |
displayName | text | no | Name shown in the menus. Falls back to the id if missing. |
typeId | text | yes | Type: cars, trucks, bikes, bicycles, boats, hovercrafts, helicopters, planes or tanks. Decides the physics. bicycles never have fuel. |
enabled | boolean | no | With false the model is not loaded (true by default). |
category | text | no | PASSENGER, CARGO, EMERGENCY or SPECIAL. If missing, falls back to vehicles-registry.yml or PASSENGER. |
price | number | no | Final price the customer pays. With 0 the vehicle does not appear in the shop. |
trunkSize | integer | no | Trunk slots (multiples of 9, maximum 54; 0 = no trunk). |
health | number | no | Vehicle health (100 by default). |
drivingMode | text | no | WASD or HORSE: how this model is driven. If missing, falls back to driving.mode in config.yml. |
availableColors | list | no | Colors offered in the shop: { red, green, blue } objects from 0 to 255. |
parts | list | yes | The vehicle's parts, see below. |
hitbox | object | yes | length (Z), width (X), height (Y) in blocks. |
fuel | object | yes | typeId (GASOLINE, DIESEL, PETROL, KEROSENE or NONE for no tank) and usage (consumption, see Fuel). For bicycles it can be omitted together with fuelTank. |
Upgradable stats
Four blocks with the same shape: maxSpeed (km/h), fuelTank (liters), turningRadius and acceleration. All required.
| Field | Description |
|---|---|
base | Starting value (required). |
upgradable | Whether the stat can be upgraded. |
max | Maximum reachable value. |
step | Increase per level. For the turning radius a negative value can be used. |
stepCost | Cost of each level, paid by the player through Vault. |
unit | Unit shown (free text). |
Levels are (max - base) / step, rounded down. Example: base 60, max 90, step 10 give 3 levels.
The parts
Each element of parts has type, xoffset, yoffset, zoffset and rotationOffset, plus the fields of its type (see Creating a vehicle). An unknown type is ignored with a warning in the log.
Optional blocks
| Field | Description |
|---|---|
physics | suspension (0-1, default 0.6), steeringSmoothing (0-1, default 0.5), liftoffSpeed (planes; default 55% of top speed). |
heightLimit | min and max: minimum and maximum altitude for helicopters and planes. |
permissions | sitWithoutRidePermission: passengers can sit without the ride permission. |
animations | wheels (spin, steer) and doors (a list of part, axis, openAngle, durationTicks). A door is a skin with a name: the model's rotation center must sit on the hinge. |
plate | Shows the plate on the vehicle: enabled, xoffset, yoffset, zoffset, rotationOffset, scale. |
Other fields (exhaust, horn, sounds, realisticSteering, drift, exitWhileMoving, gearbox) are accepted and ignored by the current engine.
Minimal example
{
"id": "offroad_black",
"displayName": "Black OffRoad",
"typeId": "cars",
"price": 5000,
"trunkSize": 9,
"availableColors": [ { "red": 255, "green": 255, "blue": 255 } ],
"parts": [
{ "type": "skin", "xoffset": 0, "yoffset": 0, "zoffset": 0, "rotationOffset": 0,
"item": { "material": "PAPER", "custommodeldata": 2400153 } },
{ "type": "seat", "xoffset": 0.4, "yoffset": -1.25, "zoffset": 0.3, "rotationOffset": 0, "steer": true }
],
"maxSpeed": { "base": 80, "upgradable": false, "max": 80, "step": 0, "stepCost": 0, "unit": "km/h" },
"fuelTank": { "base": 40, "upgradable": false, "max": 40, "step": 0, "stepCost": 0, "unit": "L" },
"turningRadius": { "base": 10, "upgradable": false, "max": 10, "step": 0, "stepCost": 0 },
"acceleration": { "base": 30, "upgradable": false, "max": 30, "step": 0, "stepCost": 0 },
"hitbox": { "length": 4.5, "width": 2, "height": 1.8 },
"fuel": { "typeId": "GASOLINE", "usage": 7 }
}