1.3. dScript Format¶
When scripting, it is important to follow the dScript format as closely as possible to avoid parsing errors, unintended behaviors, or other mishaps that may arise.
A script is composed of multiple key parts. The first is the “script container name”, and the second is the “script container type”. All other parts of the script vary depending on the container type.
The container name is simply what the script is called. For example, we may wish to create a script and name it
The container type is the type of script that the container will be. For example, we may want to make our script
task type script.
Putting this together, we get the following:
1 2 3 4
a_task_script: type: task script: - define nothing "This script does absolutely nothing!"
You will learn more about each script container type and their various parts later.
There may be times when you have a command or a tag that has a space inside of it. We have an example script below:
1 2 3 4
a_narrate_command: type: task script: - narrate My whole sentence is great, isn't it <player.name>!
When you put this script in your
./scripts/ folder and attempt to run it, you will just see “
My” in your chat,
and probably a couple of weird things in the debug printed to your console. But we wanted it to say out “
sentence is great, isn't it YOUR_USERNAME!” Why didn’t it do what we wanted it to do?
Each space is considered a “separator” between multiple arguments. The narrate command only needs one argument (it can take a second argument, but that argument has a special prefix so we can ignore it for now).
To Denizen, we’ve given it 7 different arguments and an open quote! It reads the first “argument” properly, but every
“argument” afterwards is ignored and seen as weird. The single quote character
' in the word
isn't is seen as
the start of an argument, is invalid, and will cause parsing errors. Is there a way to get the whole sentence to be
considered one argument, and to get the single quote to not cause strange behaviors?
Luckily, there is. If you encase something in quotes, Denizen will automatically consider the entire quoted segment as
one argument. For example,
Put me in quotes is considered 4 arguments while
"Put me in quotes" is seen as only
one! Below are two acceptable ways to quote an argument.
1 2 3 4 5
a_narrate_command: type: task script: - narrate "My whole sentence is great, isn't it <player.name>!" - narrate 'My whole sentence is great, isn<&sq>t it <player.name>!'
Note that when single quotes are used to quote an argument, the
' symbol in the word
isn't is replaced with
<&sq>. This is to prevent Denizen from prematurely ending the argument mid-sentence and from causing any parsing
errors that may come from the
' at the end of the sentence. Always remember to escape quote characters inside of a
quoted argument (use
<&dq> for double quotes and
<&sq> for single quotes).
One of the most important aspect of writing in dScript is consistent indentation. Remember to keep a reasonable and consistent indentation pattern. The indents can be formed using TAB or any even amount of spaces. We strongly recommend that spaces are used to indent lines rather than TABs.
The example script below demonstrates these conventions well:
1 2 3 4 5 6 7 8 9
a_task_script: type: task script: - narrate "Hello, <player.world.name>!" another_task_script: type: task script: - narrate "Goodnight, <player.world.name>!"
In this example, there are two task scripts (we will cover what task scripts are in Section 2.3). If you were to highlight each script, you would see that each indentation is formed using 4 spaces.
Indentation clearly tells Denizen which are script containers (the lines that are not indented) and what belongs to each script container (the lines that are indented). Indentation will also serve to clearly differentiate sections of script associated with particular relevant commands (for example, if and foreach).
You don’t always have to use 4 spaces! Indentation using 2, 6, or even 8 spaces are all perfectly acceptable (indentations using an odd number of spaces are not)! Just remember to be consistent and organize your script well.
Always be careful when writing in dScript! If you’re not sure if a particular style of formatting works, it is recommended to test the script on a private dev server.