Trigger Rally Map XML Reference

Fortunately it's very easy to design new maps for Trigger Rally. That's good! This means we can spend more time on optimizing our maps to make them not only interesting and challenging, but beautiful and usable as well.

It is not hard to set up an impossible or a really easy track. It is much harder to design a good looking interesting map which is fun to navigate without it being too frustrating or boring.

Thanks to Jasmine Langridge's great programming, it's not necessary to have specialist technical skills to make desirable new maps.

Many available maps and events are created using this guide.

Please write suggestions for improving this manual on the mailing list or message board.

Start

The easiest way to start with a new map for Trigger Rally is to copy an existing map folder, like greengrounds and adapt its names, values and images. To do this you need to locate the Trigger Rally data folder on your system. Just look for the trigger.config.devs file. You should find it in the needed folder.

Every map has it's own sub folder in the trigger-rally/data/maps folder, containing its images and the .level XML definition file. Usually the folder carries the same name as the .level file, but leaves out the .level extension. For example: maps/hilly/hilly.level.

It is possible to use the same map for different races. To do this, just add a .level-file (with a distinctive name) for each race in your folder. This enables you to re-use the same maps with different weather conditions and checkpoints.

For creating the level design images, please read the track tutorial.

XML settings for maps

The .level file in each map folder contains important configuration settings for this map. You need to understand the meaning of the available attributes for being able to set up your own map properly. In the following overview I describe what I have learned so far:

Overview

  1. level names and comments
  2. terrain basic source files and attributes of the map
  3. foliageband vegetation type, spreading and thickness
  4. weather atmospheric settings like clouds, fog and rain
  5. vehicleoption setting available cars
  6. race scaling value of coordinates and time limit
  7. startposition vehicle positioning and orientation at start
  8. checkpoint setting checkpoints

level

attribute example value possible values description
name Snowy Hills Latin chars Name of the track as it will be displayed in the game menu.
comment Don't worry, be happy! Latin chars This will be shown as text message when starting the race.
author John Doe Latin chars Credit to the map designer. It is displayed after selecting the map.
randomseed 1000 positive integer ?

terrain

attribute example value possible values description
heightmap heightmap.png path Link to an advisable not less than 512 x 512 pixel large greyscale png file for setting the elevation levels of the map. Dark areas are lower than bright ones. This is one of the core sources of every map and should be kept in the map folder. Depending on the scaling of the map the resolution can be increased, but for performance reasons you shouldn't use larger images than necessary. It needs to have the same resolution as the other maps.
colormap colormap.jpg path Link to an advisable not less than 512 x 512 pixel large color image file for setting surface colors of the map. Since it contains the whole map surface in one 512 pixel sized square details will be very blurred. This effect is even worse if you are setting higher values in the horizontalscale attribute. This image is one of the core sources of every map and should be kept in the map folder. Depending on the scaling of the map the resolution can be increased, but for performance reasons you shouldn't use larger images than necessary. It needs to have the same resolution as the other maps.
foliagemap foliagemap.png path Link to an advisable not less than 512 x 512 pixel large greyscale png file for setting the density levels of the vegetation on the map. Bright areas are denser (if you use the foliageband attributes accordingly). This is one of the core sources of every map and should be kept in the map folder. Depending on the scaling of the map the resolution can be increased, but for performance reasons you shouldn't use larger images than necessary. It needs to have the same resolution as the other maps.
hudmap hudmap.jpg path Link to an advisable not less than 512 x 512 pixel large color image file which is used for the HUD map display in the game. Often the colormap.jpg is reused for this purpose. Therefore, it is not vital to design a specific HUD map. It needs to have the same resolution as the other maps.
tilesize 16 power of two Defines the visual range (in tiles) in the game. Valid are powers of two only. Obviously the further you can see, the better the game looks. But since the whole landscape in the visual range gets calculated constantly this value is very performance relevant. Keep it as low as acceptable, since high values will cause slower systems to end up with very low frame rates. Values above 64 have caused display issues on different systems.
horizontalscale 2.2 positive number (decimal points possible) The higher this value is, the more the map will be scaled up. Distances are greater and landscapes are wider in comparison to the car. It is vital, to use the same value as in race/coordscale in order to fit the coordinates to the map. The more you scale the map, the more blurry the colormap projection on the landscape will become.
verticalscale 0.5 positive number (decimal points possible) The higher this value is, the greater the distance between highest and lowest point on the map will become. Use vertical scaling wisely since even practically invisible graduations in the heightmap.png can lead to unpredictable bumps in the road if you use a high vertical scale value!

foliageband one for each vegetation type

attribute example value possible values description
sprite /textures/veg/grass-sprite.png path Link to a png file with transparent parts, used as vegetation sprite. Start the link with a slash in order to define that the path starts from the trigger-rally/data folder. Optionally use a relative link to a specific vegetation image in the map folder itself.
spritecount 1 low positive integer (not zero) Number of images/axes used for each vegetation instance. The more images per instance you use, the better the result will look. But this comes with a high price: You can seriously increase rendering performance by cutting down this value. (Using more than 3 axes rarely makes sense anyway.)
middle 0.7 a positive number under 1 This defines at what brightness-level of the foliagemap a specific vegetation will be displayed. If you set it to a low value the vegetation will grow where the foliagemap is almost completely dark.
range 0.2 a positive number under 1 A low value here sets the vegetation to a very specific brightness level closely around the defined value of the middle definition. High values lead to this vegetation growing almost everywhere on the map.
density 0.05 a positive number (low under 1 recommended) The higher the value is set, the thicker the vegetation will be.

weather

attribute example value possible values description
cloudtexture /textures/sky/blue.jpg path Link to a jpg file, used as tile in the sky. Start the link with a slash in order to define that the path starts from the trigger-rally/data folder. Optionally use a relative link to a specific sky image in the map folder itself.
cloudscrollrate 0.2 positive number (low decimal point recommended) Velocity of the cloud/sky movement animation. Zero is static/no animation. A value under 1 will be fast enough for sure.
fogcolor 0.1, 0.4, 0.2 three positive numbers under one, separated by a comma and a space Red/yellow/blue values to define the color of the fog. Higher values result in brighter colors.
fogdensity 0.01 positive number under one (low decimal point recommended) Density of fog overlapping landscape and plants.
fogdensitysky 0.006 positive number under one (low decimal point recommended) Density of fog overlapping the sky.
rain (optional) 500 positive integer Density of rain. (This tag can be omitted.)

vehicleoption one for each available vehicle

attribute example value possible values description
type /vehicles/focus/focus.vehicle path Link to the vehicle definition file. Start the link with a slash in order to define that the path starts from the trigger-rally/data folder.

race

attribute example value possible values description
coordscale 2.7, -2.7 two numbers, separated by a comma and a space (decimal points possible) This value defines how much the coordinate values will be scaled. Both values need to be the same as in terrain/horizontalscale to ensure that the coordinates fit to the image map. (It's split into two values to enable you to set a negative value for flipping the direction. This could be helpful if you define the coordinates within a program where the point of origin is not the bottom left corner.)
targettime 243 a positive integer Time limit (in seconds) for finishing the map. After reaching this time limit, the race will stop and the player has lost the race.

startposition

attribute example value possible values description
pos 120, 433 two integers, separated by a comma and a space The x and y coordinates of the starting point of the vehicle on the map. The values relate to the 512 x 512 pixel map images. The coordinate origin is the bottom left. (It is possible to set values outside the map. Since in the game the map is tiled, this could lead to confusion. It's no problem to leave the original tile and to continue driving on the next one.)
oridegrees 90 integer between 0 and 359 Angle of vehicle orientation at the starting point. Degrees are counted counter clockwise and zero faces upwards/north.

checkpoint as many as you want

attribute example value possible values description
coords 261, 76 two integers, separated by a comma and a space The x and y coordinates of all checkpoints. The order in this list defines the proper sequence in which they must be reached in the race.