Vehicle Scripting

Vehicle scripting

Vehicle scripts have a few common elements.

Let's demonstrate with this example hovercar script:

<?xml version="1.0" encoding="utf-8"?>
<script>
	<hover_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.141592653</model_to_y_forwards_rot_2>

		<seat>
			<seat_position>0.45 0.43 -0.2</seat_position>
			<upper_body_rot_angle>0.2</upper_body_rot_angle>
			<upper_leg_rot_angle>1.9</upper_leg_rot_angle>
			<lower_leg_rot_angle>-0.5</lower_leg_rot_angle>
		</seat>

		<seat>
			<seat_position>-0.45 0.43 -0.2</seat_position>
			<upper_body_rot_angle>0.2</upper_body_rot_angle>
			<upper_leg_rot_angle>1.9</upper_leg_rot_angle>
			<lower_leg_rot_angle>-0.5</lower_leg_rot_angle>
		</seat>
	</hover_car>
</script>

First off we have two rotations that allow transforming from the model to world space. This is useful in cases like transforming from GLTF coordinates (y-up) to Substrata coordinates (z-up).

model_to_y_forwards_rot_1: This is an axis-angle rotation, from model coordinates (object space) to world coordinates (y-forwards space). (before overall transformation of hovercar)

The world coordinates have the following convention: the z-axis is up, the x-axis is right, and the y-axis is forwards.

The length of the model_to_y_forwards_rot_1 vector is the angle of rotation in radians, counterclockwise around the vector.

In the example above we rotate around the x axis by 90 degrees, to transform from y-up to z-up.

model_to_y_forwards_rot_2 allows defining a second rotation. In the example above the second rotation rotates around the z-axis by 180 degrees (pi radians).

The overall rotation is given by model_to_y_forwards_rot_2 * model_to_y_forwards_rot_1. This means the model_to_y_forwards_rot_1 rotation is applied first, then model_to_y_forwards_rot_2

Seats

Each vehicle can have one or more seats. The first seat is the driver's seat. Seats are defined with the following XML elements:

seat_position: This is the position in model coordinates where the hip bone of the avatar should be placed. You can get the position by opening the model in Blender, just be aware that the Blender GLTF importer changes the coordinate space from y-up of GLTF to z-up upon import.

upper_body_rot_angle: This is the rotation, in radians, of the upper body, from the default vertical orientation. A positive angle means the avatar will lean back.

upper_leg_rot_angle: This is the rotation, in radians, of the leg around the hip joint, from the default vertical orientation. A positive angle means the upper leg will rotate forwards toward the chest.

lower_leg_rot_angle: This is the rotation, in radians, of the lower leg around the knee joint. A negative angle means the lower leg will rotate backwards toward the heel.

Applying a vehicle script

You can just copy and paste the above example script into the script field of an object, however there are some requirements:

The object will need to be an object you have write permissions for (e.g. that you own). The easiest way to have an object you own is to create it on a parcel you own, or to create it in your personal world.
You will need to set an appropriate mass (in kg) of your object in the object editor - too small and wind resistance will slow the object too much, as thrust force is proportional to object mass.
You will need to check the dynamic checkbox in the object editor to make the object into a simulated physics object that can move.