Animation.pm

filter: Statementstmt 85.7% 12 / 14 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 5 / 5 Podpod n/a totaltotal 89.4% 17 / 19 CC 1 SCAR 0.6
CC
1
Cov
86%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.1
« Animation/Entity.pm ↑ Summary
1 package Term::Animation;
2  
3 1 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 1 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 0 ▶use Curses;
Subroutine BEGIN: called CC=1 SCAR=2.6
8 use Term::Animation::Entity;
9  
10 use Data::Dumper;
11  
12 =head1 NAME
13  
14 Term::Animation - ASCII sprite animation framework
15  
16 =head1 SYNOPSIS
17  
18 use Term::Animation;
19  
20 # Constructors
21 $anim = Term::Animation->new();
22 $anim = Term::Animation->new($curses_window);
23  
24 =head1 ABSTRACT
25  
26 A framework to produce sprite animations using ASCII art.
27  
28 =head1 DESCRIPTION
29  
30 This module provides a framework to produce sprite animations using
31 ASCII art. Each ASCII 'sprite' is given one or more frames, and placed
32 into the animation as an 'animation object'. An animation object can
33 have a callback routine that controls the position and frame of the
34 object.
35  
36 If the constructor is passed no arguments, it assumes that it is
37 running full screen, and behaves accordingly. Alternatively, it can
38 accept a curses window (created with the Curses I<newwin> call) as an
39 argument, and will draw into that window.
40  
41 =head1 EXAMPLES
42  
43 This example moves a small object across the screen from left to right.
44  
45 use Term::Animation;
46 use Curses;
47  
48 $anim = Term::Animation->new();
49  
50 # set the delay for getch
51 halfdelay( 2 );
52  
53 # create a simple shape we can move around
54 $shape = "<=O=>";
55  
56 # turn our shape into an animation object
57 $anim->new_entity(
58 shape => $shape, # object shape
59 position => [3, 7, 10], # row / column / depth
60 callback_args => [1, 0, 0, 0], # the default callback
61 # routine takes a list
62 # of x,y,z,frame deltas
63 wrap => 1 # turn screen wrap on
64 );
65  
66 # animation loop
67 while(1) {
68 # run and display a single animation frame
69 $anim->animate();
70  
71 # use getch to control the frame rate, and get input at the
72 # same time. (not a good idea if you are expecting much input)
73 my $input = getch();
74 if($input eq 'q') { last; }
75 }
76  
77 # cleanly end the animation, to avoid hosing up the user's terminal
78 $anim->end();
79  
80 This illustrates how to draw your animation into an existing Curses window.
81  
82 use Term::Animation;
83 use Curses;
84  
85 # Term::Animation will not call initscr for you if
86 # you pass it a window
87 initscr();
88  
89 $win = newwin(5,10,8,7);
90  
91 $anim = Term::Animation->new($win);
92  
93 Everything else would be identical to the previous example.
94  
95 =head1 METHODS
96  
97 =over 4
98  
99 =cut
100  
101 our $VERSION = '2.6';
102  
103 our ($color_names, $color_ids) = _color_list();
104  
105 =item I<new>
106  
107 $anim = Term::Animation->new();
108 $anim = Term::Animation->new($curses_window);
109  
110 The constructor. Optionally takes an existing curses window
111 to draw in.
112  
113 =cut
114 sub new {
115 my $proto = shift;
116 my $class = ref($proto) || $proto;
117 my $self = {};
118  
119 $self->{ENTITIES} = {};
120 $self->{ENTITYCOUNT} = 0;
121 $self->{PHYSICALENTITIES} = {};
122 $self->{PHYSICALCOUNT} = 0;
123 $self->{COLOR_ENABLED} = 0;
124 $self->{LAST_FRAME_TIME} = 0;
125  
126 # framerate related settings
127 $self->{TRACK_FRAMERATE} = 1;
128 $self->{FRAMERATE} = 0;
129 $self->{FRAMES_THIS_SECOND} = 0;
130  
131 $self->{WIN} = shift;
132 if(defined($self->{WIN})) {
133 unless(ref($self->{WIN}) eq 'Curses::Window') {
134 carp("Expecting Curses::Window object, recieved " . ref($self->{WIN}));
135 return undef;
136 }
137 $self->{FULLSCREEN} = 0;
138 } else {
139 # this is the method in the docs...
140 $self->{WIN} = new Curses;
141 # ...but apparently it's broken with some versions of Curses or ncurses.
142 # this seems to work everywhere, but the Curses.pm docs
143 # say to call the constructor when using objects.
144 unless(defined($self->{WIN})) {
145 $self->{WIN} = Curses::initscr();
146 }
147  
148 noecho();
149 curs_set(0);
150 $self->{FULLSCREEN} = 1;
151 }
152  
153 ($self->{WIDTH}, $self->{HEIGHT}, $self->{ASSUMED_SIZE}) = _get_term_size($self->{WIN});
154 bless ($self, $class);
155 return $self;
156 }
157  
158 sub DESTROY {
159 my ($self) = @_;
160 if($self->{FULLSCREEN}) {
161 endwin();
162 }
163 }
164  
165 =item I<new_entity>
166  
167 $anim->new_entity(
168 shape => $shape,
169 position => [ 1, 2, 3 ],
170 callback_args => [ 1, 0, 0 ]
171 );
172  
173 Creates a new Term::Animation::Entity object and adds it to the
174 animation. This is identical to:
175  
176 my $entity = Term::Animation::Entity->new(...);
177 $anim->add_entity($entity);
178  
179 See L<Term::Animation::Entity/PARAMETERS|PARAMETERS> and L<Term::Animation::Entity/new|new>
180 in L<Term::Animation::Entity> for details on calling this method.
181  
182 =cut
183 sub new_entity {
184 my ($self, @ent_args) = @_;
185 my $entity = Term::Animation::Entity->new(@ent_args);
186 $self->add_entity($entity);
187 return $entity;
188 }
189  
190 ##################### COLOR UTILITIES #######################
191  
192 # create lists mapping full color names (eg. 'blue') and
193 # single character color ids (eg. 'b')
194 sub _color_list {
195 my %color_n;
196 my %color_i = (
197 black => 'k',
198 white => 'w',
199 red => 'r',
200 green => 'g',
201 blue => 'b',
202 cyan => 'c',
203 magenta => 'm',
204 yellow => 'y',
205 );
206  
207 for (keys %color_i) {
208 $color_i{uc($_)} = uc($color_i{$_});
209 }
210  
211 for (keys %color_i) {
212 $color_n{$color_i{$_}} = $_;
213 $color_n{$_} = $_;
214 $color_n{uc($_)} = uc($_);
215 }
216  
217 for(qw{ k w r g b c m y }) {
218 $color_i{$_} = $_;
219 $color_i{uc($_)} = uc($_);
220 }
221  
222 return (\%color_n, \%color_i);
223 }
224  
225 # build a list of every color combination for our current
226 # background color
227 sub _set_colors {
228 my ($self) = @_;
229  
230 my $cid = 1;
231  
232 my $bg = eval "Curses::COLOR_$self->{BG}";
233  
234 for my $f ('w', 'r', 'g', 'b', 'c', 'm', 'y', 'k') {
235 my $c = uc(color_name($f));
236 init_pair($cid, eval "Curses::COLOR_$c", $bg);
237 $self->{COLORS}{$f} = COLOR_PAIR($cid);
238 $cid++;
239 }
240 }
241  
242 =item I<color_name>
243  
244 $name = $anim->color_name( $color );
245  
246 Returns the full name of a color, given either a full
247 name or a single character abbreviation.
248  
249 =cut
250 sub color_name {
251 my ($color) = @_;
252 if(defined($color_names->{$color})) {
253 return $color_names->{$color};
254 } else {
255 carp("Attempt to allocate unknown color: $color");
256 return undef;
257 }
258 }
259  
260 =item I<color_id>
261  
262 $id = $anim->color_id( $color );
263  
264 Returns the single character abbreviation for a color,
265 given either a full name or abbreviation.
266  
267 =cut
268 sub color_id {
269 my ($color) = @_;
270 if(defined($color_ids->{$color})) {
271 return $color_ids->{$color};
272 } else {
273 carp("Attempt to allocate unknown color: $color");
274 return undef;
275 }
276 }
277  
278 =item I<is_valid_color>
279  
280 my $is_valid = $anim->is_valid_color($color_name);
281  
282 Returns true if the supplied string is a valid color name ('blue')
283 or a valid color id ('b').
284  
285 =cut
286 sub is_valid_color {
287 my ($color) = @_;
288 return(defined($color_ids->{$color}));
289 }
290  
291 =item I<color>
292  
293 my $state = $anim->color();
294 $anim->color($new_state);
295  
296 Enable or disable ANSI color. This MUST be called immediately after creating
297 the animation object if you want color, because the Curses start_color call must
298 be made immediately. You can then turn color on and off whenever you want.
299  
300 =cut
301 sub color {
302 my $self = shift;
303 if(@_) {
304 my $enable = shift;
305 if($enable != $self->{COLOR_ENABLED}) {
306 if($enable) {
307 start_color();
308 unless(defined($self->{BG})) { $self->{BG} = 'BLACK'; }
309 $self->_set_colors();
310 $self->{WIN}->bkgdset($self->{COLORS}{'w'});
311 }
312 $self->{COLOR_ENABLED} = $enable;
313 }
314 }
315 return $self->{COLOR_ENABLED};
316 }
317  
318 =item I<background>
319  
320 $anim->background( $color );
321  
322 Change the background color. The default background color is black. You
323 can only have one background color for the entire Curses window that
324 the animation is running in.
325  
326 =cut
327 sub background {
328 my $self = shift;
329 if(@_) {
330 my $color = shift;
331 my $bg_color = color_name($color);
332 if(defined($bg_color)) {
333 $self->{BG} = uc($bg_color);
334 $self->_set_colors();
335 $self->{WIN}->bkgdset($self->{COLORS}{'w'});
336 }
337 }
338 return $self->{BG};
339 }
340  
341 ########## END COLOR UTILITIES ###########
342  
343 ########################## PHYSICS UTILITIES ##########################
344  
345  
346 # go through all of the physical entities looking for
347 # collisions.
348 sub _find_collisions {
349 my ($self) = @_;
350  
351 my @col_set = ();
352 my @coord = ();
353 my @size = ();
354 my @name = ();
355  
356 for my $ent (values %{$self->{ENTITIES}}) {
357 next unless($ent->physical());
358 push(@coord, [ $ent->position() ]);
359 push(@size, [ $ent->size() ]);
360 push(@name, $ent->name());
361  
362 for my $i (0..($#name-1)) {
363 # X
364 if( ($coord[$i][0] <= $coord[-1][0] and $coord[-1][0] < $coord[$i][0] + $size[$i][0]) or
365 ($coord[-1][0] <= $coord[$i][0] and $coord[$i][0] < $coord[-1][0] + $size[-1][0]) ) {
366 # Y
367 if( ($coord[$i][1] <= $coord[-1][1] and $coord[-1][1] < $coord[$i][1] + $size[$i][1]) or
368 ($coord[-1][1] <= $coord[$i][1] and $coord[$i][1] < $coord[-1][1] + $size[-1][1]) ) {
369 # Z
370 if( ($coord[$i][2] <= $coord[-1][2] and $coord[-1][2] < $coord[$i][2] + $size[$i][2]) or
371 ($coord[-1][2] <= $coord[$i][2] and $coord[$i][2] < $coord[-1][2] + $size[-1][2]) ) {
372 push( @{$ent->{COLLISIONS}}, $self->{ENTITIES}{$name[$i]} );
373 push( @{$self->{ENTITIES}{$name[$i]}{COLLISIONS}}, $ent );
374  
375 }
376 }
377 }
378 }
379 }
380  
381 return;
382 }
383  
384 # update the list of physical entities when the physical state
385 # of an entity changes
386 sub _update_physical {
387 my ($self, $entity) = @_;
388 if($entity->{PHYSICAL} && !defined($self->{PHYSICALENTITIES}{$entity->{NAME}})) {
389 $self->{PHYSICALCOUNT}++;
390 $self->{PHYSICALENTITIES}{$entity->{NAME}} = $entity;
391 } elsif(defined($self->{PHYSICALENTITIES}{$entity->{NAME}})) {
392 $self->{PHYSICALCOUNT}--;
393 delete $self->{PHYSICALENTITIES}{$entity->{NAME}};
394 }
395 }
396  
397 ########## END PHYSICS UTILITIES ###########
398  
399 =item I<animate>
400  
401 $anim->animate();
402  
403 Perform a single animation cycle. Runs all of the callbacks,
404 does collision detection, and updates the display.
405  
406 =cut
407 sub animate {
408 my ($self) = @_;
409 $self->_do_callbacks();
410 if($self->{PHYSICALCOUNT} > 0) {
411 $self->_find_collisions();
412 $self->_collision_handlers();
413 }
414 $self->_remove_deleted_entities();
415 $self->_move_followers();
416 $self->_build_screen();
417 $self->_display_screen();
418 $self->_track_frame_rate() if $self->{TRACK_FRAMERATE};
419 }
420  
421 sub _track_frame_rate {
422 my ($self) = @_;
423 my $time = time();
424 if($time > $self->{LAST_FRAME_TIME}) {
425 $self->{LAST_FRAME_TIME} = $time;
426 $self->{FRAMERATE} = ($self->{FRAMERATE} + ($self->{FRAMES_THIS_SECOND} * 2) ) / 3;
427 $self->{FRAMES_THIS_SECOND} = 1;
428 } else {
429 $self->{FRAMES_THIS_SECOND}++;
430 }
431 }
432  
433 =item I<track_framerate>
434  
435 $anim->track_framerate(1);
436 $tracking_framerate = $anim->track_framerate();
437  
438 Get or set the flag that indicates whether the module
439 should keep track of the animation framerate. This is
440 enabled by default.
441  
442 =cut
443 sub track_framerate {
444 my ($self) = @_;
445 if(@_) {
446 $self->{TRACK_FRAMERATE} = shift;
447 }
448 return $self->{TRACK_FRAMERATE};
449 }
450  
451 =item I<framerate>
452  
453 $frames_per_second = $anim->framerate();
454  
455 Returns the approximate number of frames being displayed
456 per second, as indicated by calls to the I<animate> method.
457  
458 =cut
459 sub framerate {
460 my ($self) = @_;
461 return $self->{FRAMERATE};
462 }
463  
464 =item I<screen_size>
465  
466 my ($width, $height, $assumed_size) = $anim->screen_size();
467  
468 Returns the width and height of the screen. The third value
469 returned is a boolean indicating whether or not the default
470 screen size was used, because the size could not be determined.
471  
472 =cut
473 sub screen_size {
474 my $self = shift;
475 return($self->{WIDTH}, $self->{HEIGHT}, $self->{ASSUMED_SIZE});
476 }
477  
478 =item I<update_term_size>
479  
480 $anim->update_term_size();
481  
482 Call this if you suspect the terminal size has changed (eg. if you
483 get a SIGWINCH signal). Call I<remove_all_entities> after this if
484 you want to recreate your animation from scratch.
485  
486 =cut
487 sub update_term_size {
488 my $self = shift;
489 # dunno how portable this is. i should probably be using
490 # resizeterm.
491 endwin();
492 refresh();
493 ($self->{WIDTH}, $self->{HEIGHT}, $self->{ASSUMED_SIZE}) = _get_term_size($self->{WIN});
494 }
495  
496 # try to figure out the terminal size, and set
497 # a reasonable size if we can't. the 'assumed_size'
498 # variable will let programs know if we had to
499 # guess or not.
500 sub _get_term_size {
501 my $win = shift;
502 my ($width, $height, $assumed_size);
503 # find the width and height of the terminal
504 $width = $win->getmaxx();
505 $height = $win->getmaxy();
506 if($width and $height) {
507 $assumed_size = 0; # so we know if we can limit the max size or not
508 } else {
509 $assumed_size = 1;
510 $width = 80;
511 $height = 24;
512 }
513 return($width, $height, $assumed_size);
514 }
515  
516 # write to the curses window
517 sub _build_screen {
518 my($self) = @_;
519  
520 # clear the window before we start redrawing
521 $self->{WIN}->addstr( 0, 0, ' 'x$self->size() );
522  
523 return unless($self->{ENTITYCOUNT});
524 foreach my $entity (sort {$b->{'Z'} <=> $a->{'Z'}} values %{$self->{ENTITIES}}) {
525 _draw_entity($self, $entity);
526 }
527 }
528  
529 # draw an entity into the curses window in memory
530 sub _draw_entity {
531 my ($self, $entity) = @_;
532  
533 # a few temporary variables to make the code below easier to read
534 my $shape = $entity->{SHAPE}[$entity->{CURR_FRAME}];
535 my $colors = $self->{COLORS};
536 my $fg = $entity->{COLOR}[$entity->{CURR_FRAME}];
537 my $attrs = $entity->{ATTR}[$entity->{CURR_FRAME}];
538 my ($x, $y) = ($entity->{'X'}, $entity->{'Y'});
539 my ($w, $h) = ($self->{WIDTH}, $self->{HEIGHT});
540 my $wrap = $entity->{WRAP};
541 my $trans = $entity->{TRANSPARENT};
542 my $win = $self->{WIN};
543 my $color_enabled = $self->{COLOR_ENABLED};
544 my $attr;
545  
546 for my $i (0..$#{$shape}) {
547 my $y_pos = $y+$i;
548  
549 for my $j (0..$#{$shape->[$i]}) {
550 unless($shape->[$i][$j] eq $trans) { # transparent char
551 my $x_pos = $x+$j;
552  
553 if($wrap) {
554 while($x_pos >= $w) { $x_pos -= $w; }
555 while($y_pos >= $h) { $y_pos -= $h; }
556 } elsif($x_pos >= $w or $y_pos >= $h) {
557 next;
558 }
559  
560 unless($x_pos < 0 or $y_pos < 0) {
561 if($color_enabled) {
562 if(defined($attrs->[$i][$j])) {
563 $attr = $colors->{$fg->[$i][$j]} | $attrs->[$i][$j];
564 } else {
565 $attr = $colors->{$fg->[$i][$j]};
566 }
567  
568 $win->attron( $attr );
569 $win->addstr( int($y_pos), int($x_pos), $shape->[$i][$j]);
570 $win->attroff( $attr );
571 } else {
572 $win->addstr( int($y_pos), int($x_pos), $shape->[$i][$j]);
573 }
574 }
575 }
576 }
577 }
578 }
579  
580 =item I<add_entity>
581  
582 $anim->add_entity( $entity1, $entity2, $entity3 );
583  
584 Add one or more animation entities to the animation.
585  
586 =cut
587 sub add_entity {
588 my ($self, @entities) = @_;
589 foreach my $entity (@entities) {
590 $self->{ENTITYCOUNT}++;
591 if($entity->{PHYSICAL}) {
592 $self->{PHYSICALCOUNT}++;
593 $self->{PHYSICALENTITIES}{$entity->{NAME}} = $entity;
594 }
595 $self->{ENTITIES}{$entity->{NAME}} = $entity;
596 $entity->{ANIMATION} = $self;
597 }
598 }
599  
600 =item I<del_entity>
601  
602 $anim->del_entity( $entity_name );
603 $anim->del_entity( $entity_ref );
604  
605 Removes an entity from the animation. Accepts either an entity
606 name or a reference to the entity itself.
607  
608 =cut
609 sub del_entity {
610 my ($self, $entity) = @_;
611 if(ref($entity)) {
612 $entity = $entity->name();
613 }
614 if(defined($self->{ENTITIES}{$entity})) {
615 push(@{$self->{DELETEQUEUE}}, $entity);
616 } else {
617 carp("Attempted to destroy nonexistant entity '$entity'");
618 }
619 }
620  
621 # go through the list of entities that have been queued for
622 # deletion using del_entity and remove them
623 sub _remove_deleted_entities {
624 my ($self) = @_;
625 while(my $entity_name = shift @{$self->{DELETEQUEUE}}) {
626 my $entity = $self->{ENTITIES}{$entity_name};
627 if(defined($entity->{DEATH_CB})) {
628 $entity->{DEATH_CB}->($entity, $self);
629 }
630 if($entity->{PHYSICAL}) {
631 $self->{PHYSICALCOUNT}--;
632 delete $self->{PHYSICALENTITIES}{$entity_name};
633 }
634 delete $self->{ENTITIES}{$entity_name};
635 $self->{ENTITYCOUNT}--;
636 }
637 }
638  
639 =item I<remove_all_entities>
640  
641 $anim->remove_all_entities();
642  
643 Removes every animation object. This is useful if you need to start the
644 animation over (eg. after a screen resize)
645  
646 =cut
647 sub remove_all_entities {
648 my ($self) = @_;
649 $self->{ENTITYCOUNT} = 0;
650 $self->{PHYSICALCOUNT} = 0;
651 $self->{PHYSICALENTITIES} = {};
652 $self->{ENTITIES} = {};
653 }
654  
655 =item I<entity_count>
656  
657 $number_of_entities = $anim->entity_count();
658  
659 Returns the number of entities in the animation.
660  
661 =cut
662 sub entity_count {
663 my ($self) = @_;
664 my $count = 0;
665 foreach (keys %{$self->{ENTITIES}}) {
666 $count++;
667 }
668 return $count;
669 }
670  
671 =item I<get_entities>
672  
673 $entity_list = $anim->get_entities();
674  
675 Returns a reference to a list of all entities in the animation.
676  
677 =cut
678 sub get_entities {
679 my ($self) = @_;
680 my @entities = keys %{$self->{ENTITIES}};
681 return \@entities;
682 }
683  
684 =item I<get_entities_of_type>
685  
686 $entity_list = $anim->get_entities_of_type( $type );
687  
688 Returns a reference to a list of all entities in the animation
689 that have the given type.
690  
691 =cut
692 sub get_entities_of_type {
693 my ($self, $type) = @_;
694 my @entities;
695 foreach my $entity (values %{$self->{ENTITIES}}) {
696 if($entity->{TYPE} eq $type) {
697 push(@entities, $entity->{NAME});
698 }
699 }
700 return \@entities;
701 }
702  
703 =item I<is_living>
704  
705 my $is_living = $anim->is_living( $entity );
706  
707 Return 1 if the entity name or reference is in the animation
708 and is not scheduled for deletion. Returns 0 otherwise.
709  
710 =cut
711 sub is_living {
712 my ($self, $entity) = @_;
713  
714 if(ref($entity) eq 'Term::Animation::Entity') {
715 $entity = $entity->name();
716 }
717  
718 unless(exists($self->{'ENTITIES'}{$entity})) {
719 return 0;
720 }
721  
722 foreach my $dying_ent (@{$self->{DELETEQUEUE}}) {
723 if($dying_ent eq $entity) {
724 return 0;
725 }
726 }
727  
728 return 1;
729 }
730  
731 =item I<entity>
732  
733 $entity_ref = $anim->entity( $entity_name );
734  
735 If the animation contains an entity with the given name,
736 the Term::Animation::Entity object associated with the name
737 is returned. Otherwise, undef is returned.
738  
739 =cut
740 sub entity {
741 my ($self, $entity_name) = @_;
742 if(defined($self->{ENTITIES}{$entity_name})) {
743 return $self->{ENTITIES}{$entity_name};
744 } else {
745 return undef;
746 }
747 }
748  
749 =item I<width>
750  
751 $width = $anim->width();
752  
753 Returns the width of the screen
754  
755 =cut
756 sub width {
757 my ($self) = @_;
758 return $self->{WIDTH};
759 }
760  
761 =item I<height>
762  
763 $height = $anim->height();
764  
765 Returns the height of the screen
766  
767 =cut
768 sub height {
769 my ($self) = @_;
770 return $self->{HEIGHT};
771 }
772  
773 =item I<size()>
774  
775 $size = $anim->size();
776  
777 Returns the number of characters in the curses window (width * height)
778  
779 =cut
780 sub size {
781 my ($self) = @_;
782 return ( $self->{HEIGHT} * $self->{WIDTH} )
783 }
784  
785 =item I<redraw_screen>
786  
787 $anim->redraw_screen();
788  
789 Clear everything from the screen, and redraw what should be there. This
790 should be called after I<update_term_size>, or if the user indicates that
791 the screen should be redrawn to get rid of artifacts.
792  
793 =cut
794 sub redraw_screen {
795 my ($self) = @_;
796 $self->{WIN}->clear();
797 $self->{WIN}->refresh();
798 $self->_build_screen();
799 $self->{WIN}->move($self->{HEIGHT}-1, $self->{WIDTH}-1);
800 $self->{WIN}->refresh();
801 }
802  
803 # draw the elements of the screen that have changed since the last update
804 sub _display_screen {
805 my ($self) = @_;
806 $self->{WIN}->move($self->{HEIGHT}-1, $self->{WIDTH}-1);
807 $self->{WIN}->refresh();
808 }
809  
810  
811 =item I<gen_path>
812  
813 # gen_path (x,y,z, x,y,z, [ frame_pattern ], [ steps ])
814  
815 $anim->gen_path( $x1, $y1, $z1, $x2, $y2, $z2, [ 1, 2, 0, 2 ], 'longest' );
816  
817 Given beginning and end points, this will return a path for the
818 entity to follow that can be given to the default callback routine,
819 I<move_entity>. The first set of x,y,z coordinates are the point
820 the entity will begin at, the second set is the point the entity
821 will end at.
822  
823 You can optionally supply a list of frames to cycle through. The list
824 will be repeated as many times as needed to finish the path. If no
825 list of frames is supplied, only the first frame will be used.
826  
827 You can also request the number of steps you would like for the entity
828 to take to finish the path. The default is 'shortest'.
829 Valid arguments are:
830 longest The longer of the X and Y distances
831 shortest The shorter of the X and Y distances
832 X,Y or Z The x, y or z distance
833 <number> Explicitly specify the number of steps to take
834  
835 =cut
836 sub gen_path {
837 my ($self, $x_start, $y_start, $z_start, $x_end, $y_end, $z_end, $frame_pattern, $steps_req) = @_;
838 my @path = ();
839 my $steps;
840  
841 my $x_dis = $x_end - $x_start;
842 my $y_dis = $y_end - $y_start;
843 my $z_dis = $z_end - $z_start;
844  
845 unless(defined($frame_pattern)) {
846 $frame_pattern = [ 0 ];
847 }
848  
849 # default path length if none specified
850 unless(defined($steps_req)) {
851 $steps_req = 'shortest';
852 }
853  
854 if($steps_req eq 'shortest' or $steps_req eq 'longest') {
855 if($x_dis == $y_dis) { $steps = $y_dis; }
856 elsif($x_dis == 0) { $steps = $y_dis; }
857 elsif($y_dis == 0) { $steps = $x_dis; }
858 elsif(abs($x_dis) < abs($y_dis)) {
859 if($steps_req eq 'shortest') { $steps = $x_dis; }
860 else { $steps = $y_dis; }
861 } else {
862 if($steps_req eq 'shortest') { $steps = $y_dis; }
863 else { $steps = $x_dis; }
864 }
865 }
866 elsif($steps_req =~ /^\d+$/) { $steps = $steps_req; }
867 elsif(uc($steps_req) eq 'X') { $steps = $x_dis; }
868 elsif(uc($steps_req) eq 'Y') { $steps = $y_dis; }
869 elsif(uc($steps_req) eq 'Z') { $steps = $z_dis; }
870 else {
871 carp("Unknown path length method: $steps_req"); return();
872 }
873  
874 $steps = abs($steps);
875  
876 if($steps == 0) { carp("Cannot create a zero length path!"); return (); }
877 elsif($steps == 1) {
878 # a path length of one is a special case where we just move from the origin to the destination
879 $path[0] = [($x_end - $x_start), ($y_end - $y_start), ($z_end - $z_start), $frame_pattern->[0]];
880 return \@path;
881 }
882  
883 my $x_incr = $x_dis / $steps;
884 my $y_incr = $y_dis / $steps;
885 my $z_incr = $z_dis / $steps;
886  
887 my ($x_pos, $y_pos, $z_pos) = ($x_start, $y_start, $z_start);
888 my ($x_act, $y_act, $z_act) = ($x_start, $y_start, $z_start);
889  
890 for(0..$steps-2) {
891 my ($x_prev, $y_prev, $z_prev) = ($x_pos, $y_pos, $z_pos);
892  
893 $x_pos+=$x_incr; $y_pos+=$y_incr; $z_pos+=$z_incr;
894 my $f_pos = $frame_pattern->[${_}%($#{$frame_pattern}+1)];
895  
896 my ($x_mov, $y_mov, $z_mov) = (int($x_pos) - int($x_prev), int($y_pos) - int($y_prev), int($z_pos) - int($z_prev));
897 $x_act += $x_mov; $y_act += $y_mov; $z_act += $z_mov;
898  
899 $path[$_] = [$x_mov, $y_mov, $z_mov, $f_pos];
900 }
901  
902 # through rounding errors, we might end up with a final position that is off by one from
903 # what we actually wanted. ending up in the right place is the most important thing,
904 # so we just set the final position to put us where we want to be
905 $path[$steps-1] = [$x_end - $x_act, $y_end - $y_act, $z_end - $z_act, $frame_pattern->[($steps - 1)%($#{$frame_pattern}+1)]];
906  
907 return \@path;
908 }
909  
910  
911 # run the callback routines for all entities that have them, and update
912 # the entity accordingly. also checks for auto death status
913 sub _do_callbacks {
914 my ($self) = @_;
915  
916 foreach my $entity (keys %{$self->{ENTITIES}}) {
917 my $ent = $self->{ENTITIES}{$entity};
918
919 # check for methods to automatically die
920 if(defined($ent->{'DIE_TIME'}) and $ent->{'DIE_TIME'} <= time()) {
921 del_entity($self, $entity); next;
922 }
923  
924 if(defined($ent->{'DIE_FRAME'}) and ($ent->{'DIE_FRAME'}--) <= 0) {
925 del_entity($self, $entity); next;
926 }
927  
928 if(defined($ent->{'DIE_ENTITY'}) and !$self->is_living($ent->{'DIE_ENTITY'}) ) {
929 del_entity($self, $entity); next;
930 }
931  
932 if($ent->{'DIE_OFFSCREEN'}) {
933 if($ent->{X} >= $self->{WIDTH} or $ent->{Y} >= $self->{HEIGHT} or
934 $ent->{X} < (0 - $ent->{WIDTH}) or $ent->{Y} < (0 - $ent->{HEIGHT})) {
935 del_entity($self, $entity); next;
936 }
937 }
938  
939 if(defined($ent->{CALLBACK})) {
940 my ($x, $y, $z, $f) = $ent->{CALLBACK}->($ent, $self);
941 if(defined($x)) {
942 if($ent->{WRAP}) {
943 if($x >= $self->{WIDTH}) { $x = ($x - int($x)) + ($x % $self->{WIDTH}); }
944 elsif($x < 0) { $x = ($x - int($x)) + ($x % $self->{WIDTH}); }
945 }
946 $ent->{X} = $x;
947 }
948 if(defined($y)) {
949 if($ent->{WRAP}) {
950 if($y >= $self->{HEIGHT}) { $y = ($y - int($y)) + ($y % $self->{HEIGHT}); }
951 elsif($y < 0) { $y = ($y - int($y)) + ($y % $self->{HEIGHT}); }
952 }
953 $ent->{Y} = $y;
954 }
955 $ent->{Z} = defined($z) ? $z : $ent->{Z};
956 $ent->{CURR_FRAME} = defined($f) ? $f : $ent->{CURR_FRAME};
957
958 }
959 }
960 }
961  
962 # called after all other updates. moves any entities that
963 # follow another entity
964 sub _move_followers {
965 my ($self) = @_;
966  
967 foreach my $entity_name (keys %{$self->{ENTITIES}}) {
968 my $follower = $self->{ENTITIES}{$entity_name};
969  
970 next unless(defined($follower->{FOLLOW_ENTITY}));
971  
972 my $leader = $self->entity($follower->{FOLLOW_ENTITY});
973 next unless(defined($leader));
974 my $offset = $follower->{FOLLOW_OFFSET};
975  
976 if(defined($offset->[0])) { $follower->x( $offset->[0] + $leader->x ); }
977 if(defined($offset->[1])) { $follower->y( $offset->[1] + $leader->y ); }
978 if(defined($offset->[2])) { $follower->z( $offset->[2] + $leader->z ); }
979 if(defined($offset->[3])) { $follower->frame( $offset->[3] + $leader->frame ); }
980 }
981 }
982  
983 sub _collision_handlers {
984 my ($self) = @_;
985 foreach my $entity (values %{$self->{ENTITIES}}) {
986 if(defined($entity->{COLL_HANDLER}) && defined($entity->{COLLISIONS})) {
987 $entity->{COLL_HANDLER}->($entity, $self);
988 }
989 $entity->{COLLISIONS} = ();
990 }
991 }
992  
993 =item I<end>
994  
995 $anim->end();
996  
997 Run the Curses endwin function to get your terminal back to its
998 normal mode. This is called automatically when the object is
999 destroyed if the animation is running full screen (if you
1000 did not pass an existing Curses window to the constructor).
1001  
1002 =cut
1003 sub end {
1004 my ($self) = @_;
1005 endwin;
1006 }
1007  
1008 # write to a log file, for debugging
1009 sub _elog {
1010 my ($mesg) = @_;
1011 open(F, ">>", "elog.log");
1012 print F "$mesg\n";
1013 close(F);
1014 }
1015  
1016 1;
1017  
1018 =back
1019  
1020 =head1 CALLBACK ROUTINES
1021  
1022 Callback routines for all entities are called each time I<animate>
1023 is called. A default callback routine is supplied, I<move_entity>, which
1024 is sufficient for most basic movement. If you want to create an entity
1025 that exhibits more complex behavior, you will have to write a custom
1026 callback routine for it.
1027  
1028 Callback routines take two arguments, a reference to the Term::Animation::Entity
1029 object that it should act on, and a reference to the Term::Animation instance
1030 that called it. Any arguments required to tell the callback what to do with
1031 the object, or any state that needs to be maintained, should be put
1032 in the I<callback_args> element of the object. I<callback_args> is only
1033 referenced by the callback routine, and thus can contain any datastructure
1034 that you find useful.
1035  
1036 Here is an example custom callback that will make an entity move randomly
1037 around the screen:
1038  
1039 sub random_movement {
1040 my ($entity, $anim) = @_;
1041  
1042 # get the current position of the entity
1043 my ($x, $y, $z) = $entity->position();
1044  
1045 # we'll use callback_args to store the last axis we moved in
1046 my $last_move = $entity->callback_args();
1047  
1048 # if we moved in x last time, move in y this time
1049 if($last_move eq 'x') {
1050 $entity->callback_args('y');
1051 # move by -1, 0 or 1
1052 $y += int(rand(3)) - 1;
1053 } else {
1054 $entity->callback_args('x');
1055 $x += int(rand(3)) - 1;
1056 }
1057  
1058 # return the absolute x,y,z coordinates to move to
1059 return ($x, $y, $z);
1060 }
1061  
1062 The return value of your callback routine should be of the form:
1063  
1064 return ($x, $y, $z, $frame)
1065  
1066 $x, $y and $z represent the X, Y and Z coordinates to which the object
1067 should move. $frame is the frame number that the object should display,
1068 if it has multiple frames of animation. Any values that are unspecified
1069 or undef will remain unchanged.
1070  
1071 You can also call the default callback from within your callback, if
1072 you want it to handle movement for you. For example, if your callback
1073 is simply used to decide when an entity should die:
1074  
1075 sub wait_for_file {
1076 my ($entity, $anim) = @_;
1077  
1078 # kill this entity if a certain file shows up
1079 if(-e "/path/to/file") {
1080 $entity->kill();
1081 return();
1082 }
1083  
1084 # use the default callback to handle the actual movement
1085 return $entity->move_entity($anim);
1086 }
1087  
1088 If you use this, be aware that I<move_entity> relies on
1089 I<callback_args>, so you cannot use it to store your own
1090 arbitrary data.
1091  
1092 =head1 COLOR
1093  
1094 ANSI color is available for terminals that support it. Only a single
1095 background color can be used for the window (it would look terrible
1096 in most cases otherwise anyway). Colors for entities are specified by
1097 using a 'mask' that indicates the color for each character. For
1098 example, say we had a single frame of a bird:
1099  
1100 $bird = q#
1101  
1102 ---. .-. .---
1103 --\'v'/--
1104 \ /
1105 " "
1106 #;
1107  
1108 To indicate the colors you want to use for the bird, create a matching
1109 mask, with the first letter of each color in the appropriate position
1110 (except black, which is 'k'). Pass this mask as the I<color> parameter.
1111  
1112 $mask = q#
1113  
1114 BBBB BBB BBBB
1115 BBBWYWBBB
1116 B B
1117 Y Y
1118 #;
1119  
1120 When specifying a color, using uppercase indicates the color should be
1121 bold. So 'BLUE' or 'B' means bold blue, and 'blue' or 'b' means non-bold
1122 blue. 'Blue' means you get an error message.
1123  
1124 You can also provide a default color with the default_color parameter.
1125 This color will be used for any character that does
1126 not have an entry in the mask. If you want the entire entity to be
1127 a single color, you can just provide a default color with no mask.
1128  
1129 The available colors are: red, green, blue, cyan, magenta, yellow, black
1130 and white.
1131  
1132 Here's an example call to build_object for the bird above.
1133  
1134 $anim->new_entity (
1135 name => "Bird",
1136 shape => $bird,
1137 position => [ 5, 8, 7 ],
1138 callback_args => [ 1, 2, 0, 0 ],
1139 color => $mask,
1140 default_color => "BLUE"
1141 );
1142  
1143 =head1 AUTHOR
1144  
1145 Kirk Baucom, E<lt>kbaucom@schizoid.comE<gt>
1146  
1147 =head1 SEE ALSO
1148  
1149 L<Curses|Curses>
1150  
1151 =cut
« Animation/Entity.pm ↑ Summary