# elizaos/eliza-3d-hyperfy-starter architecture

> Architecture diagram of the GitHub repository elizaos/eliza-3d-hyperfy-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elizaos/eliza-3d-hyperfy-starter
- Repository: https://github.com/elizaos/eliza-3d-hyperfy-starter

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB

    %% External Systems
    subgraph "External Systems" 
        direction TB
        HyperfyClient["Hyperfy Client"]:::external
        LiveKit["LiveKit Voice"]:::external
    end

    %% Core Plugin SDK
    subgraph "Core Plugin SDK (Blue)" 
        direction TB
        PBSrc["plugin-bootstrap/src"]:::core
        PBDist["plugin-bootstrap/dist"]:::core
        PBTests["plugin-bootstrap/__tests__"]:::core
        PBPhysXJS["physx-js-webidl.js (stub)"]:::core
        PBPhysXWASM["physx-js-webidl.wasm (stub)"]:::core
    end

    %% Hyperfy Integration Plugin
    subgraph "Hyperfy Integration (Green)"
        direction TB
        PHRoot["plugin-hyperfy"]:::integration
        subgraph Systems
            direction TB
            PHSystems["src/plugin-hyperfy/systems"]:::integration
        end
        subgraph Managers
            direction TB
            PHManagers["src/plugin-hyperfy/managers"]:::integration
        end
        subgraph Providers
            direction TB
            PHProviders["src/plugin-hyperfy/providers"]:::integration
        end
        subgraph PhysX_Env
            direction TB
            LoadPhysX["loadPhysX.js"]:::integration
            PhysXJS["physx-js-webidl.js"]:::integration
            PhysXWASM["physx-js-webidl.wasm"]:::integration
        end
    end

    %% Simple-Agent Harness
    subgraph "Simple-Agent Harness"
        direction TB
        AgentLoader["simple-agent/AgentLoader.js"]:::harness
        AgentControls["simple-agent/AgentControls.js"]:::harness
        AgentIndex["simple-agent/index.mjs"]:::harness
    end

    %% Assets & Engines
    subgraph "Assets & Engines" 
        direction TB
        Avatar["avatar.vrm"]:::assets
        Emotes["emotes/"]:::assets
    end

    %% Tooling
    subgraph "Tooling"
        direction TB
        Tsup["tsup"]:::tooling
        Vitest["Vitest"]:::tooling
    end

    %% Relationships
    HyperfyClient -->|emits events| PHSystems
    PHSystems -->|uses interfaces| PBSrc
    PBSrc -->|decision logic| PHManagers
    PHManagers -->|calls API| HyperfyClient
    PHManagers -->|voice via| LiveKit

    LoadPhysX --> PhysXJS
    LoadPhysX --> PhysXWASM
    LoadPhysX -->|loads assets| Avatar
    LoadPhysX -->|loads assets| Emotes

    AgentLoader -->|connects to| PHRoot
    AgentLoader -->|uses core| PBSrc
    AgentControls --> AgentLoader
    AgentIndex --> AgentLoader

    %% Click Events
    click PBSrc "https://github.com/elizaos/eliza-3d-hyperfy-starter/tree/main/src/plugin-bootstrap/src"
    click PBDist "https://github.com/elizaos/eliza-3d-hyperfy-starter/tree/main/src/plugin-bootstrap/dist"
    click PBTests "https://github.com/elizaos/eliza-3d-hyperfy-starter/tree/main/src/plugin-bootstrap/__tests__"
    click PHRoot "https://github.com/elizaos/eliza-3d-hyperfy-starter/tree/main/src/plugin-hyperfy"
    click PHSystems "https://github.com/elizaos/eliza-3d-hyperfy-starter/tree/main/src/plugin-hyperfy/systems"
    click PHManagers "https://github.com/elizaos/eliza-3d-hyperfy-starter/tree/main/src/plugin-hyperfy/managers"
    click PHProviders "https://github.com/elizaos/eliza-3d-hyperfy-starter/tree/main/src/plugin-hyperfy/providers"
    click LoadPhysX "https://github.com/elizaos/eliza-3d-hyperfy-starter/blob/main/src/plugin-hyperfy/physx/loadPhysX.js"
    click PhysXJS "https://github.com/elizaos/eliza-3d-hyperfy-starter/blob/main/src/plugin-hyperfy/physx/physx-js-webidl.js"
    click PhysXWASM "https://github.com/elizaos/eliza-3d-hyperfy-starter/blob/main/src/plugin-hyperfy/physx/physx-js-webidl.wasm"
    click AgentLoader "https://github.com/elizaos/eliza-3d-hyperfy-starter/blob/main/simple-agent/AgentLoader.js"
    click AgentControls "https://github.com/elizaos/eliza-3d-hyperfy-starter/blob/main/simple-agent/AgentControls.js"
    click AgentIndex "https://github.com/elizaos/eliza-3d-hyperfy-starter/blob/main/simple-agent/index.mjs"
    click Avatar "https://github.com/elizaos/eliza-3d-hyperfy-starter/blob/main/avatar.vrm"
    click Emotes "https://github.com/elizaos/eliza-3d-hyperfy-starter/tree/main/emotes/"

    %% Styles
    classDef external fill:#ffcc00,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef integration fill:#90EE90,stroke:#333,stroke-width:1px
    classDef harness fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef assets fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef tooling fill:#eee,stroke:#333,stroke-width:1px
```
