docs: add docs around Task configuration and subtypes

docs: add docs around Task configuration

docs: add docs on task subtypes

docs: update progress tracker

docs: update documentation

Author: Jameskmonger

src/engine/task/README.md

@@ -1,91 +1,139 @@
 # Task system
 
-This is a tick-based task system which allows for extensions of the `Task` class to be executed.
+The task system allows you to write content which will be executed on the tick cycles of the server.
 
-Tasks can be executed after a delay, or immediately. They can also be set to repeat indefinitely or continue.
+You can configure a task to execute every `n` ticks (minimum of `1` for every tick), and you can also choose a number of other behaviours, such as whether the task should execute immediately or after a delay, as well as set to repeat indefinitely.
 
 ## Scheduling a task
 
-You can schedule a task by registering it with the scheduler.
+You can schedule a task by registering it with a `TaskScheduler`.
 
 The task in the example of below runs with an interval of `2`, i.e. it will be executed every 2 ticks.
 
 ```ts
-this.taskScheduler.addTask(new class extends Task {
+class MyTask extends Task {
     public constructor() {
         super({ interval: 2 });
     }
 
     public execute(): void {
-        sendGlobalMessage('2 ticks');
+        console.log('2 ticks');
     }
-});
+}
+
+const scheduler = new TaskScheduler();
+
+scheduler.addTask(new MyTask());
+
+scheduler.tick();
+scheduler.tick(); // '2 ticks'
+```
+
+Every two times that `scheduler.tick()` is called, it will run the `execute` function of your task.
+
+## Task configuration
+
+You can pass a `TaskConfig` object to the `Task` constructor in order to configure various aspects of your task.
+
+### Timing
+
+The most simple configuration option for a `Task` is the `interval` option. Your task will be executed every `interval` amount of ticks.
+
+```ts
+/**
+* The number of ticks between each execution of the task.
+*/
+interval: number;
+```
+
+For example, with an interval of `1`, your task will run every tick. The default value is `1`.
+
+### Immediate execution
+
+You can configure your task to execute immediately with the `immediate` option.
+
+```ts
+/**
+* Should the task be executed on the first tick after it is added?
+*/
+immediate: boolean;
+```
+
+For example, if `immediate` is `true` and `interval` is `5`, your task will run on the 1st and 6th ticks (and so on).
+
+### Repeating
+
+You can use the `repeat` option to tell your task to run forever.
+
+```ts
+/**
+* Should the task be repeated indefinitely?
+*/
+repeat: boolean;
+```
+
+You can use `this.stop()` inside the task to stop it from repeating further.
+
+### Stacking
+
+The `stackType` and `stackGroup` properties allow you to control how your task interacts with other, similar tasks.
+
+```ts
+/**
+* How the task should be stacked with other tasks of the same stack group.
+*/
+stackType: TaskStackType;
+
+/**
+* The stack group for this task.
+*/
+stackGroup: string;
 ```
 
-Every two times that `taskScheduler.tick()` is called, it will run the `execute` function of your task.
+When `stackType` is set to `TaskStackType.NEVER`, other tasks with the same `stackGroup` will be stopped when your task is enqueued. A `stackType` of `TaskStackType.STACK` will allow your task to run with others of the same group.
+
+The default type is `TaskStackType.STACK` and the group is `TaskStackGroup.ACTION` (`'action'`)
+
+## Task Subtypes
+
+Rather than extending `Task`, there are a number of subclasses you can extend which will give you some syntactic sugar around common functionality.
 
-# Implementing this into RuneJS
+- `ActorTask`
 
-## Task System
+    This is the base task to be performed by an `Actor`. It will automatically listen to the actor's walking queue, and stop the task if it has a `breakType` of `ON_MOVE`.
 
-- Tick-based task scheduler :heavy_check_mark:
-- Delay task :heavy_check_mark:
-- Repeating task :heavy_check_mark:
-- Schedule tasks on world :heavy_check_mark:
-- Schedule tasks on players/npcs :heavy_check_mark:
-- Task stacking :heavy_check_mark:
-- Task breaking on walking :heavy_check_mark:
-- Task delay until arriving :heavy_check_mark:
+- `ActorWalkToTask`
 
-### Subtasks
+    This task will make an actor walk to a `Position` or `LandscapeObject` and will expose the `atDestination` property for your extended task to query. You can then begin executing your task logic.
 
-#### Actor
+- `ActorLandscapeObjectInteractionTask`
 
-- Actor task :heavy_check_mark:
-    - Handle break on move :heavy_check_mark:
-- Actor to actor interaction task :think: :x:
-    - Handle walkto :x:
-    - Keep track of interaction distance and stop if exceeded :x:
-- Actor to world item interaction task :heavy_check_mark:
-    - Handle walkto :heavy_check_mark:
-    - Keep track of interaction distance and stop if exceeded :heavy_check_mark:
-- Actor to object interaction task :think: :x:
-    - (maybe need some generic Actor to entity interaction task)
-    - Handle walkto :x:
-    - Keep track of interaction distance and stop if exceeded :x:
+    This task extends `ActorWalkToTask` and will make an actor walk to a given `LandscapeObject`, before exposing the `landscapeObject` property for your task to use.
 
-#### World
+- `ActorWorldItemInteractionTask`
 
-- World task :yellow_square:
-- Spawn game object task :x:
-- Remove game object task :x:
-- Spawn world item task :x:
-- Remove world item task :x:
+    This task extends `ActorWalkToTask` and will make an actor walk to a given `WorldItem`, before exposing the `worldItem` property for your task to use.
 
-### Content
+# Future improvements
+
+- Stalling executions for certain tasks when interface is open
+    - should we create a `PlayerTask` to contain this behaviour? The `breakType` behaviour could be moved to this base, rather than `ActorTask`
+
+- Consider refactoring this system to use functional programming patterns. Composition should be favoured over inheritance generally, and there are some examples of future tasks which may be easier if we could compose tasks from building blocks. Consider the implementation of some task which requires both a `LandscapeObject` and a `WorldItem` - we currently would need to create some custom task which borrowed behaviour from the `ActorLandscapeObjectInteractionTask` and `ActorWorldItemInteractionTask`. TypeScript mixins could be useful here.
+
+# Content requiring conversion to task system
 
 Highest priority is to convert pieces of content which make use of the old `task` system. These are:
 
-- Magic attack :x:
-- Magic teleports :x:
-- Prayer :yellow_square:
-    - ensure that one-tick pray flicking works. Speak to @jameskmonger if you want to implement this and need guidance
-- Combat :x:
-    - this one is quite broken and may not be so easy to port across
-- Forging (smithing) :x:
-- Woodcutting :yellow_square:
-    - Time to cut :heavy_check_mark:
-    - Replace tree with treestump :yellow_square:
-    - Replace treestump with tree :yellow_square:
+- Magic attack
+- Magic teleports
+- Prayer
+- Combat
+- Forging (smithing)
+- Woodcutting
 
 The following areas will make interesting use of the task system and would serve as a good demonstration:
 
-- Health regen :x:
-- NPC movement :x:
-- Firemaking :yellow_square:
-    - logs in inventory :heavy_check_mark:
-    - logs on ground :heavy_check_mark:
-    - all log types :yellow_square:
-    - spawn ashes :x:
-
-Also any content @gruckion is working on will be using the new Task system to aid with development of the API
+- Health regen
+- NPC movement
+- Firemaking

src/engine/task/task.ts

@@ -1,7 +1,7 @@
 import { TaskBreakType, TaskConfig, TaskStackGroup, TaskStackType } from './types';
 
 const DEFAULT_TASK_CONFIG: Required<TaskConfig> = {
-    interval: 0,
+    interval: 1,
     stackType: TaskStackType.STACK,
     stackGroup: TaskStackGroup.ACTION,
     immediate: false,
@@ -40,12 +40,34 @@ export interface Task {
  * @author jameskmonger
  */
 export abstract class Task {
+    /**
+     * How the task should be stacked with other tasks of the same stack group.
+     */
     public readonly stackType: TaskStackType;
+
+    /**
+     * The stack group for this task.
+     */
     public readonly stackGroup: string;
+
+    /**
+     * Conditions under which the task should be broken.
+     */
     public readonly breakTypes: TaskBreakType[];
 
+    /**
+     * The number of ticks between each execution of the task.
+     */
     private interval: number;
+
+    /**
+     * The number of ticks remaining before the task is executed.
+     */
     private ticksRemaining: number;
+
+    /**
+     * Should the task be repeated indefinitely?
+     */
     private repeat: boolean;
 
     private _isActive = true;

src/engine/task/types.ts

@@ -49,10 +49,33 @@ export enum TaskBreakType {
  * @author jameskmonger
  */
 export type TaskConfig = Partial<Readonly<{
+    /**
+     * How the task should be stacked with other tasks of the same stack group.
+     */
     stackType: TaskStackType;
+
+    /**
+     * The stack group for this task.
+     */
     stackGroup: string;
+
+    /**
+     * Conditions under which the task should be broken.
+     */
     breakTypes: TaskBreakType[];
+
+    /**
+     * The number of ticks between each execution of the task.
+     */
     interval: number;
+
+    /**
+     * Should the task be executed on the first tick after it is added?
+     */
     immediate: boolean;
+
+    /**
+     * Should the task be repeated indefinitely?
+     */
     repeat: boolean;
 }>>;