Vehicle YAML Authoring Order, File Splitting, and Starter Fleet Planning

Vehicle MC gets confusing fast when you treat every file like one giant editing surface.

The clean way to build with it is top-down:

1. set the global rules
2. build one base vehicle
3. add one variant
4. wire the player-side browse and feedback layer
5. add service systems
6. add combat only if the civilian loop already works

If you are building the public free starter release, do not start with a full fleet. Start with free Starter Dirt Bike Quick Start and Upgrade Path, then come back here once that one vehicle loop already feels clear.

Quick jump by file

If you already know the filename you want, jump straight to the matching guide:

• catalog.yml
• ui.yml
• keys.yml
• spawns.yml
• messages.yml
• fuel_tanks.yml
• duckshot_bridge.yml

Advanced rig workflow:

• advanced Rig Examples: Dirt Bikes, Jeeps, Tanks, Helicopters, and Input-Driven Parts
• rig Debug Commands, Pivot Tools, and Live Diagnostics

The top-down file order

1. config.yml (open guide)

Use this first for:

• module toggles
• runtime cadence
• rig backend default
• pickup and anti-dupe rules
• seat switching
• server-wide safety behavior

Example:

modules:
  storage:
    enabled: true
  ui:
    enabled: true
  fx:
    enabled: true
  surfaces:
    enabled: true
  fuel:
    enabled: true
  combat:
    enabled: false
  weapons:
    enabled: false

Interpretation:

• the normal vehicle loop is live
• service systems can exist
• armed-vehicle content is still out of the way

That is a good first public baseline.

2. vehicles.yml (open guide)

This is where the real vehicle authoring happens.

Use it for:

• base families
• controller type
• movement stats
• seats
• hitboxes
• HP and fuel stats
• trunk rules
• horn rules
• vehicle-specific overrides

Example structure:

bases:
  dirtbike:
    displayName: '&6Dirt Bike'
    controller: GROUND
    physics:
      ground:
        accel: 0.035
        brakeDecel: 0.03
        coastDecel: 0.006
        maxSpeedForward: 1.5
        maxSpeedReverse: 0.35
    stats:
      hp:
        max: 150.0
      fuel:
        enabled: true
      trunk:
        enabled: true
        rows: 1

Interpretation:

• this file defines what the vehicle feels like
• it is not the place for global runtime policy
• it is not the place for catalog layout or player messages

What belongs outside vehicles.yml

One of the most common Vehicle MC mistakes is stuffing too much into the vehicle definition mindset.

Here is the cleaner split:

catalog.yml (open guide)

Use this for how players browse the fleet.

Example:

catalog:
  root:
    title: '&0Vehicle Catalog'
    rows: 3
    entries:
      dirtbike:
        slot: 10
        base: dirtbike
        icon: minecraft:diamond_hoe{Damage:10}
        name: '&6Dirt Bike'

This file answers:

• what appears in the menu
• which slot it uses
• which base family it points at
• what icon, name, and lore the player sees

ui.yml (open guide)

Use this for the driver feedback layer.

Example:

ui:
  updateEveryTicks: 2
  bossbars:
    hp:
      enabled: true
      style: SEGMENTED_10
      title: '&c&lHP &7- &f{hp}/{hp_max} &7({percent}%)'
    fuel:
      enabled: true
      style: SEGMENTED_10
      title: '&e&lFuel &7- &f{fuel}/{fuel_max} &7({percent}%)'

This file answers:

• how often the bars update
• what the bars say
• how readable HP, fuel, and speed are in motion

messages.yml (open guide)

Use this for text the player reads, not for movement rules.

keys.yml and spawns.yml

open keys.yml guide
open spawns.yml guide

Use these for redemption, key handoff, and spawn or display props.

fuel_tanks.yml (open guide)

Use this for world infrastructure:

• where stations exist
• what they refill
• whether they repair
• hose visuals
• leak and explosion behavior

duckshot_bridge.yml, combat.yml, components.yml, collisions.yml, destruction.yml

open duckshot_bridge.yml guide

Use these only when the base vehicle loop already works and you are ready for armed content.

A clean first public fleet

Do not try to publish every vehicle family at once.

A strong first public release for Vehicle MC can be much smaller than a full fleet.

For the planned free starting path, keep it to:

• one dirt bike family
• one public dirt bike variant
• one browse flow
• one readable HUD
• one pickup or storage loop

That is enough to prove the plugin works without turning the starter pack into a mess.

A good public release split

Separate your content into three lanes:

Free starting path

The vehicles a new server owner should be able to test immediately in the base free pack.

Current recommended scope:

• one dirt bike
• one public dirt bike variant
• no tanks
• no helicopters
• no hybrid rigs
• no armed-vehicle assumptions

Advanced reference lane

This is where the broader rig examples belong:

• four-wheel native rigs
• hybrid ModelEngine examples
• heavy bodies and tank-ready rigs
• helicopters and other air vehicles
• armed vehicles
• edge-case handling setups

Server-specific fleet

Keep these out of the public starter pack when they depend on:

• private lore
• private balance rules
• one map or one gamemode
• one progression path
• private armed-vehicle assumptions

Suggested order

When adding a new vehicle family:

1. set or confirm the global module rules
2. make the base family work in vehicles.yml
3. add one variant
4. put it in catalog.yml
5. make sure the bars in ui.yml still read well
6. add service hooks only if the server uses them
7. add combat hooks only if the non-combat version already feels correct

That workflow keeps the YAML readable and makes debugging much easier.

Where to go next

• vehicle Bases, Controllers, Stats, Seats, and Hitboxes
• vehicle Families, Variants, Fuel, and World Service Systems
• catalog, UI, Surfaces, and Driver Feedback
• fuel Containers, Repair Tools, and Service Sessions
• duck Shot Bridge, UI, and Operator Workflows