Runtime Modules, Physics, and Safety

config.yml is the control room for Vehicle MC.

If every vehicle feels wrong in the same way, or if the whole plugin behaves badly on a live server, this is the file to check before touching any one vehicle family.

What belongs in config.yml

Use config.yml for plugin-wide behavior:

• module toggles
• runtime cadence
• collision and landing thresholds
• water behavior
• cleanup and anti-dupe rules
• packet input handling
• seat-switch rules
• pickup behavior
• default visual backend

Use vehicles.yml when the change belongs to one vehicle family or one variant.

Module toggles decide what is even active

The first section to check is modules.*.

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

Why this matters:

• surfaces.yml does not matter if the surfaces module is off
• ui.yml does not matter if the UI module is off
• armed-vehicle files do not matter if combat and weapons are off
• keys, spawns, and catalog behavior depend on the supporting modules being active

If a whole part of the plugin seems dead, confirm the module toggle before anything else.

Runtime cadence

The next important block is runtime.tick.pipeline.

runtime:
  tick:
    enabled: true
    targetTps: 20
    pipeline:
      controllerEveryTicks: 1
      collisionEveryTicks: 1
      fxEveryTicks: 3
      uiEveryTicks: 2
      storageAutosaveEverySeconds: 30
      storageAutosaveSkipWhileOccupied: true

How to read this:

• controller cadence affects how immediate driving feels
• collision cadence affects how quickly impacts and contact checks react
• FX and UI can usually run a little slower than movement without feeling broken
• autosave settings affect background storage pressure, especially on large servers

Good public rule:

• change these only when you have a real server-performance reason
• do not treat cadence values as a substitute for fixing bad vehicle content

Collision, landing, and water rules

Vehicle MC keeps a lot of global movement feel in physics.*.

The most useful public groups are:

• physics.collision.fx
• physics.collision.landing
• physics.collision.air
• physics.collision.helicopter.rotorChop
• physics.water

Example:

physics:
  collision:
    landing:
      bumpMinFallBlocks: 2.0
      crashMinFallBlocks: 10.0
      bumpMinVerticalImpact: 0.30
      crashMinVerticalImpact: 0.55
      fallDamage:
        enabled: true
  water:
    enabled: true
    shallow:
      speedMultiplier: 0.65
      damageEveryTicks: 40
      damage: 2.0
    deep:
      speedMultiplier: 0.18
      damageEveryTicks: 16
      damage: 4.0

Interpretation:

• landing thresholds stop tiny drops from feeling like wrecks
• fall-damage rules let you decide how punishing landings really are
• water settings control whether land vehicles merely slow down or become a real liability

These are good places to set server-wide tone before you touch one dirt bike, one truck, or one tank.

Helicopter rotor chop

Rotor chop is a separate global rule, not a one-off vehicle gimmick.

physics:
  collision:
    helicopter:
      rotorChop:
        enabled: true
        everyTicks: 2
        radius: 2.2
        halfHeight: 0.25
        minGroundClearance: 2.0
        damagePerHit: 4.0
        cooldownTicks: 6

Use this to decide:

• how dangerous low rotor clearance should be
• how often damage applies
• how much room pilots need near ground or obstacles

Input and seat switching

Input settings are small, but they affect the whole plugin.

input:
  provider: PACKETEVENTS
  packetEvents:
    useSteerVehicle: true
    useRotationPackets: true
    useEntityActionSneak: true
 
seats:
  switchSeat:
    enabled: true
    maxSpeed: 0.12

This is where you shape:

• how responsive the control input feels
• whether seat switching is allowed mid-drive
• how stationary a vehicle must be before players can move between seats

If all vehicles share the same control problem, check here before rewriting content.

Entity cleanup and collision shield

The entity-side safety layer lives under entities.*.

Important public groups:

• entities.cleanup
• entities.collisionShield
• entities.scoreboardTag

The cleanup settings decide when orphaned pieces should be removed. The collision shield is the simple repulsion layer that keeps players and mobs from living inside vehicle geometry.

This is especially important on busy servers where abandoned vehicles, chunk loads, and crowding can create bad edge cases.

Pickup, storage, and anti-dupe

Vehicle pickup is part of the runtime contract, not only a convenience feature.

pickup:
  enabled: true
  method: TRUNK_BUTTON
  maxSpeed: 0.10
  requireEmptyVehicle: true
  allowPickupInCombat: false
  preserveTrunkContents: true
  preserveHealth: true
  preserveFuel: true
 
safety:
  antiDupe:
    enabled: true
    spawnRequiresPersistedRecord: true
    preventDoubleSpawnSameUuid: true

These settings decide:

• how strict pickup should be
• whether vehicle state survives storage cleanly
• how much protection exists against duplicate spawns and bad persistence flow

If your server expects players to store, redeploy, and trust their vehicles, this section matters as much as the driving physics.

For the player-side side of trunks, horns, entry range, exit rules, and pickup affordances, continue into vehicle Interactions, Entry, Exit, Trunks, Horns, and Pickup. This page is the global policy layer, while that page is the per-vehicle interaction layer.

Debug settings

The debug block is useful for administrators, but it should stay quiet in normal live operation.

Useful options include:

• debug.hitboxParticles
• debug.rigTransforms

Use these when you are diagnosing:

• bad hitbox alignment
• part transform problems
• wheel/rig placement issues

Then turn them back down after testing.

Good setup order

1. Enable only the modules you truly need.
2. Keep the tick pipeline conservative until real performance testing says otherwise.
3. Set global landing and water behavior before balancing individual vehicles.
4. Confirm pickup and anti-dupe rules before handing vehicles to players.
5. Tune one visual backend path before mixing multiple rendering styles.

Related pages

• core Config, Runtime, and Rig Backends
• rig Backends, Display Parts, Wheels, and ModelEngine
• vehicle Bases, Controllers, Stats, Seats, and Hitboxes
• vehicle Interactions, Entry, Exit, Trunks, Horns, and Pickup
• fuel Containers, Repair Tools, and Service Sessions