<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 `&lt;base_folder&gt;/scripts/vehicles/` where `&lt;base_folder&gt;` 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). 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!