PHP Gameboy Emulator: Emulate Gameboy console in a terminal in pure PHP

Recommend this page to a friend!

Download

Info

Example

Screenshots

Files

Install with Composer

Download

Reputation

Support forum

Blog

Links

Ratings				Unique User Downloads		Download Rankings
66%				Total: 383		All time: 6,710 This week: 49

Version		License		PHP version		Categories
`php-terminal-gameboy` 1.0.4		MIT/X Consortium ...		5.6		PHP 5, Emulators, Games, Console

Collaborate with this project

Author

Gabriel Couto

php-terminal-gameboy-emulator - github.com

Description

This package can emulate Gameboy console in a terminal in pure PHP.

It can run a Gameboy virtual machine by emulating its hardware and executing games Z80 CPU assembly code with PHP code.

The Gameboy screen is outputted to the terminal console using braille characters. Keyboard inputs are mapped to Gameboy key controls.

Innovation Award

March 2016
Winner

Prize: One big elePHPant Plush Mascott

Gameboy is a popular 8 bit console created in the 1980 decade.

This package can emulate a Gameboy in pure PHP code. It outputs the Gameboy screen to your console terminal using Braille characters.

Manuel Lemos

Gabriel Couto

Performance

Level

Level 1

Innovation award

Nominee: 1x

Winner: 1x

Example


<?php





foreach (['../../autoload.php', '../vendor/autoload.php', 'vendor/autoload.php'] as $autoload) {

    $autoload = __DIR__.'/'.$autoload;

    if (file_exists($autoload)) {

        require $autoload;

        break;

    }

}

unset($autoload);



use GameBoy\Canvas\TerminalCanvas;

use GameBoy\Core;

use GameBoy\Keyboard;



if (PHP_VERSION_ID >= 70000) {

    set_exception_handler(function (\Throwable $exception) {

        fwrite(STDERR, $exception->getMessage() . PHP_EOL);

        exit(254);

    });

} else {

    set_exception_handler(function (Exception $exception) {

        fwrite(STDERR, $exception->getMessage() . PHP_EOL);

        exit(254);

    });

}



if (count($argv) < 2) {

    throw new \RuntimeException('You need to pass the ROM file name (Ex: drmario.rom)');

}



$filename = $argv[1];



if (!file_exists($filename)) {

    throw new \RuntimeException(sprintf('"%s" does not exist', $filename));

}



if (extension_loaded('xdebug')) {

    fwrite(STDERR, 'Running php-gameboy with Xdebug enabled reduces its speed considerably.'.PHP_EOL);

    fwrite(STDERR, 'You should consider to disable it before execute php-gameboy.'.PHP_EOL);

    sleep(1);

}



$rom = file_get_contents($filename);



$canvas = new TerminalCanvas();

$core = new Core($rom, $canvas);

$keyboard = new Keyboard($core);



$core->start();



if (($core->stopEmulator & 2) == 0) {

    throw new \RuntimeException('The GameBoy core is already running.');

}



if ($core->stopEmulator & 2 != 2) {

    throw new \RuntimeException('GameBoy core cannot run while it has not been initialized.');

}



$core->stopEmulator &= 1;

$core->lastIteration = (int) (microtime(true) * 1000);



while (true) {

    $core->run();

    $keyboard->check();

}

Details

Want to play Dr Mario or Pokémon on your server terminal? That's for you!

Why
Requirements
Running
Controls
Tests
TO-DO
Credits
Legal

Why

Some people will ask me: _"Why you did that?"_

Well, a friend asked me _"What PHP can do?"_. I thought about that awhile and the idea came up. With PHP7's performance improvement now it's possible to emulate some systems :smile: and, come on, that's funny! :dancers:

It's based on the GameBoy JS Emulator.

Requirements

The following PHP versions are supported:

PHP 5.6
PHP 7
HHVM

You will need a good terminal! I've tested only on MacOSX and Linux. I'm sorry about that Windows guys :disappointed:

Installation

Using composer:

$ composer g require gabrielrcouto/php-terminal-gameboy-emulator:dev-master

Using PHAR:

$ wget https://raw.githubusercontent.com/gabrielrcouto/php-terminal-gameboy-emulator/master/bin/php-gameboy.phar
$ chmod +x php-gameboy.phar
$ mv php-gameboy.phar /usr/local/bin/php-gameboy

Running

Your roms are loaded from the directory you are running the php-gameboy command.

$ php-gameboy drmario.gb
$ php-gameboy pokemon.gbc

If you like to run this emulator locally, simple clone the repository:

$ git clone https://github.com/gabrielrcouto/php-terminal-gameboy-emulator.git
$ cd php-terminal-gameboy-emulator
$ composer install -o

For running roms, pass the full path to your rom or put then in the php-terminal-gameboy-emulator folder:

$ bin/php-gameboy pokemon.gbc
$ bin/php-gameboy /full/path/to/your/rom/drmario.gb

Controls

_n_________________
|_|_______________|_|
|  ,-------------.  |
| |  .---------.  | |
| |  |         |  | |
| |  |         |  | |
| |  |         |  | |
| |  |         |  | |
| |  `---------'  | |
| `---------------' |
|   _               |
| _|W|_         ,-. |
||A   D|   ,-. "._,"|
|  |S|    "._," Dot |
|    _  _ Comma     |
|   // //           |
|  // //    \\\\\\  |
|  N  M      \\\\\\ ,
|________...______,"

Left = A
Up = W
Down = S
Right = D
A = Comma (,)
B = Dot (.)
Select = N
Start = M

Tests

You can use the following command to run the most common checks, such as php -l, phpcs:

$ ant check

TO-DO

Converting from the JS paradigm was a lot of work, and I still need to adapt somethings like:

[x] Code standard - PSRs, please!
[x] Array of functions - Maybe in PHP it's not the best approach
[x] Pixel auxiliary array - Very CPU intensive to convert RGBA every time
[ ] Classes - Core is too big!
[ ] Profiling and otimizing - XHProf to find the most intensive functions
[ ] Save/Restore - I need to save my Pokémon, please!

Credits

@gabrielrcouto

Legal

The purpose of this project was to study all the capabilities of PHP.

It does not have any commercial or profitable intentions.

The user is responsible to use this code and its content in the terms of the law.

The author is completely against piracy and respects all the copyrights, trademarks and patents of Nintendo.

Screenshots (1)

Files (18)

File	Role	Description
`bin` (2 files)
`src` (8 files, 1 directory)
`boot.php`	Example	Example script
`composer.json`	Data	Auxiliary data
`composer.lock`	Data	Auxiliary data
`docker-php-7`	Data	Auxiliary data
`README.md`	Data	Auxiliary data

File	Role	Description
`build`	Aux.	Auxiliary script
`php-gameboy`	Aux.	Auxiliary script

File	Role	Description
`Canvas` (2 files)
`Cbopcode.php`	Class	Class source
`Core.php`	Class	Class source
`Data.php`	Class	Class source
`Keyboard.php`	Class	Class source
`LcdController.php`	Class	Class source
`Opcode.php`	Class	Class source
`Settings.php`	Class	Class source
`TICKTables.php`	Class	Class source

File	Role	Description
`DrawContextInterface.php`	Class	Class source
`TerminalCanvas.php`	Class	Class source

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.

Install with Composer

	php-terminal-gameboy-2018-01-22.zip 394KB
	php-terminal-gameboy-2018-01-22.tar.gz 395KB
	Install with Composer

Version Control

Unique User Downloads

Download Rankings

94%

Total:	383
This week:	0

All time:	6,710
This week:	49

User Ratings

User Comments (5)

	All time
Utility:	96%
Consistency:	92%
Documentation:	-
Examples:	89%
Tests:	-
Videos:	-
Overall:	66%
Rank:	545

Haha, I liked to play with this 9 years ago (Joubert RedRat)	70%
Excellent php class package, great idea, this Mister Gabriel ... 9 years ago (marcosptf)	70%
Congratulations, this is a superb class ;-) 9 years ago (José Filipe Lopes Santos)	70%
Congratulations, this is a superb class ;-) 9 years ago (José Filipe Lopes Santos)	70%
Congratulations, this is a superb class ;-) 9 years ago (José Filipe Lopes Santos)	70%