hhy5277 / gameboy.live

🕹️ A basic gameboy emulator with terminal "Cloud Gaming" support

Gameboy.Live

🕹️ Gameboy.Live is a Gameboy emulator written in go for learning purpose. You can simply play Gameboy games on your desktop:

Or, play "Cloud gaming" in your terminal with one single command:

telnet gameboy.live 1989

Installation

You can directly download executable file from Release page, or build from the source:

git clone https://github.com/HFO4/gameboy.live.git
cd gameboy.live
go build -o gbdotlive main.go

Usage

Usage of gbdotlive:
  -c config
        Set the game option list config file path
  -d    Use Debugger in GUI mode
  -f FPS
        Set the FPS in GUI mode (default 60)
  -g    Play specific game in GUI mode (default true)
  -h    This help
  -m    Turn on sound in GUI mode (default true)
  -p port
        Set the port for the cloud-gaming server (default 1989)
  -r ROM
        Set ROM file path to be played in GUI mode
  -s    Start a cloud-gaming server

GUI mode

Play specified ROM file in GUI mode:

gbdotlive -r "Tetris.gb" 

Set up a cloud gaming server

You can use Gameboy.Live as a "cloud gaming" server, where players use telnet to play Gameboy games in terminal without additional software installation required. (Except telnet itself XD)

First of all, a gamelist.json config file is required to specify game options, this is a typical example:

[{
	"Title": "Tetris",
	"Path": "test.gb"
}, {
	"Title": "Dr. Mario",
	"Path": "Dr. Mario (JU) (V1.1).gb"
}, {
	"Title": "Legend of Zelda - Link's Awakening",
	"Path": "Legend of Zelda, The - Link's Awakening (U) (V1.2) [!].gb"
}]

It is recommended to test every ROMs before put them in the config file.

Next, start Gameboy.Live server with config file from the previous step:

gbdotlive -s -c "gamelist.json"

You will see an output like this, which means your server has started successfuly:

2019/04/30 21:27:56 Listen port: 1989 

Now, you can play games anywhere you want. The simulation and rendering process is done entirely on the server.

telnet <ip of your server>:<port>

To be careful of, this "cloud gaming" is only playable in terminals support ANSI standard and UTF-8 charset. You can use WSL instead of CMD on Windows.

Debug

Gameboy.Live has a simple build-in debugger which can be used to debug games or emulatoe itself. To turn on debug mode, set the d flag to true:

gbdotlive -r "test.gb" -d=true

The emulator will firstly break at 0x0100 in debug mode, which is the entry point of the game program. You can type the adress of next breakpoint, emulator will continue to run to the next breakpoint. At each breakpoint, emulator will print registers' status like above, and dump the main memory into memory.dump (ROM and RAM bank is not included)

[OP:NOP]
AF:01B0  BC:0013  DE:00D8  HL:014D  SP:FFFE   
PC:0100  LCDC:91  IF:E1    IE:00    IME:false 
LCD:100 

Keyboard instruction

Keyboard	Gameboy
Enter	Start
Backspace	Select
↑	Up
↓	Down
←	Left
→	Right
X	B
Z	A

Features & TODOs

• CPU instruction emulation
• Timer and interrupt
• Support for ROM-only、MBC1、MBC2、MBC3 cartridge
• Sound emulation
• Graphics emulation
• Cloud gaming
• ROM debugger

There are still many places to be perfected：

• Support Gameboy Color emulation
• Support for MBC4、MBC5、HuC1 cartridge
• Sound simulation is incomplete, still got differences compared to the Gameboy real machine
• Sprite priority issue (see Wario Land II and Metroid II: Return of Samus)
• Failed to pass Blargg's instruction timing test
• Game saving & restore in cartridge level
• Game saving & restore in emulator level

Testing

Contribution

This emulator is just for learning and entertainment purpose. There are still many places to be perfected. Any suggestions or contribution is welcomed!

Reference

• Pan Docs
• http://www.codeslinger.co.uk/pages/projects/gameboy/beginning.html
• http://www.devrs.com/gb/files/GBCPU_Instr.html
• https://github.com/Humpheh/goboy
• The Ultimate Game Boy Talk (33c3)
• http://gameboy.mongenel.com/dmg/asmmemmap.html
• ......