php-terminal-nes-emulator renders NES frames as text and colour blocks in a terminal

A PHP program that draws a cartridge's frame into a terminal

php-terminal-nes-emulator is an NES emulator written in PHP, and the repository shows a demo.gif of it working in a terminal. The description in the repository is minimal, a PHP terminal NES emulator, and the README says the project is based on bokuweb/flownes and gabrielrcouto/php-terminal-gameboy-emulator, with credit given to both at the end.

The lineage matters for understanding the design. One predecessor is a terminal NES emulator and the other is a terminal Game Boy emulator, so the approach of rendering a console's video output as terminal characters is inherited rather than invented here. The visual effect is that of a monochrome terminal frame built from character cells, which is why the emulator needs a colour PNG mode for anything that looks like a picture.

The repository layout is small and matches a single program. The top level holds boot.php, composer.json, composer.lock, the src/ directory with the implementation, tests/ for the test suite, the demo.gif, the README and a LICENSE file. There is no build system beyond Composer, no service definition and no configuration file.

The stated purpose is in the legal section rather than the introduction, and it is worth reading before anything else. The README says the purpose of the project was to study all the capabilities of PHP, that it does not have any commercial or profitable intentions, that the user is responsible to use the code and its content in the terms of the law, and that the author is completely against piracy and respects all the copyrights, trademarks and patents of Nintendo. That framing is a fair description of what this is: a technical demonstration with an academic purpose, and a repository that depends on the user bringing their own ROM.

Install is a clone, a cd and a composer install

The requirements are three things: PHP 7.0 or later, Composer, and an NES ROM. The install steps are the standard PHP project sequence:

$ git clone https://github.com/hasegawa-tomoki/php-terminal-nes-emulator.git
$ cd php-terminal-nes-emulator
$ composer install

There is a link for anyone who does not have Composer, pointing at the getcomposer.org introduction document with a locally install section, which tells you the project assumes you will install dependencies from Packagist rather than vendoring them.

The ROM requirement is the one to think about carefully. The emulator does not ship any game content, so nothing is bundled and nothing is distributed. A ROM is copyrighted content, and the README is explicit that the user is responsible for using the code and its content within the law and that the author opposes piracy. A legally obtained ROM is therefore a precondition, not a suggestion, and the ROM is not a dependency the project can provide for you.

The presence of composer.lock is worth noting for a different reason. A locked dependency set means the install you get is the one the author tested, which matters when the emulator leans on PHP extensions or library behaviour that shifts between versions.

One command starts the emulator with a ROM as the argument

Running it is a single PHP invocation with the ROM file as the first argument:

$ php boot.php your-rom-file.nes

The entry point is boot.php, and it takes the path to the ROM file directly rather than reading configuration or environment variables. That is a deliberately minimal interface, appropriate for a program whose whole input surface is a cartridge image and a few keystrokes.

There is one option, and it changes the output completely. Running with -cpng gives colour pictures, and the README says you can then see the screenshots in the ./screen directory. So the default mode is the character based terminal rendering, and -cpng switches to writing colour images out to disk instead of painting into the terminal.

That distinction explains a lot about the project. Emulating a PPU and blitting a frame is one job, and drawing that frame as coloured blocks in a terminal grid is a different, much harder one. The PNG mode sidesteps the terminal's colour limits by rendering to an image file, which is also why the author describes the screenshots as beautiful.

The one hard technical constraint is stated plainly: the emulator is compatible with mapper 0 ROM files. Mapper 0 is the simplest cartridge board, unbanked, with no extra chips. Games that rely on other mappers will not run, and there is no configuration to change that.

Five keys, mapped by letter, and no more

The controls section is a small ASCII diagram rather than a table:

  [W]
[A] [D]        [,] [.]
  [S]   [N] [M]

Eight keys are bound, and four of them are the arrow keys by letter, W for up, A for left, D for right and S for down, with N and M doing something else that the README does not name. The diagram also shows the comma and full stop keys, which are presumably the A and B buttons of the NES controller laid out in the familiar position.

What the diagram does not say is anything about the timing, the buffering, or how the emulator handles input latency in a terminal. This is one of the places where the documentation is thin, and it is worth being explicit about that rather than guessing. A terminal program reads from standard input, and a terminal's own input handling and line buffering are not the same thing as a game controller's polling, and the README does not document how that is bridged.

The same applies to the N and M keys. They are shown in the diagram, so they are bound to something, but the README does not say what they do. A reader who wants to know whether the emulator supports a pause, a mute or a frame step has to look at the source in src/.

No releases, and the last push was in July 2026

The repository has no GitHub releases, and the last push was on 2026-07-22, roughly three months before this review. The repository is not archived. So the project is a completed personal study that occasionally receives a commit rather than a maintained project with a release cadence, and there is no version to pin.

The licensing is MIT, recorded in the LICENSE file at the repository root, so the code itself can be reused, modified and redistributed with the notice retained. That is a licensing note rather than legal advice, and it applies to the emulator code, not to any ROM you feed it.

The related question is where the code came from. The README credits bokuweb/flownes and gabrielrcouto/php-terminal-gameboy-emulator, which are the upstream projects this one is based on. If you are considering reuse, check the terms of those projects as well, since a derived project does not automatically inherit only the licence of the newest layer.

There is also a Japanese blog entry linked from the README, dated October 2018, which is where the author writes about the project. For anyone who wants the design rationale rather than the operation instructions, that is the more informative document, and it is a reminder of the project's age. The demo.gif in the repository root shows the intended effect, which remains the fastest way to judge whether the terminal rendering is worth pursuing.

Editorial conclusion

Adopt this repository if you want to read a working emulator core in PHP, or if you need a terminal demo that renders retro video as text for a talk or a terminal UI experiment. Do not adopt it as a way to play commercial NES games, since the author states the project is a study of PHP's capabilities with no commercial intention and that the user is responsible for using the code within the law. Verify first that your ROM is a mapper 0 file and that you have the right to use it, keep in mind the emulator targets PHP 7.0 and above, and expect a single screen of output rather than a playable game, since the input handling is limited to the eight keys shown in the README.

Frequently asked questions

Official sources

1. hasegawa-tomoki/php-terminal-nes-emulator on GitHub
2. Issues
3. License: MIT
4. README