--- 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