emulators.base.Emulator

Registry key and log label for the emulator.

Human-readable name the UI shows.

The RomM platform slug the session was activated for, or None.

The core RomM asked for (rom.core), for a launcher that fronts many; None for its default.

Set by the activate route and the import-spec route, like platform.

Whether RomM opted this launch in to known-broken cores (rom.experimental_cores).

The language the rom was activated for, or None.

The player's own interface language, or None.

Whether a launch needs a ROM; the desktop session does not.

Whether the ROM cache may boot this emulator from a local copy of its ROM.

Root of the emulator's writable data.

Subtrees under save_root that hold save data; save restore and dump are scoped to these.

The subset of save_subtrees holding savestates, for labelling an archive's members.

File extensions the emulator will boot, in preference order.

Whether the emulator can save and load state mid-session.

Whether the emulator can change the mounted disc without restarting.

Whether the room can open and close the emulator's own menu.

The one slot the broker saves into.

Where that slot's file lives.

Where the emulator's stdout and stderr are appended.

Seconds SIGTERM gets before escalating to SIGKILL.

Seconds SIGKILL gets before the process is written off.

The subclass's declaration that it wipes the previous session's save data before a restore.

The save subtree holding the whole memory card, or None for emulators without one.

A file the emulator needs inside the card directory before it treats it as a card, or None.

Set by an emulator that can tell its process is alive but never reached a running game.

Set while a slow pre-launch extraction is running, else None.

The frame captured just before the working slot's state was written, as PNG bytes.

Set by the broker on every confirmed save and replaced, or cleared, by the next one, so it never outlives the state it was taken with.

The spawned process's exit code once it has exited, else None.

Negative for a process killed by a signal, as subprocess reports it: -11 is a segfault.

The game id this session runs as, set on every activate.

Preflight sets it when the archive has imports; resolve_activate_identity sets it when it has none. The push route's identity checks read it.

Directories a save subtree may be a symlink to although they lie outside save_root.

The chain check and the write check refuse a path through a link that resolves outside the save root. An emulator whose data is split across two trees declares the second tree here, and a subtree link that resolves exactly to it is allowed.

The subtrees an archive may restore into, read before the working slot is cleared.

Start with no process handle, no boot failure, no extraction running, and no frame.

Start the app in its own process group with output captured.

A launch banner and then the child's stdout and stderr are appended to log_path; if the log cannot be opened the output is discarded. The pid is recorded through _record_pid once the process is up.

Raises

• ValueError: When both stdin_pipe and stdin_tty are set.
• OSError: When the process started but its pid could not be recorded. The process is killed first: an emulator no record names outlives the next broker restart with nothing able to find it, so the launch fails rather than leaving one behind.

Whether a spawned process exists and has not exited.

Drop the handle on the emulator and the record of it on disk.

Every path that ends with the process gone has to go through here. A graceful exit that only clears _proc leaves a record pointing at a pid nobody owns, and the next broker start would hunt it.

Terminate the running emulator, if any, and forget it.

The process group gets SIGTERM, escalating to SIGKILL once term_timeout passes, and SIGKILL gets kill_timeout to land. A process that is already gone is a no-op.

The handle and the pid record are only dropped once the process is confirmed gone. An emulator that outlived SIGKILL, or that refused the signal outright, keeps both: dropping the record while it still runs would leave it with nothing able to find it, which is the orphan PID_FILE exists to prevent, and every subclass launch opens with a stop that would then be its next chance to try again.

This reaches the process and its group, which is every emulator here. An app that starts other apps and detaches them needs more than a signal to one group, and overrides this (see Desktop.stop).

Hook run at activate, after clear_working_slot and before any extract.

Called on every activate, whether or not there is an archive to restore: a session that starts with no archive is exactly the one where a stale save left in place would be picked up as the player's own.

Default: nothing. Override to clear anything that would block or outrank the restore: a process holding a save file open, or an existing file the newer-file guard would wrongly keep over the archived one.

Start the emulator on rom_path, optionally resuming a state.

Raises

• NotImplementedError: Always; every subclass overrides this.

Save the running game to slot.

Only called when supports_states.

Raises

• NotImplementedError: When the emulator does not support states.

Load slot into the running game.

Only called when supports_states.

Raises

• NotImplementedError: When the emulator does not support states.

The file the working slot holds right now, or None if it is empty.

This is what the state-file GET serves, so it has to be the file the emulator just wrote, not the newest state in the directory: another slot or another game's state would otherwise be filed in RomM as this save.

Record that the state-file GET route is about to read the file state_path returned.

That read moves the file's access time, which some implementations also watch to confirm a load actually happened. Called before the route reads the file's bytes, so the window it opens covers that read instead of starting after the access time has already moved; callers of load_state can then tell their own load's read from this one. The default does nothing, for implementations that confirm loads some other way.

Record that the broker itself just wrote path as a state file.

Called right after a mid-session state push (the state-file PUT route) lands the file on disk. An implementation that infers where a core actually saves by watching the filesystem needs to tell its own writes apart from the core's, since a push the broker made itself proves nothing about the core's own behavior. The default does nothing, for implementations with no such inference to protect.

Take whatever lock a pushed state file should hold before it overwrites the working slot.

A push lands as a raw file replace with no confirmation step of its own, so nothing else stops it landing in the middle of another implementation's own confirmation window for that same file (a resume retry, an in-flight load) and being mistaken for whatever that other read or write was watching for. The default has no such window to protect and always succeeds.

Release whatever lock_for_state_write took. No-op by default.

Only called after a lock_for_state_write call that returned True.

Empty one of save_subtrees without removing the directory itself.

The directory stays because an emulator that finds its save directory missing at launch writes its saves somewhere else entirely, or refuses to boot at all.

Empty every save subtree this session is responsible for.

Drop what an earlier session left in the save tree, before the restore.

Every subclass that carries real save data MUST empty the save tree here (or in prepare_restore) and declare clears_stale_saves. This is not an optimisation and not optional. The restore only overwrites the members the incoming archive happens to carry, so anything the previous session wrote and this one's archive does not name survives untouched: on a pooled or shared container that is one player's saves left readable, and mixed into the dump, in the next player's session. A clear scoped to a state slot or to one title is not enough on its own unless nothing else under save_subtrees can hold another player's data.

Deleting more than the container's own leftovers is the failure in the other direction, so the clear is scoped to save_subtrees and runs before the archive is extracted, never after. _clear_save_subtrees is the usual implementation; an emulator with app data, DLC or quarantined files sharing a subtree passes a keep predicate.

The default only reports the gap: the base class cannot know which paths are safe to delete, so an emulator with save data that reaches this warns rather than silently starting a session on the last player's files.

The directory holding the card the memory-card routes sync, or None.

The broker names the card rather than reading the name out of the emulator's own config, because RomM lays a card down before the first launch has written that config. platform is the ROM's platform slug, for an emulator whose card exists on only one of several platforms it serves (GameCube vs Wii on Dolphin); most emulators ignore it.

Where each member of a card pushed on the memory-card route goes inside the card.

The default writes every member where the image put it. An emulator that reads only one layout overrides it to move a member the player packed differently to where the emulator will look for it.

Resolve core for this launch, before anything is cleared.

Default: a launcher that is its own backend takes no core.

Raises

• CoreRejectedError: When core is set.

Extra manifest and activate-response fields describing the running core.

The folder RomM should file the state at path under.

Learn from the restored archive's session identity, before the launch.

Default: nothing. A launcher that fronts many cores reads the previous session's core here.

The core or backend actually running the game, or None.

Only meaningful for a launcher that is one shell over many cores; it goes in the archive manifest so the parent can tell a RetroArch PSP archive from a standalone PPSSPP one.

Move a battery save into the new core's save dir on a core switch.

Default: nothing. A launcher that fronts many cores, each sorting its saves under its own dir, overrides this to carry the file across.

What an archive member holds, for the manifest the parent reads.

Every emulator lays its save directories out differently, so this is what lets the parent sort an archive without a table of those layouts. The default classifies by subtree; emulators whose states and saves share a directory override it.

Whether an archive member outranks whatever sits on disk at activate.

The restore skips a member the disk already holds a newer copy of, so it can never roll back progress made since the archive was taken. That reasoning only holds for files whose mtime records this player's own saving. An emulator with a file the container writes on behalf of whoever is using it (a signed-in profile package, an account store) overrides this: the freshest copy of one of those is the last player's, and passing over the incoming one silently runs the session under their identity.

What this emulator accepts as a declared import, on self.platform.

Place one member that passed hygiene and the kind gate.

Must be pure: nothing is written, nothing is deleted, and the only reads allowed are member.head() and the rom through ctx.

Check the placements together, after the shared checks.

Where this emulator's session identity comes from.

Where a pushed state called filename belongs.

Validating the name against the emulator's own convention is what keeps a caller from dropping arbitrary files into the save tree. The slot in it is not part of that test: RomM holds the library, so a stored state carries whatever slot it was captured in and lands in this broker's own working slot regardless.

Tell whether a pushed state may be written for this session, going by its first bytes.

The push route calls this once the whole body is in, before the state replaces the slot's. The base takes every state: only an emulator whose states open with the id of the game they belong to can tell.

Block until the working slot holds a state file, or deadline passes.

A resume state can turn up after launch: the state-file routes only answer while a session is up, so RomM pushes its pick once activate has returned and the game is already booting. Waiting for it here is what keeps a deferred resume load from firing on a slot that is still empty and reporting a fresh start.

Save state (best effort) and stop.

Default: nothing to save. A slot of None is an exit that writes no state. The game's own save data is still flushed and shipped: not writing a state is the whole of "exit without saving", and discarding an in-game save the player made at a save point would be losing real progress.

File the emulator should boot for path (folder or file).

Raises

• NotImplementedError: Always; every subclass overrides this.

Mount path in place of the running disc.

Only called when supports_disc_swap.

Raises

• NotImplementedError: When the emulator has no tray.

Open the emulator's menu, or close it when it is already open.

Only called when supports_menu.

Raises

• NotImplementedError: When the emulator has no menu to reach.