> ## Documentation Index > Fetch the complete documentation index at: https://hyperscape-ai.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 **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 6 actions for navigation 3 actions for fighting 5 actions for gathering/crafting 4 actions for item management 1 action for communication 2 actions for storage 2 actions for planning 1 action for world objects *** ## Movement Actions ### `moveTo` Move to specific coordinates. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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":"css-variables"}} 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":"css-variables"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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":"css-variables"}} 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":"css-variables"}} // 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: 1. Calculates intermediate waypoint (150 tiles toward destination) 2. Moves to waypoint 3. On next tick, continues toward destination 4. Repeats until destination reached This prevents movement command rejection while maintaining progress toward distant goals. *** ## Combat Actions ### `attackEntity` Attack a target entity. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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":"css-variables"}} 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":"css-variables"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} 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":"css-variables"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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":"css-variables"}} 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":"css-variables"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} 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` *** ## Social Actions ### `chatMessage` Send a chat message. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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):** 1. **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... 2. **LLM selects** best goal based on: * Current skills and levels * Inventory contents * Nearby resources * Combat readiness * Recent goal history (diversity penalty) 3. **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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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. ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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). ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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: ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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 (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 1. **Providers** - Gather game context (10 providers) 2. **Compose State** - Merge provider data 3. **Evaluators** - Assess opportunities (5 evaluators) 4. **LLM Prompt** - Build action selection prompt with OSRS common sense rules 5. **LLM Response** - Generate THINKING+ACTION 6. **Parse** - Extract reasoning and action name 7. **Validate** - Check if action is possible 8. **Execute** - Perform action via HyperscapeService ### Survival Override Before LLM selection, a force flee check runs: ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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: ```typescript theme={"theme":{"light":"github-light","dark":"css-variables"}} // 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. *** ## Related Documentation * [Providers Reference](/wiki/ai-agents/providers) * [ElizaOS Integration](/wiki/ai-agents/elizaos) * [Agent Configuration](/wiki/ai-agents/config)