monsoon_core/lib.rs
1//! # Monsoon Core
2//!
3//! `monsoon_core` is the core emulation library for the Monsoon NES emulator.
4//! It provides a cycle-accurate emulation of the Nintendo Entertainment System
5//! (NES), including the MOS 6502 CPU, the 2C02 PPU (Picture Processing Unit),
6//! memory subsystems, and ROM parsing for the iNES and NES 2.0 file formats.
7//!
8//! ## Quick Start
9//!
10//! The main entry point is the [`Nes`] struct, which orchestrates all emulation
11//! components:
12//!
13//! ```rust,no_run
14//! use monsoon_core::emulation::nes::Nes;
15//! use monsoon_core::emulation::rom::RomFile;
16//!
17//! let mut nes = Nes::default();
18//!
19//! // Load a ROM from raw bytes
20//! let rom_data = std::fs::read("game.nes").unwrap();
21//! let rom = RomFile::load(&rom_data, None).unwrap();
22//! nes.load_rom(&rom);
23//!
24//! // Power on and run a single frame
25//! nes.power();
26//! nes.step_frame().expect("emulation error");
27//!
28//! // Get the rendered frame as a buffer of palette indices
29//! let pixels = nes.get_pixel_buffer();
30//! ```
31//!
32//! ## Architecture
33//!
34//! The library is organized into the following public modules:
35//!
36//! - [`emulation::nes`] — The top-level [`Nes`] emulator struct and execution
37//! control.
38//! - [`emulation::rom`] — ROM file parsing ([`RomFile`]) and the [`RomBuilder`]
39//! for constructing ROM metadata programmatically.
40//! - [`emulation::savestate`] — Save and restore emulator state via
41//! [`SaveState`].
42//! - [`emulation::screen_renderer`] — The [`ScreenRenderer`] trait for
43//! implementing custom pixel renderers, plus a built-in [`NoneRenderer`].
44//! - [`emulation::palette_util`] — NES color palette types ([`RgbColor`],
45//! [`RgbPalette`]) and palette file parsing.
46//! - [`emulation::ppu_util`] — PPU constants and debug data types (e.g., output
47//! dimensions, [`EmulatorFetchable`](emulation::ppu_util::EmulatorFetchable)
48//! for debug views).
49//! - [`util`] — Serialization helpers ([`ToBytes`]) and hash utilities.
50//!
51//! Internal implementation modules (`cpu`, `ppu`, `mem`, `opcode`) are
52//! `pub(crate)` and not accessible to downstream consumers.
53//!
54//! ## Pixel Buffer Format
55//!
56//! [`Nes::get_pixel_buffer`] returns a `Vec<u16>` of palette indices, **not**
57//! RGB values. Each entry encodes:
58//!
59//! - **Bits 0-5**: NES color index (0-63)
60//! - **Bits 6-8**: Emphasis bits from the PPU mask register
61//!
62//! Use a [`ScreenRenderer`] implementation (e.g., `LookupPaletteRenderer` from
63//! the `monsoon-default-renderers` crate) to convert these indices to RGB
64//! colors.
65//!
66//! ## Save States
67//!
68//! The emulator supports serializable save states through the [`SaveState`]
69//! type. States can be serialized to binary (postcard) or JSON format using the
70//! [`ToBytes`] trait, and deserialized with [`try_load_state_from_bytes`].
71//!
72//! [`Nes`]: emulation::nes::Nes
73//! [`Nes::get_pixel_buffer`]: emulation::nes::Nes::get_pixel_buffer
74//! [`RomFile`]: emulation::rom::RomFile
75//! [`RomBuilder`]: emulation::rom::RomBuilder
76//! [`SaveState`]: emulation::savestate::SaveState
77//! [`ScreenRenderer`]: emulation::screen_renderer::ScreenRenderer
78//! [`NoneRenderer`]: emulation::screen_renderer::NoneRenderer
79//! [`RgbColor`]: emulation::palette_util::RgbColor
80//! [`RgbPalette`]: emulation::palette_util::RgbPalette
81//! [`ToBytes`]: util::ToBytes
82//! [`try_load_state_from_bytes`]: emulation::savestate::try_load_state_from_bytes
83
84extern crate core;
85#[allow(clippy::upper_case_acronyms)]
86pub mod emulation;
87#[cfg(test)]
88mod tests;
89pub mod trace;
90pub mod util;