Inside Libretro: The Core/Frontend Architecture Behind RetroArch

RetroArch supports several dozen systems — NES, SNES, Genesis, PlayStation, N64, arcade boards, and far more — without each one having its own separate settings menu, its own shader pipeline, its own netplay implementation, or its own rewind feature. That’s not because someone wrote all of that logic dozens of times over; it’s because RetroArch’s actual emulation logic for any given system is deliberately not part of RetroArch itself.

The split: core and frontend

The libretro API defines a small, fixed set of C functions any emulator can implement — initialize, load a ROM, run one frame, read/write save-RAM, serialize/deserialize state — compiled into a shared library called a core. A frontend (RetroArch is the reference implementation, though not the only one) loads a core, calls those functions in a defined sequence, and handles everything the core itself doesn’t: video output, audio mixing, input mapping, on-screen menus, configuration, and save file management.

┌─────────────────────────────┐
│   RetroArch (frontend)      │   video, audio, input, shaders,
│                             │   netplay, rewind, achievements,
│                             │   UI — the same code for every core
└─────────────┬───────────────┘
              │  libretro API calls:
              │  retro_init(), retro_load_game(),
              │  retro_run(), retro_serialize(), ...
┌─────────────▼───────────────┐
│   snes9x_libretro.so (core) │   the actual SNES emulation logic —
│   (or any other core)       │   CPU/PPU/APU emulation, nothing else
└──────────────────────────────┘

A core’s primary job is emulation or game logic. It normally does not own the host window, audio device, or physical controller. Instead, the frontend registers callbacks: the core submits video and audio through them and asks the frontend’s input callbacks for current logical controls. Hardware-rendered cores can request a graphics context through the API, but the frontend still coordinates creation and presentation.

The API is a lifecycle and callback contract

The public libretro.h header defines an ABI designed for C interoperability. The frontend loads the shared library, resolves required retro_* entry points, checks the API version, installs callbacks, initializes the core, supplies system information and content, repeatedly calls retro_run, and eventually unloads content and deinitializes.

The core reports properties such as valid content extensions, whether it needs a full file path, and its nominal video geometry, frame rate, and audio sample rate. Those values let the frontend configure a generic pipeline without knowing the console’s private classes or data structures.

ABI stability is central. A core compiled separately must agree on function signatures, structures, enum values, calling convention, and ownership rules. Adding a convenience feature cannot casually change every existing binary, so many capabilities are negotiated through the environment callback and versioned structures.

Environment commands extend the narrow base

retro_environment_t is the control channel for options and capabilities that do not fit the minimal frame loop. A core can expose user-configurable variables, request pixel formats, describe input devices, provide memory maps, negotiate hardware rendering, declare achievements support, or publish messages. The frontend may accept, reject, or lack a command depending on the API contract.

This design avoids making every feature a new mandatory exported function, but it requires careful capability checking. A core must handle unsupported optional commands and must not assume RetroArch-specific behavior when claiming general libretro compatibility. A frontend likewise should not infer that every core implements serialization, disk control, cheats, or rich subsystem content.

Why this decoupling is the actual point

Because shaders, input mapping, menus, capture, and configuration can live in the frontend, improvements can benefit many cores at once. Rewind, run-ahead, rollback netplay, and some achievement features additionally depend on core behavior: deterministic execution, sufficiently complete and fast serialization, stable memory exposure, and correct timing. They are shared infrastructure, not automatically correct for every core.

Save RAM and save states illustrate the boundary. retro_get_memory_data and related calls can expose defined memory regions for persistent saves. Serialization asks the core to encode enough transient machine state into an opaque blob and later restore it. The frontend can store, rewind, or transmit that blob without understanding every CPU register, but only the core can ensure the state is complete and version-compatible.

Content loading is more varied than “a ROM path”

Simple cores load one memory-backed game image. Other systems need cue sheets and track files, firmware, multiple discs, arcade definitions, or no content at all. The API includes subsystem and disk-control mechanisms, while core metadata tells the frontend whether it can receive file data in memory or needs a filesystem path.

This is where platform policy matters. Sandboxed frontends, mobile storage permissions, archives, virtual filesystems, and firmware directories can differ. A core that bypasses frontend abstractions and opens arbitrary host paths may work on one desktop build and fail elsewhere. Clear content and firmware requirements are part of portability.

Where this architecture came from

This design wasn’t RetroArch’s starting point — it grew into it. The project began in 2010 as SSNES, a lightweight SNES-only frontend built by Hans-Kristian “Themaister” Arntzen on top of libsnes, a decoupled SNES emulation backend designed by the pseudonymous developer Near specifically to separate emulation logic from frontend concerns. On April 21, 2012, SSNES was renamed RetroArch to reflect a broader ambition: generalizing that same core/frontend split — originally built for one system — into “libretro,” an API any emulator for any system could implement, with RetroArch itself becoming a frontend for all of them rather than only SNES.

The architecture should not be confused with ownership. Many libretro cores are ports or adaptations of independent emulator projects with their own licenses, maintainers, goals, and standalone versions. Core behavior can lag, diverge, or carry frontend-specific patches. Users comparing accuracy should identify the exact core build and upstream relationship rather than treating every core name as interchangeable with the standalone emulator.

The trade-off: a lowest-common-denominator API

A single API covering wildly different hardware — a Game Boy versus a PlayStation 2 — necessarily can’t expose every system-specific quirk directly; it has to define a reasonably generic contract (frame buffers, audio buffers, generic input state, generic save-state blobs) that every core adapts its own internals to fit. This occasionally shows up as friction — a system with an unusual output format or an exotic peripheral needs a core author to work around the generic API’s assumptions — but it’s a deliberate, worthwhile trade against the alternative of a frontend that has to know something special about every system it supports.

The generic contract can also encourage a one-call-per-video-frame model even when hardware has asynchronous processors or unusual refresh behavior. Good cores preserve their internal timing and use the API boundary as a delivery interface, not as proof the emulated machine itself operates in neat frame-sized chunks.

Threading, ownership, and determinism

The frontend calls core entry points under documented expectations, and callbacks occur within that relationship. A core that creates worker threads must synchronize them before serialization, unload, and shutdown. Passing pointers across the boundary requires respecting how long buffers remain valid; neither side may retain transient memory without permission.

Rewind and rollback make hidden nondeterminism visible. Host time, uninitialized memory, racing audio threads, random seeds, and external files can cause two runs from the same serialized state to diverge. Architecture makes the feature reusable, but core testing makes it trustworthy.

Why frontends besides RetroArch matter

The API is libretro; RetroArch is its reference frontend. Other frontends can implement a subset or a different user experience for embedded devices, testing, media centers, or specialized platforms. A core that follows the published contract rather than undocumented RetroArch behavior is more portable and easier to test.

Conversely, frontend developers can use small test cores to validate lifecycle, callbacks, pixel formats, audio batching, input mapping, environment commands, and error paths without involving a complex emulator. The narrow ABI creates a seam where both sides can be tested independently.

Why this matters beyond RetroArch specifically

The core/frontend split is a genuine instance of a broader software design principle — separating a narrow, well-defined “what” (emulate this exact hardware) from a broad, shared “everything else” (how the user sees, hears, and interacts with it) — applied to a domain where, historically, almost every emulator had bundled both together. The result is less a single emulator than a shared platform that dozens of independent emulation projects plug into.

Its value is leverage with explicit limits. Shared presentation and services reduce duplicated work, while cores retain responsibility for machine accuracy and complete state. Reproducible reports therefore name frontend version, core version or commit, content hash, firmware, options, video driver, and platform—the interface connects those parts but does not make their differences disappear.

Related:

Sources: