plugin-hyperia

Overview

The @hyperia/plugin-hyperia package enables AI agents to play Hyperia autonomously using ElizaOS:

Agent actions (combat, skills, movement)
World state providers
LLM decision-making via OpenAI/Anthropic/OpenRouter
Full player capabilities

Package Location

packages/plugin-hyperia/
├── src/
│   ├── actions/        # Agent actions
│   ├── clients/        # WebSocket client
│   ├── config/         # Configuration
│   ├── content-packs/  # Character templates
│   ├── evaluators/     # Goal evaluation
│   ├── events/         # Event handlers
│   ├── handlers/       # Message handlers
│   ├── managers/       # State management
│   ├── providers/      # World state providers
│   ├── routes/         # API routes
│   ├── services/       # Core services
│   ├── systems/        # Agent systems
│   ├── templates/      # LLM prompts
│   ├── testing/        # Test utilities
│   ├── types/          # TypeScript types
│   ├── utils/          # Helper functions
│   ├── index.ts        # Plugin entry
│   └── service.ts      # Main service
└── .env.example        # Environment template

Actions

Agent capabilities are defined in src/actions/:

// From packages/plugin-hyperia/src/index.ts
actions: [
  // Movement
  moveToAction,
  followEntityAction,
  stopMovementAction,

  // Combat
  attackEntityAction,
  changeCombatStyleAction,

  // Skills
  chopTreeAction,
  catchFishAction,
  lightFireAction,
  cookFoodAction,

  // Inventory
  equipItemAction,
  useItemAction,
  dropItemAction,

  // Social
  chatMessageAction,

  // Banking
  bankDepositAction,
  bankWithdrawAction,
],

Action Categories

Category	Actions	Source File
Movement	moveTo, followEntity, stopMovement	`actions/movement.ts`
Combat	attackEntity, changeCombatStyle	`actions/combat.ts`
Skills	chopTree, catchFish, lightFire, cookFood	`actions/skills.ts`
Inventory	equipItem, useItem, dropItem	`actions/inventory.ts`
Social	chatMessage	`actions/social.ts`
Banking	bankDeposit, bankWithdraw	`actions/banking.ts`

Action Locks and Fast-Tick Mode

Problem: Agents would spam LLM calls while waiting for movement to complete, wasting tokens and causing decision conflicts. Solution: Action lock system with fast-tick mode for responsive follow-up actions. Action Lock:

// From packages/plugin-hyperia/src/managers/autonomous-behavior-manager.ts

// Skip LLM tick while movement is in progress
if (this.actionLock) {
  logger.debug('[AutonomousBehavior] Action locked, skipping LLM tick');
  return;
}

// Set lock before movement
this.actionLock = true;
await service.executeMove({ target: resourcePosition });

// Wait for movement to complete
await service.waitForMovementComplete();

// Clear lock after movement
this.actionLock = false;

Fast-Tick Mode:

// Quick follow-up after movement/goal changes (2s instead of 10s)
if (this.shouldUseFastTick()) {
  this.tickInterval = 2000;  // 2 seconds
} else {
  this.tickInterval = 10000; // 10 seconds (normal)
}

Short-Circuit LLM: For obvious decisions, skip LLM and execute directly:

// Repeat resource gathering
if (lastAction === 'gather' && resourceStillAvailable) {
  return this.executeGather(sameResource);  // No LLM call
}

// Banking completion
if (atBank && inventoryFull) {
  return this.executeBankDeposit();  // No LLM call
}

// Goal-based actions
if (goal.type === 'woodcutting' && nearbyTree) {
  return this.executeChopTree(nearbyTree);  // No LLM call
}

Benefits:

90% reduction in LLM calls for repetitive tasks
Faster response to movement completion (2s vs 10s)
Lower costs from reduced API usage
More natural behavior (no pauses between actions)

Configuration:

# Disable action locks (not recommended)
AGENT_ACTION_LOCKS_ENABLED=false

# Disable fast-tick mode
AGENT_FAST_TICK_ENABLED=false

# Disable short-circuit LLM
AGENT_SHORT_CIRCUIT_LLM_ENABLED=false

Movement Completion Tracking

New API:

// Wait for current movement to complete
await service.waitForMovementComplete(timeoutMs?: number);

// Check if currently moving
const moving = service.isMoving;

How it works:

executeMove() sets _isMoving = true
tileMovementEnd packet sets _isMoving = false and resolves promise
waitForMovementComplete() returns immediately if not moving
Timeout (default 15s) prevents infinite waits

Example:

// Banking action now awaits movement completion
async executeBankDeposit() {
  // Walk to bank
  await service.executeMove({ target: bankPosition });
  
  // Wait for movement to complete
  await service.waitForMovementComplete();
  
  // Now interact with bank
  await service.openBank(bankId);
  await service.bankDepositAll();
}

Providers

World state is accessible to agents via 6 providers:

// From packages/plugin-hyperia/src/index.ts
providers: [
  gameStateProvider,        // Player health, stamina, position, combat status
  inventoryProvider,        // Inventory items, coins, free slots
  nearbyEntitiesProvider,   // Players, NPCs, resources nearby
  skillsProvider,           // Skill levels and XP
  equipmentProvider,        // Equipped items
  availableActionsProvider, // Context-aware available actions
],

Provider	Data
`gameStateProvider`	Health, stamina, position, combat status
`inventoryProvider`	Current inventory items and coins
`nearbyEntitiesProvider`	Players, NPCs, resources in range
`skillsProvider`	Skill levels and XP
`equipmentProvider`	Currently equipped items
`availableActionsProvider`	Context-aware actions (e.g., “can cook fish”)

Configuration

# LLM Provider (at least one required)
OPENAI_API_KEY=your-openai-key
# or
ANTHROPIC_API_KEY=your-anthropic-key
# or
OPENROUTER_API_KEY=your-openrouter-key

Running

bun run dev:elizaos    # Game + AI agents

This starts ElizaOS alongside the game server. The AI agent connects as a real player and plays autonomously.

Agent Architecture

Dependencies

Package	Version	Purpose
`@elizaos/core`	^1.2.9	ElizaOS framework
`@elizaos/plugin-anthropic`	^1.5.12	Anthropic LLM
`@elizaos/plugin-openai`	1.5.16	OpenAI LLM
`@elizaos/plugin-openrouter`	^1.5.15	OpenRouter LLM
`@elizaos/plugin-sql`	^1.6.4	SQL database
`@hyperia/shared`	workspace	Core engine
`ws`	^8.18.3	WebSocket client
`zod`	^3.25.67	Schema validation

Building

cd packages/plugin-hyperia
bun run build    # Compile TypeScript
bun run dev      # Watch mode

Key Files

File	Purpose
`src/index.ts`	Plugin registration
`src/service.ts`	Main service class
`src/actions/`	All agent actions
`src/providers/`	State providers
`src/templates/`	LLM prompt templates

License

MIT License - can be used in any ElizaOS agent.

Overview

Core Packages

Extensions

Overview

Package Location

Actions

Action Categories

Action Locks and Fast-Tick Mode

Movement Completion Tracking

Providers

Configuration

Running

Agent Architecture

Dependencies

Building

Key Files

License

​Overview

​Package Location

​Actions

​Action Categories

​Action Locks and Fast-Tick Mode

​Movement Completion Tracking

​Providers

​Configuration

​Running

​Agent Architecture

​Dependencies

​Building

​Key Files

​License

Overview

Package Location

Actions

Action Categories

Action Locks and Fast-Tick Mode

Movement Completion Tracking

Providers

Configuration

Running

Agent Architecture

Dependencies

Building

Key Files

License