Term::Animation::Entity(3pm)

1Term::Animation::EntityU(s3e)r Contributed Perl DocumentaTteiromn::Animation::Entity(3)
2
3
4

NAME

6       Term::Animation::Entity
7

SYNOPSIS

9         use Term::Animation::Entity;
10
11         # Constructor
12         my $entity = Term::Animation::Entity->new(
13             shape         => ';-)',
14             position      => [ 1, 2, 3 ],
15             callback_args => [ 0, 1, 0, 0 ],
16         );
17

ABSTRACT

19       A sprite object for use with Term::Animation
20

DESCRIPTION

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

PARAMETERS

26         name < SCALAR >
27               A string uniquely identifying this object
28
29         shape < REF >
30               The ASCII art for this object. It can be provided as:
31                         1) A single multi-line text string (no animation)
32                         2) An array of multi-line text strings, where each
33                            element is a single animation frame
34                         3) An array of 2D arrays. Each element in the outer
35                            array is a single animation frame.
36               If you provide an array, each element is a single frame of animation.
37               If you provide either 1) or 2), a single newline will be stripped off
38               of the beginning of each string. 3) is what the module uses internally.
39
40         auto_trans < BOOLEAN >
41               Whether to automatically make whitespace at the beginning of each line
42               transparent.  Default: 0
43
44         position < ARRAY_REF >
45               A list specifying initial x,y and z coordinates
46               Default: [ 0, 0, 0 ]
47
48         callback < SUBROUTINE_REF >
49               Callback routine for this entity. Default: I<move_entity()>
50
51         callback_args < REF >
52               Arguments to the callback routine.
53
54         curr_frame < INTEGER >
55               Animation frame to begin with. Default: 0
56
57         wrap < BOOLEAN >
58               Whether this entity should wrap around the edge of the screen. Default: 0
59
60         transparent < SCALAR >
61               Character used to indicate transparency. Default: ?
62
63         die_offscreen < BOOLEAN >
64               Whether this entity should be killed if
65               it goes off the screen. Default: 0
66
67         die_entity < ENTITY >
68               Specifies an entity (ref or name). When the named
69               entity dies, this entity should die as well. Default: undef
70
71         die_time < INTEGER >
72               The time at which this entity should be killed. This
73               should be a UNIX epoch time, as returned
74               by I<time>.  Default: undef
75
76         die_frame < INTEGER >
77               Specifies the number of frames that should be displayed
78               before this entity is killed. Default: undef
79
80         death_cb < SUBROUTINE_REF >
81               Callback routine used when this entity dies
82
83         dcb_args < REF >
84               Arguments to the entity death callback routine
85
86         color
87               Color mask. This follows the same format as 'shape'.
88               See the 'COLOR' section below for more details.
89
90         default_color < SCALAR >
91               A default color to use for the entity.  See the 'COLOR' section
92               for more details.
93
94         data < REF >
95               Store some data about this entity. It is not used by the module.
96               You can use it to store state information about this entity.
97

METHODS

99       new
100             my $entity = Term::Animation::Entity->new(
101                 shape         => ';-)',
102                 position      => [ 1, 2, 3 ],
103                 callback_args => [ 0, 1, 0, 0 ],
104             );
105
106           Create a Term::Animation::Entity instance. See the PARAMETERS
107           section for details.
108
109       physical
110             $entity->physical( 1 );
111             $state = $entity->physical();
112
113           Enables or disabled collision detection for this entity.
114
115       auto_trans
116             $entity->auto_trans( 1 );
117             $state = $entity->auto_trans();
118
119           Enables or disables automatic transparency for this entity's
120           sprite.  This will only affect subsequent calls to shape, the
121           current sprite will be unchanged.
122
123       transparent
124             $entity->transparent( '*' );
125             $trans_char = $entity->transparent();
126
127           Gets or sets the transparent character for this entity's sprite.
128           This will only affect subsequent calls to shape, the current sprite
129           will be unchanged.
130
131       wrap
132             $entity->wrap( 1 );
133             $wrap = $entity->wrap;
134
135           Gets or sets the boolean that indicates whether this entity should
136           wrap around when it gets to an edge of the screen.
137
138       data
139             $entity->data( $stuff );
140             $data = $entity->data();
141
142           Get or set the 'data' associated with the entity. It should be a
143           single scalar or ref. This can be whatever you want, it is not used
144           by the module and is provided for convenience.
145
146       name
147             $name = $entity->name();
148
149           Returns the name of the entity.
150
151       type
152             $entity->type( 'this_type' );
153             $type = $entity->type();
154
155           Get or set the 'type' of the entity. The type can be any string,
156           and is not used by the animation itself.
157
158       frame
159             $entity->frame( 3 );
160             $current_frame = $entity->frame();
161
162           Gets or sets the current animation frame of the entity.
163
164       width
165             my $width = $entity->width();
166
167           Returns the width (columns) of the entity.
168
169       height
170             my $height = $entity->height();
171
172           Returns the height (rows) of the entity.
173
174       depth
175             my $depth = $entity->depth();
176
177           Returns the depth of the entity.
178
179       size
180             my ($width, $height, $depth) = $entity->size();
181
182           Returns the X / Y / Z dimensions of the entity.
183
184       position
185             my ($x, $y, $z) = $entity->position();
186             $entity->position($x, $y, $z);
187
188           Gets or sets the X / Y / Z coordinates of the entity. You can also
189           access each coordinate individually.
190
191             my $x = $entity->x;
192             $entity->x(5);
193
194           Note that you should normally position an entity using its callback
195           routine, instead of calling one of these methods.
196
197       callback_args
198             $entity->callback_args( $args );
199             $args = $entity->callback_args();
200
201           Get or set the arguments to the entity's callback routine. This
202           should be either a single scalar or a single ref.
203
204       callback
205             $entity->callback( \&callback_routine );
206             $callback_routine = $entity->callback();
207
208           Get or set the callback routine for the entity
209
210       death_cb
211             $entity->death_cb( \&death_callback_routine );
212             $death_callback_routine = $entity->death_cb();
213
214           Get or set the callback routine that is called when the entity
215           dies. Set to undef if you do not want anything to be called.
216
217       die_offscreen
218             $entity->die_offscreen( 1 );
219             $die_offscreen = $entity->die_offscreen;
220
221           Get or set the flag that indicates whether this entity should die
222           when it is entirely off the screen.
223
224       die_frame
225             $entity->die_frame( 1 );
226             $die_frame = $entity->die_frame;
227
228           Get or set the frame number in which this entity should die,
229           counting from the time when die_frame is called. Set to undef to
230           disable.
231
232       die_time
233             $entity->die_time( time() + 20 );
234             $die_time = $entity->die_time;
235
236           Get or set the time at which this entity should die.  The time is a
237           UNIX epoch time. Set to undef to disable.
238
239       die_entity
240             $entity->die_entity( $other_entity );
241             $other_entity = $entity->die_entity;
242
243           Get or set an entity whose death will cause the death of this
244           entity. Either an entity name or Term::Animation::Entity reference
245           are accepted, but an entity name is always returned. Set to undef
246           to disable.
247
248       shape
249             $entity->shape($new_shape);
250
251           Set the sprite image for the entity. See the "shape" argument to
252           new for details.
253
254       collisions
255             $collisions = $entity->collisions();
256
257           Returns a reference to a list of entities that this entity collided
258           with during this animation cycle.
259
260       animation
261             $entity->animation( $anim );
262             $anim = $entity->animation();
263
264           Get or set the Term::Animation object that this entity is part of.
265
266       default_color
267             $entity->default_color( 'blue' );
268             $def_color = $entity->default_color();
269
270           Get or set the default color for the entity. The color can be
271           either a single character or the full name of the color.
272
273       color_mask
274             $entity->color_mask( $mask );
275
276           Set the color mask for the entity. See the COLOR section of
277           Term::Animation for details.
278
279       move_entity
280           The default callback. You can also call this from your own callback
281           to do the work of moving and animating the entity after you have
282           done whatever other processing you want to do.
283
284             sub my_callback {
285               my ($entity, $animation) = @_;
286
287               # do something here
288
289               return $entity->move_object($animation);
290
291             }
292
293       kill
294             $entity->kill();
295
296           Remove this entity from the animation. This is equivilent to:
297
298             $animation->del_entity($entity);
299
300           This does not destroy the object, so you can still readd it later
301           (or put it in a different animation) as long as you have a
302           reference to it.
303

AUTHOR

305       Kirk Baucom <kbaucom@schizoid.com>
306