Introduction to PICO-8 for Raspberry Pi

PICO-8 is a fantasy console for making, sharing, and playing tiny 8-bit games. It thrives within constraints such as a limited screen size, colour palette, and code length. Why is this a good thing? Having a constrained code length means we really need to think and make decisions on what is really important to keep in the game. 

With other game engines such as Unity, you might need to work on a variety of different screen resolutions and optimise your game as such; On PICO-8, there's just the one resolution to work with, 128x128 pixels. It also includes a built-in sprite and music editor! All this creates an easy-to-learn environment that encourages small but expressive designs. 

Fancy creating your own physical PICO-8 handheld console? Pick up a Game HAT for the Raspberry Pi with its large 480x320 screen and you could play a PICO-8 game scaled at a crisp 256x256 pixels.

This guide walks you through on how to install PICO-8 on the Raspberry Pi, which will get you started with making your first game in no time.

Head to the official Lexaloffle website and click on the Download v0.1.12c button

Click on Get PICO-8

Head to the Downloads section of your new account on the website and download the Raspberry Pi version of PICO-8. To get it on the Raspberry Pi, use Chromium to download the .zip file directly to your Raspberry Pi.

Next, navigate to where the zip file is located and double-click on it. 

Go to Action > Extract

Extract its contents into the /home/pi directory

Click on the Extract button

Now open up the pico-8 folder and click on pico8!

After launching PICO-8 you should now see the console where you can type help to see a list of commands.

Simply hit the ESC key to move between the console and game editor.

PICO-8 has three special functions to create what's called a game loop. The _init() function happens only once. The other two special functions, _update() and _draw() happens in a loop until the game ends, specifically 30 times a second. What this also means is that PICO-8 games run at 30 fps by default. 

Go ahead and define these three functions in the code editor.

While it is possible to place all your code within these three functions, it is generally better to create other separate functions, then have these three run those other functions. Later, we will create a separate function to move the player sprite!

Sprites are the pieces of art that make up the game. These can be characters, tiles, backgrounds, and so on. Click on the sprite editor icon up the top right-hand corner to start drawing!

We will need sprites for the player movement. Go ahead and create walking sprites for your player sprite. 

Click on the Map Editor icon next to the Sprite Editor icon.

The map tiles use 8x8 sprites from the Sprite Editor, with a maximum map size of 128x64 pixels.

Lay out your sprites across the map!

Each PICO-8 cartridge can have up to 64 sounds, with each sound having 32 notes.

Frequency, instrument, volume, and effect can be controlled for each note.

Playback speed can be changed and you can also loop entire sections.

Using the sounds from the sound editor, you can create patterns of music in the music editor! Each pattern has four channels. It is here that you can layer and combine the sound effects to make music.

There are three controls on the top right-hand corner, two arrows and a square. These help to set patterns to stop, or loop back to a previous pattern. 

The right arrow if on, marks a start point
The left arrow marks a loop point.
If the square button is on, that marks a stop point.

The PICO-8's screen space is 128 pixels wide by 128 pixels tall. But notice how the coordinates starts at 0,0 up the top-left corner? Move right and the value of the X coordinate goes up, move down and the value of the y coordinate goes down. 

Now that we've looked at each section of the PICO-8 editor, let's start with coding our first game in PICO-8. For this game, we will get the player sprite to move across the screen. First, go ahead and create a new function and name it make_player.

Next, to add code to this function, we'll need to talk about variables and tables! A variable is a way to store information, with a name. In PICO-8, this information could be numbers, text, or the values TRUE or FALSE. For example, "x = 5", the variable is named x with a value of 5.

Tables are a way to store a lot of information all together under one variable name. When you add information, or value to a table, it gets paired with a key which can be a name or a number. This key is what you use to get the information back out of the table.

Go ahead and create a table, name it player by using empty curly braces.

Next, add keys such as player.x, player.y, player.sprite, and player.speed.

Remember to run the make_player() function in _init()!

Next, create another function and name it move

Add a new key for the player table, player.moving with a value of TRUE

Then increment the value of player.sprite by 1 with player.sprite += 1

Next, create a conditional statement such that if the player.sprite value is greater than 11, then set the player.sprite value back to 9.

Inside _update(), we'll now call the move function to animate and move the player character as well as add player controls. First, set player.moving to FALSE.

To move the player sprite, we'll use btn(0) and btn(1).

btn(0) represents the left arrow key and btn(1) represents the right arrow key. If the left arrow key is pressed, then decrement the value of player.x by player.speed. So if the player is currently at x coordinate 15, and we decremented it by the player.speed which is 1, the player's x coordinate or player.x will now be 14. Likewise, if the right arrow key is pressed, then the value of player.x is incremented by player.speed which is 1. Feel free to change the value of player.speed to increase or decrease its speed.

Next, remember to call move() after each button press to animate the player character.

If the player sprite is not moving then set it to sprite at #9, which shows the player character at idle.

Next, over in the _draw() function, first, clear the screen with cls()

Then draw the player sprite on screen with spr()

Hit the ESC key

Type save intro.p8

If a file already exists, you will be prompted to overwrite it or not. Hit the Y key to confirm overwrite.

Now to run the game, type run

We've barely scratched the surface on the wonderful tool that is PICO-8, but you now have a basic idea of how to use it and let your creativity flow. Check out the guides over at https://www.littlebird.com.au/a/how-to/#raspberrypi to learn even more. Happy coding!