Track Maker's Guide
Last update july 8th 2011
This page describes how to "format" your objects in Blender, when making a track, so that the STK 0.7 track exporter will recognize and export its properties.
If you have not already done so, I recommend you read articles Style Guidelines and Licensing (if you are making tracks/karts for your personal enjoyment then you may not need this, but if you wish to submit your contributions for inclusion into SuperTuxKart having read these articles is an definite prerequisite)
Get the tools
See article Installing the tools to get the proper blender setup
Modelling
Modelling the track model itself is covered in the following articles :
- New_Blender_Tutorial how to model tracks in blender (using an array modifier)
- Blender_track_modelling_tutorial another way to make tracks in blender (using BevOb - a bit harder to texture the track this way)
-
Tutoriel de modelisation de piste avec Blender (French Version / Version Française)
-
- How_Steve_Baker_makes_his_tracks (somewhat outdated)
Note that you need to be already somewhat familiar with blender
Texture your models with UV texturing. Your texture images size must be a power of two, e.g. 256x256 or 512x512, in .png or .jpg format (if you use a jpeg texture, give us the original lossless version [e.g. png] along the jpg one so that we have a lossless version)
Blender procedural materials are not supported and most of what you enter in the material buttons window will be ignored. Vertex colors may however be used.
Track-wide properties
Use the STK Browser tools to edit track parameters.
| groups, | List of groups to which this track belongs. The tracks that are shipped by default with STK are in group "standard" |
| designer | Name of the designer(s) of this track. This is displayed in the track selection menu. |
| music | The .music file to use for this track. |
| screenshot | The name of the screenshot pictures to use. The screenshot is displayed in the track selection menu. Note that the screenshot file must be a 4:3 image scaled into a square size (this is because many GPUs require textures with power-of-two sides, and with powers of 2 you can't create 4:3 images) |
| arena | Yes or no. Declares this track to be an arena for three-strike battle. |
| sky-type | One of 'dome', 'box' or 'simple' (plain color). |
| sky-texture (for sky dome and sky box) | For sky domes : the one texture. For sky boxes : or a space-separated list of 6 textures for a box. The order of the texture is the same as in irrlicht, i.e. top, bottom, left, right, front, back. |
| sky-horizontal | Number of vertices of a horizontal layer of the sphere (sky-dome only). |
| sky-vertical | Number of vertices of a vertical layer of the sphere (sky-dome only). |
| sky-texture-percent | How much of the height of the texture is used. Should be between 0 and 1 (sky-dome only). |
| sky-sphere-percent | How much of the sphere is drawn. Value should be between 0 and 2, where 1 is an exact half-sphere and 2 is a full sphere (sky-dome only) - floating point values supported. |
| ambient-color | Ambient light color, either a "r g b" or "r g b a" value. |
| sky-color | A "r g b" value to use as sky, useful in tracks were fog is used to hide some of the too distance track models (e.g. mines). |
| fog | Set to non-zero to enable fog. If fog is enabled, the following properties will be used, too. |
| fog-color | Either "r g b" or "r g b a" color values for the color of the fog. |
| fog-density | Density of the fog. Unused |
| fog-start | Distance at which the fog starts. |
| fog-end | Distance at which the fog ends. |
| camera-far | Far distance for camera - useful for indoor tracks where more objects can be culled this way, without affecting the look. |
| start-karts-per-row | How many karts are being placed in one row. The more karts, the wider the track must be (since each kart in a row will have a distance of start-sidewards-distance). |
| start-forwards-distance | How far a kart is in front of the next kart at start. |
| start-sidewards-distance | How much distance to the right/left of each kart in one row. The three parameters allow you to shape where the karts start: e.g. you could put more karts in a row and reduce the forwards distance to make the field a bit wider (perhaps even reduce sidewards distance if the track should be too narrow, but be aware of wider karts) |
| start-upwards-distance | Sometimes drivelines are too low and will be under the actual mesh. This is a simple vertical offset added to each start positions to make sure that karts start on top of the track (and not under it). Generally the drivelines should be fixed, but this allows a quick solution for existing tracks. |
Per-Object Properties (or how to handle "special" objects)
The new track exporter uses Blender game Logic Properties to specify certain attributes for objects. The logic properties can be found in the game logic panel (F4). In this text the name 'property' will be used for logic properties (i.e. per object properties), and ID property for ID properties (i.e. track-wide properties).
The type property is used to mark which objects are 'special' (i.e. are not part of the main track), and which objects are part of the main track. All objects that do not have the 'type' property defined to a value listed in this section will become part of the main track. All other objects will be exported as special objects or logic properties - e.g. animated objects or the start line of the race. See the following sub-sections for a full list.
Objects to Ignore
If an object has the property 'type' set to ignore, it will not be exported at all. This can be used to keep certain objects as a template in the blender model for further work, without having them exported into the SuperTuxKart track.
Items
Items (collectibles) are created by adding an 'empty' (add->mesh->empty) structure in blender, and giving it a type property value of banana (previously GHERRING or BANA), item (RHERRING or BBOX), nitro-small (SHERRING or COIN), or nitro-big (YHERRING or GOLD). While the objects will not be displayed in blender, they will be exported correctly for SuperTuxKart.
Start positions for arenas
For battle arenas : empties with the type property 'start' declare the start position for a kart. It should have a second property 'position' indication for which kart position (1 to maximum number of karts) this position is meant. As a shortcut, the type and position property can be set together as 'type="start1"' etc., with an integer number immediately after start indication the position.
Water
An object with the type property set to water will be exported as a special water node. The node will be animated in SuperTuxKart to have "waves". The three properties "height" (default 2), "speed" (default 300), and "length" (default 10) can be set for water nodes.
Note : apply scale and rotation to water objects before exporting!
A nice water splash
For SuperTuxKart 0.7.1 and up only
It is possible to make it so that a water splash is drawn when a kart hits the water. For this, you will need to model both the surface of the water and a "seabed" (bottom of the water).
Then apply the following settings to the surface material :
(the water splash sound is not mandatory, here the splash sound effect that comes with SuperTuxKart is used; splash.xml is a particle descriptor for water splashes that comes with STK)
and the following settings to the "seabed" material :
(the falling effect options means that the camera will stay in place and look down at the falling kart)
Separate/Animated Objects
If a blender objects has the type property set to object (or special_object) the object will be exported as a separate b3d model, and loaded in SuperTuxKart, a so called track object.
There are three main reasons for creating track objects:
- You want to animate an object - either using IPOs to change the location/orientation of an object, and/or a skeletal animation to change the shape of the object. Skeletal animations will be part of the b3d model that is exported, IPOs modifying the position (LOC-XYZ) and orientation of the object (ROT-XYZ) will be exporter to SuperTuxKart, and replayed in game. So for example if you want to have someone walking, you would need a skeletal animation for moving the limbs, and a matching IPO based animation to change the location and orientation of this object.
- The same objects are used very often in the track (e.g. a tree to create a forest). Make sure that each of those objects has the additional name property defined, and all have the same name (this way only one file is exported). The scene.xml file will then contain several references to this model. Note that at this stage we don't know which the most efficient way of handling a situation like this is - it might actually be faster (in game) to include all the static objects into the main track model (and letting irrlichts octree node take care of the culling). The model will be larger of course, but it might be faster than adding several additional scene nodes.
- You want to have several version of the track, and certain models will only be used in some versions (for example you might want to block of some ways for a beginner's version with additional road blocks, but remove them for the 'advanced' version). In this case list all those objects (e.g. road blocks) separately as objects, and copy and modify the scene.xml file to include/exclude whatever objects you want/do not want to use.
All track objects allow you to specify the file name to use when exporting them separately by setting the name property (.b3d will be appended to the name). If this is not set, the blender internal name will be used for the filename.
Track objects can have different physical properties, which also affects what kind of animations can be used for them. The physical properties are set using the 'interaction' property - it defines how a kart and this object will interact with each other. Default is 'static'.
interaction="none" or interaction="ghost"
There is no interaction between the track object and a kart. The kart can drive straight through the track object, and is not affected at all, neither is the track object. So the object is a kind of ghost. This is useful for 'eye candy' where the karts can't drive (e.g. a plane in the sky, or rotating wings of a wind turbine, or a house outside of the track; to create a secret and well hidden entrance to a different part of the track; for plants that are not supposed to stop a kart, ...). The advantage is that these objects do not increase the work for the physics, since they don't exist for the physics. Those objects can be animated with an IPO and/or a skeletal animation.
interaction="static" with IPO animation
These objects can not be moved by the kart, karts will just 'run into a wall'. The objects can also have a skeletal animation. Example for this kind of object would be animals, trains, ... crossing the track (IPO and perhaps skeletal animated), or eye candy into which the karts can potentially run into. This kind of object must have a shape defined (property shape), which must be one of 'box', 'sphere', 'cone{X,Y,Z}' or 'cylinder{X,Y,Z} (one of X,Y,Z defining the orientation of the cone or cylinder) at the moment. This is the shape bullet uses to simulate the object in the physics. Other (simple) shapes can be added on request, but the important point is that objects in the physics world must be simple, it would be too slow to (e.g.) simulate all triangles of a tree. Instead the shape will be approximated by e.g. a cone.
interaction="static" without IPO animation
Similar to the track objects mentioned above karts will be stopped when they hit this kind of object. No skeletal animations are supported for this objects atm (that might be added if needed). Examples would be road blocks used for different versions of the same track, or trees (if it should be faster not to include them in the main track).
interaction="move"
This interaction indicates that the object can be moved by the kart - it can be pushed around, and might be affected by explosions etc. Examples would be road cones, road blocks (that can be moved aside). These objects must have a shape defined (see static objects with IPO above), and should define the 'mass' property. These objects can also have skeletal animations, but might NOT have an IPO.
Animated Textures
Any objects that are part of the main track (i.e. no other special object listed here except objects of type object, see above) can mark one texture to be animated. The object must define the name of the texture in the property anim-texture, and should set the speed of movement by setting anim-dx and/or anim-dy. See the following example:
Checks and Lap Counting
SuperTuxkart is using 'check structures' for triggering events and counting laps. At the moment two different structures are supported:
- Check lines: A line segment (i.e. with a definite beginning and end, not an infinite line) that is triggered when a kart crosses it.
- Check sphere: A sphere that is triggered when a kart crosses its boundary.
Checklines are generally added near the middle of the track; they should be in a place where they cannot be missed unless by cheating.
Adding a checkline
Note that a default new lap detection is implemented in STK: it is based on detecting when the distance along track wraps around (i.e. goes from a large value to a value close to 0), which indicates that a new lap has started). If you should want to disable this, give the main driveline a 'strict-lapline=y' property, and a checkline called lap is implicitly created at the start of the driveline (no need to create this line yourself, it will be created automatically for you when you export the track). In any case, this new lap detection has the same name lap as an explicit checkline, and therefore needs re-activiation as well.
Check structures can be activated or deactivated (for each player). When an activated structure is triggered (crossed), the structure becomes deactivated (for the kart that just triggered it). As one effect of triggering, a check structure can activate other check structures.
The minimal case is to have one checkline near the center of the track, that activates the lap line (as in the screenshot above) - this prevents the player from cheating by triggering a new lap detection by driving in circles around the start line since the lap won't be counted unless the lapline was first activated by crossing the middle-of-track checkline.
Making the implicit lapline activate the checkline when crossed
You can also define a chain of check lines: check line 1 activates check line 2, which activates check line 3, which activates the new lap line (which re-activates the first check line). So karts have to cross the check lines in the right order in order to get a lap counted. Note that this system is meant to prevent cheating, i.e. bypassing a significant amount of the track, not to prevent shortcuts. If you want to prevent shortcuts, you either have to model the track appropriately (by putting objects, water, bananas, ...to prevent a kart from using the shortcut), or setting the physics parameters (i.e. making the terrain to cause a slow down of the kart so that it's not worth using this shortcut).
Groups
The check structures can be grouped: all check structures of type 'lap' belong to a group 'lap', and all check structures with the same 'name' property will be grouped together, too. This means that e.g. you activate (say) 'lap', all lap counting lines will be activated; and if you cross a lap counting line, all check structures with the group 'lap' will be deactivated etc. One reason why you want to have more than one lap line is if a kart might cross the start line a little bit to the left or right of the actual start line (and you don't want to widen the quads to accommodate this since the quads might be too wide and look odd in the minimap). Preferred solution is to model the track so that it is obvious where a kart is supposed to cross the line, e.g. having some kind of 'gate' or so. But if this is inconvenient just add more lap counting lines to the left and/or right of the first quad line, and stk will take this into account.
Using grouping to extend the implicitly created lapline
Properties Reference
- The implicit lap checkline generated from the driveline is called lap
- Activating: An object of type check is used to (re-)activate another object. It must have a second property, one of:
- activate containing the (blender) name of the check structure group to activate
- toggle containing the (blender) name of the check structure group to toggle (activate to deactivate and back).
- Ambient light changing: If a check structure (usually a sphere) has the property 'ambient' set, the sphere is used to modify the ambient light. Check spheres can be used with toggling-activate structures: Consider a tunnel in which you want to change the ambient light. Any sphere defined in that tunnel is likely to be too large (e.g. if part of the track are close by parallel to the tunnel but outside you would likely be inside of the sphere). To avoid changing the ambient light at the wrong places you can place a trigger line at the beginning and end of the tunnel: when you enter the tunnel the trigger line will activate the sphere (so that the ambient light changes when you are inside of the sphere), and when you exit the tunnel (be it at the other side of the tunnel, or because you drive out backwards), the sphere will be deactivated again. The ambient sphere takes the following additional properties:
- inner-radius The outside (default) ambient light and the ambient light inside of the sphere will be blended. When the kart crosses the outer radius of the sphere (i.e. the radius of the sphere you add in blender) it will start, and it will reach the full new color if you reach this inner-radius. For example, a sphere of radius 5 with inner-radius 3 will interpolate outside- and inside ambient color if the kart is between 3 and 5 units away from the center. If it's 3 units or closer, only the new ambient color will be used.
- color defines the new ambient color to use.
Since the first lap counting line is automatically added from the driveline, you have to give the main driveline an 'activate' property which specifies which activation line to activate.
Debugging Checklines
STK 0.7alpha3 supports a command line parameter --check-debug, which will cause STK to print a message to the terminal when a check structure is triggered etc. This can be useful in solving problems when laps are not counted correctly.
Level of Detail
Level of detail is the ability to show a highly-detailed model when you're close, and a less detailed one when you're far. Set property type to "object", and set property name to (for instance) "MyObject_LOD100". Then you can make another object called "MyObject_LOD500"; the result will be that if you are 100 meters from the object or closer, the object named "MyObject_LOD100" is shown; if you are between 100 and 500 meters, "MyObject_LOD500" is shown; if you are further than 500 meters nothing is shown.
SuperTuxKart 0.7.2
To instanciate a LOD object, simply duplicate any of the objects and rename it "MyObject_LODx" (adapt the "MyObject" part but leave the "_LODx" part textual). Each LODx object will be shown in-game with the X replaced by the appropriate level
SuperTuxKart 0.7.1
If you wish to have many of the same LOD object in the track, simply duplicate the highest resolution model (the smaller level of detail models only need to appear once)
Furthermore, note that the lower-resolution models can be placed anywhere, their blender location will not be considered
Sun
One light can be defined for STK in blender (if you have more lights, just set the 'ignore' type property in the other lights). The light position is exported as sun position for STK. The following additional properties are used:
| Property name | Value |
| ambient | A "r g b" or "r g b a" color for the ambient light of the sun. |
| diffuse | The diffuse color for the sun. |
| specular | The specular color of the sun. |
Materials
In the STK browser (as shown above), select "Textures" :
From there, you can enter the properties of each texture
- compositing
- test : alpha testing (the alpha channel of the texture is used in a black-and-white fashion : areas mostly opaque are drawn fully opaque, and areas mostly transparent are not drawn at all)
- blend : use alpha blending ("normal" use of the alpha channel to create transparent surfaces)
- additive : use additive blending
- light : if disabled, this material will be unaffected by light
- sphere : to enable UV spheric mapping (a reflection-like effect)
- anisotropic : to enable anisotropic filtering for this texture (makes textures crisper when viewed at an angle, ideal for road materials). For more info on anisotropic filtering, see [1]
- backface-culling : if backface culling is enabled, this material will only be visible from the side the normal is (see [2])
- max-speed : Fraction of the maximum speed of the kart a kart can have on this terrain. If the kart is faster, it will be slowed down gradually (see slowdown-time below).
- slowdown-time : How long it takes for a kart to be slowed down to the speed specified in the max-speed property. A small value will feel like abruptly braking, a larger value more like a gradual slow down caused by the terrain. In 0.7 we are using values between 0.5 and 4 seconds.
- ignore : The object with this texture does not interact with the player. Should be used e.g. for things that are drawn on top of the track, since otherwise there will be a slight bump in the track.
- zipper : When driving on this texture, the kart will get a zipper bonus.
- reset : When driving on this texture, the kart will be automatically rescued.
- particle : Adds a particle for graphical smoke effects while driving on this terrain.
- disable-z-write : disable writing this material to the Z Buffer (this is useful for transparent materials in order to avoid a foreground polygon to hide a background one)
- sound effect : play a sound effect when driving on this material
See the materials page to learn about the syntax of the generated materials.xml file (this is not required to make tracks)
Drivelines
All objects having the type 'maindriveline' or 'driveline' will be exported as drivelines. Drivelines are currently used to specify where to drive for the AI, and to draw the minimap which is displayed in the lower left corner of the race GUI.
For more information, see this separate article
End Camera
The current STK trunk supports different end cameras. For a track several cameras can be defined, each one of a different type. The cameras will be sorted according to the main driveline (which is where the karts will drive during end animations) - the camera closest to the beginning of the track first etc. All blender cameras will be used as end cameras, if you want a camera not to be exported, give its 'type' property the value 'ignore'. The following two camera types are currently defined:
- ahead: The camera flies ahead of the kart, facing towards the kart.
- fixed: The camera is on a fixed position on the track and does not move. It will always points towards the kart, and will zoom in/out to make sure the kart has a 'reasonable' size (i.e. is not too small).
Additionally a camera defines a property called 'start', which defines a start-sphere. If a kart comes into the start-sphere of the next end camera, this camera will replace the current camera. Note that for an 'ahead' camera the camera position you use in blender is only used to determine the start-sphere, i.e. when the camera should be activated. Once the camera is activated, it will instantly fly ahead of the kart, independent of the camera position in blender.
If you have a series of fixed cameras it is very common that the start-sphere of one camera overlaps (or covers) the previous camera. Otherwise it is likely that the previous camera will show the back of the kart, which might not be that interesting (though feel free to ignore this recommendation of course).
Other camera types might be added on request - so please let us know if you have a good idea for a different camera type.
| Property | Value |
|---|---|
| type | "ahead", "fixed" or "ignore" depending on the type of camera. "ahead" is default |
| start | the radius of the start sphere around the camera. If a kart enters the sphere the camera is activated. |
Particles
For SuperTuxKart 0.7.1 and up only
You can add particle emitters anywhere in a track. Simply add an empty, give it the type particle-emitter, and add a kind property where you enter the name of the file describing the properties you wish to use.
For a list of currently available particle files, check the data/gfx folder. You should be able to create new particle types by duplicating an existing one and tweaking its properties.
The format for a particle XML file is described at Particles File
Summary of Properties
| Name | Value | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| type | ignore | Do not export this object. | ||||||||
| type | start | Start position for battle mode, from 1 to maximum number of karts (use on empties)
|
||||||||
| type | banana | Create a banana at this location (use for an empty object). | ||||||||
| type | item | Create an item at this place (use for an empty object). | ||||||||
| type | nitro-small | Create a small nitro container at this place (use for an empty object). | ||||||||
| type | nitro-big | Create a big nitro container at this place (use for an empty object). | ||||||||
| type | water | Export as special irrlicht water node. | ||||||||
| Additional properties: |
|
|||||||||
| type | maindriveline | Export mesh as main driveline. | ||||||||
| type | driveline | Export mesh as driveline. | ||||||||
| type | object | Export object as separate b3d file. | ||||||||
| Additional properties: |
|
|||||||||
| ambient | r g b a | Specifies the ambient color of the sun (in a blender light only). | ||||||||
| diffuse | r g b a | Specifies the diffuse color of the sun (in a blender light only). | ||||||||
| specular | r g b a | Specifies the specular color of the sun (in a blender light only). | ||||||||
| anim-texture | Texture name | Name of the texture to animate. | ||||||||
| Additional properties: |
|
|||||||||
| type | lap | A check line that will trigger a new lap to be counted. | ||||||||
| type | check | A general check structure | ||||||||
| Additional properties: |
|
|||||||||
| type | billboard | Create a billboard | ||||||||
| type | particle-emitter | Create a particle emitter. | ||||||||
| Additional properties: |
|
User Tools
- This page
- Other