PICO-8 Wiki

When printed with print(), some characters have a special meaning that can be used to alter things like the cursor position and text rendering style. Control characters in PICO-8 are CHR(0)..CHR(15) and can be written as an escaped sequence ("\n" for newline etc.)

Some of the control codes below take parameters which are written using a scheme that is a superset of hexadecimal format. That is, '0'..'f' also mean 0..15. But characters after 'f' are also accepted: 'g' means 16 and so on. Such parameters are written below as P0, P1.

For example, to print with a blue background ("\#c") and dark gray foreground ("\f5"):

print("\#c\f5 blue ")

The only side-effects on the draw state are changes in cursor position and foreground color; all other attributes are reset each time print() is called.

Control Codes[]

0 "\0"   terminate printing
1 "\*"   repeat next character P0 times. ?"\*3a" --> aaa
2 "\#"   draw solid background with colour P0 
3 "\-"   shift cursor horizontally by P0-16 pixels
4 "\|"   shift cursor vertically by P0-16 pixels
5 "\+"   shift cursor by P0-16, P1-16 pixels
6 "\^"   special command (see below)
7 "\a"   audio (see below)
8 "\b"   backspace
9 "\t"   tab
a "\n"   newline
b "\v"   decorate previous character (see below)
c "\f"   set foreground colour
d "\r"   carriage return
e "\014" switch to font defined at 0x5600
f "\015" switch to default font

Special Commands[]

These commands all start with "\^" and take between none and 2 parameters (P0, P1) For example, to clear screen to dark blue: print("\^c1")

	1..9 skip 1,2,4,8,16,32..256 frames		
	c cls to colour P0, set cursor to 0,0
	g set cursor position to home
	h set home to cursor position
	j jump to absolute P0*4, P1*4 (in screen pixels)
	s set tab stop width to P0 pixels (used by "\t")
	x set character width  (default: 4)
	y set character height (default: 6)

Rendering Mode Options[]

	// prefix these with "-" to disable: e.g. ?"\^i on \^-i off "

	w wide mode: scales by 2x1 
	t tall mode: scales by 1x2
	. dotty mode: when wide or tall, draw only even pixels
	p pinball mode: equivalent to setting wide, tall and dotty
	i invert
	b border: toggle 1px padding on left and top // on by default
	# solid background  // off by default, but enabled automatically by \#


Audio[]

?"\a"   -- single beep
?"\a12" -- play existing data at sfx 12 (the index is written in decimal)

If an sfx index is not specified, a non-active sfx between 60..63 is selected automatically. To fill the SFX with data before playback, the following commands can then be appended.

1. (optional) SFX attributes must appear once at the start as they apply to the whole sound:

s P0     set the sfx speed
l P0 P1  set the sfx loop start and end points

2. Note data: Note are written as a..g, optionally followed by a sharp # or flat -, and octave number.

	print "\ace-g" -- minor triad

Note attributes apply to allow following notes. Adjust with:

	i P0    set the instrument (default: 5)
	v P0    set the volume     (default: 5)
	x P0    set the effect     (default: 0)
	<  >   increase or decrease volume by 1 

For example, to play a fast (speed 4), staccato (effect 5) arpeggio starting at C1:

	print "\as4x5c1egc2egc3egc4"

Decoration Characters[]

The control character \v can be used to decorate the last printed character with another character at a given offset, without needing to otherwise manage the cursor position. After the decorating character is printed, the previous cursor position is restored.

The format is \v P0 char, where P0 is a number giving the desired offset, and char is any character to print at that offset (relative to the previous printed character).

The offset has x packed into the lowest 2 bits, and starts (-2,-8) in reading order. So 3 means (+1, -8), 4 means (-2, -7) and so on.

For example, to write "café!", using a comma to draw the accute accent:

print"\ncafe\vb,!"

In this case P0 is 'b', which is read as the number 11. So the comma is drawn at:

x = (11%4)-2 = 1
y = (11\4)-8 = -6

Custom Font[]

A custom font can be defined at 0x5600, consisting of 8 bytes per character * 256 characters = 2048 bytes. Each character is an 8x8 bitfield (1 bit/pixel), where starting from the top, each row is a single byte starting with 0x1 on the left.

The first five bytes (character 0 is never drawn) describes attributes of the font:

0x5600 character width in pixels (can be more than 8, but only 8 pixels are drawn)
0x5601 character width for character 128 and above
0x5602 character height in pixels
0x5603 draw offset x
0x5604 draw offset y


Default Attributes[]

Although attributes are reset every time print() is called, it is possible to set their default values by writing to memory addresses 0x5f58..0x5f5b.

0x5f58 // bitfield
	0x1  when set to 0x1, bits 1..7 are observed:
	0x2  padding
	0x4  wide
	0x8  tall
	0x10 solid background
	0x20 invert
	0x40 dotty
	0x80 use custom font

	// e.g. poke(0x5f58, 0x1 | 0x2 | 0x4 | 0x8 | 0x20 | 0x40)  -- pinball everywhere

0x5f59 char_w   (low nibble), char_h   (high)
0x5f5a char_w2  (low nibble), tab_w    (high)
0x5f5b offset_x (low nibble), offset_y (high)

// any nibbles equal to 0 are ignored
// tab_w values are mapeed to 4..64