Mercurial > molko

comparison doc/spec-tileset.rst @ 219:98adc7dcdcb2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: add spec-tileset
author David Demelier <markand@malikania.fr>
date Wed, 18 Nov 2020 15:03:04 +0100
parents
children bf7169bb054d
comparison
equal deleted inserted replaced
218:71f989ae8de9 219:98adc7dcdcb2
1 .. toctree::
2 .. _spec-tileset:
3
4 =============
5 Spec: tileset
6 =============
7
8 Tilesets are files that are used to draw a map by copying individual cells from
9 an image into the screen by repeating those. A unique tileset can be reused by
10 several maps to avoid recreating every collision and animations each time a new
11 map is created.
12
13 They can be used directly as C code but can be written and read from files as
14 well.
15
16 Tilesets consists of:
17
18 - An image to use as a sprite,
19 - Dimensions of individual cells in that image,
20 - Set of animations for specific tiles,
21 - Set of collision masks for specific tiles,
22 - 3 layers (background, foreground and above),
23 - 1 layer of actions.
24
25 File format
26 -----------
27
28 The file format is a simple plain text where each each line consist of a
29 directive.
30
31 .. caution:: Order is important. You must make sure that every directives are
32 listed in the same order.
33
34 The file format must be defined as following where each ``<>`` must be replaced
35 by the appropriate C type name.
36
37 .. code-block:: text
38
39 tilewidth|<unsigned int>
40 tileheight|<unsigned int>
41 image|<const char *>
42 tiledefs
43 <unsigned short>|<int>|<int>|<unsigned int>|<unsigned int>
44 ...
45 animations
46 <unsigned short>|<const char *>|<unsigned int>
47
48 Description of directives:
49
50 ``tilewidth``
51 Cell width in the image.
52 ``tileheight``
53 Cell height in the image.
54 ``image``
55 Path to image to use (must be relative).
56 ``tiledefs``
57 Start a list of tile definitions to describe a collision mask for a given
58 tile. Each line after this directive describe a unique rectangle for one tile
59 by specifying ``tile id``, ``x``, ``y``, ``width``, ``height`` in order.
60
61 This section is optional and can be omitted entirely.
62 ``animations``
63 Start a list of tile animations that should be used instead of drawing from
64 the image sprite itself. Each line after this directive describe an animation
65 for a given tile by specifying ``tile id``, ``animation file``, ``delay`` in
66 order.
67
68 Examples
69 --------
70
71 The following file is a tileset using the image *world.png* that has 64x64
72 dimensions for each cell.
73
74 .. code-block:: text
75
76 tilewidth|64
77 tileheight|64
78 image|world.png
79
80 The following file adds some collision rectangles on tiles *3* and *5*. The
81 rectangle collision for the tile id *3* has dimensions of W=30, H=30, X=5, Y=5
82 and the rectangle for the tile id *5* has dimensions of W=10, H=15, X=10, Y=10.
83
84 .. code-block:: text
85
86 tilewidth|64
87 tileheight|64
88 image|world.png
89 tiledefs
90 3|30|30|5|5
91 5|10|15|10|10
92
93 The following file adds an animation for the tile id *3* using the file
94 *animation-water.png* with a delay of *500* ms per tile.
95
96 .. code-block:: text
97
98 tilewidth|64
99 tileheight|64
100 image|world.png
101 animations
102 3|animation-water.png|500