The Text Object

A lot of people were waiting for this: I'm proud to present to you the Text Object! With it, you can create text wherever you want, with or without a bubble, with a tail or without a tail... It's 100% your choice!

Plus, if you choose to make a bubble, the height of the bubble is automatically computed, but you can still choose the bubble's height if you want to.

By default, a Text Object has a bubble with an automatically-set height, with no tail/speech thing. Plus, the object is hidden when you enter or come out of ENEMYDIALOGUE. If you want to change this, there are a lot of functions to do so. Look down to see them!

CreateText( / text, , position, textMaxWidth, layer = "BelowPlayer", bubbleHeight = -1) returns textObject [E/M/W] This function creates a Text Object and returns it. However, as you can see, a lot of parameters are needed.
Here is what you need to set:

• text - The text to display.
  Used the same way as in BattleDialog: {"Text 1", "Text 2"}
  Can also just be a single line of text.


• position - Two numbers: The x and y positions of the center of the object. Sorry if it may be hard to place it, but you'll be able to use MoveTo to adjust it afterwards.
  You only need two numbers, like this: {320, 240}


• textMaxWidth - You'll always need this! The bubble's width will be 20px larger than the text's width. Also, bubbles have a minimum width of 40.
  Example: 150


• layer - The sprite layer of the Text Object. If it doesn't exist, it returns an error. This argument is optional. If it's not provided, the Text Object will be in the layer BelowPlayer (or Default in the Overworld).
  Example: "BelowPlayer"


• bubbleHeight - You can enter a static bubble height here if you want to. By default, this will be -1, which will auto compute the height of the bubble. However, bubbles have a minimum height of 40.
  Example: 150

Text.Remove() Shortcut to Text.DestroyText.

Text.DestroyText() This function destroys a text object, similar to .Remove() for bullets and sprites.

Trying to get, set or call almost anything besides Text.isactive on a destroyed text object will error.

Note that this happens automatically if a text object closes itself, either by having the player close it or by closing automatically if progressmode is "auto".

Text.isactive Read-only.
Tells you if a text object is active.

A text object will become inactive when it finishes its text and tries to continue, or if you call Text.DestroyText().

Text.progressmode This value is used to set the progression mode of the text to one of the following values.

• "auto": Makes the text start a new line after a given number of frames set in Text.SetAutoWaitTimeBetweenTexts().
• "manual": Makes the text require the player to press the Confirm button at the end of each line.
• "none": With this option, you will need to manually display the next line in-code using Text.NextLine().

Text.deleteWhenFinished This value is used to check whether the text object should be removed or not after the text is finished. Its default value is true, meaning the text object will be automatically removed after the end of the text. You can set it to false to automatically hide the text object once its text is complete, which allows you to reuse it later.

Text.x The local x position of the object, measured from the position of the text object's parent. This value depends on the object's pivot.

Text.y The local y position of the object, measured from the position of the text object's parent. This value depends on the object's pivot.

Text.absx The absolute x position of the object, measured from the bottom left corner of the screen. This value depends on the object's pivot.

Text.absy The absolute y position of the object, measured from the bottom left corner of the screen. This value depends on the object's pivot.

Text.textMaxWidth Get or set the maximum width of the text. If the value is lower than 16, it'll be set back to 16.

Text.bubbleHeight Get or set the height of the bubble. If the value is lower than 40, it'll be set back to 40.

Text.layer The sprite layer of the Text Object. If it doesn't exist, it returns an error. This is "BelowPlayer" by default.

, , , = 1 Text.color Get or set the color of the text, as a table of 3 or 4 values from 0 to 1.
For example, text.color = {1.0, 0.0, 0.0} makes the text red.
Black areas are not affected by coloration.
The 4th value is the alpha (transparency) value of the text.

, , , = 255 Text.color32 Get or set the color of the text, as a table of 3 or 4 integer values from 0 to 255.
For example, text.color = {250, 0, 0} makes it red.
Black areas are not affected by coloration.
The 4th value is the alpha (transparency) value of the text.

Text.ResetColor( resetAlpha = false) Resets any previous set of the variable Text.color or Text.color32, resetting the text's default color to the font's default color.
This function will not reset the color's alpha if it was set in any way unless resetAlpha is set to true.

Text.alpha Get or set the text's transparency, as a value between 0 and 1.

Text.alpha32 Get or set the text's transparency, as an integer between 0 and 255.

Text.ResetAlpha() Resets the text object's alpha value, whether it was set through Text.alpha, Text.color or Text.color32, resetting the text's default alpha to the font's default alpha.

Text.currentReferenceCharacter Returns a number representing the total number of visible characters currently shown in the text object's text.
It also works the same if your text is slowed down or sped up.

Any text commands that you have in your active line of text will be ignored by this number, as it only counts the visible characters, and not the length of the string you put into the text object.

Text.currentLine Returns the number of the line (page) that the text is currently on, starting from 0.

So, if your text object's text table is {"Text 1", "Text 2"}, then "Text 1" is line 0, and "Text 2" is line 1.

sprite Text.GetLetters() Returns a table containing sprite objects representing every letter to be displayed in the text object's current line of text. Note that even if a text object has not finished typing yet, all characters it will type are still accessible this way.

Letter sprite objects can not have their layer changed, can not run sprite.Mask, and can only be parented to other letter sprites. They cannot be deleted or dusted (using sprite.Dust()) as well.

local t = CreateText({"Some example text for testing!"}, {40, 400}, 560, "Top")
t.HideBubble()
t.progressmode = "none"

function OnTextAdvance(text, final)
    if text == t and final == false then -- optional if you only have one text object
        local letters = t.GetLetters()

        for i = 1, #letters do
            letters[i].y = math.sin(i) * 3
            letters[i].rotation = math.sin(i * 1.5) * 6
        end
    end
end
            

local t = CreateText({"[instant]Some example text for testing!"}, {40, 400}, 560, "Top")
t.HideBubble()
t.progressmode = "none"

local letters = t.GetLetters()

for i = 1, #letters do
    letters[i].y = math.sin(i) * 3
    letters[i].rotation = math.sin(i * 1.5) * 6
end
            

Text.SkipLine() This function skips to the end of the text object's current text, as if using the text command [instant].
If playerskipdocommand is true, this function will behave the same as a player skip. See Special Variables for an explanation on playerskipdocommand.

Text.lineComplete Read-only.
Returns true if the current line (page) of text is fully displayed, false otherwise.

Text.allLinesComplete Read-only.
Returns true if the current line of text is fully displayed and if this is the last line the test object will show, false otherwise.

Text.lineCount() This function returns the total number of lines/pages of text set to the text object, regardless of whether they've been shown yet.

Text.NextLine() Shows the next line (dialogue) of the text instantly, regardless of if the current one is finished or what progress mode the object has.
If you run this function while this is this text object's last line, it will delete the text object if its Text.deleteWhenFinished variable is set to true, othrwise it will deactive it until further use.

Text.SetWaitTime( time) Shortcut to Text.SetAutoWaitTimeBetweenTexts.

Text.SetAutoWaitTimeBetweenTexts( time) Sets the number of frames to wait before automatically going to the next line of text.
Only applies to the "auto" progress mode.

Text.SetParent(sprite parent) Sets the text object's parent.
The text object will follow around the parent object as it moves.

NOTE: If you are in the Overworld, you can NOT use this to parent text objects to Event objects' sprites.

Text.SetAnchor( x, y) If this text object has a parent set via Text.SetParent, this will control its anchor point (the relative point on the parent sprite that the text object will follow if the parent sprite gets scaled).

x and y should usually both be between 0 and 1. However, you are free to use numbers outside of this range as well.

Works exactly the same as sprite.SetAnchor (see Sprites & Animation).

Text.xscale,
Text.yscale,
Allows you to stretch and squish text objects, similarly to sprite objects.

This works at any point: while the text has not yet started to type, is in the middle of typing, is paused, between lines, even if it's done typing.

Text.Scale( xscale, yscale) Same as setting Text.xscale and Text.yscale at the same time.

Text.MoveBelow(text otherTextObject) Moves a text object below another text object.
They must both be on the same layer.

Text.MoveAbove(text otherTextObject) Moves a text object above another text object.
They must both be on the same layer.

Text.SendToTop() Sends this text object to the top of its layer's hierarchy. If a sprite has 5 children, for instance, you can use this to rearrange this text object's position internally. However, child text objects will always appear on top of their parents, regardless of this function being called.

Text.SendToBottom() Sends this text objct to the bottom of its layer's hierarchy. Similar rules apply as with SendToTop().

Text.AddText( text (OR) text) Adds the given text to the object's text table. Acts like Text.SetText() if all the text is already done.

Text.SetText( text (OR) text) Sets the text in the Text Object.
If the text object is inactive when this is called, the object will reactive itself.

Text.SetPause( pause) Pauses the text object's typing, in the same way as [waitfor:key], except that it doesn't resume until you use this function again.

However, while paused, text can still be skipped, unless [noskip] is applied to the text first.

Text.isPaused() This function will return a boolean, telling you whether text has been paused with SetPaused.
It does not count if the text object was paused by other means, such as [waitfor:key].

Text.SetVoice( voiceName) Sets the voice of the text object. It's the same as the text command [voice], but whatever.

Text.SetFont( fontName) Sets the font of the text. It's the same as the text command [font], but whatever.
Returns an error if the font doesn't exist.

Text.SetEffect( effect, intensity = -1) Sets the effect of the text. Can be easily replaced with the text command [effect], but whatever.
Can only take none, twitch, shake or rotate as the effect.

If you want to use the default intensity value, enter -1.

Text.ShowBubble( side = nil, / position = nil) Use this function to add a bubble to the text. You can also set the side and the position of the tail (a.k.a. speech thing) if you want to.
Look at Text.SetSpeechThingPositionAndSide to see how to use this.

Text.SetTail(side, / position = "50%") Shortcut to Text.SetSpeechThingPositionAndSide.

Text.SetSpeechThingPositionAndSide( side, / position = "50%") Sets the size and position of the dialogue bubble's tail (a.k.a speech thing). The side can only take "left", "right", "up", "down" or "none".
"none" is used to hide the speech thing, while the other directions control the side of the bubble where the speech thing is.

center can be set to one of two things:

• A number. If the side is "left" or "right", this will determine its distance from the bottom of the bubble. If the side is "up" or "down", then this will determine its distance from the right side of the bubble.
  If on the bottom or top of the bubble, this value can only be between 0 and the bubble's width. If on the left or right sides of the bubble, this value can only be between 0 and the bubble's height.


• A string. It must be formatted like "0%", where you can replace the "0" with any percentage. If on the top or bottom of the bubble, "0%" will be the right side of the bubble and "100%" will be the left side of the bubble. If on the left or right side, "0%" will be the bottom of the bubble and "100%" will be the top of the bubble. The value can only be between "0%" and "100%".

Text.HideBubble() A function that hides the bubble.

Text.MoveTo( x, y) Moves the text to a new position, relative to the text object's parent's position.

Text.MoveToAbs( x, y) Moves the text to a new position, relative to the bottom left corner of the window.

Text.GetTextWidth() Returns the width of the currently set text in pixels.
Will give the same result even if the text isn't finished typing.

Also ignores Text.xscale.

Useful if you want to center your text.

Text.GetTextHeight() Returns the height of the curently set text in pixels.
Will give the same result even if the text isn't finished typing.

Also ignores Text.yscale.

Note: This function is not 100% accurate.

Text.SetVar( yourVariableName, value)
or Text[ yourVariableName] Sets a variable in a text object that you can retrieve with Text.GetVar.
Identical to SetVar in projectiles.

Text.GetVar( yourVariableName)
or Text[ yourVariableName] = value Gets a variable in a text object that you previously set with Text.SetVar.
Identical to GetVar in projectiles.