btn( [i,] [p] )
Tests if a button is being pressed at this moment.
The button number.

The player number.

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 Edit

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.

Examples Edit

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
function _draw()
  circfill(x, y, 10, c)

See also Edit

Community content is available under CC-BY-SA unless otherwise noted.