The basic steps for updating a core to support core options v1 are as follows:
- Copy `example_default/libretro_core_options.h` to the same directory as `libretro.c/.cpp`
- Copy `example_default/libretro_core_options_intl.h` to the same directory as `libretro.c/.cpp`
- Add `#include "libretro_core_options.h"` to `libretro.c/.cpp`
- Replace any existing calls of `RETRO_ENVIRONMENT_SET_VARIABLES` with `libretro_set_core_options(retro_environment_t environ_cb)`
(Note: `libretro_set_core_options()` should be called as early as possible - preferably in `retro_set_environment()`
and no later than `retro_load_game()`)
- Open `libretro_core_options.h` and replace the contents of the existing `option_defs_us` struct array with all required core option parameters.
## Adding core option translations
To add a translation, simply:
- 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
- Translate all human-readable strings
- Add the new struct array to the appropriate location in the `option_defs_intl` array inside `libretro_core_options.h`
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.
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.
## Disabling core options on unsupported frontends
Sometimes it is desirable to only show a particular core option if the frontend supports the new core options v1 API. For example:
- The API v1 allows cores to hide options dynamically
- We can therefore create a specific 'toggle display' option to hide or show a number of other options (e.g. advanced settings)
- On frontends that do not support API v1, this 'toggle display' option will have no function - it should therefore be omitted
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`:
- Here, a `mycore_show_speedhacks` option is added to `option_defs_us`
- On line 227, the following comparison allows the option to be skipped:
(Note that another `strcmp()` may be added for each option to be omitted)
```c
if (strcmp(key, "mycore_show_speedhacks") == 0)
continue;
```
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`
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.
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).
