Crate tetanes_core

TetaNES Core

📖 Summary - ✨ Features - 🚧 Building - 🚀 Getting Started - ⚠️ Known Issues - 💬 Contact

Summary

photo credit for background: Zsolt Palatinus on unsplash

This is the core emulation library for TetaNES. Savvy developers can build their own custom emulation libraries or applications in Rust on top of tetanes-core.

Some community examples:

• NES Bundler - Transform your NES-game into a single executable targeting your favourite OS!
• Dappicom - Dappicom is a provable Nintendo Entertainment System emulator written in Noir and Rust.
• NESBox - NESBox’s vision is to become the preferred platform for people playing online multiplayer games, providing an excellent user experience for all its users.

Minimum Supported Rust Version (MSRV)

The current minimum Rust version is 1.85.0.

Features

• NTSC, PAL and Dendy emulation.
• Headless Mode.
• Pixellate and NTSC filters.
• Zapper (Light Gun) support.
• iNES and NES 2.0 ROM header formats supported.
• Over 30 supported mappers covering >90% of licensed games.
• Game Genie Codes.
• Preference snd keybonding menus using egui.
  • Increase/Decrease speed & Fast Forward
  • Save & Load States
  • Battery-backed RAM saves

Building

To build the project, you’ll need a nightly version of the compiler and run cargo build or cargo build --release (if you want better framerates).

Feature Flags

• profiling - Enables puffin profiling.

Getting Started

Below is a basic example of setting up tetanes_core with a ROM and running the emulation. For a more in-depth example see the tetanes::nes::emulation module.

use tetanes_core::prelude::*;

fn main() -> anyhow::Result<()> {
    let mut control_deck = ControlDeck::new();

    // Load a ROM from the filesystem.
    // See also: `ControlDeck::load_rom` for loading anything that implements `Read`.
    control_deck.load_rom_path("some_awesome_game.nes")?;

    while control_deck.is_running() {
      // See also: `ControlDeck::clock_frame_output` and `ControlDeck::clock_frame_into`
      control_deck.clock_frame()?;

      let audio_samples = control_deck.audio_samples();
      // Process audio samples (e.g. by sending it to an audio device)
      control_deck.clear_audio_samples();

      let frame_buffer = control_deck.frame_buffer();
      // Process frame buffer (e.g. by rendering it to the screen)

      // If not relying on vsync, sleep or otherwise wait the remainder of the
      // 16ms frame time to clock again
    }

    Ok(())
}

Stability

The aim is for general stability, but the version isn’t 1.0 yet and there are several large features on the roadmap that may result in breaking changes. This applies to both APIs and save file formats.

Once some of these larger features are completed, and 1.0 is released, more effort will be dedicatged to versioning these files for backward compatibility in the event of future breaking changes.

Known Issues

See the github issue tracker.

Contact

For issue reporting, please use the github issue tracker. You can also contact me directly at https://lukeworks.tech/contact/.

Modules

action

An Action is an enumerated list of possible state changes to ControlDeck.

apu

NES APU (Audio Processing Unit) implementation.

bus

NES Memory/Data Bus implementation.

cart

NES cartridge implementation.

common

Common traits and constants.

control_deck

Control Deck implementation. The primary entry-point for emulating the NES.

cpu

6502 Central Processing Unit (CPU) implementation.

debug

error

Error handling.

fs

Filesystem utilities for save state and compression.

genie

Game Genie code parsing.

input

Joypad and Zapper implementation.

mapper

Memory Mappers for cartridges.

mem

Memory and Bankswitching implementations.

ppu

NES PPU (Picture Processing Unit) implementation.

prelude

The prelude re-exports all the common structs/enums used for basic NES emulation.

sys

System-specific modules.

time

Time and Date methods.

video

Video output and filtering.