feat: create TaskScheduler, Task, and useful Actor subclasses of Task

feat: don't add task if already active

refactor: rename addTask to enqueue

feat: handle stacking/overriding of tasks

feat: add a BreakType property to tasks

feat: add a clear() method to the scheduler

feat: create TaskStackGroup enum

feat: add onStop callback to Task

refactor: create TaskConfig container type

feat: create ActorTask and WalkToTask

feat: make breakType an array

feat: allow `execute` to return a bool indicating task termination

feat: create Task subclasses for Actor

Author: Jameskmonger

src/engine/task/README.md

@@ -0,0 +1,25 @@
+# Task system
+
+This is a tick-based task system which allows for extensions of the `Task` class to be executed.
+
+Tasks can be executed after a delay, or immediately. They can also be set to repeat indefinitely or continue.
+
+## Scheduling a task
+
+You can schedule a task by registering it with the scheduler.
+
+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 {
+    public constructor() {
+        super(2);
+    }
+
+    public execute(): void {
+        sendGlobalMessage('2 ticks');
+    }
+});
+```
+
+Every two times that `taskScheduler.tick()` is called, it will run the `execute` function of your task.

src/engine/task/impl/actor-task.ts

@@ -0,0 +1,65 @@
+import { Subscription } from 'rxjs';
+import { Actor } from '@engine/world/actor';
+import { TaskBreakType, TaskConfig } from '../types';
+import { Task } from '../task';
+
+/**
+ * A task that is executed by an actor.
+ *
+ * If the task has a break type of ON_MOVE, the ActorTask will subscribe to the actor's
+ * movement events and will stop executing when the actor moves.
+ *
+ * @author jameskmonger
+ */
+export abstract class ActorTask<TActor extends Actor = Actor> extends Task {
+    /**
+     * A function that is called when a movement event is queued on the actor.
+     *
+     * This will be `null` if the task does not break on movement.
+     */
+    private walkingQueueSubscription: Subscription | null = null;
+
+    /**
+     * @param actor The actor executing this task.
+     * @param config The task configuration.
+     */
+    constructor(
+        protected readonly actor: TActor,
+        config?: TaskConfig
+    ) {
+        super(config);
+
+        this.listenForMovement();
+    }
+
+    /**
+     * Called when the task is stopped and unsubscribes from the actor's walking queue if necessary.
+     *
+     * TODO (jameskmonger) unit test this
+     */
+    public onStop(): void {
+        if (this.walkingQueueSubscription) {
+            this.walkingQueueSubscription.unsubscribe();
+        }
+    }
+
+    /**
+     * If required, listen to the actor's walking queue to stop the task
+     *
+     * This function uses `setImmediate` to ensure that the subscription to the
+     * walking queue is not created
+     *
+     * TODO (jameskmonger) unit test this
+     */
+    private listenForMovement(): void {
+        if (!this.breaksOn(TaskBreakType.ON_MOVE)) {
+            return;
+        }
+
+        setImmediate(() => {
+            this.walkingQueueSubscription = this.actor.walkingQueue.movementQueued$.subscribe(() => {
+                this.stop();
+            });
+        });
+    }
+}

src/engine/task/impl/actor-walk-to-task.ts

@@ -0,0 +1,105 @@
+import { Position } from '@engine/world/position';
+import { Actor } from '@engine/world/actor';
+import { TaskStackType, TaskBreakType, TaskStackGroup } from '../types';
+import { ActorTask } from './actor-task';
+
+/**
+ * This ActorWalkToTask interface allows us to merge with the ActorWalkToTask class
+ * and add optional methods to the class.
+ *
+ * There is no way to add optional methods directly to an abstract class.
+ *
+ * @author jameskmonger
+ */
+export interface ActorWalkToTask<TActor extends Actor = Actor> extends ActorTask<TActor> {
+    /**
+     * An optional function that is called when the actor arrives at the destination.
+     */
+    onArrive?(): void;
+}
+
+/**
+ * An abstract task that will make an Actor walk to a specific position,
+ * before calling the `arrive` function and continuing execution.
+ *
+ * The task will be stopped if the adds a new movement to their walking queue.
+ *
+ * @author jameskmonger
+ */
+export abstract class ActorWalkToTask<TActor extends Actor = Actor> extends ActorTask<TActor> {
+    private _atDestination: boolean = false;
+
+    /**
+     * `true` if the actor has arrived at the destination.
+     */
+    protected get atDestination(): boolean {
+        return this._atDestination;
+    }
+
+    /**
+     * @param actor The actor executing this task.
+     * @param destination The destination position.
+     * @param distance The distance from the destination position that the actor must be within to arrive.
+     */
+    constructor (
+        actor: TActor,
+        protected readonly destination: Position,
+        protected readonly distance = 1,
+    ) {
+        super(
+            actor,
+            {
+                interval: 1,
+                stackType: TaskStackType.NEVER,
+                stackGroup: TaskStackGroup.ACTION,
+                breakTypes: [ TaskBreakType.ON_MOVE ],
+                immediate: false,
+                repeat: true,
+            }
+        );
+
+        this.actor.pathfinding.walkTo(destination, { })
+    }
+
+    /**
+     * Every tick of the task, check if the actor has arrived at the destination.
+     *
+     * You can check `this.arrived` to see if the actor has arrived.
+     *
+     * If the actor has previously arrived at the destination, but is no longer within distance,
+     * the task will be stopped.
+     *
+     * @returns `true` if the task was stopped this tick, `false` otherwise.
+     *
+     * TODO (jameskmonger) unit test this
+     */
+    public execute() {
+        if (!this.isActive) {
+            return;
+        }
+
+        // TODO this uses actual distances rather than tile distances
+        //      is this correct?
+        const withinDistance = this.actor.position.withinInteractionDistance(this.destination, this.distance)
+
+        // the WalkToTask itself is complete when the actor has arrived at the destination
+        // execution will now continue in the extended class
+        if (this._atDestination) {
+            // TODO consider making this optional
+            if (!withinDistance) {
+                this._atDestination = false;
+                this.stop();
+            }
+
+            return;
+        }
+
+        if (withinDistance) {
+            this._atDestination = true;
+
+            if (this.onArrive) {
+                this.onArrive();
+            }
+        }
+    }
+}

src/engine/task/impl/actor-world-item-interaction-task.ts

@@ -0,0 +1,79 @@
+import { WorldItem } from '@engine/world';
+import { Actor } from '../../world/actor/actor';
+import { ActorWalkToTask } from './actor-walk-to-task';
+
+/**
+ * A task for an actor to interact with a world item.
+ *
+ * This task extends {@link ActorWalkToTask} and will walk the actor to the world item.
+ * Once the actor is within range of the world item, the task will expose the {@link worldItem} property
+ *
+ * @author jameskmonger
+ */
+export abstract class ActorWorldItemInteractionTask<TActor extends Actor = Actor> extends ActorWalkToTask<TActor> {
+    private _worldItem: WorldItem;
+
+    /**
+     * Gets the world item that this task is interacting with.
+     *
+     * @returns If the world item is still present, and the actor is at the destination, the world item.
+     *              Otherwise, `null`.
+     *
+     * TODO (jameskmonger) unit test this
+     */
+    protected get worldItem(): WorldItem | null {
+        // TODO (jameskmonger) consider if we want to do these checks rather than delegating to the child task
+        //                      as currently the subclass has to store it in a subclass property if it wants to use it
+        //                      without these checks
+        if (!this.atDestination) {
+            return null;
+        }
+
+        if (!this._worldItem || this._worldItem.removed) {
+            return null;
+        }
+
+        return this._worldItem;
+    }
+
+    /**
+     * @param actor The actor executing this task.
+     * @param worldItem The world item to interact with.
+     */
+    constructor (
+        actor: TActor,
+        worldItem: WorldItem,
+    ) {
+        super(
+            actor,
+            worldItem.position,
+            1
+        );
+
+        if (!worldItem) {
+            this.stop();
+            return;
+        }
+
+        this._worldItem = worldItem;
+
+    }
+
+    /**
+     * Checks for the continued presence of the world item and stops the task if it is no longer present.
+     *
+     * TODO (jameskmonger) unit test this
+     */
+    public execute() {
+        super.execute();
+
+        if (!this.isActive || !this.atDestination) {
+            return;
+        }
+
+        if (!this._worldItem || this._worldItem.removed) {
+            this.stop();
+            return;
+        }
+    }
+}

src/engine/task/impl/index.ts

@@ -0,0 +1,3 @@
+export { ActorTask } from './actor-task'
+export { ActorWalkToTask } from './actor-walk-to-task'
+export { ActorWorldItemInteractionTask } from './actor-world-item-interaction-task'

src/engine/task/index.ts

@@ -0,0 +1,3 @@
+export { Task } from './task'
+export { TaskScheduler } from './task-scheduler'
+export { TaskStackType, TaskBreakType, TaskStackGroup, TaskConfig } from './types'

src/engine/task/task-scheduler.test.ts

@@ -0,0 +1,106 @@
+import { Task } from './task';
+import { TaskScheduler } from './task-scheduler';
+import { TaskStackType } from './types';
+import { createMockTask } from './utils/_testing';
+
+describe('TaskScheduler', () => {
+    let taskScheduler: TaskScheduler;
+    beforeEach(() => {
+        taskScheduler = new TaskScheduler();
+    });
+
+    describe('when enqueueing a task', () => {
+        let executeMock: jest.Mock;
+        let task: Task
+        beforeEach(() => {
+            ({ task, executeMock } = createMockTask());
+        });
+
+        it('should add the task to the running list when ticked', () => {
+            taskScheduler.enqueue(task);
+            taskScheduler.tick();
+            expect(executeMock).toHaveBeenCalled();
+        });
+
+        it('should not add the task to the running list until the next tick', () => {
+            taskScheduler.enqueue(task);
+            expect(executeMock).not.toHaveBeenCalled();
+        });
+
+        describe('when ticked multiple times', () => {
+            beforeEach(() => {
+                taskScheduler.enqueue(task);
+                taskScheduler.tick();
+                taskScheduler.tick();
+            });
+
+            it('should tick the task twice', () => {
+                expect(executeMock).toHaveBeenCalledTimes(2);
+            });
+        });
+
+        describe('when the task is stopped', () => {
+            beforeEach(() => {
+                taskScheduler.enqueue(task);
+                taskScheduler.tick();
+            });
+
+            it('should not tick the task after stopping', () => {
+                task.stop();
+                taskScheduler.tick();
+                expect(executeMock).toHaveBeenCalledTimes(1);
+            });
+        });
+    });
+
+    describe('when enqueueing a task that cannot stack', () => {
+        const interval = 0;
+        const stackType = TaskStackType.NEVER;
+        const stackGroup = 'foo';
+
+        let firstExecuteMock: jest.Mock;
+        let firstTask: Task
+        beforeEach(() => {
+            ({ task: firstTask, executeMock: firstExecuteMock } = createMockTask(interval, stackType, stackGroup));
+        });
+
+        it('should stop any other tasks with the same stack group', () => {
+            const { task: secondTask, executeMock: secondExecuteMock } = createMockTask(interval, stackType, stackGroup);
+
+            taskScheduler.enqueue(firstTask);
+            taskScheduler.enqueue(secondTask);
+            taskScheduler.tick();
+
+            expect(firstExecuteMock).not.toHaveBeenCalled();
+            expect(secondExecuteMock).toHaveBeenCalled();
+        });
+
+        it('should not stop any other tasks with a different stack group', () => {
+            const otherStackGroup = 'bar';
+            const { task: secondTask, executeMock: secondExecuteMock } = createMockTask(interval, stackType, otherStackGroup);
+
+            taskScheduler.enqueue(firstTask);
+            taskScheduler.enqueue(secondTask);
+            taskScheduler.tick();
+
+            expect(firstExecuteMock).toHaveBeenCalled();
+            expect(secondExecuteMock).toHaveBeenCalled();
+        });
+    });
+
+    describe('when clearing the scheduler', () => {
+        let executeMock: jest.Mock;
+        let task: Task
+        beforeEach(() => {
+            ({ task, executeMock } = createMockTask());
+        });
+
+        it('should stop all tasks', () => {
+            taskScheduler.enqueue(task);
+            taskScheduler.tick();
+            taskScheduler.clear();
+            taskScheduler.tick();
+            expect(executeMock).toHaveBeenCalledTimes(1);
+        });
+    });
+});