GameBoy CPU Manual (2013) [pdf] | Hacker News Reader

GameBoy CPU Manual (2013) [pdf]

realboyemulator.files.wordpress.com

261 pointspplonski8641 comments

If you're interested in making a GB emulator here are a few resources that helped me when I did just that a few years ago:

- An intro to making a GB emulator in JS (it doesn't matter if you don't plan on using JS, it still explains the basic concepts pretty well): http://imrannazar.com/GameBoy-Emulation-in-JavaScript:-The-C...

- Opcode map (note that the GB CPU is not a stock Z80, it has different timings, different registers, different flags and different opcodes, do not use stock Z80 docs as a reference lest you end up with broken CPU emulation): http://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html

- The GameBoy programming manual: http://www.romhacking.net/documents/544/

- Accuracy test ROMs, very useful to make sure your timings are ok and you emulate various quirks of the hardware: http://tasvideos.org/EmulatorResources/GBAccuracyTests.html

Also note that even if you focus on making an original (DMG) GameBoy emulator you should be able to add GameBoy Color support later without too much difficulty, it's a fairly straightforward evolution of the original hardware.

Dumb question: is there a reason to make a gameboy emulator besides interest? Is it not a completely solved problem space, with all games playable with optimal performance?

It's fun, if you're into that kind of thing.

It's more like building a car in the garage. There's no real need to do, but some people enjoy the process of figuring out how everything fits together.

The microcorruption challenge is one of the best ways to learn about exploitation because it uses a simple CPU and easy to understand memory model. Implementing a z80-alike is like hello world if you are interested in learning lower level programming. Both of these examples share this: the obscuring parts of modern architecture are gone. And, personally, it is very rewarding to write your own emulator. It really sharpens skills for systems stuff.

It's like writing a raytracer or ray-casting engine, it's not particularly useful but it's pretty fun and it can learn quite a lot while doing it.

In the case of emulators I suspect that many developers nowadays never went underneath the syscall layer (or even beyond the interpreter) so if they're interested to learn about how it all works deep down it can be a good challenge. Of course the GameBoy is archaic in most ways but it's a start.

It’s relatively simple to do, and yet you learn a great deal. The Game Boy’s simplicity means that you have quick feedback, making it fun. Tetris, for example, works pretty early on.

Emulators of other platforms tend to need tons and tons of work to even get to booting.

I've been meaning to rewrite an existing JavaScript GB emulator so it uses JS modules (and is in general much cleaner than before)... Haven't started the work yet, though.

Correct, the CPU is not a Z80 at all. It has more in common with the 8080 but does have a few Z80 enhancements and a few original instructions.

Every time someone resurfaces the Pan Docs in a new form, I'm reminded of how I haven't touched my Gameboy dev efforts[0] in months. As fun as it is to conquer the Z80, it's difficult to get motivated working in an ecosystem that is still almost utterly without development tools.

Kirby's Dreamland was programmed with a track ball running on a hacked up Famicom. [1] We haven't come too far since then.

[0] https://github.com/Eiriksmal/gameboy

[1] https://arstechnica.com/gaming/2017/04/the-first-kirby-game-...

There a few good homebrew tools and libraries available. We did a gameboy game for a Ludum dare a short while back, and while it's certainly not pretty z80, the tooling got the job done. (Be gentle, it was my first time trying to do anything serious directly in assembly and we had a 72-hour time limit.)

https://github.com/zeta0134/ludum-dare-42

We used the RGBDS assembler and its built in tools to make the thing, mostly because that runs on Linux and that's what we both wanted to develop on. My partner did the graphics and I got a decent flow going from LibreSprite using RGBGFX for the conversions.

https://github.com/rednex/rgbds

I'll admit that I did have a major advantage going in, having written a mostly functional gameboy emulator already, but emulating a system is very, very different from programming against its constraints. There are decent software libraries floating around, but since there's no real standard way to leverage the hardware once you get past the basics (even commercial games had wildly varying strategies from company to company) the best tool in the belt is probably your documentation. Pan docs and the various wikis were instrumental in understanding how to leverage the hardware to do what we wanted.

I’ve been working on a little adventure game maker for GameBoy over the last few months actually. I’ve been sharing a few alpha builds on a mailing list and pretty close to releasing now. Was hoping to post a Show HN soon!

https://www.gbstudio.dev

I still cannot find a good Paint alternative for macOS but soon it will have a gameboy game maker :-)

Really excited about it. Good luck!

I really like Pixen

Have you tried Paintbrush? It is basically a modern mix between MacPaint and MS Paint (the good one, not the abomination introduced in Windows 7).

https://paintbrush.sourceforge.io/

Me too and I’ve tried dozens of ‘em.

Used Acorn for a while now use Paintbrush.

But they are all still too complex and don’t get the feel right.

Paint in WINE!

I actually wrote a Asteroids "Clone" that uses Vector Graphics last year :) [0]

But I agree, tooling is complicated. I'm currently adding the finishing touches to the rewrite of my own Assembler / Compiler pipeline [1] and started work on a more "traditional" Metroid-like shooter, the sprite and map editor are both custom programs written in rust using imgui bindings and take care of the grunt work for generating all the data structures used in the game currently the dev efforts are 50/50 tooling/game though :D

[0] https://gitlab.com/BonsaiDen/vectroid.gb [1] https://gitlab.com/BonsaiDen/gbasm-rs

Utterly without? https://github.com/gbdev/awesome-gbdev

Have you tried the SDCC C compiler? I use it for 8bitworkshop. It has a Gameboy CPU target.

I've tried the SDCC C compiler and I did have to fix a lot of code generation bugs, thank goodness it had source. It was a few years ago now so maybe it's been fixed. I didn't contribute my fixes at the time because I didn't know about how to do that. Today would be different.

The Sharp LR359021 CPU is what you're conquering which is an 8080 CPU with a few throw-ins from the Z80. There are enough tools to write a GB game but perhaps there aren't enough good samples or a library (mini engine).

But in general I agree that the biggest problem with making retro games is getting a comfortable dev environment that just works. I think this is the motivation behind some of the 'simple' NES development environments that have been coming out.

I feel like a really good IDE / debugger and well documented library for the Gameboy + samples would go a long way.

I really like the Gameboy hardware; it's limited, but the design feels very elegant in it's simplicity.

I've written a couple of toy Gameboy emulators at this point. It's a bit challenging to get anything working, and honestly I have no idea how to approach audio at all. Nevertheless, it's still quite fun. The LCD timings are a point of curiosity for me. It seems there's still a slight bit of mystery around it, still today.

I was inspired to play with emulating Gameboy specifically after an excellent 33c3 talk, The Ultimate Game Boy Talk, which I highly recommend.

https://youtu.be/HyzD8pNlpwI

(Some day I would like to approach emulation for more platforms, both newer and older, but I feel I still have so much time learn about designing emulators that I haven't bothered with that yet. It's so open ended, and handling things like cycle counting has a lot of different approaches of varying desirability.)

You might really enjoy this talk as well, then: https://youtu.be/GBYwjch6oEE

Oh thank you, I've never seen this talk nor heard of this conference but on it's face it sounds like it's right up my alley.

I was gonna say this depth of exposure would have a major impact in performance for all the GB emulators our there. Then I realized they probably don't need any more performance impact because they're GB emulators.

Is this document brand new?

It's been circulating in various forms since the late 90s, IIRC. Commonly referred to as the "Pan Docs."

http://gbdev.gg8.se/wiki/articles/Pan_Docs

This doc isn't new, but beyond that getting more details about the original hardware tends to make emulators slower, not faster, since they end up having to emulate more subtle details and quirks of the original.

Making an emulator run fast generally involves finding an efficient software architecture to emulate a piece of hardware (a non-trivial task since hardware is massively parallel and synchronous) and if you still can't get it to run fast enough you start cutting corners on accuracy until you do.

I have recently finished a GameBoy DMG/CGB emulator with friends from school https://github.com/nbouchin/gbmu

It was a lot of fun!

How do you use it

If you're a web developer or someone working pretty high level and have this desire to explore the depths, here's a project idea for you. First write a CHIP8 emulator in your most comfortable language, then write a Gameboy emulator in something like Rust or C++.

I would love to, but have - genuinely - no idea where to begin beyond tearing down someone else's work on Github.

Can you recommend any starting paths for someone like you mentioned?

CHIP8 is a game-oriented bytecode from the 1970s, with just a few instructions: http://mattmik.com/files/chip8/mastering/chip8.html

There's a good IDE for it with a bunch more resources: https://github.com/JohnEarnest/Octo

For the CHIP-8 emulator in particular, this is a good starting point:

http://www.multigesture.net/articles/how-to-write-an-emulato...

Or you could just read the documentation directly here:

http://devernay.free.fr/hacks/chip8/C8TECH10.HTM

CHIP8 was itself an interpreted bit of hardware, so it's reeeeally loose with things like timing requirements. Just run a couple dozen instructions per "frame" in your game loop, then draw the screen somewhere, and you'll come close to playability for most of the sample games if your interpreter is bug free. It's the kind of project that with enough motivation you could complete in a week or so, which is why it's usually recommended for a first emulator project.

Once you have CHIP8 working somewhat, think about how you had to structure your code to make that work. Wouldn't the z80 CPU in a gameboy, or the 6502 CPU in an NES, also have opcodes just like the CHIP8 interpreter did? Surely you wrote a function for each CHIP8 opcode, so why not write a function for each z80 opcode, figure out how to read the gameboy's cartridge header, and see if your new CPU can run some instructions from Tetris? Once you get the code writing to VRAM, can you draw the tiles? What about the background? Build the emulator up piece by piece, and suddenly your game library is just chok full of little puzzle boxes, waiting to be tackled one by one.

It's very difficult to do all of this accurately, but don't focus on that right away. Just get it working, and learn about the system as you go.

It's really pervasive that the CPU in the Gameboy is a Z80. It's not. It's got a few instructions from the Z80 but it's closer to the 8080 overall.

I've been working on a GB emulator for awhile.

Step one is to understand the architecture of the system. What are the different hardware components? How do they interact?

A simple emulator boils down to:

While(true) Emulate_one_cpu_cycle()

For each cycle you have to produce any side effects from the various peripherals (serial comms, update the display, generate audio, etc.), process any external changes (button presses, serial data), and emulate the next CPU instruction (basically a big switch).

I recommend "The Ultimate Gameboy Talk (33c3)" [0], for an overview of the Gameboy and it's internal peripherals.

There are various test ROMs available that you can use to verify the basic functionality. [1][2]

0. https://m.youtube.com/watch?v=HyzD8pNlpwI 1. http://gbdev.gg8.se/wiki/articles/Test_ROMs 2. https://github.com/Gekkio/mooneye-gb

GB never dies ;) And Nintendo hardware remains a great way to explore computation internals:

CPSC 305: Computer Systems and Architecture

http://ianfinlayson.net/class/cpsc305/

Using The Game Boy Advance To Teach Computer Systems And Architecture

https://www.researchgate.net/publication/323199083_Using_The...

This was my professor! It was honestly a cool class. Half of it was learning CPU design from the bottom up, and the other half was programming for the GBA.

One thing I would like to see in a gameboy emulator is the option to record / input from file keypresses so that you can test speedruns or find exploits.

I was thinking this would be trivial for something like a js emulator where you usually have a key array defined for storing keypresses.

If anyone knows of a GB emulator that already allows this please link to my comment.

Is it a fan-made document or extracted from the vendor (Nintendo)? If it's the former, it is surprising to see how they ended up with writing a chip reference manual-grade document.

Definitely fan-made. The formatting feels off, probably because it was originally a text file that was converted into a PDF. Thus you see section headings with proportional font, but body text in monospace with ASCII art diagrams and tables.

Beware, contains errors.

(been writing a gameboy simulator for a few months now...)

Maybe consider pointing out those errors

Reply on news.ycombinator.com