PICO-8 supports the use of game controllers that can be connected to a computer, either with a wired USB connection or a wireless Bluetooth connection. PICO-8's controller support is based on the SDL library.
A game can have up to 8 simultaneous players. Players 1 and 2 can use game controllers or corresponding keys on the keyboard. Players 3-8 must use game controllers.
Keyboard controls Edit
While a game is playing, PICO-8 recognizes keyboard presses as controls for players 1 and 2. For example, player 1 can use the cursor keys, Z, and X for the six possible inputs.
For a complete list of default key mappings for players 1 and 2, see btn().
Configuring controllers Edit
You can configure controller mappings by editing the
sdl_controllers.txt file in the PICO-8 configuration directory. Each line of the file is a controller mapping in the format used by SDL. You only need one line for each kind of controller you wish to use.
Here is an example of a mapping line:
79000000000000001100000000000000,Retrolink Classic Controller,x:b3,a:b2,b:b1,y:b0,back:b8,start:b9,leftshoulder:b4,rightshoulder:b5,leftx:a3,lefty:a4,platform:Mac OS X,
You can generate this line using one of these tools:
- General Arcade's GamepadTool for Windows, Mac and Linux
controllermaptool distributed with SDL2
- Find your SDL2 controller mapping in this list.
The complete procedure for using GamePadTool:
- Connect a controller to your computer.
- Start GamePadTool. The tool should detect the controllers and allow you to select between them.
- Make sure that the controller is selected, then click "Copy Mapping String." This copies the mapping string to your clipboard.
- Edit the
sdl_controllers.txtfile in the PICO-8 configuration directory. Paste the mapping string onto its own line, then save the file.
- Start (or restart) PICO-8 to use the new configuration.
Connecting controllers Edit
PICO-8 assigns controllers to players in roughly the order they are detected when PICO-8 starts up.
By default, player 1 gets the first controller. You can change which player gets the first controller by providing the
-joystick command line argument when starting PICO-8. Its value is a number from 0 to 7 (player 1 through 8). For example, to start assigning controllers with player 3:
pico8 -joystick 2
There is no way to assign specific controllers to specific players.
If you connect a controller while PICO-8 is running, you must restart PICO-8 before you can use it.
Testing controllers Edit
Here is code for a simple cart that lets you test controllers for all players:
function _update() end function _draw() cls() for p=0,8 do print(''..p..':', 0, p*7, 1) for b=0,6 do if btn(b,p) then print(b, b*5 + 10, p*7, p+1) end end end end