Skip to content

Vehicle system architecture

Vehicle behavior crosses legacy and new code. This page is a map of ownership and data flow, not a replacement for the focused reference documents.

Definition and asset layer

src/Shared/VehicleDef/ owns shared vehicle and trim definitions, paint and rim catalogs, dealership package groups, and catalog entries. VehicleDef.AssemblySystem selects a legacy asset shape or assembly-v1 composition. See Vehicle assets for model shapes and Dealership package groups for purchasable configurations.

Assembly-v1 definitions use stable part IDs to address assembly, accessory, and tuning definitions. Definition IDs are saved-data or package contracts; asset paths may move as long as definitions continue to resolve the stable IDs.

Dealership flow

The dealership catalog exposes legacy trim entries and assembly-v1 package-group entries. Package selections resolve into a purchased vehicle_id, final assembly, tuning choices, and canonical paint/rim selections. Lune scripts validate assembly-v1 package configurations offline, and the server authoritatively creates the saved vehicle during purchase.

The package's vehicle_id is the persisted trim identity. Helpers may derive a trim from a preview assembly for specifications and available paint/rim options, but that derived value does not replace the package's purchase identity.

Persistence and garage flow

CarData is the runtime and replicated owned-vehicle record. Loading partitions persisted records into canonical Cars and preserved UnavailableCars before garage replication and other vehicle consumers start. Runtime systems consume only canonical cars.

VehicleArchitecture discriminates legacy and assembly-v1 records. Assembly-v1 records additionally persist their assembly snapshot and accessory/livery ownership ledgers. See Vehicle car data and persistence for the load sequence and compatibility rules.

Customization flow

CarData.Customization is the appearance source of truth for dealership results, garage previews, the customization editor, and spawned vehicles. The server owns validation, pricing, ownership grants, and atomic commits. Assembly-v1 commits can update the complete installed assembly alongside customization and ownership.

All render paths are expected to use the same paint-target rules. See Vehicle customization for domain semantics and Vehicle asset authoring contracts for model requirements.

Model and spawn flow

Preview resources and VehicleModelManager resolve the correct legacy asset or build an assembly-v1 model from its saved or package assembly. Assembly building clones physical parts, applies accessories and tuning overlays, and produces the model consumed by previews or the spawn path.

The server spawn lifecycle is owned by src/Server/FrameworkRevamp/SpawnedVehicleManager/. Spawned models receive canonical customization and architecture-specific setup. Assembly-only services, such as folding mirrors and assembly ELS, discover their tagged models after assembly.

Change boundaries

When changing vehicle behavior, identify which contract is affected:

  • Definition IDs, vehicle IDs, option IDs, architecture values, and schema versions require saved-data compatibility consideration.
  • Asset paths and model structure require every preview and spawn consumer to continue resolving the same stable definitions.
  • Package changes must preserve explicit purchase identity and pass server package validation.
  • Customization changes must remain consistent across dealership, garage, editor, and spawned rendering.
  • Historical generation records in docs/vehicles/case-studies/ describe past work and are not updated to follow current definitions.