How elizaos/eliza-3d-hyperfy-starter works
Project type and purpose
• This is a full-stack, plugin-based “agent” project that runs inside a Hyperfy client.
• It combines:
• A core “plugin-bootstrap” SDK (a generic plugin framework with actions/providers/services)
• A “plugin-hyperfy” extension (Hyperfy-specific integration: event handlers, managers, systems)
• A small “simple-agent” harness for local testing (loads avatars, exercises the agent)
• 3D assets (VRM avatar, GLB emotes) and a PhysX physics engine (WASM/WebIDL)
File structure
Top-level:
• package.json, tsconfig, build/test configs (tsup, vitest)
• .env.example for Hyperfy credentials
• avatar.vrm + emotes/*.glb (3D assets)
• simple-agent/ (JS harness & controls)
• src/index.ts (entry point)
• src/plugin-bootstrap/ (core plugin SDK – actions, providers, dist, tests)
• src/plugin-hyperfy/ (Hyperfy plugin – actions, managers, providers, systems, PhysX loader)
Key insights from README
• This code “wraps plugin development of a Hyperfy client” so Eliza (the agent) can connect and act like a user.
• You run Hyperfy separately, inject these ENV variables, then npm run dev to start the agent in Hyperfy.
Main components & their relationships
A. Hyperfy Client (external system)
• Emits events: user chat, world updates, user movement
• Exposes APIs: move avatar, play emote, send chat, voice (LiveKit)
B. plugin-hyperfy
• “Systems” subscribe to Hyperfy events (src/plugin-hyperfy/systems/*.ts)
• “Managers” provide high-level actions (emote-manager, message-manager, voice-manager, etc.)
• Uses PhysX (loadPhysX.js + WASM) for physics simulations
• Implements providers (world, emote, etc.) that feed into plugin-bootstrap logic
→ Depends on plugin-bootstrap’s interfaces (actions, providers)
C. plugin-bootstrap
• Defines generic plugin lifecycle, action handlers, providers (time, recentMessages, shouldRespond, etc.)
• Hosts logic modules and utilities (src/plugin-bootstrap/src/*.ts)
• Built + tested independently (dist/, __tests__/)
→ Provides a pluggable API consumed by any environment (here, Hyperfy)
D. simple-agent harness
• A minimal loader (AgentLoader.js) and controls (AgentControls.js)
• Loads the VRM avatar, connects to the agent code, simulates user input for local dev
E. Assets & External Services
• 3D assets (avatar.vrm, emotes/*.glb)
• PhysX WASM module
• Hyperfy backend & LiveKit for voice
Architectural patterns & design principles
• Plugin-based architecture (bootstrap SDK + environment plugin)
• Provider/Dependency-injection pattern for state (time, world, messages)
• ECS-style “systems” for event handling and update loops
• Clear separation of concerns: core logic vs. environment glue vs. assets