Kart xml

Last update july 8th 2011

This page describes the format of the kart.xml file, which is used in SuperTuxkart to define some kart options.

File Format and Location

The kart.xml file is a simple xml file wich have to exist in each kart's folder. Here is the file of beagle:

<?xml version="1.0"?>
<kart name              = "Beagle"
      version           = "2"
      model-file        = "beagle.b3d"
      icon-file         = "beagle_icon.png"
      minimap-icon-file = "beagle_icon.png"
      shadow-file       = "beagle_shadow.png"
      groups            = "standard"
      type              = "light"
      rgb               = "0.7 0 0" 
      random-wheel-rot  = "true"
      shadow-scale      = "1.0"
      shadow-x-offset      = "0.0"
      shadow-y-offset      = "0.0">
  <sounds engine = "large"/>
  <animations left = "0"
              straight = "20"
              right = "40"
              start-winning = "50"
              start-winning-loop = "60"
              end-winning = "70"
              start-losing = "80"
              start-losing-loop = "90"
              end-losing = "100"/>
    <rear-right position = "0.392944 0.184659 -0.353249"
                 model    = "wheel-rear-right.b3d"       />
    <front-left position = "-0.394121 0.184659 0.435626"
                 model    = "wheel-front-left.b3d"       />
    <rear-left position = "-0.394121 0.184659 -0.353249"
                 model    = "wheel-rear-left.b3d"       />
    <front-right position = "0.392944 0.184659 0.435626"
                 model    = "wheel-front-right.b3d"       />

Note: Actually, you don't have to create this file yourself. The Blender's kart exporter do it for you!


The following attributes can be used.

  • name: The name of the kart which will appear in the menus (example: "Beagle").

File:Kart xml name.png

  • version: The version number of the kart (example: "1").
  • type: The type of kart which will determine to which properties group the kart belongs (light, medium or heavy).
  • model-file: The file name which contain the model of the kart (example: "beagle.b3d").
  • icon-file: The icon file (128x128) used in some menus (example: "beagle_icon.png").

File:Kart xml icon file.png

  • minimap-icon-file: The icon file used in the minimap during races (example: "beagle_icon.png").

File:Kart xml minimap-icon-file.png

  • shadow-file: The shadow image file used under the kart (example: "beagle_shadow.png"). See the Kart shadow tutorial for more informations.
  • groups: The group (tab) in which the kart will appear in the kart selection menu (example: "standard").

File:Kart xml group.png

  • rgb: If the kart don't have a valid "minimap-icon-file", a RGB colored dot will be shown on the minimap (example: "0.7 0 0"). Not really used anymore.
  • random-wheel-rot: This boolean value put the wheels in a random rotation at each race start. This can be useful avoiding to see a repetition in a strong texture of wheels in the same rotation (example: "true").
  • shadow-scale: As the shadow image can be difficult to set correctly for the kart, this value scale it (example: "1.0").

File:Kart xml shadow scale.png

  • shadow-x-offset: Offset the shadow image in the X value. Positive value slide the shadow to the right (example: "0.12").

File:Kart xml shadow xOffset.png

  • shadow-y-offset: Offset the shadow image in the Y value. Positive value slide the shadow to the top of the kart (example: "0.35").

File:Kart xml shadow yOffset.png

  • sounds
    • engine: The kind of engine sound the kart make: "large" or "small" ("small" by default). Note that in the future there wil hopefully be more options to tweak the sound.
  • animations

Here are the frame numbers, in the "model-file", of each animation:

left <-- straight --> right // The animation between directions
// Frame range between "right" and "start-winning" is not used
start-winning -> start-winning-loop -> end-winning // First the "start-winning" animation is played then "start-winning-loop" is played in loop and "end-winning" is finally played.
// It's the same for "losing".

File:Kart xml animation plan.png Note: "-loop" version are not necessary.

  • wheels
    • rear-right, front-left, rear-left, front-right
      • position: The position, in the "model-file" space of each wheels (example: "0.392944 0.184659 -0.353249").
      • model: The model file of the current wheel (example: "wheel-rear-right.b3d").

Tweaking Physics Parameter

Karts can belong to a certain properties group, where we currently have 3 specific types: light, medium or heavy. those can be set in the kart.xml, as seen below. This will load in the kart-specific settings as defined in the data/stk_config.xml file. There you have a <kart-type> tag in the <general-kart-defaults> tag, with in it the <light> tag, and so on. Additional section can be added to the kart.xml files in which kart-specific physics and gameplay parameters can be specified. All sections from the STK config file data/stk_config.xml which are in the <general-kart-defaults> tags can be just copied into the kart.xml file and modified. This way you can make a kart heavier, make it easier to use slip stream etc. A simple example:

<?xml version="1.0"?>
<kart name              = "Mozilla"
      version           = "2"
      model-file        = "mozilla.b3d"
      type              = "light"
      icon-file         = "mozillaicon.png"
      minimap-icon-file = "mozillaicon.png"
      shadow-file       = "mozillashadow.png"
      groups            = "standard"
      rgb               = "0.7 0 0" >
    <mass value="300"/>
    <nitro consumption="2" max-speed-increase="3"/>

This makes the mozilla kart heavier (default 225), and it will use up nitro quicker, and get less benefit from it. The stk_config.xml file is well documented, so feel free to tweak the kart. Note that kart-specific physics are part of the GSoC topics 2014 and will hopefully be integrated in the 0.8.3 release (see Talk:Milestones). If you do any tweaking of the physics parameters before 0.8.3 it might be necessary to redo this work after 0.8.3 (but hopefully it won't be that much work).