Libretro Core

Libretro Core

The rustynes-libretro crate provides a cycle-accurate NES emulation core for the RetroArch ecosystem. It integrates RustyNES's 100% AccuracyCoin core natively into any frontend supporting the libretro API.

Core Features

• Cycle-Accurate Emulation: Fully integrated with rustynes-core, maintaining lockstep PPU/CPU timing.
• Dynamic Audio Sync: Accurate 44.1kHz audio sampling matching the RustyNES native stream.
• Save States & Rollback: Deterministic snapshotting (on_serialize/on_unserialize) and memory mappers for robust save states, rollback netplay, and run-ahead.
• RetroAchievements Compatibility: Exposed WRAM, VRAM, and SRAM hooks enable full integration with RetroAchievements (get_memory_data and get_memory_size).
• Direct Memory Mapping: Direct integration bypassing opaque binds to support advanced RetroArch features safely.

Architecture

The libretro core acts as an API bridge:

• RustyNesLibretro Struct: Manages initialization and cleanup, wrapping a safe instance of Nes.
• on_run: Executes nes.run_frame(), fetching input via RetroArch's Joypad API and pushing video output to VideoContext.
• Video Buffer: Overcomes Libretro's XRGB8888 pixel format endianness by translating the core's native RGBA8 output linearly without allocation overhead (swaps R and B channels).

Compiling the Core

The core uses a dedicated Makefile to target standard cross-compilation endpoints natively:

cd crates/rustynes-libretro
make

The output will be the shared library appropriate for your platform (rustynes_libretro.so, rustynes_libretro.dylib, or rustynes_libretro.dll).

Upstream Synchronization

RustyNES is integrated into the upstream libretro buildbots.

Maintenance Workflow

To push new features or metadata updates upstream to libretro-super or docs:

1. Re-fork: Always fork fresh from upstream master.
2. Clone & Branch: git checkout -b update-rustynes-recipe
3. Commit: Modify recipes/docs with strict alphabetical ordering (e.g., in recipes/apple/crates.conf).
4. Pull Request: Open a PR directly to upstream.
5. Delete Fork: Delete the fork after successful merge to maintain a clean workspace.

See docs/libretro/UPSTREAM_SYNC.md for complete details.