nesemu/docs/api_contract.md

API Contract

This document defines the supported external contract for nesemu 0.x.

Use this file as the boundary of what external clients should rely on. For practical embedding examples, see integration.md. For internal structure, see architecture.md.

Supported Surface

External users should prefer these entry points:

• Root crate re-exports from src/lib.rs
• nesemu::runtime::*
• nesemu::prelude::*

Optional adapter-facing API is available behind features:

• adapter-api
• adapter-headless

Recommended Public Entry Points

The main public API is organized around these groups:

• ROM loading:
  • parse_header
  • parse_rom
  • InesHeader
  • InesRom
  • Mirroring
• Cartridge mapping:
  • create_mapper
  • Mapper
• Low-level execution:
  • Cpu6502
  • CpuBus
  • CpuError
  • NativeBus
  • Ppu
  • Apu
  • ApuStateTail
  • ChannelOutputs
• High-level runtime:
  • NesRuntime
  • RuntimeError
• Host execution and lifecycle:
  • RuntimeHostLoop
  • ClientRuntime
  • HostConfig
  • EmulationState
• Host IO traits:
  • InputProvider
  • VideoOutput
  • AudioOutput
• Null/stub implementations:
  • NullInput
  • NullVideo
  • NullAudio
• Audio helpers:
  • AudioMixer
  • RingBuffer
• Timing and pacing:
  • FrameClock
  • FramePacer
  • PacingClock
  • NoopClock
  • VideoMode
• Video constants:
  • FRAME_WIDTH
  • FRAME_HEIGHT
  • FRAME_RGBA_BYTES
• Input helpers:
  • JoypadButton
  • JoypadButtons
  • JOYPAD_BUTTON_ORDER
  • JOYPAD_BUTTONS_COUNT
  • set_button_pressed
  • button_pressed
• State versioning:
  • SAVE_STATE_VERSION

Supported Client Flow

The expected integration flow is:

1. Load ROM bytes and parse them, or construct NesRuntime directly from ROM bytes.
2. Choose your integration level:
   • use Cpu6502 + NativeBus for low-level control
   • use NesRuntime for a higher-level core wrapper
   • use RuntimeHostLoop or ClientRuntime for host-facing frame execution
3. Provide input, video, and audio implementations through the public host traits.
4. Use save/load state through the runtime or bus APIs when snapshot behavior is needed.

Stability Rules

The following are considered the primary supported surface for 0.x:

• root re-exports
• runtime
• prelude

The following are available but less stable:

• native_core::* for advanced or experimental integrations

Lower-level modules may evolve faster than the root re-export surface.

Compatibility Notes

• Types marked #[non_exhaustive] may gain fields or variants without a major version bump.
• Save-state compatibility is only guaranteed within the same crate version unless explicitly documented otherwise.
• Optional features may expose additional adapter-facing API, but they do not change the baseline contract of the main library.

Extension Points

The intended extension points for hosts and frontends are:

• InputProvider
• VideoOutput
• AudioOutput
• FrameClock
• optional adapter bridge types when adapter-api is enabled:
  • InputAdapter
  • VideoAdapter
  • AudioAdapter
  • ClockAdapter

Out Of Scope

This contract does not promise stability for:

• GTK frontend behavior in nesemu-desktop
• internal module layout under native_core and runtime
• concrete implementation details of mapper modules
• cross-version save-state compatibility unless explicitly documented