Home

Awesome

Gameboy Printer Paper Simulation

This project uses the Arduino Game Boy Printer Emulator to get raw printing data and GNU Octave/Matlab to decode them in a fancy manner. It is compatible with any of the 110 games compatible with the Game Boy Printer.

This e-paper feature is now included in the GBCamera-Android-Manager which allows printing and sharing your images online with a mobile phone !

The motivation ? As Game Boy Printer paper is becoming more and more difficult (and damn expensive) to source and subjected to definitive deterioration with time, emulating it is more and more appealing from an heritage conservation point of view. And using 6 AA batteries in 2024, honestly...

The Game Boy printer emulator developped by Brian Khuu which is used here is able to capture a stream of serial data under text form. The project here aims to tranform this hexadecimal text stream into pleasant images that have the realistic aspect of a roll of paper exiting a thermal printer. Reproducing the tone, noise, granularity and aliasing of to the printer head is challenging compared to a classical pixel perfect rendering. And what is challenging is fun.

My initial trial

My first idea was to do a simulation of printer head by replacing hard square pixels by some sort of bell-shaped spots with lots of noise. A 2D bell-shaped approximation had a sense to me as injecting heat in a point on a 2D surface result in gaussian distribution of temperatures. On thermal paper, tones are due to a chemical reaction of a powder deposited on the surface of paper driven by temperature and phase change. I took inspiration from cashier tickets and Game Boy Printer scans at high resolution. Misalignment of the printer head was also simulated. The result of a pure mathematical approach was interesting for sure.

Let's play with noisy gaussian dots

Example of an early attempt of paper simulation

Even if it was not bad at all, pixels were too regularly spaced and paper fibers that deform the dots and create vertical streaks on paper were impossible to simulate with this approach. We need a more agressive design !

My second trial : it MUST look like the real thermal paper !

After considering the differences between early outputs and real prints (scanned at 3600 dpi) obtained with a recently bought Pocket Printer, I was still not satisfied by the result. The difficulty is that the printer head and paper grain add noise to the image at different length scales. Moreover, the needles from thermal printer head do not just create noisy gaussian dots. These dots also have a random shape (typically due to fibers in paper). So my new idea was to sample a collection of representative pixels of the different grayscales on a good quality scan of isolated pixels printed with my Game Boy Printer.

There is no image available to print in Game Boy library that presents perfectly isolated pixels in huge quantity. So I have created a test case with my brand new SD Game Boy printer code

I first printed this test image with isolated pixels of the three different grayscales (white is just ignored):

Then I scanned a printing of this image at 3600 dpi (sufficient to see the details of pixels, each pixel beeing approx. 20x20 pixels on the scan):

And I sampled manually a collection of 50 pixels of each level of grayscale (very boring task but quite rewarding at the end):

Then the GNU Octave/Matlab code just reads a pixel on a pixel perfect image to get its color, picks a random pixel among the 50 of its own "color" and draws it on a new file with some overlapping. 50 pixels of each color is not much, but a pixel is a simple matrix of value. In consequence, to increase randomness each pixel itself is flipped or rotated randomly so that more than 200 different pixels can be generated out of just 50 for each color. Finally, the real printing paper presents fibres that create vertical streaks of "ink" (thermal paper has no ink but you see the idea). So the code randomly decreases the intensity of printing along some streaks of limited length chosen randomly. Of course the code in its present form can be improved, but the result is enough for my poor visual acuity.

Test case with a Chip Chip printed from Super Mario Deluxe

How to use the Game Boy Printer paper emulation ?

You will need: the cheapest Arduino Uno, the cheapest LED, the cheapest wires, the cheapest soldering iron or the cheapest breadboard, a serial cable to sacrify (for example the cheapest chinese clone found on Aliexpress, please do not sacrify original Nintendo cables) and for ease the cheapest multimeter with continuity mode. The total project cost should be around $10 maximum. Wire and/or solder all that stuff, recharge your cheapest NiMH batteries and you are ready for printing.

Indirect printing from Matlab/GNU Octave using a logfile

On Arduino IDE 1.8.X and earlier:

On Arduino IDE 2.X.X:

Direct printing from Matlab/GNU Octave without using the Arduino IDE !

You can run Read_directly_from_Arduino_Matlab.m or Read_directly_from_Arduino_Octave.m directly to acquire data and decode them in the same run. It behaves like the Arduino Serial output from the IDE but without the need to copy-paste text output: the decoder is ran automatically as soon as you reboot the Arduino after a printing session. How to use it :

The pinout to use for Arduino

But you can also use a dedicated PCB !

If you want something neat, you can follow the instructions given here to build a dedicated PCB (for cheap, really).

Back to the main subject

So, the difficulty with a Game Boy printer emulator is to know where the images have to be cut automatically. It can appear trivial to human mind (tear paper when the print is finished) but it is not for a code (some printing sessions have more than 10 seconds deadtime inbetween packets). 90% of the game sends a margin information that can be detected to cut paper easily (they feed paper to separate images). But about 10% sends nothing (like feed paper with white packets and no margin at all in print command) or margins but within a single print. For these "difficult" games, a strategy have to be invented. Now let's detail how to use the decoder:

Automatic mode or printing with margins

Set gbp_serial_io.cpp and Main_Decoder.m like this:

#define GBP_PKT10_TIMEOUT_MS 400 in gbp_serial_io.cpp line 39
Timeout_printing=0;  in Main_Decoder.m line 13

This is the mode by default: with this settings images will be separated by the decoder if an after margin different than zero is detected. Most of the games are happy with that and in particular the Game Boy Camera. For most of the users this mode will be enough, no need to go farther.

Idle mode or printing with a time out message

Set gbp_serial_io.cpp and Main_Decoder.m like this:

#define GBP_PKT10_TIMEOUT_MS 15000 in gbp_serial_io.cpp line 39
Timeout_printing=1;  in Main_Decoder.m line 13

In idle mode, the printing command from the Game Boy is not taken into account. Instead, you have to wait for the "Memory Waterline" string to appear into the Arduino serial (which means that the serial is now idle) before making another print. This allows the decoder to know how to assemble images that contains inner margins or no margin at all. Remind that the real printer uses a roll of paper that you decide to cut manually, so certains games do not care of the printing margins. So you have to force a bit the image separation in order to get the nice printing wanted by the programmers.

Games that can take advantage from the idle mode are (for example):

Some more technical trivia

The game compatibility of the Game Boy Printer emulator have been increased to 100% by applying two simple rules to the error packets sent by the Printer emulator to games: the error packet is always 0x00 before printing (the games clearly do not mind this error byte most of the time) except when an empty data packet is received, where it becomes 0x04 (image data full). This allows triggering the print command for certain rare games that require this. The post-printing commands are exactly the ones from the original project.

Can I modify the palettes of the pixel perfect images or e-paper outputs ?

The code is of course fully open to modifications. Edit "color_packet.m" and add a new line indicating your desired RGB triplets:

colors=[255 255 255 168 168 168 84 84 84 0 0 0;% 1 = Black and white
        215 247 215 130 222 73 6 75 145 0 19 26;% 2 = Game Boy Color
        123 130 16 90 121 66 57 89 74 41 65 57;% 3 = Game Boy DMG
        255 255 255 89 255 252 239 42 248 0 0 0;% 4 = CGA
        255 255 255 255 128 128 128 64 64 0 0 0];% 5 = Salmon

(R G B for white) (R G B for light gray) (R G B for dark gray) (R G B for black)];%Your palette

Then just edit "color_packet.m" to seek to the palette option:

color_option=X; %X your custom palette

Same for the paper output, edit "epaper_packet.m" and seek for these commands:

if (paper_color==X)
speckle_image(:,:,1)=speckle_image(:,:,1)*(R/255);
speckle_image(:,:,2)=speckle_image(:,:,2)*(G/255);
speckle_image(:,:,3)=speckle_image(:,:,3)*(B/255);
end

X is the number of the e-paper palette and RGB the color levels applied to the whole image. Then just edit "color_packet.m" to seek to the new palette by its number in "Main_decoder.m"

paper_color=X; %X your custome palette

Examples of default palette output from the code:

White, blue and yellow papers have the regular tones of official Nintendo papers. Pink is an invented tone that would have been cool in the series.

Known minor issues related to the printer emulator, Arduino side

Known minor issues related to the decoder, Matlab/GNU Octave side

The complete (and tested) list of games compatible with the Game Boy Printer and the Printer Emulator (ポケットプリンタ - 対応ソフト)

There is in total 110 games compatible with the Game Boy Printer (and printer emulator). I've tested all of them on various machines (DMG, GBC, GBA and the Chinese GB Boy Colour clone, serial plugged to the Arduino to print) and can certify the printer support with printer emulator, even if some printing features are very tricky to reach - like making a 100% on some RNG based Japanese kosuge. I used a general purpose flash cartridge (EZ-FLASH Junior) for testing the games I do not own (most of them in fact). I also used BGB emulator to manipulate the wram of some very though games to create custom saves to write back in real hardware. Some rare games require the original cartridge (one game uses the uncommon HuC-3 mapper) or another flash cartridge for no obvious reasons (two games with common mappers are only compatible with the GB SMART 32M). One "game" (SMARTCOM) even required a rom modification (I had to hack a hack from Furrtek) to counterpass a boot sequence trick and allow printing with real hardware. Assessing single or double speed mode in protocol was made with a digital/analog oscilloscope (series FI 3130 - Française d'Instrumentation) probing the clock pin. I'm probably the only human on earth to have printed with all games compatible with the Game Boy Printer, which is a quite nerdy achievement I admit (but I know at least someone jealous of that).

All of this represents a crazy amount of programming, hacks, researches on forgotten Japanese websites and hours of frustrating gaming sessions, spreaded on about 18 months of spare time.

The .zip file in the repo contains 100% or any% saves ready to use with printer features unlocked for many games, as well as examples of printer emulator output and prints for each of them. See the "Game Boy Printer Emulator - Games Support.xlsx" to check the various hints to print from these games, obscure Japanese and totally WTF ones included. This complete list was established by cross-checking English and Japanese game titles known for using the printer and by rom code analysis to reveal some new ones that were never included in any list before. This list was never published online before june 2021 and contains probably the entire game collection that uses the printer.

I have contributed to the NeoGB Printer which uses the same engine and has exactly the same compatibility with games. It adds some serial protocol analysis to automate automatic/timeout modes.

So, here is the curated game list:

There are nevertheless some debatable cases:

Mario Artist Paint Studio is supposed to be directly compatible with the Game Boy Printer via an unreleased "64GB Cable" coupled to an unreleased "Game Boy Printer cartridge" equipped with an unreleased "MBC4" mapper, in addition to yet allow using the transfer pak with the Game Boy Camera as middleman. Mario Artist Paint Studio contains a printer libray and menus for using printers, both grayscale and color. Mario Artist: Communication Kit also contains a dismissed printer menu and a full printer library. Both N64 games contains commands for the classic printer with packets of 640 bytes but also for the elusive color printer with packets of 320 bytes and the undocumented command 0x06.

Example of printer commands in Mario Artist: Communication Kit (and Mario Artist Paint Studio as they are exactly the same)

The Debagame Tester: Second Impact, prototype of the Game Boy Camera, contains a complete printer library and a COM menu but I do not find any way to activate a decent serial port activity from button inputs (other than a reset of CLOCK state). I guess the version 10.24 of the rom (the only one known to date) was not compiled with that functionality. Considering that the Game Boy Printer was probably just a prototype at that time, it is not that surprinsing.

Example of printer commands in Debagame Tester: Second Impact

This is probably the earliest version of the Game Boy printer library engraved in silicon. Yet, all commands are there.

Example of printer outputs from various games made with the printer emulator from real hardware

Tips for printing with japanese games : search for these characters: プリンタ (Printer) or more rarely ポケットプリンタ (Pocket Printer) in games menu. This sometimes brings you only to the contrast settings for the printer, so persevere. Some games are a real pain to play in japanese as they rely on endless discussions and menus, or need a 100% completion with special events to unlock printing features, but hey, it's for science !

I found that many Japanese exclusive games in this list are just kusoge, for various reasons sadly not only related to barrier langage, like: cryptic gameplay (Animal Breeder, Chee-Chai Alien), unfair difficulty (Sanrio Timenet series, Dino Breeder), ruthless RNG (Mahjong series, Daa! Daa! Daa! Totsuzen), boring objectives (Hamster series), uninspired level design (Cross Hunter series, Kaseki Sousei Reborn) or blatant plagiarism of Pokémons (Monster ★ Race series, Sanrio Timenet series). Of course western exclusive games have also their load of shit that gave me headaches and very unpleasant gaming sessions (Tarantula games deserve recycling in hot nitric acid bath), but at least it's documented shit in the West with no surprise.

List of games that embed a printer library but without printer support for the player

Code analysis of the Game Boy and Game Boy Color romsets revealed that some games (generally sequels of the preceding list) embed a printer library into the code but no printer support for the player. Some of them where clearly intended to use the printer as their gameplay is about unlocking images. The printer support was probably dismissed during game development as most of them are late published Game Boy Color games. Lazy recycling of non-optimized graphical libraries is also not excluded as maskrom size was less and less critical at this time. Sadly for the fetishists of furs, there was a bunch of hamster related games with printer support removed...

I guess that the printer support may be easily restored by some Game Genie code, at least for the Japanese exclusive games that are sequel of games known for using the printer. It's currently not part of my skills to mess up with assembly langage.

List of games that display a printer support on the box but without any printing feature confirmed by players

These games display a printer support logo on their box but I did not find any evidence of a printer library into their code (even a remainder) and it seems than nobody on internet was able to print something from them since more than 20 years. The consensus in 2021 is that these games do not have printer support:

In consequence, I won't include them in the official list. The printer logo on the box is very probably a copy-paste from a generic template made by an I-don't-give-a-shit-of-this-game graphist.

Time for statistics !

On the 110 games compatible with the Game Boy Printer:

Aknowledgments

Some known relaxing scene interpreted with the paper simulator to end.