Agent Actions Reference

Complete reference for ElizaOS agent actions

Agent Actions Reference

This page documents all 24 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/.

Action Categories

Movement

6 actions for navigation

Combat

3 actions for fighting

Skills

4 actions for gathering/crafting

Inventory

3 actions for item management

Social

1 action for communication

Banking

3 actions for storage

Goals

2 actions for planning

Questing

2 actions for quests

---

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: {},
};

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')" },
  },
};

Usage: Navigate using location names instead of coordinates.

---

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. Automatically walks to tree if within 40m approach range.

// 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.

Approach Range: 40m (increased from 20m in commit 593cd56b to fix “choppableTrees=0” errors despite visible trees)

How to Get Hatchet: Accept quest lumberjacks_first_lesson from Forester Wilma (grants Bronze Hatchet + Tinderbox immediately)

---

mineRock

Mine a rock for ore. Automatically walks to rock if within 40m approach range.

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

Requirements: Pickaxe in inventory, Mining level.

Approach Range: 40m (increased from 20m in commit 593cd56b to match skills validation)

How to Get Pickaxe: Accept quest torvins_tools from Torvin (grants Bronze Pickaxe + Hammer immediately)

---

catchFish

Catch fish at a fishing spot. Automatically walks to spot if within 40m approach range.

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 net or rod in inventory, Fishing level.

Approach Range: 40m (increased from 20m in commit 593cd56b)

How to Get Fishing Net: Accept quest fresh_catch from Fisherman Pete (grants Small Fishing Net immediately)

---

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.

---

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",
  parameters: {
    itemId: { type: "string", description: "Item ID to drop" },
    quantity: { type: "number", optional: true, description: "Amount to drop" },
  },
};

Usage: Make room in inventory.

---

Social Actions

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 specific items into bank. Automatically walks to nearest bank if not already there.

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

Behavior:

1. Finds nearest bank entity or station
2. Walks to bank if distance > 5 units (awaits movement completion)
3. Opens bank session (bankOpen packet)
4. Deposits specified item (bankDeposit packet)
5. Closes bank session (bankClose packet)

---

bankWithdraw

Withdraw items from bank. Automatically walks to nearest bank if not already there.

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

Behavior:

1. Finds nearest bank entity or station
2. Walks to bank if distance > 5 units (awaits movement completion)
3. Opens bank session (bankOpen packet)
4. Withdraws specified item (bankWithdraw packet)
5. Closes bank session (bankClose packet)

---

bankDepositAll

Deposit all non-essential items at the bank. Keeps essential tools (axe, pickaxe, tinderbox, fishing net). Automatically walks to nearest bank and awaits movement completion.

export const bankDepositAllAction: Action = {
  name: "BANK_DEPOSIT_ALL",
  description: "Deposit all non-essential items at the bank. Keeps tools (axe, pickaxe, tinderbox, net). Use when inventory is full from gathering.",
  parameters: {},
};

Behavior (commit 60a03f49, Feb 26 2026):

1. Finds nearest bank entity or station from nearby entities or world map
2. Walks to bank if distance > 5 units (awaits movement completion)
3. Opens bank session (bankOpen packet)
4. Deposits ALL items (bankDepositAll packet)
5. Withdraws back essential tools one by one (bankWithdraw packets)
6. Closes bank session (bankClose packet)

Essential Items (Never Deposited):

• Bronze/Iron/Steel/Mithril Hatchet
• Bronze/Iron/Steel/Mithril Pickaxe
• Tinderbox
• Small Fishing Net

Autonomous Banking Behavior:

• Agents automatically bank when inventory reaches 25/28 slots
• Banking goal has high priority (triggers before gathering goals)
• After banking, agent restores previous goal (e.g., woodcutting)
• Movement is awaited (no early return) to ensure agent reaches bank

Bank Packet Protocol (commit 593cd56b):

The old bankAction packet was broken. The new protocol uses proper packet sequence:

// ❌ Old (broken)
socket.send({ type: 'bankAction', action: 'depositAll' });

// ✅ New (correct)
socket.send({ type: 'bankOpen', entityId: bankId });
socket.send({ type: 'bankDepositAll' });
socket.send({ type: 'bankWithdraw', itemId: 'bronze_hatchet', quantity: 1 });
socket.send({ type: 'bankClose' });

Usage: Autonomous agents use this when inventory reaches 25/28 slots to free space for continued gathering.

This action replaced the old LOOT_STARTER_CHEST action as part of the quest-driven progression system (commit 593cd56b, Feb 26 2026).

Related Changes:

• Action locks prevent LLM ticks while movement is in progress (commit 60a03f49)
• Fast-tick mode (2s) for quick follow-up after movement/goal changes
• Short-circuit LLM for obvious decisions (repeat resource, banking, set goal)
• Banking goal type with auto-restore of previous goal after deposit
• Await movement completion instead of returning early (ensures agent reaches bank)

---

Questing Actions

acceptQuest

Accept a quest from an NPC. Quest items are granted immediately on accept.

// From actions/quests.ts
export const acceptQuestAction: Action = {
  name: "ACCEPT_QUEST",
  description: "Accept a quest from an NPC. Quest items are granted immediately.",
  parameters: {
    questId: { type: "string", description: "Quest ID to accept" },
    npcId: { type: "string", optional: true, description: "NPC entity ID" },
  },
};

Usage: Get starter tools and rewards from quests.

Tool-Granting Quests:

• lumberjacks_first_lesson → Bronze Hatchet + Tinderbox (from Forester Wilma)
• fresh_catch → Small Fishing Net (from Fisherman Pete)
• torvins_tools → Bronze Pickaxe + Hammer (from Torvin)

Quest-based tool acquisition replaced the old starter chest system (commit 593cd56b). Agents now get tools by talking to NPCs and accepting quests.

---

completeQuest

Complete a quest and claim rewards.

export const completeQuestAction: Action = {
  name: "COMPLETE_QUEST",
  description: "Complete a quest and claim XP/item rewards",
  parameters: {
    questId: { type: "string", description: "Quest ID to complete" },
  },
};

Usage: Turn in completed quests for XP rewards.

---

Goal Actions

setGoal

Set a new goal for the agent.

// From actions/goals.ts
export const setGoalAction: Action = {
  name: "SET_GOAL",
  description: "Set a new goal for autonomous behavior",
  parameters: {
    goal: {
      type: "string",
      description: "Goal description (e.g., 'reach level 10 woodcutting')",
    },
    priority: { type: "number", optional: true, description: "Priority (1-10)" },
  },
};

Usage: Direct agent behavior toward objectives.

Example Goals:

• “Reach level 10 Woodcutting”
• “Collect 100 logs”
• “Kill 50 goblins”
• “Earn 10,000 coins”

New Goal Types (commit 60a03f49):

• questing - Accept quests to get tools
• banking - Deposit items when inventory full

---

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" },
  },
};

Usage: Wait for events, conserve resources.

---

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

The LLM selects actions based on:

1. Providers - Current game state context
2. Evaluators - Assessment of opportunities
3. Goals - Current objectives
4. Available Actions - Context-aware action list

// Provider supplies available actions
export const availableActionsProvider: Provider = {
  name: "availableActions",
  async get(runtime, state): Promise<string> {
    const gameState = await getGameState(runtime);

    const actions = [];

    // Combat actions if enemies nearby
    if (gameState.nearbyEnemies.length > 0) {
      actions.push("ATTACK_ENTITY", "FLEE");
    }

    // Skill actions if resources nearby
    if (gameState.nearbyTrees.length > 0 && hasHatchet(gameState)) {
      actions.push("CHOP_TREE");
    }

    // ... more context-aware action filtering

    return formatActionList(actions);
  },
};

---

Related Documentation

• Providers Reference
• ElizaOS Integration
• Agent Configuration