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;

$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 routine for each object
  $screen->do_callbacks();

  # draw the new positions/frames of the objects in memory
  $screen->build_screen();

  # print the updated screen
  $screen->display_screen();

  sleep 1;
}

# in the unlikely event that 1 becomes untrue, exit cleanly
$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.

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'. See 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

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.

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.

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.

update_term_size()

Call this if you suspect the terminal size has changed (eg. if you get a SIGWINCH signal). You will want to call redraw_screen() afterwards to make sure you don't leave an artifacts on the screen.

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.

AUTHOR

Kirk Baucom, <kbaucom@schizoid.com>

SEE ALSO

Curses

cpanm Term::Animation

perl -MCPAN -e shell
install Term::Animation