Mercurial > molko
changeset 219:98adc7dcdcb2
doc: add spec-tileset
author | David Demelier <markand@malikania.fr> |
---|---|
date | Wed, 18 Nov 2020 15:03:04 +0100 |
parents | 71f989ae8de9 |
children | 617fda414bbb |
files | doc/CMakeLists.txt doc/index.rst doc/spec-tileset.rst doc/specifications.rst |
diffstat | 4 files changed, 127 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/CMakeLists.txt Wed Nov 18 13:46:29 2020 +0100 +++ b/doc/CMakeLists.txt Wed Nov 18 15:03:04 2020 +0100 @@ -36,6 +36,8 @@ ${doc_SOURCE_DIR}/conf.py ${doc_SOURCE_DIR}/getting-started.rst ${doc_SOURCE_DIR}/index.rst + ${doc_SOURCE_DIR}/specifications.rst + ${doc_SOURCE_DIR}/spec-tileset.rst ) add_custom_target(
--- a/doc/index.rst Wed Nov 18 13:46:29 2020 +0100 +++ b/doc/index.rst Wed Nov 18 15:03:04 2020 +0100 @@ -18,6 +18,7 @@ about getting-started + specifications api-js Indices and tables
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/spec-tileset.rst Wed Nov 18 15:03:04 2020 +0100 @@ -0,0 +1,102 @@ +.. toctree:: +.. _spec-tileset: + +============= +Spec: tileset +============= + +Tilesets are files that are used to draw a map by copying individual cells from +an image into the screen by repeating those. A unique tileset can be reused by +several maps to avoid recreating every collision and animations each time a new +map is created. + +They can be used directly as C code but can be written and read from files as +well. + +Tilesets consists of: + +- An image to use as a sprite, +- Dimensions of individual cells in that image, +- Set of animations for specific tiles, +- Set of collision masks for specific tiles, +- 3 layers (background, foreground and above), +- 1 layer of actions. + +File format +----------- + +The file format is a simple plain text where each each line consist of a +directive. + +.. caution:: Order is important. You must make sure that every directives are + listed in the same order. + +The file format must be defined as following where each ``<>`` must be replaced +by the appropriate C type name. + +.. code-block:: text + + tilewidth|<unsigned int> + tileheight|<unsigned int> + image|<const char *> + tiledefs + <unsigned short>|<int>|<int>|<unsigned int>|<unsigned int> + ... + animations + <unsigned short>|<const char *>|<unsigned int> + +Description of directives: + +``tilewidth`` + Cell width in the image. +``tileheight`` + Cell height in the image. +``image`` + Path to image to use (must be relative). +``tiledefs`` + Start a list of tile definitions to describe a collision mask for a given + tile. Each line after this directive describe a unique rectangle for one tile + by specifying ``tile id``, ``x``, ``y``, ``width``, ``height`` in order. + + This section is optional and can be omitted entirely. +``animations`` + Start a list of tile animations that should be used instead of drawing from + the image sprite itself. Each line after this directive describe an animation + for a given tile by specifying ``tile id``, ``animation file``, ``delay`` in + order. + +Examples +-------- + +The following file is a tileset using the image *world.png* that has 64x64 +dimensions for each cell. + +.. code-block:: text + + tilewidth|64 + tileheight|64 + image|world.png + +The following file adds some collision rectangles on tiles *3* and *5*. The +rectangle collision for the tile id *3* has dimensions of W=30, H=30, X=5, Y=5 +and the rectangle for the tile id *5* has dimensions of W=10, H=15, X=10, Y=10. + +.. code-block:: text + + tilewidth|64 + tileheight|64 + image|world.png + tiledefs + 3|30|30|5|5 + 5|10|15|10|10 + +The following file adds an animation for the tile id *3* using the file +*animation-water.png* with a delay of *500* ms per tile. + +.. code-block:: text + + tilewidth|64 + tileheight|64 + image|world.png + animations + 3|animation-water.png|500
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/specifications.rst Wed Nov 18 15:03:04 2020 +0100 @@ -0,0 +1,22 @@ +.. toctree:: + :hidden: + +Specifications +============== + +This page describe file data, conventions and project structure required to +write a game using Molko's Adventure API. Most of the code relies on the +`conventions over configuration`_ principle where the user data is required to +be in a certain manner rather than allowing lots of parameters. In that way both +of the API and the user code stay solid and simple. + +For example, the game expect sprites to be designed in such a way that the code +can simply select a row/column depending on the orientation. See individual +specifications for more details. + +.. toctree:: + :maxdepth: 1 + + spec-tileset + +.. _conventions over configuration: https://en.wikipedia.org/wiki/Convention_over_configuration