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)
TODO: Update for Picotron's specifics

The `print` function writes a line of text to the screen using the Picotron 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

Picotron 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 Picotron system font appears to be 4 pixels wide and (TODO: possibly?) 8 pixels tall, but when printed, there is a 1-pixel wide gap on the right, and there is possibly a gap (TODO: above and below?) every character so that columns are 5 pixels wide and rows are 12 pixels tall.

At this font size, 96 characters can fit on a single line (128 pixels / 4 pixels per character), and somewhat more than 22 lines (270 pixels / 12 pixels per line) can fit on the screen.

Some characters are wider, at 7 pixels with a 4-pixel gap on the right. 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 5 pixels wide, otherwise it is 11 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

TODO: verify whether these are still true

* If text is too wide to fit on the screen, it does *not* wrap to the next line. Instead, it is clipped at the right side of the screen. There is no auto-wrap functionality; if wrapping is needed, it 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.

* 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, 252, 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', 215, 129, 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, 240)  -- 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:

```
-- 240 is half of the screen width (480 / 2). To calculate the x
-- coordinate, the length of the string is multiplied by half
-- of the character width (5 / 2), then subtracted from 480.
-- Similarly, the y coordinate is 129 = 135 - (12 / 2).
function print\_centered(str)
  print(str, 240 - (#str \* 2.5), 129)
end

print\_centered('you win!')

```

## See also

* Graphics
* Draw state
* Strings
* `cls()`
* `color()`
* `cursor()`