Your First Task Script

Task Script Basics

A task script is a stand-alone script that can be run either via in-game command with the /ex command, or by the run command in a script.

Task scripts will run all of the Denizen commands that they include. A task script can be simple, it can be complicated, and it can even run other task scripts. This is useful to create logic-based script chains, like dialogue options or random content.

Task Script Syntax

Here's an example of a basic task script.

example_task:
    type: task
    script:
    - narrate "This is a basic task script!"

This script will narrate the text: This is a basic task script! to the player attached to the script. If you use the /ex command to run this script - specifically, by running /ex run example_task in-game, you will be the attached player.

Note that this script sample is highlighted in green. That means it's good enough that you could copy/paste it and it will work. Farther down this page there's a script example highlighted in blue, meaning it's a good example but some part needs to be filled in. Later on you'll see examples in red, indicating that those examples are what to not do. For more information on this highlighting system, refer to This Guide - Sample Scripts.

Building Your First Task Script In VS Code

Previously, you've learned how to set up VS Code, the editor that we recommend for writing Denizen scripts.

Creating The File

To create your first task script, start by opening your scripts folder in VS Code.

From there, right click the scripts folder in the explorer menu and click the "New File" option.

Type any file name you want, just make sure to end it with .dsc - the required extension for a Denizen script file.

Now you can begin writing your first task script!

Writing The Script

Let's start with the core of the script:

my_first_task:
    type: task
    script:
    - narrate (sometext)

This example should look familiar - it's very similar to the example above.

You should write this by first typing my_first_task: (making sure to use _ underscore symbols rather than spaces, and a : colon at the end), then press the ENTER key to go to the next line, and the TAB key to space forward the next block. As you continue typing lines, the level of indentation will remain where it was, meaning you do not have to press TAB again until you need to space something even farther out, as will be needed in later examples.

Script Names

The name of the script here is my_first_task. It's at the top of the indentation (meaning that there are no spaces at the start of the line, whereas all the other lines have exactly 4 spaces at the start - those are indented farther in). Each top-level indentation entry is a separate script. Here is an example of two different scripts:

my_first_task:
    type: task
    script:
    - narrate "This is is task number one!"

my_second_task:
    type: task
    script:
    - narrate "This is task number two!"

This example demonstrates what having two different scripts in the same file looks like. my_first_task and my_second_task are two different scripts, and each is a fully self-contained script.

Additionally, note that script names and file names are different. Both my_first_task and my_second_task could be contained within the same file named my_first_scripts.dsc. It's the script name (that my_first_task) that matters, the file name (my_first_scripts.dsc) is entirely for your own personal organization, and will not make any difference to Denizen. Note as well that you're free to create subfolders inside the scripts folder, and any script files within will be loaded just the same.

Script Types

Below the script name - on the second level of indentation - you'll see the type key.

The type key is where you specify which type of Denizen script you're writing. In this case, we're writing a task script. You may have already seen world scripts, item scripts, inventory scripts, or any of the many other types that exist. For now, we will focus on task scripts. You'll learn about the different types as you read through these guides, and you can find explanations about all of them from the meta documentation on the language explanation page.

Make sure you write type: task in your script on the second level of indentation (press enter to start a new line, then press tab to indent once. This will add 4 spaces on the line, and every time you press enter after there will automatically be 4 spaces again, until you press backspace to remove the spaces), below the script name, like this:

my_first_task:
    type: task

Script Commands

Below the type key, you'll see the script key. For a task script, the script key is where you write the content of the script - the set of instructions that tell Denizen what to do. Other types of scripts use other keys, and you'll learn about them as you continue to work through this guide. The majority of actual work you do in Denizen will be under keys like this one.

Let's look at another example script:

my_first_task:
    type: task
    script:
    - narrate "This is a valid task script!"
    - narrate "Congratulations on writing your first script!"

Notice how the text we want to narrate - This is a valid task script! - is enclosed in "" quotes. Because the message we want to narrate has spaces in it, we enclose it in quotes to make sure that the command only has one argument. Denizen commands have arguments that are separated by spaces. For example, run one two three has arguments one, two, and three, but run "one two three" only has one argument, one two three.

Completed Product

At this point, you should have a task script that's ready to run! Go on, give it a try - first, type /ex reload in-game to load the new script in, then use the /ex run (YourTaskName) command to run the task in-game. For example, the in-game command to run the above script would be /ex run my_first_task.

If you see the text that you wrote for the narrate command, you've successfully written your first task script. Congratulations!

A Little Bit Further

To take what you learned here a little bit further, and bearing in mind that while we've been using the run command via /ex, it is a Denizen script command (the /ex command is just an in-game tool to quickly run any script command), let's look at an example that does just a little bit more than the previous ones.

You can also use one task script to trigger another task script. That looks like this:

my_first_task:
    type: task
    script:
    - narrate "This is a valid task script!"
    - narrate "Congratulations on writing your first script!"
    - run my_second_task

my_second_task:
    type: task
    script:
    - narrate "This is your second task script!"

This is just a basic example, and you'll be able to create more complicated and powerful scripts as you learn more about Denizen.

It's worth noting that in the example above, my_first_task and my_second_task are each a separate script container, and both can be within one script file, or different files - it doesn't make a difference to Denizen.

Related Technical Docs

If you want to read a lot more about task scripts, here are a few technical guides you might consider...

Note: most users, especially those learning from the Denizen for the first time, should just continue on to the next guides page. These references might be of interest to later come back to after you've learned Denizen as far as this guide teaches.

• Task script containers doc

• Run command doc