Catalog, UI, Surfaces, and Driver Feedback

Not every Vehicle MC file is about physics. Some of the most important quality-of-life work lives in the operator and driver support files.

The three files that matter most for that layer are:

• catalog.yml
• ui.yml
• surfaces.yml

Quick routes:

• open the catalog.yml guide
• open the ui.yml guide
• open the surface handling guide

Together they decide how vehicles are presented, how they feel to drive across the world, and how clearly the player can read their state.

catalog.yml

catalog.yml is the public browse layer for the vehicle library.

The default catalog already defines:

• a root menu
• slot-by-slot vehicle family entries
• icons
• lore
• a base menu template for variants

Example:

catalog:
  root:
    title: '&0Vehicle Catalog'
    rows: 3
    entries:
      dirtbike:
        slot: 10
        base: dirtbike
        icon: minecraft:diamond_hoe{Damage:10}
        name: '&6Dirt Bike'
        lore:
          - '&7Click to view variants'

Interpretation:

• the catalog is not auto-generated chaos
• each base family can have a selected public position
• the operator decides how much menu polish the system gets

ui.yml

ui.yml handles the driver-facing bossbar layer.

The default UI file already exposes:

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}%)'
    speed:
      enabled: false
      style: SEGMENTED_20
      title: '&fSpeed &7{speed}/{speed_max}'

This means the vehicle can already feel:

• minimal and clean
• heavily instrumented
• arcade-like
• utility-focused

The big decision is not only which bars to show. It is also how much information you want to keep in the player's face while driving.

surfaces.yml

surfaces.yml is one of the most important handling files in the plugin because it lets the world itself change how the vehicle behaves.

The default surface file already includes:

• sample cadence
• sampling mode
• wheel source mode
• multiplier smoothing
• particle mode
• surface profile priorities
• per-surface speed, accel, traction, and slip multipliers

That means the same vehicle can feel different on:

• roads
• gravel
• sand
• ice
• grass

without cloning the vehicle config.

Surface sampling is its own design choice

The current file already gives you multiple ways to decide where wheel contact comes from:

sampling:
  everyTicks: 5
  mode: WEIGHTED_AVERAGE
  wheelMode: AUTO_FROM_HITBOX
  anchorsPrefix: "wheel_"

That is a useful split:

• use auto hitbox sampling when you want the easiest baseline
• use anchors when the rig has explicit wheel points
• use offsets when you need hardcoded local-space control

Surface particles are not only decorative

The particle lane is already designed to help the vehicle read better in motion.

particles:
  enabled: true
  mode: EVENT
  everyTicks: 4
  minSpeed: 0.05
  emitOnSurfaces:
    - sand
    - gravel
    - grass
    - roads

That means tire FX can reinforce the gameplay:

• sand feels dusty
• roads feel cleaner
• skids read differently than soft movement

Copyable surface profile example

surfaces:
  mud:
    priority: 2
    match:
      materials:
        - MUD
        - SOUL_SOIL
    multipliers:
      maxSpeedMul: 0.72
      accelMul: 0.68
      tractionMul: 0.82
      slipMul: 1.18

This is a good pattern for adding a readable bad-terrain profile without touching every vehicle family.

Suggested order

1. curate the catalog first so the vehicle families read well
2. enable only the bossbars that actually help
3. get one strong surface profile working on roads and sand
4. expand the surface library only after drivers can clearly feel the difference

Related pages

• keys, Claims, and Vehicle Redemption
• messages, Bossbars, and Driver Feedback
• core Config, Runtime, and Rig Backends
• vehicle Families, Variants, Fuel, and World Service Systems
• fuel Tanks, Repair Stations, and World Service
• surfaces, FX, and Terrain Response
• catalog, Keys, Spawns, Messages, and Driver UI