Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 28 additions & 3 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,20 @@ on:

jobs:
test:
runs-on: ubuntu-latest
# The three the README hands the same zip to. The console is the same bytes on all of them --
# nothing in mynes-core knows what a file separator is -- so what the second and third runner
# buy is everything that is not the console: the Swing panels every desktop test builds without
# a display, the sound card, the config file under a home directory, and the saves filed beside
# a ROM. Those are exactly the places a Java program still manages to be platform-specific.
strategy:
# One runner failing is a fact about that runner. Stopping the other two would throw away the
# thing worth knowing, which is whether it failed everywhere or only there.
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]

runs-on: ${{ matrix.os }}

steps:
- uses: actions/checkout@v7
- name: Set up JDK 25
Expand All @@ -22,18 +35,24 @@ jobs:
distribution: 'temurin'
cache: 'maven'

# ~1.4GB of Tom Harte fixtures. The committed subset covers every opcode without
# this, so a cache miss that fails to download is not fatal to the test run.
# ~1.4GB of Tom Harte fixtures, on one runner rather than three. What they exercise is the
# 6502, which is the one part of this that cannot tell which machine it is running on, so
# fetching them again for the other two would cost three times the bandwidth to answer the
# same question. The committed subset covers every opcode everywhere, which is why the
# download is allowed to fail here at all: the other two runners test all 256 opcodes too,
# with 500 cases each instead of 10,000.
#
# Inside the module because HarteCaseLoader resolves the path relative to wherever
# Surefire runs, which is the module rather than the checkout.
- name: Cache 6502 test data
if: matrix.os == 'ubuntu-latest'
uses: actions/cache@v6
with:
path: mynes-core/testdata/nes6502
key: nes6502-${{ hashFiles('scripts/download-6502-tests.sh') }}

- name: Download 6502 test data
if: matrix.os == 'ubuntu-latest'
continue-on-error: true
run: ./scripts/download-6502-tests.sh

Expand All @@ -42,7 +61,13 @@ jobs:

# Here rather than only in the release workflow, so that a distribution somebody has broken
# fails on the pull request that broke it instead of at the moment a tag is pushed.
#
# Not on Windows, and not because bash is missing there: what this checks is that the
# launcher came out of the zip still executable, and a file mode is a question about the
# machine that wrote the zip rather than about the machine reading it. Windows has no answer
# to give, so asking it would be a step that either fails for no reason or passes for none.
- name: Smoke test the distribution
if: runner.os != 'Windows'
run: ./scripts/smoke-distribution.sh

- name: Run tests
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -1207,7 +1207,7 @@ Seven Maven modules, and the arrows between them only point one way.
mynes-core/ depends on nothing
mynes/ the console: CPU, PPU, APU, BUS, MMU, VRAM, Cart, Region, Overclock,
controllers
mynes/mappers/ mappers 0 to 4
mynes/mappers/ the twelve boards: 0 to 4, 7, 9 to 11, 66, 71, and 155 on MMC1's own class
mynes/state/ save states, battery .sav files, and .mnm session recordings
mynes/debug/ the disassembler, the breakpoints and their conditions, the tracer, and
the meter that says how much of its frame the program used and which
Expand Down
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,7 @@ file is where they live.
- Toggles to hide the background or the sprite layer, and to take any of the five sound channels
out of the mixer (`--mute pulse1,dmc` headless).

Not there yet: a second player, and Dendy (run as PAL for now).
Not there yet: a gamepad, the Zapper, and Dendy (run as PAL for now).

## Screenshots

Expand Down Expand Up @@ -315,10 +315,10 @@ mvn -B package -DskipTests
java -jar mynes-desktop/target/mynes.jar
```

Four Maven modules — `mynes-core` (the console, no dependencies), `mynes-patch` (IPS),
`mynes-headless` (the command line) and `mynes-desktop` (the window) — flattened into one jar.
The same `mvn package` also produces the release zip. A fifth, `mynes-shots`, takes the pictures
above and is not in the jar.
Six Maven modules — `mynes-core` (the console, no dependencies), `mynes-patch` (IPS),
`mynes-archive` (zips), `mynes-midi` (MIDI files), `mynes-headless` (the command line) and
`mynes-desktop` (the window) — flattened into one jar. The same `mvn package` also produces the
release zip. A seventh, `mynes-shots`, takes the pictures above and is not in the jar.

## Tests

Expand Down
4 changes: 3 additions & 1 deletion mynes-core/src/main/java/com/github/dimiro1/mynes/CPU.java
Original file line number Diff line number Diff line change
Expand Up @@ -318,7 +318,9 @@ public void serialize(final StateIO io) {
* that a freshly constructed CPU starts with. After this call the next {@link #tick()}
* fetches an opcode from the supplied program counter.
* <p>
* This method is primarily for testing purposes.
* Nothing in a running console ever does this: a machine reaches a state by having run to it.
* It is here for the Tom Harte fixtures, which hand over a whole architectural state and one
* instruction and ask what comes back out.
*
* @param state the state to load.
*/
Expand Down
14 changes: 11 additions & 3 deletions mynes-core/src/main/java/com/github/dimiro1/mynes/Cart.java
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,18 @@
import java.security.NoSuchAlgorithmException;

/**
* Represents a NES game cartridge (ROM).
* A cartridge: the two ROMs on the board, the mapper wired to switch between them, and what the
* header said to build both from.
* <p>
* A Cart contains the program ROM (PRG-ROM), character ROM (CHR-ROM), and the
* memory mapper implementation that controls bank switching and special hardware features.
* <b>The header is kept beside the mapper rather than thrown away once it has been read</b>,
* because the two disagree in ways worth being able to see. {@link #ram()} is what the header
* <em>claimed</em> is fitted, where {@link Mapper#prgRAM()} is what the board actually got -- and
* they differ wherever a header said nothing and the mapper fell back to the 8KB every board here
* has. {@link #mapperNumber()} and the class of {@link #mapper()} part company the same way, since
* 1 and 155 build one class between them.
* <p>
* {@link #sha256()} is taken over the file as it arrived, header and any patch included, so it
* names what ran rather than what is on disk.
*
* @param filename the original filename of the ROM
* @param prgROM program ROM data (CPU-addressable)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,18 @@
import com.github.dimiro1.mynes.state.StateIO;

/**
* Represents a NES controller/joypad.
* A pad on one of the two ports: eight buttons, a shift register, and the strobe line that decides
* which of the two the register is following.
* <p>
* <b>Shaped like the hardware rather than like a set of button getters</b>, because that is what
* every awkward case here turns on. A game never asks which buttons are down. It raises the strobe
* to make the register follow them, drops it to make the register hold them, and then clocks the
* bits out one read at a time -- so "what is being held" and "what the game has been told" are two
* different questions, which is why {@link #getButtons()} and {@link #read()} are both here and
* answer differently for most of a frame.
* <p>
* Only the second of them is state the machine owns, and {@link #serialize} saves accordingly: the
* register and the strobe come back, and whose fingers were on what does not.
*/
public interface Controller {
/**
Expand Down
Original file line number Diff line number Diff line change
@@ -1,16 +1,13 @@
package com.github.dimiro1.mynes;

/**
* Exception thrown when attempting to load an invalid or malformed NES ROM file.
* A file that is not a cartridge at all.
* <p>
* This exception is thrown when a file fails to meet the iNES format specifications,
* such as:
* <ul>
* <li>Invalid magic number (file doesn't start with "NES\x1A")</li>
* <li>Missing or invalid PRG-ROM data</li>
* <li>Truncated file (insufficient data for declared banks)</li>
* <li>Corrupted header information</li>
* </ul>
* The sibling of {@link UnsupportedMapperException}, and the line between the two is worth keeping.
* This one means the bytes are not an iNES or NES 2.0 image -- the wrong four at the front, or a
* header promising more banks than the file has left to give. That one means the image parsed
* perfectly and named a board nobody has written. The first is somebody's file being wrong; the
* second is this emulator being unfinished, and only one of them is worth reporting.
*/
public class InvalidNesFileException extends RuntimeException {
/**
Expand Down
Original file line number Diff line number Diff line change
@@ -1,19 +1,75 @@
package com.github.dimiro1.mynes;

import java.util.Map;

/**
* Exception thrown when attempting to load a ROM that uses an unsupported mapper.
* A cartridge whose board nobody has written.
* <p>
* <b>The number is the least useful half of the answer.</b> A mapper number names a circuit rather
* than a chip -- what the cartridge does with the fifteen address lines and eight data lines the
* port gives it -- and there are hundreds of them where this runs twelve. Somebody told their file
* wants mapper 69 has to go and look up what 69 is before they know whether it is a famous board, a
* pirate multicart, or a header somebody filled in wrongly; told it wants Sunsoft FME-7, they
* already know.
* <p>
* The NES used various memory mappers (MMC chips) to extend the capabilities
* of the base hardware. This emulator may not support all mapper types.
* So the boards are named. Not all of them -- the tail is hundreds of bootleg conversions nobody
* loads on purpose -- but every one a real release shipped on, which is the set a collection can
* actually hand this. The names are the ones NESdev's list prints, because that is what somebody
* will search for next.
*
* @see <a href="https://www.nesdev.org/wiki/List_of_mappers">NESdev: list of mappers</a>
*/
public class UnsupportedMapperException extends RuntimeException {

/**
* What each unsupported board is called, for the numbers a real cartridge carries.
* <p>
* Only boards this does <em>not</em> run: the twelve it does never reach here, and an entry for
* one of them would be a second place to update when a thirteenth is written.
*/
private static final Map<Integer, String> BOARDS = Map.ofEntries(
Map.entry(5, "MMC5"),
Map.entry(16, "the Bandai FCG board"),
Map.entry(18, "Jaleco SS8806"),
Map.entry(19, "Namco 163"),
Map.entry(20, "the Famicom Disk System"),
Map.entry(21, "Konami VRC4a or VRC4c"),
Map.entry(22, "Konami VRC2a"),
Map.entry(23, "Konami VRC2b or VRC4e"),
Map.entry(24, "Konami VRC6a"),
Map.entry(25, "Konami VRC4b or VRC4d"),
Map.entry(26, "Konami VRC6b"),
Map.entry(34, "BNROM or NINA-001"),
Map.entry(64, "Tengen RAMBO-1"),
Map.entry(68, "Sunsoft-4"),
Map.entry(69, "Sunsoft FME-7 or 5B"),
Map.entry(73, "Konami VRC3"),
Map.entry(75, "Konami VRC1"),
Map.entry(76, "Namco 109"),
Map.entry(85, "Konami VRC7"),
Map.entry(118, "TxSROM, an MMC3 variant"),
Map.entry(119, "TQROM, an MMC3 variant"),
Map.entry(180, "UNROM wired the way Crazy Climber has it"),
Map.entry(185, "CNROM with protection diodes"),
Map.entry(206, "DxROM, or Namco 118"),
Map.entry(210, "Namco 175 or 340"),
Map.entry(232, "the Camerica Quattro board"));

/**
* Creates a new exception for an unsupported mapper.
*
* @param mapperNumber the mapper number that is not supported
* @param filename the ROM file that uses this mapper
* @param mapperNumber the mapper number the header asked for
* @param filename the ROM that asked for it, which is what somebody has to go and look at
*/
public UnsupportedMapperException(final int mapperNumber, final String filename) {
super("Mapper " + mapperNumber + " is not supported in file: " + filename);
super(message(mapperNumber, filename));
}

private static String message(final int mapperNumber, final String filename) {
var board = BOARDS.get(mapperNumber);

return filename + " wants mapper " + mapperNumber
+ (board == null ? "" : ", " + board)
+ ", which this does not run.";
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -60,20 +60,43 @@ void loadInvalid() throws IOException {
}

/**
* The mapper number is split across the high nibbles of flags 6 and 7. Reading it wrongly is
* silent: an unsupported cart loads as mapper 0 and then misbehaves at run time instead of
* being rejected here.
* A board nobody has written is refused here rather than run wrongly, which is the whole of why
* this is an exception and not a warning: reading the mapper number wrongly is otherwise silent,
* and an unsupported cart that loaded as mapper 0 would misbehave at run time instead.
* <p>
* The number alone means nothing to somebody holding a cartridge, so a board this knows the name
* of is named. Both halves are asserted: a message that dropped the file would leave somebody
* with a collection open guessing which of it failed.
*/
@Test
void loadUnsupportedMapper() {
var rom = synthesizeRom(0x50, 0x00); // mapper 5, MMC5
void theRefusalNamesTheBoardWhenItKnowsWhatOneIsCalled() {
var rom = synthesizeRom(0x50, 0x00); // mapper 5

var thrown = assertThrowsExactly(
UnsupportedMapperException.class,
() -> Cart.load(rom, "mapper5.nes")
);
UnsupportedMapperException.class, () -> Cart.load(rom, "mapper5.nes"));

assertTrue(thrown.getMessage().contains("MMC5"), thrown.getMessage());
assertTrue(thrown.getMessage().contains("mapper5.nes"), thrown.getMessage());
}

assertTrue(thrown.getMessage().contains("5"), "should name the mapper: " + thrown.getMessage());
/**
* The table stops at the boards a real release shipped on, so most numbers are not in it. That
* is the common case rather than the edge one -- the refusal still has to read as a sentence,
* with no gap where the name would have gone.
*/
@Test
void theRefusalReadsAsASentenceForABoardNobodyHasNamed() {
var rom = synthesizeRom(0xE0, 0xC0); // mapper 206, which is named
var named = assertThrowsExactly(
UnsupportedMapperException.class, () -> Cart.load(rom, "known.nes"));

var unknown = synthesizeRom(0x80, 0xD0); // mapper 216, which is not
var bare = assertThrowsExactly(
UnsupportedMapperException.class, () -> Cart.load(unknown, "unknown.nes"));

assertEquals("known.nes wants mapper 206, DxROM, or Namco 118, which this does not run.",
named.getMessage());
assertEquals("unknown.nes wants mapper 216, which this does not run.", bare.getMessage());
}

@ParameterizedTest(name = "mapper ${0} loads as ${1}")
Expand Down
Loading