What is PICO-8?
For those unfamiliar with PICO-8 - it’s a fantasy console for making, sharing and playing tiny games and other computer programs. You could think of a “fantasy console” as an emulator for a games console that never actually had a physical hardware release.
PICO-8 is basically attempting to be recreate the spirit of an 8-bit games platform - with all its limitations (128x128 resolution, 16-cols, 32k, etc.) - but with a few exceptions that take advantage of newer/modern technology (such as Lua scripting, built-in code/sprite/map/sfx/music editors, powerful exports).
Just like old consoles, PICO-8 uses Cartridges (or Carts, for short) for storing and sharing games and programs. These single files can even be saved as .PNG (image) files, containing ALL the source code and resources! Making them VERY easy to share to other PICO-8 users.
What this essentially means, is that PICO-8 is pretty much a self-contained game engine, with all the tools necessary to create wonderful “retro”-style games (that also can be exported to Web, Windows, Mac and Linux).
PICO-8 is a commercial application ($14.99) and available for Windows, Linux, Mac, and Raspberry Pi builds.
The good news is that the Raspberry Pi build has been successfully used with the GameShell (with some set-up - please see this thread for more information on the steps required). This means that, with the use of a Bluetooth keyboard - it should be possible to do PICO-8 development on the go!
First boot
Once you’ve installed PICO-8 and turn it on, the machine greets you with a boot-up sound and command line - just like an “old school” computer.
NOTE: If you see a menu screen, instead of the flashing cursor - it means you are in SPLORE mode, which is PICO-8’s cart menu system for browsing games. To exit, either press ESC on the keyboard (if you have one connected) or MENU on GameShell then “EXIT TO CONSOLE” to get to the console.
You can type commands directly into the console, just like the good old days.
For example, if you type:
CLS
…and press ENTER, it will clear the screen.
(NOTE: No need to type in capitals, PICO-8 characters are capital by default)
Now type (and press ENTER):
CIRCFILL(64,64,30,12)
…to draw a big blue Circle in the middle of the screen.
PICO-8 has a whole list of commands (API) available for performing various game-related tasks, such as drawing, audio, input, etc. - which we will use progressively over the course of this tutorial series.
Now, typing individual commands is ok, but unlike those limited computers of yesteryear, this is the 21st Century - pressing ESC switches to the “Editor” mode… which gives you considerably more power!
Editors
The first editor window you’ll see is the Code editor.
There are many editors in PICO-8 (Code, Sprite, Map, SFX, Music), but we’ll focus on just the Code editor for this tutorial.
The Code editor is where you will write all of the code for your game.
Here you can define functions and variables, and even organise your code up across multiple tab pages. PICO-8 uses the Lua syntax for development (although it does not use the full library). If you are not already familiar with the Lua scripting language, it’s quite similar to BASIC syntax, and is nice and easy to learn.
Let’s start writing our first PICO-8 cart!
Hello World!
Carts in PICO-8 need to have three main functions: _INIT(), _UPDATE() and _DRAW().
Everything else in your game code will be called from one of these three functions.
-
_INIT()- Called once, at the start of execution.
- Allows you to initialise your variables, data, etc.
-
_UPDATE()- Called every frame, 30 frames per second (fps)
- (It is also possible to run at 60 fps - but that’s for another tutorial!)
-
_DRAW()- Called every frame.
So, let’s write out (or copy+paste) our first PICO-8 program:
-- PICO-8 GAMEDEV #1
-- GETTING STARTED
FUNCTION _INIT()
MSG="HELLO PICO-8"
X=40 Y=64
DX=1 DY=1
END
FUNCTION _UPDATE()
X+=DX Y+=DY
IF X<1 OR X>128-#MSG*4 THEN
DX*=-1
ELSEIF Y<1 OR Y>127-5 THEN
DY*=-1
END
END
FUNCTION _DRAW()
CLS(1)
PRINT(MSG,X,Y,8+DX+DY)
END
If you’ve entered everything correctly - you can now run the program to see the results:
- Press ESC to switch back to the Console,
- Then type the RUN() command.
You should see the message bouncing around the screen!
TIP: You can also Run by pressing CTRL+R (⌘+R on Mac) keyboard shortcut.
Save Your Work!
Before we explore the code in more detail - it is always important to save your work!
You can do this by:
- Pressing ESC, to stop your program and exit back to the Console.
- Then using the SAVE() command, followed by the filename.
For example:
SAVE HELLO-WORLD
When you do this, PICO-8 will create a .P8 cart file with your chosen filename.
This is the standard file format for all PICO-8 program files, and is a plain text format that can also be opened and modified in other text editors, but for now - let’s stick to the PICO-8’s Code editor.
Hello World - Code Explained
Let’s take a line-by-line look at what you just wrote, and explain exactly what each command is doing…
-- PICO-8 GAMEDEV #1
-- GETTING STARTED
Two dashes “--” in Lua is a line Comment, which means that any characters after the dashes will be ignored by PICO-8 for the rest of that line. Using comments as the first two lines are particularly important when it comes to exporting your program carts (we’ll get to that later!).
Now let’s look at the code again, but this time - with in-line comments…
-- THIS IS OUR INIT FUNCTION, WHICH WILL BE CALLED ONCE AT THE START
FUNCTION _INIT()
MSG="HELLO PICO-8" -- CREATE A VARIABLE "MSG" AND ASSIGN IT SOME TEXT
X=40 Y=64 -- CREATE TWO MORE VARIABLES TO STORE OUR X AND Y POS
DX=1 DY=1 -- TWO MORE VARS TO STORE X AND Y DIRECTIONS (+/-)
END
-- THIS IS OUR UPDATE FUNCTION, WHICH WILL BE CALLED EVERY FRAME
FUNCTION _UPDATE()
-- MOVE THE CURRENT X & Y IN THE CURRENT DIRECTION (+/-)
X+=DX Y+=DY
-- IF THE TEXT X POSITION IS ABOUT TO GO OFF THE SCREEN
-- (WE CALCULATE THE RIGHT-SIDE BASED ON THE LENGTH OF "MSG")
IF X<1 OR X>128-#MSG*4 THEN
-- FLIP THE X DIRECTION
DX*=-1
-- ELSE IF TEXT Y POSITION IS ABOUT TO GO OFF THE SCREEN
-- (WE -5 FOR THE BOTTOM CHECK AS TEXT IS 5PX HIGH)
ELSEIF Y<1 OR Y>127-5 THEN
-- FLIP THE Y DIRECTION
DY*=-1
END
END
-- THIS IS OUR DRAW FUNCTION, WHICH WILL BE CALLED EVERY FRAME
FUNCTION _DRAW()
-- CLEAR THE SCREEN USING COL 1 (DARK BLUE)
CLS(1)
-- DRAW THE STRING CONTENTS OF "MSG" TO THE SCREEN AT POS X,Y
-- (THE LAST PARAMETER IS THE COL TO USE - HERE WE'RE USING A
-- COMBINATION OF THE DIRECTION VALUES AND AN OFFSET OF 8 TO
-- GET A NICE SELECTION OF COLOURS EVERY TIME THE DIR CHANGES)
PRINT(MSG,X,Y,8+DX+DY)
END
Summary
This tutorial was your first step into PICO-8 game development.
In this lesson, you:
- Purchased, Installed and ran PICO-8.
- Learned how to use the Console to execute basic commands.
- Learned about PICO-8’s main game loop functions.
- Used the Code editor to create your first PICO-8 program.
Further Exercises
If you want experiment more with PICO-8, here’s some extra things you try:
- Try changing the value of the
MSGvariable - see how it affects the program. - Try playing with the colours being used to draw the message, as well as to clear the screen - there are 16 available.
- Try commenting out the line
CLS(1)and see what happens!
NEXT: Part 2 of my PICO-8 GameDev tutorial series is now available!
I hope you enjoyed this tutorial, and if you did - please let me know. 
For more information about me & the games I’ve made, please visit my website or Twitter.
)
Thanks for such a great tutorial! 
