libretro.api.options¶

Core option definitions, values, categories, and internationalization.

Corresponds to the retro_core_option_* and retro_variable types in libretro.h. Defines option definitions, values, categories, and internationalization wrappers for core configuration.

See also

libretro.drivers.options

Module Attributes

`RETRO_NUM_CORE_OPTION_VALUES_MAX`	Maximum number of values a single core option can have.
`retro_core_options_update_display_callback_t`	Recompute the visibility of dynamic core options.
`NUM_CORE_OPTION_VALUES_MAX`	Alias for `RETRO_NUM_CORE_OPTION_VALUES_MAX`.
`CoreOptionArray`	Fixed-size array type for `retro_core_option_value` entries.

Classes

`CoreOptionArray`	Fixed-size array type for `retro_core_option_value` entries.
`retro_core_option_definition`	Corresponds to `retro_core_option_definition` in `libretro.h`.
`retro_core_option_display`	Corresponds to `retro_core_option_display` in `libretro.h`.
`retro_core_option_v2_category`	Corresponds to `retro_core_option_v2_category` in `libretro.h`.
`retro_core_option_v2_definition`	Corresponds to `retro_core_option_v2_definition` in `libretro.h`.
`retro_core_option_value`	Corresponds to `retro_core_option_value` in `libretro.h`.
`retro_core_options_intl`	Corresponds to `retro_core_options_intl` in `libretro.h`.
`retro_core_options_update_display_callback`	Corresponds to `retro_core_options_update_display_callback` in `libretro.h`.
`retro_core_options_v2`	Corresponds to `retro_core_options_v2` in `libretro.h`.
`retro_core_options_v2_intl`	Corresponds to `retro_core_options_v2_intl` in `libretro.h`.
`retro_variable`	Corresponds to `retro_variable` in `libretro.h`.

RETRO_NUM_CORE_OPTION_VALUES_MAX = 128¶: Maximum number of values a single core option can have.

class retro_variable[source]¶

Bases: Structure

Corresponds to retro_variable in libretro.h.

A key/value pair used for legacy core options (v0).

>>> from libretro.api import retro_variable
>>> v = retro_variable()
>>> v.key is None
True

key¶: The option’s unique key.

value¶: The option’s current value, or a pipe-delimited list of possible values.

__deepcopy__(_)[source]¶

Return a copy of this object, including all strings. Intended for use with copy.deepcopy().

>>> import copy
>>> from libretro.api import retro_variable
>>> copy.deepcopy(retro_variable()).key is None
True

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class retro_core_option_display[source]¶

Bases: Structure

Corresponds to retro_core_option_display in libretro.h.

Controls whether a core option is visible in the frontend UI.

>>> from libretro.api import retro_core_option_display
>>> d = retro_core_option_display()
>>> d.visible
False

key¶: The unique key of the option to show or hide.

visible¶: Whether the option should be visible to the player.

__deepcopy__(_)[source]¶: Return a copy of this object, including all strings. Intended for use with copy.deepcopy().

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class retro_core_option_value[source]¶

Bases: Structure

Corresponds to retro_core_option_value in libretro.h.

A single selectable value for a core option.

>>> from libretro.api import retro_core_option_value
>>> v = retro_core_option_value()
>>> v.value is None
True

value¶: Internal value string.

label¶: Human-readable label, or None to display value as-is.

__deepcopy__(_)[source]¶: Return a copy of this object, including all strings. Intended for use with copy.deepcopy().

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

CoreOptionArray¶: Fixed-size array type for retro_core_option_value entries.

class retro_core_option_definition[source]¶

Bases: Structure

Corresponds to retro_core_option_definition in libretro.h.

Defines a single core option with a key, description, info text, possible values, and a default value (v1 options API).

>>> from libretro.api import retro_core_option_definition
>>> d = retro_core_option_definition()
>>> d.key is None
True

key¶: Unique key for this option.

desc¶: Human-readable description shown to the player.

info¶: Extended information or tooltip text.

values¶: Array of possible values for this option.

default_value¶: Default value if not previously set.

__deepcopy__(memo=None)[source]¶: Return a copy of this object, including all strings and subobjects. Intended for use with copy.deepcopy().

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class retro_core_options_intl[source]¶

Bases: Structure

Corresponds to retro_core_options_intl in libretro.h.

Wraps US English and localized option definitions for v1 options.

>>> from libretro.api import retro_core_options_intl
>>> intl = retro_core_options_intl()
>>> intl.us is None
True

us¶: US English option definitions.

local¶: Localized option definitions.

__deepcopy__(memo=None)[source]¶: Return a copy of this object, including all strings and subobjects. Intended for use with copy.deepcopy().

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class retro_core_option_v2_category[source]¶

Bases: Structure

Corresponds to retro_core_option_v2_category in libretro.h.

Groups related options under a named category (v2 options API).

>>> from libretro.api import retro_core_option_v2_category
>>> cat = retro_core_option_v2_category()
>>> cat.key is None
True

key¶: Unique key for this category.

desc¶: Human-readable description shown to the player.

info¶: Extended information about this category.

__deepcopy__(_)[source]¶: Return a copy of this object, including all strings. Intended for use with copy.deepcopy().

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class retro_core_option_v2_definition[source]¶

Bases: Structure

Corresponds to retro_core_option_v2_definition in libretro.h.

Defines a single core option with category support (v2 options API).

>>> from libretro.api import retro_core_option_v2_definition
>>> d = retro_core_option_v2_definition()
>>> d.key is None
True

key¶: Unique key for this option.

desc¶: Human-readable description shown to the player.

desc_categorized¶: Shorter description for display under its category.

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

info¶: Extended information or tooltip text.

info_categorized¶: Shorter tooltip text for display under its category.

category_key¶: Key of the category this option belongs to, or None.

values¶: Array of possible values for this option.

default_value¶: Default value if not previously set.

__deepcopy__(memo=None)[source]¶: Return a copy of this object, including all strings and subobjects. Intended for use with copy.deepcopy().

class retro_core_options_v2[source]¶

Bases: Structure

Corresponds to retro_core_options_v2 in libretro.h.

Top-level container for v2 option categories and definitions.

>>> from libretro.api import retro_core_options_v2
>>> v2 = retro_core_options_v2()
>>> v2.categories is None
True

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

categories¶: Array of option categories, terminated by a zeroed-out entry.

definitions¶: Array of option definitions, terminated by a zeroed-out entry.

__deepcopy__(memo=None)[source]¶: Return a copy of this object, including all strings and subobjects. Intended for use with copy.deepcopy().

class retro_core_options_v2_intl[source]¶

Bases: Structure

Corresponds to retro_core_options_v2_intl in libretro.h.

Wraps US English and localized v2 option sets.

>>> from libretro.api import retro_core_options_v2_intl
>>> intl = retro_core_options_v2_intl()
>>> intl.us is None
True

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

us¶: US English option definitions and categories.

local¶: Localized option definitions and categories.

__deepcopy__(memo=None)[source]¶: Return a copy of this object, including all strings and subobjects. Intended for use with copy.deepcopy().

class retro_core_options_update_display_callback[source]¶

Bases: Structure

Corresponds to retro_core_options_update_display_callback in libretro.h.

Wraps a callback that the frontend calls to determine whether to refresh option visibility.

>>> from libretro.api import retro_core_options_update_display_callback
>>> cb = retro_core_options_update_display_callback()
>>> cb.callback is None
True

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

callback¶: Called by the frontend to request a visibility update for core options.

self()[source]¶

Invoke the callback.

Raises:: ValueError – If no callback has been set.
Return type:: bool
Returns:: True if the display should be updated.

__deepcopy__(_)[source]¶: Return a copy of this object. Intended for use with copy.deepcopy().

retro_core_options_update_display_callback_t¶

Recompute the visibility of dynamic core options.

Registered by the core and called by the frontend to ask the core to update which options should be shown or hidden, typically by calling RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY for each one. All core options are visible by default.

Returns:: True if any core option’s visibility was adjusted since the last call to this function, False otherwise.

Corresponds to retro_core_options_update_display_callback_t in libretro.h.

NUM_CORE_OPTION_VALUES_MAX = 128¶: Alias for RETRO_NUM_CORE_OPTION_VALUES_MAX.