1Term::Animation::EntityU(s3e)r Contributed Perl DocumentaTteiromn::Animation::Entity(3)
2
6 Term::Animation::Entity
7
9 use Term::Animation::Entity;
10 # Constructor
12 my $entity = Term::Animation::Entity->new(
13 shape => ';-)',
14 position => [ 1, 2, 3 ],
15 callback_args => [ 0, 1, 0, 0 ],
16 );
17
19 A sprite object for use with Term::Animation
20
22 Term::Animation::Entity is used by Term::Animation to represent a
23 single sprite on the screen.
24
26 name < SCALAR >
27 A string uniquely identifying this object
28 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 auto_trans < BOOLEAN >
41 Whether to automatically make whitespace at the beginning of each line
42 transparent. Default: 0
43 position < ARRAY_REF >
45 A list specifying initial x,y and z coordinates
46 Default: [ 0, 0, 0 ]
47 callback < SUBROUTINE_REF >
49 Callback routine for this entity. Default: I<move_entity()>
50 callback_args < REF >
52 Arguments to the callback routine.
53 curr_frame < INTEGER >
55 Animation frame to begin with. Default: 0
56 wrap < BOOLEAN >
58 Whether this entity should wrap around the edge of the screen. Default: 0
59 transparent < SCALAR >
61 Character used to indicate transparency. Default: ?
62 die_offscreen < BOOLEAN >
64 Whether this entity should be killed if
65 it goes off the screen. Default: 0
66 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 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 die_frame < INTEGER >
77 Specifies the number of frames that should be displayed
78 before this entity is killed. Default: undef
79 death_cb < SUBROUTINE_REF >
81 Callback routine used when this entity dies
82 dcb_args < REF >
84 Arguments to the entity death callback routine
85 color
87 Color mask. This follows the same format as 'shape'.
88 See the 'COLOR' section below for more details.
89 default_color < SCALAR >
91 A default color to use for the entity. See the 'COLOR' section
92 for more details.
93 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
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 Create a Term::Animation::Entity instance. See the PARAMETERS
107 section for details.
108 physical
110 $entity->physical( 1 );
111 $state = $entity->physical();
112 Enables or disabled collision detection for this entity.
114 auto_trans
116 $entity->auto_trans( 1 );
117 $state = $entity->auto_trans();
118 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 transparent
124 $entity->transparent( '*' );
125 $trans_char = $entity->transparent();
126 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 wrap
132 $entity->wrap( 1 );
133 $wrap = $entity->wrap;
134 Gets or sets the boolean that indicates whether this entity should
136 wrap around when it gets to an edge of the screen.
137 data
139 $entity->data( $stuff );
140 $data = $entity->data();
141 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 name
147 $name = $entity->name();
148 Returns the name of the entity.
150 type
152 $entity->type( 'this_type' );
153 $type = $entity->type();
154 Get or set the 'type' of the entity. The type can be any string,
156 and is not used by the animation itself.
157 frame
159 $entity->frame( 3 );
160 $current_frame = $entity->frame();
161 Gets or sets the current animation frame of the entity.
163 width
165 my $width = $entity->width();
166 Returns the width (columns) of the entity.
168 height
170 my $height = $entity->height();
171 Returns the height (rows) of the entity.
173 depth
175 my $depth = $entity->depth();
176 Returns the depth of the entity.
178 size
180 my ($width, $height, $depth) = $entity->size();
181 Returns the X / Y / Z dimensions of the entity.
183 position
185 my ($x, $y, $z) = $entity->position();
186 $entity->position($x, $y, $z);
187 Gets or sets the X / Y / Z coordinates of the entity. You can also
189 access each coordinate individually.
190 my $x = $entity->x;
192 $entity->x(5);
193 Note that you should normally position an entity using its callback
195 routine, instead of calling one of these methods.
196 callback_args
198 $entity->callback_args( $args );
199 $args = $entity->callback_args();
200 Get or set the arguments to the entity's callback routine. This
202 should be either a single scalar or a single ref.
203 callback
205 $entity->callback( \&callback_routine );
206 $callback_routine = $entity->callback();
207 Get or set the callback routine for the entity
209 death_cb
211 $entity->death_cb( \&death_callback_routine );
212 $death_callback_routine = $entity->death_cb();
213 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 die_offscreen
218 $entity->die_offscreen( 1 );
219 $die_offscreen = $entity->die_offscreen;
220 Get or set the flag that indicates whether this entity should die
222 when it is entirely off the screen.
223 die_frame
225 $entity->die_frame( 1 );
226 $die_frame = $entity->die_frame;
227 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 die_time
233 $entity->die_time( time() + 20 );
234 $die_time = $entity->die_time;
235 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 die_entity
240 $entity->die_entity( $other_entity );
241 $other_entity = $entity->die_entity;
242 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 shape
249 $entity->shape($new_shape);
250 Set the sprite image for the entity. See the "shape" argument to
252 new for details.
253 collisions
255 $collisions = $entity->collisions();
256 Returns a reference to a list of entities that this entity collided
258 with during this animation cycle.
259 animation
261 $entity->animation( $anim );
262 $anim = $entity->animation();
263 Get or set the Term::Animation object that this entity is part of.
265 default_color
267 $entity->default_color( 'blue' );
268 $def_color = $entity->default_color();
269 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 color_mask
274 $entity->color_mask( $mask );
275 Set the color mask for the entity. See the Term::Animation/COLOR
277 section of Term::Animation for details.
278 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 sub my_callback {
285 my ($entity, $animation) = @_;
286 # do something here
288 return $entity->move_object($animation);
290 }
292 kill
294 $entity->kill();
295 Remove this entity from the animation. This is equivilent to:
297 $animation->del_entity($entity);
299 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
305 Kirk Baucom <kbaucom@schizoid.com>
306
308 Term::Animation
309
311 Hey! The above document had some coding errors, which are explained
312 below:
313 Around line 622:
315 alternative text 'Term::Animation/COLOR' contains non-escaped | or
316 /
317perl v5.28.0 2011-03-26 Term::Animation::Entity(3)