This document is designed to help users use the Vehicle Editor to create working in-game vehicles and tweak vehicle properties like movement, effects, and ammunition.
Starting from an asset file, users can create working in-game vehicles without coding/scripting intervention.
Many element descriptions can be found in the
Scripts/Entities/Vehicles/def_vehicle.xml file so make sure to have a read through that for further information.
Select any vehicle entity in a level. Open the Vehicle Editor via View -> Open View Pane -> Vehicle Editor. In the Editor click Open Selected.
For starting with a nearly empty vehicle, drag the DefaultVehicle into your level. You'll see it only consists of the a default placeholder object.
In many cases it may be quicker to use an existing vehicle as a start, e.g. use a 4-wheeled vehicle as base for creating another 4-wheeled vehicle.
First use Vehicle -> Save As from the menu bar. The filename you choose determines the entity class name of the new vehicle.
To make the new entity class available, you should now restart the Editor or else you will still be working on the old (existing) vehicle class.
The Movement panel offers a box for choosing the movement type. Each type has its specific set of properties. Tool tips give a short explanation of each property.
Click Save after editing, switch to game mode and test-drive your vehicle.
Some movement types won't work immediately, like the types "StdWheeled" and "Tank", that need wheels added first (see Editing Structure).
The Structure Panel shows a tree view of the vehicle's structure. The root is the vehicle itself.
Parts are identified in the tree view by small grey boxes. You can add parts to the vehicle or to other parts using the context menu. Note that you only need to create parts for things that shall have certain abilities and therefore properties to set up.
A part always moves relative to its parent. So, if you want to create a tank-like vehicle, you would first attach a part for the turret to the vehicle and make it able to rotate left/right using the yawLimits property.
Now add another part, this time to the turret, call it 'cannon', and make it able to rotate up/down using the pitchLimits property.
Each part has a class assigned. Part classes are used to provide special functionality and can have additional properties. Currently used classes are:
Use this for CGAs that include animations.
A child of an Animated part. The name of this part specifies which sub-object inside the Animated CGA it refers to.
A wheel (also as sub-object of an Animated CGA part).
Used for static parts, typically from CGF.
Used for tank treads.
A box-shaped part without rendered geometry for tweaking mass distribution.
Used to specify a geometry for this part. The first stateLevel is the default one and has an empty name. The 'filename'_attribute contains the asset that's loaded for this part. If the part should only use a subgeometry inside this asset file, the optional _'geometry'_attribute can be used to specify it. The main part of the vehicle (chassis/hull..) usually contains the vehicle main asset file here. An optional 2nd stateLevel called _'destroyed' can be used to specify the destroyed model (for this part), which will replace the 1st stateLevel upon vehicle (or part) destruction.
The mass (in kg) of this part. Several vehicles use a single box-shaped part called _'mass'_that specifies the vehicle mass, but you can also assign mass to other parts. Note that for tweaking, a mass-box part is recommended as it can be freely moved and scaled.
Especially for external parts that are not included in the vehicle asset file (e.g. a rocket launcher mounted somewhere), a helper can be specified to position this part.
Disables all collisions for this part, but leaves it physicalized as rigid body. Used e.g. for mass boxes.
Disables physicalization of this part.
For development purposes mainly, can be used to disable rendering of this part.
Rotation speed and limits (in degrees) for this part. To be able to rotate, either yawSpeed or pitchSpeed must be greater than 0. Arcs are displayed when limits are different from zero.
Index of the axle, counted from the vehicles front, starting from 0.
If true, this wheel is affected by the handbrake.
Wheels physical density (water: 1000).
Damping of the suspension.
If true, this wheel is powered.
Maximum (stretched) suspension length.
Initial length of suspension (smaller than lenMax).
Max wheel friction.
Min wheel friction.
Suspension stiffness. If 0, it's calculated from suspension lengths.
If set, surface type of wheel material is overridden with this ID.
For easier setup of common wheel properties, the Wheel Master Dialog is available.
Selecting the desired properties (and the desired wheels) only, allows you to preserve other settings (that may vary between wheels) and that you don't want to overwrite.
As an example, the dialog below is used to update the minFriction and maxFriction of wheels 1 and 2.
Mass boxes can be used to get a symmetrical mass distribution if desired (in contrast to the distribution that's automatically computed according to the mesh otherwise).
This allows easy tweaking of Center of Gravity and Inertia, what's quite fundamental for e.g. wheeled vehicles behavior.
Helpers are small objects specifying a position and a direction in vehicle (or part) coordinate space. In the tree view, they are identified by small boxes with a 'H' in them.
In the main window, they are displayed as small yellow boxes. They are only displayed if the box "Vehicle Helpers" on the Parts Panel is checked.
Helpers are used everywhere where a user-supplied position/direction is needed, e.g. for seat & view positions, weapon positions, effect locations, and more.
You can add Helpers to parts using the context menu. Helpers will always move with the part they are attached to.
The tree view is also used to edit seats. A seat can be added to the vehicle itself or to one of its parts. That's useful for e.g. gunner seats that should move together with a tank turret.
Common Seat properties
Weapons are added to a Seat using the context menu. This seat's passenger will be the operator of the weapon. The class property determines the weapon type and contains a list of mountable vehicle weapons.
The Helpers array determines one or more Helpers for specifying the firing position(s). The firing position rotates through the Helpers list for every consecutive shot, what can be used for weapons like multiple rocket launchers.
You can add Helpers with right-clicking the property item. The helpers you specify here should of course be attached to the corresponding part you want the weapon to move with, e.g. the tank cannon.
Currently primary weapons are supported, secondary will follow. You can have several primary weapons on one seat! The weapons will be fired consecutively (e.g. alternate between left and right rocketlauncher on a Helicopter).
While this effect could also be achieved with using Helpers, several weapons enable the damage system to damage (and take them out) independently.
All further weapon properties are determined by the Weapon entity and the Ammo type. [Upcoming: Ammunition setup for the vehicle].
A damage component is specified by a name, an amount of damage points it can take and an axis-aligned bounding box:
Whenever the vehicle gets hit, the component(s) which bounding box(es) include the hit position receive damage. As damage on a component rises towards its maximum, predefined DamageBehaviors can be triggered (e.g. a particle effect, sound, change in handling, or finally, an explosion).
Examples for usage are:
In order for something to happen when the component receives damage, you have to add DamageBehaviors to the component. Right-click on the DamageBehaviors property item to do this. Currently the following classes of DamageBehaviors are available (wip):
This is intended for creating exhausts, jet turbines, etc. The Helpers array is used to specify one or more helpers, at whose position(s) the effect will be spawned.
Three exhaust effects are supported:
If you have a ParticleEffect entity in your level, you can right-click on the effect items to get the effect name from the entity without typing it manually.
Use Engine start/stop if you want to have a special effect (e.g. a large, dense exhaust cloud) for those events.
The EngineRunning effect usually will be continuous and is spawned as long as the current vehicle status adheres to the limits specified by the EngineRunning parameters.
Use them to alter the appearance depending on current speed and power (ie. engine load). Currently SizeScale and CountScale are exposed for dynamic adjustments, others can be added if needed.
Here you can setup particle effects for usage by the Component Damage System. You can add an effect with right-clicking the "DamageEffects" category. Removing is possible with right-clicking the DamageEffect item to delete.
The name that you can later use in DamageBehaviors to reference this DamageEffect.
The helper where the effect is spawned.
The particle effect. If you have a ParticleEffect entity in your level, you can right-click on the effect item to get the effect name from the entity without typing it manually.
The effect is scaled with increasing damage up to this maximum at 100% damage.