plugin-hyperscape

Overview

The @hyperscape/plugin-hyperscape package enables AI agents to play Hyperscape 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-hyperscape/
├── 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 (local type definitions)
│   │   ├── core-types.ts      # Local World, Entity, System, Player types
│   │   ├── core-interfaces.ts # Agent interfaces
│   │   ├── external-libs.ts   # THREE and PhysX types
│   │   └── system-types.ts    # System interfaces
│   ├── utils/          # Helper functions
│   ├── index.ts        # Plugin entry
│   └── service.ts      # Main service
└── .env.example        # Environment template

Type System (PR #629): The plugin now defines core types locally instead of importing from @hyperscape/shared to resolve 70+ TypeScript build errors. This ensures compatibility with ElizaOS’s isolatedModules requirement.

Actions

Agent capabilities are defined in src/actions/:

// From packages/plugin-hyperscape/src/index.ts
actions: [
  // Movement (6 actions)
  moveToAction,
  followEntityAction,
  stopMovementAction,
  exploreAction,
  approachEntityAction,
  navigateToAction,

  // Combat (3 actions)
  attackEntityAction,
  changeCombatStyleAction,
  fleeAction,

  // Skills (4 actions)
  chopTreeAction,
  catchFishAction,
  lightFireAction,
  cookFoodAction,

  // Inventory (4 actions)
  equipItemAction,
  useItemAction,
  dropItemAction,
  pickupItemAction,  // NEW in ElizaOS 1.7

  // Social (1 action)
  chatMessageAction,

  // Banking (2 actions)
  bankDepositAction,
  bankWithdrawAction,

  // Goals (2 actions)
  setGoalAction,
  idleAction,
],

Action Categories

Category	Actions	Source File
Movement	moveTo, followEntity, stopMovement, explore, approachEntity, navigateTo	`actions/movement.ts`, `actions/autonomous.ts`, `actions/goals.ts`
Combat	attackEntity, changeCombatStyle, flee	`actions/combat.ts`, `actions/autonomous.ts`
Skills	chopTree, catchFish, lightFire, cookFood	`actions/skills.ts`
Inventory	equipItem, useItem, dropItem, pickupItem	`actions/inventory.ts`
Social	chatMessage	`actions/social.ts`
Banking	bankDeposit, bankWithdraw	`actions/banking.ts`
Goals	setGoal, idle	`actions/goals.ts`, `actions/autonomous.ts`

New Actions in 1.7

PICKUP_ITEM: Pick up items from the ground with smart matching

Word-boundary scoring prevents false matches
Auto-walks to items beyond pickup range
Handles server’s 200-tile movement limit

DROP_ITEM Enhancements:

“Drop all” support for entire inventory
“Drop all <type>” for specific item types
Safety limits (max 50 items)
Consecutive failure protection

Providers

World state is accessible to agents via 6 providers:

// From packages/plugin-hyperscape/src/index.ts (lines 148-156)
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.7.0	ElizaOS framework
`@elizaos/plugin-anthropic`	^1.5.12	Anthropic LLM
`@elizaos/plugin-openai`	^1.6.0	OpenAI LLM
`@elizaos/plugin-openrouter`	^1.5.17	OpenRouter LLM
`@elizaos/plugin-ollama`	^1.2.4	Ollama local LLM
`@elizaos/plugin-sql`	^1.7.0	SQL database
`@hyperscape/shared`	workspace	Core engine
`ws`	^8.18.3	WebSocket client
`zod`	^3.25.67	Schema validation

Type System

Breaking Change (PR #629): The plugin now uses local type definitions instead of importing from @hyperscape/shared to fix TypeScript build errors with isolatedModules.

Local Type Definitions

Core types are defined in src/types/core-types.ts:

// Local type aliases for THREE types
export type Vector3 = THREEVector3;
export type Quaternion = THREEQuaternion;
export type Object3D = THREEObject3D;

// World type as instance type of WorldClass
export type World = InstanceType<typeof WorldClass>;

// System type based on SystemClass
export type System = InstanceType<typeof SystemClass>;

// Entity interface defined locally
export interface Entity {
  id: string;
  type: string;
  data?: Record<string, unknown>;
  node: {
    position: Vector3;
    quaternion: Quaternion;
    visible?: boolean;
  };
  velocity?: Vector3;
  speed?: number;
  isMoving?: boolean;
}

// Player interface extends Entity
export interface Player extends Entity {
  username?: string;
  input?: PlayerInput;
  stats?: PlayerStats;
  health?: { current: number; max: number };
  inventory?: unknown;
  equipment?: unknown;
}

Why Local Types?

The plugin uses isolatedModules: true (required by ElizaOS), which prevents importing class values as types. Local type definitions solve this by:

Importing THREE types directly from 'three' package
Defining PhysX types locally (PxVec3, PxTransform, PxQuat)
Using InstanceType<typeof WorldClass> for World type
Defining Entity, Player, System interfaces locally

This approach ensures the plugin builds successfully while maintaining type safety and compatibility with ElizaOS.

Building

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

Dashboard Features

The ElizaOS 1.7 upgrade includes comprehensive dashboard improvements: One-click commands for common tasks:

🪓 Woodcutting - Chop nearest tree
⛏️ Mining - Mine nearest ore
🎣 Fishing - Fish at nearest spot
⚔️ Combat - Attack nearest enemy
📦 Pick Up - Pick up nearby items
🏦 Bank - Go to bank
⏹️ Stop - Stop current goal immediately
⏸️ Idle - Set agent to idle mode

Stop/Resume Goal Controls

Stop Button: Halts agent and prevents auto-goal setting

Immediate halt - cancels movement path
Paused state UI - shows “Goals Paused”
Blocks auto-goals - SET_GOAL actions blocked while paused
Chat commands still work - user can send commands
Pause persists - agent returns to idle after commands

API Endpoints:

POST /api/agents/:agentId/goal/stop    # Stop goal and pause
POST /api/agents/:agentId/goal/resume  # Resume autonomous behavior

Dashboard Panels

AgentSummaryCard: Quick overview with combat level, total level, current goal AgentGoalPanel: Goal progress with time estimates and XP rates AgentSkillsPanel: Skill levels with session XP tracking AgentActivityPanel: Recent actions and session stats AgentPositionPanel: Location with nearby POIs and zone detection

Rate Limiting Improvements

Dashboard polling intervals increased to prevent 429 errors:

AgentSummaryCard: 2s → 10s
AgentGoalPanel: 2s → 10s
AgentSkillsPanel: 2-5s → 10s
AgentActivityPanel: 3s → 10s
AgentPositionPanel: 1-3s → 5-10s

All API calls include retry logic with exponential backoff (1s → 2s → 4s).

Key Files

File	Purpose
`src/index.ts`	Plugin registration
`src/services/HyperscapeService.ts`	Main service class
`src/actions/`	All agent actions
`src/providers/`	State providers
`src/templates/`	LLM prompt templates
`src/managers/autonomous-behavior-manager.ts`	Goal management and pause state

API Endpoints

Agent Management

GET  /api/agents/:agentId/goal           # Get current goal
POST /api/agents/:agentId/goal           # Set new goal
POST /api/agents/:agentId/goal/stop      # Stop and pause goals
POST /api/agents/:agentId/goal/resume    # Resume autonomous behavior
POST /api/agents/:agentId/message        # Send message to agent
GET  /api/agents/:agentId/quick-actions  # Get quick action menu data
GET  /api/agents/mapping/:agentId        # Get agent-to-character mapping

Data Endpoints

GET /api/data/skill-unlocks              # Get skill unlock definitions
GET /api/characters/:characterId/skills  # Get character skills
GET /api/characters/:characterId/position # Get character position

License

MIT License - can be used in any ElizaOS agent.

Overview

Core Packages

Extensions

Overview

Package Location

Actions

Action Categories

New Actions in 1.7

Providers

Configuration

Running

Agent Architecture

Dependencies

Type System

Local Type Definitions

Why Local Types?

Building

Dashboard Features

Quick Action Menu

Stop/Resume Goal Controls

Dashboard Panels

Rate Limiting Improvements

Key Files

API Endpoints

Agent Management

Data Endpoints

License

Overview

Core Packages

Extensions

​Overview

​Package Location

​Actions

​Action Categories

​New Actions in 1.7

​Providers

​Configuration

​Running

​Agent Architecture

​Dependencies

​Type System

​Local Type Definitions

​Why Local Types?

​Building

​Dashboard Features

​Quick Action Menu

​Stop/Resume Goal Controls

​Dashboard Panels

​Rate Limiting Improvements

​Key Files

​API Endpoints

​Agent Management

​Data Endpoints

​License

Overview

Package Location

Actions

Action Categories

New Actions in 1.7

Providers

Configuration

Running

Agent Architecture

Dependencies

Type System

Local Type Definitions

Why Local Types?

Building

Dashboard Features

Quick Action Menu

Stop/Resume Goal Controls

Dashboard Panels

Rate Limiting Improvements

Key Files

API Endpoints

Agent Management

Data Endpoints

License