.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Term::Animation::Entity 3"
.TH Term::Animation::Entity 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Term::Animation::Entity
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Term::Animation::Entity;
\&
\&  # Constructor
\&  my $entity = Term::Animation::Entity\->new(
\&      shape         => \*(Aq;\-)\*(Aq,
\&      position      => [ 1, 2, 3 ],
\&      callback_args => [ 0, 1, 0, 0 ],
\&  );
.Ve
.SH ABSTRACT
.IX Header "ABSTRACT"
A sprite object for use with Term::Animation
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Term::Animation::Entity is used by Term::Animation to
represent a single sprite on the screen.
.SH PARAMETERS
.IX Header "PARAMETERS"
.Vb 2
\&  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 \*(Aqshape\*(Aq.
\&        See the \*(AqCOLOR\*(Aq section below for more details.
\&
\&  default_color < SCALAR >
\&        A default color to use for the entity.  See the \*(AqCOLOR\*(Aq 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.
.Ve
.SH METHODS
.IX Header "METHODS"
.IP \fInew\fR 4
.IX Item "new"
.Vb 5
\&  my $entity = Term::Animation::Entity\->new(
\&      shape         => \*(Aq;\-)\*(Aq,
\&      position      => [ 1, 2, 3 ],
\&      callback_args => [ 0, 1, 0, 0 ],
\&  );
.Ve
.Sp
Create a Term::Animation::Entity instance. See the PARAMETERS section for
details.
.IP \fIphysical\fR 4
.IX Item "physical"
.Vb 2
\&  $entity\->physical( 1 );
\&  $state = $entity\->physical();
.Ve
.Sp
Enables or disabled collision detection for this entity.
.IP \fIauto_trans\fR 4
.IX Item "auto_trans"
.Vb 2
\&  $entity\->auto_trans( 1 );
\&  $state = $entity\->auto_trans();
.Ve
.Sp
Enables or disables automatic transparency for this entity's sprite.
This will only affect subsequent calls to \fIshape\fR, the current sprite
will be unchanged.
.IP \fItransparent\fR 4
.IX Item "transparent"
.Vb 2
\&  $entity\->transparent( \*(Aq*\*(Aq );
\&  $trans_char = $entity\->transparent();
.Ve
.Sp
Gets or sets the transparent character for this entity's sprite.
This will only affect subsequent calls to \fIshape\fR, the current
sprite will be unchanged.
.IP \fIwrap\fR 4
.IX Item "wrap"
.Vb 2
\&  $entity\->wrap( 1 );
\&  $wrap = $entity\->wrap;
.Ve
.Sp
Gets or sets the boolean that indicates whether this entity
should wrap around when it gets to an edge of the screen.
.IP \fIdata\fR 4
.IX Item "data"
.Vb 2
\&  $entity\->data( $stuff );
\&  $data = $entity\->data();
.Ve
.Sp
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.
.IP \fIname\fR 4
.IX Item "name"
.Vb 1
\&  $name = $entity\->name();
.Ve
.Sp
Returns the name of the entity.
.IP \fItype\fR 4
.IX Item "type"
.Vb 2
\&  $entity\->type( \*(Aqthis_type\*(Aq );
\&  $type = $entity\->type();
.Ve
.Sp
Get or set the 'type' of the entity. The type can be any string,
and is not used by the animation itself.
.IP \fIframe\fR 4
.IX Item "frame"
.Vb 2
\&  $entity\->frame( 3 );
\&  $current_frame = $entity\->frame();
.Ve
.Sp
Gets or sets the current animation frame of the entity.
.IP \fIwidth\fR 4
.IX Item "width"
.Vb 1
\&  my $width = $entity\->width();
.Ve
.Sp
Returns the width (columns) of the entity.
.IP \fIheight\fR 4
.IX Item "height"
.Vb 1
\&  my $height = $entity\->height();
.Ve
.Sp
Returns the height (rows) of the entity.
.IP \fIdepth\fR 4
.IX Item "depth"
.Vb 1
\&  my $depth = $entity\->depth();
.Ve
.Sp
Returns the depth of the entity.
.IP \fIsize\fR 4
.IX Item "size"
.Vb 1
\&  my ($width, $height, $depth) = $entity\->size();
.Ve
.Sp
Returns the X / Y / Z dimensions of the entity.
.IP \fIposition\fR 4
.IX Item "position"
.Vb 2
\&  my ($x, $y, $z) = $entity\->position();
\&  $entity\->position($x, $y, $z);
.Ve
.Sp
Gets or sets the X / Y / Z coordinates of the entity. You can also
access each coordinate individually.
.Sp
.Vb 2
\&  my $x = $entity\->x;
\&  $entity\->x(5);
.Ve
.Sp
Note that you should normally position an entity using its callback routine,
instead of calling one of these methods.
.IP \fIcallback_args\fR 4
.IX Item "callback_args"
.Vb 2
\&  $entity\->callback_args( $args );
\&  $args = $entity\->callback_args();
.Ve
.Sp
Get or set the arguments to the entity's callback routine. This
should be either a single scalar or a single ref.
.IP \fIcallback\fR 4
.IX Item "callback"
.Vb 2
\&  $entity\->callback( \e&callback_routine );
\&  $callback_routine = $entity\->callback();
.Ve
.Sp
Get or set the callback routine for the entity
.IP \fIdeath_cb\fR 4
.IX Item "death_cb"
.Vb 2
\&  $entity\->death_cb( \e&death_callback_routine );
\&  $death_callback_routine = $entity\->death_cb();
.Ve
.Sp
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.
.IP \fIdie_offscreen\fR 4
.IX Item "die_offscreen"
.Vb 2
\&  $entity\->die_offscreen( 1 );
\&  $die_offscreen = $entity\->die_offscreen;
.Ve
.Sp
Get or set the flag that indicates whether this
entity should die when it is entirely off the screen.
.IP \fIdie_frame\fR 4
.IX Item "die_frame"
.Vb 2
\&  $entity\->die_frame( 1 );
\&  $die_frame = $entity\->die_frame;
.Ve
.Sp
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.
.IP \fIdie_time\fR 4
.IX Item "die_time"
.Vb 2
\&  $entity\->die_time( time() + 20 );
\&  $die_time = $entity\->die_time;
.Ve
.Sp
Get or set the time at which this entity should die.
The time is a UNIX epoch time. Set to undef to disable.
.IP \fIdie_entity\fR 4
.IX Item "die_entity"
.Vb 2
\&  $entity\->die_entity( $other_entity );
\&  $other_entity = $entity\->die_entity;
.Ve
.Sp
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.
.IP \fIshape\fR 4
.IX Item "shape"
.Vb 1
\&  $entity\->shape($new_shape);
.Ve
.Sp
Set the sprite image for the entity. See the \f(CW\*(C`shape\*(C'\fR argument
to \fInew\fR for details.
.IP \fIcollisions\fR 4
.IX Item "collisions"
.Vb 1
\&  $collisions = $entity\->collisions();
.Ve
.Sp
Returns a reference to a list of entities that this entity
collided with during this animation cycle.
.IP \fIanimation\fR 4
.IX Item "animation"
.Vb 2
\&  $entity\->animation( $anim );
\&  $anim = $entity\->animation();
.Ve
.Sp
Get or set the Term::Animation object that this entity is
part of.
.IP \fIdefault_color\fR 4
.IX Item "default_color"
.Vb 2
\&  $entity\->default_color( \*(Aqblue\*(Aq );
\&  $def_color = $entity\->default_color();
.Ve
.Sp
Get or set the default color for the entity. The color can
be either a single character or the full name of the color.
.IP \fIcolor_mask\fR 4
.IX Item "color_mask"
.Vb 1
\&  $entity\->color_mask( $mask );
.Ve
.Sp
Set the color mask for the entity. See the Term::Animation/COLOR section of
Term::Animation for details.
.IP \fImove_entity\fR 4
.IX Item "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.
.Sp
.Vb 2
\&  sub my_callback {
\&    my ($entity, $animation) = @_;
\&    
\&    # do something here
\&    
\&    return $entity\->move_object($animation);
\&
\&  }
.Ve
.IP \fIkill\fR 4
.IX Item "kill"
.Vb 1
\&  $entity\->kill();
.Ve
.Sp
Remove this entity from the animation. This is equivilent
to:
.Sp
.Vb 1
\&  $animation\->del_entity($entity);
.Ve
.Sp
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.
.SH AUTHOR
.IX Header "AUTHOR"
Kirk Baucom <kbaucom@schizoid.com>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Term::Animation
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 622:" 4
.IX Item "Around line 622:"
alternative text 'Term::Animation/COLOR' contains non-escaped | or /