GroundTraffic kit for X-Plane®

Overview

This kit enables X-Plane scenery designers to add animated ground vehicle traffic to airport scenery packages. It requires X-Plane 10.0 or later.

How it works

This kit supplies a plugin that you can distribute with your scenery package. The plugin reads instructions from a text file that you create (and which you should also distribute with your scenery package) and animates X-Plane scenery objects according to those instructions. The objects to be animated can come from X-Plane's built-in library, from an add-on object library (e.g. OpenSceneryX), or from your scenery package.

Installation

Animation instructions

Use Notepad, TextEdit, or any other text editor to create a plain text file named GroundTraffic.txt in your scenery package folder. Save this blank file with an “ANSI”, “Western” or “UTF-8” encoding. (If using TextEdit, you may have to first choose Format → Make Plain Text to see those choices).

Add one or more “Routes” and/or “Highways” to this file and, optionally, a “Water” statement, “Debug” statement, and/or comments.

Water

The Water statement tells the plugin that some or all of your routes are on water. In practice this causes the plugin to activate sooner as the user approaches the airport (since you can see things at sea from a large distance) and, when “water reflection detail” is set to “medium” or above under X-Plane's Rendering Options, to draw objects with reflections. There is a performance cost to both of these activities, so don't use this statement unless you need to.

The Water statement just consists of the word “water” and should be preceded by a blank line:


water

Debug

The Debug statement tells the plugin to display and label routes; each waypoint is labelled with its sequence number, and each animated object is labelled with its line number from GroundTraffic.txt, its last waypoint and, if waiting, the reason why it is waiting. This is useful for checking that your routes' waypoints are at the locations that you intended and for investigating traffic jams.

The Debug statement just consists of the word “debug” and should be preceded by a blank line:


debug

Comment

Lines starting with “#” are treated as comments and are ignored. For example:

# This is a comment

Route

A Route statement starts a new animation. It should be of the form “route speed offset heading object”, where:

speed
The speed of the animated object, in km/h.
offset
Offset in metres to shift the object forwards before animation.
heading
Rotation in degrees to be applied to the object before animation.
object
The name of the animated object. This can be the name of a library object from X-Plane's built-in library or from an add-on library, the name of an object in your scenery package, or the name of a “Train”. Note that library object and train names are case-sensitive.

For the animation to look correct objects should be modelled such that they are pointing North and are roughly centered at their origin (since the plugin rotates them about their origin).

For example, a route using an object from the scenery package, travelling at 30km/h (~18mph):


route	30	0	0	objects/airport_fuel_truck.obj
...

A route using an object from X-Plane 10's built-in library, travelling at 24km/h (~15mph), to be rotated 180°:


route	24	0	180	lib/airport/Ramp_Equipment/Luggage_Truck.obj
...

A route using an object from the OpenSceneryX library, travelling at 20km/h (~12mph), shifted forwards 2.5m so that it rotates about its center:


route	20	2.5	0	opensceneryx/objects/airport/vehicles/loaders/6.obj
...

The Route statement should be preceded by a blank line and should be followed by a sequence of “waypoints” and “commands”. The Route ends with a blank line.

Waypoint

Animated objects move from one waypoint to the next at the speed specified in the Route statement. When the object passes the last waypoint it proceeds towards the first waypoint, forming a circular route (unless you specify a “reverse” command). Objects will wait at a waypoint if moving on would risk colliding with another object or getting in the way of an aircraft; refer to the guidance below if you plan to have routes that overlap with each other or with aircraft taxi paths.

Waypoints should be of the form “lat lon”. For example:

...
47.4484450 -122.3001950
...

You can use OverlayEditor or WED to map out your route, typing the the waypoint locations into GroundTraffic.txt as you go. You may also want to consider placing a “line” (e.g. one of opensceneryx/lines/airport/zone_outlines/...) in OverlayEditor or WED to record your route; this will make it easier if you want to adjust your route in the future. But remember to remove or hide these lines before publishing your scenery package.

Alternatively, you can use online mapping tools such as this to map out your route.

You can use the Debug statement to visualise your routes in X-Plane.

Pause command

The Pause command instructs the animated object to wait at the preceding waypoint for a while before moving on. Optionally, you can cause the value of a DataRef to change while the animated object is waiting, and change back before it proceeds.

The Pause command should be of the form “pause time set name slope curve duration”, where:

time
Time to wait, in seconds.
set name slope curve duration (optional)
As for the “Set” command.

For example, waiting at a waypoint for 30 minutes:

...
47.4629025 -122.3020905
pause 1800
...

Waiting at a waypoint for one minute while setting the value of the DataRef marginal/groundtraffic/var[0] such that it rises from 0 to 1 over five seconds, stays at 1, then starts going back to 0 five seconds before the object proceeds:

...
47.4380074 -122.3040742
pause 60 set var[0] rise linear 5
...

At command

The At command instructs the animated object to wait at the preceeding waypoint until a particular time of day. It should be of the form “at HH:MM on days”, where:

HH:MM
Times of day at which to proceed with the animation. Up to 24 times can be specified, in local time, and using a 24 hour clock.
on days (optional)
Days on which to proceed with the animation. Specified in English.

For example, an animation that waits until 8am:

...
47.4559849 -122.3028592
at 08:00
...

An animation that waits until 8am or 8pm on a weekday:

...
47.4559849 -122.3028592
at 08:00 20:00 on Mon Tue Wed Thu Fri
...

Backup command

The Backup command instructs the animated object to reverse from the preceding waypoint as far as the next waypoint, and thereafter move forward as normal. If the preceding waypoint also has a Pause command the object points forwards while waiting, and then backs-up after waiting.

The Backup command just consists of the word “backup”.

For example backing-up into a parking spot:

...
47.4348468 -122.3034628
backup
47.4349236 -122.3034600
pause 60
47.4348468 -122.3034628
...

Backing-up after a pause:

...
47.4379349 -122.3040074
47.4380074 -122.3040742
pause 60
backup
47.4379349 -122.3040074
...

For best results the waypoints before and after backing-up should be at the same location, as in the above examples, or at least in a straight line.

Reverse command

Normally, when the animated object passes the last waypoint it proceeds towards the first waypoint, forming a circular route. The Reverse command instead instructs the object to change direction at the last waypoint and re-trace its steps.

The Reverse command just consists of the word “reverse” and must be at the end of the Route. For example:

...
reverse

Note: You can't use the Reverse command in a route that contains Backup commands.

Set command

The Set command causes the value of a DataRef to change when the animated object arrives at the preceding waypoint. It should be of the form “set name slope curve duration”, where:

name
var[0] ... var[9] or the name of a custom DataRef.
slope
rise or fall - whether the value the DataRef rises from 0.0 to 1.0, or falls from 1.0 to 0.0.
curve
linear or sine - whether the value the DataRef changes linearly or like  ∫ over the duration.
duration
The time in seconds that the DataRef takes to change value. This can be 0 if you want the DataRef to change value instantly.

If you specify a name of the form var[n] then this command controls the “array” DataRef marginal/groundtraffic/var[n], which can be used to drive animations in a 3D modelling application that supports X-Plane animations. Each object will see values for this DataRef that are specific to the route that the object is following; so it is safe to re-use this DataRef across different objects and routes. For example, within one GroundTraffic.txt file, you could use marginal/groundtraffic/var[0] to control an animated belt in one or more beltloader objects, and also use marginal/groundtraffic/var[0] to control a refueling animation in one or more fuel truck objects. However, because the values returned for this DataRef are specific to a route, you can't usefully use it in a static object that is placed conventionally within an X-Plane scenery package.

Alternatively you can specify the name of a custom DataRef of your choice, but which should be unique to this scenery package. This DataRef can be used to animate objects that are used in a route and/or static objects that are placed conventionally within an X-Plane scenery package. Because all objects (either static or animated by this plugin) will see the same value for your custom DataRef it doesn't make sense to set the same custom DataRef in more than one route.

For example, setting the value of the DataRef marginal/groundtraffic/var[1] such that it rises from 0 to 1 over five seconds on hitting a waypoint:

...
47.4380074 -122.3040742
set var[1] rise linear 5
...

Setting the value of a custom DataRef such that it falls from 1 to 0 over two seconds on hitting a waypoint:

...
47.4348578 -122.3034624
set my/custom/dataref fall sine 2
...

The “Pause ... set” command also supports changing the value of a custom DataRef when the animated object arrives at a waypoint. The “Pause ... set” command restores the DataRef to its previous value before the object moves on from the waypoint; this command does not.

When command

The When command instructs the animated object to wait at the preceeding waypoint until a DataRef is within a specified range. It should be of the form “when name from to”, where:

name
The name of a DataRef published by the sim, the name of a custom DataRef published by the “Set” or “Pause ... set” commands in this plugin, or the name of a custom DataRef published by another plugin. To access an array DataRef, append the array index within square brackets “[n]” to the name.
from to
Range of values for the DataRef for which the animation proceeds.

For example, an animation that only takes place in daylight:

...
47.4559849 -122.3028592
when sim/graphics/scenery/percent_lights_on 0 0.2
...

The When command can be used in conjunction with the Set command to synchronise the motions of objects on different routes. For example, to trigger an object on route B to move when the object on route A reaches a waypoint:

# route A
...
# when we get to this waypoint signal the object on route B
47.4484450 -122.3001950
set my/scenerypackage/signalB rise linear 0
...
# reset the signal for next time around
47.4471804 -122.3023423
set my/scenerypackage/signalB fall linear 0
...

# route B
...
# wait here until object on route A signals to us
47.4559849 -122.3028592
when my/scenerypackage/signalB 1 1
...

And command

The And command can be used to add additional conditions to a When command. It should be of the form “and name from to”, where:

name from to
As for the “When” command.

For example, an animation that only takes place at night and in the rain:

...
47.4559849 -122.3028592
when sim/graphics/scenery/percent_lights_on 0.5 1.0
and  sim/weather/rain_percent 0.1 1.0
...

You can have as many And commands at a waypoint as you like.

Train

Instead of animating a single object along a Route, you can animate a number of objects to follow each other in succession like train cars/coaches follow their locomotive.

A Train statement starts a description of a train of connected objects. It should be of the form “train name”, where:

name
The name of your train. Use this name in a Route statement to animate this train. To avoid any ambiguity don't name your train with the same name as a library object, an object in your scenery package, or another train.

For example a suitable name for a train consisting of a tug and four luggage carts:


train	my/scenerypackage/luggage_train_4
...

The Train statement should be preceded by a blank line and should be followed by a list of the “Car” statements. The Train description ends with a blank line.

Train Car

A train Car statement should be of the form “lag offset heading object”, where:

lag
Distance in metres that the object should lag behind the lead object in the train.
offset
Offset in metres to be applied to the object before animation.
heading
Rotation in degrees to be applied to the object before animation.
object
The name of the animated object. This can be the name of a library object from X-Plane's built-in library or from an add-on library, or the name of an object in your scenery package. It should not be the name of this or of another Train.

To determine how far an object should lag behind the the lead object you can open/import the objects into a 3D modelling application and measure how far (in metres) you have to move the object behind the lead object for it to appear to “link up” correctly. If either object needs an offset to be centered on its axes then adjust for this before measuring. Repeat the process for further objects.

For example a train consisting of two objects, both of which need to be rotated 180°, the second of which is 3.36m behind the first:


train	my/scenerypackage/luggage_train_2
0	0	180	lib/airport/Ramp_Equipment/Luggage_Truck.obj
3.36	0	180	lib/airport/Ramp_Equipment/Luggage_Cart.obj

The plugin animates train Car objects as if they are connected to each other so don't leave huge gaps between Cars. In particular, if you want to send two or more separate objects down the same route don't (ab)use the Train statement; just duplicate the route (and optionally change the order of the waypoints in the copy/copies to space out the objects) or use a Highway.

Highway

Instead of animating a single object or train of objects, you can create a “highway” filled with a constant flow of one-way traffic. Highways are similar to Routes, except that a Highway description cannot contain any commands and traffic on a Highway does not stop to avoid collisions with other Highways or Routes.

A Highway statement starts a description of a traffic flow. It should be of the form “highway speed spacing”, where:

speed
The speed of the animated objects, in km/h.
spacing
Average distance in metres between objects when “number of cars” is at the maximum setting under X-Plane's Rendering Options. Lower settings for “number of cars” will result in a larger distance between objects.

For example a highway with traffic moving at 65km/h (~40mph) and objects every 50 metres:


highway	65	50
...

The Highway statement should be preceded by a blank line and should be followed by a list of highway “Car” statements, followed by a sequence of “waypoints”. The Highway description ends with a blank line.

Highway Car

A highway Car statement should be of the form “offset heading object”, where:

offset
Offset in metres to be applied to the object before animation.
heading
Rotation in degrees to be applied to the object before animation.
object
The name of the animated object. This can be the name of a library object from X-Plane's built-in library or from an add-on library, or the name of an object in your scenery package. It should not be the name of a Train. Note that library object names are case-sensitive.

For example a mix of traffic consisting of some cars, some more cars plus some trucks, and some Ford Transit vans shifted forwards 2.5m so that they rotate about their center:


highway	65	20
0	0	lib/cars/car.obj
0	0	lib/cars/car_or_truck.obj
2.5	0	opensceneryx/objects/vehicles/commercial/vans.obj
...

The plugin fills your highway with a random mix of the objects listed in the Car statements, so the order of the Car statements is not significant.

Highway Waypoint

Animated objects move from one waypoint to the next at the speed specified in the Highway statement. When an object passes the last waypoint it disappears.

Highway Waypoints should be of the form “lat lon”. For example:

...
47.4484450 -122.3001950
...

Animation DataRefs

The plugin publishes the following DataRefs that you can use to create animated objects in a 3D modelling application that supports X-Plane animations:

marginal/groundtraffic/distance
Distance travelled from the first waypoint, in metres. Resets to zero every time the object passes the first waypoint. See below for how to use this to animate rotating wheels.
marginal/groundtraffic/speed
Speed of the object, in metres/second. This returns zero if the object is stationary for any reason, up to the speed that you specified in the Route statement (converted to [m/s]) if it is moving, or negative if it is backing-up (which is useful for displaying reversing lights).
marginal/groundtraffic/steer
Turn rate of the object, in degrees. This returns zero if the object is moving in a straight line, and between zero and half the turn angle if the object is negotiating a turn; e.g. if the object is negotiating a right-angled turn, this will return up to ±45. This is useful for animating articulated vehicles / semi-trailer trucks.
marginal/groundtraffic/var[0] ... var[9]
DataRef whose value is controlled by the “Set” and “Pause ... set” commands.
marginal/groundtraffic/waypoint/last
The last waypoint in the Route (counting from zero) visited by the object.
marginal/groundtraffic/waypoint/last/distance
The distance from the last waypoint, in metres. This returns zero if the object is stationary at a waypoint.
marginal/groundtraffic/waypoint/next
The next waypoint in the Route (counting from zero) to be visited by the object. This is one greater than the last waypoint unless the object is reversing its route or is circling back to the first waypoint.
marginal/groundtraffic/waypoint/next/distance
The distance to the next waypoint, in metres.

These DataRefs return values specific to the route that the object is following; so they are only useful in animating objects on routes controlled by this plugin, not in static objects that are placed conventionally within an X-Plane scenery package. (You can use the “Set” and/or “Pause ... set” commands with a custom DataRef name to publish DataRefs for use in static objects). You can examine the values of these DataRefs using DataRefEditor or Data Ref Tool, but they will only display the values for the first route listed in GroundTraffic.txt.

The objects in a Train or Highway will receive different values for some of these DataRefs (e.g. the value returned by marginal/groundtraffic/distance takes into account the “lag” specified in the object's Train Car statement). But all objects in the train share the same marginal/groundtraffic/var[n] values.

Animating rotating wheels

The speed of rotation of a wheel depends on its size; a smaller wheel needs to rotate more quickly to cover a given distance than a larger wheel. So in a 3D modelling application measure the diameter of the wheel (in metres) and multiple this value by π to obtain the wheel's circumference.

Set up an animation for the wheel containing two keyframes. Rotate the wheel 90° forwards around its axle between the two keyframes. Specify the X-Plane animation values as follows:

For example, for a wheel 1.155m in diameter:

Collision avoidance

Objects will try to avoid crashing into each other by waiting at a waypoint if an object on another route is crossing ahead. So where routes cross don't leave a large distance between the waypoints on either side of the crossing point otherwise an object might have to wait for a long time for the crossing object to clear:

routes cross

Similarly, objects will try to avoid getting in the way of the user's and of AI aircraft. So where a route crosses a taxi or apron path don't leave a large distance between the waypoints on either side of the crossing point.

Where two or more routes share exactly the same waypoint co-ordinates for all or part of their length this is treated as a shared path rather than as a “crossing”; objects will follow each other along the shared path without waiting for other objects to clear:

shared path

Bridges & “Hard” surfaces

The animated objects will always go over “Hard” surfaces in static objects that are placed conventionally within an X-Plane scenery package. At your choice, animated objects can be made to go over or under the bridges that are part of X-Plane's road and rail networks, and over or under “Hard Deck” surfaces in static objects.

Going over X-Plane's bridges:
Place the first waypoint in the route at ground-level. Then add waypoints such that your route follows the path of the bridge. Since objects travel in a straight line between waypoints, if the bridge is curved you will need to add sufficient waypoints to ensure that the object doesn't fall off the bridge between waypoints. Note: If you turn on Debug the waypoints are shown at ground-level, but the object will follow the bridge above unless you let it fall off.
Going over static objects:
In a 3D modelling application mark the faces of your object that represent the road surface as “Hard” if the object represents something solid (e.g. an embankment) or as “Hard Deck” if the object represents something under which traffic can cross (e.g. a bridge, overpass or elevated deck). If using “Hard Deck” note that the maximum gradient that objects will follow is 1:4 or 25%. Once you've placed the static object in your scenery package (e.g. using OverlayEditor or WED) then place your waypoints as for X-Plane's bridges.
Going under X-Plane's bridges:
Animated objects will cross under X-Plane's bridges provided that there is sufficient clearance.
Going under static objects:
Animated objects will ignore static objects (i.e. cross under them or plough right through them) unless the static object contains “Hard” and/or “Hard Deck” surfaces. Objects will cross under “Hard Deck” surfaces provided that there is sufficient clearance.

Animated objects will ignore any “Hard” and “Hard Deck” surfaces in other objects that are animated by this or by another plugin.

Troubleshooting

You can check that the plugin has been loaded and is operating correctly by opening the file Log.txt in the X-Plane folder. You should see:

Fetching plugins for Custom Scenery/my scenery package/plugins
Loaded: Custom Scenery/my scenery package/plugins/GroundTraffic/mac.xpl.

If the plugin is operating correctly it produces no other output in the log. However if the plugin has a problem reading your GroundTraffic.txt file you will see one or more entries starting with “GroundTraffic:” in the log and the plugin will not perform any animation. For example:

GroundTraffic: Empty route at line 15

The plugin examines your GroundTraffic.txt file when you make a selection from the Location → Select Global Airport dialog; if you have edited the file then the plugin will re-read it and re-start the animations. Or you can force the plugin to re-read the file and re-start the animations by disabling and re-enabling it in the Plugin → Plugin Admin → Enable/Disable dialog.

Acknowledgements

“X-Plane” is a registered trademark of Laminar Research.

License

This kit is licensed under the GNU LGPL v2.1 license. In short, you can distribute the plugin provided by this kit in free or commerical scenery packages providing that, in the documentation that accompanies your scenery package, you:

If you modify the plugin provided by this kit you must publish the source code to your changes as specified in sections 2 and 3 of the LGPL v2.1 license.

The author would appreciate a courtesy copy of any commercial scenery that you make using this kit, but you are under no obligation.