Term::Animation::Entity(3)                 User Contributed Perl Documentation


NAME
       Term::Animation::Entity

SYNOPSIS
         use Term::Animation::Entity;

         # Constructor
         my $entity = Term::Animation::Entity->new(
             shape         => ';-)',
             position      => [ 1, 2, 3 ],
             callback_args => [ 0, 1, 0, 0 ],
         );

ABSTRACT
       A sprite object for use with Term::Animation

DESCRIPTION
       Term::Animation::Entity is used by Term::Animation to represent a
       single sprite on the screen.

PARAMETERS
         name < SCALAR >
               A string uniquely identifying this object

         shape < REF >
               The ASCII art for this object. It can be provided as:
                         1) A single multi-line text string (no animation)
                         2) An array of multi-line text strings, where each
                            element is a single animation frame
                         3) An array of 2D arrays. Each element in the outer
                            array is a single animation frame.
               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. 3) is what the module uses internally.

         auto_trans < BOOLEAN >
               Whether to automatically make whitespace at the beginning of each line
               transparent.  Default: 0

         position < ARRAY_REF >
               A list specifying initial x,y and z coordinates
               Default: [ 0, 0, 0 ]

         callback < SUBROUTINE_REF >
               Callback routine for this entity. Default: I<move_entity()>

         callback_args < REF >
               Arguments to the callback routine.

         curr_frame < INTEGER >
               Animation frame to begin with. Default: 0

         wrap < BOOLEAN >
               Whether this entity should wrap around the edge of the screen. Default: 0

         transparent < SCALAR >
               Character used to indicate transparency. Default: ?

         die_offscreen < BOOLEAN >
               Whether this entity should be killed if
               it goes off the screen. Default: 0

         die_entity < ENTITY >
               Specifies an entity (ref or name). When the named
               entity dies, this entity should die as well. Default: undef

         die_time < INTEGER >
               The time at which this entity should be killed. This
               should be a UNIX epoch time, as returned
               by I<time>.  Default: undef

         die_frame < INTEGER >
               Specifies the number of frames that should be displayed
               before this entity is killed. Default: undef

         death_cb < SUBROUTINE_REF >
               Callback routine used when this entity dies

         dcb_args < REF >
               Arguments to the entity death callback routine

         color
               Color mask. This follows the same format as 'shape'.
               See the 'COLOR' section below for more details.

         default_color < SCALAR >
               A default color to use for the entity.  See the 'COLOR' section
               for more details.

         data < REF >
               Store some data about this entity. It is not used by the module.
               You can use it to store state information about this entity.

METHODS
       new
             my $entity = Term::Animation::Entity->new(
                 shape         => ';-)',
                 position      => [ 1, 2, 3 ],
                 callback_args => [ 0, 1, 0, 0 ],
             );

           Create a Term::Animation::Entity instance. See the PARAMETERS
           section for details.

       physical
             $entity->physical( 1 );
             $state = $entity->physical();

           Enables or disabled collision detection for this entity.

       auto_trans
             $entity->auto_trans( 1 );
             $state = $entity->auto_trans();

           Enables or disables automatic transparency for this entity's
           sprite.  This will only affect subsequent calls to shape, the
           current sprite will be unchanged.

       transparent
             $entity->transparent( '*' );
             $trans_char = $entity->transparent();

           Gets or sets the transparent character for this entity's sprite.
           This will only affect subsequent calls to shape, the current sprite
           will be unchanged.

       wrap
             $entity->wrap( 1 );
             $wrap = $entity->wrap;

           Gets or sets the boolean that indicates whether this entity should
           wrap around when it gets to an edge of the screen.

       data
             $entity->data( $stuff );
             $data = $entity->data();

           Get or set the 'data' associated with the entity. It should be a
           single scalar or ref. This can be whatever you want, it is not used
           by the module and is provided for convenience.

       name
             $name = $entity->name();

           Returns the name of the entity.

       type
             $entity->type( 'this_type' );
             $type = $entity->type();

           Get or set the 'type' of the entity. The type can be any string,
           and is not used by the animation itself.

       frame
             $entity->frame( 3 );
             $current_frame = $entity->frame();

           Gets or sets the current animation frame of the entity.

       width
             my $width = $entity->width();

           Returns the width (columns) of the entity.

       height
             my $height = $entity->height();

           Returns the height (rows) of the entity.

       depth
             my $depth = $entity->depth();

           Returns the depth of the entity.

       size
             my ($width, $height, $depth) = $entity->size();

           Returns the X / Y / Z dimensions of the entity.

       position
             my ($x, $y, $z) = $entity->position();
             $entity->position($x, $y, $z);

           Gets or sets the X / Y / Z coordinates of the entity. You can also
           access each coordinate individually.

             my $x = $entity->x;
             $entity->x(5);

           Note that you should normally position an entity using its callback
           routine, instead of calling one of these methods.

       callback_args
             $entity->callback_args( $args );
             $args = $entity->callback_args();

           Get or set the arguments to the entity's callback routine. This
           should be either a single scalar or a single ref.

       callback
             $entity->callback( \&callback_routine );
             $callback_routine = $entity->callback();

           Get or set the callback routine for the entity

       death_cb
             $entity->death_cb( \&death_callback_routine );
             $death_callback_routine = $entity->death_cb();

           Get or set the callback routine that is called when the entity
           dies. Set to undef if you do not want anything to be called.

       die_offscreen
             $entity->die_offscreen( 1 );
             $die_offscreen = $entity->die_offscreen;

           Get or set the flag that indicates whether this entity should die
           when it is entirely off the screen.

       die_frame
             $entity->die_frame( 1 );
             $die_frame = $entity->die_frame;

           Get or set the frame number in which this entity should die,
           counting from the time when die_frame is called. Set to undef to
           disable.

       die_time
             $entity->die_time( time() + 20 );
             $die_time = $entity->die_time;

           Get or set the time at which this entity should die.  The time is a
           UNIX epoch time. Set to undef to disable.

       die_entity
             $entity->die_entity( $other_entity );
             $other_entity = $entity->die_entity;

           Get or set an entity whose death will cause the death of this
           entity. Either an entity name or Term::Animation::Entity reference
           are accepted, but an entity name is always returned. Set to undef
           to disable.

       shape
             $entity->shape($new_shape);

           Set the sprite image for the entity. See the "shape" argument to
           new for details.

       collisions
             $collisions = $entity->collisions();

           Returns a reference to a list of entities that this entity collided
           with during this animation cycle.

       animation
             $entity->animation( $anim );
             $anim = $entity->animation();

           Get or set the Term::Animation object that this entity is part of.

       default_color
             $entity->default_color( 'blue' );
             $def_color = $entity->default_color();

           Get or set the default color for the entity. The color can be
           either a single character or the full name of the color.

       color_mask
             $entity->color_mask( $mask );

           Set the color mask for the entity. See the Term::Animation/COLOR
           section of Term::Animation for details.

       move_entity
           The default callback. You can also call this from your own callback
           to do the work of moving and animating the entity after you have
           done whatever other processing you want to do.

             sub my_callback {
               my ($entity, $animation) = @_;

               # do something here

               return $entity->move_object($animation);

             }

       kill
             $entity->kill();

           Remove this entity from the animation. This is equivilent to:

             $animation->del_entity($entity);

           This does not destroy the object, so you can still readd it later
           (or put it in a different animation) as long as you have a
           reference to it.

AUTHOR
       Kirk Baucom <kbaucom@schizoid.com>

SEE ALSO
       Term::Animation

POD ERRORS
       Hey! The above document had some coding errors, which are explained
       below:

       Around line 622:
           alternative text 'Term::Animation/COLOR' contains non-escaped | or
           /

perl v5.40.0                      2024-09-01        Term::Animation::Entity(3)