Production schedule — 2026-09-13: PIPE-ROADMAP now defines 32 focused phases (P00–P31). Phase 0/1/2/3 references retained in this document are legacy scope bands, not the new phase numbers. The owner confirmed limited-area core-loop proof before full-map expansion; see the roadmap for dependencies, audited status and remaining work.
Production context
GDD/02-World/02-Vehicles.mdVerified implementation evidence
- Not verified for this documentation pass.
Relationships
TECH-NETWORK-ARCHFEAT-INVENTORYtool rolesFEAT-LOCK-ACCESS— canonical vehicle lock, key, Lockpick and Hotwire rules
Document contract coverage
Use these required Feature Specification areas during review. The HTML content below is authoritative; items not stated explicitly remain unresolved.
- ReviewPurpose & Player Value
- ReviewScope
- ReviewOut of Scope
- ReviewTerminology
- ReviewFunctional Behavior
- ReviewStates & Flows
- ReviewRules & Edge Cases
- ReviewDependencies
- ReviewAcceptance Criteria
- ReviewOpen Questions
Authoritative project content
Drivable vehicles are in — [CONFIRMED]. Vehicles serve traversal across a large open world, hauling loot/resources, and squad mobility.
Roles
- Traversal: cross the map faster than on foot; reach distant POIs and boss sites.
- Logistics: carry gathered resources and loot (vehicle storage).
- Squad mobility: move a squad together; a getaway after a raid.
- Risk object: vehicles are loud (attract zombies), need fuel, can be damaged or destroyed, and are valuable persistent assets. Vehicle recovery/theft is supported through cabin Lockpick, exact-ID keys and permanent skill-gated Hotwire.
Vehicle types — [RECOMMENDATION] (final list [TBD])
| Type | Role |
|---|---|
| Light car / sedan | Cheap, fast, low storage |
| Pickup / off-road | Storage + rough terrain |
| (Later) larger transport | Squad + heavy hauling |
Start with one well-tuned drivable vehicle in v1; expand later. Vehicles are explicitly a Phase-2 system in the roadmap (see ../00-Overview/02-Scope-and-Constraints.md).
Systems
- Fuel: consumes a fuel resource; refuel from jerry cans / gas stations. Out of fuel = stranded.
- Damage & repair: vehicles take damage (collisions, gunfire, zombies); repair with resources/kits. Can be wrecked. [CONFIRMED 2026-09-13]
Action.VehicleRepairalso requires the acting player to possess (inventory, not all held) items coveringTool.Role.JackANDTool.Role.ScrewdriverANDTool.Role.Pliers. Those ItemIds are not registered. Kits/resources remain separate. Bumper/frame install tools stay inTBD-VEHICLE-ADDON-001. Canonical contract:FEAT-INVENTORY. - Storage: integrated container (server-authoritative, persisted while the vehicle persists). Vehicle keys affect driving only; Vehicle Storage has no built-in lock and is not eligible for the confirmed installed Lock item.
- Ownership / access — [CONFIRMED 2026-09-17]: 90% of first-spawn vehicles start locked; 10% start unlocked and may be driven without a key when separately operationally ready. A matching key stores the exact Vehicle ID and may be left inserted. Squad membership alone does not grant ignition access. Lockpick opens the cabin only; ignition still requires the matching/inserted key or permanent Hotwire. Canonical rules:
FEAT-LOCK-ACCESS. - Persistence — [CONFIRMED]: vehicles use full gameplay-state persistence across dedicated-server restarts through SQLite records. See the contract below and Network Architecture.
Full vehicle persistence contract — [CONFIRMED]
“Full vehicle persistence” means every gameplay-relevant state owned by a vehicle must survive unload, restart, and reload. A vehicle is restored as the same instance, not respawned as a fresh copy.
| State group | Required persistent data |
|---|---|
| Identity and schema | Stable unique vehicle ID, vehicle definition/class ID, record/schema version, creation time, and last-save time. |
| World placement | Authoritative transform and the world/region identity needed to restore the vehicle at its saved location. |
| Ownership and access | Original spawn point, initial/current cabin lock state, ignition key requirement, permanent Hotwire state, inserted-key link, and the stable Vehicle ID referenced by every valid matching key item. |
| Condition | Overall durability plus per-component damage and destroyed/disabled state for every implemented vehicle subsystem. |
| Resources and operation | Fuel and every implemented consumable or operational subsystem value, including engine/on-off state where applicable. |
| Inventory | Integrated storage contents with complete item-instance state, quantities, durability, attachments, magazine contents, blood, wetness, and nested container references supported by the inventory model. |
| Installed configuration | Installed parts, upgrades, equipment, and cosmetic/customization selections that change the vehicle instance. |
| Lifecycle | Wrecked/active state and any implemented respawn, abandonment, recovery, or cleanup timestamps and flags. |
- The dedicated server is authoritative. Vehicle state lives in RAM while active and dirty records are written asynchronously/periodically, with final flushes on critical transitions and graceful shutdown.
- All mutations affecting persisted state—including storage, fuel, damage, repair, access, and installed parts—must dirty the same stable vehicle record or an explicitly linked child record.
- Persistence is versioned so future vehicle subsystems can add fields without replacing the vehicle identity or silently resetting existing state.
- Transient runtime references such as current actor pointers, network connections, physics contacts, and seat-occupant object references are reconstructed from authoritative saved IDs/state and are not serialized as durable object references.
Technical notes — [RISK]
- Networked vehicle physics is hard. Replicated, physics-driven vehicles with passengers, smooth client experience, and anti-cheat are a well-known source of bugs and cost. Budget accordingly; this is a key reason vehicles are Phase-2, not Phase-1.
- Use UE's Chaos Vehicle system as the baseline; evaluate replication smoothing carefully for ~40–60-player servers.
- Players riding vehicles must attach/replicate correctly (seats, exit, ragdoll on crash).
- Vehicles attract/aggro zombies (ties to ../03-Enemies/01-Zombie-Design.md).
Implementation guidance
- Vehicle as a C++ pawn using Chaos Vehicle Movement; per-vehicle stats (speed, fuel capacity, storage size, HP) data-driven.
- Interaction (enter/exit/seats) via the player's
UInteractionComponent.
Vehicle lock, key and Hotwire — [CONFIRMED 2026-09-17]
FEAT-LOCK-ACCESS owns the detailed flow. Matching keys may spawn in World Containers or on zombies near the vehicle's original spawn point, not its moved location. Lockpick permits entry but never starts the vehicle. Successful skill-gated Hotwire permanently and durably lets everyone drive without a key. Exact action tuning, key population values and operational-readiness rules remain TBD there.
Vehicle UI contract — [CONFIRMED]
FEAT-HUD-UI uses a hybrid presentation: speed and RPM are primarily diegetic, while fuel, damage, gear, seats, and access state are readable in the overlay. Vehicle storage is not persistently displayed and opens through IA_Inventory.
Exterior additions and protection
[CONFIRMED] 2026-09-13: extend vehicle customization to include add-on bumpers and exterior protective steel frames. This expands the gameplay design; it does not verify any existing runtime implementation.
| Addition | Confirmed scope | Undecided behavior |
|---|---|---|
| Bumper | Attachable vehicle addition | Vehicle fit, front/rear locations, impact/protection effects, durability and installation rules. |
| Exterior protective steel frame | External protective structure fitted to a vehicle | Protected regions, collision/occlusion, damage behavior, mass and compatibility. |
These examples do not approve a complete catalog, unrestricted attachment placement, a free-form building editor or interior roll cages. Additional categories and the exact installation workflow remain TBD.
Configuration and persistence
The existing full vehicle persistence contract applies to these additions: restore installed part identity/configuration and all implemented condition state on the same stable vehicle instance. Specific part/slot data structures remain undecided. The existing vehicle-key driving rule remains authoritative; modification permissions require a separate decision.
Flow and review criteria
Installation eligibility → authoritative configuration change → updated presentation → persisted state is the review outline. Inventory transactions, incompatible-part rejection, interrupted work, removal of damaged parts and concurrent edits need defined behavior before implementation.
AC-VEHICLE-ADDON-DOC-001: bumpers and protective exterior steel frames are explicitly represented in vehicle scope.AC-VEHICLE-ADDON-PLAY-001: after design approval and implementation, owner-check compatible/incompatible installation, access, removal, collision and damage behavior with two clients.AC-VEHICLE-ADDON-SAVE-001: owner restart checks restore installed configuration and every implemented condition value without duplication or resetting the vehicle ID.
Runtime criteria are pending; no PIE pass is asserted.
TBD-VEHICLE-ADDON-001 — Compatibility and installation
Which vehicles support bumpers and protective exterior steel frames; attachment locations, fit rules, installation/removal/replacement, tools, costs, access permissions and the player-facing interface.
TBD-VEHICLE-ADDON-002 — Protection and tradeoffs
How each part affects impact, gunfire or zombie damage, protected regions, durability, repair, destruction, collision shape, mass, handling, fuel consumption and visibility. No protection values or movement penalties are approved.
TBD-VEHICLE-ADDON-003 — Content and delivery
First supported vehicle/part set, material recipes, progression, art specifications, installation UI scope and whether customization ships with the first vehicle or a later P23 increment.