Autonomous Agent Behavior

Overview

Hyperscape agents use ElizaOS to make autonomous decisions using LLMs. Recent improvements (commit 60a03f49, Feb 26 2026) added action locks, fast-tick mode, and short-circuit decision-making for more natural MMORPG behavior.

Decision-Making Architecture

LLM Tick Cycle

Agents evaluate their situation and choose actions on a regular tick cycle: Normal Tick: 10 seconds (default) Fast Tick: 2 seconds (after movement or goal changes)

// From packages/plugin-hyperscape/src/managers/autonomous-behavior-manager.ts
const NORMAL_TICK_INTERVAL = 10_000;  // 10 seconds
const FAST_TICK_INTERVAL = 2_000;     // 2 seconds

Action Locks

Problem: Agents would spam LLM calls while movement was in progress, wasting tokens and causing decision churn. Solution: Action locks prevent LLM ticks while movement is in progress:

// Set action lock when starting movement
this.actionLock = true;

// Movement completes
await this.waitForMovementComplete();

// Clear action lock
this.actionLock = false;

// Trigger fast tick for quick follow-up
this.triggerFastTick();

Benefits:

No wasted LLM calls during movement
Agents commit to actions instead of constantly re-evaluating
More natural behavior (walk to tree, chop, don’t reconsider mid-walk)

Fast-Tick Mode

After completing an action or changing goals, agents enter fast-tick mode for quick follow-up:

// Trigger fast tick after movement completes
this.triggerFastTick();

// Next tick happens in 2 seconds instead of 10
setTimeout(() => this.tick(), FAST_TICK_INTERVAL);

Use Cases:

After reaching a tree → quickly decide to chop
After banking → quickly resume previous goal
After completing quest → quickly set new goal

Short-Circuit LLM

For obvious decisions, agents skip the LLM and execute immediately:

// Short-circuit obvious decisions
if (shouldRepeatResource(gameState)) {
  return { action: 'CHOP_TREE', params: { treeId: lastTreeId } };
}

if (shouldBank(gameState)) {
  return { action: 'BANK_DEPOSIT_ALL', params: {} };
}

if (hasNewGoal(gameState)) {
  return { action: 'SET_GOAL', params: { goal: newGoal } };
}

// Otherwise, call LLM for decision
return await callLLM(gameState);

Short-Circuit Conditions:

Repeat resource: Same resource type nearby, inventory not full
Banking: Inventory ≥ 25/28 slots
Set goal: Goal changed externally (e.g., via dashboard)

Benefits:

Faster response times
Reduced LLM costs
More predictable behavior for repetitive tasks

Goal System

Goal Types

Agents can have different goal types with varying priorities:

Goal Type	Priority	Description
`questing`	Highest	Accept quests to get tools
`banking`	High	Deposit items when inventory full
`combat`	Medium	Fight specific mobs
`skilling`	Medium	Train specific skills
`exploration`	Low	Explore new areas

Banking Goal

Trigger: Inventory ≥ 25/28 slots Behavior:

Set banking goal with high priority
Walk to nearest bank
Execute BANK_DEPOSIT_ALL action
Restore previous goal after banking

// Auto-trigger banking goal
if (inventoryCount >= 25) {
  const previousGoal = currentGoal;
  
  setGoal({
    type: 'banking',
    description: 'Deposit items at bank',
    priority: 9,
    previousGoal: previousGoal  // Restore after banking
  });
}

Goal Restoration: After banking completes, the agent automatically restores their previous goal:

// After BANK_DEPOSIT_ALL completes
if (goal.type === 'banking' && goal.previousGoal) {
  setGoal(goal.previousGoal);
  triggerFastTick();  // Quick follow-up
}

Questing Goal

Trigger: Agent lacks essential tools (axe, pickaxe, tinderbox, net) Behavior:

Set questing goal with highest priority
Walk to quest NPC
Accept quest to receive tools
Resume previous goal

Tool-Granting Quests:

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

Movement Behavior

Await Movement Completion

Banking actions now await movement completion instead of returning early:

// ❌ Old: Returned early, agent never reached bank
await service.executeMove({ target: bankPosition });
return { success: true };  // Movement still in progress!

// ✅ New: Awaits movement completion
await service.executeMove({ target: bankPosition });
await service.waitForMovementComplete(15000);  // Wait up to 15s
// Now agent is at bank, can interact

Benefits:

Agents actually reach their destination before interacting
No “bank too far” errors from premature interaction attempts
More reliable autonomous behavior

Movement Tracking

The HyperscapeService tracks movement state:

// From packages/plugin-hyperscape/src/services/HyperscapeService.ts
private isMoving: boolean = false;

async executeMove(params: { target: [number, number, number] }): Promise<void> {
  this.isMoving = true;
  // Send move packet
}

async waitForMovementComplete(timeoutMs: number): Promise<boolean> {
  const deadline = Date.now() + timeoutMs;
  
  while (this.isMoving && Date.now() < deadline) {
    await new Promise(resolve => setTimeout(resolve, 100));
  }
  
  return !this.isMoving;
}

// Clear on movement complete packet
onMovementComplete() {
  this.isMoving = false;
}

Resource Detection

Approach Range

Resource detection range was increased from 20m to 40m to fix “choppableTrees=0” errors:

// ❌ Old: 20m range (too small)
const RESOURCE_APPROACH_RANGE = 20;

// ✅ New: 40m range (matches skills validation)
const RESOURCE_APPROACH_RANGE = 40;

Affected Actions:

CHOP_TREE
MINE_ROCK
CATCH_FISH

Why 40m:

Matches server-side skills validation range
Prevents “no resources nearby” errors when resources are visible
Agents can see and approach resources from further away

Depleted Resource Filtering

Agents now filter out depleted resources from nearby entity checks:

// Filter depleted resources
const availableResources = nearbyEntities.filter(entity => {
  if (entity.type === 'tree' || entity.type === 'rock' || entity.type === 'fishing_spot') {
    return entity.depleted !== true;
  }
  return true;
});

Benefits:

Agents don’t try to chop depleted trees
More efficient resource gathering
Reduces failed action attempts

LLM Context

Last Action Tracking

The LLM prompt now includes the last action and result for continuity:

// Track last action
this.lastActionName = 'CHOP_TREE';
this.lastActionResult = 'success';

// Include in LLM prompt
const prompt = `
Last action: ${this.lastActionName}
Result: ${this.lastActionResult}

Current situation:
...
`;

Benefits:

LLM understands what just happened
Better decision continuity
Avoids repeating failed actions

Inventory Display

The LLM prompt now shows inventory count with warnings:

// Inventory status
const inventoryCount = player.items.length;
const inventoryMax = 28;
const inventoryStatus = 
  inventoryCount >= 28 ? '🔴 FULL' :
  inventoryCount >= 25 ? '🟡 NEARLY FULL' :
  `${inventoryCount}/${inventoryMax}`;

// Include in prompt
Inventory: ${inventoryStatus}

Benefits:

Agents know when to bank
Visual warnings for full inventory
Prevents inventory overflow

Autonomous Banking

Banking Trigger

Agents automatically bank when inventory reaches 25/28 slots:

// Check inventory fullness
if (inventoryCount >= 25 && !player.inCombat) {
  // Set banking goal
  setGoal({
    type: 'banking',
    description: 'Deposit items at bank',
    priority: 9,
    previousGoal: currentGoal
  });
}

Banking Workflow

Detect full inventory (≥25/28 slots)
Set banking goal with high priority
Find nearest bank from nearby entities or world map
Walk to bank (await movement completion)
Open bank session (bankOpen packet)
Deposit all items (bankDepositAll packet)
Withdraw essential tools (axe, pickaxe, tinderbox, net)
Close bank session (bankClose packet)
Restore previous goal (e.g., woodcutting)
Trigger fast tick for quick follow-up

Essential Tools

These items are never deposited (always withdrawn back):

Hatchets: Bronze, Iron, Steel, Mithril
Pickaxes: Bronze, Iron, Steel, Mithril
Tinderbox: For firemaking
Small Fishing Net: For fishing

Why Keep Tools:

Agents need tools to continue gathering
Prevents “no axe” errors after banking
Matches natural MMORPG player behavior

Quest-Driven Progression

Starter Chest Removal

The old LOOT_STARTER_CHEST action was removed (commit 593cd56b). Agents now get tools through quests:

// ❌ Old: Direct item grants from starter chest
await service.lootStarterChest();
// Gave: Bronze Hatchet, Bronze Pickaxe, Tinderbox, Small Fishing Net

// ✅ New: Quest-based tool acquisition
await service.acceptQuest('lumberjacks_first_lesson');
// Gives: Bronze Hatchet + Tinderbox (immediately on accept)

Tool Acquisition Quests

Agents are guided toward quests for tools via game knowledge:

// From packages/plugin-hyperscape/src/providers/questProvider.ts
const questKnowledge = `
Tool Acquisition Quests:
- Lumberjack's First Lesson (Forester Wilma): Bronze Hatchet + Tinderbox
- Fresh Catch (Fisherman Pete): Small Fishing Net
- Torvin's Tools (Torvin): Bronze Pickaxe + Hammer

If you lack tools, set a questing goal to acquire them.
`;

Questing Goal Priority: When agent lacks tools, questing goal has highest priority:

// Check for missing tools
const hasAxe = inventory.some(item => item.name.includes('axe'));
const hasPickaxe = inventory.some(item => item.name.includes('pickaxe'));
const hasTinderbox = inventory.some(item => item.name.includes('tinderbox'));
const hasNet = inventory.some(item => item.name.includes('net'));

if (!hasAxe || !hasPickaxe || !hasTinderbox || !hasNet) {
  setGoal({
    type: 'questing',
    description: 'Accept quests to get tools',
    priority: 10  // Highest priority
  });
}

Performance Optimizations

Action Lock Benefits

Before (without action locks):

Agent starts walking to tree (10s journey)
LLM ticks every 10s during walk
1 walk = 1 LLM call (wasted)
Total: 2 LLM calls (1 wasted)

After (with action locks):

Agent starts walking to tree (10s journey)
Action lock prevents LLM ticks during walk
Agent reaches tree
Fast tick triggers (2s)
Total: 1 LLM call (0 wasted)

Savings: 50% reduction in LLM calls for movement-heavy tasks

Short-Circuit Benefits

Before (without short-circuit):

Agent chops tree
Inventory not full, same tree type nearby
LLM call to decide next action
LLM says “chop another tree”
Total: 1 LLM call per tree

After (with short-circuit):

Agent chops tree
Inventory not full, same tree type nearby
Short-circuit: repeat last action
Total: 0 LLM calls (instant decision)

Savings: 100% reduction in LLM calls for repetitive tasks

Configuration

Enable/Disable Features

# Action locks (always enabled, no config)
# Fast-tick mode (always enabled, no config)
# Short-circuit LLM (always enabled, no config)

# Autonomous behavior (for embedded agents)
EMBEDDED_AGENT_AUTONOMY_ENABLED=false  # Disable for streaming (default)
AUTO_START_AGENTS=true                 # Auto-load embedded agents
AUTO_START_AGENTS_MAX=10               # Max embedded agents

Tick Intervals

# Normal tick interval (default: 10s)
AGENT_TICK_INTERVAL_MS=10000

# Fast tick interval (default: 2s)
AGENT_FAST_TICK_INTERVAL_MS=2000

Debugging

Action Lock Status

Check if agent is locked:

// From HyperscapeService
console.log('Action lock:', service.actionLock);
console.log('Is moving:', service.isMoving);

Last Action Tracking

View last action in agent logs:

// From autonomous-behavior-manager.ts
console.log('Last action:', this.lastActionName);
console.log('Last result:', this.lastActionResult);

Goal History

View goal changes:

// From goal provider
console.log('Current goal:', currentGoal);
console.log('Previous goal:', previousGoal);
console.log('Goal type:', currentGoal.type);
console.log('Goal priority:', currentGoal.priority);

Agent Actions Reference - All available actions
Agent Providers - Context providers
ElizaOS Integration - ElizaOS setup

Commit History

Autonomous behavior improvements:

60a03f49 (Feb 26, 2026): Action locks, fast-tick, short-circuit LLM, await banking movement
593cd56b (Feb 26, 2026): Quest-driven tools, autonomous banking, resource detection fixes

Overview

Engine Architecture

Client Application

Game Systems

AI Agents

Data Manifests

Technical Reference

​Overview

​Decision-Making Architecture

​LLM Tick Cycle

​Action Locks

​Fast-Tick Mode

​Short-Circuit LLM

​Goal System

​Goal Types

​Banking Goal

​Questing Goal

​Movement Behavior

​Await Movement Completion

​Movement Tracking

​Resource Detection

​Approach Range

​Depleted Resource Filtering

​LLM Context

​Last Action Tracking

​Inventory Display

​Autonomous Banking

​Banking Trigger

​Banking Workflow

​Essential Tools

​Quest-Driven Progression

​Starter Chest Removal

​Tool Acquisition Quests

​Performance Optimizations

​Action Lock Benefits

​Short-Circuit Benefits

​Configuration

​Enable/Disable Features

​Tick Intervals

​Debugging

​Action Lock Status

​Last Action Tracking

​Goal History

​Related Documentation

​Commit History

Overview

Decision-Making Architecture

LLM Tick Cycle

Action Locks

Fast-Tick Mode

Short-Circuit LLM

Goal System

Goal Types

Banking Goal

Questing Goal

Movement Behavior

Await Movement Completion

Movement Tracking

Resource Detection

Approach Range

Depleted Resource Filtering

LLM Context

Last Action Tracking

Inventory Display

Autonomous Banking

Banking Trigger

Banking Workflow

Essential Tools

Quest-Driven Progression

Starter Chest Removal

Tool Acquisition Quests

Performance Optimizations

Action Lock Benefits

Short-Circuit Benefits

Configuration

Enable/Disable Features

Tick Intervals

Debugging

Action Lock Status

Last Action Tracking

Goal History

Related Documentation

Commit History