Table of Contents

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.

Example task process

To implement the tree 'building' example given above :

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.

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).

If you don't set a specific task time in the TaskStart event, the task will default to being 2 minutes long.
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..)

Task Codes or Callbacks

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.

Task commands

*dotask

Format *dotask [PLAYER_NAME] [TASK_CODE/CALLBACK] [TEXT]
Description Activates the task display for the specified player.
Example *dotask %PLAYER% CallbackName Display message

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

Format *dotaskparam [PLAYER_NAME] [TASK_CODE/CALLBACK] [PARAM1] [PARAM2] [TEXT]
Description Activates the task display for the specified player, with parameters that can be access via script.
Example *dotaskparam %PLAYER% CallbackName 199 210 Display message

*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

*dobuildingtask

Format *dobuildingtask [PLAYER_NAME] [BUILDING_ID] [TASKCODE/CALLBACK] [DISPLAY_TEXT]
Description Activates the task display for the specified player in relation to the specified building.
Example *dobuildingtask %PLAYER% $nearestBuildingID 99 Running building task

*dobuildingtaskparam

Format *dobuildingtask [PLAYER_NAME] [BUILDING_ID] [TASKCODE/CALLBACK] [PARAM1] [PARAM2] [DISPLAY_TEXT]
Description Activates the task display for the specified player in relation to the specified building.
Example *dobuildingtask %PLAYER% $nearestBuildingID MyTask 333 444 Running building task

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.

*showtask

Format *showtask [PLAYER_NAME]
Description This is a sysop/debug command that tells you the current state of the task for the specified player

Task scripting

PlayerTaskStartSetTime( Seconds )

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” )

Combination tasks

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:

*docombitask

Format *docombitask [PLAYER_NAME] [ITEM1] [ITEM2] [ITEM3]
Description Activates the task display for the specified player with relation to the specified item numbers
Example *docombitask %PLAYER% $item1 $item2 $item3

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]” )