How to install the PICO-8 on Retropie for dum-dums

SpudsMcToole

Installing the fabby Pico-8 pseudo-computer on Retropie is actually really really easy, although you'd never know that from trying to follow any of the hideously confusing and complicated "tutorials" on the subject.

The short version is "Copy a folder over, edit ES_SYSTEMS.CFG and add some games", but here's a step-by-step hand-holding guide that even idiots like me should be able to follow.

YOU WILL NEED: $15 and a keyboard connected to your Pi.

1. BUY PICO-8

It's not free, but it's only 15 bucks (or less than 12 of the Queen's English Pounds) and that includes hundreds and hundreds of games, so hey. Get it from here: https://lexaloffle.com/games.php?page=updates

2. DOWNLOAD THE RASPBERRY PI VERSION

When you pay you'll get a link to a page (the one above, in fact) with loads of versions including the Pi one, but no sort of installation instructions whatsoever. Download the Pi version and you'll get a file that unzips to a folder called pico-8 with six files in it:

3. COPY IT TO YOUR PI

Copy the entire folder over to /home/pi (so that you now have /home/pi/pico-8 with the six files in it).

4. ADD PICO-8 TO EMULATION STATION

Add the following lines to your ES_SYSTEMS.CFG file, which is located in /opt/retropie/configs/all/emulationstation:

  <system>
    <name>pico8</name>
    <fullname>PICO-8</fullname>
    <path>/home/pi/pico-8</path>
    <extension>.sh .p8 .png .SH .P8 .PNG</extension>
    <command>/opt/retropie/supplementary/runcommand/runcommand.sh 0 "/home/pi/pico-8/pico8 %ROM%"</command>
    <platform>pico8</platform>
    <theme>pico8</theme>
  </system>

5. ADD SOME GAMES

Pico-8 "cartridges" come in .P8.PNG file format. You can download them from all sorts of places including the Lexaloffle BBS. Stick a few into the /home/pi/pico8 folder.

(If you have none to hand, see the appendix to this guide.)

6. INSTALL WIRINGPI

I have no idea what this is, but it appears to be necessary and it's the only marginally fiddly part of the process. Quit EmulationStation so you're looking at the Pi $ prompt. Type this:

sudo apt-get install wiringpi

It should install in a few seconds. Reboot your Pi.

7. PLAY THE GAMES

At this point Pico-8 should show up in the ES menu as a list of the games (in .P8.PNG format) you added in Step 5. Pick one and fire it up. It should boot to a screen something like this:

That's yer actual game code. (You can hit Esc to toggle between that and the main Pico-8 prompt if you like.) But you don't need to worry about the technicalities - at this point just hit Ctrl+R on the keyboard and the game will fire up.

And off you go! Games control with the joystick and the A and X buttons. To quit back to EmulationStation, press Command+Q (or Windows+Q depending on your keyboard).

NB At the time of writing, whenever I boot a game the Pi flashes up a message about being unable to access the path /dev/dri. I haven't a clue why it does that or what it means, but it doesn't appear to affect anything, so if you get it too just ignore it.

OTHER USEFUL PICO-8 KNOWLEDGE STUFF

If you don't have any .P8.PNG files, you can start Pico-8 by clicking the lexaloffle-pico8.png file that comes with the emulator. In my experience it'll display an error message on the Pico-8 screen (see pic below), but that doesn't matter because the important thing is that you'll be in.

From the command prompt you have a couple of useful getting-started options.

One is to type INSTALL_GAMES, which will install a small handful of example games for you to try. Another is to type SPLORE, which gets you into the Pico-8 file explorer, which is entirely controlled with the joystick and A button and gives you access to hundreds of games on the Lexaloffle BBS (assuming your Pi is hooked up to the internet).

A fun trivia fact is that because Pico-8 games are stored as PNG files, you can actually use them as box shots in Emulation Station. For some reason it doesn't work if you just tell GAMELIST.XML to look at the file itself in /home/pi/pico-8, but if you open gamename.p8.png in any picture-editing prog and save it out as newname.png, you can pop the new version in /opt/retropie/configs/all/emulationstation/downloaded_images and use it as your menu image.

And from that point, folks, you're on your own.

sumps

@SpudsMcToole hey! Thanks for the post it’s just what I needed!
Although I have a pre-made image on an sd card for a retropie handheld , I cannot find the /pi/home folder? When o look on the pc it’s just the bios, config, screenshots and roms folders?
Do I need to SSH into the pi from my pc to put the PICO-8 folder in there??
Looking forward to hearing from you soon! Thanks

bobuk1973

@SpudsMcToole I've followed the steps and can see pico-8 on the emulation station menu and have the lexoLoffle cart listed but when I select it screen goes.black, runcommand popsup then goes back.to menu does not start Pico 8 or the cart.

Any help would.be appreciated

Thanks in advance.

SpudsMcToole

@bobuk1973 What does RUNCOMMAND.LOG (in /dev.shm) say?

Capeman

I also tried this tutorial, and it just loads to a black screen and kicks me back also.

Capeman

In case anyone comes across this and can't start Pico-8 on retropie, you have to make sure you allow permissions to run.

Install per the guide above, then run this from the command line or via SSH:

sudo chmod 777 ~/pico-8/pico8

This will allow the pico8 application to run and it won't just hard stop and drop you back to ES.

Also if you boot into splore instead of roms directly, you don't need to use a keyboard to run the games or exit back to ES. Works on GPi (but gets a bit hot, haha)

GoodClover

For me es_systems.cfg was at /etc/emulationstation/ not / /opt/retropie/configs/all/emulationstation/.

I have tried @capeman 's suggestion of using chmod to modify the permissions, but I still get a black screen and then it returns to emulation station.

From /dev/shm/runcommand.log:

Parameters: 
Executing: /home/pi/pico-8/pico8 /home/pi/pico-8/lexaloffle-pico8.png
/opt/retropie/supplementary/runcommand/runcommand.sh: line 1279:  1275 Segmentation fault      /home/pi/pico-8/pico8 /home/pi/pico-8/lexaloffle-pico8.png

/home/pi/.emulationstation/es_log.txt had no useful info.

Any ideas?

Capeman

@goodclover if you copy the es_systems.cfg over to the location I specified, you don't need any special permissions to edit it, and it overrides the file in the /etc folder. Last time I tried, I needed root permissions to edit the file in the /etc directory. This just makes it easier.

Try running the pico-8 application directly and boot to splore instead of trying to load a game file. I never figured out how to get downloaded games to run directly from ES, I boot directly to splore and add the games through the splore interface to my favorites list.

Benefit of this is that the main splore menu is controller driven and has an option to exit pico-8 back to ES from a menu item. If you load a game directly (from the people I've seen figure out how to do it), it appears that you would need a keyboard to exit pico-8 to ES.

This is my es_systems.cfg entry that allows it to boot into splore. BUT you still need to add a "game" to the specified roms folder (pico8) to get a selectable item in the Emulationstation list.

<system>
         <name>pico8</name>
         <fullname>PICO-8</fullname>
         <path>/home/pi/RetroPie/roms/pico8</path>
         <extension>.sh .p8 .png .SH .P8 .PNG</extension>
         <command>/opt/retropie/supplementary/runcommand/runcommand.sh 0 "/home/pi/pico-8/pico8 -splore"</command>
         <platform>pico8</platform>
         <theme>pico8</theme>
</system>

pjft

@capeman you can edit to ES when loading a games directly, let that not scare you into doing it.

I'll share my config file later. I think by default I'm loading a game, and then I just have a '+Start SPLORE.sh' file to load SPLORE directly. Will look into it when I get the hands on my pi!

pjft

@Capeman for reference, here are my notes:

1. Change theme
2. Change es_systems.cfg
  <system>
    <name>pico8</name>
    <fullname>Pico-8</fullname>
    <path>/home/pi/RetroPie/roms/pico8</path>
    <extension>.p8 .png .sh</extension>
<command>/opt/retropie/supplementary/runcommand/runcommand.sh 0 _SYS_ pico8 %ROM%</command>    
    <platform>pico8</platform>
    <theme>pico8</theme>
  </system>

3. in /opt/retropie/configs/pico8/emulators.cfg add

default = "pico8_dyn"
pico8_dyn = "/home/pi/RetroPie/roms/pico8/pico8_dyn -run %ROM%"

4. See this:
https://www.lexaloffle.com/pico-8.php?page=manual

add this to the sdl_controllers.txt file:

03000000790000000600000010010000,DragonRise Inc. Generic USB Joystick,a:b3,b:b1,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,leftshoulder:b4,leftstick:b10,lefttrigger:b6,leftx:a0,lefty:a1,rightshoulder:b5,rightstick:b11,righttrigger:b7,rightx:a3,righty:a4,start:b9,x:b2,y:b0,

5. Change in ~/.lexaloffle/pico8/config.txt

// audio volume: 0..256 
volume 96

// Location of pico-8's root folder
root_path /home/pi/RetroPie/roms/pico8/

// Location of cartridge save data
cdata_path /home/pi/RetroPie/roms/pico8/cdata

6. Create SPLORE launcher by adding a "+Start Splore.sh" file at /home/pi/RetroPie/roms/pico8/

#!/bin/bash
/home/pi/RetroPie/roms/pico8/pico8_dyn -splore -root_path /home/pi/RetroPie/roms/pico8/

Some notes:

I have my executable and roms in /home/pi/RetroPie/roms/pico8/ (needs execution permission if external storage)
Step 4 is useful for me as I have a DragonRise joystick. If you have others that need more specific settings, you can add yours from the SDL list, or ignore that step - my PS3 controller works perfectly out of the box.
Step 6 is needed to have Splore be launched.

Hope this helps. What games do you have there that you recommend, if you don't mind me asking?

Best.

Capeman

@pjft Sweet! I'll have to try that, I tried to follow another writeup before but it definitely didn't include some of the steps you detailed above. I'll update it one of these evenings and let you know how it works out for me, thanks!

pjft

@capeman Sure thing. Just saying that these were my notes for my specific setup. Your paths and decisions may vary (for instance, the changes to the .ini file).

silent_lesch

Thank you for the guide. Almost all of it worked in 2021, but there are few things I'd like to alter for those who will come after us.

First, there's a typo in pt 5

Stick a few into the /home/pi/pico8 folder

the correct folder path is /home/pi/pico-8 with a dash. Not a big thing, but if you doing this via SSH, there could be a hiccup.

Then, the es_systems.cfg file. There's no such file in /opt/retropie/configs/all/emulationstation by default. Maybe it was changed in some RetroPie update, but anyway. To add a new system to Emulation Staion, you have to:

Copy the system config to the home folder to make a custom config:

cp /etc/emulationstation/es_systems.cfg ~/.emulationstation/es_systems.cfg

Edit this file and add the Pico8 configuration snippet from the guide

nano ~/.emulationstation/es_systems.cfg

Restart RetroPie

sudo shutdown -r now

Finally, I use my RetroPie as an emulation station it is. There's no keyboard in my setup, only a gamepad. Therefore I cannot press Ctrl-R to run a cartridge. For those like me who just wanna play their games, just add -run suffix to the command line in the snippet

<command>/opt/retropie/supplementary/runcommand/runcommand.sh 0 "/home/pi/pico-8/pico8 %ROM% -run"</command>

You still gonna have to manually restart RetroPie (or use ssh), but at least your ROMs will start automatically.

Also, as for that WiringPi lib - I'd say that it is needed only if you want to connect a custom controller using GPIO.

Anyway, thanks again for the guide. Cheers.

Tupin86

I'm still having trouble installing this. I followed all of the instructions and it still kicks me out with a black screen. Is it some issue with permissions? I went into the dev log and this is what I got:

Parameters: 
Executing: /home/pi/pico-8/pico8 /home/pi/pico-8/picooffroad-5.p8
/opt/retropie/supplementary/runcommand/runcommand.sh: line 1279:  1279 Segmentation fault      /home/pi/pico-8/pico8 /home/pi/pico-8/picooffroad-5.p8

pjft

A segmentation fault shouldn't really be a permissions thing.

What happens when you run it straight from the command line? What system are you on?

Tupin86

@pjft
"SDL error: Could not initialize EGL

FATAL ERROR: Unable to create window

Segmentation fault"

That's what I get running it from the command line, I'm on a RPi4

pjft

@tupin86 Please provide more details per https://retropie.org.uk/forum/topic/3/read-this-first , specifically:

RetroPie Version Used (eg 3.6, 3.8.1, 4.1 - do not write latest):
Built From: (Pre made SD Image on RetroPie website, Berryboot, or on top of existing OS etc.. - please provide the filename of any image used)
Attachment of config files: /boot/config.txt
Pico8 version that you installed, and from.

That error you're getting suggests an issue with the video driver being used in your setup.

EDIT: it seems @GoodClover had the same issue as you in the past. Maybe others can help here, as I certainly don't have that from my RetroPie setup, but I can certainly imagine that more recent versions use a different video driver that causes issues with Pico8.

BenMcLean

This is still somewhat confusing as it has you editing files that may not even exist and aren't accessible by the default samba shares. Also, leaving out that chmod step was very bad. I may need to write my own better guide if nobody else has made a simple one.

Anyway, I did this over ssh to make es_systems.cfg accessible so I could open it in Notepad++ on Windows

sudo cp /etc/emulationstation/es_systems.cfg /opt/retropie/configs/all/emulationstation/

I also had to do

sudo chmod -R 0777 /opt/retropie/configs/all/emulationstation/es_systems.cfg

in order to allow me to edit it. This is not easy stuff for dum-dums. It needs a script really. People who just want to play Pico-8 games cannot understand all this arcane wizardry.

Also had to switch to using pico8_dyn

I shouldn't have to choose between running the pico8 cartridge directly versus running splore. I should be able to do either one, anytime. How do I fix this?

(later edit) More recent guide here: https://retropie.org.uk/forum/topic/30736/how-to-install-pico-8-on-a-raspberry-pi-3-or-4-for-dummies-2021-version?_=1627524066426