Mercurial > molko
changeset 77:837ef1d387b4
doc: improve documentation
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 31 Jan 2020 13:48:27 +0100 |
parents | 25a52025c8f5 |
children | 1bd1233b4cbc |
files | doxygen/Doxyfile doxygen/page-faq.c doxygen/page-howto-initialization.c src/core/error.h src/core/event.h |
diffstat | 5 files changed, 164 insertions(+), 39 deletions(-) [+] |
line wrap: on
line diff
--- a/doxygen/Doxyfile Fri Jan 31 13:48:16 2020 +0100 +++ b/doxygen/Doxyfile Fri Jan 31 13:48:27 2020 +0100 @@ -29,10 +29,15 @@ AUTOLINK_SUPPORT = NO QUIET = YES WARNINGS = YES -INPUT = doxygen/groups.c doxygen/mainpage.c src +INPUT = doxygen/groups.c \ + doxygen/mainpage.c \ + doxygen/page-howto-initialization.c \ + doxygen/page-faq.c \ + src INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.h RECURSIVE = YES EXCLUDE_PATTERNS = *_p.h GENERATE_LATEX = NO GENERATE_MAN = YES +MAX_INITIALIZER_LINES = 0
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doxygen/page-faq.c Fri Jan 31 13:48:27 2020 +0100 @@ -0,0 +1,78 @@ +/** + * \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, C18 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 C18 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. + * + * # Can I write an action RPG like Zelda? + * + * Probably. + * + * Do not use the battle system provided and then depending on your game you + * may: + * + * - Edit the \ref map_state.h module to your needs (you may also simply define + * your own input/update handler instead), + * - Create a dedicated state and use \ref map.h if you want. + */
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doxygen/page-howto-initialization.c Fri Jan 31 13:48:27 2020 +0100 @@ -0,0 +1,39 @@ +/** + * \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 | \ref sys_init | \ref sys_close | Required for most API | + * | Window | \ref window_init | \ref window_close | 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 + * error_fatal will print the error and exit if needed. + * + * \code + * if (!sys_init()) + * error_fatal(); + * if (!window_init("My Awesome Game", 1920, 1080)) + * error_fatal(); + * \endcode + */
--- a/src/core/error.h Fri Jan 31 13:48:16 2020 +0100 +++ b/src/core/error.h Fri Jan 31 13:48:27 2020 +0100 @@ -38,7 +38,7 @@ error(void); /** - * Convenient handler that sets last error from global C errno and then return + * Convenient helper that sets last error from global C errno and then return * false. * * \return false @@ -56,7 +56,7 @@ error_printf(const char *fmt, ...); /** - * Similar to \a error_printf. + * Similar to \ref error_printf. * * \param fmt the format stinrg * \param ap the variadic arguments pointer @@ -72,7 +72,7 @@ error_fatal(void); /** - * Prints an error to stderr and exit. + * Prints an error to stderr and exit with code 1. * * \param fmt the format string */ @@ -80,7 +80,7 @@ error_fatalf(const char *fmt, ...); /** - * Similar to \a error_fatalf + * Similar to \ref error_fatalf. * * \param fmt the format string * \param ap the variadic arguments pointer
--- a/src/core/event.h Fri Jan 31 13:48:16 2020 +0100 +++ b/src/core/event.h Fri Jan 31 13:48:27 2020 +0100 @@ -34,47 +34,50 @@ * \brief Kind of event. */ enum event_type { - EVENT_CLICKDOWN, /*!< Mouse click down */ - EVENT_CLICKUP, /*!< Mouse click released */ - EVENT_KEYDOWN, /*!< Single key down */ - EVENT_KEYUP, /*!< Single key released */ - EVENT_MOUSE, /*!< Mouse moved */ + EVENT_CLICKDOWN, /*!< Mouse click down (\ref event_click) */ + EVENT_CLICKUP, /*!< Mouse click released (\ref event_click) */ + EVENT_KEYDOWN, /*!< Single key down (\ref event_key) */ + EVENT_KEYUP, /*!< Single key released (\ref event_key) */ + EVENT_MOUSE, /*!< Mouse moved (\ref event_mouse) */ EVENT_QUIT, /*!< Quit request */ }; /** + * \brief Key event. + */ +struct event_key { + enum event_type type; /*!< EVENT_KEYDOWN or EVENT_KEYUP */ + enum key key; /*!< Which key */ +}; + +/** + * \brief Mouse motion event. + */ +struct event_mouse { + enum event_type type; /*!< EVENT_MOUSE */ + enum mouse_button buttons; /*!< OR'ed buttons that are pressed */ + int x; /*!< Mouse position in x */ + int y; /*!< Mouse position in y */ +}; + +/** + * \brief Mouse click event. + */ +struct event_click { + enum event_type type; /*!< EVENT_CLICKDOWN or EVENT_CLICKUP */ + enum mouse_button button; /*!< Unique button that was pressed */ + int x; /*!< Mouse position in x */ + int y; /*!< Mouse position in y */ +}; + +/** * \brief Store events. */ union event { - enum event_type type; /*!< Which kind of event */ - - /** - * Store key down/up event. - */ - struct { - enum event_type type; /*!< EVENT_KEYDOWN or EVENT_KEYUP */ - enum key key; /*!< Which key */ - } key; - - /** - * Store mouse motion event. - */ - struct { - enum event_type type; /*!< EVENT_MOUSE */ - enum mouse_button buttons; /*!< OR'ed buttons that are pressed */ - int x; /*!< Mouse position in x */ - int y; /*!< Mouse position in y */ - } mouse; - - /** - * Store mouse click event. - */ - struct { - enum event_type type; /*!< EVENT_CLICKDOWN or EVENT_CLICKUP */ - enum mouse_button button; /*!< Unique button that was pressed */ - int x; /*!< Mouse position in x */ - int y; /*!< Mouse position in y */ - } click; + enum event_type type; /*!< Which kind of event */ + struct event_key key; /*!< Key event */ + struct event_mouse mouse; /*!< Mouse motion event */ + struct event_click click; /*!< Mouse click event */ }; /**