Btn

btn( [i,] [p] )

Tests if a button is being pressed at this moment.

i

The button number.

p

The player number.

return-value

If a button is specified, then true or false, otherwise a bitfield for multiple players.

PICO-8 supports six buttons (0-5) of input for each of up to eight players (0-7). When on the device with a keyboard, inputs for players 0 and 1 can come from keys on the keyboard. All eight players can connect SDL-supported controllers. Each controller is meant to be (or resemble) a Nintendo Entertainment System controller.

btn() called with both arguments returns true if the given player is pressing the given button, false otherwise. If the button number is provided but the player number is omitted, player 0 is assumed.

When btn() is called without arguments, it returns a bitfield of the button states for players 0 and 1. Player 0's buttons are represented by bits 0 through 5 (the rightmost bits), and player 1's buttons are represented by bits 8 through 13 (the leftmost bits). Each bit corresponds to a button number, and a 1 (on) bit representing that the button is pressed.

The button numbers and default keyboard emulation keys are as follows:

Number	Button	Player 0 key	Mask	Player 1 key	Mask
0	🎮 ←	←	0x0001	S	0x0100
1	🎮 →	→	0x0002	F	0x0200
2	🎮  ↑	↑	0x0004	E	0x0400
3	🎮  ↓	↓	0x0008	D	0x0800
4	🎮 O	Z / C / N / NP-*	0x0010	LShift / ⇥Tab	0x1000
5	🎮 X	X / V / M / 8*	0x0020	A / Q	0x2000

* Note that NumPad- and 8 are undocumented button mappings. From PICO-8 0.1.12, these mappings are only default in the CHIP build of PICO-8.

btn() is useful for most action/arcade button uses, where holding down a button for multiple frames needs to be detected for each frame. For actions such as selecting menu options, see btnp().

Undocumented buttons

Number	Button	Player 0 key	Mask	Player 1 key	Mask
6	🎮 Pause	Enter Esc (Splore)	0x0040	n/a	0x4000
7	n/a	n/a	0x0080	n/a	0x8000

Button 6 opens the Pause/Splore menu, and thus btn(6) will only return true the frame just before the menu opens. If detected, this behavior can suppressed by poke(0x5f30,1) to allow the game to use a custom pause menu. See Memory for further details.

Button 7 is currently reserved and always returns false.

Predefined button values

The P8SCII character set includes 26 special glyphs that can be typed by holding Shift and pressing a letter from A to Z in the code editor or the prompt. PICO-8 pre-defines 26 single-character global variables with names from this set of glyphs and gives them useful values. In the case of btn() the ones associated with U, D, L, R, O, and X (⬆️, ⬇️, ⬅️, ➡️, 🅾️, and ❎) are useful, because they represent the corresponding button indices 0 through 5.

These can be used as an argument to btn() (or btnp()) to represent the corresponding button. Do not surround the value in quotes, because these are not strings, they are predefined global variables with single glyphs for names.

-- test for the "left" button, typed as shift + l
if btn(⬅️) and x > 0 then
 x -= 1
end

Examples

x = 0
y = 0
c = 8

function _update()
  if (btn(0) and x > 0) x -= 1
  if (btn(1) and x < 127) x += 1
  if (btn(2) and y > 0) y -= 1
  if (btn(3) and y < 127) y += 1
  if (btn(4) and c > 1) c -= 1
  if (btn(5) and c < 15) c += 1
end

function _draw()
  cls()
  circfill(x, y, 10, c)
end

See also

• Controllers
• Configuration
• SDL
• btnp()