feat: add behavior tree implementation
Introduces a `TaskRunner` for executing behavior trees within the ECS world. Supports leaf, sequential, parallel, and random task kinds, along with status propagation (succeeded, failed, cancelled).
This commit is contained in:
@@ -0,0 +1,14 @@
|
||||
export {
|
||||
Task,
|
||||
Scheduled,
|
||||
Running,
|
||||
Succeeded,
|
||||
Failed,
|
||||
Cancelled,
|
||||
TERMINAL_TAGS,
|
||||
ChildOf,
|
||||
} from "./task";
|
||||
export type { TaskKind } from "./task";
|
||||
|
||||
export { TaskRunner } from "./runner";
|
||||
export type { LeafHandler, TerminalHandler } from "./runner";
|
||||
@@ -0,0 +1,287 @@
|
||||
import type { World, Entity } from "../index";
|
||||
import { query } from "../query";
|
||||
import {
|
||||
Task,
|
||||
Scheduled,
|
||||
Running,
|
||||
Succeeded,
|
||||
Failed,
|
||||
Cancelled,
|
||||
TERMINAL_TAGS,
|
||||
ChildOf,
|
||||
} from "./task";
|
||||
|
||||
// ── Types ─────────────────────────────────────────────
|
||||
/** Callback invoked for each leaf task that becomes Scheduled. */
|
||||
export type LeafHandler = (world: World, entity: Entity) => void;
|
||||
|
||||
/** Callback invoked when a task reaches a terminal status. */
|
||||
export type TerminalHandler = (
|
||||
world: World,
|
||||
entity: Entity,
|
||||
status: "succeeded" | "failed" | "cancelled",
|
||||
) => void;
|
||||
|
||||
// ── Helpers ───────────────────────────────────────────
|
||||
function terminalStatus(
|
||||
world: World,
|
||||
entity: Entity,
|
||||
): "succeeded" | "failed" | "cancelled" | null {
|
||||
if (world.has(entity, Succeeded)) return "succeeded";
|
||||
if (world.has(entity, Failed)) return "failed";
|
||||
if (world.has(entity, Cancelled)) return "cancelled";
|
||||
return null;
|
||||
}
|
||||
|
||||
function isTerminal(world: World, entity: Entity): boolean {
|
||||
return terminalStatus(world, entity) !== null;
|
||||
}
|
||||
|
||||
function clearStatus(world: World, entity: Entity): void {
|
||||
for (const tag of TERMINAL_TAGS) {
|
||||
if (world.has(entity, tag)) world.remove(entity, tag);
|
||||
}
|
||||
if (world.has(entity, Running)) world.remove(entity, Running);
|
||||
}
|
||||
|
||||
function childrenOf(world: World, parent: Entity): Entity[] {
|
||||
return world.getRelatedTo(parent, ChildOf);
|
||||
}
|
||||
|
||||
function parentOf(world: World, child: Entity): Entity | null {
|
||||
return world.getRelated(child, ChildOf) ?? null;
|
||||
}
|
||||
|
||||
// ── TaskRunner ────────────────────────────────────────
|
||||
/**
|
||||
* Push-based behaviour-tree runner.
|
||||
*
|
||||
* Only tasks tagged with `Scheduled` are processed each tick.
|
||||
* When a task finishes, it notifies its parent, which may schedule
|
||||
* the next child (sequential), aggregate results (parallel), or
|
||||
* propagate upward.
|
||||
*
|
||||
* Leaves are dispatched to a user-provided `onLeaf` callback.
|
||||
* Terminal results are dispatched to a user-provided `onTerminal` callback.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const runner = new TaskRunner(world);
|
||||
* runner.onLeaf = (world, entity) => {
|
||||
* // do the leaf's work, then call:
|
||||
* runner.succeed(entity);
|
||||
* };
|
||||
*
|
||||
* // Each frame:
|
||||
* runner.tick();
|
||||
* ```
|
||||
*/
|
||||
export class TaskRunner {
|
||||
private _world: World;
|
||||
|
||||
/** Called when a leaf task becomes Scheduled. */
|
||||
onLeaf: LeafHandler = () => {};
|
||||
|
||||
/** Called when any task reaches a terminal status. */
|
||||
onTerminal: TerminalHandler = () => {};
|
||||
|
||||
constructor(world: World) {
|
||||
this._world = world;
|
||||
}
|
||||
|
||||
// ── Public API ────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Process all Scheduled tasks.
|
||||
*
|
||||
* Call once per frame. Only entities with `Scheduled` are touched.
|
||||
*/
|
||||
tick(): void {
|
||||
const scheduled = [...this._world.query(query(Task, Scheduled))];
|
||||
for (const entity of scheduled) {
|
||||
this._world.remove(entity, Scheduled);
|
||||
this._execute(entity);
|
||||
}
|
||||
}
|
||||
|
||||
/** Mark a leaf task as succeeded and propagate upward. */
|
||||
succeed(entity: Entity): void {
|
||||
this._finish(entity, Succeeded);
|
||||
}
|
||||
|
||||
/** Mark a leaf task as failed and propagate upward. */
|
||||
fail(entity: Entity): void {
|
||||
this._finish(entity, Failed);
|
||||
}
|
||||
|
||||
/** Cancel a task and all its descendants. */
|
||||
cancel(entity: Entity): void {
|
||||
this._cancelTree(entity);
|
||||
}
|
||||
|
||||
/** Schedule a task for execution next tick. */
|
||||
schedule(entity: Entity): void {
|
||||
if (this._world.has(entity, Task)) {
|
||||
this._world.add(entity, Scheduled);
|
||||
}
|
||||
}
|
||||
|
||||
/** Reset a task to idle (removes all status tags). */
|
||||
reset(entity: Entity): void {
|
||||
clearStatus(this._world, entity);
|
||||
this._world.remove(entity, Scheduled);
|
||||
}
|
||||
|
||||
// ── Internal execution ────────────────────────────
|
||||
|
||||
private _execute(entity: Entity): void {
|
||||
const t = this._world.get(entity, Task);
|
||||
|
||||
switch (t.kind) {
|
||||
case "leaf":
|
||||
this._executeLeaf(entity);
|
||||
break;
|
||||
case "sequential":
|
||||
this._executeSequential(entity);
|
||||
break;
|
||||
case "parallel":
|
||||
this._executeParallel(entity);
|
||||
break;
|
||||
case "random":
|
||||
this._executeRandom(entity);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
private _executeLeaf(entity: Entity): void {
|
||||
this._world.add(entity, Running);
|
||||
this.onLeaf(this._world, entity);
|
||||
}
|
||||
|
||||
private _executeSequential(entity: Entity): void {
|
||||
const children = childrenOf(this._world, entity);
|
||||
|
||||
// Find the first non-terminal child
|
||||
for (const child of children) {
|
||||
if (isTerminal(this._world, child)) {
|
||||
const status = terminalStatus(this._world, child)!;
|
||||
if (status === "failed" || status === "cancelled") {
|
||||
this._finish(entity, status === "cancelled" ? Cancelled : Failed);
|
||||
return;
|
||||
}
|
||||
// succeeded — continue to next child
|
||||
continue;
|
||||
}
|
||||
|
||||
// Found a child that hasn't run yet — schedule it
|
||||
this._world.add(child, Scheduled);
|
||||
return;
|
||||
}
|
||||
|
||||
// All children succeeded
|
||||
this._finish(entity, Succeeded);
|
||||
}
|
||||
|
||||
private _executeParallel(entity: Entity): void {
|
||||
const children = childrenOf(this._world, entity);
|
||||
let allDone = true;
|
||||
|
||||
for (const child of children) {
|
||||
if (isTerminal(this._world, child)) {
|
||||
const status = terminalStatus(this._world, child)!;
|
||||
if (status === "failed" || status === "cancelled") {
|
||||
this._finish(entity, status === "cancelled" ? Cancelled : Failed);
|
||||
return;
|
||||
}
|
||||
// succeeded — this child is done
|
||||
continue;
|
||||
}
|
||||
|
||||
allDone = false;
|
||||
|
||||
// Schedule if not already running or scheduled
|
||||
if (
|
||||
!this._world.has(child, Running) &&
|
||||
!this._world.has(child, Scheduled)
|
||||
) {
|
||||
this._world.add(child, Scheduled);
|
||||
}
|
||||
}
|
||||
|
||||
if (allDone) {
|
||||
this._finish(entity, Succeeded);
|
||||
}
|
||||
}
|
||||
|
||||
private _executeRandom(entity: Entity): void {
|
||||
const children = childrenOf(this._world, entity);
|
||||
|
||||
// Check if any child already reached a terminal
|
||||
for (const child of children) {
|
||||
if (isTerminal(this._world, child)) {
|
||||
const status = terminalStatus(this._world, child)!;
|
||||
this._finish(
|
||||
entity,
|
||||
status === "succeeded"
|
||||
? Succeeded
|
||||
: status === "cancelled"
|
||||
? Cancelled
|
||||
: Failed,
|
||||
);
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
// Pick a random child that isn't already running
|
||||
const eligible = children.filter(
|
||||
(c) => !this._world.has(c, Running) && !this._world.has(c, Scheduled),
|
||||
);
|
||||
|
||||
if (eligible.length > 0) {
|
||||
const pick = eligible[Math.floor(Math.random() * eligible.length)];
|
||||
this._world.add(pick, Scheduled);
|
||||
}
|
||||
// If no eligible children (all running), wait for one to finish
|
||||
}
|
||||
|
||||
// ── Completion propagation ────────────────────────
|
||||
|
||||
private _finish(
|
||||
entity: Entity,
|
||||
tag: typeof Succeeded | typeof Failed | typeof Cancelled,
|
||||
): void {
|
||||
if (!this._world.has(entity, Task)) return;
|
||||
|
||||
clearStatus(this._world, entity);
|
||||
this._world.add(entity, tag);
|
||||
|
||||
const status = terminalStatus(this._world, entity)!;
|
||||
this.onTerminal(this._world, entity, status);
|
||||
|
||||
// Notify parent
|
||||
const parent = parentOf(this._world, entity);
|
||||
if (parent) {
|
||||
this._world.add(parent, Scheduled);
|
||||
}
|
||||
}
|
||||
|
||||
private _cancelTree(entity: Entity): void {
|
||||
if (!this._world.has(entity, Task)) return;
|
||||
|
||||
// Cancel children first
|
||||
for (const child of childrenOf(this._world, entity)) {
|
||||
this._cancelTree(child);
|
||||
}
|
||||
|
||||
// Cancel this node
|
||||
clearStatus(this._world, entity);
|
||||
this._world.add(entity, Cancelled);
|
||||
this.onTerminal(this._world, entity, "cancelled");
|
||||
|
||||
// Notify parent
|
||||
const parent = parentOf(this._world, entity);
|
||||
if (parent) {
|
||||
this._world.add(parent, Scheduled);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
import { defineComponent } from "../component";
|
||||
import { defineRelationship } from "../relationship";
|
||||
|
||||
// ── Task component ────────────────────────────────────
|
||||
/**
|
||||
* Core component for behaviour-tree tasks.
|
||||
*
|
||||
* `kind` determines how the task evaluates its children:
|
||||
* - `"leaf"` — terminal node; external logic drives it to completion.
|
||||
* - `"sequential"` — runs children one at a time, left to right.
|
||||
* Succeeds when all children succeed; fails when any child fails.
|
||||
* - `"parallel"` — schedules all children at once.
|
||||
* Succeeds when all children succeed; fails when any child fails.
|
||||
* - `"random"` — picks one child at random each time it's scheduled.
|
||||
* Succeeds/fails with that child's result.
|
||||
*/
|
||||
export const Task = defineComponent("task", {
|
||||
kind: "leaf" as "leaf" | "sequential" | "parallel" | "random",
|
||||
});
|
||||
|
||||
export type TaskKind = typeof Task.type["kind"];
|
||||
|
||||
// ── Status tags (zero-size — presence is the signal) ──
|
||||
/** A task that should be executed this tick. */
|
||||
export const Scheduled = defineComponent("scheduled", {});
|
||||
|
||||
/** A task that is currently executing (multi-frame leaves). */
|
||||
export const Running = defineComponent("running", {});
|
||||
|
||||
/** The task completed successfully. */
|
||||
export const Succeeded = defineComponent("succeeded", {});
|
||||
|
||||
/** The task failed. */
|
||||
export const Failed = defineComponent("failed", {});
|
||||
|
||||
/** The task was cancelled externally. */
|
||||
export const Cancelled = defineComponent("cancelled", {});
|
||||
|
||||
/** All terminal status tags. */
|
||||
export const TERMINAL_TAGS = [Succeeded, Failed, Cancelled] as const;
|
||||
|
||||
// ── Relationship ──────────────────────────────────────
|
||||
/** Parent → child edge in the task tree. */
|
||||
export const ChildOf = defineRelationship("taskChild");
|
||||
Reference in New Issue
Block a user