Racing Component, Vehicles & Peripherals

V2 is a fighting game that also ships a full racing genre, and the racing side is not a bolt-on minigame — it is seven Unreal C++ modules that follow the same "data plus a load plan" discipline as the rest of the project. A race mode is an FV2RaceModeDefinition value (an id, a family, a ruleset, a network model, a driver-count band, a synthesized Game Feature plugin URL, a map path, and a set of HUD injections), a vehicle is a UV2VehicleDataAsset carrying an engine / drivetrain / tire / suspension / damage / aero / performance bundle, and the physics is an analytical per-frame solver that takes those structs and returns a FV2RacePhysicsFrameResult. The modules are V2Racing, V2Vehicles, V2RacePhysics, V2RaceTracks, V2RaceModes, V2VehicleAudio, and V2VehicleVFX (V2/ue/Source/), all seven registered in V2.uproject (lines 109–139) and all seven compiled on the on-box engine — the build tree carries 9–11 .o objects per module under V2/ue/Intermediate/Build/Linux/.../<Module>/. Their type headers are large and real: V2RaceModeTypes.h alone is 3,970 lines declaring 47 enum classes and 114 USTRUCTs (the per-mode content model for pursuit, combat, drift, rally, bike, futuristic, sports, and crossover racing), and V2VehicleTypes.h is 1,565 lines / 18 enums / 42 structs.

The reason racing looks different from combat starts with one engineering decision: racing does not run on the rollback envelope. The frame-perfect rewind-and-resimulate machine documented in ./rollback-netcode-and-tag-team.md is for 1v1 fighting; continuous vehicle physics across vendors is not bit-identical, so every shipped race ruleset uses a ClientServerAuthoritative or AsyncGhost network model instead. The corresponding promise is not "bit-identical across platforms" but "server-consistent outcomes plus deterministic, reproducible replay." This page owns the racing module set, the vehicle data model, the physics solver, the audio/VFX evaluators, the designer and pit-crew systems, the hardware-peripheral story, and the cook-time ecosystem bridge; the section hub is ../V2_ARCHITECTURE.md.

What ships, honestly#

The racing logic core is real, compiled, and tested. The seven modules build into the editor, and seven automation specs exercise them (V2/ue/Source/V2Tests/Automation/: Racing.Module.spec.cpp, Vehicles.Module.spec.cpp, RacePhysics.Module.spec.cpp, RaceModes.Module.spec.cpp, RaceTracks.Module.spec.cpp, VehicleAudio.Module.spec.cpp, VehicleVFX.Module.spec.cpp). FV2RaceCatalog::BuildDefaultRaceModeDefinitions() constructs 25 canonical race modes — Racing.Module.spec.cpp:54 asserts RaceModes.Num() == 25 — each validated, each carrying ≥3 HUD injections, each with a deterministic CRC signature. The race-lifecycle state machine, the officiating/scoring resolver, the vehicle data-asset quartet and their validators, the analytical physics solver, the engine/tire/damage math, the audio mix-frame and VFX-frame evaluators, and the track data asset are all substantive C++ exercised by those tests. The TypeScript racing-ecosystem-bridge service (apps/v2/racing-ecosystem-bridge/) is also real and composes live sister libraries; its spec has four cases.

Three honest qualifications, all instances of the V2 target-artifact convention (see V2 Product Promise and Game Modes, Mode Plugins, Training & Replay):

• The Game Feature plugins are URLs, not plugins. BuildRacePluginURL() synthesizes strings like Plugins/GameFeatures/V2Race_Circuit/V2Race_Circuit.uplugin (V2RaceCatalog.cpp:34), and map/widget paths like /Game/V2/Racing/Modes/Circuit/L_Circuit are convention strings. No V2Race_*.uplugin directory exists on disk, and there are no .uasset binaries — the racing tree is logic and a content skeleton, validated headless.
• There is no Chaos vehicle solver. The monolith says "the Chaos vehicle solver runs server-authoritative." It does not: a grep for ChaosVehicles / UChaosVehicleMovementComponent across V2/ue/Source returns nothing, and no racing Build.cs lists a Chaos dependency. The physics is a custom analytical model (see below) — which is the honest and, for a deterministic replay budget, arguably better choice; but it is not Chaos.
• There is no Source/V2Peripherals/ module. The monolith places the hardware SDK layer there. In reality peripherals live in V2Input, a balance dataset (V2/balance/data/hardware-peripherals.json), and a V2Tests asset-contract test. The designer's vehicle-designer.proto gRPC service is also absent, and the share-code is a plain string, not the Base32/HMAC grammar described. Each of these is corrected in its section below — honest "implemented elsewhere / not present" beats fake "shipped as described."

The module split#

These extend the fighting-game module set catalogued in Glossary & Module Topology. Responsibilities and the real dependency edges (from each *.Build.cs):

The DAG is acyclic by construction: V2Vehicles defines the data, V2RacePhysics consumes it, V2RaceTracks consumes both, and V2RaceModes sits at the top composing everything. V2VehicleAudio and V2VehicleVFX are leaves that read physics output without feeding back into it — the same "presentation never mutates simulation" rule that combat enforces.

Race modes as data: the catalog and registry#

FV2RaceCatalog::BuildDefaultRaceModeDefinitions() (V2Racing/Private/V2RaceCatalog.cpp:237) is a flat factory that builds 25 definitions via a MakeRaceMode(...) helper. The canonical ids span the design sections the monolith describes but are richer than its 17-node diagram suggests: Race.Circuit, Race.Sprint, Race.Drag.QuarterMile, Race.Drift, Race.TimeTrial, Race.Eliminator, Race.SpeedTrap, Race.Knockout, Race.Outrun, Race.RaceDayTournament, Race.CustomRoom, Race.Pursuit.Evade, Race.CopsVsRacers, Race.Combat.Blur, Race.DeathRace, Race.PowerPlay, Race.CanyonDuel, Race.Rally.Stage, Race.Bike.Street, Race.PodRacer.AntiGrav, Race.Crossover.GetOutAndFight, Race.VehicleSoccer, Race.VehicleStunt, Race.CrashBreaker, and Race.TrackmaniaTimeTrial. Each definition carries a FV2RaceRuleset whose ScoringModel is one of eleven EV2RaceScoringModel values — FinishOrder, BestElapsedTime, DriftScore, SpeedTrapAggregate, EliminatorSurvival, PursuitEscape, CombatTakedown, TournamentPoints, CanyonLeadDistance, GoalScore, StuntComboScore, CrashDamageScore — and the catalog wires sensible specifics: drag sets bRequiresPerfectLaunch with BestElapsedTime scoring, drift uses DriftScore, Race.VehicleSoccer uses GoalScore with MaxDrivers == 8 (4v4).

HUD is data, not layout code. BuildDefaultHUDInjectionsForMode() (V2RaceCatalog.cpp:181) always emits a Timer (slot Slot.TopCenter, priority 120), a PositionTower, and an ObjectiveTracker, then branches on the scoring model — DriftScore → DriftMeter, GoalScore → GoalScoreboard, StuntComboScore → StuntMeter, CrashDamageScore → CrashDamage, BestElapsedTime/SpeedTrapAggregate → SectorSplits, PursuitEscape → PursuitHeat — and appends PowerUpInventory + VehicleDamage when combat is allowed and a PowerPlayPrompt when power-plays are on. That is why the test can assert "drift mode exposes the drift HUD layer" without a single widget asset existing: the injection is a FV2RaceHUDInjectionSpec with a FSoftClassPath pointing at a convention widget path. These HUD layers are the racing entries that the HUD system in ./ui-hud-vr-ar-and-accessibility.md consumes.

Lifecycle and officiating, worked end to end#

UV2RaceRegistrySubsystem (V2Racing/Public/V2RaceRegistrySubsystem.h) is the runtime. The lifecycle is an enforced state machine — IsLegalTransition() (V2RaceRegistrySubsystem.cpp:381) only allows Registered/Lobby → Staging → Countdown → Racing → FinalLap → Finished → Officiating → Results, with Aborted reachable from any live state. A worked example, exactly as Racing.Module.spec.cpp drives it:

Two real behaviours fall out of that flow. First, online modes fail loud when services are absent: BuildRaceStartSnapshotFromDefinitions rejects an offline request for an online-required mode with the message "requires online racing services" (Racing.Module.spec.cpp:176) — a fail-closed gate, not a silent downgrade. Second, officiating is scoring-aware: for a FinishOrder circuit it ranks lower elapsed time first (Driver.B at 184 000 ms beats Driver.A at 186 000 ms), and for a DriftScore race it ranks higher score first (Driver.A at 120 000 beats Driver.C at 101 000), with a red-light penalty surfaced as an incident. The whole catalog hashes to a deterministic CRC (BuildCatalogSignature, V2RaceCatalog.cpp:286) so a content drift shows up as a changed signature in CI.

V2RaceModes adds a second registry, UV2RaceModeRegistrySubsystem, that turns each definition into a FV2RaceModePluginDescriptor (MakePluginFromRaceMode, V2RaceModePluginCatalog.cpp:86) carrying the synthesized GameFeaturePluginURL, the RequiredModules, and an EV2RaceModePluginState (Unregistered → Registered → Loading → Active → Suspended/Failed). BuildActivationPlan produces the eight ordered EV2RaceModeActivationSteps — ValidateRequest, LoadRequiredModules, ActivateGameFeature, RegisterTrackRules, InjectRaceHUD, OpenTrackMap, StartRaceState, MarkReady. The plan and the module-load are real C++; the Game Feature plugin the plan would activate is the target-artifact URL.

Vehicles: data assets and the chassis component#

A vehicle ships as four UPrimaryDataAsset subclasses (V2Vehicles/Public/V2VehicleDataAssets.h): UV2VehicleDataAsset (the base spec), UV2VehicleTuneDataAsset, UV2VehicleCustomizationDataAsset, and UV2VehicleDamageDataAsset — the DA_Vehicle family the monolith names. The base asset composes a stack of validated structs: a FV2VehicleEngineRPMModel (idle/redline/peak-torque RPM, MaxTorqueNm, aspiration, per-RPM-bin sound ids, turbo BoostPressureKpa + BoostSpoolDelaySeconds, and a TSoftObjectPtr<UCurveFloat> torque curve), a FV2VehicleDrivetrainModel (layout across FWD/RWD/AWD/4×4/ bike-chain/hover/hover-magnet, gear ratios, ShiftTimeMs, a PerfectShiftWindowMs of 45 ms, clutch-kick multiplier), a FV2VehicleTireModel (dry/wet/dirt grip, lateral stiffness, slip-angle peak, heat/wear rates), plus mass, collision, aero, suspension, damage, and performance-envelope structs. Every struct has an IsValid…(OutErrors) validator and the asset's BuildPerformanceRating() rolls a single number out of the envelope.

UV2VehicleChassisComponent (V2VehicleChassisComponent.h) is the runtime that brings a data asset to life: ConfigureFromVehicleData() copies the models in, ApplyTuneData() layers a tune, TickDrivetrain(Delta, Throttle, Brake) steps RPM and wheel speed, ShiftToGear() handles the box, and CalculateAvailableWheelTorque() / CalculateCurrentGrip(Wetness, Dirt) expose the derived numbers. The math underneath is genuinely domain-specific rather than CRUD: FV2VehicleTireModel::CalculateSurfaceGrip lerps dry→wet by wetness then that result→dirt by coverage (V2VehicleTypes.cpp:389), and the engine's CalculateTorqueAtRPM interpolates the curve. This is the data the EV cook-time bridge and the designer both manipulate.

Race physics: an analytical per-frame solver#

UV2RacePhysicsComponent::SimulateFrame() is the entry point (V2RacePhysicsComponent.cpp:16). It does not own an integrator; it delegates to UV2RacePhysicsBlueprintLibrary::SimulatePhysicsFrame() (V2RacePhysicsBlueprintLibrary.cpp:197), which composes the result from a set of small, named, closed-form functions: a normal force from the suspension (CalculateNormalForce), a surface grip from tire × contact patch × the handling profile's TractionScale, a yaw torque, a hover force, a stepped bike-lean angle, and a pod-magnet centering force. The handling personality is a FV2RaceHandlingTuning selected from nine EV2RacePhysicsHandlingProfiles (Arcade, Simcade, Simulation, Drift, OffRoad, Rally, Bike, AntiGrav, PodRacer) plus a 0–100 ArcadeSimDial — the continuous arcade↔sim spectrum the design calls for.

The yaw-torque formula is a fair example of the model's honesty — CalculateYawTorque (V2RacePhysicsTypes.cpp:101) is:

yaw = (steer + counterSteer) · SteeringResponse · max(0, grip) · speedFactor · assistMul
      − YawDamping · speedFactor · 0.10

where speedFactor = clamp(speedKph / 160, 0.15, 1.60), counterSteer is a negative feedback term scaled by the auto-counter-steer assist, and assistMul softens torque when stability assist is on. It is a real steering response with speed sensitivity and an assist seam, not a constant. The same shape recurs in drafting (CalculateDraftDragScale, V2RacePhysicsTypes.cpp:242: a slipstream that starts at 42 m, peaks at 7.5 m, and removes up to 24% drag), in the bike lean, the hover spring, and the pod-magnet centering. The exotic chassis types each get their own state struct — FV2OffroadSuspensionState, FV2BikeLeanState (max lean 58°), FV2AntiGravHoverState (target height 180 cm, magnet strength, damping), FV2PodRacerMagnetState — so a hovercraft and a superbike use the same solver with different inputs.

Crucially, V2RacePhysics also carries a FV2RaceDeterminismConfig (seed 1337, FixedStepHz = 60, bQuantizeFloatingPoint, and a BuildDeterministicFrameHash that HashCombines seed/frame/input/step into a non-negative int32) and a FV2RacePhysicsLODConfig whose ResolveLODMode returns Full / ReducedFidelity / PoseInterpolationOnly by distance and on-screen flag. This is the data spine behind the replay-determinism gate and the server-authoritative LOD model: the server runs full physics for all vehicles; the client LOD only changes local visual fidelity, never sync. One honest nuance — the determinism config exposes bRollbackEligibleUpToEightPlayers, but no shipped race mode in the catalog selects a rollback netcode model; the flag is a forward-looking data field, and the live promise remains client-server with prediction, consistent with ./rollback-netcode-and-tag-team.md.

Damage model#

Damage is five EV2VehicleDamageTier steps — Clean, Scuffed, Damaged, Wrecked, Totaled — each a FV2VehicleDamageTierModel with a decal preset, bend-deformation scalar, part-fall-off chance, steering pull, engine-power-loss percent, brake-failure and transmission-seize chances, and a repair cost. The performance consequence is computed, not cosmetic: GetEnginePowerScale (V2VehicleTypes.cpp:187) returns 1.0 when the ruleset is arcade and bCosmeticOnlyArcadeDamage is set, otherwise clamp(1 − EnginePowerLossPct, 0, 1) for the active tier. Totaled flips bTotaledTriggersRetireOrGetOutAndFight, which is the hook into the racing×fighting crossover (Race.Crossover.GetOutAndFight) — a totaled car can retire the racer or dump them out to fight on foot.

Damage is also where licensing meets gameplay. FV2RacingManufacturerDamagePolicySpec gates LicensedLuxuryPermission to CosmeticOnly while OriginalIPPermission allows FullDamage, and FV2RacingVehicleLicenseContractSpec records manufacturer-signed contracts and a DamagePermission. These live in the §119 FV2RacingComplianceCertCatalog, which also carries region variants (a bChinaPublisherSKUAdjustsCopVisuals flag, kph/mph display unit), a content-safety policy (no impaired-driving depiction; "incapacitate not kill" outside Death Race), the anti-cheat gate ids (impossible-time detection, the replay-determinism gate, valid tuning ranges), and the cert/accessibility specs. The region-variant companion doc the catalog points at, V2/docs/regions/racing-variant.md, does exist. Compliance detail belongs to ./security-compliance-and-sister-monorepo-integration.md.

Audio and VFX subsystems#

Both presentation subsystems are pure evaluators. UV2VehicleAudioSubsystem registers per-vehicle FV2VehicleEngineAudioProfiles and ambience zones, then EvaluateVehicleMixFrame(VehicleId, turbo, tire, doppler, RPM, throttle, boost) returns a FV2VehicleAudioMixFrame — the per-RPM-bin engine note blend, turbo spool / blow-off, tire screech, and Doppler shift resolved into one frame. The engine model's five RPM-bin sound ids (IdleRPMBinSoundId … RedlineRPMBinSoundId, plus an optional BlowOffValveSoundId) come straight from the vehicle data asset, so audio is authored on the same struct that drives physics. UV2VehicleVFXSubsystem mirrors this: EvaluateVehicleVFXFrame(smoke, spark, debris, motion, glow, airborne) returns a FV2VehicleVFXFrame, and the subsystem also holds the FV2RacingVFXDeepCatalog. Neither subsystem ships particle or wave assets — they resolve parameters that an authored asset would bind to — which is consistent with the broader presentation pipeline.

Vehicle Designer, Pit Crew, and telemetry#

V2VehicleTypes.h carries the whole §120 designer suite as validated structs. FV2CustomVehicleDesignerSpec lists the authored components (chassis silhouette, engine-bay layout, suspension mounts) and a set of slider-based FV2CustomVehicleGeometryControlSpecs that feed an autosculpt subdivision surface. The balance gate is real and specific: FV2CustomVehicleBalanceBudgetSpec sets a TotalStatBudget of 1000, a MaxTopSpeedPenaltyPer100KgKph of 8.0, and a bBudgetLinterBlocksOutOfRangeBuilds flag — the "heavier chassis slows top speed, bigger engine raises torque and mass" tradeoffs the design promises. FV2CustomVehicleSaveShareGallerySpec sets 10 save slots per user and gates ranked eligibility to the designer-approved subset while leaving casual/private lobbies always eligible.

The pit-crew minigame is genuinely deterministic, not a Math.random() fake: FV2PitCrewActionSpec::ResolvePitStop(StepTimingHits, BaseSecondsPerStep) (V2VehicleTypes.h:1330) takes a vector of per-step timing hits and returns a FV2PitStopResult — a hit step costs the base time, a missed step costs double, and a flawless run is the perfect stop. Mechanic specialty cuts pit time 30%, other specialties 10% (FV2PitCrewMechanicMinigameSpec). Driver telemetry (FV2DriverTelemetryDashboardSpec), auto-classified driving styles (Aggressive/Defensive/Drafter/Reckless/Conservative/SlipstreamMaster/DriftSpecialist), and a heat-map spec round out the profile surface that ./telemetry-performance-testing-and-release-gates.md and ./live-ops-store-progression-and-community.md build on.

Two corrections to the monolith's "service contract" here. The promised gRPC service libs/proto/v2/racing/vehicle-designer.proto is absent, and the share-code is not a "Base32-encoded 12-char HMAC over vehicle hash + watermark + nonce." The actual implementation is human-readable: SaveSlot.ShareCode = FString::Printf(TEXT("V2-%s-%s"), VehicleId, SlotId) (V2VehiclesBlueprintLibrary.cpp:355). The originality-shields review the monolith cites is real (V2/docs/decisions/originality-shields-launch-gate.md exists), but the cryptographic share grammar and the gRPC façade are spec-described, not shipped.

Hardware peripherals — where they actually live#

There is no V2Peripherals module. The peripheral story is split across three real places. The input layer is V2Input — V2InputTypes.h declares EV2HardwarePeripheralClass (SteeringWheel, PedalSet, …) alongside the rest of the fighting-game input model documented in ./animation-and-input-pipeline.md. The vendor catalogue is data: V2/balance/data/hardware-peripherals.json is the shipped source of truth, enumerating wheels from Logitech, Thrustmaster, Fanatec, Hori, MOZA, Cammus, Asetek SimSports, and Simucube; pedals, shifters, handbrakes, button-boxes, sim-rigs (SimVibe/ButtKicker bass shakers), fight-sticks, and the adaptive controllers (PlayStation Access, Xbox Adaptive Controller, Logitech Adaptive Gaming Kit, Quadstick). It also encodes the force-feedback model (per-vehicle authored profile; per-corner suspension, per-tire grip, per-collision impact, per-curb rumble; gain/dynamic-range/linearity/damping/spring/friction tuning UI; direct-drive torque scaling; a community profile gallery), a first-launch calibration wizard with load-cell brake and pedal-curve calibration, and the ranked-pool separation (wheel+pedals vs gamepad in separate tournament pools, gamepad pool with more assists by default). The C++ cert surface is a subset: EV2RacingWheelVendor in V2RaceTypes.h lists only the five primary vendors used by FV2RacingCertWheelSupportSpec, while the balance JSON covers eight wheel makers. Validation runs through V2Tests (HardwarePeripherals.spec.cpp and the V2.Input.HardwarePeripherals.AssetContract automation the JSON names at its tail). So the capability the monolith promises is real; the file layout it asserts is wrong.

The cook-time ecosystem bridge#

The one piece of racing that runs as a TypeScript service rather than UE C++ is apps/v2/racing-ecosystem-bridge/. buildV2RacingEcosystemBridgeExport() composes four sister-monorepo libraries to produce a cook-time manifest: it models the driver as an articulated body through @galatea/kinematics + @galatea/whole-body-control (mass matrix, gravity-compensation torque, center-of-mass support-polygon containment), configures an EV powertrain through @saraswati/ev (PowertrainConfigurator → motor, gear ratios, regen, drivetrain efficiency, estimated cost), and evaluates the track world through @maya/genesis-terrain + @maya/genesis-urban (streaming-LOD and road-network coverage). The output is a status (ready/needs-attention/blocked), an issue list, and a cookManifestText.

The bridge's defining property is a hard boundary: its V2_RACING_ECOSYSTEM_BRIDGE_ROLLBACK_POLICY is authoring-and-content-cook-only-no-live-race-frame-rpc, it sets offRollback: true / mayInfluenceRollback: false / rejectsLiveRaceFrameRpc: true, and validateRequest throws if calledFromLiveRaceFrame is set. In other words, this composition can shape vehicles and tracks at cook time but is structurally forbidden from touching a live race frame — the same discipline that keeps presentation out of simulation, applied at the service boundary. It is the racing entry point into the sister-monorepo integration covered by ./security-compliance-and-sister-monorepo-integration.md and the build/cook pipeline in ./build-cook-assets-data-and-production.md.

How it connects to neighbouring systems#

Racing is deliberately a peer genre that reuses the fighting backbone rather than forking it. Combat pickups, Death Race weaponization, and Get-Out-and-Fight all route into the GAS layer in ./combat-system-gas-frame-data-and-determinism.md; race HUD layers are injected through the system in ./ui-hud-vr-ar-and-accessibility.md; race modes are registered, loaded, and lifecycle-driven by the same discipline as the fighting modes in ./game-modes-training-and-replay.md; matchmaking, ranked MMR, anti-cheat, and the autolog rivalry surface live in ./online-backbone-and-competitive-integrity.md; free-roam convoys, heists, and demolition derby are the open-world racing modes in ./open-world-coop-and-special-modes.md; and the AI driver personalities, cop AI, and the racing AI director connect to ./esports-companion-and-ai-services.md. The shared roster, currency ledger, store, and Battle Pass that make the crossover economically coherent are in ./live-ops-store-progression-and-community.md. For the design source this page reorganizes and corrects, see the racing sections of ../V2_ARCHITECTURE.md.