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!
As this object exists in CYF's hierarchy, it's possible to manipulate its parent. See the General Objects page for more information.

CreateText( / text, , position, width, 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}


• width - You'll always need this, as it's the maximum width of the text! 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.text Returns all lines of text the text object is holding. The texts might be different to how you added them to the text object because of how CYF handles text.

For example, if your text is too long to be held within one line, the text object will replace spaces with newline characters when needed. This change will be visible on the current line of text and all previous ones, but not on the lines of text which have yet to be displayed.

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 or Text.width 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.currentCharacter Returns a number representing the total number of characters currently shown in the text object's text.
It also works the same if your text is slowed down or sped up.

Text commands are also taken in account using this variable. You can easily check where the text is currently at using this value and Text.text's output.

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.rotation Gets or sets a text object's rotation, in degrees. Will also rotate the text object's bubble if it has any.

The text object will rotate around the bottom left corner of the first letter of the text object.

It's clamped between 0 and 360, so if you set it to 365, it will become 5.

Text.adjustTextDisplay False by default. If set to true, CYF will try to adjust the text's position and scale to prevent jagged lines to appear if the text's scale or position is slightly off.

Only taken in account if set, otherwise the global value set through the adjusttextdisplay Encounter variable is used.

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.

Text.linePrefix This variable will be added at the beginning of each line of text the text object will display.

Useful for adding various text commands you want to apply to all lines of text displayed by a given text object.

Text.columnNumber Represents the number of columns used by some texts in CYF, such as the ITEM and ACT menu.
If this is value is set, you should also consider changing Text.columnShift.

This value is only ever used by the engine, so setting it to a specific value doesn't prevent you from using the character \t as much as you like.
Refer to the entry on Text.columnShift for more informations on the character \t.

Text.columnShift Amount of horizontal pixels the letters moves by from its last column (or first character) whenever the character \t is used.

The \t character is used in-engine for aligning columns of text. It affects the current line of the text and can be used several times on the same line to support more than two columns.

For example, the following text will result with the following image:

* Check \t * Act 1 \t * Act 2 \n
* Act 3 \t * Act 4 \t * Act 5 \n
\t \t * Act 6

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
            

function Text.OnTextDisplay(text text) Every time this text object's letters are created, this function gets called. This function is the best place to manipulate the text object's letters using Text.GetLetters.

The argument text is the text object itself.

If this value isn't set and the function OnTextDisplay() exists in the Encounter script, it will call it with the text object as its argument.

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.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%") Shorter (and better) alias of 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.

position 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.Move( x, y) Moves the text object by x pixels horizontally and y pixels vertically from its current position.

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( firstLetter = 0, lastLetter = 999999) Returns the width of the currently set text in pixels. Useful if you want to center your text.
Will give the same result even if the text isn't finished typing.

Also ignores Text.xscale.

firstLetter chooses the index of the first letter from which the text's width should be computed, while lastLetter chooses the index of the last letter, and both start with 0 as the index for the first letter.

The values of these arguments can be negative, in which case it will start from the end, pointing at the xth last letter of the text. For example, using Text.GetTextHeight(-4) on the text I want some text will start counting the text's width from the first t of "text", or the 4th letter from the end of the text.

Text.GetTextHeight( firstLetter = 0, lastLetter = 999999) 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.

firstLetter chooses the index of the first letter from which the text's height should be computed, while lastLetter chooses the index of the last letter, and both start with 0 as the index for the first letter.

The values of these arguments can be negative, in which case it will start from the end, pointing at the xth last letter of the text. For example, using Text.GetTextHeight(-4) on the text I want some text will start counting the text's height from the first t of "text", or the 4th letter from the end of the text.

Text.SetVar( yourVariableName, value)
or Text[ yourVariableName] = value 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] Gets a variable in a text object that you previously set with Text.SetVar.
Identical to GetVar in projectiles.