Barbarian Meets Codingbarbarianmeetscoding

WebDev, UX & a Pinch of Fantasy

7 minutes readpico-8


What is PICO-8?

PICO-8 is a fantasy console to build, play and share tiny, cute games very reminiscent and evocative of the 8 bit era. What makes PICO-8 special is that it is a console and a complete game development environment all in one. PICO-8 comes with a code editor, a pixel editor, a map editor, a sound editor and a music editor, all in a single bundle of joy.

If you have a couple of minutes to spare the following video does an awesome job at explaining what’s so awesome about PICO-8:

Getting started

PICO-8 start screen. When you start the PICO-8 console the start screen looks like a terminal application and you have a cursor positioned at the start of a command prompt.

Basic shortcuts

ALT+ENTER  -- Toggle Fullscreen
ENTER / P  -- Pause Menu (while running cart)
ALT+F4     -- Fast Quit (Windows)
CTRL-Q     -- Fast Quit (Mac, Linux)
CTRL-M     -- Mute / Unmute Sound

Playing Games

  • Player 1 default keys: Cursors + ZX / NM / CV
  • Player 2 default keys: SDFE + tab,Q / shift A

Command mode

REBOOT -- reboots the console. Useful if you want to 
       -- start working on a new game.

CLS    -- cleans screen

            -- This is specially useful when saving a new game.
            -- After a game has been saved once you can just use SAVE

LOAD MYGAME -- loads your game's cartridge
SAVE        -- save game currently loaded
RUN         -- runs previously loaded game

INFO  -- Provides info about the tokens, chars and size of your
      -- game. This is specially useful if you use external tools
      -- to write your game.

KEYCONFIG  -- Open key configuration tool that lets you change 
           -- the keys used to control each player

Code Editor


CTRL-R     -- Reload / Run / Restart cartridge
CTRL-S     -- Quick-Save working cartridge

Sound Editor


  • Space - Play/stop
  • - - Go to previous sound
  • + - Go to next sound
  • < - Decrease speed of current sound
  • > - Increase speed of the current sound
  • Shift-Space - Play the current group of 8 notes
  • Shift-Click on an instrument, effect, or volume to change all notes in a sound at once
  • Tracker mode only shortcuts
    • Ctrl-Up/Ctrl-Down, PgUp/PgDn - Move up/down 4 notes at a time
    • Ctrl-Left/Ctrl-Right - Switch columns

Writing a Game for PICO-8

// TODO: describe game loop // it runs at 30 fps


Cheat Sheet by @LightBWK

Using external tools with PICO-8

Part of the beauty of PICO-8 is that you don’t need any other tool to build a game be it coding, sound, music or art other that PICO-8 itself. But if you still want to use your favorite code editor, art tool, etc you can do it. PICO-8 files mygame.p8 can be opened in any text editor.

Open a p8 file and you’ll see that it is subdivided in sections, one for each part of the game

pico-8 cartridge //
version 32
// here goes the game code
// here go the sound and music

If you start changing your game’s code under the lua section you’ll see that when you load your cartridge within the PICO-8 console your code updates are there. This naive approach can work but you won’t have the ability to separate your code in tabs and might struggle with syntax highlighting. A better approach is to take advantage of lua imports to include an external lua file from the game #include main.lua:

pico-8 cartridge //
version 32
// here goes the game code
// Now we can write our game on main.lua and take advantage of your favorite
#  text editor
#include main.lua
// Note that PICO-8 doesn't support nested imports. So we'll need to import
// all of our lua files from here.
#include player.lua
// you can also use folders to group things
#include entities/monster.lua
#include entities/weapon.lua
#include engine/physics.lua
#include engine/combat.lua
#include scene/splash.lua
#include scene/credits.lua
#include scene/game.lua
// it's specially helpful to group things you can reuse
// between games
#include utilities/animation.lua
#include utilities/audio.lua
#include utilities/logging.lua
// here go the sound and music

When you’re using an external code editor the built-in token counter doesn’t work. Use the INFO command from the command mode to get an accurate count.

You can log information outside of PICO-H by using the printh function:

printh('log this text', -- what to log
      'logfilename',  -- file to log things to
      false)  -- this boolean decides whether to clean the file when logging

-- when this function is called it'll log 'log this text' into a filename
-- called logfilename.p8l
-- you can use tail -f logfilename to see things being logged as they happen

This is a great video that illustrates all of the above:


Jaime González García

Written by Jaime González García , Dad, Husband, Front-end software engineer, UX designer, amateur pixel artist, tinkerer and master of the arcane arts. You should follow him on Twitter where he shares useful stuff! (and is funny too).Jaime González García