1Term::Animation(3) User Contributed Perl Documentation Term::Animation(3)
2
6 Term::Animation - ASCII sprite animation framework
7
9 use Term::Animation;
10 # Constructors
12 $anim = Term::Animation->new();
13 $anim = Term::Animation->new($curses_window);
14
16 A framework to produce sprite animations using ASCII art.
17
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 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
31 This example moves a small object across the screen from left to right.
32 use Term::Animation;
34 use Curses;
35 $anim = Term::Animation->new();
37 # set the delay for getch
39 halfdelay( 2 );
40 # create a simple shape we can move around
42 $shape = "<=O=>";
43 # 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 # animation loop
55 while(1) {
56 # run and display a single animation frame
57 $anim->animate();
58 # 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 # cleanly end the animation, to avoid hosing up the user's terminal
66 $anim->end();
67 This illustrates how to draw your animation into an existing Curses
69 window.
70 use Term::Animation;
72 use Curses;
73 # Term::Animation will not call initscr for you if
75 # you pass it a window
76 initscr();
77 $win = newwin(5,10,8,7);
79 $anim = Term::Animation->new($win);
81 Everything else would be identical to the previous example.
83
85 new
86 $anim = Term::Animation->new();
87 $anim = Term::Animation->new($curses_window);
88 The constructor. Optionally takes an existing curses window to draw
90 in.
91 new_entity
93 $anim->new_entity(
94 shape => $shape,
95 position => [ 1, 2, 3 ],
96 callback_args => [ 1, 0, 0 ]
97 );
98 Creates a new Term::Animation::Entity object and adds it to the
100 animation. This is identical to:
101 my $entity = Term::Animation::Entity->new(...);
103 $anim->add_entity($entity);
104 See Term::Animation::Entity/PARAMETERS and
106 Term::Animation::Entity/new in Term::Animation::Entity for details
107 on calling this method.
108 color_name
110 $name = $anim->color_name( $color );
111 Returns the full name of a color, given either a full name or a
113 single character abbreviation.
114 color_id
116 $id = $anim->color_id( $color );
117 Returns the single character abbreviation for a color, given either
119 a full name or abbreviation.
120 is_valid_color
122 my $is_valid = $anim->is_valid_color($color_name);
123 Returns true if the supplied string is a valid color name ('blue')
125 or a valid color id ('b').
126 color
128 my $state = $anim->color();
129 $anim->color($new_state);
130 Enable or disable ANSI color. This MUST be called immediately after
132 creating the animation object if you want color, because the Curses
133 start_color call must be made immediately. You can then turn color
134 on and off whenever you want.
135 background
137 $anim->background( $color );
138 Change the background color. The default background color is black.
140 You can only have one background color for the entire Curses window
141 that the animation is running in.
142 animate
144 $anim->animate();
145 Perform a single animation cycle. Runs all of the callbacks, does
147 collision detection, and updates the display.
148 track_framerate
150 $anim->track_framerate(1);
151 $tracking_framerate = $anim->track_framerate();
152 Get or set the flag that indicates whether the module should keep
154 track of the animation framerate. This is enabled by default.
155 framerate
157 $frames_per_second = $anim->framerate();
158 Returns the approximate number of frames being displayed per
160 second, as indicated by calls to the animate method.
161 screen_size
163 my ($width, $height, $assumed_size) = $anim->screen_size();
164 Returns the width and height of the screen. The third value
166 returned is a boolean indicating whether or not the default screen
167 size was used, because the size could not be determined.
168 update_term_size
170 $anim->update_term_size();
171 Call this if you suspect the terminal size has changed (eg. if you
173 get a SIGWINCH signal). Call remove_all_entities after this if you
174 want to recreate your animation from scratch.
175 add_entity
177 $anim->add_entity( $entity1, $entity2, $entity3 );
178 Add one or more animation entities to the animation.
180 del_entity
182 $anim->del_entity( $entity_name );
183 $anim->del_entity( $entity_ref );
184 Removes an entity from the animation. Accepts either an entity name
186 or a reference to the entity itself.
187 remove_all_entities
189 $anim->remove_all_entities();
190 Removes every animation object. This is useful if you need to start
192 the animation over (eg. after a screen resize)
193 entity_count
195 $number_of_entities = $anim->entity_count();
196 Returns the number of entities in the animation.
198 get_entities
200 $entity_list = $anim->get_entities();
201 Returns a reference to a list of all entities in the animation.
203 get_entities_of_type
205 $entity_list = $anim->get_entities_of_type( $type );
206 Returns a reference to a list of all entities in the animation that
208 have the given type.
209 is_living
211 my $is_living = $anim->is_living( $entity );
212 Return 1 if the entity name or reference is in the animation and is
214 not scheduled for deletion. Returns 0 otherwise.
215 entity
217 $entity_ref = $anim->entity( $entity_name );
218 If the animation contains an entity with the given name, the
220 Term::Animation::Entity object associated with the name is
221 returned. Otherwise, undef is returned.
222 width
224 $width = $anim->width();
225 Returns the width of the screen
227 height
229 $height = $anim->height();
230 Returns the height of the screen
232 size()
234 $size = $anim->size();
235 Returns the number of characters in the curses window (width *
237 height)
238 redraw_screen
240 $anim->redraw_screen();
241 Clear everything from the screen, and redraw what should be there.
243 This should be called after update_term_size, or if the user
244 indicates that the screen should be redrawn to get rid of
245 artifacts.
246 gen_path
248 # gen_path (x,y,z, x,y,z, [ frame_pattern ], [ steps ])
249 $anim->gen_path( $x1, $y1, $z1, $x2, $y2, $z2, [ 1, 2, 0, 2 ], 'longest' );
251 Given beginning and end points, this will return a path for the
253 entity to follow that can be given to the default callback routine,
254 move_entity. The first set of x,y,z coordinates are the point the
255 entity will begin at, the second set is the point the entity will
256 end at.
257 You can optionally supply a list of frames to cycle through. The
259 list will be repeated as many times as needed to finish the path.
260 If no list of frames is supplied, only the first frame will be
261 used.
262 You can also request the number of steps you would like for the
264 entity to take to finish the path. The default is 'shortest'.
265 Valid arguments are:
266 longest The longer of the X and Y distances
267 shortest The shorter of the X and Y distances
268 X,Y or Z The x, y or z distance
269 <number> Explicitly specify the number of steps to take
270 end
272 $anim->end();
273 Run the Curses endwin function to get your terminal back to its
275 normal mode. This is called automatically when the object is
276 destroyed if the animation is running full screen (if you did not
277 pass an existing Curses window to the constructor).
278
280 Callback routines for all entities are called each time animate is
281 called. A default callback routine is supplied, move_entity, which is
282 sufficient for most basic movement. If you want to create an entity
283 that exhibits more complex behavior, you will have to write a custom
284 callback routine for it.
285 Callback routines take two arguments, a reference to the
287 Term::Animation::Entity object that it should act on, and a reference
288 to the Term::Animation instance that called it. Any arguments required
289 to tell the callback what to do with the object, or any state that
290 needs to be maintained, should be put in the callback_args element of
291 the object. callback_args is only referenced by the callback routine,
292 and thus can contain any datastructure that you find useful.
293 Here is an example custom callback that will make an entity move
295 randomly around the screen:
296 sub random_movement {
298 my ($entity, $anim) = @_;
299 # get the current position of the entity
301 my ($x, $y, $z) = $entity->position();
302 # we'll use callback_args to store the last axis we moved in
304 my $last_move = $entity->callback_args();
305 # if we moved in x last time, move in y this time
307 if($last_move eq 'x') {
308 $entity->callback_args('y');
309 # move by -1, 0 or 1
310 $y += int(rand(3)) - 1;
311 } else {
312 $entity->callback_args('x');
313 $x += int(rand(3)) - 1;
314 }
315 # return the absolute x,y,z coordinates to move to
317 return ($x, $y, $z);
318 }
319 The return value of your callback routine should be of the form:
321 return ($x, $y, $z, $frame)
323 $x, $y and $z represent the X, Y and Z coordinates to which the object
325 should move. $frame is the frame number that the object should display,
326 if it has multiple frames of animation. Any values that are unspecified
327 or undef will remain unchanged.
328 You can also call the default callback from within your callback, if
330 you want it to handle movement for you. For example, if your callback
331 is simply used to decide when an entity should die:
332 sub wait_for_file {
334 my ($entity, $anim) = @_;
335 # kill this entity if a certain file shows up
337 if(-e "/path/to/file") {
338 $entity->kill();
339 return();
340 }
341 # use the default callback to handle the actual movement
343 return $entity->move_entity($anim);
344 }
345 If you use this, be aware that move_entity relies on callback_args, so
347 you cannot use it to store your own arbitrary data.
348
350 ANSI color is available for terminals that support it. Only a single
351 background color can be used for the window (it would look terrible in
352 most cases otherwise anyway). Colors for entities are specified by
353 using a 'mask' that indicates the color for each character. For
354 example, say we had a single frame of a bird:
355 $bird = q#
357 ---. .-. .---
359 --\'v'/--
360 \ /
361 " "
362 #;
363 To indicate the colors you want to use for the bird, create a matching
365 mask, with the first letter of each color in the appropriate position
366 (except black, which is 'k'). Pass this mask as the color parameter.
367 $mask = q#
369 BBBB BBB BBBB
371 BBBWYWBBB
372 B B
373 Y Y
374 #;
375 When specifying a color, using uppercase indicates the color should be
377 bold. So 'BLUE' or 'B' means bold blue, and 'blue' or 'b' means non-
378 bold blue. 'Blue' means you get an error message.
379 You can also provide a default color with the default_color parameter.
381 This color will be used for any character that does not have an entry
382 in the mask. If you want the entire entity to be a single color, you
383 can just provide a default color with no mask.
384 The available colors are: red, green, blue, cyan, magenta, yellow,
386 black and white.
387 Here's an example call to build_object for the bird above.
389 $anim->new_entity (
391 name => "Bird",
392 shape => $bird,
393 position => [ 5, 8, 7 ],
394 callback_args => [ 1, 2, 0, 0 ],
395 color => $mask,
396 default_color => "BLUE"
397 );
398
400 Kirk Baucom, <kbaucom@schizoid.com>
401
403 Curses
404
406 Hey! The above document had some coding errors, which are explained
407 below:
408 Around line 179:
410 alternative text 'Term::Animation::Entity/PARAMETERS' contains non-
411 escaped | or /
412 alternative text 'Term::Animation::Entity/new' contains non-escaped
414 | or /
415perl v5.28.0 2011-03-29 Term::Animation(3)