Crate rustynes_core

Expand description

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::MIN_FORMAT_VERSION;
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.
Attestation: A rolling hash of a run’s video output, and the checkpoints along the way.
AttestationBuilder: Accumulates an Attestation one frame at a time.
BoardDescription: What the cartridge header told the core to build, after any load-time correction: the facts that change emulation and that a host cannot apply.
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: four controller ports plus an expansion byte.
HardwareOptions: Every host-settable option that changes what the emulated console does.
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.
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.
SystemBus: The system bus.
TraceRec: v1.1.0 beta.2 (Workstream C, T-110-C2) — one cycle-trace record.

Enums§

ConsoleModel: v2.9.8 — which console wires the PPU’s /RESET line.
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.
VerifyOutcome: The result of replaying an attested movie and comparing it to its record.

Constants§

ATTESTATION_CHECKPOINT_INTERVAL: Frames between recorded checkpoint hashes.
ATTESTATION_MAGIC: Marker for the optional attestation tail: "RNAT" little-endian.
ATTESTATION_VERSION: Attestation tail schema version.
BYTES_PER_FRAME: Bytes stored per recorded frame: players 1-4, then a reserved expansion-port byte (always 0 today).
DEFAULT_SAMPLE_RATE: The APU sample rate Nes::from_rom and friends build with when no explicit rate is given (44_100 Hz).
EMULATION_EPOCH: v3.0.0 (ADR 0045) — which emulator behaviour a movie or a netplay peer expects, beside the options and the board that HardwareOptions and BoardDescription describe.
EXPANSION_DEVICE_MAX_LEN: Largest encoding of one port’s expansion device in the BUS section.
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.
MAX_CPU_OVERCLOCK: The largest CPU-multiplier overclock the core accepts (v3.1.0, T-CPU-OVERCLOCK).
MAX_EXTRA_SCANLINES: The largest extra-scanline overclock the core accepts.
MIN_MOVIE_FORMAT_VERSION: The oldest container version this build replays: v6.
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.
SAVE_STATE_DEVICE_HEADROOM: How much a snapshot can grow after it is first measured.

Functions§

config_digest: SHA-256 over everything two machines must share to run one timeline from the same ROM: the region, the BoardDescription and the HardwareOptions, each in its canonical encoding.
power_on_for_movie: v2.9.0 — the state every StartPoint::PowerOn movie starts from.
recorded_before_v2_timebase: Peek a .rnm blob’s header to learn its recording epoch.
version: Returns the crate version string.

Type Aliases§

OptionsDecodeError: Why an options or board block could not be decoded.