Vehicle Scripts Information

From Garry's Mod
Jump to: navigation, search

Contents

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.

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"
Parameter Unit Description Usage
"wheelsperaxle"
"body" Structure Physical properties of the body
"body" → "countertorquefactor" ratio
"body" → "massCenterOverride" in

x y z

The center of gravity

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.

The unit does not seem similar to kW or bhp. I suggest twice the value in bhp to begin with.

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.
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.

"engine" → "maxspeed" MPH The maximum forward speed under normal conditions

For prop_vehicle_airboat, this scales the forward engine power as well.

See "autobrakeSpeedGain" and "autobrakeSpeedFactor".

"engine" → "maxReverseSpeed" MPH The maximum backward speed under normal conditions

For prop_vehicle_airboat, this scales the backward engine power as well.

NOTE

The vehicle will accelerate slower when this limit is reached.

NOTE

No backward speed limit applies under active boost.

"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}.

The value does not seem to apply in reverse.

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.

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

It is like a "master ratio" affecting all the gears.

"engine" → "gear" ratio Gearbox: gear 0 ratio, aka. 1st gear
NOTE

You can comment out one of the first gears or more if you experience spinning wheels.

"engine" → "gear" ratio Gearbox: gear 1 ratio, aka. 2nd gear
"engine" → "gear" ratio etc.

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.
NOTE

The upshift will only happen if the RPM calculated with the next gear is greater than "shiftdownrpm".

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.

"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

To fully disable the boost feature, simply remove this structure from the vehicle script.

NOTE

For prop_vehicle_airboat, the max speed will be changed but there will be no boost.

Optional
"engine" → "boost" → "force" The amount of boost
"engine" → "boost" → "duration" s The duration of the boost
NOTE

If you just want to change the max speed with no boost, you can set the value to 0.0001

"engine" → "boost" → "delay" s The delay to wait after the end of the last boost
"engine" → "boost" → "torqueboost" Behavior of the boost feature

When 0, the rear wheels will spin in the opposite direction.

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

Between the "slowcarspeed" and the "fastcarspeed" speeds, the steer angle is interpolated.

"steering" → "degreesBoost" degrees Steer angle over the "engine" → "boost" → "maxspeed" speed

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).

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

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.

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

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.

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

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

The structure is identical to that of the front axle.

The "vehicle_sounds" category defines vehicle sounds.

Category "vehicle_sounds"
Parameter Unit Description Usage
"gear" Structure Each gear is specified with a few values
NOTE

If you do not use the engine sound system of Garry's Mod, you can remove them all.

NOTE

The gears used for sounds are totally independent of the gears defined in the "vehicle" category.

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.

The current state depends on the gears and the driver input.

NOTE

If you do not use the engine sound system of Garry's Mod, you can remove them all.

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
NOTE

A few states such as SS_START_IDLE seem to get forced stopped before this duration is elapsed.

NOTE

The value does not take effect on every state.

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

Personal tools
Navigation