GoAP

Goal-Oriented Action Planning library for TypeScript/JavaScript.

Overview

GoAP enables autonomous agents to dynamically generate action sequences to achieve goals. Unlike behavior trees or state machines, plans are computed at runtime based on current world state and available actions.

Key features:

• Automatic plan generation via backward-chaining search
• Cost-based path selection
• Dynamic state evaluation at runtime
• Action hierarchies with preconditions and effects
• Extensible via TypeScript mixins

Installation

npm install @ankhzet/goap
# or
yarn add @ankhzet/goap
# or
pnpm add @ankhzet/goap

Requires TypeScript 4.0+ or ES2018+ runtime.

Quick Start

import {
  Action,
  ActionEnactor,
  ActionProcessingResult,
  EnactorState,
  GoalActionPlanner,
  GoalActionExecutor,
  StateBitInterface,
  StateInterface
} from 'goap';

// Define state bits
const isHungry: StateBitInterface<Agent> = { name: 'isHungry' };
const hasFood: StateBitInterface<Agent> = { name: 'hasFood' };

// Define actions
class EatAction extends Action<Agent> {
  cost = 1;
  requires = new EnactorState([[isHungry, true]]);
  provides = new EnactorState([[hasFood, true]]);

  process(enactor: Agent): ActionProcessingResult {
    enactor.hunger = 100;
    return ActionProcessingResult.Finished;
  }
}

// Create agent
class Agent extends ActionEnactor(BaseClass) {
  actions = new Set([new EatAction()]);
  state = new EnactorState();
  deriveGoal(): StateInterface<Agent> {
    return new EnactorState([[hasFood, true]]);
  }
}

// Plan and execute
const planner = new GoalActionPlanner<Agent>();
const executor = new GoalActionExecutor<Agent>();

const plan = planner.plan(agent, agent.deriveGoal(), agent.state);
if (plan) {
  agent.acceptSequence(plan);
  // In game loop:
  executor.process(agent, delta);
}

Documentation

• Core Concepts - State system, actions, goals, planner algorithm
• Public API - Complete type and method reference
• Examples - Real-world usage patterns

Examples

| Domain | Description | |--------|-------------| | Game NPC AI | Survival game with hunger, health, combat, socialization | | Warehouse Robot | Pick-and-deliver logistics with battery management | | Smart Home | Home automation with HVAC, lighting, security | | Autonomous Vehicle | Navigation with routing, obstacle avoidance, parking |

Core Concepts

State

World state is represented as a collection of bits with boolean values:

const state = new EnactorState<Agent>([
  [hasWeapon, true],
  [isHealthy, false]
]);

State bits can be static or dynamic:

const nearEnemy = {
  name: 'nearEnemy',
  isFulfilledBy: (agent) => agent.distanceToEnemy < 10
};

Actions

Actions have preconditions (requires), effects (provides), and cost:

class MyAction extends Action<Agent> {
  cost = 5;
  requires = new EnactorState([[hasAmmo, true]]);
  provides = new EnactorState([[enemyDead, true]]);

  process(enactor: Agent, delta: number): ActionProcessingResult {
    // Execution logic
    return ActionProcessingResult.Finished;
  }
}

Agents

Agents combine state with available actions:

class MyAgent extends ActionEnactor(BaseClass) {
  actions = new Set<ActionInterface<MyAgent>>();
  state = new EnactorState<MyAgent>();

  deriveGoal(): StateInterface<MyAgent> {
    // Compute goal based on current needs
    return new EnactorState([[hasFood, true]]);
  }
}

Planning

The planner finds the cheapest sequence to achieve a goal:

const planner = new GoalActionPlanner<MyAgent>();
const plan = planner.plan(agent, goal, currentState);
// Returns ActionInterface[] or undefined

Execution

The executor runs the planned sequence:

const executor = new GoalActionExecutor<MyAgent>();

// In game loop:
const isActing = executor.process(agent, delta);
if (!isActing) {
  // Replan
}

API Overview

| Class | Purpose | |-------|---------| | EnactorState | Mutable world state | | Action | Base action class | | ActionWithTarget | Action requiring movement | | ActionEnactor | Mixin for action-performing agents | | GoalActionPlanner | Plan generation | | GoalActionExecutor | Plan execution |

See Public API for complete reference.

License

MIT