Executing sub-tasks

From ADRIFT 5 Manual Wiki
Jump to: navigation, search
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

A single ADRIFT task checks its restrictions and if they pass it performs its actions and displays its text.

Basically it is a single IF <restrictions> THEN <perform actions and display text> ELSE <display first failing restriction message> statement.

In most cases this is all you need, but what if you want to output text both before and after the actions, or if you want to perform an action that is more complex than the one's provided by ADRIFT.

No matter what you want to do, it is possible to do it in ADRIFT by using execute-task actions to run sub-tasks that contain extra restrictions, and can operate on the result of an item function instead of the original item references.

Execute Task Action

To execute a sub-task, create a new action and select the "Task" tab:

ExecuteClimbObject.jpg

This action can execute any task, general, specific or system. If you are creating a new task to use as a sub-task then you should create a system task if you don't need to pass parameters to it, or a general task if you do.

Executing a system task to print text

There are several reasons to create a system task that only displays text, and execute it with an action.

  1. It allows you to keep one copy of a large block of text that you want to display in several tasks.
  2. You may need to display some text before executing actions, and some after.
  3. You may have a complex arrangement of alternate restrictions that you don't want to duplicate every time you need it.

TaskSystem.jpg

This system task simply prints the players current score and then uses a series of alternate descriptions based on that score to name the level that they have reached.

"Run this task when:" is set to "Only when called by event/task", which means that it is only executed if a sub event has been set to "execute task", or if we include an action in another task that executes this one.

Executing a system task to add conditional actions

Sometimes you may have several actions that you want to perform when a task executes, but some of those actions should only be performed some of the time.

You can do this by moving the conditional actions to a system task and adding restrictions that prevent them from being performed when those restrictions fail.

If main task passes its own restrictions it will perform its actions, including one to call the new system task.

The system task checks its own restrictions before executing, so its actions are only performed if BOTH its own restrictions and the main task's restrictions have all passed.

You can execute as many of these as you want from the main task, each one with different restrictions. For example you could execute two sub-tasks which have completely opposite restrictions so that one or the other will be executed, not both.

Executing a general task for advanced processing

TaskGeneralSub.jpg

Note the use of the # symbol at the start of the command line. This tells ADRIFT that this task does not contain a command and should be ignored by the command parser.

After the #, you can add any combination of references (%object1% to %object5%, %objects%, %character1% to %character5%, %characters%, %direction%, %number%, %text% and %location%)

These references can then be used in the usual manner in the restrictions and actions of the task.

When you now execute this task from an action in another task, you will be presented with a series of parameter entry dialogs, one for each reference that you defined:

ActionTaskParameter.jpg

In the simplest case you might pass on the references of the main task to the sub-task so it can use them, but you are also able to use the full power of the general and item functions to generate whatever reference you need.

Using a list of items to execute a sub-task multiple times

If you use an item function to access the list of objects on or in another object, or worn/held by a character, then the sub-task will be executed once for each item in that list.

ActionTaskParameterHeld.jpg

The sub-task can contain restrictions that prevents the task being executed for some members of the list, effectively filtering the list so only certain members are processed.

The actions of the sub-task are performed independantly for each member of the list that passed restrictions. You could for example check the players inventory for all objects that have the property "Valuable" and have them transfered to the inventory of the character who is robbing them.

The contents of the sub-tasks text box is however only printed once, but ADRIFT combines all of the items that passed restrictions so that the text "The thief steals your %object%.Name(possessive)" will print "The thief steals your red ruby, gold bar and share certificate" if those were the three items.

To have the sub-task print a separate message for each item, uncheck the "Aggregate output, where possible" option on the Advanced page of the sub-task.

Using a group as a parameter

If you pass the key of a character group, object group or location group as a parameter, then the %character%, %object% or %location% reference in the task will actually be a group so you can use any group function with the group, such as a filter or the list and count functions.

  • Note that this only runs the task once, and you cannot use any action that uses the [Referenced Object] reference. Only group functions such as "%object%.List" and "%object%.Count" can be used in the text.

To instead run the task for each member of the group individually, as we did for lists in the section above, you will need to use a filter function after the group key.

If you want to process every member of the group without filtering it, then you will need to create a dummy selection-only property and make the property "Mandatory" so that every member of the group will have it set.

Make this a property of "Any Item", not just objects, so that the same property can be used with every group.

IconWarning.png In version 5.0.31 of ADRIFT you will need to open and then click on OK for every existing item that you want to set in the group, so that this property is added.

In the parameter of the execute task action, you need to use the group key followed by a dot, followed by the key of this property.

MagicItems.Items

In this example "MagicItems" is the key of the group and "Items" is the key of the new property.

Nested Subtasks

There is no reason why a sub-task should not contain actions which call yet more tasks.

This technique allows very complex operations to be built up a layer at a time, for example you could check the neighboring locations to the players location to see which ones are indoors, get all containers at those locations, check which ones are open and if any of those contain a certain kind of object then make something happen.

IconWarning.png It is highly recomended that all of the sub-tasks and sub-sub-tasks have their "Aggregeate output, where possible" option turned OFF (not ticked on their advanced page) when using nested sub-tasks.


<<< General tasksMain_PageHow tasks work >>>