controls


btn = "button"

btn( index, [player] )
index a button number or button symbol (see chart below)
player (optional) a player number (0-7)

If you hold the button down, this will act like it is rapidly pressed.

For multiplayer games, you will need to include player numbers (0-7).

These are the button indexes you can use:

Button Number Glyph
Left 0 shift+L
Right 1 shift+R
Up 2 shift+U
Down 3 shift+D
O 4 shift+O
X 5 shift+X


For Example:

if btn(0) then x-=1 end  --left
if btn(1) then x+=1 end  --right
if btn(2) then y-=1 end  --up
if btn(3) then y+=1 end  --down

It is common to see this simple style of button detection and player movement in PICO-8 games. We check if the default direction buttons are pressed using the button numbers (0-3), then if any of those are true, then we subtract or add to the X and Y position appropriately. 

(Remember: The Y-axis is the opposite from what you might assume. Subtract to move upwards, and add to move downwards.)


Button Glyphs

These are the glyphs or symbols that are used inside of the PICO-8 code editor. These button glyphs can actually replace the button numbers when using the btn() function.

This is what that code will look like inside of PICO-8, with the buttons appearing as glyphs:

Here is what the glyphs look like oustide of PICO-8:

function _update()

	if btn(⬅️) then x-=1 end --left
	if btn(➡️) then x+=1 end --right
	if btn(⬆️) then y-=1 end --up
	if btn(⬇️) then y+=1 end --down
	if btn(🅾) then a=true end--o
	if btn(❎) then b=true end--x

end

You can copy the code you find on this site, even if it uses these button glyphs, and paste it into PICO-8.


Multiplayer Games

In order to detect the button input for a multiplayer game, you will need to include the second argument for the player number.

btn( button_number, player_number )

If you understand how to use tables and loops, you can use these to help you write less code, even when you need to check for buttons of multiple players. For example, you can use a for loop to check the same button inputs for each player in one block of code:

num_players=2

for i=0, num_players-1 do
	if btn(0,i) then
		--left button pressed
		--i = which player
	end
end

One thing to keep in mind is that the player-index used in this function's second argument starts at 0, not 1. So player 1 is index 0 and player 8 is index 7. This is why the above loop starts at zero, and ends at one less than the total number of players.

Player Count 1 2 3 4 5 6 7 8
Index Number 0 1 2 3 4 5 6 7




1909

17 Oct 2023


btnp = "button pressed"

btnp( index, [player] )
index a button number or button symbol (see chart below)
player (optional) a player number (0-7)

If you hold the button down, this will only return true once because it also checks if on the last frame the button was not pressed. However, if you hold the button down for longer than 15 frames, then this resets and does return true. It will then continue to return true every 4 frames after that.

For multiplayer games, you will need to include player numbers (0-7).

These are the button indexes you can use:

Button Number Symbol
Left 0 shift+L
Right 1 shift+R
Up 2 shift+U
Down 3 shift+D
O 4 shift+O
X 5 shift+X

Custom Delay Length


You can set your own button delay by poking memory 0X5F5C like this:

POKE(0X5F5C, DELAY) 

You can set it to 255 to stop the btnp from resetting automatically at all, so that the player must release the button and press again for it to trigger again.


You can set your own repeating delay by poking memory 0X5F5D like this:

POKE(0X5F5D, DELAY)


Multiplayer Games

In order to detect the button input for a multiplayer game, you will need to include the second argument for the player number.

btn( button_number, player_number )

If you understand how to use tables and loops, you can use these to help you write less code, even when you need to check for buttons of multiple players. For example, you can use a for loop to check the same button inputs for each player in one block of code:

num_players=2

for i=0, num_players-1 do
	if btnp(0,i) then
		--left button pressed
		--i = which player
	end
end

One thing to keep in mind is that the player index used in this function's second argument starts at 0, not 1. So player 1 is index 0 and player 8 is index 7. This is why the above loop starts at zero, and ends at one less than the total number of players.

Player Count 1 2 3 4 5 6 7 8
Index Number 0 1 2 3 4 5 6 7



1379

17 Oct 2023


By default, PICO-8 does not track mouse inputs. In order to access the mouse and full keyboard inputs, you first need to enable devkit input mode with this poke:

poke( 0x5f2d, flags )

There are 3 flags that you can send with this memory poke:

Flag Result
0x1 Enable devkit mode
0x2 Mouse buttons trigger buttons (#4-6)
0x4 Mouse pointer tracking 

Warning from the Manual: "Note that not every PICO-8 will have a keyboard or mouse attached to it, so when posting carts to the Lexaloffle BBS, it is encouraged to make keyboard and/or mouse control optional and off by default, if possible. When devkit input mode is enabled, a message is displayed to BBS users warning them that the program may be expecting input beyond the standard 6-button controllers."

After enabling the devkit mode and the mouse inputs, you will need to use stat to get the mouse data for your game.

The state of the mouse and keyboard can be found in stat(x):

STAT(30) (Boolean) True when a keypress is available
STAT(31) (String) character returned by keyboard
STAT(32) Mouse X
STAT(33) Mouse Y
STAT(34) Mouse buttons (bitfield)
STAT(36) Mouse wheel event
STAT(38) Relative x movement (in host desktop pixels)
-- requires flag 0x4
STAT(39) Relative y movement (in host desktop pixels)
-- requires flag 0x4

1384

3 Apr 2024


Images in this Guide by NerdyTeachers is licensed under CC BY-SA 4.0
Font