Skip to content

Vehicle customization domain

CarData.Customization is the persisted and replicated source of truth for vehicle appearance. Canonical customization has a SchemaVersion; data without one is legacy data and must be migrated before use. UI and server consumers read customization from the vehicle's CarData rather than maintaining a separate read model. See Vehicle car data and persistence for loading, migration, architecture, quarantine, and compatibility invariants.

This document owns customization semantics and purchasing behavior. Model naming and target discovery are authoring contracts documented in Vehicle asset authoring contracts; they are summarized here only where needed to explain the domain behavior.

Paint

Canonical paint has three independent slots:

  • primary targets body parts named Paint, plus supported legacy paintable markers.
  • secondary targets body parts named Secondary.
  • brake-caliper targets parts named Paint beneath Wheels.

Editors expose only slots with observable targets on the preview model. Dealership, customization, garage, and spawned-vehicle rendering must use the same target rules.

TrimDef.FactoryPaints describes bundled dealership options. A string is shorthand for a combination whose primary and secondary colors are the same. A table can specify primary, secondary, brake-caliper color, stable option ID, and display name. The option ID selects a bundle; it is never persisted. Purchases persist the resolved paint selections.

The customization shop derives independent primary and secondary catalogs from the dealership combinations. Brake-caliper choices come from the global brake-caliper catalog. Model color inference is only for dealership previews whose bundle omits a caliper color.

Assembly accessories

The assembly tree records what is installed. AssemblyItemsOwned is a separate, per-vehicle flat set keyed by accessory part ID. Ownership is independent of socket and installation path. A part the vehicle shipped with is owned, including nested accessories. Buying an unowned part ID charges once and makes that ID free to install anywhere it is valid on that vehicle.

Installed livery selections remain keyed by assembly part address because different parts can display different liveries. AssemblyLiveriesOwned is a separate, per-vehicle flat set keyed only by stable livery ID. Buying a livery ID charges once and makes it free anywhere that livery is compatible on that vehicle.

Customization purchase pricing is authoritative on the server. Purchase commits are discriminated by vehicle architecture. A legacy commit contains only canonical customization; an assembly-v1 commit contains canonical customization, the complete assembly root, accessory ownership grants, and livery ownership grants. These consequences constitute one purchase and must be committed atomically.