Struct ExecutionEngine 

pub struct ExecutionEngine {
    pub emu: Nes,
    pub config: ExecutionConfig,
    pub savestate_config: SavestateConfig,
    pub frames: Vec<Vec<u16>>,
    /* private fields */
}

The main execution engine for CLI-driven emulation.

This struct manages the emulator lifecycle and provides a clean API for running emulation with various configurations.

Video Export Modes

• Buffered mode (default): All frames are stored in memory, then encoded at the end. Suitable for small exports or when you need access to all frames.

• Streaming mode: Frames are encoded immediately as they are generated. Use run_with_video_encoder() for this mode. Significantly reduces memory usage for long recordings.

Fields

emu: Nes

The emulator instance

config: ExecutionConfig

Execution configuration

savestate_config: SavestateConfig

Savestate configuration

frames: Vec<Vec<u16>>

Collected frames (used in buffered mode) - raw palette indices

Implementations

impl ExecutionEngine

pub fn new() -> Self

Create a new execution engine with default emulator

pub fn with_emulator(emu: Nes) -> Self

Create execution engine with existing emulator

pub fn with_config(self, config: ExecutionConfig) -> Self

Set execution configuration

pub fn with_savestate_config(self, config: SavestateConfig) -> Self

Set savestate configuration

pub fn load_rom(&mut self, path: &Path) -> Result<(), String>

Load ROM from path

pub fn power_on(&mut self)

Power on the emulator

pub fn power_off(&mut self)

Power off the emulator

pub fn reset(&mut self)

Reset the emulator

pub fn load_savestate(&mut self) -> Result<(), String>

Load savestate based on configuration

pub fn save_savestate(&self) -> Result<(), String>

Save savestate based on configuration

pub fn run(&mut self) -> Result<ExecutionResult, String>

Run execution until a stop condition is met

pub fn run_with_video_encoder( &mut self, encoder: &mut StreamingVideoEncoder, renderer: &mut Box<dyn ScreenRenderer>, ) -> Result<ExecutionResult, String>

Run execution with streaming video export.

This mode writes frames directly to the video encoder as they are generated, instead of buffering all frames in memory. This significantly reduces memory usage for long recordings.

Arguments

• encoder - A streaming video encoder that will receive frames as they’re generated

Performance

• Uses parallel upscaling via rayon (if encoder has upscaling enabled)
• O(1) memory usage per frame instead of O(n) for all frames
• Frames are written immediately, reducing peak memory usage

FPS Multipliers

When the encoder’s FPS config specifies a multiplier > 1 (e.g., 2x, 3x), this method captures frames at sub-frame intervals. For example:

• 2x: Captures at mid-frame and end of frame (2 captures per PPU frame)
• 3x: Captures at 1/3, 2/3, and end of frame (3 captures per PPU frame)

This produces true intermediate states showing partial rendering progress.

pub fn set_collect_frames(&mut self, collect: bool)

Enable or disable frame collection.

When disabled, frames are not stored in memory during execution. Use this for streaming mode or when you don’t need frame data.

pub fn emulator(&self) -> &Nes

Get reference to the emulator

pub fn emulator_mut(&mut self) -> &mut Nes

Get mutable reference to the emulator

Trait Implementations

impl Default for ExecutionEngine

fn default() -> Self

Returns the “default value” for a type.