Differences

This shows you the differences between two versions of the page.

--- world_setup:game_features:tasks [2023/07/12 14:55] – [*dotask] mit
+++ world_setup:game_features:tasks [2023/07/12 16:08] (current) – [Example task process] mit
@@ Line 9: / Line 9: @@
 ===== Example task process =====
 To implement the tree 'building' example given above :
-  * Unordered List ItemUsing the building editor, create the building as a 'Scripted-NoWindow' type. For the purposes of the example we'll say its building type 10.
+  * 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>
@@ Line 36: / Line 36: @@
 </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] [TEXT] |
+^ 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]" )''
+''Event( "CustomTaskStart", "[TASK_CODE/CALLBACK]" )''
 then
-''Event( "TaskStart", "1" )''\\
+''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).
+(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
@@ Line 54: / Line 61: @@
 When the task completes (and assuming the player does not cancel or interrupt it) two further events are triggered:
-''Event( "CustomTaskComplete", "[TASK_CODE]" )''
+''Event( "CustomTaskComplete", "[TASK_CODE/CALLBACK]" )''
 then
-''Event( "TaskComplete", "1" )''\\
+''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 ====
-''*dobuildingtask [player] [BuildingRecordnum] [taskcode/callback] [text]''\\
+^ 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'' |
-==== *docombitask ====
+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 =====
@@ Line 75: / Line 109: @@
 ==== PlayerTaskStartSetTime( Seconds ) ====
-$gTaskItem1, $gTaskItem2, $gTaskItem3\\
+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).
-Specific
-Event( "TaskStart", .. )\\
+''Event( "TaskStart", "[TASK_TYPE]/[CALLBACK]" )''\\
-Event( "TaskComplete", .. )\\
+''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
-Event( "BuildingTaskStart", .. )\\
+***docombitask** and ***docombitaskparam** trigger: \\
-Event( "BuildingTaskComplete", .. )\\
+''Event( "CombiTaskStart", "[TASK_CODE/CALLBACK]" )''\\
-Event( "CustomTaskStart", .. )\\
+''Event( "CombiTaskComplete", "[TASK_CODE/CALLBACK]" )''\\
-Event( "CustomTaskComplete", .. )\\
-Event( "CombiTaskStart", .. )\\
-Event( "CombiTaskComplete", .. )\\