---
name: "SDLx::Sprite::Animated"
section: "3pm"
platform: "linux"
package: "libsdl-perl"
version: "2.548-5+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/SDLx::Sprite::Animated"
---

# SDLx::Sprite::Animated(3pm)

create animated SDL sprites easily!

## NAME

SDLx::Sprite::Animated - create animated SDL sprites easily!

## CATEGORY

Extension

## SYNOPSIS

```
  use SDLx::Sprite::Animated;
  # simplest possible form, where 'hero.png' is an image containing
  # fixed-length sprites in sequence. It doesn't matter if they are
  # placed vertically or horizontally, as long as the the widest
  # side is a multiple of the (narrowest) other. The widget will
  # automatically divide it in the proper frames, provided there is
  # no slack space between each frame.
  my $animation = SDLx::Sprite::Animated->new->load('hero.png');
  # that's it! Defaults are sane enough to DWIM in simple cases,
  # so you just have to call draw() on the right place. If you
  # need to setup your animation or have more control over it,
  # feel free to use the attributes and methods below.
  # these are the most useful methods to use in your game loop
  # (or wherever you want to manipulate the animation):
  $animation->next;
  $animation->previous;
  $animation->reset;
  $animation->current_frame;   # current frame number
  $animation->current_loop;    # current loop number
  # you can control positioning just like a regular SDLx::Sprite:
  $animation->rect
  $animation->x;
  $animation->y;
  # just like a regular Sprite, we fetch our source rect from ->clip,
  # updating it on each call to ->next (or ->previous, or ->reset).
  # If source rects for your animation are further apart (or less)
  # than the rect's width and height, you can adjust the animation
  # x/y offsets:
  $animation->step_x(15);
  $animation->step_y(30);
  $animation->draw($screen); # remember to do this! :)
  # we can also call ->next() automatically after each draw():
  $animation->start;
  $animation->stop;
  # default is to go to the next frame at each draw(). If this is
  # too fast for you, change the attribute below:
  $animation->ticks_per_frame(10);
  # select type of animation loop when it reaches the last frame:
  $animation->type('circular'); # restarts loop at the beginning
  $animation->type('reverse');  # goes backwards
  $animation->max_loops(3); 0 or undef for infinite looping
  # as usual, you can setup most of the above during object spawning
  my $animation = SDLx::Sprite::Animated->new(
                       image  => 'hero.png',
                       rect   => SDL::Rect->new(...),
                       step_x => 20,
                       step_y => 0,
                       ...
                  );
```

## DESCRIPTION

An animation is a series of frames that are played in order. Frames are loaded from an image, usually referred to as a Sprite Sheet or Sprite Strip.

This module let's you interact with such strips and create sprite animations just as easily as you would manipulate a regular SDLx::Sprite object.

## WARNING! VOLATILE CODE AHEAD

This is a new module and the API is subject to change without notice. If you care, please join the discussion on the #sdl IRC channel in *irc.perl.org*. All thoughts on further improving the API are welcome.

You have been warned :)

## ATTRIBUTES AND METHODS

SDLx::Sprite::Animated is a **subclass** of SDLx::Sprite, inheriting all its attributes and methods. Please refer to that module's documentation for information on those.

The one difference in behavior is that, while a standard SDLx::Sprite uses `"->clip()"` to select the part of the surface to display, SDLx::Sprite::Animated treats `"->clip()"` as the **initial** rect, from which to start the animation.

The following attributes and methods are available:

### new

### new( %options )

Creates a new SDLx::Sprite::Animated object. No option is mandatory. It accepts all the options from a regular SDLx::Sprite object plus these:

- •

  step\_x =\> `$integer`

  Uses `$integer` as the number of pixels to move on the x-axis (left-to-right, 0 being no dislocation whatsoever, when the strip goes from top to bottom) to reach the next frame.

- •

  step\_y =\> `$integer`

  Uses `$integer` as the number of pixels to move on the y-axis (top-to-bottom, 0 being no dislocation whatsoever, when the strip goes from left to right) to reach the next frame.

- •

  max\_loops =\> `$integer`

  Uses `$integer` as the number of times to loop the animation (when it reaches the end of the strip).

- •

  ticks\_per\_frame =\> `$integer`

  Uses `$integer` to set how many calls to **draw()** must be issued before we go to the next frame during autoplay (i.e. between calls to **start()** and **stop()**).

- •

  type =\> `$string`

  Uses `$string` to set the type of animation loop when it reaches the last frame in the strip. See the **type()** method below for information on available looping types.

- •

  sequences =\> { `$string` =\> \[ \[ `$x1`, `$y1` \], \[ `$x2`, `$y2` \], ... \], ... }

  Uses the supplied hashref to define named sequences of frames.

- •

  sequence =\> `$string`

  Uses `$string` to set the current sequence.

### step\_x()

### step\_x( $integer )

Uses `$integer` as the number of pixels to move on the x-axis (left-to-right, 0 being no dislocation whatsoever, when the strip goes from top to bottom) to reach the next frame.

Defaults to the same width as the **clip()** rect.

### step\_y()

### step\_y( $integer )

Uses `$integer` as the number of pixels to move on the y-axis (top-to-bottom, 0 being no dislocation whatsoever, when the strip goes from left to right) to reach the next frame.

Defaults to the same height as the **clip()** rect.

### max\_loops()

### max\_loops( $integer )

Uses `$integer` as the number of times to loop the animation (when it reaches the end of the strip). After that **all calls to previous() or next() will be no-ops**.

Set it to `0` or `"undef"` to allow infinite loops. Default is 0 (infinite).

### ticks\_per\_frame()

### ticks\_per\_frame( $integer )

Uses `$integer` to set how many calls to **draw()** must be issued before we go to the next frame during autoplay (i.e. between calls to **start()** and **stop()**).

Default is just 1 tick per frame, so you might want to change this if it's too fast.

### type()

### type( $string )

Uses `$string` to set the type of animation loop when it reaches the last frame in the strip. Available looping types are:

- •

  'circular'

  Restarts loop at the beginning of the strip. If you have 4 frames, the flow will be 1-2-3-4-1-2-3-4-1-2-3-4-1-2-... up until the number of loops you set in the **max\_loops()** attribute.

- •

  'reverse'

  Loops back and forth on the strip. If you have 4 frames, the flow will be 1-2-3-4-3-2-1-2-3-4-3-2-... up until the number of loops you set in the **max\_loops()** attribute.

Case is irrelevant for **type()**, so for example 'Circular', 'CIRCULAR' and 'CiRcUlAr' are all accepted as 'circular'. The return value is guaranteed to be lowercase.

Default value is 'circular'.

### set\_sequences( $string =\> \[ \[ $x1, $y1 \], \[ $x2, $y2 \], ... \], ... )

Uses the supplied hashref to define named sequences of frames. Replaces any previously defined sequences.

### sequence( $string )

Uses `$string` to set the current sequence. Goes to the first frame in the sequence and resets the loop counter.

### next()

Goes to the next frame in the strip. Calling this method will also reset the tick counter used by **ticks\_per\_frame()**.

If **max\_loops()** has reached its limit, this will be a no-op.

Returns the object, allowing method chaining.

### previous()

Goes to the previous frame in the strip. Calling this method will also reset the tick counter used by **ticks\_per\_frame()**.

If **max\_loops()** has reached its limit, this will be a no-op.

Returns the object, allowing method chaining.

### reset()

Goes to the first frame in the strip, meaning whatever clip is set to.

If **max\_loops()** has reached its limit, this will be a no-op.

Returns the object, allowing method chaining.

### current\_frame()

Returns the current frame number. Note that this is 1-based (first frame is 1, second is 2, etc).

### current\_loop()

Returns the loop counter, i.e. which run number is it at. This is also 1-based (first time is 1, second time is 2, etc). Note that we only keep track of the counter if **max\_loops()** is set to a finite number. Otherwise, this will be a no-op.

## start()

After you call this method, the object will issue a call to `"->next()"` automatically for you every time `"->draw()"` is called `ticks_per_frame()` times.

If you want to stop autoplay, see `stop()` below.

Default is off (no autoplay).

## stop()

Stops autoplay. After you call this, the object will need you to call `"->previous()"` and `"->next()"` explicitly to change frames.

To resume autoplay from wherever you are, use `start()`.

If you want to restart autoplay from the initial frame, just do:

```
  $sprite->reset->start;
```

## AUTHORS

See "AUTHORS" in SDL.

## SEE ALSO

SDL::Surface, SDL