Clipboard

PICO-8 allows access to the system clipboard, both through its editors and with Lua code.

Reading the clipboard with Lua

The system clipboard contents can be found using stat(4), as a string:

print('clipboard: '..stat(4))

Caveat: Initially, stat(4) will return a blank string, even if there is data already on the system clipboard. The clipboard contents will only update under one of these conditions:

• The user presses the "paste" key sequence while Lua code is actively running. This is either Control-v (Windows, Linux) or Command-v (Mac OS X).
• A string is written to the clipboard by Lua inside the current PICO-8 instance.

This is to prevent a cartridge from accessing potentially-sensitive data on the host system's clipboard without the user's permission.

Writing to the clipboard with Lua

A string may be written to the system clipboard with printh(), so you can paste it into another program interactively. To do this, provide a filename of '@clip':

printh('collision data: xpos='..xpos..' ypos='..ypos, '@clip')

Each call to printh(..., '@clip') completely replaces the contents of the system clipboard with the given string. There is no way to append the string to the existing contents. As such, you must use the existing clipboard contents before the next call to printh(..., '@clip').

NOTE: It is necessary to press CTRL+V in the Pico-8 task you have open in order to PASTE the clipboard's contents to that task so it may be read by STAT(4). You must do this each time now.

Editor clipboard formats

The sprite editor reads and writes rectangular image data to the clipboard, formatted as a string of hexadecimal characters, like so:

[gfx]WWHHPPPPP...PPP[/gfx]

With:

• WW = width in hex (01..80, or 1..128 in decimal)
• HH = height in hex (01..80, or 1..128 in decimal)
• P = pixel in hex (0..f, or 0..15 in decimal)

There should be WW * HH pixels encoded in the string.

When creating strings to for pasting into the sprite editor, be aware that newlines and any other characters that are not hexadecimal values will be treated as "0" (black) pixels.