Mercurial > molko
changeset 239:d47e70da760e
doc: switch to mkdocs+doxybook2, closes #2516 @2h
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 27 Nov 2020 17:00:30 +0100 |
parents | b30c3af37a01 |
children | d7e5e02f70a1 |
files | CMakeLists.txt doc/CMakeLists.txt doc/about.rst doc/api.rst doc/api/core/action.rst doc/api/core/alloc.rst doc/api/core/animation.rst doc/api/core/clock.rst doc/api/core/color.rst doc/api/core/core.rst doc/api/core/drawable.rst doc/api/core/error.rst doc/api/core/event.rst doc/api/core/font.rst doc/api/core/game.rst doc/api/core/image.rst doc/api/core/inhibit.rst doc/api/core/key.rst doc/api/core/maths.rst doc/api/core/mouse.rst doc/api/core/music.rst doc/api/core/painter.rst doc/api/core/panic.rst doc/api/core/save.rst doc/api/core/script.rst doc/api/core/sound.rst doc/api/core/sprite.rst doc/api/core/state.rst doc/api/core/sys.rst doc/api/core/texture.rst doc/api/core/trace.rst doc/api/core/util.rst doc/api/core/wait.rst doc/api/core/window.rst doc/api/libcore.rst doc/build.rst doc/conf.py doc/docs/about.md doc/docs/dev/error.md doc/docs/dev/faq.md doc/docs/dev/howto/01-init.md doc/docs/dev/ownership.md doc/docs/index.md doc/docs/install.md doc/docs/specs/map.md doc/docs/specs/tileset.md doc/docs/tools/bcc.md doc/docs/tools/map.md doc/docs/tools/tileset.md doc/doxybook.json doc/doxygen/groups.c doc/index.rst doc/mkdocs.yml 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 doxygen/CMakeLists.txt doxygen/groups.c doxygen/mainpage.c doxygen/page-faq.c doxygen/page-howto-error.c doxygen/page-howto-initialization.c doxygen/page-howto-ownership.c doxygen/page-portability.c |
diffstat | 68 files changed, 933 insertions(+), 1293 deletions(-) [+] |
line wrap: on
line diff
--- a/CMakeLists.txt Fri Nov 27 13:32:52 2020 +0100 +++ b/CMakeLists.txt Fri Nov 27 17:00:30 2020 +0100 @@ -24,8 +24,7 @@ set(CMAKE_C_EXTENSIONS Off) set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake") -option(MOLKO_WITH_DOXYGEN "Enable Doxygen build" On) -option(MOLKO_WITH_DOC "Enable documentation (requires sphinx)" On) +option(MOLKO_WITH_DOC "Enable documentation (requires doxygen, doxybook2 and mkdocs)" On) option(MOLKO_WITH_TESTS "Enable unit tests" On) option(MOLKO_WITH_EXAMPLES "Enable build of examples" On) @@ -48,10 +47,6 @@ add_subdirectory(extern/libgreatest) add_subdirectory(extern/libsqlite) -if (MOLKO_WITH_DOXYGEN) - add_subdirectory(doxygen) -endif () - add_subdirectory(tools/bcc) add_subdirectory(tools/map) add_subdirectory(tools/tileset) @@ -63,10 +58,6 @@ add_subdirectory(molko) if (MOLKO_WITH_DOC) - if (NOT MOLKO_WITH_DOXYGEN) - message(FATAL_ERROR "Can't build documentation with doxygen disabled") - endif () - add_subdirectory(doc) endif ()
--- a/doc/CMakeLists.txt Fri Nov 27 13:32:52 2020 +0100 +++ b/doc/CMakeLists.txt Fri Nov 27 17:00:30 2020 +0100 @@ -18,36 +18,118 @@ project(doc) -find_program(SPHINX_EXE sphinx-build DOC "Path to sphinx-build") +find_package(Doxygen QUIET) +find_program(MKDOCS_EXE mkdocs DOC "Path to mkdocs") +find_program(DOXYBOOK2_EXE doxybook2 DOC "Path to doxybook2") -if (SPHINX_EXE) +if (DOXYGEN_FOUND AND MKDOCS_EXE AND DOXYBOOK2_EXE) + set( + DOXYGEN_SOURCES + libcore + libui + librpg + ${doc_SOURCE_DIR}/doxygen/groups.c + ) + set( - SOURCES - ${doc_SOURCE_DIR}/about.rst - ${doc_SOURCE_DIR}/build.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 + DOXYGEN_STRIP_FROM_PATH + ${CMAKE_SOURCE_DIR}/libcore + ${CMAKE_SOURCE_DIR}/libui + ${CMAKE_SOURCE_DIR}/librpg + ) + set( + DOC_SOURCES + ${doc_SOURCE_DIR}/docs/specs/map.md + ${doc_SOURCE_DIR}/docs/specs/tileset.md + ${doc_SOURCE_DIR}/docs/tools/bcc.md + ${doc_SOURCE_DIR}/docs/tools/map.md + ${doc_SOURCE_DIR}/docs/tools/tileset.md + ${doc_SOURCE_DIR}/docs/about.md + ${doc_SOURCE_DIR}/docs/index.md + ${doc_SOURCE_DIR}/docs/install.md + ${doc_SOURCE_DIR}/mkdocs.yml ) - configure_file( - ${doc_SOURCE_DIR}/conf.py - ${doc_BINARY_DIR}/conf.py + # 1. Generate XML structure with Doxygen. + set(DOXYGEN_SHOW_GROUPED_MEMB_INC NO) + set(DOXYGEN_SHOW_INCLUDE_FILES NO) + set(DOXYGEN_SHOW_USED_FILES NO) + set(DOXYGEN_ALLOW_UNICODE_NAMES YES) + set(DOXYGEN_AUTOLINK_SUPPORT NO) + set(DOXYGEN_ENABLE_PREPROCESSING YES) + set(DOXYGEN_EXAMPLE_PATH examples) + set(DOXYGEN_EXCLUDE_PATTERNS *_p.h) + set(DOXYGEN_FILE_PATTERNS *.h) + set(DOXYGEN_GENERATE_LATEX NO) + set(DOXYGEN_GENERATE_MAN NO) + set(DOXYGEN_GENERATE_XML YES) + set(DOXYGEN_GENERATE_HTML NO) + set(DOXYGEN_INPUT_ENCODING UTF-8) + set(DOXYGEN_MAX_INITIALIZER_LINES 0) + set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) + set(DOXYGEN_OUTPUT_DIRECTORY doxygen) + set(DOXYGEN_PREDEFINED DOXYGEN) + set(DOXYGEN_XML_OUTPUT ${doc_BINARY_DIR}/doxygen-xml) + #set(DOXYGEN_PROJECT_BRIEF "2D RPG game in C") + #set(DOXYGEN_PROJECT_NAME "Molko's Adventure") + set(DOXYGEN_QUIET YES) + set(DOXYGEN_RECURSIVE YES) + set(DOXYGEN_TAB_SIZE 8) + set(DOXYGEN_WARNINGS YES) + + # 1. Generate XML from doxygen. + doxygen_add_docs( + doc-doxygen-xml + ${DOXYGEN_SOURCES} + WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}" + ) + + # 2. Convert XML through markdown with doxybook2. + add_custom_target( + doc-doxybook + VERBATIM + DEPENDS doc-doxygen-xml + COMMAND + ${CMAKE_COMMAND} -E make_directory ${doc_BINARY_DIR}/docs + COMMAND ${DOXYBOOK2_EXE} -q + -i ${doc_BINARY_DIR}/doxygen-xml + -o ${doc_BINARY_DIR}/docs + -c ${doc_SOURCE_DIR}/doxybook.json + ) + + # 3. Copy the directory containing hand-made documentation and call mkdocs. + add_custom_target( + doc + VERBATIM + DEPENDS doc-doxybook + WORKING_DIRECTORY ${doc_BINARY_DIR} + COMMAND + ${CMAKE_COMMAND} -E copy_directory + ${doc_SOURCE_DIR}/docs + ${doc_BINARY_DIR}/docs + COMMAND + ${CMAKE_COMMAND} -E copy + ${doc_SOURCE_DIR}/mkdocs.yml + ${doc_BINARY_DIR} + COMMAND + ${MKDOCS_EXE} build + -d ${doc_BINARY_DIR}/html ) add_custom_target( - doc - ALL VERBATIM - SOURCES ${SOURCES} - COMMAND ${SPHINX_EXE} -c ${doc_BINARY_DIR} -q . ${doc_BINARY_DIR} - WORKING_DIRECTORY ${doc_SOURCE_DIR} - COMMENT "Generating documentation" - DEPENDS doxygen + doc-serve + VERBATIM + DEPENDS doc-doxybook + WORKING_DIRECTORY ${doc_BINARY_DIR} + COMMAND + ${CMAKE_COMMAND} -E copy_directory + ${doc_SOURCE_DIR}/docs + ${doc_BINARY_DIR}/docs + COMMAND + ${CMAKE_COMMAND} -E copy + ${doc_SOURCE_DIR}/mkdocs.yml + ${doc_BINARY_DIR} + COMMAND + ${MKDOCS_EXE} serve ) endif ()
--- a/doc/about.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,19 +0,0 @@ -===== -About -===== - -Molko's Adventure is a 2D solo RPG game and an API to build more RPG games. It -is designed with the following characteristics: - -- Turn based battle. Similar to old RPG games battle operate on a dedicated game - state where the player and enemies select actions to perform when the member - is ready to play. -- Tile based maps using scrolling and pixel granularity movements. -- Theme system to allow customization of some user interface components. -- Set of predefined dialog windows to control the game. - -While the API is flexible and powerful enough to create different games, it is -still kept as simple possible without cluttering the API with dozen of -abstraction and generics all over the place. This means that there are -predefined kinds of character status (poison, slow, etc) along with kind of -spells (earth, neutral).
--- a/doc/api.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,22 +0,0 @@ -============= -API Reference -============= - -Official C API reference. - -The API is split into individual libraries: - -``libcore`` - Low level access to the library that provides input, sound, animations and - windowing system. - -``libui`` - User interface elements. - -``librpg`` - Every other components that are related to the RPG gameplay. - -.. toctree:: - :maxdepth: 1 - - api/libcore
--- a/doc/api/core/action.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================== -#include <core/action.h> -======================== - -.. doxygenfile:: core/action.h
--- a/doc/api/core/alloc.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/alloc.h> -======================= - -.. doxygenfile:: core/alloc.h
--- a/doc/api/core/animation.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -=========================== -#include <core/animation.h> -=========================== - -.. doxygenfile:: core/animation.h
--- a/doc/api/core/clock.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/clock.h> -======================= - -.. doxygenfile:: core/clock.h
--- a/doc/api/core/color.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/color.h> -======================= - -.. doxygenfile:: core/color.h
--- a/doc/api/core/core.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -====================== -#include <core/core.h> -====================== - -.. doxygenfile:: core/core.h
--- a/doc/api/core/drawable.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -========================== -#include <core/drawable.h> -========================== - -.. doxygenfile:: core/drawable.h
--- a/doc/api/core/error.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/error.h> -======================= - -.. doxygenfile:: core/error.h
--- a/doc/api/core/event.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/event.h> -======================= - -.. doxygenfile:: core/event.h
--- a/doc/api/core/font.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -====================== -#include <core/font.h> -====================== - -.. doxygenfile:: core/font.h
--- a/doc/api/core/game.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -====================== -#include <core/game.h> -====================== - -.. doxygenfile:: core/game.h
--- a/doc/api/core/image.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/image.h> -======================= - -.. doxygenfile:: core/image.h
--- a/doc/api/core/inhibit.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -========================= -#include <core/inhibit.h> -========================= - -.. doxygenfile:: core/inhibit.h
--- a/doc/api/core/key.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -===================== -#include <core/key.h> -===================== - -.. doxygenfile:: core/key.h
--- a/doc/api/core/maths.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/maths.h> -======================= - -.. doxygenfile:: core/maths.h
--- a/doc/api/core/mouse.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/mouse.h> -======================= - -.. doxygenfile:: core/mouse.h
--- a/doc/api/core/music.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/music.h> -======================= - -.. doxygenfile:: core/music.h
--- a/doc/api/core/painter.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -========================= -#include <core/painter.h> -========================= - -.. doxygenfile:: core/painter.h
--- a/doc/api/core/panic.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/panic.h> -======================= - -.. doxygenfile:: core/panic.h
--- a/doc/api/core/save.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -====================== -#include <core/save.h> -====================== - -.. doxygenfile:: core/save.h
--- a/doc/api/core/script.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================== -#include <core/script.h> -======================== - -.. doxygenfile:: core/script.h
--- a/doc/api/core/sound.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/sound.h> -======================= - -.. doxygenfile:: core/sound.h
--- a/doc/api/core/sprite.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================== -#include <core/sprite.h> -======================== - -.. doxygenfile:: core/sprite.h
--- a/doc/api/core/state.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/state.h> -======================= - -.. doxygenfile:: core/state.h
--- a/doc/api/core/sys.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -===================== -#include <core/sys.h> -===================== - -.. doxygenfile:: core/sys.h
--- a/doc/api/core/texture.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -========================= -#include <core/texture.h> -========================= - -.. doxygenfile:: core/texture.h
--- a/doc/api/core/trace.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================= -#include <core/trace.h> -======================= - -.. doxygenfile:: core/trace.h
--- a/doc/api/core/util.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -====================== -#include <core/util.h> -====================== - -.. doxygenfile:: core/util.h
--- a/doc/api/core/wait.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -====================== -#include <core/wait.h> -====================== - -.. doxygenfile:: core/wait.h
--- a/doc/api/core/window.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,5 +0,0 @@ -======================== -#include <core/window.h> -======================== - -.. doxygenfile:: core/window.h
--- a/doc/api/libcore.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,38 +0,0 @@ -================ -Library: libcore -================ - -.. toctree:: - :maxdepth: 1 - - core/action - core/alloc - core/animation - core/clock - core/color - core/core - core/drawable - core/error - core/event - core/font - core/game - core/image - core/inhibit - core/key - core/maths - core/mouse - core/music - core/painter - core/panic - core/save - core/script - core/sound - core/sprite - core/state - core/sys - core/texture - core/trace - core/util - core/util - core/wait - core/window
--- a/doc/build.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,98 +0,0 @@ -==================== -Building from source -==================== - -This page will explain how to build Molko's Adventure and libraries. - -Requirements ------------- - -The following requirements are necessary to build the project. - -- C11 compiler: obviously, -- cmake_: the build system, -- `SDL2`_: the main game library, -- `SDL2_image`_: to load images, -- `SDL2_mixer`_: to play sounds and music, -- `SDL2_ttf`_: to open fonts, -- `Jansson`_: only for ``mlk-tileset`` and ``mlk-map`` tools. - -Platforms supported -------------------- - -The project has been tested on the following platforms. - -- Windows 10: only with `MSYS2`_, Visual Studio **is not** supported yet. -- macOS 11.0 (Big Sur): using Xcode 12 and libraries from `brew`_, -- Linux: on Alpine Linux (musl) and Arch Linux. - -C and POSIX features --------------------- - -Both of the API and the game are written using C99 and C11 but not all of the -features from both C versions are required. Here's a list of functionalities -that are required: - -From C99 -^^^^^^^^ - -Features: - -- `Compound literals`_, -- `inline`_ keyword. - -Headers: - -- `stdbool.h`_ - -Functions: - -- `snprintf`_ - -From C11 -^^^^^^^^ - -- `stdnoreturn.h`_ - -From POSIX -^^^^^^^^^^ - -Expectations: - -- We use a few parts of POSIX_ specification but try to keep its use limited as - not all platforms are POSIX compliant. -- We assume that ``fopen``, ``malloc`` and friends set errno in case of failures. - -Functions: - -- `dirname`_, -- `getopt`_. - -Headers: - -- `libgen.h`_ - -Macros: - -- PATH_MAX: in limits.h. - -.. note:: When a POSIX requirement isn't present it is replaced by a shim - specified for the platform. - -.. _Compound literals: https://en.cppreference.com/w/c/language/compound_literal -.. _Jansson: https://digip.org/jansson -.. _MSYS2: https://www.msys2.org -.. _POSIX: https://pubs.opengroup.org/onlinepubs/9699919799 -.. _SDL2: http://libsdl.org -.. _SDL2_image: https://www.libsdl.org/projects/SDL_image -.. _SDL2_mixer: https://www.libsdl.org/projects/SDL_mixer -.. _SDL2_ttf: https://www.libsdl.org/projects/SDL_ttf -.. _brew: https://brew.sh -.. _cmake: http://cmake.org -.. _dirname: https://pubs.opengroup.org/onlinepubs/9699919799/functions/dirname.html -.. _getopt: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getopt.html -.. _inline: https://en.cppreference.com/w/c/language/inline -.. _libgen.h: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/libgen.h.html -.. _snprintf: https://en.cppreference.com/w/c/io/fprintf -.. _stdbool.h: https://en.cppreference.com/w/c/language/arithmetic_types#Boolean_type -.. _stdnoreturn.h: https://en.cppreference.com/w/c/types
--- a/doc/conf.py Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,38 +0,0 @@ -# -# conf.py -- sphinx documentation configuration -# -# Copyright (c) 2020 David Demelier <markand@malikania.fr> -# -# Permission to use, copy, modify, and/or distribute this software for any -# purpose with or without fee is hereby granted, provided that the above -# copyright notice and this permission notice appear in all copies. -# -# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -# - -# Project information. -project = "Molko's Adventure" -copyright = "2020, David Demelier" -author = "David Demelier" -release = '0.1.0' - -# General settings. -templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -# HTML output. -html_theme = "haiku" -html_static_path = ["_static"] - -# Doxygen bridge through breathe. -extensions = [ "breathe" ] -breathe_projects = { - "molko": "@doxygen_BINARY_DIR@/doxygen/xml" -} -breathe_default_project = "molko"
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/docs/about.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,17 @@ +# About + +Molko's Adventure is a 2D solo RPG game and an API to build more RPG games. It +is designed with the following characteristics: + +- Turn based battle. Similar to old RPG games battle operate on a dedicated game + state where the player and enemies select actions to perform when the member + is ready to play. +- Tile based maps using scrolling and pixel granularity movements. +- Theme system to allow customization of some user interface components. +- Set of predefined dialog windows to control the game. + +While the API is flexible and powerful enough to create different games, it is +still kept as simple possible without cluttering the API with dozen of +abstraction and generics all over the place. This means that there are +predefined kinds of character status (poison, slow, etc) along with kind of +spells (earth, neutral).
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/docs/dev/error.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,72 @@ +# Error handling + +How error handling is used within the API and the user code. + +## Synopsis + +Error handling is always a complicated task in the software development. In +Molko's Adventure there is three kinds of errors: + +1. Programming error. +2. Recoverable error at runtime. +3. Unexpected error at runtime. + +## Kind of errors + +### Assertions + +One of the easiest errors to detect are about programming errors. In the +Molko's Adventure API they are usually detected at runtime when you use a +function with preconditions unmet. In that case standard C `assert` is used. + +For example, it happens when you: + +- Pass a NULL pointer where the function expects non-NULL, +- Pass invalid arguments such as out of bounds indicies. + +Always read carefully preconditions that are annotated through the +documentation. + +### Recoverable errors + +Next, come recoverable errors. Those arise when you may expect a failure from +the API and can do something else. + +For example, it happens when you: + +- Open a font file that is invalid, +- Open a music file that is no longer on the disk. + +In these situations, the API indicates usually by a return code that the +function was unable to complete correctly (and you can use error to retrieve +the specified error). In some case, you *MUST* not ignore the return value +because if the function takes an input as argument it will be kept untouched. +For example, the texture_new function may fail to create a texture and in that +case it is left untouched. + +### Unexpected errors + +Finally, come what we call unexpected errors. Those happen while they are not +supposed to. + +For example, it happens when there is a severe issue either in the kernel, +graphics or any other library that aren't raised by the API itself. + +This includes (but not limited to): + +- A rendering error (caused by an internal issue). + +In these situations, the API calls the function panic which definitely calls +the panic_handler. The default implementation prints an error and exit with a +code of 1. User may pass a custom function but should quit the game because the +API does not take care of deallocating data before calling panic. + +## Error handling in Molko's Adventure API + +The following table shows what is used and when. + +| | `assert` | Booleans | panic | Notes | +|---------|--------------------|---------------------|-------------------------------------------|-----------------------------------| +| libcore | Programming errors | As much as possible | Only in memory utilities from util.h | Never called from libcore itself. | +| libui | Programming errors | When applicable | Mostly in rendering errors | None. | +| librpg | Programming errors | When applicable | Mostly in rendering errors | None. |
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/docs/dev/faq.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,71 @@ +# FAQ + +Frequently asked questions about the development. + +## Why not creating a game engine? + +Game engines are usually too generic, too complex and do too much things. Lots +of them also use scripting language which require another learning curve to be +used. + +Molko's Adventure is a solo tactical 2D RPG and its core is especially designed +for that gameplay. Thus the code stay simple to understand and to follow. +Coupling a general purpose game engine with a game design is sometimes more +complicated than writing small code. + +However, game engines are still interesting for people who already know how to +use them and feel confident with them. + +## Why no prefix like "ma_" or "MA_"? + +See also question above. + +The purpose of Molko's Adventure is not to provide a drop-in reusable library +to create RPG games. It is highly coupled with the gameplay of the original +game. Thus we wanted to keep the codebase extremely simple and minimalist +without adding bunch of generics. + +The core API isn't meant to be installed system wide (possible, but not +recommended), instead users are encouraged to copy the core code and to adapt +to their gameplay. + +A simple example: if someone wants to create a game and would like to allow +only three playable entities at a time, it should simply edit appropriates +structures and everything is adapted. Then, structures and array can stay +static without dynamic allocations. + +Also, having a large amount of different data types, this would generate very +large function and type names. + +## Why C instead of *FOO*? + +C is an awesome language. It still has its place in the industry especially in +low-level, kernel and game design. + +Games are usually designed without OO in mind using simple procedural codes and +lots of data. In C, writing code makes easier to understand what's happening +under the hood without having to check if functions will generate dynamic +allocations or not. + +However, we also love modernity and as such, C11 is the minimal requirement to +build and run Molko's Adventure. + +## Can I make a MMORPG with that? + +Not easily. + +This core API is really tied to a unique solo RPG adventure and therefore it +does not separate logic from rendering. + +Also, note that creating a server-client game is really different in terms of +architecture than a local solo game. Most of the logic part is done server side +and requires much more code to analyze to avoid cheats, lag, synchronisation and +many other stuff than a local game does not require. + +There are no plans to create a network oriented core API anytime soon. + +## What are these stranges symbols `(+-*&?)` in member fields? + +It's a custom notation to indicate ownership and user access. + +See [ownership](ownership.md) file for more information.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/docs/dev/howto/01-init.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,37 @@ +# Howto: initialization + +Howto initialize the API before developing. + +## Synopsis + +Before using the core, you need to initialize the subsystems and internal +backend API. + +!!! caution + Even non-rendering modules requires initialization and some of them even + require a window to be open. + +## Usage + +The following table summarize the functions to be used at the beginning and +the end of your game. + +| System | Init function | Close function | Remarks | +|---------|------------------|--------------------|------------------------| +| General | sys_init | sys_finish | Required for most API | +| Window | window_init | window_finish | Required by some parts | + +All init functions set an error code if any and you're encouraged to test the +result and check the error if any. + +## Example + +Init the core and create a window of Full HD resolution. The function \ref +panic will all the panic handler. + +```c +if (!sys_init()) + panic(); +if (!window_init("My Awesome Game", 1920, 1080)) + panic(); +```
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/docs/dev/ownership.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,127 @@ +# Howto: ownership and memory management + +How memory and ownership is used within Molko's Adventure API. + +## Synopsis + +In C, memory management can be a cumbersome issue and a major common complain +when it comes to leak. + +As such, the API itself does not use dynamic allocations in most of the case. +Instead it is kept to the user responsability to handle storage of data. In that +manner the code stays simpler, stronger and more flexible. The API itself does +not have to deal with memory management and deallocation, it only expect data +from user and work with that. + +You can imagine a situation with a DVD player and some movies on DVDs. You have +one DVD player where you put some DVDs inside but the DVD player never make its +own copy, it simply reads your disc and you get it back afterwards. + +Following this philosophy, the Molko's Adventure API for this scenario would +look like this: + +```c +struct dvd_player player; +struct dvd dvd; + +dvd_open(&dvd, "/dev/sr0"); + +dvd_player_turn_on(); +dvd_player_insert(&player, &dvd); +dvd_player_play(&player); +dvd_player_turn_off(); +``` + +## Memory handling + +### Arrays + +Some modules in the API may require an array. Depending on the situation they +can be passed as parameter or are usually of a fixed reasonable size in +structures. + +They are always annotated with a macro to let the user flexibility over it if +necessary. + +Example, a player has a set of spells. + +```c +#define PLAYER_SPELL_MAX (16) + +struct player { + struct spell *spells[PLAYER_SPELL_MAX]; +}; +``` + +!!! note + You may think that we could use a pointer to pointer of spell to let user + pass a variable number of spells. That would help flexibility but makes user + code more complex and painful, instead the macro can be redefined at build + time. + +### Strings + +When dealing with strings, they are almost always referenced and not copied +unless explicitly required. As such, no allocation/deallocation required either. + +```c +struct player { + const char *name; // Not allocated, no deallocation +``` + +## Ownership + +Alongside the memory handling comes the ownership. Related to the DVD scenario +explained above, not having to *own* a resource within a structure means no +allocation/deallocation required. + +Also, since C does not have a scoped mechanism, all fields in structured are +publicly available and to avoid allocating them on the heap they are always +declared to the user even if they need internal data. + +As a documentation notice, fields are always annotated using (XYZ) prefix with +some symbols to indicate whether user is allowed to touch or not. + +The letter *X* defines the following restriction + +`+` +: The property is readable/editable by the user, + +`-` +: The property is readable by the user, + +`*` +: The property is not meant to be used directly by the user. + +The letter *Y* can be set to `&` in that case means it is only referenced and is +not an owned property (usually a non-owning pointer). Which means user is +responsible for deallocation if required. + +The finall letter *Z* can be set to `?` which means it is optional (like a +nullable pointer). + +Examples: + +```c +struct foo { + int x; /*!< (+) Position in x. */ + int y; /*!< (+) Position in y. */ + struct theme *th; /*!< (+&?) Theme to use. */ + unsigned int elapsed; /*!< (-) Elapsed time since last frame. */ + struct texture text; /*!< (*) Texture used for rendering. */ +}; +``` + +Within this structure, the fields `x` and `y` are completely accessible to the +user for both reading/writing. The field `th` is an optional non-owning pointer +to a theme which is also readable/writable. The field `elapsed` is readable but +should not be modified. Finally, the field `text` is private and should not be +touched by the user. + +## Memory handling in Molko's Adventure API + +| | Dynamic allocation? | Notes | +|---------|---------------------|---------------------------------------------------------| +| libcore | None | The util.h provides convenient allocators for the user. | +| libui | None | | +| librpg | In map.h module | Maps are big chunk of data. |
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/docs/index.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,11 @@ +# Molko's Adventure documentation + +Welcome to the Molko's Adventure documentation. + +This documentation provides informations for both users of the game of the same +name and creators that desire to create their own game. + +## Introduction + +The Molko project is a framework for developing 2D RPG games in C. It is +designed in mind to be simple, fast, convenient, flexible and fun to use.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/docs/install.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,120 @@ +# Installation + +This page will explain how to build Molko's Adventure and libraries. + +## Requirements + +The following requirements are necessary to build the project. + +- C11 compiler: obviously, +- [CMake][]: the build system, +- [SDL2][]: the main game library, +- [SDL2_image][]: to load images, +- [SDL2_mixer][]: to play sounds and music, +- [SDL2_ttf][]: to open fonts, +- [Jansson][]: only for `mlk-tileset` and `mlk-map` tools. + +## Platforms supported + +The project has been tested on the following platforms. + +- Windows 10: only with [MSYS2][], Visual Studio **is not** supported yet. +- macOS 11.0 (Big Sur): using Xcode 12 and libraries from [brew][], +- Linux: on Alpine Linux (musl) and Arch Linux (glibc). + +## C and POSIX features + +Both of the API and the game are written using C99 and C11 but not all of the +features from both C versions are required. Here's a list of functionalities +that are required: + +### From C99 + +Features: + +- [Compound literals][] +- [inline] keyword + +Headers: + +- [stdbool.h][] + +Functions: + +- [snprintf][] +- [vsnprintf][] + +### From C11 + +- [stdnoreturn.h][] + +### From POSIX + +Expectations: + +- We use a few parts of [POSIX][] specification but try to keep its use limited + as not all platforms are POSIX compliant. +- We assume that `fopen`, `malloc` and friends set errno in case of failures. + +Functions: + +- [dirname][] +- [getopt][] + +Headers: + +- [libgen.h][] + +Macros: + +- `PATH_MAX`: in limits.h. + +!!! note + When a POSIX requirement isn't present it is replaced by a shim + specified for the platform. + +## Building with CMake + +Enter the source directory and type the following commands. In this example we +will use the "Unix Makefiles". + + mkdir build + cd build + cmake .. -DCMAKE_BUILD_TYPE=Debug + make + +!!! note + If you use a CMake generator that supports configuration types (e.g. Xcode, + Visual Studio) do not set `CMAKE_BUILD_TYPE`. + +### Available options + +The following CMake options are availble: + +`MOLKO_WITH_DOC` +: Enable documentation (default: On). + +`MOLKO_WITH_EXAMPLES` +: Build examples (default: On). + +`MOLKO_WITH_TESTS` +: Build tests (default: On). + +[CMake]: http://cmake.org +[Compound literals]: https://en.cppreference.com/w/c/language/compound_literal +[Jansson]: https://digip.org/jansson +[MSYS2]: https://www.msys2.org +[POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799 +[SDL2]: http://libsdl.org +[SDL2_image]: https://www.libsdl.org/projects/SDL_image +[SDL2_mixer]: https://www.libsdl.org/projects/SDL_mixer +[SDL2_ttf]: https://www.libsdl.org/projects/SDL_ttf +[brew]: https://brew.sh +[dirname]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/dirname.html +[getopt]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getopt.html +[inline]: https://en.cppreference.com/w/c/language/inline +[libgen.h]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/libgen.h.html +[snprintf]: https://en.cppreference.com/w/c/io/fprintf +[vsnprintf]: https://en.cppreference.com/w/c/io/fprintf +[stdbool.h]: https://en.cppreference.com/w/c/language/arithmetic_types#Boolean_type +[stdnoreturn.h]: https://en.cppreference.com/w/c/types
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/docs/specs/map.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,107 @@ +# 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 [tileset](tileset.md), 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. + + 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. + + 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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/docs/specs/tileset.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,92 @@ +# 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. + +Tilesets have an extension of `.tileset`. + +## 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. + + 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. + + 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. + + 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. + + 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/docs/tools/bcc.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,39 @@ +# 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: + +-0 +: Terminate the array with a NUL terminator. + +-c +: Generate a ``const`` C array. + +-s +: Generate a ``static`` C array. + +-u +: Use ``unsigned char`` instead of ``signed char`` when generating the byte + array. + +-I num +: Use ``num`` tabs to indent (defaults to 1). + +-i num +: Use ``num`` spaces to indent. + +filename +: Filename to read as input, a value of ``-`` will read the standard input. + +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/docs/tools/map.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,11 @@ +# Tool: mlk-map + +Convert a map generated from [Tiled][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/docs/tools/tileset.md Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,11 @@ +# 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/doxybook.json Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,19 @@ +{ + "baseUrl": "/", + "indexInFolders": true, + "linkSuffix": "/", + "indexClassesName": "index", + "indexFilesName": "index", + "indexGroupsName": "index", + "indexNamespacesName": "index", + "indexRelatedPagesName": "index", + "indexExamplesName": "index", + "mainPageInRoot": true, + "mainPageName": "index", + "folderClassesName": "classes", + "folderExamplesName": "examples", + "folderFilesName": "files", + "folderGroupsName": "modules", + "folderNamespacesName": "namespaces", + "folderRelatedPagesName": "pages" +}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/doxygen/groups.c Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,47 @@ +/* + * groups.c -- describe "Modules" in Doxygen + * + * Copyright (c) 2020 David Demelier <markand@malikania.fr> + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +/** + * \defgroup actions Actions + * \brief Predefined actions. + */ + +/** + * \defgroup states States + * \brief Predefined states. + */ + +/** + * \defgroup basics Basics + * \brief Basics utilities. + */ + +/** + * \defgroup drawing Drawing + * \brief Modules for rendering on the screen. + */ + +/** + * \defgroup input Input and events + * \brief Input and event handling. + */ + +/** + * \defgroup ui UI + * \brief User interface elements. + */
--- a/doc/index.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,33 +0,0 @@ -=============================== -Molko's Adventure documentation -=============================== - -Welcome to the Molko's Adventure documentation. - -This documentation provides informations for both users of the game of the same -name and creators that desire to create their own game. - -Introduction ------------- - -The Molko project is a framework for developing 2D RPG games in C. It is -designed in mind to be simple, fast, convenient, flexible and fun to use. - -Contents --------- - -.. toctree:: - :maxdepth: 1 - - about - build - specifications - tools - api - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search`
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/mkdocs.yml Fri Nov 27 17:00:30 2020 +0100 @@ -0,0 +1,45 @@ +# +# mkdocs.yml.txt -- documentation for Molko's Adventure +# +# Copyright (c) 2020 David Demelier <markand@malikania.fr> +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +# + +site_name: Molko's Adventure +theme: material +markdown_extensions: + - admonition + - tables + - def_list +nav: + - Home: index.md + - About: about.md + - Installation: install.md + - Specifications: + - map: specs/map.md + - tileset: specs/tileset.md + - Tools: + - mlk-bcc: tools/bcc.md + - mlk-map: tools/map.md + - mlk-tileset: tools/tileset.md + - Developer corner: + - Notes: + - Error handling: dev/error.md + - Ownership: dev/ownership.md + - FAQ: dev/faq.md + - Howto: + - dev/howto/01-init.md + - API Reference: + - Modules: modules/index.md + - Files: files/index.md
--- a/doc/spec-map.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,117 +0,0 @@ -.. 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 Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,102 +0,0 @@ -.. 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. - -Tilesets have an extension of ``.tileset``. - -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
--- a/doc/specifications.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,23 +0,0 @@ -.. 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 - spec-map - -.. _conventions over configuration: https://en.wikipedia.org/wiki/Convention_over_configuration
--- a/doc/tool-bcc.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,51 +0,0 @@ -============= -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.
--- a/doc/tool-map.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ -============= -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
--- a/doc/tool-tileset.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ -================= -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
--- a/doc/tools.rst Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ -===== -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
--- a/doxygen/CMakeLists.txt Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,77 +0,0 @@ -# -# CMakeLists.txt -- CMake build system for doxygen -# -# Copyright (c) 2020 David Demelier <markand@malikania.fr> -# -# Permission to use, copy, modify, and/or distribute this software for any -# purpose with or without fee is hereby granted, provided that the above -# copyright notice and this permission notice appear in all copies. -# -# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -# - -project(doxygen) - -find_package(Doxygen QUIET) - -if (DOXYGEN_FOUND) - set( - INPUT - doxygen/groups.c - doxygen/mainpage.c - doxygen/page-faq.c - doxygen/page-howto-error.c - doxygen/page-howto-initialization.c - doxygen/page-howto-ownership.c - doxygen/page-portability.c - libcore - libui - librpg - ) - - set( - DOXYGEN_STRIP_FROM_PATH - ${CMAKE_SOURCE_DIR}/libcore - ${CMAKE_SOURCE_DIR}/libui - ${CMAKE_SOURCE_DIR}/librpg - ) - - set(DOXYGEN_SHOW_GROUPED_MEMB_INC NO) - set(DOXYGEN_SHOW_INCLUDE_FILES NO) - set(DOXYGEN_ALLOW_UNICODE_NAMES YES) - set(DOXYGEN_AUTOLINK_SUPPORT NO) - set(DOXYGEN_ENABLE_PREPROCESSING YES) - set(DOXYGEN_EXAMPLE_PATH examples) - set(DOXYGEN_EXCLUDE_PATTERNS *_p.h) - set(DOXYGEN_FILE_PATTERNS *.h) - set(DOXYGEN_GENERATE_LATEX NO) - set(DOXYGEN_GENERATE_MAN NO) - set(DOXYGEN_GENERATE_XML YES) - set(DOXYGEN_GENERATE_HTML NO) - set(DOXYGEN_INPUT_ENCODING UTF-8) - set(DOXYGEN_MAX_INITIALIZER_LINES 0) - set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) - set(DOXYGEN_OUTPUT_DIRECTORY doxygen) - set(DOXYGEN_PREDEFINED DOXYGEN) - set(DOXYGEN_PROJECT_BRIEF "2D RPG game in C") - set(DOXYGEN_PROJECT_NAME "Molko's Adventure") - set(DOXYGEN_QUIET YES) - set(DOXYGEN_RECURSIVE YES) - set(DOXYGEN_TAB_SIZE 8) - set(DOXYGEN_WARNINGS YES) - - doxygen_add_docs( - doxygen - ${INPUT} - ALL - WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}" - ) - - set_target_properties(doxygen PROPERTIES FOLDER misc) -endif ()
--- a/doxygen/groups.c Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,47 +0,0 @@ -/* - * groups.c -- describe "Modules" in Doxygen - * - * Copyright (c) 2020 David Demelier <markand@malikania.fr> - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR - * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF - * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - */ - -/** - * \defgroup actions Actions - * \brief Predefined actions. - */ - -/** - * \defgroup states States - * \brief Predefined states. - */ - -/** - * \defgroup basics Basics - * \brief Basics utilities. - */ - -/** - * \defgroup drawing Drawing - * \brief Modules for rendering on the screen. - */ - -/** - * \defgroup input Input and events - * \brief Input and event handling. - */ - -/** - * \defgroup ui UI - * \brief User interface elements. - */
--- a/doxygen/mainpage.c Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,71 +0,0 @@ -/* - * mainpage.c -- describe "Main Page" in Doxygen - * - * Copyright (c) 2020 David Demelier <markand@malikania.fr> - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES - * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF - * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR - * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES - * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN - * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF - * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - */ - -/** - * \mainpage - * - * Welcome to the Molko's reference API. - * - * # About - * - * Molko's Adventure is a 2D solo RPG written in pure C, using SDL2 and SDL2 - * addons. - * - * As its heart, the game is split into multiple parts, libraries, game data and - * game code. - * - * - It is not a game engine! Many aspects in the core are still tightly coupled - * with the original game design. We wanted the core to be kept simple without - * thousands of dynamic allocations and genericity all over the place. - * - It is not meant to be used as system library. Functions were kept simple - * and not prefixed by any "namespace"-like word. Instead, it is meant to be - * bundled with your game as boilerplate code with the possibility for you to - * change all internals if you want. - * - * # Usage - * - * If you plan to create your own game, simply copy the whole directory - * directory to your project and select which libraries you need. - * - * \note If you find a bug regarding your platform, feel free to send bug - * reports and patches. - * - * Then, check this API or read .h files for documentation. The files ending - * with _p.h are usually reserved for the implementation and should not be used - * unless you know what you're doing. - * - * # Libraries - * - * The following libraries are available and built separately: - * - * | Library | Description | Dependencies | - * |---------|----------------------------------------------|----------------------------------------| - * | libcore | Low level audio, video, windowing and input. | SDL2, SDL2_mixer, SDL2_ttf, SDL2_image | - * | libui | Minimalist UI routines to draw interfaces | libcore | - * | librpg | Group of modules related to RPG games | libcore, libui | - * - * ## Thread safety and reentrancy - * - * The core API is **not** thread-safe at all. Any module must always be used in - * a single thread unless you really know what you're doing. - * - * Most of the API is reentrant though except the some modules which use global - * objects. - * - * \note This may change in the future. - */
--- a/doxygen/page-faq.c Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,67 +0,0 @@ -/** - * \page faq FAQ - * \tableofcontents - * - * # Why not creating a game engine? - * - * Game engines are usually too generic, too complex and do too much things. - * Lots of them also use scripting language which require another learning curve - * to be used. - * - * Molko's Adventure is a solo tactical 2D RPG and its core is especially - * designed for that gameplay. Thus the code stay simple to understand and to - * follow. Coupling a general purpose game engine with a game design is - * sometimes more complicated than writing small code. - * - * However, game engines are still interesting for people who already know how - * to use them and feel confident with them. - * - * # Why no prefix like "ma_" or "MA_"? - * - * See also question above. - * - * The purpose of Molko's Adventure is not to provide a drop-in reusable library - * to create RPG games. It is highly coupled with the gameplay of the original - * game. Thus we wanted to keep the codebase extremely simple and minimalist - * without adding bunch of genericity. - * - * The core API isn't meant to be installed system wide (possible, but not - * recommended), instead users are encouraged to copy the core code and to adapt - * to their gameplay. - * - * A simple example: if someone wants to create a game and would like to allow - * only three playable entities at a time, it should simply edit appropriates - * structures and everything is adapted. Then, structures and array can stay - * static without dynamic allocations. - * - * # Why C instead of <FOO>? - * - * C is an awesome language. It still has its place in the industry especially - * in low-level, kernel and game design. - * - * Games are usually designed without OO in mind using simple procedural codes - * and lots of data. In C, writing code makes easier to understand what's - * happening under the hood without having to check if functions will generate - * dynamic allocations or not. - * - * However, we also love modernity and as such, C11 is the minimal requirement - * to build and run Molko's Adventure. - * - * \note The code does not make any assumption about the platform it runs, it - * expects to have a fully conformant C11 implementation. Microsoft MSVC - * is known to **not** support this C version. - * - * # Can I make a MMORPG with that? - * - * Not easily. - * - * This core API is really tied to a unique solo RPG adventure and therefore it - * does not separate logic from rendering. - * - * Also, note that creating a server-client game is really different in terms of - * architecture than a local solo game. Most of the logic part is done server - * side and requires much more code to analyze to avoid cheats, lag, - * synchronisation and many other stuff than a local game does not require. - * - * There are no plans to create a network oriented core API anytime soon. - */
--- a/doxygen/page-howto-error.c Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,76 +0,0 @@ -/** - * \page howto-error Howto: error handling - * \tableofcontents - * - * How error handling is used within the API and the user code. - * - * # Synopsis - * - * Error handling is always a complicated task in the software development. In - * Molko's Adventure there is three kinds of errors: - * - * 1. Programming error. - * 2. Recoverable error at runtime. - * 3. Unexpected error at runtime. - * - * # Kind of errors - * - * ## Assertions - * - * One of the easiest errors to detect are about programming errors. In the - * Molko's Adventure API they are usually detected at runtime when you use a - * function with preconditions unmet. In that case standard C `assert` is used. - * - * For example, it happens when you: - * - * - Pass a NULL pointer where the function expects non-NULL, - * - Pass invalid arguments such as out of bounds indicies. - * - * Always read carefully preconditions that are annotated through the - * documentation. - * - * ## Recoverable errors - * - * Next, come recoverable errors. Those arise when you may expect a failure from - * the API and can do something else. - * - * For example, it happens when you: - * - * - Open a font file that is invalid, - * - Open a music file that is no longer on the disk. - * - * In these situations, the API indicates usually by a return code that the - * function was unable to complete correctly (and you can use \ref error to - * retrieve the specified error). In some case, you *MUST* not ignore the return - * value because if the function takes an input as argument it will be kept - * untouched. For example, the \ref texture_new function may fail to create a - * texture and in that case it is left untouched. - * - * ## Unexpected errors - * - * Finally, come what we call unexpected errors. Those happen while they are not - * supposed to. - * - * For example, it happens when there is a severe issue either in the kernel, - * graphics or any other library that aren't raised by the API itself. - * - * This includes (but not limited to): - * - * - A rendering error (caused by an internal issue). - * - * In these situations, the API calls the function \ref panic which definitely - * calls the \ref panic_handler. The default implementation prints an error and - * exit with a code of 1. User may pass a custom function but should quit the - * game because the API does not take care of deallocating data before calling - * panic. - * - * # Error handling in Molko's Adventure API - * - * The following table shows what is used and when. - * - * | | `assert` | Booleans | panic | Notes | - * |---------|--------------------|---------------------|-------------------------------------------|-----------------------------------| - * | libcore | Programming errors | As much as possible | Only in memory utilities from util.h | Never called from libcore itself. | - * | libui | Programming errors | When applicable | Mostly in rendering errors | None. | - * | librpg | Programming errors | When applicable | Mostly in rendering errors | None. | - */
--- a/doxygen/page-howto-initialization.c Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,39 +0,0 @@ -/** - * \page howto-init Howto: initialization - * \tableofcontents - * - * Howto initialize the core. - * - * \section synopsis Synopsis - * - * Before using the core, you need to initialize the subsystems and internal - * backend API. - * - * \warning Even non-rendering modules requires initialization and some of them - * even require a window to be open. - * - * \section usage Usage - * - * The following table summarize the functions to be used at the beginning and - * the end of your game. - * - * | System | Init function | Close function | Remarks | - * |---------|------------------|--------------------|------------------------| - * | General | sys_init | sys_finish | Required for most API | - * | Window | window_init | window_finish | Required by some parts | - * - * All init functions set an error code if any and you're encouraged to test the - * result and check the error if any. - * - * \section example Example - * - * Init the core and create a window of Full HD resolution. The function \ref - * panic will all the panic handler. - * - * \code - * if (!sys_init()) - * panic(); - * if (!window_init("My Awesome Game", 1920, 1080)) - * panic(); - * \endcode - */
--- a/doxygen/page-howto-ownership.c Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,120 +0,0 @@ -/** - * \page howto-ownership Howto: ownership and memory management - * \tableofcontents - * - * How memory and ownership is used within Molko's Adventure API. - * - * # Synopsis - * - * In C, memory management can be a cumbersome issue and a major common complain - * when it comes to leak. - * - * As such, the API itself does not use dynamic allocations in most of the case. - * Instead it is kept to the user responsability to handle storage of data. In - * that manner the code stays simpler, stronger and more flexible. The API - * itself does not have to deal with memory management and deallocation, it only - * expect data from user and work with that. - * - * You can imagine a situation with a DVD player and some movies on DVDs. You - * have one DVD player where you put some DVDs inside but the DVD player never - * make its own copy, it simply reads your disc and you get it back afterwards. - * - * Following this philosophy, the Molko's Adventure API for this scenario would - * look like this: - * - * ```c - * struct dvd_player player; - * struct dvd dvd; - * - * dvd_open(&dvd, "/dev/sr0"); - * - * dvd_player_turn_on(); - * dvd_player_insert(&player, &dvd); - * dvd_player_play(&player); - * dvd_player_turn_off(); - * ``` - * - * # Memory handling - * - * ## Arrays - * - * Some modules in the API may require an array. Depending on the situation they - * can be passed as parameter or are usually of a fixed reasonable size in - * structures. - * - * They are always annotated with a macro to let the user flexibility over it if - * necessary. - * - * Example, a player has a set of spells. - * - * ```c - * #define PLAYER_SPELL_MAX (16) - * - * struct player { - * struct spell *spells[PLAYER_SPELL_MAX]; - * }; - * ``` - * - * ## Strings - * - * When dealing with strings, they are almost always referenced and not copied - * unless explicitly required. As such, no allocation/deallocation required - * either. - * - * ```c - * struct player { - * const char *name; // Not allocated, no deallocation - * ``` - * - * # Ownership - * - * Alongside the memory handling comes the ownership. Related to the DVD - * scenario explained above, not having to *own* a resource within a structure - * means no allocation/deallocation required. - * - * Also, since C does not have a scoped mechanism, all fields in structured are - * publicly available and to avoid allocating them on the heap they are always - * declared to the user even if they need internal data. - * - * As a documentation notice, fields are always annotated using (XYZ) prefix - * with some symbols to indicate whether user is allowed to touch or not. - * - * The letter *X* defines the following restriction - * - * - `+`: The property is readable/editable by the user, - * - `-`: The property is readable by the user, - * - `*`: The property is not meant to be used directly by the user. - * - * The letter *Y* can be set to `&` in that case means it is only referenced - * and is not an owned property (usually a non-owning pointer). Which means - * user is responsible for deallocation if required. - * - * The finall letter *Z* can be set to `?` which means it is optional (like a - * nullable pointer). - * - * Examples: - * - * ```c - * struct foo { - * int x; // (+) Position in x. - * int y; // (+) Position in y. - * struct theme *th; // (+&?) Theme to use. - * unsigned int elapsed; // (-) Elapsed time since last frame. - * struct texture text; // (*) Texture used for rendering. - * }; - * ``` - * - * Within this structure, the fields `x` and `y` are completely accessible to - * the user for both reading/writing. The field `th` is an optional non-owning - * pointer to a theme which is also readable/writable. The field `elapsed` is - * readable but should not be modified. Finally, the field `text` is private - * and should not be touched by the user. - * - * # Memory handling in Molko's Adventure API - * - * | | Dynamic allocation? | Notes | - * |---------|---------------------|---------------------------------------------------------| - * | libcore | None | The util.h provides convenient allocators for the user. | - * | libui | None | | - * | librpg | In map.h module | Maps are big chunk of data. | - */
--- a/doxygen/page-portability.c Fri Nov 27 13:32:52 2020 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,34 +0,0 @@ -/** - * \page portability Portability - * \tableofcontents - * - * A note about portability in Molko's Adventure API. - * - * # C standard used - * - * The code is based mostly written in C99 with a subset of C11. The following - * features from C11 are required: - * - * - `<stdnoreturn.h>` header. - * - * # POSIX - * - * A few routines from the POSIX specification are also used: - * - * - `<sys/stat.h>` header. - * - `read(2)` function. - * - `open(2)` function. - * - `getopt(3)`, - * - `fmemopen(3)`. - * - * Efforts are ongoing to provide fallback implementations for systems that lack - * those functionalities. - * - * # System tested - * - * - macOS (10.15 and later), - * - Linux (glibc and musl variants), - * - FreeBSD, NetBSD and OpenBSD. - * - * Windows is currently not supported right now but will be in the future. - */