Appendix A

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 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-grey foreground ("\f5"):

PRINT("\#C\F5 BLUE ")

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

Control Codes

code	description
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 up to 2 parameters (P0, P1) For example, to clear screen to dark blue: print("\^c1")

command	description
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 P04, P14 (in screen pixels)
r	set rhs character wrap boundary to P0*4
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"

command	description
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 \#

Raw memory writes

The following two commands take 4-character hex parameters:

command	description
@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"

One-off characters

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"

Audio

?"\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:

   attributes	description
   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

   Empty notes Can be written with a dot:

   PRINT "\AC..E-..G" -- STACCATO MINOR TRIAD 

   Note attribute commands apply to following notes:

   attributes	description
   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"

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 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

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: | address | description | | 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

  value	description
  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 values are mapped to 4…64