rather than raise Exception("Invalid write to address %04X" % addr) we should use a specific exception like raise InvalidWriteAddress(addr)

• [x] c++
• [x] python
• [x] rust
• [x] go
• [x] php

For languages which support inheritance, I'd do something like:

• Exception
  • ControlledExit - emulation should stop for some reason (exit 0, except for UnitTestFailed, which should exit 2)
    • Quit - the user hit the X button on the window
    • Timeout - we reached as far as we wanted to reach with the --profile flag
    • UnitTestPassed - Opcode 0xFC was executed
    • UnitTestFailed - Opcode 0xFD was executed
  • GameException - bugs in the game itself (exit 3)
    • InvalidOpcode
    • InvalidRomBank
    • InvalidRomRead
    • InvalidRomWrite
    • InvalidRamBank
    • InvalidRamRead
    • InvalidRamWrite
  • UserException - the user gave us some sort of invalid input (exit 4)
    • RomMissing - the .gb file specified on the command line doesn't exit
    • HeaderChecksumFailed - the .gb file specified has an invalid checksum
    • LogoChecksumFailed - the .gb file specified has an invalid checksum

Implements #57.

This enables two usage modes:

1. If you run nix-shell in any of the implementation subdirectories, you get a shell with correct versions of everything needed to build and run for that language.
2. If you run nix-shell in the root directory, you get a shell with everything needed for all implementations.

I tested it on a clean Debian 11 Bullseye Stable container with Nix 2.3.7, and also on an Arch-based rolling distro with Nix 2.11.1. The format and build scripts work for all languages (though the Zig output doesn't run on Debian Stable, due to an unrelated(?) issue of GLIBC being too old).

Since most of the languages are actually fairly mature and stable on their own, I only pinned Zig to a specific language interpreter/compiler version. Everything else just uses the latest versions from the users' <nixpkgs> channel, though with a major version qualifier if relevant (E.G. python310, php81). It is trivial to pin everything by changing the import argument to a specific commit in the NixPkgs repository, though, if that becomes a problem, but doing so might mean giving up the binary cache and requiring the user to build everything from source.

Compare with @rrbutani's approach: https://github.com/shish/rosettaboy/issues/57#issuecomment-1332564900

The above (@rrbutani's WIP) uses Nix Flakes. As I understand it, flakes are the more advanced and more reproducible, technically still-experimental way to specify code dependencies. I think the flake above not only fetches dependencies but also builds each implementation? My goal was only to define shells that allow the existing run.sh and format.sh scripts to be used.

Personally I'm not convinced that the complexity, schema, whatever of Flakes is worth it compared to ad-hoc derivations and shells unless you're targeting a completely Nix-based platform. I'm still quite new to Nix though, and I'm sure @rrbutani can comment more on the merits of each approach.

Things I did not do:

• Github Workflow to test the Nix environments. I personally found the GH Workflow API annoying the last time I interacted with it. Plus, I can't test this locally. Should be easy, though— Can just do nix-shell --pure --run './utils/bench.py --default --frames 10 --threads 4' (or whatever the test script is).

I got the below error trying to run the Zig version:

./build.zig:22:8: error: no member named 'addLibraryPath' in struct 'std.build.LibExeObjStep'
    exe.addLibraryPath("/Users/shish2k/homebrew/lib/");
       ^
./lib/sdl/Sdk.zig:139:63: error: expected type 'std.mem.Allocator', found 'std.zig.CrossTarget'
    const target = (std.zig.system.NativeTargetInfo.detect(exe.target) catch @panic("failed to detect native target info!")).target;
                                                              ^
/usr/lib/zig/std/mem/Allocator.zig:1:1: note: std.mem.Allocator declared here
//! The standard memory allocation interface.
^
/usr/lib/zig/std/zig/CrossTarget.zig:1:1: note: std.zig.CrossTarget declared here
//! Contains all the same data as `Target`, additionally introducing the concept of "the native target".
^
./lib/sdl/Sdk.zig:86:9: error: no member named 'source' in struct 'std.build.Pkg'
        .source = .{ .path = sdkPath("/src/wrapper/sdl.zig") },
        ^

Rather than endlessly trying to keep track of libraries, version incompatibilities, etc., I think Nix can be used to declaratively define reproducible, self-contained development environments as needed.

For example, I have the below shell.nix file for the Python version:

{ pkgs ? import <nixpkgs> {} } : pkgs.mkShell {
	buildInputs = with pkgs; [
		(python310.withPackages (pypkgs: with pypkgs; [
			pysdl2
			setuptools
			
			mypy
			black
		])).out
	];
}

(To read this if you haven't looked into Nix before: The language is functional. Colons are function definitions, with signature to the left and the return expression to the right. Calls are names followed by a space and then argument. With makes names from a mapping available in the subsequent scope. Lists are whitespace-separated, and curly braces are mappings. — The root expression is a function that takes the argument pkgs (or actually uses the default value import <nixpkgs> {}) and returns an environment, and the argument passed to .withPackages is a function that takes the argument pypkgs and returns a list of Python packages.)

And then, anyone on any distro of Linux or MacOS can just run $ nix-shell in the terminal to get the exact right development environment. The packages are stored entirely self-contained in /nix, and symlinked in ~/.nix-profile or added to $PATH as requested.

For perfect reproducibility, the packages used can be pinned to a specific version by downloading from a specific commit in the nixpkgs respository. So this way, if you specify a version of a library or language that works on your machine, anyone else running it will get the exact same version.

{ pkgs ? import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/facfd565093c8f410be840dc427975a6d7368f91.tar.gz") {} } : pkgs.mkShell {
	buildInputs = […];
}

More info:

https://nixos.org/guides/declarative-and-reproducible-developer-environments.html

I'm not trying to evangelize. I bring this up as somebody who is reluctant to modify my global computing environment for a local requirement— I.E. I'm not going to change my system Zig, set up venvs everywhere, or install new pip packages just to run this, so I was just thinking it'd be useful if a declarative ad-hoc environment were provided.

I do see there's already something similar with Docker/Podman, which I guess fills the same purpose. But that seems heavier (pulling in a whole Debian, looks like?), and involves more permissions and system configuration to set up. — FWIW, Nix can also be used to generate Docker images, and it looks like there's a Nix image on Docker (though I haven't tried either).

Anyway, it's just an idea.

Running on my machine using daa54a6de67c6c7f21125372afb52c311ddd8954: Emulated 600 frames in 0.53s (1136fps)

WIth this change: Emulated 600 frames in 0.38s (1568fps)

1. --mm:arc
2. "The benefit of --panics:on is that it produces smaller binary code and the compiler has more freedom to optimize the code."

[email protected]:~/Projects/rosettaboy$ ./utils/shell.sh
[email protected]:/home/dev$ ./utils/bench.py 
  cpp / release: 
   go / release: Emulated 600 frames in  2.07s (290fps)
  nim / release: Emulated 600 frames in  0.30s (1969fps)
  php / release: Emulated 600 frames in 11.16s (54fps)
   py / release: Emulated 600 frames in 60.24s (10fps)
   py / mypyc  : Emulated 600 frames in 56.73s (11fps)
   rs / release: Emulated 600 frames in  0.26s (2302fps)
   rs / pgo    : 
  zig / release: 

cpp crashes

rust pgo is probably missing something

zig compiler isn't installed

Since mypyc compiles modules, it probably needs to be run on all src/*.py files. Doing only mypyc main.py probably only compiles the entrypoint.

E.G.:

• If you delete one of the files like src/cpu.py, mypyc still compiles successfully but ModuleNotFoundErrors at run time. This presumably shows it's still trying to import the slow, uncompiled cpu.py.
• Looks like you can open build/__native.c to read the generated code. It's not pretty, but it doesn't look like it's doing anything more than importing the uncompiled modules, running them, and exiting.
• Docs show separately specifying all modules that you want to compile.

No idea if it will even work if you try to compile everything— E.G. To get it running in Cython, I had to separate all the exec()-generated code in cpu.py out into actual code instead (....Which I see has been removed and made obsolete literally the day after I did that.... Gosh dangit!)— ~~If that's needed for MyPy too, I can post that as a starting point.~~

Hi, I just saw your comment on top of ycombinator (congrats!), checking out this repo I notice that in all github workflow we are using sdl2 lib binding, but in php github workflow I didn't see it being use (It is still actively maintained at https://github.com/Ponup/php-sdl).

That may yield why php is roughly the same speed with python (it is faster in my experience).

I've never use SDL2 for php so I don't yet know how, creating this issue for tracking (as I might try SDL with php on weekend).

Rather than

u8 IE = this->ram->get(Mem::IE);

it would be nice to treat RAM as if it was an array, like:

u8 IE = this->ram[Mem::IE];

• [x] Python
• [ ] C++
• [ ] Rust - https://doc.rust-lang.org/core/ops/trait.Index.html & https://doc.rust-lang.org/core/ops/trait.IndexMut.html

(Do Go or PHP support this?)

Right now most implementations use the Surface API (software rendering), except for rust which uses the Renderer API (hardware accelerated, except in our case that just means "additional overhead on every setpixel() call") - the docs say that for our use case (we are setting every pixel individually) the Texture API is best

https://wiki.libsdl.org/MigrationGuide#if_your_game_just_wants_to_get_fully_rendered_frames_to_the_screen

This adds a Cythonized pxd copy of the py implementation.

The pxd implementation shoots Pythonic performance up past PHP to a bit below Go, but not quite yet to the level of any of the other native-targeting languages.

I aimed for a mostly naïve use of Cython. Basically, all logic is exactly the same as the Python version, but type annotations and definitions are added to compile all costly code to C.

Looking at the annotated HTML output produced during a build, essentially all of the emulation logic now runs as native. Only some of the __init__s, the errors, and debug stuff still do a lot of stuff in Python-space, which I didn't bother with as I assume they're usually run only a couple times at most in the lifetime of the emulator. SDL2 is also linked directly from the generated C code (based on the project sdl2_cython on PyPI), rather than used through pysdl2— This was surprisingly painless to drop in, and only required a couple minor changes for some struct types and decisions in Python-space on how to handle arrays.

The individual commit messages say how much of a speedup each change brought on my machine.

The Python sources still run fine in CPython as well. I don't know if it might be possible to unify this with the py implementation so there's only one code set to maintain that works with CPython, MyPyC, and also Cython. This implementation is logically basically identical, but Cython uses some special types that may or may not play nice with MyPy, and doesn't support match yet (although apparently match is nearly identical to elif chains in CPython bytecode anyway).

I haven't tested this with Python 3.11.

Cython also has a number of options that may affect the output. Most notably, Cython can output C++ instead of C, which enables access to a handful of extra features. This PR does not include variations for any of those options, although I don't suppose compiling largely the same code as C++ instead of C would really make much of a difference.

When reviewing: It would make sense to ignore the first commit, as it's just a copy of py, as well as the SDL2 header wrapper that adds a lot of lines.

It's not immediately clear to me exactly why this is still significantly slower than the other native binaries. For example, profiling points to RAM.get() being the largest single cost, but comparing that code with other implementations side-by-side, they look essentially identical. I originally thought Pythonic code might leave a lot of superfluous allocations around, but that doesn't really look like the case either. Cython seems to be using gcc -O3, so that should be fine too, unless the generated code is somehow much harder to optimize. Is the overall call graph significantly different?

IIRC I was thrown off a bit by this.

palette in GPU.paint_tile() and GPU.paint_tile_line() is typed to SDL_Color.

https://github.com/shish/rosettaboy/blob/177f282c7b0e10eb5df0e0597d966a7ccc8e9ab9/py/src/gpu.py#L365-L372

https://github.com/shish/rosettaboy/blob/177f282c7b0e10eb5df0e0597d966a7ccc8e9ab9/py/src/gpu.py#L388-L396

However, in all invocations, it's set to something like self.bgp, self.obp1, or self.obp0, which are actually List[SDL_Color]:

https://github.com/shish/rosettaboy/blob/177f282c7b0e10eb5df0e0597d966a7ccc8e9ab9/py/src/gpu.py#L325

https://github.com/shish/rosettaboy/blob/177f282c7b0e10eb5df0e0597d966a7ccc8e9ab9/py/src/gpu.py#L344-L353

https://github.com/shish/rosettaboy/blob/177f282c7b0e10eb5df0e0597d966a7ccc8e9ab9/py/src/gpu.py#L205-L228

In soft real-time and interactive uses, performance consistency is arguably more important than mean performance.

60FPS with constant frame times is way better than 200FPS with a lag spike every couple hundred frames. Apparently, even some quite large games and GUI applications can have quite bad issues with the entire process freezing every couple seconds when the garbage collector kicks in.

Complication: Nim has multiple memory management strategies that can be used. I don't know if some of the other languages might too. I suppose these would probably be best exposed as run_arc.sh, run_boehm.sh, etc., similar to how there's already run_speed.sh, run_mypyc.sh, run_lto.sh, etc.

Obviously results from this should be taken with a grain of salt the size of a boulder, as small implementation details could completely change them. But still, I could see it as an at-a-glance useful way to judge what you're likely going to be able to get out of each language if you jump in without taking special measures, for which I have not yet seen any previously existing empirical data or comparison.

Possible components:

• Output format? Maybe just dump a JSON array of frame times to disk without any additional processing.
• Option to sample only after a warm-up period? So skip startup, and give JITs time to get going. Hm; I guess if it's implemented as something like --frametimes 1000 meaning "Keep only the last 1,000 frame times," then we can also avoid having to ever reallocate for the internal frame time array. (And then you could do, E.G. --frametimes 1000 --frames 1200 to get 1000 frame times after 200 warm-up frames.)
• ./utils/frametimes.py <LANG>/frametimes.json to bin the times and show a MatPlotLib histogram?
• Would it be worth it to make bench.py report on deviations/quantiles when available too?

I considered PR'ing this directly or trying to start it myself, but I suppose there's enough different ways it could be done and reasons to do or not do it, and I'm not proficient enough, that it should probably be discussed more thoroughly.

An experiment for making it easier to see if changes are helping or hindering

exposes the code as a library, with args and gameboy marked as public

run with cargo bench