RetroArch/libretro-common/samples/core_options/README.md

Adding 'enhanced' core options to a core

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)

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

Adding core option categories

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).