Track Maker's Guide
This page describes how to "format" your objects in Blender 2.5 / 2.6, when making a track, so that the STK 0.7 track exporter will recognize and export its properties. There is also a track editor, an easier way to create less professional tracks. You can find its manual here, and a tutorial here.
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 2 to get the proper blender set-up.
It's also a good idea to enable Artist Debug Mode.
Porting an old track
If you have an old track, made in Blender 2.4 for SuperTuxKart <= 0.7.2, see this tutorial to upgrade it to the latest version. Note: 2.49b and later of Blender allow you to edit the files used for 0.6.0. You can use this to your advantage and take 0.6.0s tracks and export for 0.7.3 (and later).
If you wish to work on an existing track, or just see how current tracks are done, check the Media Repository.
Note that making tracks for SuperTuxKart currently requires knowledge of Blender. If you are not at ease in Blender, it is suggested to start by following Blender tutorials.
Modelling the track model itself is covered in the following articles:
- Blender_25_Modeling_Tutorial how to model tracks in blender (using an array modifier).
- Blender_track_modelling_tutorial older tutorial : another way to make tracks in blender (using BevOb - a bit harder to texture the track this way). This tutorial was written for Blender 2.4.
Note that you need to be already somewhat familiar with blender. Tutorials are easily found with a Google search.
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.
For static objects, most combinations of scale and rotation will export file. However please avoid giving a negative scale to objects (this is bad practice anyway).
If you have installed the SuperTuxKart blender plugins as described above, a new panel called SuperTuxKart Scene Properties will appear in the properties window.
Note that in this screenshot, Is a SuperTuxKart track is checked; by default this checkbox is unchecked and many less options are visible. The first thing to do when you make a track is to check this checkbox.
- Groups : List of groups to which this track belongs. The tracks that are shipped by default with STK are in group "standard"; add-ons have group "Add-Ons".
- 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).
- Battle arena : Whether this track is an arena for three-strike battle.
- Sky type : The type of sky : dome, box, plain color or none. None is suitable for indoor tracks like the mines.
- Sky-horizontal : Number of vertices of a horizontal 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.
- Sky color : For plain-color skies only. A color to use as sky; useful for instance in tracks were fog is used to hide some of the too distance track models (e.g. mines).
- fog : Whether to enable fog. Fog has the following properties :
- Fog color : if fog is enabled, the color of the fog.
- Fog start : Distance at which the fog starts (only if fog is enabled).
- Fog end : Distance at which the fog ends (only if fog is enabled).
- 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)
If you installed the SuperTuxKart Blender plugins as described above, a new "SuperTuxKart Properties" panel will appear for each object in the scene, in the properties window.
The most important setting is this panel is the type property, which is used to mark which objects are 'special' (i.e. are not part of the static scenery).
- Banana, Item (gift box), Nitro (big) and Nitro (small). These types must be set on empty blender objects (menu Add > Empty). While the objects will not be displayed in blender, they will be exported correctly for SuperTuxKart. (Empties are displayed in Blender as a black X,Y,Z line object).
- Billboard : this property might be set on a plane mesh to create a billboard (flat quad that always looks at the camera). Apply on a quad object that is either along the X axis or Z axis in blender
- Checkline, driveline : objects used to guide AIs, count laps and prevent shortcuts. See more information on these below
- End camera : you may add end cameras to indicate the viewpoints to look from when a track is over; a "look ahead" camera will be "attached" to the kart, while a "fixed" camera will stay in place and look at the kart
- Ignore : this object 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).
- Object : an object with this type is exported in a separate model file; it can optionally be animated or movable by the player. (See more info below)
- Particle emitter : type to be set on empty; the specified particles will be emitted from this location in the track
- Sound Emitter : a sound will be played at this location. May only be applied to a blender empty object. Has property rolloff which indicates how quickly the sound fades out when you go further away from the emitter, and the volume property which indicates how loud the sound is (between 0 and 1 where 0 is silent and 1 full volume).
- Start position : a start position for 3 strikes battle mode. This type is to be set on empty blender objects (menu Add > Empty). It should have a second property start index indication for which kart position (1 to maximum number of karts) this position is meant.
- Sun : this type can be set on a Blender Sun (menu Add > Lamp > Sun). Contains subproperties that allow tweaking the global lighting (for instance you can make a track darker by using dimmer diffuse and ambient colors). The position of the sun will also be used to determined which parts of the track are in the shadows.
- Water : An object with this will be exported as a special water node. The node will be animated in SuperTuxKart to have "waves". The subproperties "height" (default 2), "speed" (default 300), and "length" (default 10) can be set to customize the waves animation. The time for a point to go from its highest offset to again its highest offset (so a full wave length) is actually 2*PI*speed/1000, so the default value of 300 results in a wave coming every 1.9 seconds. A value of 0 is invalid (and will automatically be reset to the default of 300).
apply scale and rotation to water objects before exporting!
SuperTuxKart supports different end cameras. For a track several cameras can be defined. The cameras will be sorted relative 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.
|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.|
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 texture to animate, and should set the speed of movement by setting Animation X Speed and/or Animation Y Speed. See the following example:
You can add particle emitters anywhere in a track. Simply add an empty, give it the type Particle emitter, and in the particle kind property enter the name of the file describing the particles 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
Level of Detail
Note : In simple cases, when there is a single level of detail (i.e. the object is either visible or non-visible), and the object appears only once (i.e. not appropriate for the trees of a forest), you can select object type LOD Standalone which will make the object disappear after a distance.
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.
Start by creating the various models with different levels of detail, and give them type LOD Model. Place them anywhere in the track, these particular models won't be visible in-game. Then place an object in the track where the LOD object should be instanciated and give it type LOD Instance (you can place any model on the track; it could be a cube, etc. but of course usually it's more helpful to place the actual model).
For instance, here is the example of how to setup a LOD sphere :
The various models that represent various definitions of the same object should all receive the same LOD group name.
Once the 3 levels are defined, you are ready to place instances of the sphere in the track, setting the LOD group name of the object you want to appear there :
The result in-game will be that, at this location :
- The highest resolution sphere will be visible if you are 50 meters or closer from the object
- The medium resolution sphere will be visible if you are between 50 and 100 meters from the object
- The low resolution sphere will be visible if you are between 100 and 200 meters from the object
- If you are further away than 200 meters away from the object, it will not be shown at all
When using LOD, please make sure that the transition between the various levels is a seamless as possible.
SuperTuxKart supports lightmaps from version 0.8. See article lightmaps
SuperTuxKart supports splatting from version 0.8. See article splatting
If you have installed the SuperTuxKart Blender plugins as described above, you will see a new panel called "SuperTuxKart Image Properties"
From there, you can enter the properties of each texture
- Affected by lights : if disabled, this material will be flat and will be unaffected by shadows
- Backface culling : if backface culling is enabled, this material will only be visible from the side the normal is (see )
- Below surface : to be used for the bottom of shallow water where it is OK to drive
- 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
- Clamp texture horizontally/vertically : see  if you don't know what clamping is.
- Disable writing to Z buffer : 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)
- Enable slowdown : slowdown the kart when driving on this material
- 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.
- Falling effect : to be used for materials that pave the bottom of pits, etc. This will make the camera look down at the falling kart instead of trying to follow it
- Graphical Effect : at this time, the only available effect is a water splash; see below for more information on water splash
- High Tires adhesion : when this number is higher, the material will be very grippy on tires so that you can't slip even in curves (useful for inclined curves)
- Ignore (ghost material) : The object with this texture does not interact with the player (karts will go through this material)
- Mask image : if the image mask is found in a separate file instead of being embedded in the texture's alpha mask (or in the case that the texture's format doesn't support alpha channels, like JPEG)
- Particle effect : Adds a particle for graphical smoke effects while driving on this terrain.
- Particle file : the particle.xml file to use
- Play Sound effect : play a sound effect when driving on this material
- Maximal kart speed : speed of the kart at which the sound is at maximal pitch
- Minimal kart speed : speed of the kart at which the sound is at minimal pitch
- Sound pitch at min/max speed : 1.0 is unchanged; 0.5 is half the pitch, 2.0 twice the pitch, etc.
- Reset kart (on drive) : When driving on this texture, the kart will be automatically rescued (this is only appropriate for ground textures).
- Reset kart (on touch) : When touching this texture, the kart will be automatically rescued. The difference with Reset kart (on drive) is that this one can be useful for a wall, for instance.
- Sphere mapping : to enable UV spheric mapping (a reflection-like effect)
- Surface : for water surface (see how to make a water splash below)
- Zipper : When driving on this texture, the kart will get a zipper bonus.
See the materials page to learn about the syntax of the generated materials.xml file (this is not required to make tracks)
A nice water splash
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 and "seabed" materials :
(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)
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
For lap counting to work, you need to create a driveline and at least one checkline as mentioned in the article above
You can export the track by clicking the Export button in the Track Export panel under the Scene tab of the properties.
After the export, the log section under it may contain additional information.