libretro.drivers.content.driver

Protocol definition and supporting types for the content-loading driver interface.

See also

libretro.api.content

Provides the game info types and content override structures that content drivers manage.

Classes

ContentAttributes	Resolved content-loading attributes for a single content file.
ContentDriver	Protocol for drivers that load content for the core.
LoadedContentFile	A single content file that has been loaded and prepared for the core.

Exceptions

ContentError

Raised when content cannot be loaded due to a policy violation (e.g., the core requires content but none was provided).

class ContentDriver

Bases: Protocol

Protocol for drivers that load content for the core.

Manages content attributes, subsystem support, and extended game info.

See also

libretro.api.content

The C game info types and content loading structures that implementations of this protocol handle.

abstractmethod load(content)

Load all content files.

Parameters:

content (TypeAliasType | SubsystemContent | None) –

May be one of the following:

• None, which will result in no content being loaded.

• A zipfile.Path object representing a file within a ZIP archive.

• A str or a PathLike object representing a file path. The loaded content will not be part of a subsystem. If retro_system_info.need_fullpath is False and no override for this extension defines ContentAttributes.need_fullpath as True, the driver will load the content as a file. Otherwise, the path will be provided to the core without opening the file.

• A bytes, bytearray, memoryview, or Buffer object that represents content data. The loaded content will be passed directly to the core without being set to a path.

• A retro_game_info object, which will be passed to the core as-is.

• A SubsystemContent object, which contains multiple content files that together form a subsystem.

Raises:

• FileNotFoundError – If content is a path to a non-existent file.

• ContentError – If loading None and the core requires content, or if content is a retro_game_info whose attributes are inconsistent with need_fullpath and block_extract.

• RuntimeError – If called before system_info is set.

Return type:

AbstractContextManager[tuple[retro_subsystem_info | None, Sequence[LoadedContentFile] | None]]

Returns:

A context manager that yields a tuple containing the subsystem info and a sequence of loaded content files. Non-persistent content files will be closed when the context manager exits.

Note

All files not marked as persistent will be closed when the context manager exits. The ones that are persistent will be closed when the driver is destroyed.

abstract property enable_extended_info

Whether to populate and expose retro_game_info_ext to the core via RETRO_ENVIRONMENT_GET_GAME_INFO_EXT.

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

abstract property game_info_ext

The most recently loaded extended game info array, or None if extended info is disabled or no content has been loaded.

abstract property system_info

The system info provided by the core.

See also

Core.get_system_info()

The method that cores use to provide this information.

abstract property overrides

Per-extension content-info overrides registered by the core.

abstract property subsystem_info

Subsystem descriptors registered by the core, or None if none were registered.

abstract property support_no_game

Whether the core supports being run without any content.

None if the core has not called RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME.

class ContentAttributes

Bases: object

Resolved content-loading attributes for a single content file.

These attributes are derived from the system info, per-extension overrides, and subsystem ROM descriptors.

block_extract

If True, the frontend should not extract this content from an archive.

persistent_data

If True, the content buffer must remain valid for the lifetime of the core.

need_fullpath

If True, the core requires a filesystem path rather than an in-memory buffer.

required

If True, the content file is mandatory and loading must fail without it.

__init__(block_extract, persistent_data, need_fullpath, required)

classmethod __new__(*args, **kwargs)

class LoadedContentFile

Bases: NamedTuple

A single content file that has been loaded and prepared for the core.

info

The retro_game_info passed to retro_load_game().

info_ext

Extended game info, if the core opted in via RETRO_ENVIRONMENT_GET_GAME_INFO_EXT.

key in self

Return bool(key in self).

self[key]

Return self[key].

__init__()

iter(self)

Implement iter(self).

len(self)

Return len(self).

static __new__(_cls, info, info_ext)

Create new instance of LoadedContentFile(info, info_ext)

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

exception ContentError

Bases: RuntimeError

Raised when content cannot be loaded due to a policy violation (e.g., the core requires content but none was provided).

__init__(*args, **kwargs)

classmethod __new__(*args, **kwargs)

add_note(note, /)

Add a note to the exception

args

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.