Barbarian Meets Coding
barbarianmeetscoding

WebDev, UX & a Pinch of Fantasy

13 minutes readpico-8draft

PICO-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

When you start the PICO-8 fantasy console you see a satisfying start screen followed by an evocative ti-di-Di-DI sound and a command line.

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.

You’re in the PICO-8 command mode, here you can type different commands to either start developing your game or playing any game available for the PICO-8 fantasy console. Type splore and you’ll be brought to a kind of marketplace with thousands of games to peruse and play. Let’s wait with that for now and focus on the game development aspects of PICO-8.

Type:

-- Type this using lowercase letters, PICO-8 uses a delicious
-- 8-bit typeface that although hard to read some times fits 
-- perfectly into the aesthetics of the console.
PRINT("HELLO WORLD")

And you’ll see that the HELLO WORLD string appears in the console.

The command mode in PICO-8 acts like a REPL where you can experiment directly with any code that you’d want to use in an actual game.

Try the following:

--CIRCFILL(X,Y,RADIUS,COLOR)
CIRCFILL(20,20,15,14)

And a pink circle will appear on the screen.

This is not, however, how you’ll normally write a game in PICO-8, nope. You’ll use a full-fledged text editor built right into PICO-8. Type ESC and you’ll be magically transported from the command mode into editor mode.

PICO-8 editor screen. When you type ESC from command mode you jump into this tiny cute editor.

As it happens with many game engines a game is an infinite loop of gathering user input an then updating the game universe and drawing it to the screen for the player to see and interact with. This infinite loop is represented in PICO-8 by three functions:

  • _INIT where you initialize your game (only runs once at the beginning)
  • _UPDATE where you listen for user input and update the state of the game universe
  • _DRAW where you draw your game universe in the screen

A simple game to move a pink circle around the screen would look like this:

-- this example is straight out of the PICO-8 user manual
-- https://www.lexaloffle.com/dl/docs/pico-8_manual.html#_Hello_World
X = 64  Y = 64
FUNCTION _UPDATE()
  IF (BTN(0)) THEN X=X-1 END
  IF (BTN(1)) THEN X=X+1 END
  IF (BTN(2)) THEN Y=Y-1 END
  IF (BTN(3)) THEN Y=Y+1 END
END
 
FUNCTION _DRAW()
  CLS(5)
  CIRCFILL(X,Y,7,14)
END

Once you’ve created your game, or as soon as you want you can save it:

SAVE MYCIRCLEGAME

And run it:

RUN

// TODO: add GIF

From then on you can jump between coding and playing by using ESC (to return to the editor) and ESC and RUN to run the cartridge (or alternatively CTRL-R to run the cartrige from the editor)

Let’s make our game more exciting by changing the circle for an actual character. From the code editor we can jump into the pixel art editor by typing ALT+RIGHT (or clicking on its icon with the mouse)

// TODO: Add image

Now we can go back to the editor with ALT+LEFT and update our _UPDATE function to draw the sprite.

Writing a Game for PICO-8

// TODO: writing an actual game can be part of a tutorial and not these notes // TODO: describe game loop // it runs at 30 fps // one can activate 60 fps

Learning PICO-8

Here some great guides to help you learn PICO-8:

  • The PICO-8 user manual has lots of information about PICO-8 features and APIS and is written in a tutorial format.
  • Game development in PICO-8 is a small book on game development in PICO-8 that teaches you through the process of building 2 small games.
  • You can learn from the community of PICO-8 creators by loading games via SPLORE and typing ESC to access their source code, art and music.
  • The PICO-8 console comes with a bunch of demo games that you can peruse for your own learning. In command mode type INSTALL_DEMOS to create a DEMOS directory with a bunch of small demos illustrating different features of PICO-8. For example, to access a demo of most APIs in PICO-8 type:
    • INSTALL_DEMOS
    • CD DEMOS
    • LOAD API
    • RUN to run the demo
    • ESC to look at the source code and art

Splore and playing with PICO-8

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

More about command mode

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

CLS    -- cleans screen

SAVE MYGAME -- saves MYGAME.
            -- 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

INSTALL_DEMOS  -- Installs playable PICO-8 demos that showcase different
               -- features in PICO-8

Common Shortcuts

ALT+ENTER          -- Toggle Fullscreen
ESC                -- Toggle between console and editor.
ALT+LEFT/ALT+RIGHT -- Jump between editors (code, sprites, tiles, etc...)

Code Editor

Shortcuts

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

Sound Editor

Shortcuts

  • 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

More 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

Screenshots and GIFS

CTRL-6 -- Save a screenshot to desktop
CTRL-7 -- Capture cartridge label image
CTRL-8 -- Start recording a video
CTRL-9 -- Save GIF video to desktop (8 seconds by default)

-- To configure GIF length use (max 120 seconds)
CONFIG GIF_LEN 60

Cheatsheet

Cheat Sheet by @LightBWK

PICO-8 Standard Library

Tables

  • COUNT(table): Returns number of elements in a table
  • COUNT(table, item): Returns number of instances of item in a table

Debugging and Troubleshooting

Logging

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

Inspecting variables

When working on your game there may be times when you run into issues and don’t know what’s the culprit. When that occurs a useful way to debug the problem is to:

  1. Use a STOP() instruction in your pico game
  2. This will stop the game at the expected time of the issue
  3. Now in command mode you can inspect the values of variables (e.g. PRINT(P.X)), to resume the game type the RESUME command.

Token optimization

Cartriges in PICO-8 are limited to 8192 tokens. A token in PICO-8 is defined as follows:

Each token is a word (e.g. variable name) or operator. Pairs of brackets, and strings each count as 1 token. commas, periods, LOCALs, semi-colons, ENDs, and comments are not counted.

It may happen during the development of your game that you’ll reach this limit. These are some heuristics to reduce the number of tokens:

  • DRY. Don’t repeat yourself. Extract duplicated code into functions or variables.
  • Declare multipe variables within the same line:
    • x=10 y=20 are 6 tokens, whereas x,y = 10,20 are 5 tokens

Bear in mind that many of these techniques reduce the number of tokens while reducing the readablity of the code which may not be justified unless you really need those extra tokens.

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.

This is a great video that illustrates all the content in this section (refer to the text below if you want a summarized version).

Coding PICO-8 games in a external text editor

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 // http://www.pico-8.com
version 32
__lua__
// here goes the game code
__gfx__
// 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 // http://www.pico-8.com
version 32
__lua__
// 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
__gfx__
// 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.

Working on your pixel art outside of PICO-8

To work on pixel art using a different art tool than the one built-in with PICO-8:

  1. Export your spritesheet running EXPORT {MY-GAME}-SPRITESHEET.PNG (this will include all your sprites and map tiles)
  2. Make your changes
  3. Import your spritesheet running IMPORT {MY-GAME}-SPRITESHEET.PNG

If you use the extended palette in PICO-8 there’ll be some colors that won’t match the initial 16 colors of a PICO-8 game. To get around that you need to create and load a new palette than matches your games palette, and make sure to setup your spritesheet to use an indexed palette.

Resources

Jaime González García

Written by Jaime González García , dad, husband, software engineer, ux designer, amateur pixel artist, tinkerer and master of the arcane arts. You can also find him on Twitter jabbering about random stuff.Jaime González García