P8SCII

P8SCII is PICO-8's 8-bit character set. It includes 19 control codes and 237 printable characters. All characters and codes can appear in string literals using typed characters or escape sequences (such as \n for a newline code). The chr() function takes a character number and returns a one-character string with the corresponding P8SCII character.

Printable characters

Printable characters 32-127 match the ASCII standard. Several control codes in the range 0-15 also match ASCII terminal control codes. Other control codes do PICO-8 specific things. (See below.)

Characters 128-153 and 254-255 are graphical symbols proprietary to PICO-8.

Characters 154-203 are the Japanese Hiragana alphabet, and characters 204-253 are the Japanese Katakana alphabet. Japanese characters appear in alphabetical order, followed by the four digraph indicators. Japanese diacritics and punctuation can be found in characters 24-31.

P8SCII range 65-90 appear as lowercase (small-caps) English letters when printed. The uppercase letters normally used by PICO-8 are P8SCII range 97-122 (ASCII lowercase).

When printed, characters 128-255 are eight pixels wide, not four.

Control code sequences

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").

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