1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
|
<xml>
<head>
<title>Sprites Resources</title>
</head>
<body>
<h3>Resource options</h3>
<p>The sprite resource options is a plethora of possibilities to tweak a sprites
looks and behaviours, but all of them have default values. In most
cases you will only need to use the basic options.</p>
<p>Each sprite <i>can</i> have the following properties:</p>
<pre>
<sprite
name="my_sprite"
description="resource_containing_shared_description_data"
pack_texture="[yes,no]"
base_angle="angle"
id="id">
<!-- Frame image loading: -->
<image file="filename" />
<image file="filename">
<grid
pos="x,y"
size="width,height"
array="tiles_x,tiles_y"
array_skipframes="skip_count"
spacing="width,height" />
</image>
<image file="filename">
<palette
pos="x,y" />
</image>
<image file="image4.png">
<alpha
pos="x,y"
free="true"
trans_limit="limit" />
</image>
<!-- Sprite render and animation states: -->
<color
red="red_component"
green="green_component"
blue="blue_component"
alpha="alpha_component" />
<animation
speed="speed"
loop="[yes,no]"
pingpong="[yes,no]"
direction="[backward,forward]
on_finish="[blank,last_frame,first_frame]" />
<scale x="scale_x" y="scale_y" />
<translation
origin="[top_left, top_center, top_right,
center_left, center, center_right,
bottom_left, bottom_center, bottom_right]"
x="offset_x"
y="offset_y" />
<rotation
origin="[top_left, top_center, top_right,
center_left, center, center_right,
bottom_left, bottom_center, bottom_right]"
x="offset_x"
y="offset_y" />
<frame
nr="frame_number"
speed="frame_delay"
x="offset_x"
y="offset_y" />
</sprite>
</pre>
<p>Only the <i>name</i> attribute of <sprite> and at least one <image>
element is required to construct a sprite. The remaining elements and
attributes are optional.</p>
<h3>Using the <image> element</h3>
<p>The first step in setting up a sprite is telling the resource loader
where it should get the images for all the frames. This is done specifying
one or more <image> elements. Each <image> element specify an image from
where one or several frames should be extracted:</p>
<ul>
<li>If there is no child element in <image>, it will simply take the entire
image and add it as one large frame.</li>
<li>If the child element is <grid> it will use the grid cutter in
CL_SpriteDescription to extract a set of frames placed in a grid in the
image file.</li>
<li>If the child is <alpha> the alpha cutter will be used instead. The alpha
cutter uses the alpha channel to find frames separated with pure alpha
(within trans_limit).</li>
<li>Then there is the <palette> child element. This method adds frames
separated with palette-colours defining the boundaries.</li>
</ul>
<p>If you have many sprites that are using the same frames for its
animation, you can use the <i>description</i> attribute on the
<sprite> element to use the frames from an other sprite resource.</p>
<h3>Setting up render and animation</h3>
<p>The remaining elements <color>, <animation>, <scale>,
<translation> and <rotation> alter the default values of the
CL_Sprite render and animation properties.</p>
<p><frame> sets up properties for a specific frame.</p>
<h3>Sprite resource options reference</h3>
<p><b><sprite></b></p>
<ul>
<li>Attribute <b>name</b>: Name of resource.
<p>
<i>Valid values</i>:<br>
<i>Default value</i>: None, MUST BE PRESENT.
</p>
</li>
<li>Attribute <b>description</b>: Resource identifier of other resource to
use as base for this sprite.
<p>
<i>Valid values</i>: "string" - Resource ID of other sprite resource<br>
<i>Default value</i>: Don't use any other sprite resource as base.
</p>
</li>
<li>Attribute <b>pack_texture</b>: When pack_texture is enabled CL_Sprite
will pack as many frames as it can into the same texture object.
<p>
<i>Valid values</i>: "yes, no" - Enable or disable texture packing<br>
<i>Default value</i>: yes
</p>
</li>
<li>Attribute <b>base_angle</b>: Defines what direction the sprite is in. All other angles are relative to this one.
<p>
<i>Valid values</i>:<br>
<i>Default value</i>: "0"
</p>
</li>
<li>Attribute <b>id</b>: Sets the sprite identify retrievable via
CL_Sprite::get_id().
<p>
<i>Valid values</i>:<br>
<i>Default value</i>: "0"
</p>
</li>
</ul>
<p><b><image></b></p>
<ul>
<li>Attribute <b>file</b>: Image filename.
<p>
<i>Valid values</i>:<br>
<i>Default value</i>: None, MUST BE PRESENT.
</p>
</li>
</ul>
<p><b><grid></b></p>
<ul>
<li>Attribute <b>pos</b>: Position in image to start grid-cutting.
<p>
<i>Valid values</i>: "integer, integer" - x-position, y-position<br>
<i>Default value</i>: "0, 0"
</p>
</li>
<li>Attribute <b>size</b>: Size of each grid-tile.
<p>
<i>Valid values</i>: "integer, integer" - width, height<br>
<i>Default value</i>: "1, 1"
</p>
</li>
<li>Attribute <b>array</b>: Grid-size.
<p>
<i>Valid values</i>: "integer, integer" - width, height<br>
<i>Default value</i>: None, MUST BE PRESENT.
</p>
</li>
<li>Attribute <b>array_skipframes</b>: How many frames to skip at end of last gridline.
<p>
<i>Valid values</i>: "integer" - frames to skip<br>
<i>Default value</i>: "0"
</p>
</li>
<li>Attribute <b>spacing</b>: Space between each grid-tile.
<p>
<i>Valid values</i>: "integer, integer" - x-spacing, y-spacing<br>
<i>Default value</i>: "0, 0"
</p>
</li>
</ul>
<p><b><palette></b></p>
<ul>
<li>Attribute <b>pos</b>: Position in image to start palette-cutting.
<p>
<i>Valid values</i>:<br>
<i>Default value</i>: "0, 0"
</p>
</li>
</ul>
<p><b><alpha></b></p>
<ul>
<li>Attribute <b>pos</b>: Position in image to start alpha-cutting.
<p>
<i>Valid values</i>: (integer,integer)<br>
<i>Default value</i>: "0, 0"
</p>
</li>
<li>Attribute <b>free</b>: Use the "Free Alpha Cutter".
<p>The default alpha cutter finds columns of sprites, all of which have the
same height and variable width. The "Free Cutter" identifies all rectangular
non alpha blocks of pixels and puts them on a single frame. The algorithms
starts at the top left corner (or the specified position) and scans the
image line by line, from top to bottom.
</p>
<p>
<i>Valid values</i>: blank, true<br>
<i>Default value</i>: blank
</p>
</li>
<li>Attribute <b>trans_limit</b>: Transparency limit.
<p>
<i>Valid values</i>: "float" - between 0.0 and 1.0<br>
<i>Default value</i>: "0.05"
</p>
</li>
</ul>
<p><b><color></b></p>
<ul>
<li>Attributes <b>red</b>, <b>green</b>, <b>blue</b>, <b>alpha</b>: Color.
<p>Sets the red, green, blue and alpha color components of the sprite.</p>
<p>
<i>Valid values</i>: "float" - between 0.0 and 1.0<br>
<i>Default values</i>: 1.0, 1.0, 1.0, 1.0
</p>
</li>
</ul>
<p><b><animation></b></p>
<ul>
<li>Attribute <b>speed</b>: Default frame delay.
<p>This sets the delay between each frame. You can override separate frames using frameX_speed (see below).
Value is in milliseconds.</p>
<p>
<i>Valid values</i>: integer<br>
<i>Default value</i>: 50
</p>
</li>
<li>Attribute <b>loop</b>: Loop the animation.
<p>Set it to loop if you want the animation to loop after it has reached end of
of the animation.</p>
<p>
<i>Valid values</i>: "yes, no" - Enable or disable looping.<br>
<i>Default value</i>: "yes"
</p>
</li>
<li>Attribute <b>pingpong</b>: Pingpong the animation.
<p>Set it to pingpong if you want the animation to play back to start once it has reached
the end of the animation.</p>
<i>Valid values</i>: "yes, no" - Enable or disable pingpong.<br>
<i>Default value</i>: "no"
</li>
<li>Attribute <b>direction</b>: Direction of animation.
<p>Set it to backwards if you want the animation to play backwards - starts at
last frame, and plays forward to first frame.</p>
<i>Valid values</i>: "backward, forward" - Play the animation backwards or forwards.<br>
<i>Default value</i>: "forward"
</li>
<li>Attribute <b>on_finish</b>: What to show when animation is finished.
<p>Specify what is shown when the animation is finished. Blank shows nothing,
last_frame shows last frame in animation, first_frame shows first frame in animation.
If you use looping, this option has no effect.</p>
<p>
<i>Valid values</i>: blank, last_frame, first_frame - one of the 3 options<br>
<i>Default value</i>: blank
</p>
</li>
</ul>
<p><b><scale></b></p>
<ul>
<li>Attributes <b>x</b> and <b>y</b>: Scale.
<p>Sets the x and y scale of the sprite. A value of 1.0 is the normal size,
2.0 is double the size, etc.</p>
<p>
<i>Valid values</i>: (float, float)<br>
<i>Default value</i>: (1.0, 1.0)
</p>
</li>
</ul>
<p><b><translation></b></p>
<ul>
<li>Attribute <b>origin</b>: Hotspot/alignment for translation operations.
<p>This is which pixel will go at the location specified with CL_Sprite::draw.
So if your sprite has origin=top_left (the default), and you call, say,
my_sprite.draw(50, 100), the very top left hand pixel will be placed at (50, 100)
and the rest of the sprite drawn around that. If you have origin=center then the
centermost pixel will be placed at (50, 100) and the rest of the picture drawn
around that.</p>
<p>
<i>Valid values</i>: top_left, top_center, top_right, center_left, center, center_right, bottom_left, bottom_center, bottom_right<br>
<i>Default value</i>: top_left
</p>
</li>
<li>Attributes <b>x</b> and <b>y</b>: This is how far from the origin the picture should be placed.
<p>x=50 will draw the picture 50 pixels right of where it would normally go. Note that this does take into account the value of origin.</p>
<p>
<i>Valid values</i>: integer <br>
<i>Default value</i>: 0
</p>
</li>
</ul>
<p><b><rotation></b></p>
<ul>
<li>Attribute <b>origin</b>: Hotspot/alignment for rotation operations.
<p>This is the pixel that will stay where it is when you rotate the image.
By default this is the center, so any rotations will leave the center pixel
where it is and rotate the rest of the image around it. If you want to rotate
about the top left corner set this to top_left, etc.</p>
<p>
<i>Valid values</i>: top_left, top_center, top_right, center_left, center, center_right, bottom_left, bottom_center, bottom_right<br>
<i>Default value</i>: center
</p>
</li>
<li>Attributes <b>x</b> and <b>y</b>: This is how far to offset the hotspot from the origin.
<p>
<i>Valid values</i>: integer <br>
<i>Default value</i>: 0
</p>
</li>
</ul>
<p><b><frame></b></p>
<ul>
<li>Attribute <b>speed</b>: Override default speed for this specific frame.
<p>Value is in milliseconds.</p>
<p>
<i>Valid values</i>: integer<br>
<i>Default value</i>: play_speed
</p>
</li>
<li>Attributes <b>x</b> and <b>y</b>: Offset to display this frame.
<p>This let you set a position-offset on a frame, finetuning its
position relative to the other frames.</p>
<p>
<i>Valid values</i>: (integer, integer) - x-position, y-position<br>
<i>Default value</i>: (0, 0)
</p>
</li>
</ul>
</body>
</xml>
|
