Mercurial > molko
changeset 222:bf7169bb054d
doc: improve
author | David Demelier <markand@malikania.fr> |
---|---|
date | Wed, 18 Nov 2020 19:03:47 +0100 |
parents | d51d9c0c2186 |
children | 560303066120 |
files | doc/CMakeLists.txt doc/index.rst doc/spec-map.rst doc/spec-tileset.rst doc/specifications.rst doc/tool-bcc.rst doc/tool-map.rst doc/tool-tileset.rst doc/tools.rst |
diffstat | 9 files changed, 220 insertions(+), 8 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/CMakeLists.txt Wed Nov 18 15:19:25 2020 +0100 +++ b/doc/CMakeLists.txt Wed Nov 18 19:03:47 2020 +0100 @@ -23,11 +23,16 @@ if (SPHINX_EXE) set( SOURCES - ${doc_SOURCE_DIR}/about.rst - ${doc_SOURCE_DIR}/conf.py - ${doc_SOURCE_DIR}/index.rst - ${doc_SOURCE_DIR}/specifications.rst - ${doc_SOURCE_DIR}/spec-tileset.rst + ${doc_SOURCE_DIR}/about.rst + ${doc_SOURCE_DIR}/conf.py + ${doc_SOURCE_DIR}/index.rst + ${doc_SOURCE_DIR}/spec-map.rst + ${doc_SOURCE_DIR}/spec-tileset.rst + ${doc_SOURCE_DIR}/specifications.rst + ${doc_SOURCE_DIR}/tool-bcc.rst + ${doc_SOURCE_DIR}/tool-map.rst + ${doc_SOURCE_DIR}/tool-tileset.rst + ${doc_SOURCE_DIR}/tools.rst ) add_custom_target(
--- a/doc/index.rst Wed Nov 18 15:19:25 2020 +0100 +++ b/doc/index.rst Wed Nov 18 19:03:47 2020 +0100 @@ -21,6 +21,7 @@ about specifications + tools Indices and tables ==================
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/spec-map.rst Wed Nov 18 19:03:47 2020 +0100 @@ -0,0 +1,117 @@ +.. toctree:: +.. _spec-map: + +========= +Spec: map +========= + +Maps are probably the most important files within the game, it provides the map +definition, structure, actions and player interactions. + +It consists of: + +- A tileset to use (only one), +- A size in terms of number of rows and columns, +- 3 layers (background, foreground and above), +- 1 layer of actions. + +Just like :ref:`spec-tileset`, maps are defined in a custom map file format in +plain text. + +Maps have an extension of ``.map``. + +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 + + title|<const char *> + columns|<unsigned int> + rows|<unsigned int> + tileset|<const char *> + origin|<int>|<int> + layer|background + <int> + <int> + ... + layer|foreground + <int> + <int> + ... + layer|above + <int> + <int> + ... + layer|actions + <int>|<int>|<unsigned int>|<unsigned int>|<const char *> + +Description of directives: + +``title`` + Map title, must not exceed 64 bytes. + +``columns`` + Number of columns. + +``rows`` + Number of rows. + +``tileset`` + The tileset to use given as a string name. The path must be relative. + +``origin`` + (Optional) Position in where the player starts bt specifying ``x``, ``y`` + respectively. + +``layer`` + (Optional) For layers of type ``background``, ``foreground`` and ``above``, + defines the tiles to use in order from top-left to bottom-right starting from + 1, a value of 0 means no tile to render. If a map has a dimensions of 4 + columns and 6 the number of tiles must not exceed 24. + + For the layer action, defines an object to be implemented in the API. The + first 4 integers define the ``x``, ``y``, ``width`` and ``height`` dimensions + of the action rectangle respectively. The final string is an argument to pass + to the action. + +Examples +-------- + +The following file is a map with 4 columns and 2 rows (it is probably small for +a real game but at least it is readable for this example). The player starts at +10, 10, the background is using the same tile while the foreground is using +different tiles. + +.. code-block:: text + + title|Small map + columns|4 + rows|2 + origin|10|10 + layer|background + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + layer|foreground + 0 + 0 + 2 + 2 + 0 + 0 + 3 + 3
--- a/doc/spec-tileset.rst Wed Nov 18 15:19:25 2020 +0100 +++ b/doc/spec-tileset.rst Wed Nov 18 19:03:47 2020 +0100 @@ -18,9 +18,9 @@ - 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. +- Set of collision masks for specific tiles. + +Tilesets have an extension of ``.tileset``. File format -----------
--- a/doc/specifications.rst Wed Nov 18 15:19:25 2020 +0100 +++ b/doc/specifications.rst Wed Nov 18 19:03:47 2020 +0100 @@ -18,5 +18,6 @@ :maxdepth: 1 spec-tileset + spec-map .. _conventions over configuration: https://en.wikipedia.org/wiki/Convention_over_configuration
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/tool-bcc.rst Wed Nov 18 19:03:47 2020 +0100 @@ -0,0 +1,51 @@ +============= +Tool: mlk-bcc +============= + +This utility generates C byte array from any input file. Its main purpose is to +allow embedding data directly into the executable without having to load files +from disk. + +It reads the given file and generate the output to the standard output. + +Synopsis:: + + mlk-bcc [-0csu] [-I num] [-i num] filename variable + +Options and arguments: + +.. program:: mlk-bcc + +.. option:: -0 + + Terminate the array with a NUL terminator. + +.. option:: -c + + Generate a ``const`` C array. + +.. option:: -s + + Generate a ``static`` C array. + +.. option:: -u + + Use ``unsigned char`` instead of ``signed char`` when generating the byte + array. + +.. option:: -I num + + Use ``num`` tabs to indent (defaults to 1). + +.. option:: -i num + + Use ``num`` spaces to indent. + +.. option:: filename + + Filename to read as input, a value of ``-`` will read the standard input. + +.. option:: variable + + The C variable to generate, any character that is not valid in C will be + replaced by a ``_`` but the variable must still not start with a digit.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/tool-map.rst Wed Nov 18 19:03:47 2020 +0100 @@ -0,0 +1,12 @@ +============= +Tool: mlk-map +============= + +Convert a map generated from Tiled_ into a Molko's Adventure compatible one. + +The utility will read standard input and write the converted map to the standard +output. + +.. caution:: Only JSON files are supported. + +.. _Tiled: http://mapeditor.org
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/tool-tileset.rst Wed Nov 18 19:03:47 2020 +0100 @@ -0,0 +1,12 @@ +================= +Tool: mlk-tileset +================= + +Convert a tileset generated from Tiled_ into a Molko's Adventure compatible one. + +The utility will read standard input and write the converted tileset to the +standard output. + +.. caution:: Only JSON files are supported. + +.. _Tiled: http://mapeditor.org
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/tools.rst Wed Nov 18 19:03:47 2020 +0100 @@ -0,0 +1,13 @@ +===== +Tools +===== + +The following tools are provided by the Molko's Adventure build and can be used +for creators. + +.. toctree:: + :maxdepth: 1 + + tool-bcc + tool-tileset + tool-map