neser 1.2.0

NESER - Nintendo Emulation Systems Engine (Rust). Desktop and WebAssembly frontends.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213

//! Mapper 244 - Decathlon (C-N22M)
//!
//! Specifications:
//! - Main: <https://www.nesdev.org/wiki/INES_Mapper_244>
//!
//! Known Limitations:
//! - No known gameplay-blocking functional limitations are currently documented.

use crate::nes::cartridge::base_mapper::BaseMapper;
use crate::nes::cartridge::mapper::{Mapper, MapperCapabilities};

/// Mapper 244 - Decathlon (C-N22M)
///
/// Hardware: Simple PRG+CHR bank switching with lookup tables.
///
/// Specifications:
/// - Main: <https://www.nesdev.org/wiki/INES_Mapper_244>
/// - PRG-ROM: Up to 128KB (4 x 32KB banks)
/// - CHR-ROM: Up to 64KB (8 x 8KB banks)
/// - Mirroring: Fixed from header
///
/// Write to $8000-$FFFF:
/// - If bit 3 == 0: bits 0-1 select PRG bank (through lookup table)
/// - If bit 3 == 1: bits 0-2 select CHR bank (through lookup table)
///
/// The lookup tables implement a simple copy-protection scramble:
/// - PRG: Identity mapping [0, 1, 2, 3]
/// - CHR: Swapped pairs [0, 2, 1, 3, 4, 6, 5, 7]
pub struct Mapper244 {
    base: BaseMapper,
}

impl Mapper244 {
    /// PRG bank lookup table (identity)
    const PRG_LUT: [u8; 4] = [0, 1, 2, 3];
    /// CHR bank lookup table (pairs 1/2 and 5/6 swapped)
    const CHR_LUT: [u8; 8] = [0, 2, 1, 3, 4, 6, 5, 7];

    pub fn new(ctx: crate::nes::cartridge::mapper::MapperContext) -> Self {
        let capabilities = MapperCapabilities {
            has_chr_banking: true,
            max_prg_ram_kb: 8,
            prg_bank_size_kb: 32,
            chr_bank_size_kb: 8,
            ..Default::default()
        };
        let mut base = BaseMapper::new(&ctx, capabilities);
        base.configure_prg_banking(32 * 1024);
        base.configure_chr_banking(8 * 1024);
        Self { base }
    }
}

impl Mapper for Mapper244 {
    fn base(&self) -> &BaseMapper {
        &self.base
    }

    fn base_mut(&mut self) -> &mut BaseMapper {
        &mut self.base
    }

    fn write_prg(&mut self, addr: u16, value: u8) {
        if self.base.try_write_prg_ram(addr, value) {
            return;
        }
        if (0x8000..=0xFFFF).contains(&addr) {
            if value & 0x08 == 0 {
                // PRG bank select via LUT
                let index = (value & 0x03) as usize;
                self.base.select_prg_page(0, Self::PRG_LUT[index] as i16);
            } else {
                // CHR bank select via LUT
                let index = (value & 0x07) as usize;
                self.base.select_chr_page(0, Self::CHR_LUT[index] as i16);
            }
        }
    }

    fn registers_snapshot(&self) -> Vec<u8> {
        self.base.banking_snapshot()
    }

    fn restore_registers(&mut self, data: &[u8]) {
        self.base.restore_banking(data);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::nes::cartridge::NametableLayout;
    use crate::nes::cartridge::mapper::{MapperContext, create_mapper};
    use crate::nes::cartridge::test_helpers::banked_data;

    fn create_mapper244(
        prg_rom: Vec<u8>,
        chr_rom: Vec<u8>,
        mirroring: NametableLayout,
    ) -> std::io::Result<Box<dyn Mapper>> {
        create_mapper(MapperContext::new_for_test(
            244, prg_rom, chr_rom, mirroring,
        ))
    }

    #[test]
    fn test_factory_creates_mapper_244() {
        let prg_rom = banked_data(32 * 1024, 4);
        let chr_rom = banked_data(8 * 1024, 8);
        let mapper = create_mapper244(prg_rom, chr_rom, NametableLayout::Vertical);
        assert!(mapper.is_ok(), "Mapper 244 should be creatable via factory");
    }

    #[test]
    fn test_prg_bank_select_via_lut() {
        let prg_rom = banked_data(32 * 1024, 4);
        let chr_rom = banked_data(8 * 1024, 8);
        let mut mapper = create_mapper244(prg_rom, chr_rom, NametableLayout::Vertical).unwrap();

        // PRG LUT is identity: [0, 1, 2, 3]
        // value bit 3 == 0, so bits 0-1 select PRG bank via LUT
        mapper.write_prg(0x8000, 0); // index 0 -> bank 0
        assert_eq!(mapper.read_prg(0x8000), 0);

        mapper.write_prg(0x8000, 1); // index 1 -> bank 1
        assert_eq!(mapper.read_prg(0x8000), 1);

        mapper.write_prg(0x8000, 2); // index 2 -> bank 2
        assert_eq!(mapper.read_prg(0x8000), 2);

        mapper.write_prg(0x8000, 3); // index 3 -> bank 3
        assert_eq!(mapper.read_prg(0x8000), 3);
    }

    #[test]
    fn test_chr_bank_select_via_scrambled_lut() {
        let prg_rom = banked_data(32 * 1024, 4);
        let chr_rom = banked_data(8 * 1024, 8);
        let mut mapper = create_mapper244(prg_rom, chr_rom, NametableLayout::Vertical).unwrap();

        // CHR LUT: [0, 2, 1, 3, 4, 6, 5, 7]
        // value bit 3 == 1, so bits 0-2 select CHR bank via LUT
        mapper.write_prg(0x8000, 0x08); // index 0 -> bank 0
        assert_eq!(mapper.read_chr(0x0000), 0);

        mapper.write_prg(0x8000, 0x09); // index 1 -> bank 2 (scrambled!)
        assert_eq!(mapper.read_chr(0x0000), 2);

        mapper.write_prg(0x8000, 0x0A); // index 2 -> bank 1 (scrambled!)
        assert_eq!(mapper.read_chr(0x0000), 1);

        mapper.write_prg(0x8000, 0x0B); // index 3 -> bank 3
        assert_eq!(mapper.read_chr(0x0000), 3);

        mapper.write_prg(0x8000, 0x0C); // index 4 -> bank 4
        assert_eq!(mapper.read_chr(0x0000), 4);

        mapper.write_prg(0x8000, 0x0D); // index 5 -> bank 6 (scrambled!)
        assert_eq!(mapper.read_chr(0x0000), 6);

        mapper.write_prg(0x8000, 0x0E); // index 6 -> bank 5 (scrambled!)
        assert_eq!(mapper.read_chr(0x0000), 5);

        mapper.write_prg(0x8000, 0x0F); // index 7 -> bank 7
        assert_eq!(mapper.read_chr(0x0000), 7);
    }

    #[test]
    fn test_mirroring_is_fixed() {
        let prg_rom = banked_data(32 * 1024, 4);
        let chr_rom = banked_data(8 * 1024, 8);
        let mut mapper = create_mapper244(prg_rom, chr_rom, NametableLayout::Horizontal).unwrap();

        assert_eq!(mapper.get_mirroring(), NametableLayout::Horizontal);
        mapper.write_prg(0x8000, 0xFF);
        assert_eq!(mapper.get_mirroring(), NametableLayout::Horizontal);
    }

    #[test]
    fn test_prg_and_chr_banks_are_independent() {
        let prg_rom = banked_data(32 * 1024, 4);
        let chr_rom = banked_data(8 * 1024, 8);
        let mut mapper = create_mapper244(prg_rom, chr_rom, NametableLayout::Vertical).unwrap();

        // Set PRG bank 2
        mapper.write_prg(0x8000, 2);
        assert_eq!(mapper.read_prg(0x8000), 2);
        assert_eq!(mapper.read_chr(0x0000), 0); // CHR unchanged

        // Set CHR bank (index 1 -> bank 2)
        mapper.write_prg(0x8000, 0x09);
        assert_eq!(mapper.read_prg(0x8000), 2); // PRG unchanged
        assert_eq!(mapper.read_chr(0x0000), 2);
    }

    #[test]
    fn test_registers_snapshot_and_restore() {
        let prg_rom = banked_data(32 * 1024, 4);
        let chr_rom = banked_data(8 * 1024, 8);
        let mut mapper =
            create_mapper244(prg_rom.clone(), chr_rom.clone(), NametableLayout::Vertical).unwrap();

        mapper.write_prg(0x8000, 2); // PRG bank 2
        mapper.write_prg(0x8000, 0x0D); // CHR bank 6 (LUT index 5)

        let regs = mapper.registers_snapshot();

        let mut restored = create_mapper244(prg_rom, chr_rom, NametableLayout::Vertical).unwrap();
        restored.restore_registers(&regs);
        assert_eq!(restored.read_prg(0x8000), 2);
        assert_eq!(restored.read_chr(0x0000), 6);
    }
}