print( str, [x,] [y,] [col] )
Prints a string of characters to the screen.
The string of characters to print.

The x coordinate of the upper left corner to start printing.

The y coordinate of the upper left corner to start printing.

The color to use for the text.

The print function writes text to the screen using the PICO-8 font.

Given only a Lua string, print uses the cursor location and draw color of the current draw state. The cursor position is moved to the next line, potentially scrolling the entire display up by a line. This form of print() behaves like a scrolling display of text.

print('you are standing at the end of')
print('a road before a small brick')

Given x and y coordinates, print uses the given coordinates as the upper left corner of the rectangle containing the text.

print('press x to start', 32, 60)

If the col argument is provided, the message is printed in the given color. This changes the draw color of the draw state.

print('press x to start', 32, 60, 7)

Each character of the PICO-8 font is 4 pixels wide and 6 pixels high. At this size, 32 characters can fit on a single line (128 pixels / 4 pixels per character). If the string is too long to display at the given coordinates, it is clipped, similar to other draw operations. (The string does not wrap to the next line.)

print() is especially useful at the PICO-8 command prompt. When you interrupt the program by pressing escape, the global variables and functions of the cartridge are available to expressions you type. To see the value of these expressions, you use the print() function.

> print(player.x)

Cursor positioning and scrolling Edit

When you call print() with only a string, the message is printed at the current cursor position, and the cursor is moved to the next line. Specifically, the cursor position advances to the next line: y = y + 6. The cursor's x position is unchanged from its original value, as if it were the left margin of a series of print() calls.

If the cursor's new y position is less than 6 pixels from the bottom of the screen, the entire graphics display is shifted up by six pixels after the string is printed, producing a scrolling display effect.

Note: The scrolling effect only occurs when the cursor position reaches the bottom of the physical display (y > 128). It ignores the clipping region. It honors the camera offset. The scroll effect has unusual behavior when a clipping region or camera offset are in effect. It is probably best to avoid using scrolling print() in combination with a clipping region or camera offset.

Printing at coordinates Edit

When given explicit coordinate arguments, print() uses those coordinates as the upper left corner of the rectangle where the text appears.

In this case, the draw state's cursor position is set to the given coordinates, and remain there after the message is printed. The cursor is not relocated to the next line of text. (This is not particularly useful, just a side effect of how it is implemented.)

Newlines Edit

Without coordinates, there is an implied newline at the end of your string. You may also include additional newline characters ("\n") in your string to draw several lines of text with a single call. The screen will scroll as needed.

With coordinates, there are no automatic newlines, only those you place in the string yourself. Also, there is no scrolling if you try to render text outside of the visible area. Aside from that, newlines still behave as expected.

Shorthand form Edit

PICO-8 provides a BASIC-like "?" shorthand for print(). Here is an example showing the normal method and the shorthand method:

-- print the player x position just inside the upper left corner, in red
-- print the player y position to the right of the x position, in green

This shorthand is intended mostly for quick evaluation of variables at the command line:

> ?player.x

However, it does work in source code and can be used to save a few tokens in dire situations. The only requirement is that it must be alone on a line. Also keep in mind that this shorthand form is not as readable as the function call.

Examples Edit

-- print a score display at the bottom of the screen in red
score = 1234
print('score: '..score, 0, 120, 8)

A demonstration of cursor positioning and scrolling:

-- clear the screen and reset the cursor position
-- print "try this" at the center of the screen
print('try this', 46, 60, 8)
-- reset the cursor to (0, 0) and the color to 7
print('one')  -- prints "one" in the upper left corner, advances cursor
print('two')  -- prints "two" on the line below "one", advances cursor
print('three', 16, 16)  -- prints "three" at (16, 16), sets cursor
print('four')  -- prints "four" on top of "three", advances cursor
print('five')  -- prints "five" on the line below "four", advances cursor
print('six', 0, 112)  -- prints "six" on the second-to-last line, sets cursor
print('seven')   -- prints "seven" on top of "six"
print('eight')   -- prints "eight" on the last line, then scrolls up by 8 pixels

A function that prints a message at the center of the screen:

-- 64 is half of the screen width (128 / 2). To calculate the x
-- coordinate, the length of the string is multiplied by half
-- of the character width (4 / 2), then subtracted from 64.
-- Similarly, the y coordinate is 60 = 64 - (8 / 2).
function print_centered(str)
  print(str, 64 - (#str * 2), 60) 
print_centered('you win!')

See also Edit

Community content is available under CC-BY-SA unless otherwise noted.