Description

This week we begin using Pico-8, a fantasy console for making tiny games. We’ll rapidly prototype a game with sprites, sound and a map.

Class notes

PICO-8 is a fantasy console for making, sharing and playing tiny games and other computer programs. When you turn it on, the machine greets you with a shell for typing in Lua commands and provides simple built-in tools for creating your own cartridges.

Intro to Pico-8

PICO-8 is available for purchase as an app for Windows, Mac OS X, Linux (Intel), and Raspberry Pi. It also came bundled with the PocketC.H.I.P. portable computer, and works on many other handheld retro game handheld devices (such as Anbernic) and on Raspberry Pi computers. See the PICO-8 website for purchasing information.

PICO-8 intends to capture the fun and creativity of writing programs for the small personal computers of the 1980’s, without the hassles of an arcane platform. The specifications are purposefully limited so that making games is easy and fun. The console has built-in tools for creating graphics, sound, music, and code, all of which run within the console’s 128-by-128 pixel screen. You program PICO-8 using the Lua programming language.

Games are saved as cartridges (or “carts”), which are just small files that can be shared over the Internet. You can publish a cartridge to the PICO-8 forum, where anyone can play it directly in a web browser without the PICO-8 app, discuss it, and download it to examine it in the app’s tools. Publishing a cart also makes it accessible from within the app’s Splore cartridge explorer.

You can also export cartridges with a standalone player that can be embedded into any web page, suitable for commercial publication on game networks such as itch.io.

PICO-8 has an active developer community, with hundreds of games, tools, and resources for learning how to make games.

Splore

Splore is a graphical interface for exploring PICO-8 cartridges. You can use Splore to browse, search, and play cartridges published to the forum (BBS) directly over the Internet. You can also use Splore to navigate the Cartridge Storage area, with or without an Internet connection.

To activate Splore, run the splore command (or its abbreviation, s) from the PICO-8 command prompt.

Select a cartridge to run it. To return to Splore from the running cart, press the Esc key to pause the cart and display the Pause menu, then select Splore.

To return to the command prompt, press Esc from within the Splore interface.

Saving carts locally

When you select a published cartridge, PICO-8 downloads the cart, loads it into memory, and runs it. The cart is stored on your computer in a cache separate from the cartridge storage area.

To save the cart to the storage area:

While the cart is running, press Esc to pause the cart. Select Splore to return to the browse interface. Press Esc again to exit Splore and return to the command prompt. Use the save command to save the cart.

As usual, you can press Esc from the prompt to examine the contents of the cart.

Examples

> splore

> s

Pico-8 specifications

• Display
• 128 x 128 pixel resolution
• 16 colors
• Sound
• 4 channels
• 8 waveforms
• Controls
• two 6-button controllers (up, down, left, right, x, o) available from a PC keyboard
• connect up to eight 6-button controllers via SDL
• Cartridge size
  • 32 kilobytes per cartridge
  • 128 x 128 pixel sprite sheet
  • 128 x 32 tile map
  • 64 sound patterns, 64 music patterns
  • Lua code space limited by characters and tokens
• Memory
  • addressable memory regions for graphics, sound, and general use
  • separate RAM for the Lua call stack
  • 64 values (256 bytes) persistent memory per cart
  • Raspberry Pi GPIO pins mapped to memory

Getting Started

The easiest way to start playing games is to visit the PICO-8 forum in a web browser. All cartridges published to the forum can be played in a web browser without the PICO-8 app.

From the PICO-8 app or a network-connected device (such as PocketC.H.I.P.), you can use the built-in Splore utility to browse and play all carts published to the forum. Type splore at the PICO-8 prompt and hit enter.

PICO-8 includes a small set of demonstration carts built in. To access these carts, you must first run the install_demos command at the PICO-8 prompt. This creates a demos/ folder in the PICO-8 file system with carts that can be loaded, run, and edited.

You can download carts from the forum by clicking on the “Cartridge” link and saving the file. The file is a .p8.png file and appears as an image of a cartridge in a web browser. Use the folder command to open the PICO-8 file system location in your operating system’s file browser, then move the file to that location to make it accessible to PICO-8.

When you execute folder in your PICO-8 prompt, your operating system’s file browser opens a window showing the files and folders in the cartridge storage area. You can copy files in and out of this area to make them available to PICO-8.

To save a cartridge discovered within Splore, load and run the cart, hit Escape to open the pause menu, select Splore, then hit Escape again to return to the PICO-8 prompt. The loaded cart is still in memory. Use the save command to save it as a local file.

Pico-8 command prompt

The PICO-8 command prompt lets you interact with PICO-8 and the currently loaded cartridge using typed commands. By default, the command prompt is the first thing you see when starting PICO-8.

You use the command prompt to load and save cartridges, manage PICO-8 files, organize them into folders (“directories”), and perform other actions such as starting [[Splore]].

> install_demos
> load demos/jelpi
> run

For a list of available commands, see [[CommandReference]].

You can type Lua statements (such as print()) at the prompt to execute them. This is a good way to experiment with the PICO-8 APIReference and try Lua.

Note: The PICO-8 prompt only accepts commands and statements. To see the value of an expression, you must use the print() statement.

Getting back to the command prompt

When playing a cartridge, you can interrupt it and return to the command prompt by pressing the Esc key. You can enter Lua statements at the prompt to examine or change the program’s global variables. In many cases, you can use the resume command to continue the program.

If you started the cartridge from Splore, pressing Escape opens the Splore pause menu. To get to the command prompt from here, select Splore from this menu, then press Escape again.

At the command prompt, pressing Esc opens the cartridge editor interface. To return to the command prompt from here, press Esc again.

The command prompt is exclusive to the PICO-8 app, and is not available from the PICO-8 web player.

Debugging: Frame Advance

Typing a period, “.”, and hitting enter will advance your program one frame by calling _update() and then _draw(). This can be useful to test behavior from frame to frame.

Links

• Pico-8 website
• Pico-8 manual
• Pico-8 learning resources
• Pico-8 wiki
• Pico-8 API (unofficial)