Car Scripting

Car scripting

You can use a car script to add a 4-wheeled vehicle to Substrata.

model_to_y_forwards_rot_1: axis-angle 3-vector. See Vehicle scripting for details.

model_to_y_forwards_rot_2: axis-angle 3-vector. See Vehicle scripting for details.

seat: Defines a seat. See Vehicle scripting for details.

front_wheel_radius: radius of the front wheels, in metres.

rear_wheel_radius: radius of the rear wheels, in metres.

front_wheel_width: width of the front wheels (e.g. width of the tire), in metres.

rear_wheel_width: width of the rear wheels (e.g. width of the tire), in metres.

front_suspension_min_length: How long the suspension is in max raised position relative to the attachment point (metres), for front wheels. Default is 0.2.

rear_suspension_min_length: How long the suspension is in max raised position relative to the attachment point (metres), for rear wheels. Default is 0.2.

front_suspension_max_length: How long the suspension is in max droop position relative to the attachment poin (metres), for front wheels. Default is 0.5.

rear_suspension_max_length: How long the suspension is in max droop position relative to the attachment point (metres), for rear wheels. Default is 0.5.

front_wheel_attachment_point_raise_dist: How far up the car body from the modelled wheel position should the suspension attach, in metres.

rear_wheel_attachment_point_raise_dist: How far up the car body from the modelled wheel position should the suspension attach, in metres.

front_suspension_spring_freq: Oscillation frequency of the front wheel suspension springs, in Hertz. A higher value means stiffer suspension. Default is 2.

rear_suspension_spring_freq: Oscillation frequency of the rear wheel suspension springs, in Hertz. A higher value means stiffer suspension. Default is 2.

front_suspension_spring_damping: Damping ration for the front wheel suspension. 0 = no damping, 1 = critical damping. Default is 0.5.

rear_suspension_spring_damping: Damping ration for the rear wheel suspension. 0 = no damping, 1 = critical damping. Default is 0.5.

max_steering_angle: Maximum steering angle for the front wheels, in radians. Default is 0.78525

engine_max_torque: Maximum torque of the engine, in Nm. Default is 500.

engine_max_RPM: Maximum RPM of the engine. Default is 6000.

max_brake_torque: Maximum torque applied by the brake pads to each wheel, in Nm. Default is 1500.

max_handbrake_torque: Maximum torque applied by the handbrake to each rear wheel, in Nm. Default is 4000.

longitudinal_friction_factor: A multiplier for the longitudinal (front-back) friction force between the tire and ground. Default is 1.

lateral_friction_factor: A multiplier for the lateral (sideways) friction force between the tire and ground. Default is 1.

front_left_wheel_joint_name: Name of the front left wheel joint node. A transform is applied to this node to animate the wheel.

front_right_wheel_joint_name: Name of the front right wheel joint node. A transform is applied to this node to animate the wheel.

back_left_wheel_joint_name: Name of the back left wheel joint node. A transform is applied to this node to animate the wheel.

back_right_wheel_joint_name: Name of the back right wheel joint node. A transform is applied to this node to animate the wheel.

front_left_wheel_brake_joint_name: Name of the front left wheel brake joint node. A transform is applied to this node to animate the wheel brake.

front_right_wheel_brake_joint_name: Name of the front right wheel brake joint node. A transform is applied to this node to animate the wheel brake.

back_left_wheel_brake_joint_name: Name of the back left wheel brake joint node. A transform is applied to this node to animate the wheel brake.

back_right_wheel_brake_joint_name: Name of the back right wheel brake joint node. A transform is applied to this node to animate the wheel brake.

convex_hull_points

This XML element has a list of child point XML elements, defining a convex hull that is the geometry of the car body. This geometry is used for collision. You can think of the convex hull as being the result of shrink-wrapping some fabric around the points.

point: A space-separated 3-vector definging a convex hull point.

Example

<?xml version="1.0" encoding="utf-8"?>
<script>
	<car>
		<model_to_y_forwards_rot_1>1.57079632679 0 0</model_to_y_forwards_rot_1>
		<model_to_y_forwards_rot_2>0 0 3.1415926535897932384626433832795</model_to_y_forwards_rot_2>

		<front_wheel_radius>0.42</front_wheel_radius>
		<rear_wheel_radius>0.48</rear_wheel_radius>

		<front_wheel_width>0.16</front_wheel_width>
		<rear_wheel_width>0.16</rear_wheel_width>
		
		<front_suspension_min_length>0.15</front_suspension_min_length>
		<rear_suspension_max_length>0.5</rear_suspension_max_length>

		<front_wheel_attachment_point_raise_dist>0.3</front_wheel_attachment_point_raise_dist>
		<rear_wheel_attachment_point_raise_dist>0.24</rear_wheel_attachment_point_raise_dist>

		<max_steering_angle>0.78</max_steering_angle>

		<!-- +y is up, +z is forward for this model -->

		<convex_hull_points>
			<!-- front top -->
			<point>1.0 0.3 2.7</point>
			<point>-1.0 0.3 2.7</point>

			<!-- front bottom -->
			<point>1.0 -0.2 2.7</point>
			<point>-1.0 -0.2 2.7</point>

			<!-- roof top points -->
			<point>0.8  0.9 -1.2</point>
			<point>-0.8 0.9 -1.2</point>
			<point>0.8 0.9 -0.2</point>
			<point>-0.8 0.9 -0.2</point>

			<!-- rear top -->
			<point>-0.8 1.0 -3.0</point>
			<point>0.8 1.0 -3.0</point>

			<!-- rear bottom bumper -->
			<point>-1.1 0.0 -3.2</point>
			<point>1.1  0.0 -3.2</point>

			<!-- rear side -->
			<point>-1.2 0.2 -2.2</point>
			<point>1.2  0.2 -2.2</point>

			<!-- underside rear -->
			<point>-1.0 -0.45 -1.3</point>
			<point>1.1  -0.45 -1.3</point>

			<!-- underside front -->
			<point>-1.0 -0.43 1.05</point>
			<point>1.1  -0.43 1.05</point>

		</convex_hull_points>

		<seat>
			
			<seat_position>0.5 0.03 -0.15</seat_position>

			<upper_body_rot_angle>0.4</upper_body_rot_angle>

			<upper_leg_rot_angle>1.5</upper_leg_rot_angle>
			<upper_leg_rot_around_thigh_bone_angle>0.27</upper_leg_rot_around_thigh_bone_angle>
			<upper_leg_apart_angle>0.17</upper_leg_apart_angle>

			<lower_leg_rot_angle>0</lower_leg_rot_angle>
			<lower_leg_apart_angle>0.1</lower_leg_apart_angle>
			<rotate_foot_out_angle>0.5</rotate_foot_out_angle>

			<arm_down_angle>1.7</arm_down_angle>
			<arm_out_angle>0.1</arm_out_angle>
		</seat>
	</car>
</script>

Visualising the car physics

You can check the 'Show vehicle physics visualisation' checkbox in the Diagnostics widget in the Substrata native client (Window > Diagnostics). This will show a visualisation of the convex hull of the vehicle, with small red spheres marking the convex hull points, as well as blue cylinders show the physics engine wheel objects.