libretro.core

Thin ctypes wrapper around a libretro core’s exported retro_* functions.

See also

libretro.api

The Python equivalents of the C types passed across this boundary.

libretro.session

The high-level harness that orchestrates calls into a Core.

Classes

Core	A thin wrapper around a libretro core that can be used to call its public interface.
CoreInterface	An interface for a libretro core.

class CoreInterface

Bases: Protocol

An interface for a libretro core.

abstractmethod set_environment(env)

Call the core’s retro_set_environment function with the given callback.

Return type:

None

abstractmethod set_video_refresh(video)

Call the core’s retro_set_video_refresh function with the given callback.

Return type:

None

abstractmethod set_audio_sample(audio)

Call the core’s retro_set_audio_sample function with the given callback.

Return type:

None

abstractmethod set_audio_sample_batch(audio)

Call the core’s retro_set_audio_sample_batch function with the given callback.

Return type:

None

abstractmethod set_input_poll(poll)

Call the core’s retro_set_input_poll function with the given callback.

Return type:

None

abstractmethod set_input_state(state)

Call the core’s retro_set_input_state function with the given callback.

Return type:

None

abstractmethod init()

Call the core’s retro_init function.

Return type:

None

abstractmethod deinit()

Call the core’s retro_deinit function.

Return type:

None

abstractmethod api_version()

Call the core’s retro_api_version function and return the result.

Return type:

int

abstractmethod get_system_info()

Call the core’s retro_get_system_info function and return the result.

Return type:

retro_system_info

abstractmethod get_system_av_info()

Call the core’s retro_get_system_av_info function and return the result.

Return type:

retro_system_av_info

abstractmethod set_controller_port_device(port, device)

Call the core’s retro_set_controller_port_device function with the given arguments.

Return type:

None

abstractmethod reset()

Call the core’s retro_reset function.

Return type:

None

abstractmethod run()

Call the core’s retro_run function to advance the core by one frame.

Return type:

None

abstractmethod serialize_size()

Call the core’s retro_serialize_size function and return the result.

Return type:

int

abstractmethod serialize(data)

Call the core’s retro_serialize function with the given mutable buffer.

Return type:

bool

abstractmethod unserialize(data)

Call the core’s retro_unserialize function with the given buffer.

Return type:

bool

abstractmethod cheat_reset()

Call the core’s retro_cheat_reset function.

Return type:

None

abstractmethod cheat_set(index, enabled, code)

Call the core’s retro_cheat_set function with the given arguments.

Return type:

None

abstractmethod load_game(game)

Call the core’s retro_load_game function with the given game info.

Return type:

bool

abstractmethod load_game_special(game_type, info)

Call the core’s retro_load_game_special function with the given arguments.

Return type:

bool

abstractmethod unload_game()

Call the core’s retro_unload_game function.

Return type:

None

abstractmethod get_region()

Call the core’s retro_get_region function and return the result.

Return type:

Region | int

abstractmethod get_memory_data(id)

Call the core’s retro_get_memory_data function for the given memory region.

Return type:

c_void_ptr | None

abstractmethod get_memory_size(id)

Call the core’s retro_get_memory_size function for the given memory region.

Return type:

int

get_memory(id)

Get a writable memoryview of the memory region given by id.

Convenience wrapper around get_memory_data() and get_memory_size().

Parameters:

id (int) – The ID of the memory region to access.

Return type:

memoryview | None

Returns:

A writable memoryview of the given region, or None if retro_get_memory_data returned NULL.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

class Core

Bases: CoreInterface

A thin wrapper around a libretro core that can be used to call its public interface.

Does not manage the underlying core’s life cycle, i.e. retro_* methods are not called implicitly unless otherwise noted; that’s left to Session or some custom abstraction layer.

__init__(core)

Create a new Core instance.

Parameters:

core (CDLL | PathLike[str] | PathLike[bytes] | str) –

The core to wrap. Can be one of the following:

• A str or PathLike representing the path to the core’s shared library.

• A CDLL representing the core’s shared library.

Raises:

• ValueError – If the core does not define all the required functions (i.e. the retro_* function that each method corresponds to).

• TypeError – If core is not one of the above-mentioned types.

set_environment(env)

Call the core’s retro_set_environment function with the given callback.

Parameters:

env (CFunctionType | Callable[[int, c_void_ptr], bool]) – The function that the core should use for environment calls.

Raises:

TypeError – If env is not a retro_environment_t.

Return type:

None

set_video_refresh(video)

Call the core’s retro_set_video_refresh function with the given callback.

Parameters:

video (CFunctionType | Callable[[c_void_ptr, int, int, int], None]) – The function that the core should call to update its video output.

Raises:

TypeError – If video is not a retro_video_refresh_t.

Return type:

None

set_audio_sample(audio)

Call the core’s retro_set_audio_sample function with the given callback.

Parameters:

audio (CFunctionType | Callable[[int, int], None]) – The function that the core should call to render a single audio frame.

Raises:

TypeError – If audio is not a retro_audio_sample_t.

Return type:

None

set_audio_sample_batch(audio)

Call the core’s retro_set_audio_sample_batch function with the given callback.

Parameters:

audio (CFunctionType | Callable[[LP_c_short, int], int]) – The function that the core should call to render a batch of audio frames.

Raises:

TypeError – If audio is not a retro_audio_sample_batch_t.

Return type:

None

set_input_poll(poll)

Call the core’s retro_set_input_poll function with the given callback.

Parameters:

poll (CFunctionType | Callable[[], None]) – The function that the core should call to poll for updated input state.

Raises:

TypeError – If poll is not a retro_input_poll_t.

Return type:

None

set_input_state(state)

Call the core’s retro_set_input_state function with the given callback.

Parameters:

state (CFunctionType | Callable[[Port (int), int, int, int], int]) – The function that the core should call to request part of the input state.

Raises:

TypeError – If state is not a retro_input_state_t.

Return type:

None

init()

Call the core’s retro_init function.

Note:

This method does not check if the core has already been initialized. Additionally, this method is not implicitly called by __init__.

deinit()

Call the core’s retro_deinit function.

Note:

This method does not validate that the core has been initialized. Additionally, it is not implicitly called upon deletion.

api_version()

Call the core’s retro_api_version function.

Return type:

int

Returns:

The integer returned by the core’s implementation of retro_api_version.

Warning:

This method does not validate the returned version number.

get_system_info()

Call the core’s retro_get_system_info function.

Return type:

retro_system_info

Returns:

A retro_system_info instance containing information about the core. All strings are copied and may be accessed even after unloading the core.

get_system_av_info()

Call the core’s retro_get_system_av_info function.

Return type:

retro_system_av_info

Returns:

A retro_system_av_info instance containing information about the core’s audiovisual capabilities. It may be accessed even after unloading the core.

set_controller_port_device(port, device)

Call the core’s retro_set_controller_port_device function with the given arguments.

Parameters:

• port (Port (int)) – The port to set the device for. Masked to fit within the range of an unsigned int.

• device (int) – The device to assign to port. Masked to fit within the range of an unsigned int.

reset()

Call the core’s retro_reset function.

Warning:

Does not check if the core is in a state where it can be reset.

run()

Call the core’s retro_run function.

Warning:

Does not check if the core is in a state where it can be run.

serialize_size()

Call the core’s retro_serialize_size function.

Return type:

int

Returns:

The length of the buffer needed to serialize the core’s state, in bytes. If zero, the core does not support serialization.

serialize(data)

Call the core’s retro_serialize function with the given mutable buffer.

Fills data with whatever serialized state the core returns.

Parameters:

data (bytearray | memoryview[int] | Buffer) – A bytearray, mutable memoryview, or Buffer implementation that core’s serialized state will be saved to.

Return type:

bool

Returns:

True if the core successfully serialized its state, False otherwise.

Raises:

• TypeError – If data is not one of the aforementioned types.

• ValueError – If data is a read-only memoryview or Buffer.

Note:

The buffer must be at least as large as the last value returned by serialize_size, or else the serialized data will be incomplete.

unserialize(data)

Call the core’s retro_unserialize function with the given buffer.

Restores the core’s state from the serialized data in data.

Parameters:

data (bytes | bytearray | memoryview[int] | Buffer) – A bytes, bytearray, memoryview, or Buffer.

Raises:

TypeError – If data is not one of the aforementioned types.

Return type:

bool

Returns:

True if the core successfully loaded a state from data, False if not.

cheat_reset()

Call the core’s retro_cheat_reset function.

cheat_set(index, enabled, code)

Call the core’s retro_cheat_set function with the given arguments.

Parameters:

• index (int) – The number of the cheat code to toggle.

• enabled (bool) – Whether the cheat code should be enabled or disabled.

• code (bytes | bytearray | str) – A buffer containing a zero-terminated byte string.

Raises:

• TypeError – If any parameter’s value is inconsistent with its documented type.

• ValueError – If code does not contain a null terminator (i.e. the value 0).

load_game(game)

Call the core’s retro_load_game function with the given game info.

Parameters:

game (retro_game_info | None) – A retro_game_info instance or None.

Return type:

bool

Returns:

True if the core successfully loaded game, False otherwise.

Raises:

TypeError – If game is not a retro_game_info or None.

Warning:

This method does not validate any preconditions documented in libretro.h, e.g. it’s possible to pass None even if the core doesn’t support no-content mode.

load_game_special(game_type, info)

Call the core’s retro_load_game_special function with the given arguments.

Parameters:

• game_type (int | retro_subsystem_info) – The subsystem type to activate. May be passed as an int or a retro_subsystem_info instance.

• info (Sequence[retro_game_info] | Array[retro_game_info]) – A Sequence or ctypes.Array of retro_game_info instances.

Return type:

bool

Returns:

True if the core successfully loaded the game, False if not.

Raises:

TypeError – If any parameter’s value is inconsistent with its documented type.

Warning:

This method does not validate any preconditions documented in libretro.h, e.g. it’s possible to use this method even if the core doesn’t define subsystems.

unload_game()

Call the core’s retro_unload_game function.

Warning:

Does not check if the preconditions for retro_unload_game are met, e.g. it doesn’t check if a game is currently loaded.

get_region()

Call the core’s retro_get_region function.

Return type:

Region | int

Returns:

The returned region as a Region enum if it’s a known value, or as a plain int if not.

get_memory_data(id)

Call the core’s retro_get_memory_data function for the given memory region.

Parameters:

id (int) – The ID of the memory region to access.

Return type:

c_void_ptr | None

Returns:

Pointer to the memory region returned by the core, or None if the core returned NULL.

Raises:

TypeError – If id is not an int.

get_memory_size(id)

Call the core’s retro_get_memory_size function for the given memory region.

Parameters:

id (int) – The ID of the memory region to get the size of.

Raises:

TypeError – If id is not an int.

Return type:

int

Returns:

The size of the memory region, in bytes.

property path

The path to the core’s shared library.

classmethod __new__(*args, **kwargs)

get_memory(id)

Get a writable memoryview of the memory region given by id.

Convenience wrapper around get_memory_data() and get_memory_size().

Parameters:

id (int) – The ID of the memory region to access.

Return type:

memoryview | None

Returns:

A writable memoryview of the given region, or None if retro_get_memory_data returned NULL.