hypercross
/
ecs-observable
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Compare commits

base: hypercross:1253bf82d27f96189bf068416744217afda4e918
Branches Tags
hypercross:master
..
compare: hypercross:968672da06146ed9957630eec905c4ba95a98136
Branches Tags
hypercross:master

No commits in common. "1253bf82d27f96189bf068416744217afda4e918" and "968672da06146ed9957630eec905c4ba95a98136" have entirely different histories.
1253bf82d2 ... 968672da06

9 changed files with 179 additions and 398 deletions
Show Stats Expand all files Collapse all files

72
USAGE.md
View File

@ -393,33 +393,32 @@ Command entities are automatically destroyed after processing if they become bar
Behaviour trees control game flow by composing tasks into a tree. Each node in the tree is an ECS entity with a `Task` component. Parent-child relationships are `ChildOf` edges. This means you can query, observe, and serialize the tree just like any other ECS data.
`buildTree()` takes a task entity definition and materializes it into entities, returning a fully-wired `TaskRunner`. Task definitions are created with factories, and non-task child entities can be mixed in as metadata; the runner ignores those non-task children during execution.
`buildTree()` takes a declarative definition and materializes it into entities, returning a fully-wired `TaskRunner`.
```ts
import { defineComponent, entity } from "ecs-observable";
import { buildTree, Cancel, leaf, parallel, repeat, sequential } from "ecs-observable/bt";
import { buildTree, Cancel } from "ecs-observable/bt";
```
#### Leaf patterns
**One-shot** — just return. Implicit success.
```ts
leaf(() => { doWork(); })
{ kind: "leaf", run: () => { doWork(); } }
```
**Fail** — throw any error.
```ts
leaf(() => { throw new Error("bad"); })
{ kind: "leaf", run: () => { throw new Error("bad"); } }
```
**Cancel** — throw the `Cancel` symbol.
```ts
leaf(() => { throw Cancel; })
{ kind: "leaf", run: () => { throw Cancel; } }
```
**Ongoing** — generator function. Each `yield` suspends until next tick. The yielded value is the delay in ms (or nothing for next frame). Completion = success.
```ts
leaf(function* tickTimer() {
{ kind: "leaf", *run() {
while (true) {
const dt: number = yield; // delta time from runner.tick(dt)
timer.accumulator += dt;
@ -427,54 +426,49 @@ leaf(function* tickTimer() {
// ... act ...
}
}
})
} }
```
#### Composite nodes
```ts
sequential([a, b, c]) // left-to-right, all must succeed
selector([a, b, c]) // left-to-right, first success wins
parallel([a, b, c]) // all at once, all must succeed
random([a, b, c]) // pick one child each activation
repeat(a) // decorator — re-run child forever
```
Non-task entity children are materialized but ignored by the runner:
```ts
const Label = defineComponent("label", { value: "" });
sequential([
entity(Label, { value: "main sequence" }),
leaf(handleInput),
leaf(render),
])
{ kind: "sequential", children: [a, b, c] } // left-to-right, all must succeed
{ kind: "selector", children: [a, b, c] } // left-to-right, first success wins
{ kind: "parallel", children: [a, b, c] } // all at once, all must succeed
{ kind: "random", children: [a, b, c] } // pick one child each activation
{ kind: "repeat", child: a } // decorator — re-run child forever
```
#### Full example
```ts
const runner = buildTree(
world,
parallel([
leaf(function* physicsLoop() {
const runner = buildTree(world, {
kind: "parallel",
children: [
{
kind: "leaf",
*run() {
while (true) {
const dt: number = yield;
updatePhysics(dt);
}
}),
repeat(
sequential([
leaf(() => { handleInput(); }),
leaf(() => { render(); }),
]),
),
]),
);
},
},
{
kind: "repeat",
child: {
kind: "sequential",
children: [
{ kind: "leaf", run: () => { handleInput(); } },
{ kind: "leaf", run: () => { render(); } },
],
},
},
],
});
// Kick off
runner.schedule(runner.root!);
runner.schedule((runner as any).root);
// Game loop
setInterval(() => runner.tick(16), 16);

53
examples/blackjack/main.ts
View File

@ -23,13 +23,7 @@
// npx tsx examples/blackjack/main.ts
import { World } from "../../src/index";
import {
buildTree,
leaf,
parallel,
repeat,
sequential,
} from "../../src/bt/index";
import { buildTree } from "../../src/bt/index";
import { CommandQueue } from "../../src/commands/index";
import {
@ -69,12 +63,14 @@ const commands = new CommandQueue(world);
registerCommands(world, commands, cards);
// ── Behaviour Tree ───────────────────────────────────
const runner = buildTree(
world,
parallel([
leaf(function* dealerPlay() {
const runner = buildTree(world, {
kind: "parallel",
children: [
{
kind: "leaf",
*run() {
while (true) {
yield;
const dt: number = yield;
const phase = world.getSingleton(GamePhase);
if (phase.phase !== "dealerTurn") continue;
@ -87,19 +83,30 @@ const runner = buildTree(
resolveRound(world, cards);
}
}
}),
repeat(
sequential([
leaf(() => {
},
},
{
kind: "repeat",
child: {
kind: "sequential",
children: [
{
kind: "leaf",
run: () => {
commands.execute();
}),
leaf(() => {
},
},
{
kind: "leaf",
run: () => {
render(world, ui);
}),
]),
),
]),
);
},
},
],
},
},
],
});
// ── Input → Command mapping ──────────────────────────
const keyToCommand: Partial<Record<Key, typeof Hit>> = {

51
examples/tetris/main.ts
View File

@ -20,13 +20,7 @@
// npx tsx examples/tetris/main.ts
import { World } from "../../src/index";
import {
buildTree,
leaf,
parallel,
repeat,
sequential,
} from "../../src/bt/index";
import { buildTree } from "../../src/bt/index";
import { CommandQueue } from "../../src/commands/index";
import {
@ -70,10 +64,12 @@ registerCommands(world, commands, pieces);
pieces.spawnPiece();
// ── Behaviour Tree ───────────────────────────────────
const runner = buildTree(
world,
parallel([
leaf(function* gravityTick() {
const runner = buildTree(world, {
kind: "parallel",
children: [
{
kind: "leaf",
*run() {
while (true) {
const dt: number = yield;
if (world.hasSingleton(GameOver) || world.hasSingleton(Paused)) {
@ -94,19 +90,30 @@ const runner = buildTree(
}
}
}
}),
repeat(
sequential([
leaf(() => {
},
},
{
kind: "repeat",
child: {
kind: "sequential",
children: [
{
kind: "leaf",
run: () => {
commands.execute();
}),
leaf(() => {
},
},
{
kind: "leaf",
run: () => {
render(world, ui);
}),
]),
),
]),
);
},
},
],
},
},
],
});
// ── Input → Command mapping ──────────────────────────
const keyToCommand: Partial<Record<Key, typeof MoveLeft>> = {

13
src/bt/index.ts
View File

@ -13,14 +13,5 @@ export type { TaskKind } from "./task";
export { TaskRunner } from "./runner";
export type { LeafHandler, TerminalHandler } from "./runner";
export {
buildTree,
Cancel,
leaf,
sequential,
parallel,
selector,
random,
repeat,
} from "./tree-def";
export type { TreeDef, TaskEntityDef, LeafTaskMeta, LeafFn } from "./tree-def";
export { buildTree, Cancel } from "./tree-def";
export type { TreeDef, LeafFn } from "./tree-def";

9
src/bt/runner.ts
View File

@ -53,11 +53,7 @@ function clearSubtree(world: World, entity: Entity): void {
}
function* childrenOf(world: World, parent: Entity): IterableIterator<Entity> {
for (const child of world.getRelatedTo(parent, ChildOf)) {
if (world.has(child, Task)) {
yield child;
}
}
yield* world.getRelatedTo(parent, ChildOf);
}
function parentOf(world: World, child: Entity): Entity | null {
@ -91,9 +87,6 @@ function parentOf(world: World, child: Entity): Entity | null {
export class TaskRunner {
private _world: World;
/** Root task entity, set by `buildTree` for convenience. */
root?: Entity;
/** Called when a leaf task becomes Scheduled. */
onLeaf: LeafHandler = () => {};

157
src/bt/tree-def.ts
View File

@ -1,5 +1,4 @@
import type { World, Entity } from "../index";
import type { EntityDef, EntityDefChild } from "../entity-tree";
import { Task, ChildOf } from "./task";
import { TaskRunner } from "./runner";
@ -10,7 +9,7 @@ import { TaskRunner } from "./runner";
*
* @example
* ```ts
* leaf(() => { throw Cancel; })
* { kind: "leaf", run: () => { throw Cancel; } }
* ```
*/
export const Cancel: unique symbol = Symbol("leaf.cancel");
@ -22,148 +21,75 @@ export type LeafFn =
| ((world: World, dt: number) => void)
| (() => Generator<number | void, void, number>);
export interface LeafTaskMeta {
readonly run: LeafFn;
}
export type TaskEntityDef = EntityDef<
typeof Task.type,
LeafTaskMeta | undefined
>;
/** Behaviour-tree definition accepted by `buildTree`. */
export type TreeDef = TaskEntityDef;
// ── Entity task factories ──────────────────────────────
function compactChildren(children: readonly EntityDefChild[]): EntityDef[] {
return children.filter(Boolean) as EntityDef[];
}
function task(
kind: typeof Task.type.kind,
children: readonly EntityDefChild[] = [],
meta?: LeafTaskMeta,
): TaskEntityDef {
return {
kind: "entity",
component: Task,
value: { kind },
children: compactChildren(children),
meta,
};
}
/** Create a leaf task entity definition. */
export function leaf(
run: LeafFn,
children: readonly EntityDefChild[] = [],
): TaskEntityDef {
return task("leaf", children, { run });
}
/** Create a sequential task entity definition. */
export function sequential(
children: readonly EntityDefChild[] = [],
): TaskEntityDef {
return task("sequential", children);
}
/** Create a parallel task entity definition. */
export function parallel(
children: readonly EntityDefChild[] = [],
): TaskEntityDef {
return task("parallel", children);
}
/** Create a selector task entity definition. */
export function selector(
children: readonly EntityDefChild[] = [],
): TaskEntityDef {
return task("selector", children);
}
/** Create a random task entity definition. */
export function random(
children: readonly EntityDefChild[] = [],
): TaskEntityDef {
return task("random", children);
}
/**
* Create a repeat task entity definition.
*
* `repeat(child)` and `repeat([child, metadataEntity])` are both supported.
* The runner operates only on child entities that have the `Task` component.
*/
export function repeat(child: EntityDef): TaskEntityDef;
export function repeat(children?: readonly EntityDefChild[]): TaskEntityDef;
export function repeat(
childOrChildren: EntityDef | readonly EntityDefChild[] = [],
): TaskEntityDef {
return task(
"repeat",
Array.isArray(childOrChildren) ? childOrChildren : [childOrChildren],
);
}
/** Declarative behaviour-tree definition. */
export type TreeDef =
| { kind: "leaf"; run: LeafFn }
| { kind: "sequential"; children: TreeDef[] }
| { kind: "parallel"; children: TreeDef[] }
| { kind: "selector"; children: TreeDef[] }
| { kind: "random"; children: TreeDef[] }
| { kind: "repeat"; child: TreeDef };
// ── Builder ───────────────────────────────────────────
/**
* Materialize a behaviour-tree definition into ECS entities and return a
* Recursively materialize a `TreeDef` into ECS entities and return a
* fully-wired `TaskRunner`.
*
* Definitions are `EntityDef` trees produced by the task factories (`leaf`,
* `sequential`, `parallel`, `selector`, `random`, `repeat`) and generic
* single-component entity factories. Non-task child entities are materialized
* into the ECS tree but ignored by `TaskRunner` execution.
*
* Leaf `run` functions:
* - **Plain function** — runs once per tick. `return` = success. `throw` = fail.
* `throw Cancel` = cancel.
* - **Generator function** — each `yield` suspends until next tick. The value
* yielded is the desired delay in ms (or `undefined` for next frame).
* Generator completion = success. `throw` = fail. `throw Cancel` = cancel.
*
* @example
* ```ts
* const runner = buildTree(world, {
* kind: "repeat",
* child: {
* kind: "sequential",
* children: [
* { kind: "leaf", run: () => { doWork(); } },
* { kind: "leaf", *run() { yield 1000; doLater(); } },
* ],
* },
* });
* runner.schedule(runner.root);
* setInterval(() => runner.tick(16), 16);
* ```
*/
export function buildTree(world: World, def: TreeDef): TaskRunner {
const leafHandlers = new Map<Entity, LeafFn>();
// Track generator iterators for multi-frame leaves
const generators = new Map<Entity, Generator<number | void, void, number>>();
function build(def: EntityDef, parent?: Entity): Entity {
function build(def: TreeDef, parent?: Entity): Entity {
const entity = world.spawn();
world.add(entity, def.component, def.value);
if (parent !== undefined) {
world.relate(entity, ChildOf, parent);
}
if (def.component === Task) {
const taskData = world.get(entity, Task);
if (taskData.kind === "leaf") {
const run = (def.meta as LeafTaskMeta | undefined)?.run;
if (!run) {
throw new Error("Leaf task entity is missing a run function");
}
leafHandlers.set(entity, run);
}
}
if (def.kind === "leaf") {
world.add(entity, Task, { kind: "leaf" });
leafHandlers.set(entity, def.run);
} else if (def.kind === "repeat") {
world.add(entity, Task, { kind: "repeat" });
build(def.child, entity);
} else {
world.add(entity, Task, { kind: def.kind });
for (const child of def.children) {
build(child, entity);
}
}
if (parent) {
world.relate(entity, ChildOf, parent);
}
return entity;
}
const root = build(def);
if (!world.has(root, Task)) {
throw new Error("buildTree root must be a task entity");
}
const runner = new TaskRunner(world);
runner.root = root;
runner.onLeaf = (_w, entity, dt) => {
const handler = leafHandlers.get(entity);
@ -217,5 +143,8 @@ export function buildTree(world: World, def: TreeDef): TaskRunner {
generators.delete(entity);
};
// Stash the root entity on the runner for convenience
(runner as any).root = root;
return runner;
}

80
src/entity-tree.ts
View File

@ -1,80 +0,0 @@
import type { ComponentDef } from "./component";
import type { Entity } from "./entity";
import type { RelationshipDef } from "./relationship";
import type { World } from "./world";
/**
* Declarative definition for one entity with one primary component.
*
* Children are materialized as entities and related to their parent by the
* relationship passed to `buildEntityTree`.
*/
export interface EntityDef<T extends Record<string, any> = any, M = unknown> {
readonly kind: "entity";
readonly component: ComponentDef<T>;
readonly value?: Partial<T>;
readonly children: readonly EntityDef[];
readonly meta?: M;
}
export type EntityDefChild = EntityDef | null | undefined | false;
function compactChildren(children: readonly EntityDefChild[]): EntityDef[] {
return children.filter(Boolean) as EntityDef[];
}
/** Create a single-component entity definition. */
export function entity<T extends Record<string, any>>(
component: ComponentDef<T>,
value?: Partial<T>,
children?: readonly EntityDefChild[],
): EntityDef<T>;
export function entity<T extends Record<string, any>>(
component: ComponentDef<T>,
children?: readonly EntityDefChild[],
): EntityDef<T>;
export function entity<T extends Record<string, any>>(
component: ComponentDef<T>,
valueOrChildren?: Partial<T> | readonly EntityDefChild[],
children: readonly EntityDefChild[] = [],
): EntityDef<T> {
const hasChildrenAsSecondArg = Array.isArray(valueOrChildren);
const value = hasChildrenAsSecondArg
? undefined
: (valueOrChildren as Partial<T> | undefined);
const childDefs = hasChildrenAsSecondArg ? valueOrChildren : children;
return {
kind: "entity",
component,
value,
children: compactChildren(childDefs),
};
}
/**
* Materialize an `EntityDef` tree into ECS entities.
*
* The supplied relationship connects child entities to their parent, which lets
* callers choose the semantic meaning of the tree edge.
*/
export function buildEntityTree(
world: World,
def: EntityDef,
childRelationship: RelationshipDef,
parent?: Entity,
): Entity {
const entity = world.spawn();
world.add(entity, def.component, def.value);
if (parent !== undefined) {
world.relate(entity, childRelationship, parent);
}
for (const child of def.children) {
buildEntityTree(world, child, childRelationship, entity);
}
return entity;
}

2
src/index.ts
View File

@ -8,8 +8,6 @@ export { query } from "./query";
export { Query } from "./query";
export type { Entity } from "./entity";
export { makeEntity, entityIndex, entityGeneration } from "./entity";
export { entity, buildEntityTree } from "./entity-tree";
export type { EntityDef, EntityDefChild } from "./entity-tree";
export { SparseSet } from "./storage/sparse-set";
export type {
WorldEvent,

60
test/bt.test.ts
View File

@ -1,5 +1,5 @@
import { describe, it, expect, beforeEach } from "vitest";
import { World, defineComponent, entity, type Entity } from "../src/index";
import { World, type Entity } from "../src/index";
import {
Task,
Scheduled,
@ -9,10 +9,6 @@ import {
Cancelled,
ChildOf,
TaskRunner,
buildTree,
leaf,
repeat,
sequential,
} from "../src/bt/index";
// ── Helpers ─────────────────────────────────────────
@ -58,60 +54,6 @@ function makeSelector(world: World, parent?: Entity): Entity {
return e;
}
// ── Entity task factories ───────────────────────────
describe("Entity task factories", () => {
it("materializes non-task child entities and ignores them during execution", () => {
const Label = defineComponent("testLabel", { value: "" });
const world = new World();
const calls: string[] = [];
const runner = buildTree(
world,
sequential([
entity(Label, { value: "sequence metadata" }),
leaf(() => calls.push("a")),
entity(Label, { value: "between leaves" }),
leaf(() => calls.push("b")),
]),
);
const root = runner.root!;
const children = [...world.getRelatedTo(root, ChildOf)];
const labels = children
.filter((child) => world.has(child, Label))
.map((child) => world.get(child, Label).value);
expect(labels).toEqual(["sequence metadata", "between leaves"]);
runner.schedule(root);
for (let i = 0; i < 5; i++) runner.tick();
expect(calls).toEqual(["a", "b"]);
expect(world.has(root, Succeeded)).toBe(true);
});
it("repeat works with component child entities beside its task child", () => {
const Label = defineComponent("repeatLabel", { value: "" });
const world = new World();
let calls = 0;
const runner = buildTree(
world,
repeat([
entity(Label, { value: "repeat metadata" }),
leaf(() => {
calls++;
}),
]),
);
runner.schedule(runner.root!);
for (let i = 0; i < 5; i++) runner.tick();
expect(calls).toBeGreaterThan(1);
});
});
// ── Leaf tasks ──────────────────────────────────────
describe("Leaf tasks", () => {
let world: World;