Agent Actions Reference

This page documents all 23 actions available to ElizaOS agents in Hyperscape. Actions are the executable commands that agents use to interact with the game world.

Actions are defined in packages/plugin-hyperscape/src/actions/. As of PR #628, agents use a THINKING+ACTION format for transparent decision-making.

Action Categories

Movement

6 actions for navigation

Combat

3 actions for fighting

Skills

5 actions for gathering/crafting

Inventory

4 actions for item management

Social

1 action for communication

Banking

2 actions for storage

Goals

2 actions for planning

World Interaction

1 action for world objects

Movement Actions

`moveTo`

Move to specific coordinates.

// From actions/movement.ts
export const moveToAction: Action = {
  name: "MOVE_TO",
  description: "Move to a specific position in the game world",
  parameters: {
    x: { type: "number", description: "X coordinate" },
    z: { type: "number", description: "Z coordinate" },
  },
};

Usage: Navigate to resources, NPCs, or destinations.

`followEntity`

Follow another player or NPC.

export const followEntityAction: Action = {
  name: "FOLLOW_ENTITY",
  description: "Follow a specific entity in the game",
  parameters: {
    entityId: { type: "string", description: "ID of entity to follow" },
  },
};

Usage: Follow players for social interaction or group activities.

`stopMovement`

Stop all movement.

export const stopMovementAction: Action = {
  name: "STOP_MOVEMENT",
  description: "Stop moving immediately",
  parameters: {},
};

Features:

Movement Cancellation: Sends cancel: true flag to clear server-side path
Immediate Stop: Prevents “walking in place” bug
Path Clearing: Removes queued movement commands

Usage: Halt when reaching destination or when threatened.

`explore`

Explore the surrounding area.

// From actions/autonomous.ts
export const exploreAction: Action = {
  name: "EXPLORE",
  description: "Explore the nearby area to discover resources and entities",
  parameters: {
    direction: { type: "string", optional: true, description: "Preferred direction" },
  },
};

Usage: Discover new areas, find resources.

`approachEntity`

Move closer to an entity for interaction.

export const approachEntityAction: Action = {
  name: "APPROACH_ENTITY",
  description: "Move within interaction range of an entity",
  parameters: {
    entityId: { type: "string", description: "Target entity ID" },
    range: { type: "number", optional: true, description: "Desired distance" },
  },
};

Usage: Get within combat or interaction range.

`navigateTo`

Navigate to a named location.

// From actions/goals.ts
export const navigateToAction: Action = {
  name: "NAVIGATE_TO",
  description: "Navigate to a named location or area",
  parameters: {
    location: { type: "string", description: "Name of destination (e.g., 'bank', 'forest')" },
  },
};

Features:

Named Locations: Use location names instead of coordinates
Distance Stepping: Automatically handles server’s 200-tile movement limit
- Moves in 150-tile steps for safety margin
- Shows progress: “Moving towards bank (50 units remaining)”
Multi-Step Navigation: Continues moving until destination reached

Usage: Navigate using location names instead of coordinates. Long-Distance Movement: The server has a 200-tile movement limit. For destinations beyond this range, the action automatically moves in steps:

Calculates intermediate waypoint (150 tiles toward destination)
Moves to waypoint
On next tick, continues toward destination
Repeats until destination reached

This prevents movement command rejection while maintaining progress toward distant goals.

Combat Actions

`attackEntity`

Attack a target entity.

// From actions/combat.ts
export const attackEntityAction: Action = {
  name: "ATTACK_ENTITY",
  description: "Attack a hostile entity",
  parameters: {
    targetId: { type: "string", description: "Entity ID to attack" },
  },
};

Usage: Engage mobs or hostile players.

`changeCombatStyle`

Change combat style for XP distribution.

export const changeCombatStyleAction: Action = {
  name: "CHANGE_COMBAT_STYLE",
  description: "Change combat style (accurate, aggressive, defensive, controlled)",
  parameters: {
    style: {
      type: "string",
      enum: ["accurate", "aggressive", "defensive", "controlled"],
      description: "Combat style to use",
    },
  },
};

Usage: Train specific combat skills.

Style	Trains	Bonus
Accurate	Attack	+3 Attack
Aggressive	Strength	+3 Strength
Defensive	Defense	+3 Defense
Controlled	All	+1 each

`flee`

Escape from combat.

// From actions/autonomous.ts
export const fleeAction: Action = {
  name: "FLEE",
  description: "Flee from combat to a safe location",
  parameters: {
    direction: { type: "string", optional: true, description: "Direction to flee" },
  },
};

Usage: Escape when low on health.

Skill Actions

`chopTree`

Chop a tree for logs.

// From actions/skills.ts
export const chopTreeAction: Action = {
  name: "CHOP_TREE",
  description: "Chop down a nearby tree",
  parameters: {
    treeId: { type: "string", optional: true, description: "Specific tree entity ID" },
  },
};

Requirements: Hatchet in inventory, Woodcutting level. Validation: Checks for trees within 20m approach range, filters by level requirement, walks to tree if needed.

`mineRock`

Mine a rock for ore.

export const mineRockAction: Action = {
  name: "MINE_ROCK",
  description: "Mine a rock to gather ore",
  parameters: {
    rockId: { type: "string", optional: true, description: "Specific rock entity ID" },
  },
};

Requirements: Pickaxe in inventory, Mining level. Validation: Checks for rocks within 20m approach range, filters by level requirement, walks to cardinal adjacent tile before mining.

Added in PR #628 to support mining skill training for AI agents.

`catchFish`

Catch fish at a fishing spot.

export const catchFishAction: Action = {
  name: "CATCH_FISH",
  description: "Fish at a nearby fishing spot",
  parameters: {
    spotId: { type: "string", optional: true, description: "Specific fishing spot ID" },
  },
};

Requirements: Fishing rod in inventory, Fishing level.

`lightFire`

Light logs to create a fire.

export const lightFireAction: Action = {
  name: "LIGHT_FIRE",
  description: "Light a fire using logs",
  parameters: {
    logId: { type: "string", optional: true, description: "Specific log item ID" },
  },
};

Requirements: Tinderbox and logs in inventory.

`cookFood`

Cook raw food on a fire.

export const cookFoodAction: Action = {
  name: "COOK_FOOD",
  description: "Cook raw food on a fire",
  parameters: {
    foodId: { type: "string", optional: true, description: "Raw food item ID" },
    fireId: { type: "string", optional: true, description: "Fire entity ID" },
  },
};

Requirements: Raw food in inventory, fire nearby.

`mineRock`

Mine a rock to gather ore.

// From actions/skills.ts
export const mineRockAction: Action = {
  name: "MINE_ROCK",
  description: "Mine a rock to gather ore. Requires a pickaxe.",
  parameters: {
    rockId: { type: "string", optional: true, description: "Specific rock entity ID" },
  },
};

Requirements: Pickaxe in inventory, Mining level. Features:

Automatically walks to nearest cardinal-adjacent tile
Validates Mining level requirements for rock type
Filters out depleted rocks
Handles copper, tin, iron, coal, mithril, adamant, rune ores

Inventory Actions

`equipItem`

Equip an item from inventory.

// From actions/inventory.ts
export const equipItemAction: Action = {
  name: "EQUIP_ITEM",
  description: "Equip an item from inventory",
  parameters: {
    itemId: { type: "string", description: "Item ID to equip" },
  },
};

Usage: Equip weapons, armor, tools.

`useItem`

Use a consumable item.

export const useItemAction: Action = {
  name: "USE_ITEM",
  description: "Use an item (eat food, drink potion)",
  parameters: {
    itemId: { type: "string", description: "Item ID to use" },
  },
};

Usage: Heal with food, buff with potions.

`dropItem`

Drop an item on the ground.

export const dropItemAction: Action = {
  name: "DROP_ITEM",
  description: "Drop an item from inventory onto the ground",
  parameters: {
    itemId: { type: "string", description: "Item ID to drop" },
    quantity: { type: "number", optional: true, description: "Amount to drop" },
  },
};

Usage: Make room in inventory, drop unwanted items. Special Features:

Drop All: Use “drop all” to drop entire inventory
Drop All Type: Use “drop all logs” to drop all items of a specific type
Smart Matching: Uses word-boundary scoring to match correct items
Safety Limits: Max 50 items per drop-all operation
Failure Protection: Stops after 3 consecutive failures

Examples:

"drop bronze hatchet"     → Drops Bronze Hatchet
"drop all logs"           → Drops all log items
"drop everything"         → Drops entire inventory (max 50 items)

`pickupItem`

Pick up an item from the ground.

export const pickupItemAction: Action = {
  name: "PICKUP_ITEM",
  description: "Pick up an item from the ground nearby",
  parameters: {
    itemName: { type: "string", description: "Name of item to pick up" },
  },
};

Usage: Collect loot, gather dropped items. Features:

Smart Matching: Word-boundary scoring prevents false matches
Auto-Walk: Automatically walks to items beyond pickup range (4m)
Distance Stepping: Handles server’s 200-tile movement limit
Nearest Fallback: Picks nearest item if no name match

Scoring System:

typescript\n// Prevents "bronze pickaxe" matching "bronze hatchet"\n"Bronze Pickaxe" → "pick up bronze pickaxe" = 30 points (both words match)\n"Bronze Hatchet" → "pick up bronze pickaxe" = 15 points (only "bronze" matches)\n// Agent picks the item with highest score\n

Examples:

\n"pick up bronze pickaxe"  → Walks to and picks up Bronze Pickaxe (not Hatchet)\n"grab that sword"         → Picks up nearest sword\n"loot the coins"          → Picks up Coins\n

`chatMessage`

Send a chat message.

// From actions/social.ts
export const chatMessageAction: Action = {
  name: "CHAT_MESSAGE",
  description: "Send a message to nearby players",
  parameters: {
    message: { type: "string", description: "Message to send" },
  },
};

Usage: Communicate with other players.

Banking Actions

`bankDeposit`

Deposit items into bank.

// From actions/banking.ts
export const bankDepositAction: Action = {
  name: "BANK_DEPOSIT",
  description: "Deposit items into the bank",
  parameters: {
    itemId: { type: "string", description: "Item ID to deposit" },
    quantity: { type: "number", optional: true, description: "Amount to deposit" },
  },
};

Requirements: Must be at a bank.

`bankWithdraw`

Withdraw items from bank.

export const bankWithdrawAction: Action = {
  name: "BANK_WITHDRAW",
  description: "Withdraw items from the bank",
  parameters: {
    itemId: { type: "string", description: "Item ID to withdraw" },
    quantity: { type: "number", optional: true, description: "Amount to withdraw" },
  },
};

Requirements: Must be at a bank, item must be in bank.

Goal Actions

`setGoal`

Set a new goal using LLM with goal templates.

// From actions/goals.ts
export const setGoalAction: Action = {
  name: "SET_GOAL",
  description: "Choose a new goal using LLM with structured goal templates",
  parameters: {},
};

How it works (PR #628):

Goal Templates Provider supplies scored goal options:
- woodcutting_basics - Chop trees for logs
- mining_basics - Mine rocks for ore
- combat_training_goblins - Fight goblins
- bronze_gear_chain - Mine → smelt → smith
- acquire_starter_tools - Get basic tools
- And more…
LLM selects best goal based on:
- Current skills and levels
- Inventory contents
- Nearby resources
- Combat readiness
- Recent goal history (diversity penalty)
Goal is set with target, progress tracking, and location

Example LLM Selection:

THINKING: I have no axe or pickaxe. I should get starter tools first before attempting any gathering skills.

ACTION: SET_GOAL

Selected Goal: acquire_starter_tools

Goal Types:

combat_training - Train combat skills
woodcutting - Train woodcutting
mining - Train mining
smithing - Smelt and smith
fishing - Catch fish
firemaking - Burn logs
cooking - Cook food
exploration - Discover areas
starter_items - Get basic tools

When goals are paused (via dashboard Stop button), SET_GOAL is automatically blocked and replaced with IDLE. This prevents agents from auto-selecting new goals until the user resumes or sets a manual goal.

`idle`

Wait without taking action.

// From actions/autonomous.ts
export const idleAction: Action = {
  name: "IDLE",
  description: "Wait without taking any action",
  parameters: {
    duration: { type: "number", optional: true, description: "Seconds to wait" },
  },
};

Features:

Movement Cancellation: Stops current movement with cancel: true flag
Pause State: Used when goals are paused by user
Observation Mode: Agent stands still and observes surroundings

Usage: Wait for events, conserve resources, or when goals are paused.

World Interaction Actions

`lootStarterChest`

Interact with the starter chest to get starter equipment.

// From actions/autonomous.ts
export const lootStarterChestAction: Action = {
  name: "LOOT_STARTER_CHEST",
  description: "Search the starter chest to get starter equipment (bronze tools, tinderbox, net, food). Only works once per character.",
  parameters: {},
};

Usage: New players/agents should use this to acquire basic tools and food. Starter Items:

Bronze hatchet (woodcutting)
Bronze pickaxe (mining)
Tinderbox (firemaking)
Small fishing net (fishing)
Bread x5 (food)

Location: Near spawn at coordinates (5, 0, -20) Restrictions: Only works once per character

World Interaction Actions

`lootStarterChest`

Loot the starter chest for basic tools (one-time per character).

// From actions/autonomous.ts
export const lootStarterChestAction: Action = {
  name: "LOOT_STARTER_CHEST",
  description: "Search the starter chest to get starter equipment (bronze tools, tinderbox, net, food). Only works once per character.",
  parameters: {},
};

Starter Items:

Bronze hatchet (woodcutting)
Bronze pickaxe (mining)
Tinderbox (firemaking)
Small fishing net (fishing)
Shrimp x5 (food)

Location: Near spawn at coordinates (5, 0, -20) Behavior: If chest not nearby, agent walks to known location first.

Added in PR #628 to help new agents bootstrap their equipment.

Action Execution

Actions are executed through the HyperscapeService:

// From services/HyperscapeService.ts
async executeAction(name: string, params: Record<string, unknown>): Promise<boolean> {
  switch (name) {
    case "MOVE_TO":
      return this.moveTo(params.x, params.z);
    case "ATTACK_ENTITY":
      return this.attackEntity(params.targetId);
    case "CHOP_TREE":
      return this.chopTree(params.treeId);
    // ... other actions
  }
}

Action Selection (THINKING+ACTION Format)

As of PR #628, agents use a structured decision format:

THINKING: [Agent's reasoning about the situation]

ACTION: [Action name to execute]

Selection Pipeline

Providers - Gather game context (10 providers)
Compose State - Merge provider data
Evaluators - Assess opportunities (5 evaluators)
LLM Prompt - Build action selection prompt with OSRS common sense rules
LLM Response - Generate THINKING+ACTION
Parse - Extract reasoning and action name
Validate - Check if action is possible
Execute - Perform action via HyperscapeService

Survival Override

Before LLM selection, a force flee check runs:

// From autonomous-behavior-manager.ts
if (healthPercent < 25 && threats.length > 0) {
  // Bypass LLM - execute FLEE immediately
  await executeAction(fleeAction);
  return;
}

This ensures agents survive even if the LLM makes poor decisions.

Target Locking

During combat, agents lock onto targets for 30 seconds:

// From autonomous-behavior-manager.ts
private lockedTargetId: string | null = null;
private readonly TARGET_LOCK_TIMEOUT = 30000; // 30s

// In ATTACK_ENTITY action
if (lockedTargetId) {
  targetMob = attackableMobs.find(mob => mob.id === lockedTargetId);
  if (targetMob) {
    // Continue attacking locked target
  } else {
    // Target died/despawned, clear lock and find new target
    clearTargetLock();
  }
}

This prevents agents from switching between targets without finishing kills.

Overview

Engine Architecture

Client Application

Game Systems

AI Agents

Data Manifests

Technical Reference

​Agent Actions Reference

​Action Categories

Movement

Combat

Skills

Inventory

Social

Banking

Goals

World Interaction

​Movement Actions

​moveTo

​followEntity

​stopMovement

​explore

​approachEntity

​navigateTo

​Combat Actions

​attackEntity

​changeCombatStyle

​flee

​Skill Actions

​chopTree

​mineRock

​catchFish

​lightFire

​cookFood

​mineRock

​Inventory Actions

​equipItem

​useItem

​dropItem

​pickupItem

​Social Actions

​chatMessage

​Banking Actions

​bankDeposit

​bankWithdraw

​Goal Actions

​setGoal

​idle

​World Interaction Actions

​lootStarterChest

​World Interaction Actions

​lootStarterChest

​Action Execution

​Action Selection (THINKING+ACTION Format)

​Selection Pipeline

​Survival Override

​Target Locking

​Related Documentation

Agent Actions Reference

Action Categories

Movement Actions

`moveTo`

`followEntity`

`stopMovement`

`explore`

`approachEntity`

`navigateTo`

Combat Actions

`attackEntity`

`changeCombatStyle`

`flee`

Skill Actions

`chopTree`

`mineRock`

`catchFish`

`lightFire`

`cookFood`

`mineRock`

Inventory Actions

`equipItem`

`useItem`

`dropItem`

`pickupItem`

Social Actions

`chatMessage`

Banking Actions

`bankDeposit`

`bankWithdraw`

Goal Actions

`setGoal`

`idle`

World Interaction Actions

`lootStarterChest`

World Interaction Actions

`lootStarterChest`

Action Execution

Action Selection (THINKING+ACTION Format)

Selection Pipeline

Survival Override

Target Locking

Related Documentation