Script Commands
There are a variety of commands available when writing a script. Let’s go through all of them, starting with the script headers. Unless otherwise noted, you should always put script commands on their own lines (though converted scripts may allow them to share lines with unknown text control codes, and this is absolutely fine).
Please keep in mind that all of these can vary based on your active language
pack. In order to find out your language pack’s equivalent for a command name,
take a look at the resources/global/txt/xml/lang/language/Script.xml file,
where language is your active language.
Script commands have syntax highlighting for parameters — green indicates a valid parameter, red indicates an invalid parameter (with some exceptions, noted in the entries for specific commands), and purple indicates a valid character name.
Script Headers
Valid Forms:
[SCRIPT]
[FORMATTED SCRIPT]
There are two script headers: [SCRIPT] and [FORMATTED SCRIPT]. Every script
must begin with one of these.
[SCRIPT] is the ‘lazy’ option, for people who don’t want to have to
micromanage line length. It will automatically perform wrapping when converted
back to game text, including the maximum possible My Unit name length and the
longest of any gender-based substitutions in the line in its calculations. If
you enter a newline, it will treat it as a request for a completely new page in
the conversation rather than a newline.
[FORMATTED SCRIPT] is the way to go for advanced users and those who are
obsessive about the exact layout of their text. It will not perform any kind of
line wrapping, so you will need to make sure to accommodate My Unit name length
and gender-based substitution length in your own manual line breaks. In
[FORMATTED SCRIPT] mode, every line break is treated as a request for a line
break and every second line break is treated as a request for a new page.
All scripts converted from existing messages will become formatted scripts. If you wish to preserve a script in non-formatted mode, ensure that you save a copy of it in the .fescript format.
Display Type
Valid Forms:
(TYPE: VALUE)
Replace VALUE with either ZERO or ONE, depending on your desired display
type. Generally speaking, this should be one of the first commands in your text
file. At most a BGM command should precede it, and it must come before any
lines of speech.
Type ZERO will put one speaker at the top of the screen and the other at
the bottom, in the process showing the last message from each speaker as the
next one takes their turn. Small face portraits will be used in place of the
torso images. This format is often used for in-battle conversations.
Type ONE will put the speakers across from one another horizontally and will
display only a single message at a time. The inactive speaker will be faded out.
This mode uses full torso images for characters and is used for most
conversations.
Has Permanents
Valid Forms:
[HAS PERMANENTS]
Similar to the Type command, this should come at the top of your script — but only if you are using Fates and intend to use My Unit-dependent text control codes like $Nu and $G.
Awakening does not require the control code that this represents, and indeed does not appear to support it for the same purpose. In Awakening, it instead seems to provide the ability to reference game-provided variables via $a0, $a1, $a0, and so on. Best to leave it alone unless you’re doing some really fancy romhacking.
Enter
Valid Forms:
(ENTER POSITION: NAME)
(ENTER POSITION: NAME, EMOTIONS)
The Enter command allows you to bring a character’s portrait to the screen. Up to two can be displayed at once — you will need to use the Exit command if you wish to bring in others.
POSITION has four possible options, depending on your display type. Type ONE
can have either LEFT or RIGHT, while type ZERO can have either TOP or
BOTTOM.
NAME is the name of the character to display. Generally speaking, this will be
the English name of a character from the game. It may also be the name of the
active My Unit if the option has been selected in the My Unit menu. A full list
of names can be found in the
resources/game-mode/text/xml/lang/language/PID.xml file, where game-mode is
the current game mode and language is the active editor language.
In the case of the second format, EMOTIONS consists of up to three
comma-separated values. The first is the name of an emotion posssessed by the
character. You can find a full list of emotions for Awakening
here and Fates here. The second and
third can be either Blushing or Sweat, both of which act as self-explanatory
modifiers to the expression — Blushing adds a blush, while Sweat adds a
drop of sweat.
Exit
Valid Forms:
(EXIT: NAME)
(EXIT)
The exit command will remove a character portrait from the screen. In the first
form, NAME specifies the character to remove. The second form will simply
remove the last speaker.
BGM
Valid Forms:
(BGM: NAME)
(BGM: NAME, VALUE)
The BGM command is used to cause a BGM to start playing. Substitute NAME with
the name of the BGM file to play — these can be found in the
resources/game-mode/sound/bgm folder, where game-mode is the current game
mode. If you enter an invalid BGM name (that is, one that is not recognized as
existing in the resources folder — if a core game archive has an ‘invalid’
BGM, it is using another way to reference an existing BGM) it will be
highlighted in red. Valid names will be green.
VALUE does… Something. I’m not entirely sure what, so the simulator
won’t handle it, but it appears to be something related to selecting a playing
offset in the BGM.
This command works in Fates, but none of the core text makes use of it and it should thus be used with caution.
Sound Effect
Valid Forms:
(SOUND EFFECT: NAME)
This command will play the sound effect with the name NAME. Sound effects can
be tested in the Audio Palette. As with BGMs, valid and invalid values will be
highlighted. There will be far more cases of ‘invalid’ sound effects being
detected in converted game text than BGM, however — many game sound effects
have multiple internal names, but they have only been provided with their ‘base’
names.
If placed between two lines of speech, it will also have the effect of paginating.
Emotion Shift
Valid Forms:
(EMOTION SHIFT: NAME, EMOTIONS)
(EMOTION SHIFT: EMOTION)
This command allows you to change the expression of a displayed portrait.
The first form specifies the target of the change by NAME. The name can be any
appropriate character name, but must be someone present in the conversation.
The second form will apply to the last speaker.
As with the Enter command, EMOTIONS consists of up to three comma-separated
values. The first is the name of an emotion posssessed by the character. You can
find a full list of emotions for Awakening here and Fates
here. The second and third can be either Blushing or
Sweat, both of which act as self-explanatory modifiers to the expression —
Blushing adds a blush, while Sweat adds a drop of sweat.
Text Color
Valid Forms:
(TEXT COLOR: R, G, B, A)
This is a fun one that’s used a lot for dragon-form Grima’s red text in Awakening, but only for some system messages in Fates.
To use it, replace R, G, B, and A with the red, green, blue, and alpha
(respectively) values of the color that you would like to use. To revert the
text color you will need to use the command again, but with the default color
values: [78, 61, 41, 255] for Awakening and [68, 8, 0, 255] for Fates. I didn’t
think to include a command for automatic reversion in the first release because
I’m an idiot, but I’ll go ahead and pack one in an update at some point.
At the moment this command can have some issues with the type zero display mode, which I will iron out in a future release. I have not confirmed whether or not rainbow text is a valid possibility in the games, but if it is that will be another thing that I need to add handling for. It’s nice to have goals, isn’t it?
…Nothing is ever finished…
Speech
NAME: TEXT
NAME [SOUND EFFECT]: TEXT
NAME (EMOTIONS): TEXT
NAME [SOUND EFFECT] (EMOTIONS): TEXT
NAME {CONTROL CODES} [SOUND EFFECT]: TEXT
NAME {CONTROL CODES} (EMOTIONS): TEXT
NAME {CONTROL CODES} [SOUND EFFECT] {CONTROL CODES}: TEXT
NAME {CONTROL CODES} [SOUND EFFECT] {CONTROL CODES} (EMOTIONS): TEXT
The last thing available for now is regular speech, which has a ton of variants.
At their base, they all consist of a NAME as in the Enter command, potentially
followed by some other commands and then a colon, space, and the actual TEXT
that should be displayed. Contiguous lines spoken by the same character do not
require the whole thing — just text, unless you want to play another sound
effect or perform an emotion change.
SOUND EFFECT is the name of a sound effect as in the Sound Effect command,
surrounded by square brackets. It indicates the name of a sound effect that
should be played when the line is spoken, and should always precede emotions
if they are present.
EMOTIONS are a set of emotions as in the Enter or Emotion Shift commands,
surrounded by parentheses. They should always be the last thing before a colon,
if they are included.
CONTROL CODES can be present in two places — before a sound effect and
before emotions. They are wrapped in curly braces and are generally only found
in converted scripts, where they contain unknown control codes that were found
in those positions. Unknown control codes found after emotion selection will
be added as the first part of the text.
This may sound a little complicated, but in practice the only forms you really need to worry about are the first four. Thankfully those are the easiest, and the syntax highlighting will let you know if you did it right! If the line isn’t highlighted, it’s not formatted correctly.
Useful Control Codes
Simple in-line control codes have not received commands, partially because they are already brief and easy to understand. The two most useful are $Nu and $G.
Lucina: Hello, $Nu.
This would print “Hello, Robin.” for a default My Unit. $Nu is simply replaced
with the player’s name, though in Fates it will only work if you have already
used [HAS PERMANENTS].
Lucina: $GHe,She| looks strong.
This would print “She looks strong.” for a female My Unit and “He looks strong.” for a male My Unit. It substitutes the first line of text for male characters and the second for females. This text cannot contain commas or vertical bars, as those are used to divide it.