VehicleAsset — Vehicle Definitions

Advanced40-60 minutesWindowsVisual Studio

VehicleAsset is the largest single asset class in Unturned at 2,809 lines. It defines every aspect of a vehicle: engine type, speed, acceleration, steering, fuel, battery, health, damage resistance, turrets, passenger seats, paint, cargo storage, wheel configuration, engine simulation with RPM and gears, bumper damage, explosion behavior, and network validation parameters. It extends Asset directly and uses the VEHICLE asset category rather than the ITEM category.

Source code location: Unturned/Bundles/VehicleAsset.cs

Inheritance Chain

Asset
  → ISkinableAsset  (interface)
  → IArmorFalloff    (interface)
    → VehicleAsset
    → VehiclePhysicsProfileAsset
    → VehicleRedirectorAsset

Engine Types

public enum EEngine { CAR, BOAT, HELICOPTER, PLANE, BLIMP, TRAIN }

Property	CAR	BOAT	HELICOPTER/PLANE	TRAIN
Default physics profile	defaultProfile_Car	defaultProfile_Boat	defaultProfile_Helicopter/Plane	None
Fuel burn rate	2.05	4.2	4.2	—
Valid speed up	12.5	3.25	100	100
Valid speed down	25.0	25.0	100	100
Default steering tires	2	1	1	1

Model Loading

Vehicle models are loaded via deferred asset references:

private IDeferredAsset<GameObject> clientModel;      // "Vehicle" prefab
private IDeferredAsset<GameObject> legacyServerModel; // "Clip" prefab (deprecated)

Load Order

1. If on dedicated server and Has_Clip_Prefab is true, load "Clip" first. Fall back to client model.
2. Otherwise, load "Vehicle" client model.

OnClientModelLoaded

When the client model loads:

• Detects Headlights, Sirens, Hook child transforms.
• Determines _pitchIdle and _pitchDrive from AudioSource clip name.
• Runs AssetValidation and server-side component removal.
• Validates the Seats transform and checks for root Rigidbody.
• If no physicsProfileRef is set and root/wheel masses are 1.0, auto-assigns the default profile by engine type.
• Recursively tags all children with "Vehicle" for hit detection.
• If no wheelConfiguration is explicitly set, calls BuildAutomaticWheelConfiguration.

Speed and Acceleration

Field	Type	Description
TargetReverseVelocity	float	Maximum reverse speed (negative value)
TargetForwardVelocity	float	Maximum forward speed, multiplied by 1.25 unless TRAIN
_brake	float	Brake torque
_lift	float	Helicopter/plane lift force
engineForceMultiplier	float	Global force multiplier (default 1.0)
airTurnResponsiveness	float	Air vehicle turn speed (default 2)
airSteerMin	float	Air steering at max speed
airSteerMax	float	Air steering at zero speed

Steering System

Field	Type	Description
MaxSteeringAngle (_steerMax)	float	Steering angle at zero speed (deg)
MaxSteeringAngleAtFullSpeed (_steerMin)	float	Steering angle at max speed (deg)
SteeringAngleTurnSpeed	float	Steering wheel rotation rate (deg/s)
CrawlerTrackSteeringTorque	float	Differential torque for tank steering
CrawlerTrackSteeringSidewaysFrictionMultiplier	float	Side friction reduction during tank turns
CrawlerTrackSteeringMaxSpeedScale	float	Steering effectiveness at max speed

Steering angle is interpolated between MaxSteeringAngleAtFullSpeed and MaxSteeringAngle based on |speed| / |targetSpeed|. This provides tighter turning at low speeds while maintaining stability at high speeds.

Bicycle / Motorcycle Leaning

Field	Type	Description
steeringLeaningForceMultiplier	float	Roll torque per steering input (default -1 = disabled)
steeringLeaningForceShouldScaleWithSpeed	bool	Scale leaning force with speed
steeringLeaningForceSpeedExponent	float	Speed exponent for scaling

Wheel Configuration

Each wheel has a detailed VehicleWheelConfiguration entry with fields for collider path, model path, power state, steering mode, motion effects, and explosion behavior.

Key Configuration Fields

Field	Type	Description
wheelColliderPath	string	Hierarchy path to WheelCollider
isColliderPowered	bool	Whether motor torque is applied
modelPath	string	Path to visual wheel model
isModelSteered	bool	Whether model rotates with steering
modelUseColliderPose	bool	Use GetWorldPose for positioning
modelRadius	float	Visual-only wheel radius (RPM calculation)
copyColliderRpmIndex	int	Copy RPM from another collider
copyCrawlerTrackSpeedIndex	int	Copy crawler track speed
steeringAngleMultiplier	float	Per-wheel steering multiplier (default 1.0)
modelSuspensionOffset	float	Vertical model offset for suspension
modelSuspensionSpeed	float	Interpolation speed
motionEffectsMode	EWheelMotionEffectsMode	Particle effects mode
canExplode	bool	Wheel flies off on explosion (default true)
steeringMode	EWheelSteeringMode	None/SteeringAngle/CrawlerTrack
crawlerTrackForwardMode	ECrawlerTrackForwardMode	Tank track rotation direction

Automatic Configuration

If no WheelConfigurations list is provided, BuildAutomaticWheelConfiguration reconstructs the legacy layout:

1. Tires transform → children Tire_N → each gets a configuration. First 2 wheels steer (CAR), last 2 are powered.
2. Wheels transform → children matched to colliders by distance.
3. Steering tire indices from steeringTireIndices are matched to models for isModelSteered.

RPM and Gear System

When ForwardGearRatios is specified, the vehicle uses simulated engine RPM with gear shifting:

Field	Type	Description
reverseGearRatio	float	Reverse gear multiplier (default 1.0)
forwardGearRatios	float[]	Per-gear ratios
UsesEngineRpmAndGears	bool	True if gear ratios array is non-empty
AllowsEngineRpmAndGearsInHud	bool	Show RPM/gear HUD (default true)

RPM Parameters

Field	Default	Description
EngineIdleRpm	1000	Minimum RPM at idle
EngineMaxRpm	7000	Redline RPM
EngineRpmIncreaseRate	-1 (instant)	RPM increase rate
EngineRpmDecreaseRate	-1 (instant)	RPM decrease rate
EngineMaxTorque	1.0	Torque curve multiplier

Gear Shifting

Field	Default	Description
GearShiftDownThresholdRpm	1500	RPM threshold to downshift
GearShiftUpThresholdRpm	5500	RPM threshold to upshift
GearShiftDuration	0.5s	Throttle disengagement during shift
GearShiftInterval	1.0s	Min time between gear changes
GearShiftAllowSkippingGears	true	Allow gear skipping

RPM Mismatch Handling

Field	Description
EngineRpmMismatchTorqueReductionEnabled	Reduces torque when RPM mismatches wheel speed
EngineRpmMismatchTorqueReductionThreshold	RPM difference threshold
EngineRpmMismatchGearShiftPreventShifting	Blocks gear shifts during mismatch

Required prefab component: EngineCurvesComponent for the torque curve (validated at asset load).

Fuel System

Field	Type	Default	Description
_fuelMin / _fuelMax	ushort	—	Fuel spawn range
_fuel	ushort	—	Full fuel capacity
fuelBurnRate	float	2.05 (CAR) / 4.2 (other)	Fuel consumed per second

Battery System

Field	Type	Default	Description
canSpawnWithBattery	bool	true	Vehicle spawns with battery
batterySpawnChargeMultiplier	float	1.0	Starting charge level
batteryBurnRate	float	20	Drain per second (Burn mode)
batteryChargeRate	float	20	Charge per second (Charge mode)
batteryDriving	EBatteryMode	Charge	Mode while driving
batteryEmpty	EBatteryMode	None	Mode when depleted
batteryHeadlights	EBatteryMode	Burn	Mode with headlights
batterySirens	EBatteryMode	Burn	Mode with sirens

public enum EBatteryMode { None, Burn, Charge }

Health and Damage

Vulnerability Flags

Field	Description
isVulnerable	Takes non-explosive damage
isVulnerableToExplosions	Takes explosive damage
isVulnerableToEnvironment	Takes environmental damage
isVulnerableToBumper	Takes collision self-damage
canTiresBeDamaged	Tires can be shot out
CanDecay	Can decay over time (false for TRAIN)

Bumper Damage

When the vehicle collides with an entity:

Field	Type	Default	Description
_bumperMultiplier	float	1.0	Speed→damage multiplier
BumperSpeedDamageThreshold	float	3	Minimum speed for damage
BumperPlayerDamage	float	10	Player damage at 1 m/s
BumperZombieDamage	float	15	Zombie damage at 1 m/s
BumperAnimalDamage	float	15	Animal damage at 1 m/s
BumperObjectDamage	float	30	Object damage at 1 m/s
BumperResourceDamage	float	85	Resource damage at 1 m/s
BumperSelfDamageMultiplier	float	1	Self-damage multiplier

Explosion

Field	Type	Description
ExplosionEffectGuid / _explosion	Guid + ushort	Explosion effect
ShouldExplosionCauseDamage	bool	Damage nearby entities
ShouldExplosionBurnMaterials	bool	Burn paintable sections
minExplosionForce / maxExplosionForce	Vector3	Physics impulse range
passengerExplosionArmor	float	Passenger damage reduction (default 1.0)
childExplosionArmorMultiplier	float	Passenger armor multiplier (default 0.2)

Passenger and Turret System

Seats

Seats are discovered automatically from the Seats transform hierarchy. The seat count is calculated by counting Seat_N children of the Seats transform.

Turrets

public class TurretInfo
{
    public byte seatIndex;     // Which seat controls this turret
    public ushort itemID;      // The gun item ID for the turret weapon
    public float yawMin/Max;   // Horizontal rotation limits
    public float pitchMin/Max; // Vertical rotation limits
    public bool useAimCamera;  // Whether aiming zooms
}

Defined via indexed .dat keys:

• Turret_N_Seat_Index — Which seat controls turret N.
• Turret_N_Item_ID — The weapon item.
• Turret_N_Yaw_Min/Max — Yaw rotation limits.
• Turret_N_Pitch_Min/Max — Pitch rotation limits.
• Turret_N_Ignore_Aim_Camera — Disable aim camera.

Cargo / Trunk

Field	Type	Description
trunkStorage_X / trunkStorage_Y	byte	Trunk inventory grid size
dropsTableId	ushort	Spawn table for death drops
dropsMin / dropsMax	byte	Drop count range
tireID	ushort	Compatible tire item ID (default 1451)

Camera

Field	Type	Default	Description
_camFollowDistance	float	5.5	Third-person camera distance
camDriverOffset	float	0	Driver vertical offset
camPassengerOffset	float	0	Passenger vertical offset

Network Validation

Field	Description
_sqrDelta	Max horizontal movement per tick
validSpeedUp	Max upward speed
validSpeedDown	Max downward speed
ValidHitDistanceMultiplier	Hit position distance threshold
_exit	Exit distance from vehicle (default 2)

Buildable Placement

public enum EVehicleBuildablePlacementRule { None, AlwaysAllow, Block }

Controls barricade placement on the vehicle: follow barricade rules, always allow, or always block.

Paint System

Field	Description
PaintableVehicleSections	Sections that can be repainted
SupportsPaintColor	True if sections exist
IsPaintable	Players can apply paint items
DefaultPaintColors	Random color pool
defaultPaintColorMode	List or RandomHueOrGrayscale
randomPaintColorConfiguration	HSV ranges for random colors

Mechanical Fields

Field	Description
staminaBoost	Stamina recovery bonus
isStaminaPowered	Bicycle (powered by player stamina)
isBatteryPowered	Requires battery
isReclined	Sporty car seating
hasTraction	Enhanced traction control
hasSleds	Snowmobile skis
hasZip	Zip line targeting
hasBicycle	Bicycle pedaling
canBeLocked	Lockable to group (default true)
canStealBattery	Battery removable by others (default true)
carjackForceMultiplier	Flip force (default 1.0)
hasCenterOfMassOverride	Custom center of mass
centerOfMass	Center of mass position

Trains

Field	Description
trainTrackOffset	Track alignment offset
trainWheelOffset	Wheel visual offset
trainCarLength	Car length for coupling

Wheel Balancing (Motorcycles)

Field	Default	Description
wheelBalancingForceMultiplier	-1 (disabled)	Roll torque for stability
wheelBalancingUprightExponent	1.5	Upright alignment curve
rollAngularVelocityDamping	-1 (disabled)	Roll damping

Engine Sound

Legacy Sound

Uses _pitchIdle and _pitchDrive computed from AudioSource clip name:

• "Engine_Large" → pitchIdle 0.625, pitchDrive 0.025.
• "Engine_Small" → pitchIdle 0.75, pitchDrive 0.075.
• Default → pitchIdle 0.5, pitchDrive 0.05 (0.03 helicopter, 0.1 blimp).

RPM-Based Sound

When engineSoundType = EngineRPMSimple, uses RpmEngineSoundConfiguration with idle/max pitch and volume driven by current RPM.

Cargo Data Export

BuildCargoData writes to the Vehicle table and three child tables:

• Vehicle_TurretInfo — Per-turret seat, item, yaw/pitch limits.
• Vehicle_DefaultPaintColors — Color list.
• Vehicle_VehicleRandomPaintColorConfiguration — HSV configuration.
• Locale_Vehicle — Localized names.

Common Issues

1. Speed_Max multiplied by 1.25 — TargetForwardVelocity is silently scaled for non-train vehicles. A speed of 80 becomes 100.
2. Steer_Max backward compatibility — Steer_Max is multiplied by 0.75. The newer Steering_Angle_Max avoids this.
3. Wheel auto-generation requirements — If no WheelConfigurations is provided, the legacy Tires/Wheels layout must exist. Misnamed transforms produce errors.
4. Battery mode defaults — BatteryMode_Driving charges, BatteryMode_Headlights and BatteryMode_Sirens burn. Misconfiguration can charge while lights are on.
5. Default physics profile only for mass-1.0 vehicles — If the prefab has non-default mass, the profile is not auto-assigned.
6. Shared skin lookup GUID — When not set, _sharedSkinLookupGuid defaults to the asset GUID, requiring vehicle-specific skins.