Lifecycle, Persistence, Variants, and Alias Publishing

Vehicle MC separates three concerns that are easy to mix together:

• how long a vehicle should live in the world
• how a vehicle family is presented to players
• how administrators spawn, test, or sell that family safely

If those three concerns stay clean, the vehicle library scales well. If they get mixed together, the catalog gets messy and live-server storage becomes hard to trust.

Base family first, variant second

The base family is where the vehicle actually works.

The variant is where the public version is presented.

That is why a good Vehicle MC family usually looks like this:

bases:
  jeep:
    displayName: '&6Jeep'
    controller: GROUND
    stats:
      hp:
        max: 2000.0
    variants:
      standard_imc:
        displayName: '&6Standard IMC Jeep'
        modelItem: minecraft:diamond_hoe{Damage:4}
        price: 6000.0
        aliases:
          - STANDARD_IMC_JEEP
          - JEEP01

Public rule:

• build the machine in the base
• publish the sellable or spawnable identity in the variant

Defaults, bases, and variants work as a stack

Vehicle MC already uses a layered merge model:

• defaults define shared starting behavior
• bases.<id> define the vehicle family
• variants.<id> override the public presentation layer

That lets you keep one clean family while still publishing multiple public versions.

Good uses for defaults:

• shared fuel behavior
• shared trunk defaults
• shared horn defaults
• shared collision or damage baselines

Good uses for variants:

• different model item
• different display name
• different price
• different alias list

Do not move seat layout, hitbox logic, or core handling into variants unless a variant is truly a different machine.

Lifecycle decides whether a vehicle feels disposable or persistent

The lifecycle layer lives in the base vehicle, not in the catalog.

Two common patterns already appear in the current source examples:

lifecycle:
  persistAcrossRestart: true
  despawnAfterSecondsUnoccupied: 7200

and:

lifecycle:
  enabled: true
  persistAcrossRestart: true
  idleDespawn:
    enabled: true
    seconds: 18000
    requireStationary: true
    maxSpeed: 0.05

How to choose:

• persistAcrossRestart: true is the standard choice for persistent vehicles
• despawnAfterSecondsUnoccupied works well when you want abandoned vehicles to clear themselves
• idleDespawn is better when you want more control over what counts as abandoned

For a personal asset or purchased vehicle, persistence usually matters. For temporary spawn content or test vehicles, a stronger despawn rule often makes more sense.

Use explicit lifecycle policy for each family

Ask these questions for every base family:

• should the vehicle survive server restarts
• should abandoned vehicles clear themselves
• should moving vehicles be protected from idle cleanup
• is this vehicle a personal asset, a temporary world prop, or an event vehicle

That policy choice is more important than making the catalog look full.

Variants are where the public identity becomes real

A good variant usually controls four things:

• displayName
• modelItem
• price
• aliases

Example:

variants:
  snow_camo_imc:
    displayName: '&6Snow Camo IMC Jeep'
    modelItem: minecraft:diamond_hoe{Damage:204}
    price: 1000.0
    aliases:
      - SNOW_CAMO_IMC_JEEP
      - JEEP02

That is enough to:

• show a polished version in the catalog
• use a distinct model item in the world
• price the vehicle for redemption or shop use
• give administrators a stable spawn alias

A clean alias strategy saves a lot of admin pain

Aliases should be:

• stable
• short enough to use quickly
• specific enough that two vehicles cannot be confused

Good pattern:

• one readable alias like STANDARD_IMC_JEEP
• one short operational alias like JEEP01

Avoid:

• reusing the same alias across multiple variants
• leaving test-only aliases in public production content
• changing aliases casually after admins or automation already use them

Debug or test variants should stay obviously separate

The current source examples include debug-style variants such as barrier-backed test entries. That is useful during setup, but public servers should keep that separation clear.

Good public rule:

• test or debug variants should have unmistakable names
• keep them out of the normal catalog when possible
• never let a debug alias overlap with the alias of a public vehicle

If you need a vehicle family to have both public and test versions, the alias layer is what keeps that safe.

If you only need one version, explicit variants are still cleaner

Vehicle MC can still resolve a family even when the variant layer is minimal, but public servers are easier to manage when every real vehicle has an explicit variant entry.

Why:

• catalog and key systems think in terms of public entries
• prices belong to the public entry
• aliases belong to the public entry
• later recolors or premium editions become easier to add

If a family is meant to be player-side, giving it one explicit variant is usually worth it.

Publishing workflow that stays clean

1. Build the base family until it drives correctly.
2. Set the lifecycle policy before giving the vehicle to players.
3. Add one explicit public variant.
4. Give that variant stable aliases and a final price.
5. Add extra variants only after the first one is already safe.

Cross-reference points that matter

Lifecycle and variants do not stand alone. They connect directly to:

• vehicle Interactions, Entry, Exit, Trunks, Horns, and Pickup for storage and pickup behavior
• keys, Claims, and Vehicle Redemption for how players receive vehicles
• catalog, UI, Surfaces, and Driver Feedback for how variants are presented
• spawn Pools, Tables, and Display Props for world-spawn use

Related pages

• vehicle Families, Variants, Fuel, and World Service Systems
• vehicle Bases, Controllers, Stats, Seats, and Hitboxes
• vehicle Interactions, Entry, Exit, Trunks, Horns, and Pickup
• keys, Claims, and Vehicle Redemption
• spawn Pools, Tables, and Display Props