Appendix
Appendix A: P8SCII Control Codes
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.
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
These commands all start with "\^" and take up to 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
d set delay to P0 frames for every character printed
g set cursor position to home
h set home to cursor position
j jump to absolute P0*4, P1*4 (in screen pixels)
r set rhs character wrap boundary to P0*4
s set tab stop width to P0 pixels (used by "\t")
u underline
x set character width (default: 4)
y set character height (default: 6)
// prefix these with "-" to disable: e.g. ?"\^i on \^-i off "
w wide mode: scales by 2x1
t tall mode: scales by 1x2
= stripey mode: when wide or tall, draw only even pixels
p pinball mode: equivalent to setting wide, tall and stripey
i invert
b border: toggle 1px padding on left and top // on by default
# solid background // off by default, but enabled automatically by \#
The following two commands take 4-character hex parameters:
@addrnnnn[binstr] poke nnnn bytes to address addr
!addr[binstr] poke all remaining characters to address addr
For example, to write 4 bytes to video memory halfway down the screen:
>?"\^@70000004xxxxhello"
Character data can be specified and printed in-line using \^. followed by 8 bytes of
raw binary data, or \^: followed by 8 2-digit hexadecimal values. The data format is
the same as custom fonts; each byte specifies a row of 1-bit pixel values, with the
low bit on the left.
\^.[8 chars of raw binary data]
\^:[16 chars of hexadecimal]
To print a cat:
> ?"\^:447cb67c3e7f0106"
. and : always render an 8x8 character with no padding. To respect the padding state,
use , and ; instead.
> ?"\#3\^;447cb67c3e7f0106"
The outline command first draws each pixel of the character in up to 8 neighbouring
positions given by an 8-bit bitfield. The bit value for each neighbour starts with low
bits at the top left, and increases in reading order:
0x01 0x02 0x04
0x08 -- 0x10
0x20 0x40 0x80
The first character after the command "\^o" is the colour, and the following two
characters are the neighbours' bitfield in hexadecimal. For example, to draw a pixel up
to the left of each foreground pixel, the value 0x01 can be used:
> ?"\^o801hey"
The following draws a blue pixel to the left, right, top and bottom of each foreground
pixel which corresponds to bits 8+16+2+64 = 90, or 0x08+0x10+0x02+0x40 = 0x5a in hex:
> ?"\f7\^oc5aoutline"
Finally, a full outline can be achieved by setting all bits. Outline works in
combination with the tall and/or wide commands but the outline is still drawn one pixel
thick:
> ?"\fe\^w\^t\^o7ffchunky"
Drawing an outline costs around twice as much cpu as drawing a non-outlined character.
The outline colour parameter can be "$" to use the current colour, or "!" to use the
current colour and skip drawing the interior.
> ?" \^o!ff empty interior"
?"\A" -- SINGLE BEEP
?"\A12" -- PLAY EXISTING DATA AT SFX 12
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:
Notes are written as a..g, optionally followed by a sharp # or flat -, and octave
number.
PRINT "\ACE-G" -- MINOR TRIAD
Empty notes can be written with a dot:
PRINT "\AC..E-..G" -- STACCATO MINOR TRIAD
Note attribute commands apply to following notes:
i P0 set the instrument (default: 5)
v P0 set the volume (default: 5)
x P0 set the effect (default: 0)
For example, to play a fast (speed 4), staccato (effect 5) arpeggio starting at C1:
PRINT "\AS4X5C1EGC2EGC3EGC4"
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 acute 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
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 128 bytes (characters 0~15 are never drawn) describe 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
0x5605 flags: 0x1 apply_size_adjustments 0x2: apply tabs relative to cursor home
0x5606 tab width in pixels (used only when alt font is drawn)
0x5607 unused
The remaining 120 bytes are used to adjust the width and vertical offset of characters
16..255. Each nibble (low nibbles first) describes the adjustments for one character:
bits 0x7: adjust character width by 0,1,2,3,-4,-3,-2,-1
bit 0x8: when set, draw the character one pixel higher (useful for latin accents)
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 stripey (when wide or tall)
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 (global tab width) values are mapped to 4..60