Crate rustynes_core 

Cycle-accurate NES emulator core.

This crate is the public entry point for embedders (frontend, test harness, future ports). It owns the scheduler, the bus, save-state serialization, the rewind ring, and the Nes facade. Per-chip implementations live in rustynes-cpu, rustynes-ppu, rustynes-apu, and rustynes-mappers, and are re-exported from this crate so downstream consumers depend on rustynes-core only.

See docs/architecture.md and docs/scheduler.md for the design.

Re-exports

pub use debug::ApuDebugView;

pub use debug::CpuDebugView;

pub use debug::MapperDebugView;

pub use debug::PpuDebugView;

pub use genie::GenieCode;

pub use genie::GenieError;

pub use input_device::BandaiHyperShotState;

pub use input_device::FamilyKeyboardState;

pub use input_device::InputDevice;

pub use input_device::KonamiHyperShotState;

pub use input_device::PowerPadState;

pub use input_device::SnesMouseState;

pub use input_device::VausState;

pub use input_device::ZapperState;

pub use legacy_movie::LegacyMeta;

pub use legacy_movie::LegacyMovieError;

pub use legacy_movie::import_fcm;

pub use legacy_movie::import_fmv;

pub use legacy_movie::import_mc2;

pub use legacy_movie::import_vmv;

pub use save_state::BinReader;

pub use save_state::BinWriter;

pub use save_state::FORMAT_VERSION;

pub use save_state::HEADER_LEN;

pub use save_state::Header;

pub use save_state::MAGIC;

pub use save_state::ROM_HASH_TAG_LEN;

pub use save_state::Section;

pub use save_state::SectionIter;

pub use save_state::SnapshotError;

pub use save_state::THUMBNAIL_HEIGHT;

pub use save_state::THUMBNAIL_LEN;

pub use save_state::THUMBNAIL_VERSION;

pub use save_state::THUMBNAIL_WIDTH;

pub use save_state::parse_header;

pub use save_state::tag;

pub use save_state::tag_string;

pub use save_state::write_header;

pub use save_state::write_section;

pub use vs_db::VsDbEntry;

pub use vs_db::lookup as vs_db_lookup;

pub use vs_dualsystem::Emu;

pub use vs_dualsystem::VsDualSystem;

pub use zwinder::ZWINDER_DEFAULT_BUDGET_BYTES;

pub use zwinder::ZWINDER_DEFAULT_KEYFRAME_INTERVAL;

pub use zwinder::ZwinderError;

pub use zwinder::ZwinderStateManager;

pub use rustynes_apu;

pub use rustynes_cpu;

pub use rustynes_mappers;

pub use rustynes_ppu;

Modules

bk2_interop

BizHawk .bk2 movie interop.

debug

Read-only debug snapshots for the frontend’s egui debugger UI.

genie

Game Genie cheat-code decoding.

input_device

Optional non-standard input-device overlays for the $4016/$4017 controller ports: the Arkanoid “Vaus” paddle and the NES Zapper light gun.

legacy_movie

v1.7.0 “Forge” Workstream G4 — legacy NES TAS movie import.

movie_interop

FCEUX .fm2 movie interop: import + export of FCEUX’s plain-text TAS movie format to and from the native Movie type.

save_state

Save-state container format for RustyNES v2.

scheduler

Lockstep-scheduler types shared across the bus, the IRQ-timing trace fixture, and (in Phase B+) the CPU IRQ sampling path.

vs_db

Vs. System per-game database (v2.7.0).

vs_dualsystem

Vs. DualSystem — two complete NES systems in one arcade cabinet (v2.0.0 beta.5, Workstream C of the “Timebase” plan).

zwinder

Zwinder-class compressed, density-tiered state manager (v1.7.0 “Forge” Workstream D2).

Structs

AccessRec

v1.1.0 beta.3 (Workstream E, T-110-E2) — one CPU bus-access record for the Lua onRead / onWrite callbacks: direction + full address + the byte.

Buttons

Standard NES controller buttons. Bits ordered to match the wire shift order (LSB first): A, B, Select, Start, Up, Down, Left, Right.

Controller

One standard NES controller plugged into $4016 (player 1) or $4017 (player 2).

EventBreakHit

v1.4.0 Workstream D (D2) — one event-driven breakpoint hit.

EventRec

One event-viewer record: kind + the PPU (scanline, dot) + the address + (v1.5.0 A2) the byte read or written.

FrameInput

Per-frame controller input: the Buttons bits for both standard ports plus a reserved expansion byte. Bit layout matches FCEUX .fm2 (bit0=A .. bit7=Right), which is exactly Buttons::bits.

InterruptRec

v1.2.0 (Workstream E, T-110-E1) — one interrupt-service record for the Lua onNmi / onIrq callbacks: the service direction + the vector the CPU fetched its new PC from.

LockstepBus

Lockstep bus.

Movie

A complete TAS movie: a versioned header, a start point, and the per-frame input stream.

MoviePlayer

Plays a movie back, feeding its recorded inputs into an emulator one frame at a time.

MovieRecorder

Records the per-frame input stream applied to an emulator.

Nes

Top-level NES emulator handle.

PowerOnConfig

v2.1.7 P5 — power-on hardware configuration for a freshly-constructed or power-cycled machine.

RewindRing

Rewind ring buffer.

TraceRec

v1.1.0 beta.2 (Workstream C, T-110-C2) — one cycle-trace record.

Enums

Cpu2A03Revision

Ricoh 2A03 CPU/APU die revision, selecting the hardware-revision difference in the DMA unit’s “unexpected DMA” extra halt-read (v2.1.7 “Hardware Revisions & DMA Frontier”).

EventBpKind

v1.4.0 Workstream D (D2) — the class of hardware event an event-driven breakpoint can trigger on.

EventKind

v1.1.0 beta.2 (Workstream C, T-110-C3) — the class of a captured CPU write.

M2Phase

Convention for the M2-phase reference relative to the CPU cycle’s 3 PPU dots.

MovieError

Errors produced by movie encode / decode / playback.

PaletteInit

v2.1.7 P5 — selectable power-up palette-RAM contents.

PowerOnRam

v2.1.7 P5 — power-on 2 KiB CPU work-RAM contents.

PpuRevision

v2.1.7 P5 — selectable 2C02 die revision, gating revision-dependent quirks.

Region

NES region (governs clock dividers, scanline counts, audio rate tables).

RewindError

Errors raised by RewindRing::pop_back when an entry can’t be reconstructed.

StartPoint

Where a movie begins. Clean-room analogue of Mesen2’s RecordMovieFrom.

Constants

BYTES_PER_FRAME

Bytes stored per recorded frame: player 1, player 2, and a reserved expansion-port byte (always 0 in v1).

FRAME_DURATION_DENDY

Nominal Dendy frame duration: 50 Hz Russian famiclone, same as PAL.

FRAME_DURATION_NTSC

Nominal NTSC frame duration: 1 / 60.0988 Hz ≈ 16.6393 ms.

FRAME_DURATION_PAL

Nominal PAL frame duration: 1 / 50.0070 Hz ≈ 19.9972 ms.

MOVIE_FORMAT_VERSION

Current movie container-format version.

MOVIE_MAGIC

Magic header bytes — first 8 bytes of every .rnm movie file.

REWIND_DEFAULT_KEYFRAME_PERIOD

Default keyframe period (1 keyframe per second of capture).

REWIND_DEFAULT_MAX_BYTES

Default ring capacity in bytes — 60 s × 60 fps with our typical compression ratio fits comfortably under 32 MiB.

Functions

recorded_before_v2_timebase

Peek a .rnm blob’s header to learn its recording epoch.

version

Returns the crate version string.