This is a complete reference to all the features of a SUDS Script File. Scripts are the static template for a runtime dialogue, containing all possible routes through the interaction; think of them like a movie script.
A SUDS script file must have the extension .sud.
SUDS scripts are line-based. Each line is self-contained and does one thing. You can't split commands over 2 lines, or combine multiple commands into a single line.
Whitespace is trimmed from the start/end of all lines. However indenting can matter when it comes to branching due to choices.
Script files are imported into Unreal as SUDS Script assets and an associated string table (see Localisation).
The easiest way to do this is simply to save your .sud file in your Unreal
project's Content folder and confirm the auto-import prompt. You can keep making
changes to the .sud and UE will re-import it as changes are detected.
SUDS has a VSCode extension which makes it much more pleasant to edit
the .sud format, recognised it as a language and syntax highlighting everything.
Here are all the types of lines you can include in your scripts:
| Line Type | Summary |
|---|---|
| Speaker lines | Lines of dialogue |
| Choice lines | Player choices that can branch dialogue |
| Goto lines | Jump dialogue execution to another line |
| Gosub & Return lines | Jump to another line, then return back |
| Set lines | Set variable values |
| Conditional lines | Include/exclude parts of the dialogue based on state |
| Event lines | Raise events to be received by code |
| Comment Lines | Ignored by the importer |
| Import Setting Lines | Change behaviour during import |
A script is generally run from top to bottom, starting at the top unless told to start from a label. Lines are executed one after the other until a Speaker line is hit, at which point the dialogue will pause and wait to be told to continue; potentially via a player choice, or simply just a continue prompt.
A few things can alter this simple top-to-bottom sequence:
- Headers: Lines contained in the header section of the script are executed when the dialogue is created.
- Choices: choices represent player decisions which branch the dialogue. Everything indented under a choice line is only executed if that choice is picked.
- Gotos: goto lines jump the dialogue execution to either a
label, or to
end, which terminates the dialogue. - Conditionals: conditional lines include or exclude sections of the dialogue based on variable state.
There are also fallthrough rules which control what happens when you reach the bottom of an indented section (under a choice).