Mercurial > molko
changeset 312:4ea0f035f712
doc: update according to new game API
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 09 Sep 2021 15:30:07 +0200 |
parents | f10fd1293a7e |
children | dbfe05b88627 |
files | doc/docs/cmake/MolkoBuildAssets.md doc/docs/cmake/MolkoBuildMaps.md doc/docs/cmake/MolkoBuildTilesets.md doc/docs/cmake/MolkoBuildTranslations.md doc/docs/cmake/MolkoDefineExecutable.md doc/docs/cmake/MolkoDefineLibrary.md doc/docs/cmake/MolkoDefineTest.md doc/docs/cmake/MolkoSetBuildDirectories.md doc/docs/cmake/MolkoSetCompilerFlags.md doc/docs/dev/api/core/game.md doc/mkdocs.yml |
diffstat | 10 files changed, 35 insertions(+), 255 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/docs/cmake/MolkoBuildAssets.md Thu Sep 09 13:57:54 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,27 +0,0 @@ -# molko_build_assets - -Generate custom commands to convert assets into C header files using mlk-bcc. -The argument output will be set to contain every generated output so that the -caller can set them as source input and be generated before the target itself. - -## Synopsis: - -```cmake -molko_build_assets(assets outputs) -``` - -## Example - -```cmake -molko_build_assets(image.png outputs) -add_executable(main main.c ${outputs}) -``` - -Do not forget to add the CMake current binary directory -`${CMAKE_CURRENT_BINARY_DIR}` through the include flags of the given target. - -Each file is generated using the exact same file hierarchy as the input so -an input of foo/bar/baz.png will be generated as foo/bar/baz.h in the binary -directory. The exported symbol use the pattern <last-directory>_<basename> so -in the above example, the file variable would be "bar_baz" -
--- a/doc/docs/cmake/MolkoBuildMaps.md Thu Sep 09 13:57:54 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,24 +0,0 @@ -# molko_build_maps - -Convert [Tiled][] maps and tilesets into textual representations that can be -loaded from Molko's Adventure API. - -## Synopsis - -```cmake -molko_build_maps( -OUTPUT_DIR output directory -OUTPUTS output variables -MAPS (Optional) List of maps -TILESETS (Optional) List of tilesets -) -``` - -Argument MAPS and TILESETS should contain list of .json files generated from -[Tiled][tiled] and store the result in OUTPUT_DIR - -Arguments OUTPUTS will be filled with genereted files from CMake and can be -used as executable and input. - -[Tiled]: http://mapeditor.org -
--- a/doc/docs/cmake/MolkoBuildTranslations.md Thu Sep 09 13:57:54 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,37 +0,0 @@ -# molko_build_translations - -Build translations and update them. - -## Synopsis - -```cmake -molko_build_translations( -TARGET target name -SOURCES target sources -OUTPUTS output variable -TRANSLATIONS list of localizations -) -``` - -Generate target and output commands for NLS (via GNU gettext) support for the -given *TARGET* name. - -The argument *SOURCES* must contain sources to extract gettext keywords, it -will search for _, N_. The list of *SOURCES* can contain any files, only .c -and .h will be filtered. - -The argument *OUTPUTS* will be set with the generated .mo files in the binary -directory and installed to *CMAKE_INSTALL_LOCALEDIR*. - -The argument *TRANSLATIONS* should contain a list of languages supported in the -gettext form (ll_LL@variant, see ISO 639 and ISO 3166 for more details). - -This macro create a `<TARGET>-po` target that will recreate the .pot file and -every .po files in the nls/ directory for each language specified in -*TRANSLATIONS*. Note, if you add a new language into translations but do not -copy the .pot file, a warning will be issued and you should copy the .pot -file as the new .po language file. - -Since the target is modifying files directly in the source tree they are not -included in any build process and must be invoked manually. -
--- a/doc/docs/cmake/MolkoDefineExecutable.md Thu Sep 09 13:57:54 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,31 +0,0 @@ -# molko_define_executable - -Create an executable. - -## Synopsis - -```cmake -molko_define_test( -TARGET target name -SOURCES src1, src2, srcn -FOLDER (Optional) IDE folder if supported -TRANSLATIONS (Optional) list of translations -ASSETS (Optional) list of assets to build -FLAGS (Optional) C flags (without -D) -LIBRARIES (Optional) libraries to link -INCLUDES (Optional) includes -INSTALL (Optional) create install target -) -``` - -Create an executable with the name *TARGET* with the given *SOURCES*. - -Optional include paths, libraries and flags can be specified via *INCLUDES*, -*LIBRARIES* and *FLAGS* arguments respectively. - -If argument *ASSETS* is set, they are generated in the target binary -directory. - -The optional argument *TRANSLATIONS* should contain a list of supported -translations. See molko_build_translations for more info. -
--- a/doc/docs/cmake/MolkoDefineLibrary.md Thu Sep 09 13:57:54 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,45 +0,0 @@ -# molko_define_library - -Create any kind of library. - -## Synopsis - -```cmake -molko_define_library( -TARGET target name -SOURCES src1, src2, srcn -EXTERNAL (Optional) set to true for external libraries -FOLDER (Optional) optional subfolder to organize -TYPE (Optional) type of library -LIBRARIES (Optional) libraries to link -FLAGS (Optional) C flags (without -D) -INCLUDES (Optional) local includes for the target only -) -``` - -Create a library and optionally install it. - -The function create a new library named with the parameter *TARGET*, you -should prefix it with "lib" as its the convention within molko (e.g. libfoo), -the prefix is automatically removed. - -The argument *SOURCES* should contains the C source files and *HEADERS* -should points to a directory to be installed verbatim in the include -directory. - -Optional argument *EXTERNAL* should be set for targets that are not -maintained here (e.g. third party libraries embedded). - -The optional arguments *LIBRARIES*, *FLAGS* and *INCLUDES* are passed to the -respective CMake command [target_link_libraries][], -[target_compile_definitions][] and [target_include_directories][] -respectively. As such, it is necessary to specify the scope (PUBLIC, PRIVATE -or INTERFACE) for every argument. - -If *FOLDER* option is set, it is organized into its name under the IDE if -supported. - -[target_compile_definitions]: https://cmake.org/cmake/help/latest/command/target_compile_definitions.html -[target_include_directories]: https://cmake.org/cmake/help/latest/command/target_include_directories.html -[target_link_libraries]: https://cmake.org/cmake/help/latest/command/target_link_libraries.html -
--- a/doc/docs/cmake/MolkoDefineTest.md Thu Sep 09 13:57:54 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,26 +0,0 @@ -# molko_define_test - -Create unit test. - -## Synopsis - -```cmake -molko_define_test( -TARGET target name -SOURCES src1, src2, srcn -ASSETS (Optional) list of assets to build -FLAGS (Optional) C flags (without -D) -LIBRARIES (Optional) libraries to link -INCLUDES (Optional) includes -) -``` - -Create an executable with the name *TARGET* and a test case of the same name -with the given *SOURCES*. - -Optional include paths, libraries and flags can be specified via *INCLUDES*, -*LIBRARIES* and *FLAGS* arguments respectively. - -If argument *ASSETS* is set, they are generated in the target binary -directory. -
--- a/doc/docs/cmake/MolkoSetBuildDirectories.md Thu Sep 09 13:57:54 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ -# molko_set_build_directories - -Change build directories for the given target. - -## Synopsis - -```cmake -molko_set_build_directories(target) -``` - -This function will set output directories for the given target. It is -necessary so that binaries can know where to find extra data. -
--- a/doc/docs/cmake/MolkoSetCompilerFlags.md Thu Sep 09 13:57:54 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ -# molko_set_compiler_flags - -Set default compiler flags for the given target. - -## Synopsis - -```cmake -molko_set_compiler_flags(target) -``` - -This function will adds some compiler flags for the development such as -warnings, sanitizers if the compiler is compatible. -
--- a/doc/docs/dev/api/core/game.md Thu Sep 09 13:57:54 2021 +0200 +++ b/doc/docs/dev/api/core/game.md Thu Sep 09 15:30:07 2021 +0200 @@ -12,9 +12,8 @@ is designed to help switching game states and inhibit some of the functions when necessary. -In contrast to popular engines, states are not stacked and only one is used at a -time. Switching states mean that the current state will run until next frame and -will be closed afterwards. +States are pushed and removed from the stack as a LIFO queue, the last pushed +state will be the first state to be removed. The main loop use a constant frame rate mechanism based on the screen refresh rate if supported, otherwise it use a default frame rate of 60hz. In any case, @@ -40,39 +39,46 @@ | Field | Access | Type | |---------------------------|--------|------------------| | [inhibit](#inhibit) | (+) | `enum inhibit` | -| [state](#state) | (+&?) | `struct state *` | -| [state_next](#state_next) | (+&?) | `struct state *` | #### inhibit Current inhibit flags set, see [inhibit](inhibit.md) for more information. -#### state - -Current state running. - -#### state\_next - -Optional next state to be changed in next frame loop. - ## Functions -### game\_switch - -Set `state` for the next frame. +### game\_init -The state will only be effective after the next call to -[game_update](#game_update). - -If argument `quick` is non-zero, the state is changed immediately and the -current state code should immediately return. +Initialize the game. This isn't required unless [game_quit](#game_quit) was +called. ```c void -game_switch(struct state *state, int quick) +game_init(void) ``` -#### game\_handle +### game\_push + +Push `state` into the stack. If there is a current running state, it is +suspended through the defined callback. + +The argument `state` must remain valid until the lifetime of the game. + +```c +void +game_push(struct state *state) +``` + +### game\_pop + +Remove the last state and invoke finalizer callbacks (end, finish). If there is +a previous state into the stack, it is resumed through the defined callback. + +```c +void +game_pop(void) +``` + +### game\_handle Handle the event `ev` into the current state. @@ -81,16 +87,16 @@ game_handle(const union event *ev) ``` -#### game\_update +### game\_update -Update the current state with `ticks` since last frame. +Update the current state with `ticks` (in milliseconds) since last frame. ```c void game_update(unsigned int ticks) ``` -#### game\_draw +### game\_draw Draw the current state. @@ -99,7 +105,7 @@ game_draw(void) ``` -#### game\_loop +### game\_loop Start a blocking loop that call in order [game_handle](#game_handle), [game_update](#game_update) and [game_draw](#game_draw) while keeping a constant @@ -110,9 +116,9 @@ game_loop(void) ``` -#### game\_stop +### game\_quit -Destroy both next and current state if any. +Destroy all states. Even if you don't use [game_loop](#game_loop) you should call this function because it will close state resources.
--- a/doc/mkdocs.yml Thu Sep 09 13:57:54 2021 +0200 +++ b/doc/mkdocs.yml Thu Sep 09 15:30:07 2021 +0200 @@ -42,16 +42,6 @@ - FAQ: dev/faq.md - Howto: - dev/howto/01-init.md - - CMake macros: - # Don't edit manually, generated from top cmake/*.cmake files. - - cmake/MolkoBuildAssets.md - - cmake/MolkoBuildMaps.md - - cmake/MolkoBuildTranslations.md - - cmake/MolkoDefineExecutable.md - - cmake/MolkoDefineLibrary.md - - cmake/MolkoDefineTest.md - - cmake/MolkoSetBuildDirectories.md - - cmake/MolkoSetCompilerFlags.md - API Reference: - libmlk-core: - action: dev/api/core/action.md