Guide to writing new SDL2 controller mappings for your input devices for use with Pico-8 from your PocketCHIP


To write your own SDL2 controller mappings for Pico-8 directly on your PocketCHIP, in brief:

  1. Compile controllermap
  2. sudo apt-get install gcc make libsdl2-dev
  • wget

  • tar -zxvf SDL2-2.0.4.tar.gz

  • cd SDL2-2.0.4/test

  • ./configure

  • make controllermap

  • OPTIONAL: Assuming there were no errors, you may remove the SDL2 source and object files now that we’re done with it:
    mv controllermap ../.. cd ../.. rm -r SDL2-2.0.4 rm SDL2-2.0.4.tar.gz
    Be very careful with rm -r commands, because that’s how you accidentally delete everything.

  • Have your desired gamepad, flight stick, or other wacky input peripheral connected at this point.

  • If it’s a wireless bluetooth device, make sure it’s awake, paired, and connected.

  • ./controllermap

  • If the application outputs:
    INFO: There are 0 joysticks attached
    Then just give up here, you’re screwed. (This is why we can’t have nice things…)

  • ./controllermap 0 > out.txt

  • You should see an illustration of a gamepad on the screen now. Press your controller’s equivalent of the highlighted buttons. The results will be saved to out.txt

  • If you screwed up, just rm out.txt and try again.

  • When you’re satisfied, add it to Pico-8’s game controller mappings like so:
    cat out.txt >> ~/.lexaloffle/pico-8/sdl_controllers.txt

  • Close Pico-8 if it’s open by switching to it (Ctrl+Tab or through the home menu) and pressing Ctrl+Q (or pressing Esc and navigating its menus to SHUTDOWN PICO-8 or typing shutdown in its console or whatever you prefer) and re-open it to reload sdl_controllers.txt

  • Note: Pico-8 is not “open” until you pass the title screen and it does that little boot-up animation, expect controllers will not work until you’re in the game selector.


Usb controller for Pico-8 on PocketC.H.I.P?
Usb controller for Pico-8 on PocketC.H.I.P?

You need to keep controllermap.bmp, axis.bmp and button.bmp from the SDL2-2.0.4/test folder in the same directory of the compiled controllermap !


Hi there, thanks for this guide- it was useful though didn’t quite get me all the way there. I, too was hung up on the missing .bmp files, and did the file removal before getting to that point, so I had to backtrack a good ways.

But the main issue I’m having, is that I get the controllermap app working, and the app hangs or becomes unresponsive/sluggish when identifying the analog sticks. Then it never goes further than identifying the vertical axis on the right analog stick. I have tried this three times and am using a bluetooth 8bitdo NES30 Pro gamepad. I followed this guide to get the bluetooth working. Bluetooth Pairing - “pastebin” - session I also suspect that this controller has a tilt sensor and that the other axis registrations may have accidentally been the tilt. There is no documentation of this, but the controls’ similar layout to ps3 and the optional firmware I mention below make me think it might.

I am going to try updating the firmware on this controller tonight and see if that solves anything. Also, the instructions/manual on this controller are in pretty bad Engrish and don’t even mention several crucial functions and/or buttons. I also noticed that this controller has an optional PS3 mode firmware you can add to it, and I have a PS3, but got this because I wanted something more compact. I noticed a guide however for getting a ps3 controller to work, though it is said to be difficult. I may try that if I get desperate.


tried again after updating firmware on the same controller. Bluetooth is connected, got the controllermap app to finish, though not sure if it properly registered the axes again. copied text to SDL file, launched pico-8, the controller does nothing. Rebooted, same thing. This controller has several “modes,” I used “keyboard mode.” Opened SDL file to verify the text was there, and it was. Noticed there were Windows listings in the SDL file for this controller. copy-pasted the button mappings from that to the Linux one, rebooted, still no effect.


UPDATE: Got this controller (8bitdo NES30 Pro) working successfully- it only works with the pocketchip in “joystick mode,” and I had to redo the bluetooth configuration after switching modes, despite what these forums had been saying about using keyboard mode.


Hello, I have some problem. I use noname SNES-like gamepad(so, there are 12 buttons), but controllermap recognize 10 buttons and 2 axises and in GUI presses on left and up buttons is doesn’t making anything(but they sends something in /dev/input/js0).
I think, gamepad emulates axises instead of arrow buttons(but why?) but two arrow buttons works normal.
And Pico-8 all the same doesn’t see a gamepad(but, for example, I configured gamepad in Mednafen and it works) :\

Thanks in advice.

EDIT: Problem solved. I just passed arrows configurations(by pressing Space) and press arrows buttons on axises configuration.