General tasks

From ADRIFT 5 Manual Wiki
Jump to: navigation, search
---- Specific
---- General
---- System
---- Executing sub-tasks
---- How tasks work
Text Overrides
User functions

General tasks are used to add a new command that is not provided by the standard library.

Creating a General Task

To create a new General task, click on the Task button at the top of the screen, or right-click in a folder and select Add New > Task. This brings up the New Task form. This defaults to Specific tasks (more on these later) because that is the most common task type, so click on the General button to change the task type. This should bring up a screen like so:


Here, you must specify the command that the player must type in order to match this command. A really simple case might just be something like:


Then, whenever anyone types the command "dig" into Runner, this task will match. If a task matches the command, its restrictions will be checked, and if all restrictions are met, the task will run. So General Tasks essentially enable you to create new verbs that the parser understands.

More often than not, you might want to refer to an object or character in your task. So you might want to create a command such as:

drop the vase

There are several problems with this. The first, is that the player might type something slightly differently in the game, but mean the same thing. This is commonly known as "guess the verb". For example, the player might be holding the vase, and type "put the vase down". Obviously this wouldn’t match the command you specified. To get around this there are three things you can do. Firstly, you can enter multiple commands. So, you could set the task up with the commands:

drop the vase
put down the vase
put the vase down

So now, we instantly have three ways we can match this command. In this example, having three commands isn’t too bad, but consider a slightly more complicated example of putting something inside something else. You could have:

put the flower in the vase
drop the flower in the vase
put the flower inside vase
drop the flower inside the vase
put flower into the vase

Etc etc. As you can see, the number of possibilities can rapidly increase the more complex the statement becomes. To get around this problem, ADRIFT understands "advanced command construction". This allows you to create multiple ways to define the command on a single line.

Advanced Command Construction

Advanced Command Construction, commonly abbreviated to ACC, allows you to define words within the command as being mandatory or optional, and to also give a choice between different words. You can create a choice between words by separating them with a forward slash "/". Words inside square brackets are mandatory, and words inside curly brackets are optional.

So going back to our earlier example, you could reduce this from three commands to two:

[drop/put down] {the} vase
put {the} vase down

ADRIFT now understands a total of six different ways of saying the same thing.

Similarly, the second example above could be reduced from 36 individual commands to the following:

[put/drop] {a/the} flower in{to/side} {the} vase


A third way of matching commands in ADRIFT is to make use of wildcards. This allows you to match anything a user types against part of your command. For example, you could create a command:

drop * in*		

(note the lack of space between in and *)

This would now match anything such as "drop the ball in the box", or "drop match into the large can of petrol".

A word of warning though; wildcards really are just that. They could end up matching on things that you really haven't considered when designing the game. For example, it would also match on "drop everything except the match into the petrol". This may end up being the exact opposite of what you intended. Therefore, it is recommended you use wildcards only when absolutely necessary.


In the examples above, we refer to an object "the vase". This object may have been defined as

[a] [large fragile] [vase]

Because of the articles "large" and "fragile", which may or may not be used when referring to the vase, we need each command to understand both the articles being there and also not being there. The object could also have been set up with alternative nouns (a cup could be a mug, a lamp a light, a box a carton etc), and we would have to cater for all of these4.

To make things easier, ADRIFT has the concept of References. There are several types of references. These are Objects, Characters, Directions, Number and Text. References are essentially placeholders within the task command that can match on any object, character etc. References are simply entered as a keyword between two percent symbols. So to recreate the earlier example, we would have:

[drop/put down] %object%
put %object% down

This greatly simplifies how you define the task commands, as you do not have to consider all the ways of writing object/character names. Also, if you later change the object name, you don't have to go back and change all your tasks. Simply put, General Tasks should never refer to object/character names unless absolutely necessary.

You can also have multiple references within the same command, for example:

put %object% in{side/to} %object2%	

If you have multiple commands within the same task, each command must contain the same references. So in the first references example, both commands contain %object%. You couldn’t create another command that missed the reference out.

Also, each reference must be unique within a command. So for example, if you wish to refer to more than one object, you must use %object% and %object2%, rather than %object% and %object%.

A full list of references that ADRIFT understands is as follows:

%object%, %object2%, %object3%, %object4%, %object5%, %objects%, 
%character%, %character2%, %character3%, %character4%, %character5%, %characters%, 
%direction%, %number%, %text%, %location%, %item%

IconWarning.png %object% %object1% and %objects% all refer to the same reference. You cannot use more than one of these in the one task. The second object reference should always be %object2%.

IconWarning.png In the current version (5.0.32) all references of the same type must be in numerical order! You can have %objects% %object2% but the order %object2% %objects% will not work.

You will notice the plural references %objects% and %characters% above. These references are even more powerful than the other references, because they can match on multiple objects. So you could refer to, for example, "the red ball and the green ball", "all except the pink ball" or "all small balls".

The %item% reference allows the player to enter the name of an object, a character or a location. Hence you could make a "smell %item%" task which prints the value of an item property that specifies the odour of anything in the game.

As soon as you create a reference in your task, all the Restriction and Action dropdowns have extra options in them to allow you to test and manipulate whatever object or character the player refers to. So in our "drop" command above we can add a restriction that the referenced object must be held by the player. If so, our task will match and we run its actions, which we could define as moving the referenced object to the same location as the player.


Scope refers to where ADRIFT will look when you refer to an item. ADRIFT 5 has three levels of scope. These are Applicable, Visible, and Seen. Visible and Seen should be pretty obvious. Applicable means it must match any task restrictions on the task creating the reference.

When you create a task that references an object or character, ADRIFT will check the scope to see which one you are referring to. So, say you create a task

eat %object% 

You may add a restriction that the referenced object must have a property 'edible'.

So, say you create two objects, "a chocolate button" and "a large red button", and give the former the property "edible". If you then type "eat button", ADRIFT will first check to find all objects that match the applicable scope. There are two buttons, but only one of them is in applicable scope (because the Eat Object task has a restriction that objects must have the "edible" property), and so ADRIFT will automatically assume you mean the chocolate button. If the chocolate button didn’t have the edible property, neither buttons will match applicable scope, and so ADRIFT will look to see which ones are visible. If only one is visible, ADRIFT will assume that’s the button you are referring to. If neither are visible, ADRIFT will check to see which ones you have seen before. So if you have come across the red button in the game but not the chocolate button ADRIFT will assume you are referring to the red button. If, after all three levels of scope have been checked and there are still multiple possibilities, ADRIFT will prompt for disambiguation.

1 There are actually two types of tasks in ADRIFT 4. Those with # symbols at the start to prevent the user typing the command (i.e. System tasks in ADRIFT 5), and those without (i.e. General tasks in ADRIFT 5).

2 General Tasks are the equivalent of normal tasks in ADRIFT 4.

3 General tasks should not refer to individual objects unless absolutely necessary. See Best Practice section.

4 For those of you familiar with ADRIFT 4, this was one of the problems with the parser, because the task command may not cover all the possibilities of the built-in parser.

Message to display on completion

In the bottom half of the Description page is a text box that contains the message to be displayed if this task is matched to the user input and passes all of its restrictions.

As well as displaying text (which can include General Functions) a text box can also control the display of images and the playing of sounds at the same time as the text is output.

A text box can also use Alternate Descriptions to change the text that is output in different circumstances.

<<< Specific tasksMain_PageSystem tasks >>>