Guide: Pico-8 on Retro Handheld Devices

Last updated 19JUN2021 (see Changelog for details)

Pico-8 is one of my favorite systems to run on handheld emulation devices, because there are thousands of indie games right at your fingertips, and they are a perfect match for a handheld system.

Table of Contents:
Purchase and download Pico-8
Download Pico-8 games ("carts")
EmuELEC
ArkOS
351ELEC
Stock firmware for RG351P / RG351M / RG351V
Lazy Devs' top 10 Pico-8 games

Changelog

Purchase and download Pico-8

I know we’re all used to running free and open-source software on these devices, but in order to run Pico-8, you need a legally purchased version of this microconsole. I personally think that $15 is a small price to pay to access thousands of awesome indie games, but it’s up to you. One neat feature: once you purchase the system, you can also download the PC, Linux, and Mac versions to play on your home computer!

If you have purchased a game bundle in the recent past, such as the viral Bundle for Racial Justice and Equality earlier this year, you may actually already own Pico-8. I recently purchased Pico-8, only to find out that I had already purchased it two other times as part of game bundles, and didn’t realize it.

So head over to the Pico-8 homepage and purchase the Raspberry Pi version of the console. Download and unzip the file.

Download Pico-8 games (“carts”)

The amazing thing about Pico-8 is that all of the games (called “carts”) are freely available, and there are thousands of them to choose from. To get started, head over to this page and try out some carts to see which ones you like — yep, you can load them right up in your web browser to test them. Once you find one you like, simply right-click on the word “Cart” at the bottom-left of the game screen, and select “Save Target As…” and download the corresponding .p8.png file. That is the game cart that you can launch directly on your device once set up.

This entire process is optional, because once you load Pico-8 onto your device, you can actually browse their cart library over the internet, and load/save games directly from your device.

If you’re looking for a couple to test out, might I recommend Bearmy, a game that I developed over a weekend? My son also made one that same weekend, and his is called Challenge Game, and it’s better than mine. Both of these are just demos, but are a cool indication of the things you can create on this platform.

EmuELEC (ODROID Go Advance, ODROID Go Super, GameForce Chi, Super Console X, and more)

Take the downloaded contents of the Raspberry Pi version of Pico-8 and put them in a folder named “pico-8” within your EEROMS/bios/ folder on your SD card. So the contents will look like this:

EEROMS/bios/pico-8
 lexaloffle-pico8.png
 license.txt
 pico-8.txt
 pico8
 pico8_dyn
 pico8_gpio
 pico8.dat 

Next, you can add your carts directly to the EEROMS/pico-8 folder if you’d like, and can boot them from the EmuELEC menu. Otherwise, when you power on the device, it will detect that you have added the appropriate Pico-8 BIOS files and will now display that system in the main menu. From there you can go directly into the “splore” menu to browse and launch games over the internet.

To exit out of Pico-8, you can either use a hotkey like SELECT + START to kill the app (or HOME + START for the GameForce Chi), or you can navigate to a game and select OPTIONS > Shutdown Pico-8.

Any game you boot within the splore menu will appear in your EmuELEC Pico-8 folder afterwards, which is handy (unless you tried a game and didn’t like it!). To delete the game, you can connect to the device to your computer by opening up a connection to \\emuelec in your File Explorer (Windows) or type CMD + K while in Finder on a Mac and type smb://emuelec (connect as a Guest). Then navigate to the ROMS > pico-8 folder and delete the unwanted cart(s).

Additionally, you can organize the carts into a subfolder (name it something like “carts”) to make navigation a little bit easier. Once you’ve placed them in a subfolder, go into the Pico-8 folder while in EmulationStation, and then press SELECT > View Customization > Show Folders > Always. This will clean up the menu for you.

ArkOS (RG351V, RG351P, RG351M, RGB10, and more)

For ArkOS, add the following files from the Raspberry Pi version of Pico-8 to your EASYROMS/pico-8 folder on your SD card:

pico8
pico8_dyn
pico8.dat

Inside that folder you should also find an sdl_controllers.txt file, don’t mess with it (that file allows the controls to work!). If you’re using the RG351V, and you have your ROMs on the second SD card, place the Pico-8 files on the second SD card as well.

Within the EASYROMS/pico-8 folder, make another folder named “carts”. Inside this folder you can put your own game carts (in .p8 or .png format) and they will appear in the ArkOS main menu.

If you want to use the splore function, you need to create a blank text file named “zzzsplore.p8” and place it in the EASYROMS/pico-8/carts folder. Then, from the main ArkOS menu, select the “zzzsplore” file to boot into splore.

From the ArkOS wiki:

By default, pico-8 games will load in a 1:1 aspect ratio. You can also load games in full screen and pixel perfect aspect ratios as well by changing the default emulator setting. See here for information on how to change the default emulator.

To exit out of Pico-8, you can use the hotkey like SELECT + START to kill the app.

351ELEC (RG351V, RG351P, RG351M)

Place the following files from the Raspberry Pi version of Pico-8 into the GAMES/pico-8 folder of your SD card:

pico8
pico8_dyn
pico8.dat

Inside your GAMES/pico-8 folder, create another folder named “carts”. Place all of your Pico-8 carts (in .png or .p8 format) in that folder. If you’re using the RG351V, and you have your ROMs on the second SD card, place the Pico-8 files on the second SD card as well.

Pico-8 is hidden by default in 351ELEC. To make it visible, select Main Menu > Game Collection Settings > Systems Displayed > Pico-8 and make sure that it is checked. Once visible, you will be able to select “Start Pico-8” to boot into splore, or just boot your cart directly from the main menu.

To exit out of Pico-8, you have two options:

• If you started your game directly from ES then press the select button and choose shutdown from the menu
• If you started pico-8 through “Start pico-8” then highlight a game in the splore menu, press the select button, choose “options” then choose “shutdown pico-8”

Stock firmware for RG351P / RG351M / RG351V

Adding Pico-8 to the stock firmware of the RG351 devices is easily the most difficult of all these processes. I recommend that you move on from stock firmware to something else, like ArkOS or 351ELEC, but if you’re stubborn and want to stick with an inferior gaming experience, here are the instructions 🙂

In order to make the games run, you must add them to the Linux partition of the device and make them executable. The only way to access this part of the device is via WiFi FTP or through Linux file system software. For more info on this process, check out my File Transfer Guide.

Connect to your device via FTP, then go to the storage/.config/emuelec/ports folder. Inside this folder, create a folder named “pico-8”. Place all of your Pico-8 system files inside the new storage/.config/emuelec/ports/pico-8 folder. They should be the following files:

lexaloffle-pico-8.png
license.txt
pico-8.txt
pico8
pico8_dyn
pico8.dat
sdl_controllers.txt

Right-click on the pico8 file and select “Properties” (or “Get Info” if using Forklift on a Mac). In the permissions box, you should see Read, Write, and Execute permissions for the file. Make sure that all of the Execute (“X”) permissions are checked YES. Do the same for the pico8_dyn file.

Next, we need to make a file that will execute the Pico-8 program. To do this, go back to the storage/.config/emuelec/ports folder and create a file named pico-8.sh. If there is already a .sh file in there, you could just make a copy of it and rename it to the pico-8.sh file you’ll need.

Open up the pico-8.sh file, and paste the following code:

#!/bin/bash

/storage/.config/emuelec/ports/pico-8/pico8_dyn -splore -home -root_path /storage/roms/pico-8 -joystick 0

Save and close the pico-8.sh file. Now, right-click on the pico-8.sh file and select “Properties” (or “Get Info” if using Forklift on a Mac). In the permissions box, you should see Read, Write, and Execute permissions for the file. Make sure that all of the Execute (“X”) permissions are checked YES.

Still inside the storage/.config/emuelec/ports folder, create a folder named “images” if there isn’t one already. Go to the storage/.config/emuelec/ports/pico-8 folder and copy the lexaloffle-pico8.png file and paste it into the storage/.config/emuelec/ports/images folder. Rename this file to system-pico-8.png.

Back in the storage/.config/emuelec/ports folder, create a file named gamelist.xml if there isn’t one already. Open it up with a text editor, and paste in this code:

<?xml version="1.0"?>
<gameList> 
       <game>
              <path>./pico-8.sh</path>
              <name>pico-8</name>
              <desc>The Pico-8 is a virtual machine and game engine created by Lexaloffle Games. It is designed to mimic a "fantasy video game console," by emulating the harsh hardware limitations of the video game consoles around the 1980s.</desc>
              <image>./images/system-pico-8.png</image>
              <thumbnail>./images/system-pico-8.png</thumbnail>
              <developer>Lexaloffle Games</developer>
              <playcount>6</playcount>
              <lastplayed>20201104T095110</lastplayed>
              <gametime>1606</gametime>
              <lang>en</lang>
       </game>
</gameList> 

Note that if you already have an existing gamelist.xml file in the directory, don’t paste in the “<?xml version=”1.0”?> and <gamelist> tags, just take everything between the <game> tags.

Head back over to the storage/.config/emuelec/ports/pico-8 folder. You need a proper “sdl_controllers.txt” file, which will map the controls for your system, but they don’t work with the RG351P right out of the box. Instead, download and unzip this file and drag it into this folder to replace the current sdl_controllers.txt file. That’s it.

Head over to the storage/roms folder, and inside this folder, create another folder named “pico-8”. Inside this folder, add all of your Pico-8 game files. To find games to add, go to this page and browse through until you find something you like. You can even demo the game on your computer or phone ahead of time to see if you like it. To download the game, just click on the small “Cart” link on the bottom-left, and download the .png file. That’s actually the compressed version of your game. Rinse and repeat until you have all the games you want, then add them to that storage/roms/pico-8 folder.

Alternatively, if your RG351 device is hooked up to the internet (via an OTG adapter and WiFi USB dongle), you can just boot up Pico-8 and check out games in the “Featured” or “New” sections.

If you’ve done everything correctly, Pico-8 should now show up as an option in the Ports section of EmuELEC. If you don’t see a “Ports” section, enable them in the settings. Go into UI Settings > Systems Displayed and make sure Ports is checked.

When you first boot up the system, press left or right until you get to the folder icon, and you’ll see all of your downloaded games. If you are network-enabled, I recommend going to the “Featured” section and selection the UPDATE option, and then browsing from there. Press A to start up a game. To set a game as a Favorite, boot up the game and then press SELECT and select “Favourite”.

To exit a game, press SELECT then choose “Exit to Splore” which will take you to the Pico-8 menu. To exit the program, press SELECT again and select Options > Shutdown Pico-8.

Lazy Devs’ top 10 Pico-8 games

If you’re looking to get started with Pico-8’s “cartverse”, it’s as simple as navigating through Splore and booting up a game to see if you like it. But if you’d like a more curated introduction, here are Lazy Devs‘ top 10 Pico-8 games (as featured in the video above).

Celeste
Just One Boss
UFO Swamp Odyssey
Swordfish
Alpine Alpaca
Dusk Child
Dank Tomb
Mai-Chan’s Sweet Buns
The Lost Night
Pico Racer

---

Changelog

19JUN2021
– added video guide
– added Lazy Devs’ top 10 Pico-8 games

06JUN2021
– rewrote the guide to incorporate all major firmwares and devices

23MAY2021
– updated link to 351ELEC guide

24FEB2021
– updated links to 351ELEC and ArkOS guides

12NOV2020
– published guide