Struct HardwareOptions 

#[non_exhaustive]
pub struct HardwareOptions {

    pub console_model: ConsoleModel,
    pub ppu_revision: PpuRevision,
    pub cpu_2a03_revision: Cpu2A03Revision,
    pub oam_decay: bool,
    pub power_on_ram: PowerOnRam,
    pub power_up_palette: PaletteInit,
    pub extra_scanlines: u16,
    pub cpu_overclock: u8,
    pub sprite_limit_disabled: bool,
    pub mmc3_revision: Option<Mmc3Revision>,
    pub four_score: bool,
    pub zapper_temporal_light: bool,
    pub vs_dip: u8,
    pub vs_ppu_type: Option<VsPpuType>,
    pub mirroring_override: Option<Mirroring>,
    pub genie_codes: Vec<String>,
}

Every host-settable option that changes what the emulated console does.

Default is the stock NES: the configuration every release before the option existed emulated, and what a foreign movie import (.fm2, .bk2, .fcm, .fmv, .vmv, .mc2) records, because those formats cannot say anything else.

One exception to “all defaults are the default build”: the Vs. PPU type is a property of the cartridge header that a host may override, so its default is None, meaning “whatever the header declares” — applying a stock VsPpuType::None to a Vs. cartridge would strip its RGB PPU.

#[non_exhaustive] since v3.0.0 (T-API-EXTENSIBLE): outside this crate, start from HardwareOptions::default (the stock NES) or HardwareOptions::capture and set the fields that differ. A later option is then not a break.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

console_model: ConsoleModel

Which console’s reset wiring is modelled (Nes::set_console_model).

ppu_revision: PpuRevision

The 2C02 die revision (Nes::set_ppu_revision).

cpu_2a03_revision: Cpu2A03Revision

The 2A03 die revision (Nes::set_cpu_2a03_revision).

oam_decay: bool

The optional OAM-decay model (Nes::set_oam_decay).

power_on_ram: PowerOnRam

The power-on work-RAM fill (Nes::set_power_on_ram).

power_up_palette: PaletteInit

The power-up palette-RAM contents (Nes::set_power_up_palette).

extra_scanlines: u16

The extra-vblank-scanline overclock (Nes::set_extra_scanlines).

cpu_overclock: u8

The CPU-multiplier overclock, 1..=MAX_CPU_OVERCLOCK (Nes::set_cpu_overclock); 1 is stock. v3.1.0. A value outside that range never reaches the core as written: decoding a record refuses it, and applying one clamps it (0 to 1, anything above to the maximum), as Nes::set_cpu_overclock does.

sprite_limit_disabled: bool

Draw the sprites beyond the eighth on a scanline (Nes::set_sprite_limit_disabled); render-only. v3.1.0.

mmc3_revision: Option<Mmc3Revision>

A forced MMC3 IRQ revision (Nes::set_mmc3_revision_override); None = the header’s. v3.1.0.

four_score: bool

Whether the Four Score adapter is plugged in (Nes::set_four_score). It changes $4016 / $4017 reads 9-24 even with players 3/4 idle.

zapper_temporal_light: bool

The beam-relative Zapper light model (Nes::set_zapper_temporal_light).

vs_dip: u8

The Vs. System DIP-switch bank (Nes::set_vs_dip); read through $4016 / $4017 on Vs. carts, inert elsewhere.

vs_ppu_type: Option<VsPpuType>

The Vs. System PPU type (Nes::set_vs_ppu_type); None = the header’s. See the type-level note.

mirroring_override: Option<Mirroring>

The per-game nametable mirroring override (Nes::set_mirroring_override); None = the mapper decides.

genie_codes: Vec<String>

The active Game Genie codes, canonical upper-case strings in address order (Nes::add_genie_code).

Implementations

impl HardwareOptions

pub fn capture(nes: &Nes) -> Self

The options nes is running with right now.

pub fn apply(&self, nes: &mut Nes) -> Result<(), String>

Apply every option to nes, including the two power-on fills.

The fills write live state: Nes::set_power_on_ram refills work RAM and the open-bus latch, and Nes::set_power_up_palette rewrites palette RAM. That is right before a power cycle or a save-state restore (which replace that state anyway) and wrong in the middle of a game, where Self::apply_live is the call to make.

Errors

Returns the offending code if a Game Genie string does not decode. Codes read through Self::read_from are validated there, so this can only fail for a hand-built value.

pub fn apply_live(&self, nes: &mut Nes) -> Result<(), String>

Apply every option except the two power-on fills, never writing work RAM or palette RAM. Each knob is compared first and set only if it differs, so calling this once per frame to hold a movie’s options in place costs a handful of comparisons.

The fills are excluded because they act only at the next power cycle and applying them writes the running game’s RAM; see Self::apply.

Errors

Returns the offending code if a Game Genie string does not decode.

pub fn restore_after_playback(&self, nes: &mut Nes) -> Result<(), String>

Put nes back on these options after a movie ran on others, without disturbing the game in progress.

Self::apply_live alone would leave the movie’s power-on fills stored, so the player’s next power cycle would boot with the movie’s RAM pattern. Storing the player’s fills means calling their setters, which write work RAM and palette RAM, so this takes a snapshot first and restores it afterwards: the snapshot carries RAM, the open-bus latch and palette RAM but not configuration, so the restore puts the running game back exactly while the stored fills stay the player’s. Skipped when the fills already match, which is the common case.

Errors

Returns the offending code if a Game Genie string does not decode.

pub fn write_to(&self, w: &mut BinWriter)

Append the canonical encoding to w.

Layout (all little-endian): console model, PPU revision, 2A03 revision, OAM decay, power-on RAM kind + u64 payload, power-up palette, extra scanlines (u16), CPU overclock, the sprite-limit flag and the MMC3 revision override (0 = header, 1 = Sharp, 2 = the alternate; all three since .rnm format 6 and netplay protocol 7, v3.1.0), Four Score, Zapper light model, Vs. DIP, Vs. PPU type (0xFF = the header’s), mirroring override (0 = none, else variant + 1), then a code count and each Game Genie code as a length byte plus ASCII. Every enum is an explicit byte, never a discriminant cast, so reordering a Rust enum cannot silently change what an old file means.

pub fn read_from(r: &mut BinReader<'_>) -> Result<Self, OptionsDecodeError>

Decode what Self::write_to wrote. Strict: an unknown enum byte, a boolean other than 0 or 1, or a Game Genie code that does not decode is an error, never a silent default, because a default here is exactly the silent divergence this record exists to prevent.

Errors

A fixed description of the first malformed field, or "truncated".

pub fn to_bytes(&self) -> Vec<u8>

The canonical encoding as a byte vector.

pub fn differences(&self, other: &Self) -> Vec<&'static str>

Every option that differs between self and other, by name, in field order. Empty when they agree. For an error message a person can act on: “OAM decay, console model” rather than “the options differ”.

Trait Implementations

impl Clone for HardwareOptions

fn clone(&self) -> HardwareOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HardwareOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for HardwareOptions

fn default() -> Self

Returns the “default value” for a type.

impl Eq for HardwareOptions

impl Hash for HardwareOptions

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for HardwareOptions

fn eq(&self, other: &HardwareOptions) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for HardwareOptions