Crate rgy

rgy is no-std cross-platform Rust GameBoy emulator library.

The users of this library only needs to implement Hardware trait, which abstracts OS-specific function. Once it’s implemented, the emulator works.

The following code is the example which just implements Hardware. The implementation does nothing. You can replace the body of each function with the actual meaningful logic.

use rgy::{Config, Key, Stream, VRAM_HEIGHT, VRAM_WIDTH};

struct Hardware {
    dummy_display: Vec<Vec<u32>>,
}

impl Hardware {
    fn new() -> Self {
        // Create a frame buffer with the size VRAM_WIDTH * VRAM_HEIGHT.
        let dummy_display = vec![vec![0u32; VRAM_HEIGHT]; VRAM_WIDTH];

        Self { dummy_display }
    }
}

impl rgy::Hardware for Hardware {
    // Called when a horizontal line in the display is updated by the emulator.
    fn vram_update(&mut self, line: usize, buffer: &[u32]) {
        // `line` corresponds to the y coordinate.
        let y = line;

        for (x, col) in buffer.iter().enumerate() {
            // TODO: Update the pixels in the actual display here.
            self.dummy_display[x][y] = *col;
        }
    }

    // Called when the emulator checks if a key is pressed or not.
    fn joypad_pressed(&mut self, key: Key) -> bool {
        println!("Is {:?} pressed?", key);

        // TODO: Read a keyboard device and check if the `key` is pressed or not.

        false
    }

    // Called when the emulator plays a sound.
    fn sound_play(&mut self, _stream: Box<dyn Stream>) {
        // TODO: Play the wave pattern provided `Stream`.
    }

    // Provides clock for the emulator.
    fn clock(&mut self) -> u64 {
        // TODO: Return the epoch in microseconds.
        let epoch = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .expect("Couldn't get epoch");
        epoch.as_micros() as u64
    }

    // Called when the emulator sends a byte to the serial port.
    fn send_byte(&mut self, _b: u8) {
        // TODO: Send a byte to a serial port.
    }

    // Called when the emulator peeks a byte from the serial port.
    fn recv_byte(&mut self) -> Option<u8> {
        // TODO: Check the status of the serial port and read a byte if any.
        None
    }

    // Called every time the emulator executes an instruction.
    fn sched(&mut self) -> bool {
        // TODO: Do some periodic jobs if any. Return `true` to continue, `false` to stop the emulator.
        println!("It's running!");
        true
    }

    // Called when the emulator stores the save data to the battery-backed RAM.
    fn load_ram(&mut self, size: usize) -> Vec<u8> {
        // TODO: Return save data.
        vec![0; size]
    }

    // Called when the emulator loads the save data from the battery-backed RAM.
    fn save_ram(&mut self, _ram: &[u8]) {
        // TODO: Store save data.
    }
}

fn main() {
    // Create the default config.
    let cfg = Config::new();

    // Create the hardware instance.
    let hw = Hardware::new();

    // TODO: The content of a ROM file, which can be downloaded from the Internet.
    let rom = vec![0u8; 1024];

    // Run the emulator.
    rgy::run(cfg, &rom, hw);
}

Modules

cpu

CPU state.

debug

Debugger interface.

device

Adaptor to register devices to MMU.

inst

Decoder which evaluates each CPU instructions.

mmu

Handles memory and I/O port access from the CPU.

Structs

Config

Configuration of the emulator.

System

Represents the entire emulator context.

Enums

Key

Represents a key of the joypad.

Constants

VRAM_HEIGHT

The height of the VRAM.

VRAM_WIDTH

The width of the VRAM.

Traits

Hardware

The interface to abstracts the OS-specific functions.

Stream

Sound wave stream which generates the wave to be played by the sound device.

Functions

run

Run the emulator with the given configuration.

run_debug

Run the emulator with the given configuration and debugger.