Print

print( text, [x,] [y,] [color] )

Prints a string of characters to the screen.

text

The Lua string of characters to print.

x

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

y

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

color

The color to use for the text.

return-value

The x coordinate of the next character to be printed (can be used to calculate printed width)

The print function writes a line of text to the screen using the PICO-8 font, and then moves the cursor to the start of the next line. To write multiple lines in one call, insert one or more newline characters ('\n') in the text.

If only the text argument is supplied, print() uses the cursor position and draw color from the current draw state to determine where to draw the text, and what color to use.

Unless specific x and y position coordinates are supplied, print() behaves like a retro text-based scrolling display. The text is rendered to the screen and then the cursor moves to the left margin on the next line, as if text had a hidden newline character at the end. If there isn't enough room to have another line on the screen, the screen scrolls upwards to make enough.

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

The three additional arguments are all optional, and can be supplied in three ways:

If there is only one additional argument, it is assumed to be the color argument. The text is printed in the same manner as above, but in the given color. This also changes the current draw color of the draw state.

print('press x to start', 7)         -- white

If there are two additional arguments, they are assumed to be the x and y arguments, which are used as the upper left corner of the rectangle containing the text. The current draw color of the draw state is used, and the current draw position and left margin are set accordingly.

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

If there are three additional arguments, they are assumed to be the x, y and color arguments. The text is printed in the same manner as when there are just x and y, but using the given color instead of the one in the draw state.

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

The print() function is especially useful at the PICO-8 command prompt. After interrupting a running program by pressing Esc, global variables and functions that were created while running are available to any code that is entered on the command line.

To see the value of a variable, or even a full expression, run the print() function on the command line like this:

> print(player.x)
42
> print(player.hp / player.maxhp)
0.75

Shorthand form

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

-- print the player x position just inside the upper left corner, in red
print(player.x,2,2,8)

-- print the player y position to the right of the x position, in green
?player.y,32,2,11

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

> ?player.x
42

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.

Character size and screen capacity

Each character in the PICO-8 system font appears to be 3 pixels wide and 5 pixels tall, but the font includes a 1-pixel wide gap on the right, and a 1-pixel-tall gap on the bottom, so the final size is actually 4 pixels wide and 6 pixels high.

At this font size, 32 characters can fit on a single line (128 pixels / 4 pixels per character), and slightly more than 21 lines (128 pixels / 6 pixels per line) can fit on the screen.

Some characters are double-width, or 8 pixels. The ord() function may be used to get a character's ordinal number, which can be checked to see if it is less than 128. If it is, it is 4 pixels wide, otherwise it is 8 pixels wide. The control codes in characters 0..15 are exceptions to this rule, and may or may not advance the cursor, or may advance the cursor using a special algorithm, such as the '\t' "advance to next tab stop" character.

Technical notes

• If text is too wide to fit on the screen, it does not wrap to the next line by default during game execution. Instead, it is clipped at the right side of the screen. For print() calls without explicit x, y arguments, character-level wrapping may be enabled by setting bit 7 of memory address 0x5f36 (see Memory for details) and the wrapping boundary may be controlled with the \^r control sequence. Word-level or other wrapping must be done by the code that calls print().

• Whenever the cursor position gets close enough to the bottom of the screen that the bottom of new text would be cut off, the entire graphics display is shifted up by enough pixels to make room for a new line of text. This simulates the kind of scrolling-text mode that retro computers had. This behavior may be disabled by clearing bit 6 of memory address 0x5f36 (see Memory for details).

• The camera offset is observed.

• The clipping region is observed, but is not used for positioning.

• The scrolling functionality may have unusual behavior when either a clipping region or a camera offset is in effect, so be sure to test such code thoroughly.

Examples

-- 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
cls()

-- 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
cursor()
color(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) 
end

print_centered('you win!')

See also

• Graphics
• Draw state
• Strings
• cls()
• color()
• cursor()