A sprite is an object consisting of a number of properties that define an image which be used by the GUI. Many sprites are defined in <sprite1.xml>.

The sprite system is quite complex, but very powerful once understood. An image can consist of a number of textures, arranged in a collage, and they can be placed and tiled in a quite dynamic way. For example, one could create a dialog box with fixed edges, but a resizeable tile inside.

Take the resizeable button illustrated in the image below, for example:

All the corners have a static size (the size of the border texture), but the length dynamically tiles. The central image also tiles. Here's how we'd define that sprite, assuming that the border's texture is size 20x20:

  <sprites>
      <sprite name="button">
            <!-- Starting with top left corner continuing in a clockwise manner -->
            <image texture="t1.jpg"
                   size="0 0 20 20"
                   texture_size="0 0 20 20" 
            />
            <image texture="t2.jpg" 
                   size="20 0 100%-20 20"
                   texture_size="0 0 20 20" 
            />
            <image texture="t3.jpg"
                   size="100%-20 0 100% 20"
                   texture_size="0 0 20 20" 
            />
            <image texture="t4.jpg"
                   size="100%-20 20 100% 100%-20"
                   texture_size="0 0 20 20" 
            />
            <image texture="t5.jpg"
                   size="100%-20 100%-20 100% 100%"
                   texture_size="0 0 20 20" 
            />
            <image texture="t6.jpg"
                   size="20 100%-20 100%-20 100%"
                   texture_size="0 0 20 20" 
            />
            <image texture="t7.jpg"
                   size="0 100%-20 20 100%"
                   texture_size="0 0 20 20" 
            />
            <image texture="t8.jpg"
                   size="0 20 20 100%-20"
                   texture_size="0 0 20 20" 
            />
            <!-- middle -->
            <image texture="t9.jpg"
                   size="20 20 100%-20 100%-20"
                   texture_size="0 0 100 100" 
            />
      </sprite>
  </sprites>

We just created a sprite with its texture stretched to its every corner with the image stretched to the object's corners. Within the <sprite> and </sprite> you can have as many <image /> as you like, they are each real sprites; they all together form the entire collage.

sprite

Within <sprites></sprites>, you can define as many <sprite></sprite>s as you wish.

name

Each sprite has a unique name. This is referenced by properties such as sprite and sprite_over to tell the control to use this sprite as its image under the appropriate circumstances.

image

The sprite can consist of any number of images, forming a collage. Each image is derived from a single texture.

The image in turn has a number of definable properties:

backcolor

• default: "0 0 0 0"
• value: color

Regular RGB colour stamp including transparency eg backcolor="255 0 255 50" (see GUIColor). If no texture property is specified, the area is filled with this colour.

real_texture_placement

• default: "0 0 0 0"
• value: client area

This is a recent addition to get around the problem of having to very precisely define objects with a percentage size (eg buttons that should adjust to fit the current resolution, and always take up the same amount of space onscreen). This led to definitions like:

  <image texture="ui_pregame_mainmenu_background.png"
         size="0 0 100% 100%" 
         texture-size="0 0 100% 133.333333333%"
  />

To get around this, we have the property real_texture_placement, which specifies the size of the real texture, not the texture file. So the above example becomes:

  <image texture="ui_pregame_mainmenu_background.png"
         real-texture-placement="0 0 1024 768"
         size="0 0 100% 100%" 
  /> 

This feature could also be used to store several textures in a file and specify a certain area of the source texture and cut out that area as the sprite's texture.

Since it just processes the texture coordinates, it doesn't cut out the texture, so you can't tile a cut out texture, because the rest of the image will be shown too.

size

• default: "0 0 100% 100%"
• value: client area

Indicates size and position of the image relative to object size.

For single-textured sprites, it's recommended to leave the size as "0 0 100% 100%", and let the size of the object dictate the size of the sprite.

texture

• default: "null"
• value: name

The name and path of the texture file to use as the source image for this texture. A number of file formats are available, including .jpg, .gif, .png and .dds.

texture_size

• default: "0 0 100% 100%"
• value: client area

Where the texture should be placed within the image; outside this size it will tile. If set to a percentage (eg "0 0 100% 100%"), it will stretch beyond this size instead of tile.

Note that "0 0 100% 100%" is the default, so if you need a sprite that simply stretches to fit its control object, you don't need to specify texture_size.

Skip a step

Single Texture

When using sprites it's very important to know the difference between the sprite name and the texture name. You can't just go sprite="example_texture.jpg" and expect that to work. You have to setup a sprite with that texture first.

Because a 100%-stretched single texture sprite is such a regular occurrence, however, there's a template to skip that step and directly reference the texture. You can do that by using stretched: in the object's sprite property:

  sprite="stretched:example_texture.jpg"

The above is perfectly valid code, the equivalent of:

  <sprite name="single_texture">
          <image texture="texture-from-texture-database"
                 size="0 0 100% 100%"
                 texture_size="0 0 100% 100%" 
          />
  </sprite>

Single Texture, Grayscale

The above can be extended further with the addition of grayscale: after stretched: but before the texture's name. For instance:

  sprite="stretched:grayscale:example_texture.jpg"

Is the equivalent of:

  <sprite name="grayscale_single_texture">
          <effect grayscale=""/>
            
          <image texture="texture-from-texture-database"
                 size="0 0 100% 100%"
                 texture_size="0 0 100% 100%" 
          />
  </sprite>

Block Colour

Under certain circumstances, you might want a sprite to just be a single block colour, such as a unit's health or capture bars. This can most easily be achieved by using color: at the start of an object's sprite property, and following it up with a colour specified using the same syntax as the backcolor sprite syntax above:

  sprite="color: 255 0 0"

The above is perfectly valid and creates an entirely red, opaque block, the equivalent of:

  <sprite name="block_colour">
          <image
              backcolor="255 0 0"
          />
  </sprite>

Scripting Tip: In JS, you can use rgbToGuiColor() (found in common/functions_utility.js) to translate from a {"r":64, "g":64, "b":64} type object to a "64 64 64" string.

effect

Effects are special features that can be added to a sprite when it is first created. For example, the brightness of all images in a sprite can be altered from their base image so they appear lit (to create an illuminated hover version of a button, for example, without having to create a duplicate texture and alter its brightness in Gimp, PhotoShop or any other image editor).

Effects are specified in the <effect/> tag, which must always appear before any <image>s in a <sprite> declaration.

  <!-- Creates a stretched texture that's bled of all colour (grayscale), and brighter than the source image. -->
  <sprite name="new_name_over">
          <effect add_color="42 42 42 0"
                  grayscale="" 
          />
          <image texture="texture-from-texture-database"
                 size="0 0 100% 100%"
                 texture_size="0 0 100% 100%" 
          />
  </sprite>

add_color

The add_color effect adds a specified RGB value to the colour value of the sprite. For example, add-color="42 42 42" increases the overall brightness of the sprite when displayed, particularly useful for buttons that illuminate when the cursor hovers over them.

grayscale

This effect removes all colour from the sprite, replacing colours with shades of gray. This is particularly useful for disabled versions of sprites.