Vehicles¶
Responsibility¶
vehicle models a movable assembly of vehicle_part instances, including mounts, cargo,
engines, batteries, controls, faults, labels, zones, power networks, motion, collisions,
autodrive, and interaction.
Entry points¶
Read src/vehicle.h and focused vehicle_*.cpp files. Definition data enters through vehicle
prototypes and part registries; placement integrates with map; persistence is implemented in
src/savegame_json.cpp.
Data ownership¶
A vehicle owns its part vector and part-contained items. Loaded submaps own vehicle instances;
map vehicle caches index their occupied points. A vehicle_part_location is a checked locator,
not independent ownership.
Dependencies¶
Vehicles depend on map coordinates and caches, item pockets, part/type registries, fuels and energy units, characters, creatures, zones, activities, and physics calculations.
Lifecycle¶
A prototype spawns or a save loads a vehicle; parts install, remove, shift and refresh; the map tracks movement and collisions; splits create distinct owners; unload/save persists each assembly.
Invariants¶
Part mount coordinates and cached occupied points agree; referenced parts remain valid only within their documented lifetime; cargo has one owner; power and mass caches invalidate on part changes; splits do not duplicate parts or labels.
Extension points¶
Prefer JSON vehicle parts and prototypes. Native behaviors belong in a focused component and must update refresh/cache, interaction, serialization, and split rules together.
Serialization¶
vehicle::serialize / deserialize and vehicle-part persistence live in
savegame_json.cpp. Derived physics and map caches rebuild; durable part state needs old-save
defaults and migration handling.
Tests¶
Use vehicle part, split, power, efficiency, drag, ramp, turret, export, fake-part, interaction, and mapgen-placement tests according to the change.
Performance¶
Movement recalculates occupied tiles and physics frequently. Preserve dirty flags, avoid full part scans per queried property, and benchmark large moving assemblies.
CCB divergence¶
CCB vehicle data and code are selectively ported and may not share upstream cache or save semantics. Validate against CCB prototypes, tests, and current serialization.
Technical debt¶
Parts, caches, physics, power, UI, and persistence remain tightly coupled. Refactors need a dedicated non-behavioral change with round-trip and movement evidence.