ecs-observable/src/bt/task.ts

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.
 * - `"repeat"` — runs its single child. When the child finishes, resets it
 *   and runs again. Never terminates on its own (only via cancel).
 * - `"selector"` — runs children left to right. Succeeds on the first
 *   child that succeeds; fails only if all children fail.
 */
export const Task = defineComponent("task", {
  kind: "leaf" as
    | "leaf"
    | "sequential"
    | "parallel"
    | "random"
    | "repeat"
    | "selector",
});

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");