NAME

Term::Animation - ASCII sprite animation framework

SYNOPSIS

  use Term::Animation;

  # Constructors
  $screen = Term::Animation->new();
  $screen = Term::Animation->new($curses_window);

ABSTRACT

A framework to produce sprite animations using ASCII art.

DESCRIPTION

This module provides a framework to produce sprite animations using ASCII art. Each ASCII 'sprite' is given one or more frames, and placed into the animation as an 'animation object'. An animation object can have a callback routine that controls the position and frame of the object.

If the constructor is passed no arguments, it assumes that it is running full screen, and behaves accordingly. Alternatively, it can accept a curses window (created with the Curses newwin call) as an argument, and will draw into that window.

EXAMPLES

This example moves a small object across the screen from left to right.

    use Term::Animation;
    use Curses;

    halfdelay( 2 );

    $screen = Term::Animation->new();

    # create a simple shape we can move around
    $shape = "<=O=>";

    # turn our shape into an animation object
    $object = $screen->build_object(
                 name          => "UFO",         # object name
                 shape         => $shape,        # object shape
                 position      => [3, 7, 10],    # row / column / depth
                 callback_args => [1, 0, 0, 0],  # the default callback
                                                 # routine takes a list
                                                 # of x,y,z,frame deltas
                 wrap          => 1              # screen wrap
             );

    # add the object to our animation
    $screen->add_object($object);

    # animation loop
    while(1) {
      # run the callback routines for all the objects, and update
      # the screen
      $screen->animate();

      # use getch to control the frame rate, and get input at the
      # same time. 
      my $input = getch();
      if($input eq 'q') { last; }
    }

    # cleanly end the animation, to avoid hosing up the user's terminal
    $screen->end();

This illustrates how to draw your animation into an existing Curses window.

    use Term::Animation;
    use Curses;

    # Term::Animation will not call initscr for you if
    # you pass it a window
    initscr();

    $win = newwin(5,10,8,7);

    $screen = Term::Animation->new($win);

Everything else would be identical to the previous example.

METHODS

add_object ($object1, [ $object2 ...])

Add one or more animation objects to the animation.

animate()

Generate and display a single animation frame. Calls do_callbacks(), build_screen() and display_screen(). You can call them yourself if you want to, but there is little useful you could do between these calls.

auto_trans ($shape, ['transparent character'])

Given a sprite animation, this will return the animation with transparency characters replacing any whitespace that appears on a line before the first non-whitespace character. The default transparent character is '?'. If you need to use '?' in your ASCII art, you can pass an alternate character here, but you will need to make sure you pass the same character as the transparent argument to the build_object() routine.

build_object()

Create an animation object given one or more frames of ASCII art, and a set of arguments to describe the object's behavior. The only required arguments are name and shape.

    name              A string uniquely identifying this object
    shape             The ASCII art for this object. It can be
                      provided as:
                      1) A single multi-line text string
                      2) An array of multi-line text strings
                      3) An array of 2D arrays, where each array
                         element is a single character
                      If you provide an array, each element is a
                      single frame of animation. If you provide
                      either 1) or 2), a single newline will be
                      stripped off of the beginning of each string.
    position          A list specifying initial x,y and z coordinates
                      Default: [ 0, 0, 0 ]
    callback          Callback routine for this object
                      Default: I<move_object()>
    callback_args     Arguments to the callback routine
    curr_frame        Animation frame to begin with
                      Default: 0
    wrap              Whether this object should wrap around the edge
                      of the screen (0 = No, 1 = Yes)
                      Default: 0
    transparent       Character used to indicate transparency
                      Default: ?
    auto_death        Method to automatically kill an object. Valid
                      values are 'offscreen', 'time', and 'frame'.
                      AUTO_DEATH section below for more detail.
    death_arg         Integer indicating 'time' or 'frame' for this
                      object to die
    death_cb          Callback routine used when this object dies
    dcb_args          Arguments to the death callback routine
    color             Color mask. This follows the same format as
                      'shape'. See the 'COLOR' section below for more
                      details
    default_color     A default color to use for the object.
                      See the 'COLOR' section below for more details

build_screen()

Update the curses object in memory with any changes that have been made after do_callbacks() has run. After calling this, you will need to call display_screen() for the changes to show up on your display.

color_enabled()

Returns 1 if color is enabled, 0 otherwise

disable_color()

Turn off ANSI color after it has been turned on using enable_color()

display_screen()

Update the display with the changes since the last update. Calling this twice in a row without calling build_screen() and do_callbacks() in the middle won't do anything.

do_callbacks()

Run the callback routines for all of the objects in the animation.

enable_color()

Turn on ANSI color. This MUST be called immediately after creating the animation object, because the Curses start_color call must be made immediately. You can then turn color on and off using this and disable_color() whenever you want.

end()

Run the Curses endwin function to get your terminal back to its normal mode. You should call this before your program exits.

exist('object_name')

Given an object name, will return true if it exists, false if it doesn't.

gen_path (x,y,z, x,y,z, [ frame_pattern ], [ steps ])

Given beginning and end points, this will return a path for the object to follow that can be given to the default callback routine, move_object(). The first set of x,y,z coordinates are the point the object will begin at, the second set is the point the object will end at.

You can optionally supply a list of frames to cycle through. The list will be repeated as many times as needed to finish the path.

You can also request the number of steps you would like for the object to take to finish the path. Valid arguments are: longest The longer of the X and Y distances shortest The shorter of the X and Y distances X,Y or Z Select the x, y or z distance <number> Explicitly specify the number of steps to take

get_current_frame('object_name')

Returns the current animation frame number of the named object. Carps if the object does not exist.

get_position('object name')

Returns the x,y,z coordinates of the named object. Carps if the object does not exist.

move_object('object name')

The default callback routine. Callback routines get their arguments from the CALLBACK_ARGS element of the object they have been told to act on. The data structure that move_object expects for CALLBACK_ARGS is either a list of X,Y,Z and frame deltas or a path generated by gen_path().

redraw_screen()

Clear everything from the screen, and redraw what should be there. This should be called after update_term_size(), or if the user indicates that the screen should be redrawn to get rid of artifacts.

remove_all_objects()

Remove every animation object. This is useful if you need to start the animation over (eg. after a screen resize)

set_background('color_name')

Change the background color. The default background color is black. You can only have one background color for the entire Curses window that the animation is running in.

size()

Returns the number of characters in the curses window (width * height)

update_term_size()

Call this if you suspect the terminal size has changed (eg. if you get a SIGWINCH signal). Call remove_all_objects() after this if you want to recreate your animation from scratch.

CALLBACK ROUTINES

Callback routines for all objects are called each time do_callbacks() is called. A default callback routine is supplied, move_object(), which is sufficient for most basic movement. If you want to create an object that exhibits more complex behavior, you will have to write a custom callback routine for it.

Callback routines take a single argument, the name of the object to act on. Any arguments required to tell the callback what to do with the object, or any state that needs to be maintained, should be put in the callback_args element of the object. callback_args is only referenced by the callback routine, and thus can contain any datastructure that you find useful.

The return value of your callback routine should be of the form:

    return ($x, $y, $z, $frame, $flag)

$x, $y and $z represent the X, Y and Z coordinates to which the object should move. $frame is the frame number that the object should display, if it has multiple frames of animation. $flag is a signal to do_callbacks() to perform some action on this object. Currently, the only valid value for $flag is 'kill', which will remove the object from the animation, and call the objects death callback routine if there is one. Any values that are unspecified or undef will remain unchanged.

AUTO_DEATH

Objects can be instructed to automatically die (remove themselves from the animation) under certain circumstances, so that after they are created they will clean up after themselves. There are three methods to automatically kill an object:

    offscreen           The object is no longer visible on the screen
    time                The current time is later than a supplied time
    frame               A specified number of frames have been displayed 

The type of automatic death is specified as the auto_death argument to build_object() when the object is created. the 'time' and 'frame' auto death types require a value to be sent as the death_arg argument to build_object. For 'time', the argument represents the time at which the the object should die, as returned by localtime() in scalar context. For 'frame', the argument is the number of frames that should be displayed after this object is added to the animation, before it dies. The 'offscreen' option does not require a death_arg argument.

COLOR

ANSI color is available for terminals that support it. Only a single background color can be used for the window (it would look terrible in most cases otherwise anyway). Colors for objects are specified by using a 'mask' that indicates the color for each character. For example, say we had a single frame of a bird:

$bird = q#

---. .-. .--- --\'v'/-- \ / " " #;

To indicate the colors you want to use for the bird, create a matching mask, with the first letter of each color in the appropriate position (except black, which is 'k'). Pass this mask to build_object() as the 'color' parameter.

$mask = q#

BBBB BBB BBBB BBBWYWBBB B B Y Y #;

When specifying a color, using uppercase indicates the color should be bold. So 'BLUE' or 'B' means bold blue, and 'blue' or 'b' means non-bold blue. 'Blue' means you get an error message.

You can also provide a default color with the default_color parameter to build_object. This color will be used for any character that does not have an entry in the mask. If you want the entire object to be a single color, you can just provide a default color with no mask.

The available colors are: red, green, blue, cyan, magenta, yellow, black and white.

Here's an example call to build_object for the bird above.

    $object = $screen->build_object (
                name            => "Bird",
                shape           => $bird,
                position        => [ 5, 8, 7 ],
                callback_args   => [ 1, 2, 0, 0 ],
                color           => $mask,
                default_color   => "BLUE"
                                    );

AUTHOR

Kirk Baucom, <kbaucom@schizoid.com>

SEE ALSO

Curses

cpanm Term::Animation

perl -MCPAN -e shell
install Term::Animation