Guide:Internal scripting/Text box construction

This guide explains exactly how text boxes can be constructed, and tweaked, in internal scripting.

The basics (showing and removing, color, position, sound)

This is the most basic version of a text box:

text(player,50,60,1)
This is some text!
speak_active

This creates a cyan-colored text box 50 pixels from the left and 60 pixels from the top, with 1 line. The text command just stores the text and position in memory, but doesn't display it yet; when you're finished, use speak_active to actually display it. The color can be player/cyan (it doesn't matter which of the two you use), gray (or anything that doesn't exist), red, blue, purple, yellow, green, orange or white.

But it'd be nice if we could position it above the player or in the center, instead of at some coordinates...

text(player,0,0,1)
This is some text!
position(player,above)
speak_active

text(gray,0,0,1)
This is a terminal text box!
position(center)
speak_active

The position command replaces the coordinates that are given in the text command, and there are different combinations possible, such as position(center), position(player,above), position(red,below), et cetera. There are also position(centerx) and position(centery), for only centering on the X and Y axis respectively. (You can then also, for example, set a numeric coordinate in the text command, and then override only the X axis.)

How about the sound that someone/a terminal makes when a text box appears? There's the squeak command for that:

squeak(player)
text(player,0,0,1)
This is some text!
position(player,above)
speak_active

squeak(terminal)
text(gray,0,0,1)
This is a terminal text box!
position(center)
speak_active

This combination of commands is by far the most commonly used for text boxes.

But the last text box will not go away!

squeak(player)
text(player,0,0,1)
This is some text!
position(player,above)
speak_active

squeak(terminal)
text(gray,0,0,1)
This is a terminal text box!
position(center)
speak_active

endtext

The endtext command should be used to dismiss text boxes before any kind of delay and before ending the script, basically whenever it isn't followed by another text box.

That's basically everything you need to know to get started, but there's more advanced stuff that you can use.

Multiple text boxes

speak_active removes old text boxes that were already on the screen, but you can avoid that by using speak instead of speak_active:

squeak(player)
text(player,0,0,1)
This is some text!
position(player,above)
speak_active

squeak(terminal)
text(gray,0,0,2)
The previous text box
is still on the screen now!
position(center)
speak

endtext

In other words, speak simply displays a text box, while speak_active displays a text box and removes all previous text boxes.

You can even make multiple text boxes appear at once. Normally speak and speak_active wait until you press the action key before the script continues, but not if you put backgroundtext before it:

squeak(player)
text(player,0,0,1)
This is some text!
position(player,above)
backgroundtext
speak_active

squeak(terminal)
text(gray,0,0,2)
Two text boxes
at the same time!
position(center)
speak

endtext

The same example with three text boxes that will appear at the same time:

squeak(player)
text(player,0,0,1)
This is some text!
position(player,above)
backgroundtext
speak_active

squeak(player)
text(player,0,0,1)
This is more text!
position(player,below)
backgroundtext
speak

squeak(terminal)
text(gray,0,0,2)
Three text boxes
at the same time!
position(center)
speak

endtext

No text box fadeout

Sometimes you may want to remove a text box immediately without fading it out. For that, endtextfast exists, you can just use it instead of endtext.

Flip mode positioning

There's a command flipme that will correct text box positions in flip mode (for if you have a terminal that puts multiple text boxes on the screen). Level creators usually don't use this command in custom levels. It also didn't work properly before VVVVVV 2.3.

Removing all but the last text box

There's also a command textboxactive, which removes all text boxes from the screen except for the last one. speak_active is actually a combination of speak and textboxactive, so textboxactive doesn't really have much use (unless you want to show multiple text boxes and then, after a delay, only leave the last one).

Centering via coordinates

There's also a hidden way of centering a text box without using position(center)/position(centerx)/position(centery) that was especially useful when needing to maintain compatibility with 2.0, which is to write -500 for x and/or y coordinates. It saves a line, but it makes the script a bit less readable.

Unusual colors

There's a trick that allows you to access a couple more colors for text boxes.

(TODO: include that trick on this page instead of linking)

The End

Apart from the specialline(x) command (which probably doesn't have a use in player levels at all), that should be everything there is to know about text boxes in internal scripting!