Revision Difference
Vehicle_Scripts_Information#512153
<cat>Dev</cat>⤶
## Intro ⤶
⤶
The goal of this tutorial is to provide a maximum of information about vehicle scripts, which are an important origin of mistakes.⤶
⤶
Vehicle scripts are **.txt** files that provide working parameters of **prop_vehicle_jeep** (4-wheel vehicles) and **prop_vehicle_airboat** (4-floating-spot vehicles) entities. They are necessary for **prop_vehicle_prisoner_pod** entities (seats) as well but the standard script **prisoner_pod.txt** is usually fine.⤶
⤶
They are located in `<base_folder>/scripts/vehicles/` where `<base_folder>` is the **garrysmod** directory (next to addons) or the root directory of an addon. Default vehicle scripts are [available here](https://github.com/Facepunch/garrysmod/tree/master/garrysmod/scripts/vehicles).⤶
⤶
When editing a vehicle script, please note that once applied on a vehicle, it is loaded and any further modification is ignored. It can be reloaded by changing the map or by running the **vehicle_flushscript** concommand.⤶
⤶
## Known components ⤶
⤶
There are a certain number of components. You should respect the layout of default vehicle scripts when editing the values.⤶
⤶
The "vehicle" category defines the specifications of the body, the engine, the gearbox, the steering, the wheels and the suspensions.⤶
⤶
⤶
⤶
Category "vehicle" |⤶
------------------|⤶
| "wheelsperaxle" | | | |⤶
| "body" | Structure | Physical properties of the body | |⤶
| "body" → "countertorquefactor" | ratio | | |⤶
| "body" → "massCenterOverride" | in<br/>x y z | The center of gravity<br/><br/>It should be set to somewhere under the vehicle to make it stable, in order to overcome the chassis that is replaced with a uniform volumetric weight distribution. The mass of wheels will help with stability too. | |⤶
| "body" → "massoverride" | kg | The mass value, overriding the mass of the 3D model | |⤶
| "body" → "addgravity" | ratio | | |⤶
| "body" → "maxAngularVelocity" | | | |⤶
| "engine" | Structure | Engine and gearbox characteristics | |⤶
| "engine" → "horsepower" | | The base power value of the vehicle.<br/><br/>The unit does not seem similar to kW or bhp. I suggest twice the value in bhp to begin with.<br/><br/>Combined with "maxrpm", it actually defines the constant torque of the engine. | Used only by **prop_vehicle_jeep** |⤶
| "engine" → "maxrpm" | RPM | The RPM of the engine that is used to calculate the constant torque of the engine.<br/><br/><warning>If the engine exceeds this value, the gearbox will give the same torque output as for the gear 0, making an over-rev boost.</warning> | |⤶
| "engine" → "maxspeed" | MPH | The maximum forward speed under normal conditions<br/><br/>For **prop_vehicle_airboat**, this scales the forward engine power as well.<br/><br/>See "autobrakeSpeedGain" and "autobrakeSpeedFactor". | |⤶
| "engine" → "maxReverseSpeed" | MPH | The maximum backward speed under normal conditions<br/><br/>For **prop_vehicle_airboat**, this scales the backward engine power as well.<br/><br/><note>The vehicle will accelerate slower when this limit is reached.</note><br/><br/><note>No backward speed limit applies under active boost.</note> | |⤶
| "engine" → "autobrakeSpeedGain" | ratio | This is the ratio of the max speed value at which the brake is activated in order to reduce the speed. | |⤶
| "engine" → "autobrakeSpeedFactor" | ratio | This defines how much brake will be applied when exceeding {the forward max speed} times {the "autobrakeSpeedGain" ratio}.<br/><br/>The value does not seem to apply in reverse.<br/><br/>I currently do not know if this value applies under boost. | |⤶
| "engine" → "autotransmission" | 0/1 | When 0, the RPM simulation is disabled and the gearbox will always give the torque output of the gear 0.<br/><br/>When 1, the gearbox instantaneously shifts gears automatically, but it upshifts in downhills only if the **+forward** key is pressed. It acts like an automatic sequential gearbox or an automatic dual-clutch transmission without prediction errors. | |⤶
| "engine" → "axleratio" | ratio | Gearbox: final ratio<br/><br/>It is like a "master ratio" affecting all the gears. | |⤶
| "engine" → "gear" | ratio | Gearbox: gear 0 ratio, aka. 1st gear<br/><br/><note>You can comment out one of the first gears or more if you experience spinning wheels.</note> | |⤶
| "engine" → "gear" | ratio | Gearbox: gear 1 ratio, aka. 2nd gear | |⤶
| "engine" → "gear" | ratio | etc.<br/><br/>Add the desired number of gears. There must be at least 1 gear ratio. | |⤶
| "engine" → "shiftuprpm" | RPM | The RPM at which the gearbox decides to shift up.<br/><br/><note>The upshift will only happen if the RPM calculated with the next gear is greater than "shiftdownrpm".</note><br/><br/><note>When the "shiftdownrpm" and the "shiftuprpm" conditions are very close to each other, the gearbox can continuously shift gears for a little while. This is not a problem, but there is a concern if you display the RPM or the gear number, or if you make your own engine sound.</note> | |⤶
| "engine" → "shiftdownrpm" | RPM | The RPM at which the gearbox decides to shift down. | |⤶
| "engine" → "boost" | Structure | Settings of the boost feature, including `torqueboost` (aka. nitrous oxide) and max speed increase<br/><br/>To fully disable the boost feature, simply remove this structure from the vehicle script.<br/><br/><note>For **prop_vehicle_airboat**, the max speed will be changed but there will be no boost.</note> | Optional |⤶
| "engine" → "boost" → "force" | | The amount of boost | |⤶
| "engine" → "boost" → "duration" | s | The duration of the boost<br/><br/><note>If you just want to change the max speed with no boost, you can set the value to **0.0001**</note> | |⤶
| "engine" → "boost" → "delay" | s | The delay to wait after the end of the last boost | |⤶
| "engine" → "boost" → "torqueboost" | | Behavior of the boost feature<br/><br/>When 0, the rear wheels will spin in the opposite direction.<br/><br/>When 1 (or any other value), the behavior is normal. | |⤶
| "engine" → "boost" → "maxspeed" | MPH | The maximum forward speed while the **+speed** key is pressed or the boost is active. | |⤶
| "steering" | Structure | Steering parameters (front wheels only) | |⤶
| "steering" → "degreesSlow" | degrees | Steer angle below the "slowcarspeed" speed | |⤶
| "steering" → "degreesFast" | degrees | Steer angle over the "fastcarspeed" speed and below the "engine" → "maxspeed" speed<br/><br/>Between the "slowcarspeed" and the "fastcarspeed" speeds, the steer angle is interpolated. | |⤶
| "steering" → "degreesBoost" | degrees | Steer angle over the "engine" → "boost" → "maxspeed" speed<br/><br/>Between the "engine" → "maxspeed" and the "engine" → "boost" → "maxspeed" speeds, the steer angle is interpolated. | |⤶
| "steering" → "steeringExponent" | exponent | When 0, the steering speed is constant (easier for network games).<br/><br/>Otherwise the value is an exponent meant to steer faster and faster. | |⤶
| "steering" → "slowcarspeed" | MPH | The speed below which the maximum steer angle is the "degreesSlow" angle | |⤶
| "steering" → "fastcarspeed" | MPH | The speed over which the maximum steer angle is the "degreesFast" angle | |⤶
| "steering" → "slowSteeringRate" | | | |⤶
| "steering" → "fastSteeringRate" | | | |⤶
| "steering" → "steeringRestRateSlow" | | | |⤶
| "steering" → "steeringRestRateFast" | | | |⤶
| "steering" → "turnThrottleReduceSlow" | | | |⤶
| "steering" → "turnThrottleReduceFast" | | | |⤶
| "steering" → "brakeSteeringRateFactor" | | | |⤶
| "steering" → "throttleSteeringRestRateFactor" | | | |⤶
| "steering" → "boostSteeringRestRateFactor" | | | |⤶
| "steering" → "boostSteeringRateFactor" | | | |⤶
| "steering" → "powerSlideAccel" | | | |⤶
| "steering" → "skidallowed" | | | |⤶
| "steering" → "dustcloud" | | | |⤶
| "axle" | Structure | Properties of the front axle | |⤶
| "axle" → "wheel" | Structure | Characteristics of wheels on this axle | |⤶
| "axle" → "wheel" → "radius" | in | The radius of the wheels on this axle | |⤶
| "axle" → "wheel" → "mass" | kg? | The mass of each wheel on this axle | |⤶
| "axle" → "wheel" → "inertia" | | | |⤶
| "axle" → "wheel" → "damping" | | | |⤶
| "axle" → "wheel" → "rotdamping" | | | |⤶
| "axle" → "wheel" → "material" | | | |⤶
| "axle" → "wheel" → "skidmaterial" | | | |⤶
| "axle" → "wheel" → "brakematerial" | | | |⤶
| "axle" → "suspension" | Structure | | |⤶
| "axle" → "suspension" → "springConstant" | | The height of the body over the wheel axle<br/><br/>To adjust this value, you can move your vehicle to a flat horizontal surface and monitor the poseparameter of every wheel, namely **vehicle_wheel_fl_height**, **vehicle_wheel_fr_height**, **vehicle_wheel_rl_height**, **vehicle_wheel_rr_height** (their value should vary between 0 {compressed} and 1 {extended}). | |⤶
| "axle" → "suspension" → "springDamping" | | | |⤶
| "axle" → "suspension" → "stabilizerConstant" | | | |⤶
| "axle" → "suspension" → "springDampingCompression" | | | |⤶
| "axle" → "suspension" → "maxBodyForce" | | Defines how much springs will be squeezed under weight.<br/><br/>This value is scaled with the "body" → "massoverride" mass so it does not need to be adjusted. | |⤶
| "axle" → "torquefactor" | ratio | Center differential: ratio of the total torque to be applied on this axle<br/><br/>The sum of {the value for the front axle} and {the value of the rear axle} should equal 1.0, but this is not a requirement.<br/><br/>Note that the front differential, the read differential and the center differential are all open differentials. | |⤶
| "axle" → "brakefactor" | ratio | Brakeforce distribution: ratio of the total brakeforce to be applied on this axle<br/><br/>The sum of {the value for the front axle} and {the value of the rear axle} should equal 1.0, but this is not a requirement. | |⤶
| "axle" | Structure | Properties of the rear axle<br/><br/>The structure is identical to that of the front axle. | |⤶
⤶
⤶
⤶
The "vehicle_sounds" category defines vehicle sounds.⤶
⤶
⤶
⤶
Category "vehicle_sounds" |⤶
-------------------------|⤶
| "gear" | Structure | Each gear is specified with a few values<br/><br/><note>If you do not use the engine sound system of Garry's Mod, you can remove them all.</note><br/><br/><note>The gears used for sounds are totally independent of the gears defined in the "vehicle" category.</note> | Optional |⤶
| "gear" → "max_speed" | | | |⤶
| "gear" → "speed_approach_factor" | | | |⤶
| "gear" | Structure | etc. | Optional |⤶
| "state" | Structure | Each state has a name and uses a sound, plus optionally a minimum play time.<br/><br/>The current state depends on the gears and the driver input.<br/><br/><note>If you do not use the engine sound system of Garry's Mod, you can remove them all.</note> | Optional |⤶
| "state" → "name" | | The name of the state. | |⤶
| "state" → "sound" | | The name of the sound that should be played during that state. | |⤶
| "state" → "min_time" | s | Minimum duration of the sound state<br/><br/><note>A few states such as `SS_START_IDLE` seem to get forced stopped before this duration is elapsed.</note><br/><br/><note>The value does not take effect on every state.</note> | Optional |⤶
| "state" | Structure | etc. | Optional |⤶
| "crashsound" | Structure | Each crash sound is defined with a few properties. | |⤶
| "crashsound" → "min_speed" | | | |⤶
| "crashsound" → "min_speed_change" | | | |⤶
| "crashsound" → "sound" | | The name of the sound that should be played for that crash event. | |⤶
| "crashsound" → "gear_limit" | | | Optional |⤶
| "crashsound" | Structure | etc. | |⤶
| "skid_lowfriction" | | | |⤶
| "skid_normalfriction" | | | |⤶
| "skid_highfriction" | | | |⤶
⤶
⤶
⤶
You actually can add your own components as the game will ignore them.⤶
⤶
⤶
## Accessing values in Lua ⤶
⤶
⤶
```⤶
local veh = ents.FindByClass( "prop_vehicle_*" )[1]⤶
if IsValid( veh ) and veh:IsVehicle() then⤶
-- Print in console the content of the vehicle script:⤶
local scriptPath⤶
if SERVER then⤶
scriptPath = veh:GetKeyValues().VehicleScript⤶
else⤶
-- This only works if Vehicle:SetVehicleClass() was called (as done by Sandbox spawn menu).⤶
local spawnData = list.Get( "Vehicles" )[veh:GetVehicleClass()]⤶
if spawnData and spawnData.KeyValues then⤶
for key, keyValue in pairs( spawnData.KeyValues ) do⤶
if string.lower( key ) == "vehiclescript" then⤶
scriptPath = keyValue⤶
break⤶
end⤶
end⤶
end⤶
end⤶
if scriptPath ~= nil and string.len( scriptPath ) ~= 0 then⤶
local scriptContent = util.KeyValuesToTablePreserveOrder( file.Read( scriptPath, "GAME" ) ) -- This table should be cached.⤶
print( "----- veh: vehicle script content =" )⤶
PrintTable( scriptContent )⤶
end⤶
⤶
if SERVER then -- server-side only⤶
-- Print in console the loaded content of the vehicle script:⤶
print( "----- veh:GetVehicleParams() =" )⤶
PrintTable( veh:GetVehicleParams() )⤶
⤶
-- Print in console the current operating values of the vehicle:⤶
print( "----- veh:GetOperatingParams() =" )⤶
PrintTable( veh:GetOperatingParams() ) -- nil for some entity classes (prop_vehicle_prisoner_pod, etc.)⤶
end⤶
end⤶
```⤶
⤶
⤶
Client-side, you can only read the content of the vehicle script, if the client has the file. But unfortunately the path of the vehicle script is not available from the vehicle.⤶
⤶
## Links & Tools ⤶
⤶
* [MR's On-board Diagnostics GUI](https://steamcommunity.com/sharedfiles/filedetails/?id=1858793462)⤶
* [VCMod Handling Editor](https://steamcommunity.com/sharedfiles/filedetails/?id=345123840)⤶
* Feel free to complete the list!⤶
⤶
Garry's Mod
Rust
Steamworks
Wiki Help
S&box