Difference between revisions of "Materials xml"

(File Format and Location)
(Added documentation for terrain-specific sfx)
Line 1: Line 1:
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, ...)
+
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 ==
 
== File Format and Location ==
Line 9: Line 9:
 
   <material name="bush2.png" transparency="y" clamp="y"/>
 
   <material name="bush2.png" transparency="y" clamp="y"/>
 
   <material name="wood_planks1_alpha.png">
 
   <material name="wood_planks1_alpha.png">
       <sfx  name="wood" rolloff="0.6"
+
       <sfx  filename="wooden_bridge.ogg" name="wood" rolloff="0.6"
 
             volume="1.0" min-speed="9" max-speed="22"
 
             volume="1.0" min-speed="9" max-speed="22"
 
             min-pitch="1.0" max-pitch="1.7" positional="y"/>
 
             min-pitch="1.0" max-pitch="1.7" positional="y"/>
Line 45: Line 45:
 
*graphical-effect="water"/"smoke"
 
*graphical-effect="water"/"smoke"
 
** Adds a particle for graphical water and smoke effects while driving on this terrain.
 
** Adds a particle for graphical water and smoke effects while driving on this terrain.
 +
*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.

Revision as of 02:59, 29 June 2010

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"?>
<materials>
  <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"/>
  </material>
</materials>

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.

Attributes

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.
  • 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.