Debian Codegraph @

Documentation/Overview/sprites_resources.xml

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