Sprite Resources - ClanLib SDK

Sprite Resources

The clan::Sprite resource options are a plethora of possibilities to tweak a sprites looks and behaviours, but all of them have default values. In most cases you will only need to use the basic options.

Only the name attribute of <sprite> and at least one <image> element is required to construct a sprite. The remaining elements and attributes are optional.

## Using the <sprite> element

- Attribute: name
  Resource identifier to use as base for this sprite
  Default value: None, MUST BE PRESENT.
- Attribute: base_angle
  Defines what direction the sprite is in. All other angles are relative to this one.
  Default value: "0"
- Attribute: id
  Sets the sprite identify retrievable via clan::Sprite::get_id().
  Default value: "0"
- Element: <image>
  Description of the sprite frames.
  You can specify any number of <image> elements
- Element: <color>
  Description of the sprite color.
  You can specify any number of <color> elements
- Element: <frame>
  Description of the sprite frames.
  You can specify any number of <frame> elements
- Element: <animation>
  Description of the sprite animation.
  You can specify any number of <animation> elements
- Element: <scale>
  Description of the sprite scale.
  You can specify any number of <scale> elements
- Element: <translation>
  Description of the sprite translation.
  You can specify any number of <translation> elements
- Element: <rotation>
  Description of the sprite rotation.
  You can specify any number of <rotation> elements

## Using the <image> element

The first step in setting up a sprite is telling the resource loader where it should get the images for all the frames. This is done specifying one or more <image> elements. Each <image> element specify an image from where one or several frames should be extracted:

- If there is no child element in <image>, it will simply take the entire image and add it as one large frame.
- If the child element is <grid> it will use the grid cutter to extract a set of frames placed in a grid in the image file.
- If the child is <alpha> the alpha cutter will be used instead. The alpha cutter uses the alpha channel to find frames separated with pure alpha (within trans_limit).
- Attribute: file (Optional)
  Image filename.
- Element: <grid> (Optional - Only when file attribute is set)
  Use the grid cutter to extract a set of frames placed in a grid in the image file
  You can specify any number of <grid> elements
- Element: <alpha> (Optional - Only when file attribute is set)
  The alpha cutter uses the alpha channel to find frames separated with pure alpha
  You can specify any number of <alpha> elements
- Attribute: fileseq (Optional)
  A sequence of images.
  Valid values: "filename.ext" where ext is any of the supported ClanLib image types (for example png, jpg) so that it will be translated into "filename0001.ext"
  Default value: None. For non-sequenced images, use the file attribute.
- Attribute: start_index (Optional - Used when fileseq attribute is set)
  The start index.
  Valid values: "integer" - greater or equal to 0
  Default value: "0"
- Attribute: skip_index (Optional - Used when fileseq attribute is set)
  How many images to skip per iteration. (fileseq)
  Valid values: "integer" - greater or equal to 1
  Default value: "1"
- Attribute: leading_zeroes (Optional - Used when fileseq attribute is set)
  Number of zeroes before the extension.
  Valid values: "integer" - greater or equal to 0
  Default value: "0"

## Using the <grid> element

- Attribute: pos
  Position in image to start grid-cutting.
  Valid values: "integer, integer" - x-position, y-position
  Default value: "0, 0"
- Attribute: size
  Size of each grid-tile.
  Valid values: "integer, integer" - width, height
  Default value: "1, 1"
- Attribute: array
  Grid-size.
  Valid values: "integer, integer" - width, height
  Default value: None, MUST BE PRESENT.
- Attribute: array_skipframes
  How many frames to skip at end of last gridline.
  Valid values: "integer" - frames to skip
  Default value: "0"
- Attribute: spacing
  Space between each grid-tile.
  Valid values: "integer, integer" - x-spacing, y-spacing
  Default value: "0, 0"

## Using the <alpha> element

- Attribute: pos
  Position in image to start alpha-cutting.
  Valid values: (integer,integer)
  Default value: "0, 0"
- Attribute: free
  Use the "Free Alpha Cutter".
  The default alpha cutter finds columns of sprites, all of which have the same height and variable width. The "Free Cutter" identifies all rectangular non alpha blocks of pixels and puts them on a single frame. The algorithms starts at the top left corner (or the specified position) and scans the image line by line, from top to bottom.
  Valid values: blank, true
  Default value: blank

- Attribute: trans_limit
  Transparency limit.
  Valid values: "float" - between 0.0 and 1.0
  Default value: "0.05"

  ## Using the <color> element

  - Attribute: red, green, blue, alpha
    Color. Sets the red, green, blue and alpha color components of the sprite.
    Valid values: "float" - between 0.0 and 1.0
    Default values: 1.0, 1.0, 1.0, 1.0

  ## Using the <animation> element

  - Attribute: speed
    Default frame delay. This sets the delay between each frame. You can override separate frames using frame speed (see below). Value is in milliseconds.
    Valid values: integer
    Default value: 60
  - Attribute: loop
    Loop the animation. Set it to loop if you want the animation to loop after it has reached end of of the animation.
    Valid values: "yes, no" - Enable or disable looping.
    Default value: "yes"
  - Attribute: pingpong
    Pingpong the animation. Set it to pingpong if you want the animation to play back to start once it has reached the end of the animation.
    Valid values: "yes, no" - Enable or disable pingpong.
    Default value: "no"
  - Attribute: direction
    Direction of animation. Set it to backwards if you want the animation to play backwards - starts at last frame, and plays forward to first frame.
    Valid values: "backward, forward" - Play the animation backwards or forwards.
    Default value: "forward"
  - Attribute: on_finish
    What to show when animation is finished. Specify what is shown when the animation is finished. Blank shows nothing, last_frame shows last frame in animation, first_frame shows first frame in animation. If you use looping, this option has no effect.
    Valid values: blank, last_frame, first_frame - one of the 3 options
    Default value: blank

  ## Using the <scale> element

  - Attribute: x and y
    Scale. Sets the x and y scale of the sprite. A value of 1.0 is the normal size, 2.0 is double the size, etc.
    Valid values: (float, float)
    Default value: (1.0, 1.0)

  ## Using the <translation> element

  - Attribute: origin
    Hotspot/alignment for translation operations.
    This is which pixel will go at the location specified with clan::sprite::draw(). So if your sprite has origin=top_left (the default), and you call, say, my_sprite.draw(50, 100), the very top left hand pixel will be placed at (50, 100) and the rest of the sprite drawn around that. If you have origin=center then the centermost pixel will be placed at (50, 100) and the rest of the picture drawn around that.
    Valid values: top_left, top_center, top_right, center_left, center, center_right, bottom_left, bottom_center, bottom_right
    Default value: top_left
  - Attribute: x and y
    This is how far from the origin the picture should be placed. x=50 will draw the picture 50 pixels right of where it would normally go. Note that this does take into account the value of origin.
    Valid values: integer
    Default value: 0

  ## Using the <rotation> element

  - Attribute: origin
    Hotspot/alignment for rotation operations.
    This is the pixel that will stay where it is when you rotate the image. By default this is the center, so any rotations will leave the center pixel where it is and rotate the rest of the image around it. If you want to rotate about the top left corner set this to top_left, etc.
    Valid values: top_left, top_center, top_right, center_left, center, center_right, bottom_left, bottom_center, bottom_right
    Default value: center
  - Attribute: x and y
    This is how far to offset the hotspot from the origin.
    Valid values: integer
    Default value: 0

  ## Using the <frame> element

  - Attribute: nr
    The frame number Valid values: integer
    Default value: 0
  - Attribute: speed
    Override default speed for this specific frame. Value is in milliseconds. Valid values: integer
    Default value: play_speed
  - Attribute: x and y
    Offset to display this frame. This let you set a position-offset on a frame, finetuning its position relative to the other frames.
    Valid values: (integer, integer) - x-position, y-position
    Default value: (0, 0)