Crate rustynes_mappers

Expand description

Cartridge file format (iNES + NES 2.0) parsing and mapper implementations.

See docs/mappers.md and docs/cartridge-format.md for the implementation specs, and ref-docs/research-report.md §Cartridge for the source material.

Supports a broad set of mapper families covering the great majority of the licensed NES library: NROM, MMC1, MMC2/MMC4, MMC3 (Sharp default, NEC submapper), MMC5 (with vertical split-screen, ExGrafix, 4-byte fill mode, dual sprite/BG CHR for 8×16 sprites), UxROM, CNROM, AxROM, GxROM, Color Dreams, CPROM, BNROM/NINA (mapper 34 variants), Camerica BF9093, VRC1, VRC2/VRC4 (shared superset, submapper-dispatched), VRC3, VRC6, VRC7 (banking and IRQ; FM audio deferred per docs/adr/0004-vrc7-audio-deferred.md), Sunsoft FME-7, Namco 163, the Bandai discrete and FCG family, Jaleco SS88006, plus the v2.1.0 Tier 2 boards Tengen RAMBO-1 (64), Irem H3001 (65), Sunsoft-3 (67), Sunsoft-4 (68, CHR-ROM nametables), Holy Diver / Cosmo Carrier (78), TxSROM/TLSROM (118, per-bank nametable mirroring), and Namco 175/340 (210), and the v2.6.0 boards including the Nintendo Vs. System (99), the Taito X1-005 (80, on-cart battery RAM) / X1-017 (82, CHR A12-inversion mode), and Konami VS / VRC1-on-Vs. (151).

Structs§

Action52M228: Mapper 228 (Action 52 / Cheetahmen II).
Action53M28: Mapper 28 (Action 53 homebrew multicart).
AxRom: AxROM mapper.
Bandai74: Bandai discrete mapper (iNES mapper 70).
Bandai96: Mapper 96 (Bandai Oeka Kids).
Bandai152: Bandai 74161/161 1-screen mapper (iNES mapper 152).
BandaiFcg: Bandai FCG mapper (iNES mappers 16 + 159).
BgSplitState: Per-tile override produced by a mapper that implements a vertical split-screen mode (currently MMC5 via $5200-$5202).
Bitcorp38: Mapper 38 (Bit Corp UNL-PCI556).
Bxrom241: Mapper 241 (BxROM-like pirate board).
Caltron41: Mapper 41 (Caltron 6-in-1).
Camerica: Camerica / Codemasters BF9093 (Mapper 71).
Camerica232: Mapper 232 (Camerica Quattro / BF9096).
Cartridge: Concrete iNES / NES 2.0 cartridge value.
CnRom: CNROM mapper.
CnRom185: Mapper 185 (CNROM with CHR-disable copy protection).
Cne240: Mapper 240 (C&E multicart).
ColorDreams: Color Dreams (Mapper 11).
Cony83: Mapper 83 (Cony / Yoko).
Cprom: CPROM (Mapper 13).
Cufrom29: Mapper 29 (Sealie RET-CUFROM).
Daou156: Mapper 156 (DIS23C01 DAOU).
Decathlon244: Mapper 244 (Decathlon).
DiscreteMapper: A discrete unlicensed/multicart board with a simple register surface.
ExAttribute: Per-tile extended-attribute / extended-bank info supplied by mappers that implement an extended attribute mode (currently MMC5 in $5104 mode 01).
Fds: FDS RAM-adapter device, modelled as a Mapper.
FdsDisk: A parsed FDS disk image: an ordered list of disk sides.
FdsQuirk: Per-game FDS timing quirk: a per-CRC drive-timing table derived from puNES’s src/core/fds.c per-CRC drive table (GPL-2.0-or-later). See NOTICE and docs/originality-and-provenance.md (Section 1).
FdsTraceRec: One record in the optional FDS read-stream trace.
Fme7: Sunsoft FME-7 (Mapper 69). Bank-switching, CPU-cycle IRQ, and (gated behind mapper-audio) the on-cart Sunsoft 5B audio chip.
FongShenBang246: Mapper 246 (Fong Shen Bang / G0151-1).
Gtrom111: Mapper 111 (GTROM / Cheapocabra), written from nesdev_wiki/output/GTROM.md (v2.9.6 “Roster”: the register window, bonus RAM and self-flashing were added and the board promoted to Curated).
GxRom: GxROM mapper.
Header: Parsed header view, format-detected.
Hengedianzi177: Mapper 177 (Hengedianzi).
Hengedianzi179: Mapper 179 (Hengedianzi variant).
Inl31: Mapper 31 (INL-NSF-style 4 KiB-banked board).
Irem77: Mapper 77 (Irem, Napoleon Senki).
Irem97: Mapper 97 (Irem TAM-S1, Kaiketsu Yanchamaru).
IremG101: Irem G-101 mapper (iNES mapper 32).
IremH3001: Irem H3001 mapper (iNES mapper 65).
Jaleco72: Mapper 72 (Jaleco JF-17/JF-19).
Jaleco86: Mapper 86 (Jaleco JF-13).
Jaleco87: Jaleco/Konami mapper 87.
Jaleco92: Mapper 92 (Jaleco JF-19-variant — like 72 with a 5-bit PRG field).
Jaleco101: Mapper 101 (Jaleco JF-10 CHR latch).
Jaleco140: Mapper 140 (Jaleco JF-11/JF-14).
JalecoSs88006: Jaleco SS88006 mapper (iNES mapper 18).
Jy91: Mapper 91 (JY830623C / EJ-006-1).
JyAsic: J.Y. Company ASIC mapper (iNES 90 / 209 / 211).
KonamiVs: Konami VS (Mapper 151) — VRC1 on Vs. System hardware.
M34: Mapper 34 (BNROM / NINA-001).
M78: Mapper 78 (Holy Diver / Cosmo Carrier).
MagicDragon107: Mapper 107 (Magic Dragon).
MagicFloor218: Mapper 218 (“Magic Floor”).
Mapper42: Mapper 42 (FDS-to-cart conversion: Mario Baby / Ai Senshi Nicol).
Mapper50: Mapper 50 (Alibaba / SMB2J alternate FDS-to-cart conversion).
MapperCaps: v2.8.0 Phase 4 — per-CPU-cycle mapper capability flags (see Mapper::caps). Each flag corresponds to one of the four hooks the bus would otherwise virtually dispatch every CPU cycle.
MapperDebugInfo: Read-only debug snapshot of mapper-internal state for the UI.
MapperFrameEvents: APU frame-counter event mask fanned out to the mapper, used by on-cart audio extensions (MMC5, FDS, …) whose internal envelopes / length counters share the CPU’s frame-counter clocks.
Maxi15M234: Mapper 234 (Maxi 15 / BNROM-like multicart).
Mmc1: MMC1 mapper.
Mmc2: MMC2 (Mapper 9).
Mmc3: MMC3 mapper (iNES mapper 4).
Mmc4: MMC4 (Mapper 10).
Mmc5: MMC5 mapper (iNES mapper 5).
Mmc3Board: An MMC3 board with a board-specific layer between the MMC3’s bank outputs and the memories. See the module docs.
Mmc3CloneMapper: An MMC3-clone board: the shared MMC3-style core plus a board-specific outer-bank register and PRG/CHR transform.
Multicart15: Mapper 15 (K-1029 / 100-in-1 Contra Function 16 multicart).
Multicart58: Mapper 58 (multicart).
Multicart60: Mapper 60 (reset-based 4-in-1 multicart; power-on bank only).
Multicart61: Mapper 61 (0x80-style multicart).
Multicart62: Mapper 62 (multicart).
Multicart200: Mapper 200 (MG109 NROM-128 multicart).
Multicart201: Mapper 201 (NROM-256 multicart).
Multicart202: Mapper 202 (150-in-1 multicart).
Multicart203: Mapper 203 (35-in-1 multicart).
Multicart212: Mapper 212 (BMC Super HiK 300-in-1 multicart).
Multicart213: Mapper 213 (9999999-in-1 multicart).
Multicart214: Mapper 214 (Super Gun 20-in-1 multicart).
Multicart225: Mapper 225 (ColorDreams 72-in-1).
Multicart226: Mapper 226 (76-in-1 BMC).
Multicart227: Mapper 227 (1200-in-1 BMC).
Multicart229: Mapper 229 (31-in-1 BMC).
Multicart231: Mapper 231 (20-in-1 multicart).
Multicart233: Mapper 233 (42-in-1 reset-based BMC).
Namco118: Namco 118 / DxROM mapper (iNES 206 + 88).
Namco163: Namco 163 (Mapper 19). Banking + CPU-cycle IRQ + (gated behind mapper-audio) 1-8 channel wavetable audio.
Namco175: Namco 175 / 340 mapper (iNES mapper 210).
Namcot3425M95: Mapper 95 (NAMCOT-3425, Dragon Buster).
Namcot3446M76: Mapper 76 (NAMCOT-3446).
Nanjing163: Mapper 163 (Nanjing FC-001).
NesEvent105: Mapper 105 (NES-EVENT).
Nichibutsu180: Mapper 180 (Nichibutsu UNROM-inverted, Crazy Climber).
Nina006M113: Mapper 113 (NINA-006/MB-91 multicart).
Nina0379: Mapper 79 (AVE NINA-03/NINA-06).
Nitra250: Mapper 250 (Nitra, Time Diver Avenger).
Nrom: NROM mapper state.
Nsf: Parsed NSF header + program image.
NsfMapper: A synthetic “mapper” that plays an Nsf through the standard lockstep engine. See the module docs for the driver mechanism.
Ntdec63: Mapper 63 (NTDEC 0324 multicart).
Ntdec81: Mapper 81 (NTDEC Super Gun).
Ntdec174: Mapper 174 (NTDEC 5-in-1).
Ntdec2722M40: Mapper 40 (NTDEC 2722, SMB2J pirate).
NtdecAsder112: Mapper 112 (NTDEC ASDER / Huang-1).
Rambo1: Tengen RAMBO-1 mapper (iNES mapper 64).
Sachen133: Mapper 133 (Sachen 3009).
Sachen145: Mapper 145 (Sachen SA-72007).
Sachen146: Mapper 146 (Sachen, NINA-03/mapper-79-equivalent behaviour).
Sachen148: Mapper 148 (Sachen SA-008-A / Tengen 800008).
Sachen149: Mapper 149 (Sachen SA-0036).
Sachen150: Sachen SA-020A eight-register ASIC (iNES mappers 150 and 243).
Sachen8259: Sachen 8259 A/B/C (mappers 141 / 138 / 139). 32 KiB PRG + 2 KiB CHR banks.
Sachen3018M147: Mapper 147 (Sachen 3018 / TXC JV001).
Sachen8259M137: Mapper 137 (Sachen 8259D).
SachenTca01M143: Mapper 143 (Sachen TCA01).
Subor39: Mapper 39 (Subor BNROM-like, 32 KiB PRG).
Sunsoft1: Sunsoft-1 mapper (iNES mapper 184).
Sunsoft2: Sunsoft-2 IC (iNES mapper 89).
Sunsoft3: Sunsoft-3 mapper (iNES mapper 67).
Sunsoft4: Sunsoft-4 mapper (iNES mapper 68).
Sunsoft3r: Sunsoft-3R / Sunsoft-2 IC mapper (iNES mapper 93).
TaitoTc0190: Taito TC0190 / TC0350 mapper (iNES mapper 33).
TaitoTc0690: Taito TC0690 mapper (iNES mapper 48).
TaitoX1005: Taito X1-005 mapper (iNES mapper 80).
TaitoX1017: Taito X1-017 mapper (iNES mapper 82).
Tqrom: TQROM mapper (iNES mapper 119): MMC3 core with a mixed 64 KiB CHR-ROM + 8 KiB CHR-RAM address space.
TxSrom: TxSROM / TLSROM mapper (iNES mapper 118).
Txc36: Mapper 36 (TXC 01-22000 / Policeman).
Txc132: Mapper 132 (TXC 22211).
Un1rom94: Mapper 94 (UN1ROM).
UnifImage: A parsed + resolved UNIF image, ready to build a crate::Cartridge.
Unrom512M30: Mapper 30 (UNROM-512).
UxRom: UxROM mapper.
Vrc1: VRC1 (Mapper 75).
Vrc2: VRC2 (Mapper 22 + sub-variants of 23/25).
Vrc3: Konami VRC3 mapper (iNES mapper 73).
Vrc4: VRC4 (and treats VRC2 hardware as a no-IRQ subset since the banking is identical). IRQ counter is 8-bit, clocked per CPU cycle by default (mode bit selects scanline mode where it ticks every 114 cycles).
Vrc6: VRC6 (Mappers 24 / 26). Audio extension is implemented behind the mapper-audio Cargo feature (default ON).
Vrc7: VRC7 (Mapper 85). Banking + IRQ + (deferred per ADR-0004) FM audio surface for Lagrange Point.
VsSystem: Nintendo Vs. System mapper (iNES mapper 99).
Waixing178: Mapper 178 (Waixing educational series).
Waixing242: Mapper 242 (Waixing 43-in-1).
WaixingFs304M162: Mapper 162 (Waixing FS304).

Enums§

ConsoleType: Console type from NES 2.0 header byte 7 (bits 0-1).
DiscreteBoard: Which discrete board the DiscreteMapper models.
ExpansionDevice: Default expansion device: NES 2.0 header byte 15, bits 0-6.
ExtendedConsoleType: Extended console type: NES 2.0 header byte 13, low nibble, when the console type (byte 7 bits 0-1) is 3.
FcgVariant: FCG board / EEPROM variant.
JyBoard: Which iNES mapper number wired the ASIC. Selects the ROM-nametable / extended-mirroring policy and the mapper 209 MMC4 auto-latch behaviour.
M34Variant: Mapper 34 variant.
M78Variant: Mirroring wiring variant, selected by NES 2.0 submapper.
MapperError: Errors produced by mapper save-state load.
MapperTier: Accuracy-evidence tier for a supported mapper family. See the module docs.
Mirroring: Nametable mirroring layout selected by the cartridge wiring.
Mmc3BoardKind: Which board an Mmc3Board models.
Mmc3Revision: MMC3 IRQ-counter behaviour. Default is the Sharp (“new”) behaviour; the alternative suppresses the “reload to 0 asserts IRQ” behaviour.
Mmc3Variant: Which chip or board wiring an Mmc3 models, beyond the IRQ revision (the NES 2.0 submappers of mapper 4, NES_2_0_submappers.md). v2.9.6.
Namco118Board: Board variant for the Namco 118 family.
Namco175Board: Board variant for mapper 210.
Region: Region governing CPU/PPU dividers, scanline counts, audio rate tables.
RomError: Errors returned by crate::parse.
Sa020aBoard: Mapper 150 (Sachen SA-015/SA-630, UNL-Sachen-74LS374N). Which PCB the SA-020A ASIC is wired into.
Sachen8259Variant: Which Sachen 8259 variant (CHR shift + OR constants).
UnifError: Errors from parsing a UNIF container.
VsHardwareType: Vs. System hardware type: NES 2.0 header byte 13, high nibble, when the console type (byte 7 bits 0-1) is 1.
VsPpuPalette: Hardware RGB palette selected by a Vs. System / PlayChoice-10 PPU.
VsPpuType: Vs. System PPU type from NES 2.0 header byte 13 low nibble.

Constants§

DISK_BYTE_CYCLES: Nominal CPU cycles between disk byte transfers.
FDS_SIDE_LEN: Bytes per disk side in the common .fds / fwNES file format (no CRCs, no gaps). The on-disk physical capacity and the QD (65536) variant are larger; see FDS_disk_format.xhtml §True disk capacity.
HEAD_RESEEK_CYCLES: Head re-seek time (CPU cycles) modelled on a motor restart.
NWC_TOURNAMENT_DIP: The tournament DIP setting: switch C closed.

Traits§

Mapper: Trait implemented by every cartridge mapper.

Functions§

board_to_mapper: Resolve a UNIF MAPR board name to its iNES mapper id, or None if the board is unknown / not implemented by RustyNES.
fds_crc32: CRC-32/ISO-HDLC (the standard zlib/PNG “CRC-32”) over data.
is_nsf: Detect an NSF-family music file (classic NESM or extended NSFE).
mapper_tier: Classify a mapper family by its iNES id and NES 2.0 submapper into a MapperTier.
mirroring_name: Helper for mapper debug_info overrides.
new_m44: Mapper 44 (BMC SuperBig 7-in-1 MMC3 multicart).
new_m46: Mapper 46 (Color Dreams Rumble Station 15-in-1).
new_m49: Mapper 49 (BMC 4-in-1 MMC3 multicart).
new_m51: Mapper 51 (BMC 11-in-1 multicart).
new_m52: Mapper 52 (BMC Mario 7-in-1 MMC3 multicart).
new_m56: Mapper 56 (Kaiser KS202).
new_m57: Mapper 57 (BMC GK 6-in-1 multicart).
new_m104: Mapper 104 (Codemasters Golden Five / Pegasus 5-in-1).
new_m115: Mapper 115 (Kasheng SFC-02B/-03/-004 MMC3 clone).
new_m120: Mapper 120 (Tobidase Daisakusen FDS-conversion protection).
new_m134: Mapper 134 (T4A54A / WX-KB4K MMC3-clone multicart).
new_m136: Mapper 136 (Sachen 3011, TXC protection CHR select).
new_m142: Mapper 142 (Kaiser KS7032).
new_m164: Mapper 164 (Waixing Final Fantasy V, 32 KiB-PRG split register).
new_m176: Mapper 176 (8025 enhanced-MMC3 ASIC: Waixing FK23C, and FS005 on submapper 2).
new_m189: Mapper 189 (TXC 32 KiB-PRG MMC3 clone).
new_m193: Mapper 193 (NTDEC TC-112, Fighting Hero).
new_m204: Mapper 204 (discrete NROM/UNROM 2-in-1 BMC multicart).
new_m205: Mapper 205 (BMC 3-in-1 / 15-in-1 MMC3 multicart).
new_m221: Mapper 221 (NTDEC N625092 multicart).
new_m238: Mapper 238 (MMC3 clone + $4020-$7FFF security LUT).
new_m245: Mapper 245 (Waixing MMC3 clone, CHR-RAM PRG-256K outer).
new_m253: Mapper 253 (Waixing VRC4-clone, Dragon Ball Z).
new_m261: Mapper 261 (BMC-810544-C-A1 address-as-data multicart).
new_m268: Mapper 268 (COOLBOY / MINDKIDS MMC3-clone multicart).
new_m286: Mapper 286 (Waixing BS-5 Olympic multicart).
new_m289: Mapper 289 (BMC-60311C NROM/UNROM multicart).
new_m290: Mapper 290 (NTDEC Asder BMC-NTD-03).
new_m299: Mapper 299 (TXC/BMC-11160 multicart).
new_m301: Mapper 301 (BMC-8157 address-as-data multicart).
new_m303: Mapper 303 (Kaiser KS7017).
new_m305: Mapper 305 (Kaiser KS7031).
new_m306: Mapper 306 (Kaiser KS7016).
new_m312: Mapper 312 (Kaiser KS7013B).
new_m320: Mapper 320 (BMC-830425C-4391T UNROM/UOROM multicart).
new_m336: Mapper 336 (BMC-K-3046 UNROM-style multicart).
new_m348: Mapper 348 (BMC-830118C MMC3 multicart).
new_m349: Mapper 349 (BMC-G-146 NROM/UNROM/NROM-256 multicart).
new_m366: Mapper 366 (BMC-GN-45 MMC3 multicart).
new_m513: Mapper 513 (Sachen 9602 MMC3-clone).
parse: Parse an iNES 1.0 / NES 2.0 ROM file.
parse_fds: Parse a .fds / fwNES disk image into an FdsDisk.
parse_header: Parse a 16-byte header into a Header.
parse_nsf: Parse an NSF-family music file — classic NESM or extended NSFE.
parse_unif: Parse a UNIF container into a resolved UnifImage.
quirk_for_crc: Look up the per-game FdsQuirk for a disk image by its CRC-32.
serialize_header_preserving: Write the edits in h over original, the 16 header bytes h was parsed from, and return the result.
unif_to_ines: Synthesize an equivalent NES 2.0 image from a parsed UNIF, so the standard crate::parse path builds the crate::Cartridge + mapper with zero duplicated mapper construction.
version: Returns the crate version string.