Controllers

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

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().

You can customize the key mappings for players 1 and 2 interactively using the keyconfig command. You can also edit config.txt directly.

Configuring controllers

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
• The controllermap tool distributed with SDL2
• Find your SDL2 controller mapping in this list.

The complete procedure for using GamePadTool:

1. Connect a controller to your computer.
2. Start GamePadTool. The tool should detect the controllers and allow you to select between them.
3. Make sure that the controller is selected, then click "Copy Mapping String." This copies the mapping string to your clipboard.
4. Edit the sdl_controllers.txt file in the PICO-8 configuration directory. Paste the mapping string onto its own line, then save the file.
5. Start (or restart) PICO-8 to use the new configuration.

Connecting controllers

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

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

See also

• Configuration
• keyconfig
• SDL