Materials xml

This page describes the format of the materials.xml file, which can be used in SuperTuxkart to define special effects for certain textures. The effects might be graphical, or physical (e.g. define a slowdown that applies while you are driving on this kind of textures). Later on other effects might be added, too (e.g. special sound effects, ...)

File Format and Location

The materials.xml file is a simple xml file that contains one entry for each texture. Notice that defaults apply, so unless you want a special effect it is not necessary to create a materials.xml file to include all your textures. The materials.xml file can go into a track- or kart-directory, and it will overwrite the default settings used in stk: for example, usually sand causes a certain slow down. But on the Shifting Sand track the physics settings can be overwritten, so that there is no slowdown on sand in this track only.

<?xml version="1.0"?>
  <material name="bush.png" transparency="y"/>
  <material name="bush2.png" transparency="y" clamp="y"/>
  <material name="wood_planks1_alpha.png">
     <sfx  name="wood" rolloff="0.6"
           volume="1.0" min-speed="9" max-speed="22"
           min-pitch="1.0" max-pitch="1.7" positional="y"/>

This shows a simple example of a materials.xml file with three textures, one of which contains a terrain-specific sound effect to be played when a kart is driving on that terrain. A list of all possible attributes are in the next section.


Note that the 0.7-alpha release is actually using some The following attributes can be used (defaults in bold)

  • clamp=Y/N
    • Clamping (not sure if this works atm)
  • transparency=Y/N
    • Uses alpha testing: if alpha is >127 a pixel is written, otherwise not. See EMT_TRANSPARENT_ALPHA_CHANNEL_REF in irrlicht.
  • alpha=Y/N
    • Uses alpha blending, the final color is blended together from the destination color and the texture color, using the alpha channel value as blend factor. See EMT_TRANSPARENT_ALPHA_CHANNEL in irrlicht.
  • light=Y/N
    • Set to false if the texture should not be affected by lights.
  • sphere=Y/N
    • Enables UV sphere mapping (a reflection-like effect) for this texture.
  • slowdown=1
    • This slowdown factor is multiplied to the engine power. A value of 0.4 is used for the slowdown on sand in the beach track for example. Note that for the first alpha version of 0.7 you have to use 'slowdownTime'.
  • anisotropic="Y"
    • Enable anisotropic filtering for this texture (makes texture crisper when viewed at an angle, ideal for road materials). Default is anisotropic filtering disabled. For more info on anisotropic filtering, see [1]
  • max-speed=1.0
    • 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. Note that for the first alpha version of 0.7 you have to use 'maxSpeed'.
  • ignore=Y/N
    • 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=Y/N
    • When driving on this texture, the kart will get a zipper bonus.
  • reset=Y/N
    • When driving on this texture, the kart will be automatically rescued.
  • graphical-effect="water"/"smoke"
    • Adds a particle for graphical water and smoke effects while driving on this terrain.