====== 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 :
  * 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:
<code>
Event( "AccessBuilding", "10" )
{
    *dobuildingtask %PLAYER% $gBuildingNum 0 Chopping wood
}
</code>
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:
<code>
Event( "BuildingTaskStart", "10" )
{
   PlayerTaskStartSetTime( 15 )
}
</code>
This means the task will run for 15 seconds. (During which time the player will be shown the 'Chopping Wood' message).
<note>If you don't set a specific task time in the TaskStart event, the task will default to being 2 minutes long.
</note>
  * Once the 15 seconds is up (and presuming the player didnt cancel the task before it finished), a BuildingTaskCompleted event is triggered.
<code>
Event( "BuildingTaskComplete", "10" )
{
   *grantitem %PLAYER% 5 Wood
}
</code>
(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]" )''\\
\\
[[Scripting:Samples:SimpleTask|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. : 
<code>
*dotaskparam %PLAYER% MyTask 100 150 Performing task

Event( "CustomTaskStart", "MyTask" )
{
   $var1 = $gParam[1]
   $var2 = $gParam[2]
   
   *say Parameters were $var1 and $var2
}
</code>
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]" )''\\