Creating & editing vehicles

Every vehicle is a model stored as an HJSON file (a friendlier JSON that allows comments). This page is the complete reference for that file: where it lives, every setting it has, and every part type you can add.

The easy way to start

Don't write a model from scratch — copy an existing one. The plugin ships an Example<Type> model for every type. Duplicate it, rename the file and the id, tweak it, then run /vm reload <id>.

Where models live

/plugins/VehiclesPlus/vehicles/<type>/<id>.hjson

• <type> is the folder for the vehicle type (cars, bikes, helicopters, boats, planes, tanks, hovercrafts, or a custom type).
• <id> is the model id and must match the id inside the file.

After editing, apply your changes with /vm reload <id>. Setting changes apply to spawned vehicles immediately; part changes need a re-spawn.

---

Model structure

A trimmed example (an ExampleCar):

{
  id: ExampleCar
  displayName: &cExample &aCar
  typeId: cars
  typeStrategies: [ { movementType: land } ]

  price: 100000
  health: 100
  trunkSize: 27
  drift: true
  exitWhileMoving: true
  realisticSteering: false

  permissions: {
    buy: vp.buy.ExampleCar
    adjust: vp.adjust.ExampleCar
    spawn: vp.spawn.ExampleCar
    ride: vp.ride.ExampleCar
    sitWithoutRidePermission: true
  }

  availableColors: [ { red: 255, green: 0, blue: 0 } /* ... */ ]

  parts: [ /* see "Parts" below */ ]

  maxSpeed:       { base: 100, upgradable: true, max: 200, step: 5, stepCost: 1000, unit: km/h }
  acceleration:   { base: 50,  upgradable: true, max: 100, step: 5, stepCost: 1000, unit: "" }
  turningRadius:  { base: 7,   upgradable: true, max: 15,  step: 1, stepCost: 1000, unit: "" }
  fuelTank:       { base: 50,  upgradable: true, max: 100, step: 5, stepCost: 1000, unit: L }

  fuel:   { typeId: gasoline, usage: 6 }
  hitbox: { length: 3.05, width: 2, height: 1.25 }
  gearbox:{ realistic: true, cooldown: 10 }
  exhaust:{ enabled: true, particle: LARGE_SMOKE, xoffset: -3, yoffset: 0.1, zoffset: -1 }
  horn:   { enabled: true, sound: { sound: block.note_block.bass, volume: 1, pitch: 1, duration: 3 } }
  sounds: { /* idle / start / accelerate / driving / slowingDown */ }

  # heightLimit: { minHeight: -64, maxHeight: 320 }   # air vehicles only
}

---

General settings

Key	Type	Description
id	string	Unique model id. Must equal the file name (without .hjson).
displayName	string	Shown in menus. Supports & color codes.
typeId	string	The vehicle type (the folder name), e.g. cars.
typeStrategies	list	The movement strategy/strategies, e.g. [ { movementType: land } ]. Usually matches the type's movement types (land, air, water).
price	number	Buy price (shop) and the basis for the repair cost.
health	number	Hit points before the vehicle is destroyed.
trunkSize	number	Trunk inventory size in slots (0 = no trunk). Use multiples of 9.
drift	boolean	Whether the vehicle can drift.
exitWhileMoving	boolean	If false, players can't leave while it's moving (it brakes to a stop instead).
realisticSteering	boolean	Realistic (momentum-based) steering instead of instant turning.

permissions

Key	Description
buy	Permission required to buy this model.
adjust	Permission to adjust/tune it.
spawn	Permission to spawn it.
ride	Permission to ride it.
sitWithoutRidePermission	If true, players may sit in passenger seats without the ride permission.

See Permissions for how these tie into the wildcard nodes.

availableColors

A list of { red, green, blue } colors (0–255) players can choose from when the vehicle uses colorable (leather) parts.

---

Upgradable settings

maxSpeed, acceleration, turningRadius and fuelTank all share the same shape:

Key	Description
base	Starting value of a freshly spawned vehicle.
upgradable	Whether players can upgrade it in the tuning/upgrade menu.
max	Maximum value it can be upgraded to.
step	How much each upgrade adds.
stepCost	Money charged per upgrade step.
unit	Unit shown in the UI (e.g. km/h, L, or empty).

note

maxSpeed, fuelTank, acceleration and turningRadius are independent — upgrading one only changes that stat.

---

Other setting blocks

fuel

fuel: { typeId: gasoline, usage: 6 }

• typeId — the fuel type the vehicle consumes (see Fuel types).
• usage — how fast it burns fuel.

hitbox

hitbox: { length: 3.05, width: 2, height: 1.25 }

The collision box used for crash/step-up detection (in blocks).

gearbox

gearbox: { realistic: true, cooldown: 10 }

• realistic — enable a gear system the player shifts through.
• cooldown — ticks between gear shifts.

exhaust

exhaust: { enabled: true, particle: LARGE_SMOKE, xoffset: -3, yoffset: 0.1, zoffset: -1 }

Exhaust particles emitted while driving, at the given offset from the vehicle center. particle is any Bukkit particle name.

horn

horn: { enabled: true, sound: { sound: block.note_block.bass, volume: 1, pitch: 1, duration: 3 } }

The sound played when the player honks.

sounds

The engine sounds, each with sound (resource-pack sound key), volume, pitch and duration:

sounds: {
  idle:        { sound: vp.idle,        volume: 1, pitch: 1, duration: 6 }
  start:       { sound: vp.start,       volume: 1, pitch: 1, duration: 2 }
  accelerate:  { sound: vp.accelerate,  volume: 1, pitch: 1, duration: 2 }
  driving:     { sound: vp.driving,     volume: 1, pitch: 1, duration: 2 }
  slowingDown: { sound: vp.slowingdown, volume: 1, pitch: 1, duration: 2 }
}

tip

If your sounds come from the resource pack set in resourcePackUrl, the plugin measures each sound's real length automatically, so you don't have to get duration exactly right — sounds won't overlap or get cut off.

heightLimit (air vehicles only)

heightLimit: { minHeight: -64, maxHeight: 320 }

The lowest and highest Y a flying vehicle may reach.

---

Parts

parts is a list of objects, each with a type. All parts share these offset fields (in blocks, steps of 0.1, relative to the vehicle's spawn point):

Field	Description
xoffset	Left/right offset.
yoffset	Up/down offset.
zoffset	Forward/backward offset.
rotationOffset	Rotation in degrees relative to the vehicle (0 = facing forward).

skin

The visible body of the vehicle (an item on an invisible armor stand).

{
  type: skin
  xoffset: 0, yoffset: -0.2, zoffset: 0, rotationOffset: 0
  item: {
    material: LEATHER_BOOTS
    custommodeldata: 1           # the custom model from your resource pack
    color: { red: 255, green: 255, blue: 255 }   # for leather/colorable items
  }
  position: HEAD                 # HEAD, LEFT_HAND or RIGHT_HAND
}

Bikes use type: bikeskin instead — same fields, but it leans into turns.

seat

A place to sit. One seat should have steer: true (the driver).

{
  type: seat
  xoffset: 0.3, yoffset: -1.3, zoffset: 0.65, rotationOffset: 0
  steer: true                    # true = driver seat
  guiitem: { material: DIAMOND_HOE, damage: 1, unbreakable: true, flags: [ HIDE_UNBREAKABLE, HIDE_ADDITIONAL_TOOLTIP ] }
}

Bikes use type: bikeseat (same fields).

wheel

A wheel that turns and (optionally) steers. Cars only.

{
  type: wheel
  xoffset: 1.89, yoffset: 0, zoffset: 1.13, rotationOffset: 0
  rimDesignId: default           # see the Rims page
  steering: true                 # true = a front (steering) wheel
}

rotor

The spinning blade of a helicopter.

{
  type: rotor
  xoffset: -0.3, yoffset: 0.95, zoffset: 0, rotationOffset: 0
  item: { material: LEATHER_CHESTPLATE, custommodeldata: 2, color: { red: 128, green: 128, blue: 128 } }
  position: HEAD
}

turret & turretseat

A rotatable, firing turret (tanks). The turret has an identifier; the turretseat points at it via controllingTurret.

{
  type: turret
  xoffset: -0.5, yoffset: 0, zoffset: 0, rotationOffset: 0
  item: { material: LEATHER_CHESTPLATE, custommodeldata: 3, color: { red: 0, green: 0, blue: 0 } }
  position: HEAD
  identifier: tank_turret_1      # any unique id within this model
  explosionSize: 3               # blast radius when firing
  ammo: { material: TNT }        # item required to fire
}
{
  type: turretseat
  xoffset: -3.05, yoffset: 0, zoffset: 0.9, rotationOffset: 0
  steer: false
  controllingTurret: tank_turret_1   # must match the turret's identifier
  guiitem: { material: DIAMOND_HOE, damage: 1, unbreakable: true }
}

---

Adding a new vehicle — checklist

1. Model the vehicle and add it to your resource pack with a unique custommodeldata — see Resource packs (or use ItemsAdder / Oraxen).
2. Copy an existing Example<Type>.hjson to a new file in the matching vehicles/<type>/ folder.
3. Rename the file and set a matching id.
4. Point each skin/rotor/turret part's custommodeldata at your model.
5. Tune the offsets, hitbox, speed, fuel, price, etc.
6. Run /vm reload <id> and spawn it with /v spawn <id>.

See the per-type pages under Types for what makes each vehicle type unique.