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 or Mac
• The controllermap tool distributed with SDL2

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. Player 1 gets the first controller.

There is no way to assign specific controllers to specific players. Also, there is no way to force the first controller to get assigned to Player 3. To use a controller with player 3, you must have at least three controllers connected. (Players 1 and 2 can continue to use the keyboard, but there must be controllers connected for those 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