Text commands

There are two types of text commands: commands that get executed instantly, like text color and effects; and commands that get executed inline, as they're displayed, like wait commands and character voices. Note that currently, if you skip a text command (with X), it'll also skip all inline commands that were still in your text. Unless, that is, you use playerskipdocommand :P

On line breaks: there are actually two different kinds. In UI messages where asterisks are used, you can use \n to start a new line with an asterisk. If you want a new line without an asterisk, use \r.

This is different for monster dialogue that isn't prefixed with asterisks: Always use \n for line breaks here. Or use autolinebreak! See Special Variables.

Instant commands

[color:rrggbb] This sets the text color for all text after this command to the specified hex code. It resets per dialogue. [color:ff0000] would be red, [color:555555] a dark grey.
Here are a few examples:

If you have to use colours, try to stick to these. While the option for any colour is offered, actual usage in Undertale is very limited.

The default UI text is plain white and the default enemy dialogue text is plain black - [color:ffffff] and [color:000000] respectively.

[color] This command resets any previous usage of the [color:rrggbb] command, displaying any following text in the font's default color.

[alpha:aa] This command allows you to set the alpha (transparency) value of your text.

The number you enter should be a two-character hex value between "00" and "ff".

[alpha] This command resets any previous usage of the [alpha:aa] command, displaying any following text in the font's default alpha.

[starcolor:rrggbb] Same usage as color but only affects the first asterisk in a dialogue box that has asterisks. This is a dirty workaround, but now you don't need it anymore, it's deprecated.

As commands are now executed before the star, you can use [color:rrggbb] to color the star.

[effect:x] or [effect:x,intensity] Sets the text effect for the entire message, regardless of position. You can use the following effects:

• none: No effect on the text.


• rotate: Rotating text, most random monsters have this by default. Intensity sets how far letters rotate, in pixels. Default is 1.5.


• shake: Shaking text. Flowey uses this sometimes. Intensity sets how far the letters offset, in pixels. Default is 1.0.


• twitch: Letters twitch occasionally - the battle UI has this by default. Intensity sets how far a letter should shake. Default is 2.0.

Note that the twitch effect should, at a later point, let you set shake frequency. Unfortunately you can't do this yet.

[lettereffect:x] or [lettereffect:x,intensity] This works the same as [effect:x] / [effect:x,intensity], but it works inline. This means you can have multiple different text effects in a single line!

Keep in mind that, like all other inline text commands, this command will not execute if the player skips over it with X - unless you set playerskipdocommand to true, first.

[font:x] Sets the font for this dialogue. Usually includes a default voice. As the [font] command can change both text colour and voice, if you want to have your own voice/text color do it after the font change. Possible options:

• uidialog: Default large pixel font for UI.


• monster: Default font for almost all monsters in the game.


• sans: sans. use lowercase. uppercase works, but... sans.


• papyrus: PAPYRUS! USE UPPERCASE ONLY. LOWERCASE WON'T WORK.


• wingdings: Wingdings.


• uibattlesmall: The font used for the character name, HP and level.


• and a lot of others...you can even create your own font!

For all default fonts, check out the Default/Sprites/UI/Fonts folder. Every font with a matching .xml file is mapped.

[charspacing:number] and [charspacing:default] Sets the number of pixels that separate characters on the same line.
Negative = less space between characters, Positive = more space between characters

The default value is 3.
Fonts can specify a <charspacing> tag that sets this value.

Enter [charspacing:default] to reset this value to the value provided by the font (or the default value of 3).

[linespacing:number] Number of pixels that separate different lines. The number you enter here gets added on to the active font's regular line spacing.
Negative = less space between lines, Positive = more space between lines

By default, the amount of pixels between lines is 1.5 * the height of the font's "space" character.
If the font has a <linespacing> tag, its number value will be the amount of pixels between lines instead.

Enter [linespacing:0] to reset the line spacing to its original value.

Inline commands

[noskip] Prevents this dialogue from being skipped by pressing X.

It is effective only whenever the text reaches it, but if it is placed at the beginning of a line of text, it will always work, even if it is not the first command.

[noskip:off] Cancels a previous [noskip] command.

[instant] Instantly shows the entire text without having to wait or press anything.

* Note: This command works as an inline command when placed at the beginning of a line of text.

[instant:allowcommand] The same as [instant], but here other text commands are called, except [w], [letters] and commands with the "skipover" tag.

* Note: This command works as an inline command when placed at the beginning of a line of text.

[instant:stop] Cancels a previous [instant] or [instant:allowcommand] command, and resumes typing.

[instant:stopall] Cancels a previous [instant], [instant:allowcommand] command or a Player skip, and resumes typing.

[w:x] The wait command. Pauses your textbox temporarily based on the number you enter.

Technically: This will pause the textbox for x * 4 in-game frames.
Calling [w:1] will freeze the textbox for 4 in-game frames.
[w:4] is 16 in-game frames, [w:10] is 40, and so on.

[waitall:x] Makes all letters after this command take x times as long to type out. (slightly different from [w:x])

Use [waitall:1] to reset text to its default speed.

Overrides [speed:x].

[voice:filename] Sets the voice (sound per letter) to a sound located in YOUR MOD/Sounds/Voices. Applies to all letters after the command. It resets per dialogue. This has to be a .wav file, and you shouldn't include the file extension when using [voice]. If your voice sound is YOUR MOD/Sounds/Voices/mettaton.wav, you can use it with [voice:mettaton].
[voice:default] resets to the default voice (beeps). If you have a voice sound named 'default', it will be ignored.

[novoice] Removes the voice for the letters after this command. It resets per dialogue. Useful for when you should be burning in hell.
[next] Skips to the next dialogue automatically. You can also use this for textbox trickery. Here's an example to replicate Flowey's text-changing effect if you dodge the Friendliness Pellets(tm) twice.

first line:  "[noskip][voice:flowey][effect:none]RUN. [w:30]INTO. [w:30]THE.\n[w:30]BULLETS!![w:30][next]"
second line: "[instant][effect:none]RUN. INTO. THE.\nfriendliness\npellets"

[finished] Sets this dialogue box as "finished". To go through the next dialogue box, you'll have to wait until the other monsters' dialogue boxes are also finished.

[nextthisnow] Skips to the next dialogue of all monsters automatically, without concern for the other monsters' dialogue's state.

[waitfor:key] Waits for the user to press the given key to continue the message. Check the Key List to see the available keys.

[func:x], [func:x,argument] or [func:x,{argument1, argument2...}] The most powerful command. If the previous text commands were established official characters, [func] is some kid's deviantArt original character that never dies and has all the superpowers.

In all seriousness, [func] allows you to execute any function from your script in line with the text. Refer to the examples below.

your dialogue: "hoi hoi this is dog [func:dog] and now the music changed"

function dog()
    Audio.LoadFile("dog_music")
    --plays dog_music.ogg (or .wav) from your Audio folder! for built-in functions like this, refer to section API - Functions & Objects
    --insert more code here, any code!
end

your dialogue: "dog with arguments!! [func:newmusic,temietheme] so intense!"

function newmusic(yourargumentname)
    Audio.LoadFile(yourargumentname) --with this example, it'll load 'temietheme.ogg (or .wav)'...
    --and then play it! THE FUTURE IS NOW! By using an argument, your function can be more versatile.
end

[speed:x] Makes the text handler print x characters over every 4 frames.
The default text speed in CYF ([speed:1]) is 1 character every 4 frames.

For example, [speed:4] will type text at 4x the regular speed: 4 characters every 4 frames, or 1 per frame.

* Supports fractional numbers! [speed:0.25] writes text at 1/4th the regular speed, for instance.

Overrides [waitall:x].

[letters:x] For this frame only, the text box will show the next x characters.

[name] This text gets replaced by by the name of the player. I totally forgot that we could actually use Player.name, but whatever.

[music:x] Plays the music given as an argument on the main music channel, unless the argument is one of these keywords:

• play = Only plays the last played music, from the beginning.


• pause = Pauses the music.


• unpause = Unpauses the music.


• stop, null, nil or an empty string = Stops the current music.

[sound:x] Plays the sound given as an argument.

[mugshot:face], [mugshot:null] or [mugshot:{face1,face2,...,time}] Overworld only.

Displays a set face sprite (or sequence of face sprites) next to your dialogue set by General.SetDialog.
Note that the overworld's automatic line break system will not account for face sprites set this way; instead, it's recommended to set a face sprite in General.SetDialog (see The General Object).

This function loads face sprites from YOUR MOD/Sprites/Mugshots. You may put folder names in here, such as [mugshot:Papyrus/suspicious] for YOUR MOD/Sprites/Mugshots/Papyrus/suspicious.png.
Use [mugshot:null] to revert the overworld text box back to normal.


To use a sequence of face sprites, enter something such as
[mugshot:{Papyrus/happy,Papyrus/suspicious,0.1}].
This is a list of normal paths to put into [mugshot:x] as described above, followed by the amount of real time seconds between faces (such as with sprite.SetAnimation).

If you do not provide a time, or the time you enter is <= 0, a default value of 0.2 will be used.

[health:x,y] Heals the Player by x points. Can damage the player if x is negative, but the Player's HP will not go under 1 unless certain conditions are met. The parameter y is optional.

Examples:

• [health:3] => Heals 3 HP.


• [health:-5] => Damages 5 HP. Doesn't go under 1HP.

• x (y is unused if these tags are used):
  • kill = Kills the Player.
  
  
  • Max-1 = Sets the Player's HP at Player's Max HP minus 1.
  
  
  • Max = Sets the Player's HP at Player's Max HP.
  
  
• y:
  • killable = The possible HP reduction can now kill the Player.
  
  
  • set = The amount of HP given in the first argument will be the Player's current HP.
  
  

Command tags

These tags can be added after a text command and have different behaviours.
To use them, you must do this: [command:tag] or [command:arguments:tag]. For now, only one tag can be added at a time.

skipover Makes a command only be activated when the text is not skipped (by using any [instant] command or the player's skip if playerskipdocommand is set to true). Has no effect on [w] and [letters].

skiponly The command this is attached to will only be activated if the text has been skipped by using any [instant] command, or if the player skips it manually and playerskipdocommand is set to true. This tag disables the [w] and [letters] commands if used on them.