Task System Reference

The task system is a collection of commands, script events and UI elements that allow you to specify timed events during which the player is blocked from moving or interacting with other systems.

For example, you might have a tree 'building', and when the player accesses the tree a 'Chopping tree' task is started, the user is blocked from movement then after 10 seconds the task completes and they're granted some wood.

The task system also has some facilities that makes it useful as a crafting system, allowing the user to select 2 or 3 items to be combined to generate new items.

To implement the tree 'building' example given above :

• Using the building editor, create the building as a 'Scripted-NoWindow' type. For the purposes of the example we'll say its building type 10.
• Implement the building access script as shown:

Event( "AccessBuilding", "10" )
{
    *dobuildingtask %PLAYER% $gBuildingNum 0 Chopping wood
}

i.e. When the player accesses building type 10, a buildingtask is started - the parameters for the task are the player name, the ID number of the building, a generic param (0 for now) and the text we're going to show to the user.

• When the *dobuildingtask command is executed, a BuildingTaskStart event will be triggered ; in this event you can set the time the event will take, as shown:

Event( "BuildingTaskStart", "10" )
{
   PlayerTaskStartSetTime( 15 )
}

This means the task will run for 15 seconds. (During which time the player will be shown the 'Chopping Wood' message).

• Once the 15 seconds is up (and presuming the player didnt cancel the task before it finished), a BuildingTaskCompleted event is triggered.

Event( "BuildingTaskComplete", "10" )
{
   *grantitem %PLAYER% 5 Wood
}

(Then if you wanted to get real fancy, you could also use the *changebuilding command to change the tree building to one set up with a tree stump graphic - then perhaps use a ProductionRun event to turn the stump back into a tree building after its had time to regrow. That kinda thing, ya know..)

In the various task commands listed below, there are two ways of using the functions, either by using a TaskCode - which is an integer value, or a Callback - which is a text string.

The resulting script events triggered are slightly different depending on whether you're providing a TaskCode number or a Callback string.

Using *dotask triggers two events when the task starts:
Event( “CustomTaskStart”, “[TASK_CODE/CALLBACK]” ) then Event( “TaskStart”, “1/[CALLBACK]” )

(The two events are used because in some circumstances you'd want to react to a specific task_code, and sometimes you just want to do something whenever any *dotask event starts. Note that when using a 'Callback' text field, the TaskStart event needs to have the callback name in it too.).

In either of those events you can use the script command PlayerTaskStartSetTime( [SECONDS] ) to specify how long the task takes to complete.

When the task completes (and assuming the player does not cancel or interrupt it) two further events are triggered: Event( “CustomTaskComplete”, “[TASK_CODE/CALLBACK]” ) then Event( “TaskComplete”, “1/[CALLBACK]” )

Basic *dotask example

*dotaskparam is basically the same as *dotask with the addition of two parameter values, which you can access in the various task events through $gParam[1] and $gParam[2]

e.g. :

*dotaskparam %PLAYER% MyTask 100 150 Performing task

Event( "CustomTaskStart", "MyTask" )
{
   $var1 = $gParam[1]
   $var2 = $gParam[2]
   
   *say Parameters were $var1 and $var2
}

would print Parameters were 100 and 150

As with the *dotask equivalents, *dobuildingtaskparam just mirrors the *dobuildingtask command but allows the setting of some extra parameters that can be accessed in the task events.

Call this function from one of the TaskStart events to set the number of seconds that the task will last for.

These script System Values provide the item numbers that were used in the *docombitask command

*dobuildingtask and *dobuildingtaskparam trigger:
Event( “BuildingTaskStart”, “[BUILDING_CODE]” )
Event( “BuildingTaskComplete”, “[BUILDING_CODE]” )

*dotask and *dotaskparam trigger:
Event( “CustomTaskStart”, “[TASK_CODE/CALLBACK]” )
Event( “CustomTaskComplete”, “[TASK_CODE/CALLBACK]” )

TaskStart and TaskComplete events are triggered on all types of task (i.e. from all of the *do.. commands).

Event( “TaskStart”, “[TASK_TYPE]/[CALLBACK]” )
Event( “TaskComplete”, “[TASK_TYPE]/[CALLBACK]” )

When a numeric TaskCode is used in the task command, the event is triggered with a TASK_TYPE, where TASK_TYPE is:
0 : Combination Tasks (Tasks triggered with *docombitask and no text callback field)
1 : Standard/Custom Tasks (Tasks triggered with *dotask and no text callback field)
2 : Building Tasks (Tasks triggered with *dobuildingtask and no text callback field)

If you specify a callback name in the task command, this is used in the event instead. e.g. *dotask %PLAYER% CallbackText This is a task with a callback text
would trigger
Event( “TaskStart”, “CallbackText” )
and not
Event( “TaskStart”, “1” )

You probably don't need to use combination tasks unless you're doing something very funky. (They were used on some early worlds to build a complex, but probably rather daft, crafting system which used the combination of items to generate a single code that could be looked up to find the resulting item - e.g. combining items 12, 39 and 41 would generate a code 12039041 and there'd be an event that granted a certain item when that code appeared. Whacky).

Anyway.. for reference:

Combi tasks also make use of the system values :
$gTaskItem1, $gTaskItem2, $gTaskItem3
which correspond to the three values used in the combitask command

*docombitask and *docombitaskparam trigger:
Event( “CombiTaskStart”, “[TASK_CODE/CALLBACK]” )
Event( “CombiTaskComplete”, “[TASK_CODE/CALLBACK]” )