Setting Up Vehicles

Document Summary: This document explains how to create vehicles in a 3D package, import them into the engine and get them working in-game.

Document Changelog: Created by James Golding.

Modeling Vehicles

Vehicles in UnrealEngine 3 use a skeletal mesh to render. This makes it easy to import a mesh with multiple moving parts for wheels, suspension, flaps, doors etc as one asset. Vehicles can take many different forms - but the code does assume they have a single rigid chassis. If your vehicle has wheels, you can use any number you like, and they can be of different sizes. There are a few key things to keep in mind when creating a vehicle mesh for use in UE3:

• The root bone must be weighted to the main rigid chassis of the vehicle.
• The vehicle should point down the +X axis and have +Z as up, and the root `chassis' bone should point down the +X axis and have +Z as up as well. It is a good idea to get the vehicle pointing in the right direction before adding any bones.
• Any other bones for wheels and suspension should be direct children of the chassis bone. Do not make wheel bones children of suspension bones - leave them as children of the chassis.
• Place each tire bone where you want the wheel to rotate (both roll and steering). One axis of the bone should point along the roll axis and another should point along the steering axis (you can tell the engine which axis to use once it has been imported and you are setting up the AnimTree).
• When exporting the vehicle, make sure the wheel bones are moved down to the fullest extension of the suspension.

You export/import vehicle skeletal meshes into the engine in exactly the same way as a regular skeletal mesh.

Create A Physics Asset

Once you have imported your vehicle mesh into the engine, you need to create a Physics Asset for it, to define the collision shape for it. To do this you need to use PhAT (the Physics Asset Tool) - there is information on this tool on the PhysicsAssetTool page.

The only body that is important for a Physics Asset used with a vehicle is the root `chassis' bone. You do not need to create physics bodies for any other bones - you don't need to create joints for wheels for example. Wheel simulation is all handled by the vehicle physics code. Only the chassis body will be created as a physics object, and used for the vehicle collision. PhysicsAssets are used for line check and player collision against the vehicle though, so you may want to create collision shapes for other bones to get more accurate collision - particularly if those bones are going to move (doors, flaps, turrets etc).

The mass and inertia of a vehicle in the game is calculated based on the volume of the chassis collision geometry, and the Density property of the PhysicalMaterial applied to the chassis BodySetup. To modify the mass of a vehicle in the game you can either modify the PhysicalMaterial, or adjust the MassScale property of the chassis BodySetup.

Create An Anim Tree

Although you may not be playing animation on your vehicle, you will still need to create an AnimTree for it to work properly. This is because AnimTrees also contain SkelControls to move individual bones around procedurally in the game. The UE3 vehicle system uses a special type of bone controller to move the wheel bones to match the underlying simulation. You can find more information on wheel SkelControls on the Using Skeletal Controllers page.

Setting Up Wheels

The `WheelDisplacement', `WheelRoll', and `WheelSteering' settings are simply visual so you can see, in the editor, that things are moving the correct direction in the correct axis. They do not actually change the performance or limitations of the vehicle.

The `WheelMaxRenderDisplacement' setting will set the upper limit of translation in the Z axis. This will determine the range of movement for the suspension. So enter values into `WheelDisplacement' to visually determine where you want the upper most limit of travel for the wheel. Then enter that final value into `WheelMaxRenderDisplacement' to set it as a limit. While using the vehicle in game, the wheels will travel up and down between 0 and the number you specify in `WheelMaxRenderDisplacement'. The Roll and Steering axis can be changed and inverted using the remaining settings.

You need to set the ControlName property of the SkelControlWheel. This will be passed to the simulation so it knows which control to update as you drive around.

Setting Up Suspension Bones

As well as having a control to move the wheels as you drive, you may want to add some additional controls to bones that control suspension arms. There is a type of SkelControl called a `look at' controller, which tells the bone to always point one axis towards another object, bone, or point in space. This node is used to control suspension bones.

The blue diamond shape is the aiming target. The `TargetLocationSpace' setting determines what the aim target is relative to: itself, its parent, actor space, world space, or in this case, another bone. Enter the name of the bone you want to aim at in the `TargetSpaceBoneName' setting. The `Target Location' setting will offset the position of the aim target relative to its `Target Location Space' setting. You can also offset the aim by chaining a SkelControlSingleBone node after the LookAt node to offset the rotation of the suspension bone.

You can change or invert the LookAtAxis or UpAxis if it was aligned different in your 3D package. Depending on the complexity of your suspension, you could use the LookAt nodes and SingleBone nodes to create pistons and other connected moving parts.

LookAt nodes can also be used to cancel out rotation on parts connected to the wheel, such as fenders, that need to rotate with the steering and move with the suspension, but should not spin forwards or backwards. To do this, add a bone, parented under the wheel bone, but located in the exact same place. Bind the fender mesh to this bone. Add another bone directly above wheel bone. This will be what the fender will aim at. In the AnimTree, add a LookAt constraint to the fender bone, aiming at the fender-aim bone. In the LookAt node settings, set both the LookAt Axis and Up Axis to Z. The fender bone should now move with the wheel bone during suspension travel, and steering, but will not spin.

For Programmers

Once you have all the assets set up correctly, you need to give some information to a programmer for implementation. The information you will need is:

• The name of the SkeletalMesh.
• The name of the PhysicsAsset.
• The name of the AnimTree.
• The name of each wheel bone.
• The name of each SkelControlWheel.
• The radius of each wheel.

For efficient iteration, it's best to come up with a set of standards for this information.

Creating The Script File

Here is how you would enter all of the needed information into an UnrealScript .uc file for your vehicle:

class MyVehicle extends SVehicle;

defaultproperties
{

   Begin Object Name=SVehicleMesh
      SkeletalMesh=SkeletalMesh'VehiclePackage.VehicleMesh'
      AnimTreeTemplate=AnimTree'VehiclePackage.VehicleAnimTree'
      PhysicsAsset=PhysicsAsset'VehiclePackage.VehiclePhysAsset'
   End Object

   Begin Object Class=SVehicleWheel Name=RRWheel
      BoneName="R_R_Tire"
      SkelControlName="R_R_Tire_Cont"
      WheelRadius=25
   End Object
   Wheels(0)=RRWheel
}

Note: You would have one SVehicleWheel property for each wheel of the vehicle.

Performance: Tuning Vehicles

There are many parameters which control how a vehicle handles. Some are per-wheel parameters which reside in each SVehicleWheel object, whereas those that affect the entire vehicle are in the SVehicle and SVehicleSim objects. An explanation of each parameters is available on the Vehicle Guide page.

Useful Console Commands

One feature of the Unreal Engine which is very useful for tuning vehicles is the editactor console command. While driving the vehicle you can type editactor class=svehicle at the console, and a property window should pop up. This allows you to tune almost all of the parameters as you drive around, making iteration very quick.