Materials xml

Last update july 8th 2011

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, physical (e.g. define a slowdown that applies while you are driving on this kind of textures), or a special sound effect (e.g. a sound to be played while the kart is driving on this particular terrain).

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  filename="wooden_bridge.ogg" 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.


The following attributes can be used (defaults in bold)

  • compositing=none/blend/test/additive
    • How to composite the image with the background. blend uses the alpha channel to determine the opacity of each pixel; test uses the alpha channel but in a bi-polar fashion, i.e. each pixel is either fully transparent or fully opaque, no in-betweens; additive uses additive blending.
  • clamp=Y/N
    • Clamping (not sure if this works atm)
  • 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.
  • 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]
  • backface-culling=Y/N
    • Disable backface culling (which also allows setting two textures for a mesh - front and back).
  • 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 (see slowdown-time below).
  • slowdown-time=1.0
    • 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=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.
  • surface=Y/N'
    • A mesh that is marked as being a surface does not have a physical representation - meaning that karts will just ignore this (drive through), but the graphics will still be shown. But as opposed to 'ignore' STK can detect this kind of terrain, and trigger special graphical effects. An example to use this for is a water surface, where the kart can either drive trough on a surface under the water (so the kart is partly under water), or is rescued (by either not having a surface under the water surface, or a surface with reset property). The surface will in this case be detected (once the wheel of the karts are under this surface), and can trigger special gfx.
  • below-surface=Y/N
    • If a material is marked as being below a surface, a special graphical effect can be triggered at the actual surface. An example would be a pond where karts could drive through. The water is marked as 'surface', and the mesh the kart is driving on has the 'below-surface' property. The water texture can then contain particle effects for water splashes, and those splashes will emerge from the surface (and not from under the surface).
  • falling-effect=Y/N
    • If the camera is driving on (or even falling onto) a terrain with a 'falling-effect', the camera will not move anymore but keep on pointing to the kart, resulting in a nice visual effect of the kart falling quickly. Can also be used for a 'seabed' under a water surface.
  • friction="20000.0" (or any other value)
    • When friction is higher, the material will be less slippery. Note that this only applies to materials with great slopes, as straight materials always have good traction. Default : 1.0
  • 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.
  • disable-z-write=N/Y
    • If set to Y, this material will not be written to the Z buffer when rendered. Only useful with materials with alpha blending, when there are alpha sorting issues
  • sfx
    • While driving on this terrain, a special sound is played. This effect will always be looped. Additional attributes for sound effects:
      • filename
        • The filename for this sound effect. The sound effect will be loaded from the track directory.
      • name
        • A name for the sound effect. This can be used to either avoid loading a track specific sound effect more than once (only specify the filename the first time it is used, then only use name without filename), or to use an STK internal sound effect, see data/sfx/sfx.xml for available names.
      • rolloff=0.1
        • Speed with which the sound decreases when the distance increases.
      • min-speed=0
        • Minimal speed at which the sound effect is played. Nothing is played if the kart is slower than this value (in m/s).
      • max-speed=30
        • Maximum speed when adjusting the pitch, see min- and max-pitch below.
      • min-pitch=1.0
        • The pitch adjustment to be used when the kart is driving at the minimum speed. Must be between 0.5 and 2.0
      • max-pitch=1.0
        • The pitch adjustment to be used when the kart is driving at the maximum speed (as defined above). Must be between 0.5 and 2.0. The pitch adjustment is linearly interpolated for speeds between min- and max-speed; if the kart is driving faster than max-speed, max-pitch is used.
      • positional=Y/N
        • If the sound effect is played where the kart is currently, or from the inital position only.


Normal maps :

<material name="pyramidwall.png" normal-map="pyramidwall.png_normalmap.jpg" />

note that in order for this to work properly, the said material must be used on a mesh that is a SEPARATE object (type = object) and has the tangents property set to true in materials.xml :

<static-object model="Pyramids.b3d" tangents="true" ... />


Use the new compositing property instead

  • 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.
  • additive=Y/N