1Term::Animation(3)    User Contributed Perl Documentation   Term::Animation(3)
2
3
4

NAME

6       Term::Animation - ASCII sprite animation framework
7

SYNOPSIS

9         use Term::Animation;
10
11         # Constructors
12         $anim = Term::Animation->new();
13         $anim = Term::Animation->new($curses_window);
14

ABSTRACT

16       A framework to produce sprite animations using ASCII art.
17

DESCRIPTION

19       This module provides a framework to produce sprite animations using
20       ASCII art. Each ASCII 'sprite' is given one or more frames, and placed
21       into the animation as an 'animation object'. An animation object can
22       have a callback routine that controls the position and frame of the
23       object.
24
25       If the constructor is passed no arguments, it assumes that it is
26       running full screen, and behaves accordingly. Alternatively, it can
27       accept a curses window (created with the Curses newwin call) as an
28       argument, and will draw into that window.
29

EXAMPLES

31       This example moves a small object across the screen from left to right.
32
33           use Term::Animation;
34           use Curses;
35
36           $anim = Term::Animation->new();
37
38           # set the delay for getch
39           halfdelay( 2 );
40
41           # create a simple shape we can move around
42           $shape = "<=O=>";
43
44           # turn our shape into an animation object
45           $anim->new_entity(
46                        shape         => $shape,        # object shape
47                        position      => [3, 7, 10],    # row / column / depth
48                        callback_args => [1, 0, 0, 0],  # the default callback
49                                                        #  routine takes a list
50                                                        #  of x,y,z,frame deltas
51                        wrap          => 1              # turn screen wrap on
52           );
53
54           # animation loop
55           while(1) {
56             # run and display a single animation frame
57             $anim->animate();
58
59             # use getch to control the frame rate, and get input at the
60             # same time. (not a good idea if you are expecting much input)
61             my $input = getch();
62             if($input eq 'q') { last; }
63           }
64
65           # cleanly end the animation, to avoid hosing up the user's terminal
66           $anim->end();
67
68       This illustrates how to draw your animation into an existing Curses
69       window.
70
71           use Term::Animation;
72           use Curses;
73
74           # Term::Animation will not call initscr for you if
75           # you pass it a window
76           initscr();
77
78           $win = newwin(5,10,8,7);
79
80           $anim = Term::Animation->new($win);
81
82       Everything else would be identical to the previous example.
83

METHODS

85       new
86             $anim = Term::Animation->new();
87             $anim = Term::Animation->new($curses_window);
88
89           The constructor. Optionally takes an existing curses window to draw
90           in.
91
92       new_entity
93             $anim->new_entity(
94                   shape         => $shape,
95                   position      => [ 1, 2, 3 ],
96                   callback_args => [ 1, 0, 0 ]
97             );
98
99           Creates a new Term::Animation::Entity object and adds it to the
100           animation. This is identical to:
101
102             my $entity = Term::Animation::Entity->new(...);
103             $anim->add_entity($entity);
104
105           See PARAMETERS and new in Term::Animation::Entity for details on
106           calling this method.
107
108       color_name
109             $name = $anim->color_name( $color );
110
111           Returns the full name of a color, given either a full name or a
112           single character abbreviation.
113
114       color_id
115             $id = $anim->color_id( $color );
116
117           Returns the single character abbreviation for a color, given either
118           a full name or abbreviation.
119
120       is_valid_color
121             my $is_valid = $anim->is_valid_color($color_name);
122
123           Returns true if the supplied string is a valid color name ('blue')
124           or a valid color id ('b').
125
126       color
127             my $state = $anim->color();
128             $anim->color($new_state);
129
130           Enable or disable ANSI color. This MUST be called immediately after
131           creating the animation object if you want color, because the Curses
132           start_color call must be made immediately. You can then turn color
133           on and off whenever you want.
134
135       background
136             $anim->background( $color );
137
138           Change the background color. The default background color is black.
139           You can only have one background color for the entire Curses window
140           that the animation is running in.
141
142       animate
143             $anim->animate();
144
145           Perform a single animation cycle. Runs all of the callbacks, does
146           collision detection, and updates the display.
147
148       track_framerate
149             $anim->track_framerate(1);
150             $tracking_framerate = $anim->track_framerate();
151
152           Get or set the flag that indicates whether the module should keep
153           track of the animation framerate. This is enabled by default.
154
155       framerate
156             $frames_per_second = $anim->framerate();
157
158           Returns the approximate number of frames being displayed per
159           second, as indicated by calls to the animate method.
160
161       screen_size
162             my ($width, $height, $assumed_size) = $anim->screen_size();
163
164           Returns the width and height of the screen. The third value
165           returned is a boolean indicating whether or not the default screen
166           size was used, because the size could not be determined.
167
168       update_term_size
169             $anim->update_term_size();
170
171           Call this if you suspect the terminal size has changed (eg. if you
172           get a SIGWINCH signal). Call remove_all_entities after this if you
173           want to recreate your animation from scratch.
174
175       add_entity
176             $anim->add_entity( $entity1, $entity2, $entity3 );
177
178           Add one or more animation entities to the animation.
179
180       del_entity
181             $anim->del_entity( $entity_name );
182             $anim->del_entity( $entity_ref );
183
184           Removes an entity from the animation. Accepts either an entity name
185           or a reference to the entity itself.
186
187       remove_all_entities
188             $anim->remove_all_entities();
189
190           Removes every animation object. This is useful if you need to start
191           the animation over (eg. after a screen resize)
192
193       entity_count
194             $number_of_entities = $anim->entity_count();
195
196           Returns the number of entities in the animation.
197
198       get_entities
199             $entity_list = $anim->get_entities();
200
201           Returns a reference to a list of all entities in the animation.
202
203       get_entities_of_type
204             $entity_list = $anim->get_entities_of_type( $type );
205
206           Returns a reference to a list of all entities in the animation that
207           have the given type.
208
209       is_living
210             my $is_living = $anim->is_living( $entity );
211
212           Return 1 if the entity name or reference is in the animation and is
213           not scheduled for deletion. Returns 0 otherwise.
214
215       entity
216             $entity_ref = $anim->entity( $entity_name );
217
218           If the animation contains an entity with the given name, the
219           Term::Animation::Entity object associated with the name is
220           returned. Otherwise, undef is returned.
221
222       width
223             $width = $anim->width();
224
225           Returns the width of the screen
226
227       height
228             $height = $anim->height();
229
230           Returns the height of the screen
231
232       size()
233             $size = $anim->size();
234
235           Returns the number of characters in the curses window (width *
236           height)
237
238       redraw_screen
239             $anim->redraw_screen();
240
241           Clear everything from the screen, and redraw what should be there.
242           This should be called after update_term_size, or if the user
243           indicates that the screen should be redrawn to get rid of
244           artifacts.
245
246       gen_path
247             # gen_path (x,y,z, x,y,z, [ frame_pattern ], [ steps ])
248
249             $anim->gen_path( $x1, $y1, $z1, $x2, $y2, $z2, [ 1, 2, 0, 2 ], 'longest' );
250
251           Given beginning and end points, this will return a path for the
252           entity to follow that can be given to the default callback routine,
253           move_entity. The first set of x,y,z coordinates are the point the
254           entity will begin at, the second set is the point the entity will
255           end at.
256
257           You can optionally supply a list of frames to cycle through. The
258           list will be repeated as many times as needed to finish the path.
259           If no list of frames is supplied, only the first frame will be
260           used.
261
262           You can also request the number of steps you would like for the
263           entity to take to finish the path. The default is 'shortest'.
264           Valid arguments are:
265             longest      The longer of the X and Y distances
266             shortest     The shorter of the X and Y distances
267             X,Y or Z     The x, y or z distance
268             <number>     Explicitly specify the number of steps to take
269
270       end
271             $anim->end();
272
273           Run the Curses endwin function to get your terminal back to its
274           normal mode. This is called automatically when the object is
275           destroyed if the animation is running full screen (if you did not
276           pass an existing Curses window to the constructor).
277

CALLBACK ROUTINES

279       Callback routines for all entities are called each time animate is
280       called. A default callback routine is supplied, move_entity, which is
281       sufficient for most basic movement. If you want to create an entity
282       that exhibits more complex behavior, you will have to write a custom
283       callback routine for it.
284
285       Callback routines take two arguments, a reference to the
286       Term::Animation::Entity object that it should act on, and a reference
287       to the Term::Animation instance that called it. Any arguments required
288       to tell the callback what to do with the object, or any state that
289       needs to be maintained, should be put in the callback_args element of
290       the object. callback_args is only referenced by the callback routine,
291       and thus can contain any datastructure that you find useful.
292
293       Here is an example custom callback that will make an entity move
294       randomly around the screen:
295
296         sub random_movement {
297             my ($entity, $anim) = @_;
298
299             # get the current position of the entity
300             my ($x, $y, $z) = $entity->position();
301
302             # we'll use callback_args to store the last axis we moved in
303             my $last_move = $entity->callback_args();
304
305             # if we moved in x last time, move in y this time
306             if($last_move eq 'x') {
307                 $entity->callback_args('y');
308                 # move by -1, 0 or 1
309                 $y += int(rand(3)) - 1;
310             } else {
311                 $entity->callback_args('x');
312                 $x += int(rand(3)) - 1;
313             }
314
315             # return the absolute x,y,z coordinates to move to
316             return ($x, $y, $z);
317         }
318
319       The return value of your callback routine should be of the form:
320
321           return ($x, $y, $z, $frame)
322
323       $x, $y and $z represent the X, Y and Z coordinates to which the object
324       should move. $frame is the frame number that the object should display,
325       if it has multiple frames of animation. Any values that are unspecified
326       or undef will remain unchanged.
327
328       You can also call the default callback from within your callback, if
329       you want it to handle movement for you. For example, if your callback
330       is simply used to decide when an entity should die:
331
332         sub wait_for_file {
333             my ($entity, $anim) = @_;
334
335             # kill this entity if a certain file shows up
336             if(-e "/path/to/file") {
337                 $entity->kill();
338                 return();
339             }
340
341             # use the default callback to handle the actual movement
342             return $entity->move_entity($anim);
343         }
344
345       If you use this, be aware that move_entity relies on callback_args, so
346       you cannot use it to store your own arbitrary data.
347

COLOR

349       ANSI color is available for terminals that support it. Only a single
350       background color can be used for the window (it would look terrible in
351       most cases otherwise anyway). Colors for entities are specified by
352       using a 'mask' that indicates the color for each character. For
353       example, say we had a single frame of a bird:
354
355         $bird = q#
356
357         ---. .-. .---
358           --\'v'/--
359              \ /
360              " "
361         #;
362
363       To indicate the colors you want to use for the bird, create a matching
364       mask, with the first letter of each color in the appropriate position
365       (except black, which is 'k'). Pass this mask as the color parameter.
366
367         $mask = q#
368
369         BBBB BBB BBBB
370           BBBWYWBBB
371              B B
372              Y Y
373         #;
374
375       When specifying a color, using uppercase indicates the color should be
376       bold. So 'BLUE' or 'B' means bold blue, and 'blue' or 'b' means non-
377       bold blue. 'Blue' means you get an error message.
378
379       You can also provide a default color with the default_color parameter.
380       This color will be used for any character that does not have an entry
381       in the mask. If you want the entire entity to be a single color, you
382       can just provide a default color with no mask.
383
384       The available colors are: red, green, blue, cyan, magenta, yellow,
385       black and white.
386
387       Here's an example call to build_object for the bird above.
388
389           $anim->new_entity (
390                     name              => "Bird",
391                     shape             => $bird,
392                     position          => [ 5, 8, 7 ],
393                     callback_args     => [ 1, 2, 0, 0 ],
394                     color             => $mask,
395                     default_color     => "BLUE"
396           );
397

AUTHOR

399       Kirk Baucom, <kbaucom@schizoid.com>
400

SEE ALSO

402       Curses
403
404
405
406perl v5.32.0                      2020-07-28                Term::Animation(3)
Impressum