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.
Given only a Lua string,
print() behaves like a scrolling display of text.
print('you are standing at the end of') print('a road before a small brick') print('building.')
print('press x to start', 32, 60)
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(player.x) 42
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
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.)
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(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.
-- 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!')