Tasks

THE MAIN ITEMS
Locations
Objects
Tasks
--- Specific
--- General
--- System
--- Executing sub-tasks
--- How tasks work
Characters
Events
Variables
Groups
Properties
Text Overrides
Hints
Synonyms
User functions

Everything that happens within an ADRIFT adventure is the result of a task. Tasks do things. All tasks have a set of restrictions (conditions that must be met in order for the task to run) and a set of actions (things that will be carried out if the task runs).

The ADRIFT command parser decides which task to run by matching what the player types with the commands defined in general tasks, and with the names of the objects, characters and locations in the game.

A task is like an IF statement in a programming language, when it is executed it first checks its restrictions to see if they pass. Each restriction contains text that is displayed to the player if it is the first one to fails.

If the restrictions pass then the task does two things, it displays the text in its main text box, and it performs the actions on its actions page.

There are three main types of task in ADRIFT 5. These are:

Specific tasks	Use these to define what happens when the player uses a command on a specific object, character or location, or in specific circumstances. This is the most common type of task that you will use.
General tasks	Use these to define new commands that the player can enter. You create a new general task if you want to use a command (verb) that is not defined in the standard library
System tasks	Controls what happens when the player first starts the game or whenever they enter a particular location

How ADRIFT decides which tasks to execute

Whenever the player types a command into Runner, ADRIFT searches through all of the General tasks in the Standard library as well as those that you have created yourself, trying to find any that match.

It does this is by pattern matching the command against each of the command definition lines in each general task.

In most cases there will only be one general task that matches what the player typed, but if more than one matches it will try the one with the highest Task priority.

If the task has been "Completed" (see "Task is Repeatable" below) then it is ignored and ADRIFT looks for the next match in priority order.

All of the restrictions of the general task must pass, otherwise one of two things will happen. If the first restriction that failed contained text, then that message is displayed and the player is prompted for their next command. If however it was blank, then ADRIFT will try the next matching general task in priority order.

ADRIFT now checks the Specific tasks that override that general task, and if it finds one that passes its own restrictions and matches the items that the player refered to, then that specific task is executed (its Actions are performed and the contents of its text box is displayed)

If none of the specific tasks override the general task, then it acts as a default, its actions are performed and its text box contents is displayed.

Task is Repeatable

At the bottom left corner of the task is a tickbox called "Task is Repeatable".

• If this is ticked then the task can be run any number of times.
• If it is not ticked then this task can only be run once, and will then be considered "completed" and will not be run again.

This almost always needs to be left ticked, the only time you would not tick it is if you have a specific or system task which is part of the story and which must only be able to execute its actions once. If this box is not ticked then, after this task has executed the first time, it will no longer take part in the matching of any future command. It will be as if this task no longer exists.

Note that you DONT need to do this to prevent the players score being incremented more than once by the same task, as ADRIFT contains special logic that prevents a particular task from changing the %score% variable more than once.

• There is a task restriction which can be used to check if a particular task has been completed or not.
• There is a task action called "unset task" which can be used to reset the "completed" flag, allowing it to run again.
• The "Execute Task" action ignores the "completed" flag and will always work.

Restrictions and Actions

The restrictions page of a task contains a Restrictions list which determines whether a task will be executed. When the command template on a general task matches the user input, or an attempt is made to execute a system task, Adrift checks these restrictions before deciding to execute the task. If the boolean relation of the Restrictions in this list evaluates to true, then the task executes:

• The "Message to display on completion" is shown.
• The Actions listed on the Actions page are executed.

NOTE: The order in which these are done can be changed on the "Advanced" page (see below).

If the boolean relation evaluates to false then the first restriction test that failed will display its failure message to the player.

If the restriction that failed has a completely blank text box then ADRIFT will try to execute the next matching task in priority order.

Hints

Hints are not yet functional in ADRIFT 5.

Advanced

On the Advanced tab are a series of settings that allow you to tweek how the task behaves and how it interacts with other tasks that also match the player input.

The ADRIFT developer must be in Advanced mode for this tab-page to be available.

The task priority determines which task Adrift should execute if more than one matches the players' input. The one with the lowest number in this field has the highest priority and will be executed first. The tasks in the Standard Library always have very large priority numbers, while the tasks that you create will initially be numbered in order of creation starting at 1. This means that any task you create will execute before any Standard Library task by default. You will only need to alter this field if you have two tasks which are both able to match the same player input and pass their restrictions at the same time, and you wish to change the order in which they are executed.

The "Auto-fill priority" is only available on General Tasks and is responsible for the auto-completion feature whereby the player only has to type part of a command or object name and the rest of the word will be filled in automatically. Normally a player will expect common commands such as "north" or "examine" to be chosen by this feature, but if you create a new command such as "exit" or "nobble" then you may need to change the value in this field to stop them being selected.

Setting the auto-fill priority to zero will prevent this general task's commands from ever being displayed by the auto-fill.

If "Prevent this task from being inherited" is selected on a General task then it will not be possible to override it with a specific task. You are unlikely to need to select this. One example where it is used is in the Take Objects (Parent Task) library task, because we want to override the Take Objects from Object or the Take Objects from Location tasks individually.

If you edit a library task, the "On load, if another task exists with the same key, this should replace it" checkbox becomes available. If you have multiple libraries, and those libraries contain the same key (for example, both libraries have a task with the key Inventory), the second library will import and the key will be renamed (e.g. to Inventory1). What this checkbox does is allows you to specify that the task should override any existing tasks with the same key. This is useful if you want to customise an existing library task.

The default behaviour is for the task execution logic is set on the Advanced Tab of the Options dialog. If the first option is selected then the highest priority task is executed whether it passes restrictions or not, and lower priority tasks are only used if that task has no text output at all, or if it has multiple matching enabled (see next paragraph). If the second option is selected then tasks that pass restrictions to override higher priority tasks that do not, even when the failing higher priority task has output. To change this behaviour, you need to check the "This task can be overridden by other task restriction failures (apart from other tasks with this checked)" checkbox on the lower priority task.

Whenever ADRIFT finds a task that matches user input and passes it's restrictions, it will run that task. If that task has output text, that text will be displayed and no more tasks will be checked. In some instances, you might want to continue to match lower priority tasks after the initial task has run. To do this, you would select the "Continue executing matching lower priority tasks (multiple matching)" checkbox.

A task can be run by calling it from another task with an "execute task" action and passing more than one key to a reference, or by the player specifying multiple objects, eg: "get the ball, the bat and the vase". The "Aggregate output, where possible" checkbox is normally ticked and causes each of the the text messages output by the task to be combined into one. For the above example this will produce "You take the ball, the bat and the vase.". If this checkbox is not ticked then a separate message is produced for object, eg: "You take the ball. You take the bat. You take the vase."

The drop-down list "Display completion message before/after executing actions" controls the order in which the task executes.

• Before: The contents of the tasks' text box is displayed first, then the Actions of the Actions tab are executed.
• After: The actions are executed first and then the text is displayed.

This is only important if:

• An action executes a task that produces text output.
• An action alters a variable which is then displayed as part of the text output.
• An action alters something which is used to determine if a restriction passes on an alternate description in the text box.

	If the "Message to display on completion" needs to display both values calculated by the actions as well the original values they had before the actions changed them, you can create a system task that contains only text and use an "execute task" action at the beginning or end of the other actions to display its text at the right time.
	If you find yourself changing this setting regularly, you can change the default value that new tasks are set to at the bottom of the first page of the Settings dialog.

Finally, the text box at the bottom allows a special message to be displayed, instead of the usual restriction failure message, if the player entered "All" instead of a specific object in the command.

<<< Objects

Main_Page

Specific tasks >>>