Catalog YML: Browse Layout and Variant Entry Flow

catalog.yml is the file that decides how the public vehicle library looks when someone actually opens the catalog.

It does not decide physics, fuel burn, or damage. It decides:

• which base families appear
• where they appear in the menu
• what icon, name, and lore they use
• how the variant menu opens after the player clicks a base family

If players cannot find the right vehicle, or the fleet looks messy even though the vehicles themselves work, this is one of the first files to fix.

What the current file already contains

The current resource file is split into two main blocks:

• catalog.root
• catalog.baseMenu

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'
          - '&89 variants'
  baseMenu:
    titleTemplate: '&0{base_display}'
    rows: 6
    variantItemLore:
      - '&7Click to give/spawn'
      - '&8ID: {variant_id}'

Interpretation:

• root is the top-level browse surface
• entries are the clickable family cards
• baseMenu is the follow-up menu that shows the variants inside that family

catalog.root

catalog.root controls the first screen players see.

The important fields are:

• title
• rows
• entries

That means you are deciding:

• how large the catalog should feel
• how many family entries fit cleanly on one page
• which base families deserve the most visible slots

Good use:

• put the core fleet in the strongest slots
• keep similar families grouped together
• avoid scattering air, land, and utility families randomly

catalog.root.entries.<id>

Each entry is a selected gateway into a vehicle family.

The current entry shape uses:

• slot
• base
• icon
• name
• lore

This is not only decoration. It answers four player questions immediately:

1. What am I clicking?
2. Which family does it open?
3. Does this family have variants?
4. Does it belong in this menu at all?

Slot planning matters more than people think

These slot values are part of the public reading order.

If the catalog is confusing, the issue is often not the vehicles. It is the slot plan.

Good slot planning usually means:

• keep the common ground fleet close together
• separate specialty air vehicles clearly
• keep experimental or combat-heavy families out of the first row unless the server revolves around them

base

base should point cleanly at the family id in vehicles.yml.

That means a catalog entry should feel like a reliable door into a family that already makes sense in:

• vehicle Bases, Controllers, Stats, Seats, and Hitboxes
• vehicle Families, Variants, Fuel, and World Service Systems

If the catalog entry looks correct but opens a confusing family, the problem is usually in vehicles.yml, not in catalog.yml.

icon, name, and lore

These three fields create the first impression of the family.

Use them to communicate:

• vehicle role
• tone
• rarity or breadth of the family
• whether the player is opening a browse screen or immediately receiving a key or spawn

The current file uses simple lore like:

lore:
  - '&7Click to view variants'
  - '&89 variants'

That works well because it tells the player exactly what happens next.

catalog.baseMenu

This block handles the variant view after someone opens a family.

The important fields in the current file are:

• titleTemplate
• rows
• variantItemLore

This is where you decide whether the variant screen feels:

• clean and premium
• dense and utilitarian
• starter-friendly
• staff-facing

titleTemplate

titleTemplate should make it obvious that the player is now looking inside one family.

The current pattern:

titleTemplate: '&0{base_display}'

is a good baseline because it keeps the menu title tied to the selected family instead of inventing a second naming layer.

variantItemLore

This is the simplest way to explain what clicking a variant will do.

The current default:

variantItemLore:
  - '&7Click to give/spawn'
  - '&8ID: {variant_id}'

works because it tells the user:

• the entry is actionable
• the system is variant-based
• the variant id exists if staff or creators need to reference it later

Suggested order

1. Make the family ids in vehicles.yml readable first.
2. Put only the most useful families into the root menu.
3. Use names and lore that tell the player what happens next.
4. Keep the variant menu simple before adding more decorative polish.
5. Test the catalog with someone who did not build it.

Related pages

• vehicle YAML Authoring Order, File Splitting, and Starter Fleet Planning
• catalog, UI, Surfaces, and Driver Feedback
• catalog, Keys, Spawns, Messages, and Driver UI
• ui YML: Bossbars, Thresholds, and Driver HUD
• vehicle Bases, Controllers, Stats, Seats, and Hitboxes