PICO-8 Wiki

PICO-8 maintains a set of variables that affect how the drawing functions work. For example, it remembers the current "pen color," and when you call functions such as circ() or print() without the optional color parameter, it uses the current pen color. The pen color is changed whenever you provide a color parameter to a draw function, and you can change it directly by calling the color() function.

A typical use of the draw state is to use the same feature for a series of related consecutive draw calls. For example, to draw a the cockpit of a spaceship, the game can call clip() to set the clipping region for the window, call draw functions for the objects outside the window, then call clip() again to set the clipping region for the cockpit controls, and so on.

The following features are stored in the draw state and affect how graphics features work:

Feature Description Changed by
Pen color The default color. Used by functions that accept an optional color argument when the argument is not provided or nil. color(); providing a color argument to a drawing function
Camera position A position offset. Modifies the position of all functions that take position arguments (x, y). camera()
Print cursor position The default position for the next call to print() without position arguments. Such a call advances the cursor's y position by 8 pixels. If the cursor advances below the bottom of the screen, the screen scrolls. The cursor's x position can only be changed by cursor() and establishes a left margin. cursor(); advanced by print()
Clipping region Limits the drawable region to a portion of the screen. Subsequent calls to draw functions will not draw outside this area even if they extend beyond the edge. clip()
Palette modifications Filters drawing so that some colors are replaced with others. There are two palettes: one used when a drawing to the graphics buffer for a specific draw call (including spr()), and one used when copying the graphics buffer to the screen (for full-screen effects). pal(), palt()
Fill pattern Specifies an alternate two-color pattern to use for some drawing functions. Both 4-bit colors can be specified in the low and high bits of the color value passed to the drawing function. Alternatively, the fill pattern can set one of its colors to transparent. fillp()

The draw state is stored in the addressable memory region 0x5f00-0x5f3f. This is useful if you want to save and restore the current draw state by copying the memory region with memcpy().