| 1 | ## Adding 'enhanced' core options to a core |
| 2 | |
| 3 | The basic steps for updating a core to support core options v1 are as follows: |
| 4 | |
| 5 | - Copy `example_default/libretro_core_options.h` to the same directory as `libretro.c/.cpp` |
| 6 | |
| 7 | - Copy `example_default/libretro_core_options_intl.h` to the same directory as `libretro.c/.cpp` |
| 8 | |
| 9 | - Add `#include "libretro_core_options.h"` to `libretro.c/.cpp` |
| 10 | |
| 11 | - Replace any existing calls of `RETRO_ENVIRONMENT_SET_VARIABLES` with `libretro_set_core_options(retro_environment_t environ_cb)` |
| 12 | (Note: `libretro_set_core_options()` should be called as early as possible - preferably in `retro_set_environment()` |
| 13 | and no later than `retro_load_game()`) |
| 14 | |
| 15 | - Open `libretro_core_options.h` and replace the contents of the existing `option_defs_us` struct array with all required core option parameters. |
| 16 | |
| 17 | ## Adding core option translations |
| 18 | |
| 19 | To add a translation, simply: |
| 20 | |
| 21 | - Copy the contents of `option_defs_us` *from* `libretro_core_options.h` *to* `libretro_core_options_intl.h` into a new struct array with the appropriate language suffix |
| 22 | |
| 23 | - Translate all human-readable strings |
| 24 | |
| 25 | - Add the new struct array to the appropriate location in the `option_defs_intl` array inside `libretro_core_options.h` |
| 26 | |
| 27 | This is most easily understood by considering the example in `example_translation/`. Here a French translation has been added (`option_defs_fr`), with comments explaining the appropriate formatting requirements. |
| 28 | |
| 29 | NOTE: Since translations involve the use of UTF-8 characters, `libretro_core_options_intl.h` must include a BOM marker. *This renders translations incompatible with c89 builds*. When performing a c89 build, the flag `HAVE_NO_LANGEXTRA` *must* be defined (e.g. `-DHAVE_NO_LANGEXTRA`). This will disable all translations. |
| 30 | |
| 31 | ## Disabling core options on unsupported frontends |
| 32 | |
| 33 | Sometimes it is desirable to only show a particular core option if the frontend supports the new core options v1 API. For example: |
| 34 | |
| 35 | - The API v1 allows cores to hide options dynamically |
| 36 | |
| 37 | - We can therefore create a specific 'toggle display' option to hide or show a number of other options (e.g. advanced settings) |
| 38 | |
| 39 | - On frontends that do not support API v1, this 'toggle display' option will have no function - it should therefore be omitted |
| 40 | |
| 41 | This can be handled easily by editing the `libretro_set_core_options()` function to ignore certain core name (key) values when generating option variable arrays for old-style frontends. Again, this is most easily understood by considering the example in `example_hide_option/libretro_core_options.h`: |
| 42 | |
| 43 | - Here, a `mycore_show_speedhacks` option is added to `option_defs_us` |
| 44 | |
| 45 | - On line 227, the following comparison allows the option to be skipped: |
| 46 | (Note that another `strcmp()` may be added for each option to be omitted) |
| 47 | |
| 48 | ```c |
| 49 | if (strcmp(key, "mycore_show_speedhacks") == 0) |
| 50 | continue; |
| 51 | ``` |
| 52 | |
| 53 | For any cores that require this functionality, `example_hide_option/libretro_core_options.h` should be used as a template in place of `example_default/libretro_core_options.h` |
| 54 | |
| 55 | ## Adding core option categories |
| 56 | |
| 57 | Core options v2 adds a mechanism for assigning categories to options. On supported fontends, options of a particular category will be displayed in a submenu/subsection of the main core options menu. This functionality may be used to reduce visual clutter, or to effectively 'hide' advanced settings without requiring a dedicated 'toggle display' option. |
| 58 | |
| 59 | A template for enabling categories via the core options v2 interface is provided in `example_categories`. The usage of this code is identical to that described in the `Adding 'enhanced' core options to a core` section, with one addition: the `libretro_set_core_options()` function here includes an additional argument identifying whether the frontend has option category support (a core may wish to selectively hide or reorganise options based upon this variable). |