> ## Documentation Index > Fetch the complete documentation index at: https://hyperscape-ai-mintlify-docs-update.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 6 actions for navigation 3 actions for fighting 4 actions for gathering/crafting 3 actions for item management 1 action for communication 3 actions for storage 2 actions for planning 2 actions for quests *** ## Movement Actions ### `moveTo` Move to specific coordinates. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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: ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // ❌ 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // 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: ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // From services/HyperscapeService.ts async executeAction(name: string, params: Record): Promise { 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 ```typescript theme={"theme":{"light":"github-light","dark":"tokyo-night"}} // Provider supplies available actions export const availableActionsProvider: Provider = { name: "availableActions", async get(runtime, state): Promise { 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](/wiki/ai-agents/providers) * [ElizaOS Integration](/wiki/ai-agents/elizaos) * [Agent Configuration](/wiki/ai-agents/config)