Track exporter
Contents |
Track Exporter For Irrlicht Version
The new track exporter uses blender logic properties to specify certain attributes for objects, and ID properties to specify track-wide attributes. The logic properties can be found in the logic panel (F4). The ID properties menu is in the help menu (ID Property Browser).
In this text the name 'property' will be used for logic properties, and ID property for ID properties.
ID Properties for Tracks
| version | Version of the track. This can be used to make sure that the executable can already (or still) use this track. |
| groups, | List of groups to which this track belongs. |
| description | Description of the track, usually used to name the designer. This text 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. |
| ambient-color | Ambient light colour, either a "r g b" or "a r g b" value. |
| 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 "a r g b" color values for the color of the fog. |
| fog-density | Density of the fog. |
| fog-start | Distance at which the fog starts. |
| fog-end | Distance at which the fog ends. |
Main Track and Special Objects: The type Property
The type property is used to mark which objects are 'special', i.e. not part of the main track, and which 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
Itema are created by adding an 'empty' (add->mesh->empty) structure in blender, and giving it a type property value of banana, item, nitro-small, or nitro-big. While the objects will not be displayed in blender, they will be exported correctly for SuperTuxKart.
Water
Note: Due to an irrlicht bug currently a water node will cause a crash. This bug has already been fixed in irrlicht SVN and will work in the next release. But for now do not use this node - just export water nodes as part of the track.
An object with the type property set to water will be exported as a special water node. The node will be animated in SuperTuxKart. Certain additional properties will be added later on allowing you to specify parameters like wave height and length.
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. Full details about the new driveline system are on the separate new drivelines page.
Animations
Objects can be animated using blender's IPO feature. These objects must have the 'type' value set to animation. All IPOs modifying the position (LOC-XYZ) and orientation of the object (ROT-XYZ) will be exporter to SuperTuxKart, and replayed in game. The object can have the additional property name set to the filename to use for the exported animated object (.b3d will be appended to this value). If this is not specified, the blender name is used. Note that the fps value is taken from the blender settings.
Object
If an objects has the type property set to object the object will be exported as a separate b3d model, and loaded at the same location in SuperTuxKart. These objects take a 2nd property: name to specify the file name to use for the exported b3d model (.b3d will be appended to the name).
There are two reasons to export objects separately instead of as part of the main track:
- 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 you should always compare both versions: even if the model is contained several times in a model (and the exported .b3d file might be somewhat larger), irrlicht uses a highly optimised oct-tree to handle the model. If instead several separate objects are used, irrlicht has to handle more scene nodes, and might actually be slower.
- You want to have several version of the track, and certain models will only be used in some versions. Then export all those objects separately, and copy and modify the scene.xml file to include/exclude whatever objects you want/do not want to use.
Physical or Movable Objects
A physical object is an object in the scene that can be affected by the player, i.e. pushed around (or push the kart around). The object will be approximated by a simple shape. Declare these blender objects to have type 'movable'. Additional properties:
- shape The shape of the object, must be 'box', 'cone', or 'sphere'. Default is a box.
- mass The mass of the object. Default is 10 (kg).
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
SuperTuxkart is using 'check structures' for couting laps, and triggering events. 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.
Check structures can be activated or deactivated, which applies to each kart individually (i.e. the same structure can be activated for some karts, and deactivated for others). When an activated structure is triggered (i.e. an activated check line is crossed), the structure becomes deactivated (for the kart that just triggered it). As one effect of triggering a check structure they can activate other check structures. As an example: Each track has to have one check structure used to count laps. But since the lap counting line will be deactivated, the player can not easily cheat by driving little circles crossing the lap line over and over again, since the line is then deactivated. So each track needs at least one more check structure elsewhere, which re-activates the new lap line. So the designer has so find (at least) one place in the track which needs to be crossed by a kart in order to have considered really driving on the track. 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).
- Lap Counting: An object having the type lap is used to trigger that a new lap was started. The object must be a mesh with two vertices. It is automatically deactivated after crossing it, so an activating check structure is needed to be able to finish the next 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 to activate
- toggle containing the (blender) name of the check structure 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 colour if you reach this inner-radius. For example, a sphere of radius 5 with inner-radius 3 will interpolate outside- and inside ambient colour if the kart is between 3 and 5 units away from the center. If it's 3 units or closer, only the new ambient colour will be used.
- color defines the new ambient colour to use.
Sun
One light can be defined for STK in blender (if you have more light, 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 |
|---|---|
| color | A "r g b" or "a r g b" color value for the light of the sun. |
| specular | The specular color of the sun. |
| diffuse | The diffuse color for the sun. |
Summary of Properties
| Property | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| type | ignore | Do not export this object. | ||||||||
| type | banana | Create a banana at this place (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 (not working at this stage due to irrlicht bugs). | ||||||||
| type | maindriveline | Export mesh as main driveline. | ||||||||
| type | driveline | Export mesh as driveline. | ||||||||
| type | animation | An object that is animated using IPOs. | ||||||||
|
||||||||||
| type | object | Export object as separate b3d file. | ||||||||
|
||||||||||
| type | movable | Export object as separate b3d file and make it movable in stk. | ||||||||
|
||||||||||
| ambient-color | a r g b | Specifies the ambient colour to used | ||||||||
| anim-texture | Texture name | Name of the texture to animate. | ||||||||
|
||||||||||
| type | lap | A check line that will trigger a new lap to be counted. | ||||||||
| type | check | A general check structure | ||||||||
|
||||||||||