Vehicle Bases, Controllers, Stats, Seats, and Hitboxes

vehicles.yml is where Vehicle MC becomes a real content plugin.

This file defines what the vehicles actually are:

• their family
• their controller type
• their stats
• their seats
• their hitboxes
• their public variants

For the current public starter plan, the only required free family is the dirt bike. The jeep, hybrid, tank-style, and helicopter examples in the broader source are still valuable, but they belong to the wider reference lane rather than the minimum free pack.

The high-level structure

Vehicle MC splits the file into reusable defaults and real vehicle families.

defaults:
  stats:
    fuel:
      enabled: true
 
bases:
  dirtbike:
    displayName: '&6Dirt Bike'
    controller: GROUND
    physics:
      ground:
        accel: 0.035
    variants:
      standard_gray:
        price: 3000.0

This is a good structure because:

• shared defaults stay at the top
• each bases.<id> entry becomes the real design home of a vehicle family
• variants can change public identity without cloning the entire file

Controller types

Vehicle MC supports these main controller families:

• GROUND
• TANK
• BOAT
• HELICOPTER
• PLANE

That controller choice is one of the biggest design decisions in the whole file. It decides how later physics blocks are interpreted and which vehicle behaviors are actually relevant.

If you are mapping persistence policy, public variants, or alias strategy, continue into lifecycle, Persistence, Variants, and Alias Publishing after this page.

What belongs in a base vehicle

Each base entry is where the plugin decides what kind of machine this is.

Common branches include:

• displayName
• controller
• model
• physics
• stats
• lifecycle
• seats
• fx
• variants
• hitbox
• impactDamage
• damage

If the vehicle family is hard to understand, the base entry usually needs cleanup before the variants do.

Stats

The stats layer is where you shape the practical day-to-day feel of the vehicle.

HP

stats:
  hp:
    max: 150.0

This is the top-level survivability lane for the vehicle as a whole.

Fuel

stats:
  fuel:
    enabled: true
    capacity: 100.0
    burn:
      basePerTick: 0.002
      mode: THROTTLE_SCALED
      idleFactor: 0.25
    interaction:
      allowWhileMoving: false
      maxSpeedWhileFueling: 0.1
      allowWhileMounted: true
      allowWhileUnmounted: true

This decides:

• whether the vehicle uses fuel
• how fast it burns fuel
• whether idle drain matters
• whether fueling is a mobile action or a mostly-stationary service action

Trunk and horn

stats:
  trunk:
    enabled: true
    rows: 1
    usableSlots: 3
  horn:
    enabled: false

These are small details, but they strongly affect how practical a vehicle feels in a live server economy.

Seats

Seat layout is part of gameplay, not just an attachment detail.

seats:
  - id: driver
    role: DRIVER
    offset: [0.0, -0.8, -0.6]
  - id: passenger1
    role: PASSENGER
    offset: [0.0, -0.65, -1.6]

Seat roles already support:

• DRIVER
• PASSENGER
• GUNNER
• OTHER

This lets the same framework support:

• solo scout vehicles
• troop carriers
• armed crew vehicles
• multi-role special vehicles

If you are trying to make entry, exit, trunk access, horn use, or pickup feel correct, continue into vehicle Interactions, Entry, Exit, Trunks, Horns, and Pickup. Seat layout and interaction policy need to agree with each other.

Variants

Variants are the public presentation layer of a family.

variants:
  standard_gray:
    displayName: '&6Standard Gray Dirt Bike'
    modelItem: minecraft:diamond_hoe{Damage:10}
    price: 3000.0
    aliases:
      - STANDARD_GRAY_DIRT_BIKE
      - DBK10A

This is a good place to vary:

• model item
• public name
• price
• aliases

Keep the family logic in the base. Use variants to present clean public options.

Hitbox and collision shape

The hitbox layer is where driving feel and combat feel meet.

hitbox:
  enabled: true
  collision:
    enabled: true
    box:
      halfExtents: [0.2, 1.0, 0.6]
      offset: [0.0, 1.0, 0.0]
    stepUp:
      enabled: true
      maxHeight: 0.6
  impact:
    enabled: true
    box:
      halfExtents: [0.26, 1.08, 0.65]
      offset: [0.0, 0.0, 0.0]

Important split:

• collision box is for physical world interaction
• impact box is for impact and damage behavior

Keeping those separate gives you much more control than trying to solve everything with one box.

Impact damage and collision damage

Vehicle MC separates movement collision and actual damage behavior.

Useful branches include:

• impactDamage
• damage.projectiles
• damage.collision

That means you can build a vehicle that:

• drives over terrain safely but still takes projectile damage
• feels physically solid without being absurdly lethal on contact
• has different danger levels for world collision versus combat damage

Suggested order

1. Build one clean base family.
2. Pick the correct controller type.
3. Tune HP, fuel, trunk, and seats before polishing variants.
4. Make the hitbox readable and believable.
5. Add variants only after the base family feels stable.
6. Add advanced combat or service behavior afterward.

Related pages

• free Starter Dirt Bike Quick Start and Upgrade Path
• advanced Rig Examples: Dirt Bikes, Jeeps, Tanks, Helicopters, and Input-Driven Parts
• runtime Modules, Physics, and Safety
• rig Backends, Display Parts, Wheels, and ModelEngine
• vehicle Interactions, Entry, Exit, Trunks, Horns, and Pickup
• lifecycle, Persistence, Variants, and Alias Publishing
• fuel Containers, Repair Tools, and Service Sessions
• combat Components, Duck Shot Bridge, Projectiles, and Loadouts