# jerometremblay/hyperfy architecture

> Architecture diagram of the GitHub repository jerometremblay/hyperfy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jerometremblay/hyperfy
- Repository: https://github.com/jerometremblay/hyperfy

## Overview

Hyperfy is a browser-based multiplayer 3D world platform, with this fork adding construction tools, splats, browser surfaces, pose editing, and enhanced XR avatars. The main workflow is a player entering a world, where the client renders and synchronizes a shared scene; users can build or edit objects and interact with other players. Server-side world networking and persistence support that experience. The README documents the fork’s feature branches, while source excerpts expose world setup and selected builder, app, and server behavior; relationships for unsampled systems are omitted unless documented.

Main entry points: [`src/core/createClientWorld.js`](https://github.com/jerometremblay/hyperfy/blob/main/src/core/createClientWorld.js) (Client world setup), [`src/server/index.js`](https://github.com/jerometremblay/hyperfy/blob/main/src/server/index.js) (Server entry), [`src/client/world-client.js`](https://github.com/jerometremblay/hyperfy/blob/main/src/client/world-client.js) (Client entry), [`src/core/entities/App.js`](https://github.com/jerometremblay/hyperfy/blob/main/src/core/entities/App.js) (App runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["World runtime"]
  node_client["Client entry<br/>[world-client.js]"]
  node_world["World simulation<br/>[World.js]"]
  node_systems["System lifecycle<br/>[System.js]"]
  node_clientworld["Client world setup"]
  node_network["Client networking<br/>[ClientNetwork.js]"]
  node_scene["Scene nodes<br/>[Node.js]"]
  node_apps["App runtime<br/>[App.js]"]
  node_three["3D utilities<br/>[three.js]"]
  node_priorities["Control priorities"]
  node_layers["Scene layers<br/>[Layers.js]"]
  node_apphelpers["App tools<br/>[appTools.js]"]
  node_lockdown["Runtime lockdown<br/>[lockdown.js]"]
  node_actions["Client actions<br/>[ClientActions.js]"]
end

subgraph group_editing["Building and editing"]
  node_ui["Core world UI<br/>[Sidebar.js]"]
  node_builder["World builder<br/>[ClientBuilder.js]"]
  node_prompt["Prompt-box workflow"]
end

subgraph group_avatar["Avatars and interaction"]
  node_pose["Sitting-pose editor"]
  node_controls["Controls and hand tracking<br/>[ClientControls.js]"]
  node_nametags["Player nametags<br/>[Nametags.js]"]
end

subgraph group_server["Server services"]
  node_server["Server entry<br/>[index.js]"]
  node_serverworld["Server world setup"]
  node_database[("World database<br/>[db.js]")]
  node_storage[("Server storage<br/>[Storage.js]")]
  node_loader["Server asset loader<br/>[ServerLoader.js]"]
end

subgraph group_fork["Fork capabilities"]
  node_splats["Gaussian splat node<br/>[GaussianSplat.js]"]
  node_browser["Browser surfaces<br/>[Browser.js]"]
  node_webview["Private webview<br/>[WebView.js]"]
  node_extrude["Extruded primitives<br/>[Prim.js]"]
  node_xr["XR tracking<br/>[XR.js]"]
end

node_player(("World player"))

node_player -->|"enters world"| node_client
node_client -->|"creates"| node_clientworld
node_clientworld -->|"instantiates"| node_world
node_clientworld -->|"registers"| node_network
node_world -->|"runs lifecycle"| node_systems
node_world -->|"registers"| node_apps
node_apps -->|"creates nodes"| node_scene
node_clientworld -->|"registers"| node_builder
node_clientworld -->|"registers"| node_pose
node_clientworld -->|"registers"| node_controls
node_clientworld -->|"registers"| node_nametags
node_client -->|"renders"| node_ui
node_builder -->|"uses workflow"| node_prompt
node_player -.->|"edits world"| node_builder
node_player -.->|"adjusts seat pose"| node_pose
node_controls -.->|"tracks hands"| node_xr
node_server -->|"creates"| node_serverworld
node_server -->|"initializes"| node_database
node_server -->|"initializes"| node_storage
node_player -.->|"loads and transforms"| node_splats
node_player -.->|"shares browser input"| node_browser
node_player -.->|"uses private browser"| node_webview
node_player -.->|"builds primitives"| node_extrude
node_systems -.->|"uses 3D runtime"| node_three
node_apps -->|"uses layer rules"| node_layers
node_apps -->|"uses priorities"| node_priorities
node_database -->|"uses app tools"| node_apphelpers
node_server -.->|"configures world"| node_loader
node_client -->|"imports runtime guard"| node_lockdown
node_clientworld -->|"registers"| node_actions

click node_client "https://github.com/jerometremblay/hyperfy/blob/main/src/client/world-client.js"
click node_world "https://github.com/jerometremblay/hyperfy/blob/main/src/core/World.js"
click node_systems "https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/System.js"
click node_clientworld "https://github.com/jerometremblay/hyperfy/blob/main/src/core/createClientWorld.js"
click node_network "https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ClientNetwork.js"
click node_scene "https://github.com/jerometremblay/hyperfy/blob/main/src/core/nodes/Node.js"
click node_apps "https://github.com/jerometremblay/hyperfy/blob/main/src/core/entities/App.js"
click node_ui "https://github.com/jerometremblay/hyperfy/blob/main/src/client/components/Sidebar.js"
click node_builder "https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ClientBuilder.js"
click node_prompt "https://github.com/jerometremblay/hyperfy/blob/main/src/core/extras/PromptBoxWorkflow.js"
click node_pose "https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ClientPoseEditor.js"
click node_controls "https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ClientControls.js"
click node_nametags "https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/Nametags.js"
click node_server "https://github.com/jerometremblay/hyperfy/blob/main/src/server/index.js"
click node_serverworld "https://github.com/jerometremblay/hyperfy/blob/main/src/core/createServerWorld.js"
click node_database "https://github.com/jerometremblay/hyperfy/blob/main/src/server/db.js"
click node_storage "https://github.com/jerometremblay/hyperfy/blob/main/src/server/Storage.js"
click node_splats "https://github.com/jerometremblay/hyperfy/blob/main/src/core/nodes/GaussianSplat.js"
click node_browser "https://github.com/jerometremblay/hyperfy/blob/main/src/core/nodes/Browser.js"
click node_webview "https://github.com/jerometremblay/hyperfy/blob/main/src/core/nodes/WebView.js"
click node_extrude "https://github.com/jerometremblay/hyperfy/blob/main/src/core/nodes/Prim.js"
click node_xr "https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/XR.js"
click node_three "https://github.com/jerometremblay/hyperfy/blob/main/src/core/extras/three.js"
click node_priorities "https://github.com/jerometremblay/hyperfy/blob/main/src/core/extras/ControlPriorities.js"
click node_layers "https://github.com/jerometremblay/hyperfy/blob/main/src/core/extras/Layers.js"
click node_apphelpers "https://github.com/jerometremblay/hyperfy/blob/main/src/core/extras/appTools.js"
click node_lockdown "https://github.com/jerometremblay/hyperfy/blob/main/src/core/lockdown.js"
click node_actions "https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ClientActions.js"
click node_loader "https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ServerLoader.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_world,node_systems,node_clientworld,node_network,node_scene,node_apps,node_three,node_priorities,node_layers,node_apphelpers,node_lockdown,node_actions toneBlue
class node_ui,node_builder,node_prompt toneAmber
class node_pose,node_controls,node_nametags toneMint
class node_server,node_serverworld,node_database,node_storage,node_loader toneRose
class node_splats,node_browser,node_webview,node_extrude,node_xr,node_player toneIndigo
```

## Components

### World runtime

- [Client entry](https://github.com/jerometremblay/hyperfy/blob/main/src/client/world-client.js): `src/client/world-client.js`
- [World simulation](https://github.com/jerometremblay/hyperfy/blob/main/src/core/World.js): `src/core/World.js`
- [System lifecycle](https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/System.js): `src/core/systems/System.js`
- [Client world setup](https://github.com/jerometremblay/hyperfy/blob/main/src/core/createClientWorld.js): `src/core/createClientWorld.js`
- [Client networking](https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ClientNetwork.js): `src/core/systems/ClientNetwork.js`
- [Scene nodes](https://github.com/jerometremblay/hyperfy/blob/main/src/core/nodes/Node.js): `src/core/nodes/Node.js`
- [App runtime](https://github.com/jerometremblay/hyperfy/blob/main/src/core/entities/App.js): `src/core/entities/App.js`
- [3D utilities](https://github.com/jerometremblay/hyperfy/blob/main/src/core/extras/three.js): `src/core/extras/three.js`
- [Control priorities](https://github.com/jerometremblay/hyperfy/blob/main/src/core/extras/ControlPriorities.js): `src/core/extras/ControlPriorities.js`
- [Scene layers](https://github.com/jerometremblay/hyperfy/blob/main/src/core/extras/Layers.js): `src/core/extras/Layers.js`
- [App tools](https://github.com/jerometremblay/hyperfy/blob/main/src/core/extras/appTools.js): `src/core/extras/appTools.js`
- [Runtime lockdown](https://github.com/jerometremblay/hyperfy/blob/main/src/core/lockdown.js): `src/core/lockdown.js`
- [Client actions](https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ClientActions.js): `src/core/systems/ClientActions.js`

### Building and editing

- [Core world UI](https://github.com/jerometremblay/hyperfy/blob/main/src/client/components/Sidebar.js): `src/client/components/Sidebar.js`
- [World builder](https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ClientBuilder.js): `src/core/systems/ClientBuilder.js`
- [Prompt-box workflow](https://github.com/jerometremblay/hyperfy/blob/main/src/core/extras/PromptBoxWorkflow.js): `src/core/extras/PromptBoxWorkflow.js`

### Avatars and interaction

- [Sitting-pose editor](https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ClientPoseEditor.js): `src/core/systems/ClientPoseEditor.js`
- [Controls and hand tracking](https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ClientControls.js): `src/core/systems/ClientControls.js`
- [Player nametags](https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/Nametags.js): `src/core/systems/Nametags.js`

### Server services

- [Server entry](https://github.com/jerometremblay/hyperfy/blob/main/src/server/index.js): `src/server/index.js`
- [Server world setup](https://github.com/jerometremblay/hyperfy/blob/main/src/core/createServerWorld.js): `src/core/createServerWorld.js`
- [World database](https://github.com/jerometremblay/hyperfy/blob/main/src/server/db.js): `src/server/db.js`
- [Server storage](https://github.com/jerometremblay/hyperfy/blob/main/src/server/Storage.js): `src/server/Storage.js`
- [Server asset loader](https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/ServerLoader.js): `src/core/systems/ServerLoader.js`

### Fork capabilities

- [Gaussian splat node](https://github.com/jerometremblay/hyperfy/blob/main/src/core/nodes/GaussianSplat.js): `src/core/nodes/GaussianSplat.js`
- [Browser surfaces](https://github.com/jerometremblay/hyperfy/blob/main/src/core/nodes/Browser.js): `src/core/nodes/Browser.js`
- [Private webview](https://github.com/jerometremblay/hyperfy/blob/main/src/core/nodes/WebView.js): `src/core/nodes/WebView.js`
- [Extruded primitives](https://github.com/jerometremblay/hyperfy/blob/main/src/core/nodes/Prim.js): `src/core/nodes/Prim.js`
- [XR tracking](https://github.com/jerometremblay/hyperfy/blob/main/src/core/systems/XR.js): `src/core/systems/XR.js`

### Other components

- **World player**

## Connections

- World player → Client entry: enters world (evidence: `src/client/world-client.js`)
- Client entry → Client world setup: creates (evidence: `src/client/world-client.js`)
- Client world setup → World simulation: instantiates (evidence: `src/core/createClientWorld.js`)
- Client world setup → Client networking: registers (evidence: `src/core/createClientWorld.js`)
- World simulation → System lifecycle: runs lifecycle (evidence: `src/core/World.js`)
- World simulation → App runtime: registers (evidence: `src/core/World.js`)
- App runtime → Scene nodes: creates nodes (evidence: `src/core/entities/App.js`)
- Client world setup → World builder: registers (evidence: `src/core/createClientWorld.js`)
- Client world setup → Sitting-pose editor: registers (evidence: `src/core/createClientWorld.js`)
- Client world setup → Controls and hand tracking: registers (evidence: `src/core/createClientWorld.js`)
- Client world setup → Player nametags: registers (evidence: `src/core/createClientWorld.js`)
- Client entry → Core world UI: renders (evidence: `src/client/world-client.js`)
- World builder → Prompt-box workflow: uses workflow (evidence: `src/core/systems/ClientBuilder.js`)
- World player → World builder: edits world (evidence: `README.md`)
- World player → Sitting-pose editor: adjusts seat pose (evidence: `README.md`)
- Controls and hand tracking → XR tracking: tracks hands (evidence: `README.md`)
- Server entry → Server world setup: creates (evidence: `src/server/index.js`)
- Server entry → World database: initializes (evidence: `src/server/index.js`)
- Server entry → Server storage: initializes (evidence: `src/server/index.js`)
- World player → Gaussian splat node: loads and transforms (evidence: `README.md`)
- World player → Browser surfaces: shares browser input (evidence: `README.md`)
- World player → Private webview: uses private browser (evidence: `README.md`)
- World player → Extruded primitives: builds primitives (evidence: `README.md`)
- System lifecycle → 3D utilities: uses 3D runtime
- App runtime → Scene layers: uses layer rules (evidence: `src/core/entities/App.js`)
- App runtime → Control priorities: uses priorities (evidence: `src/core/entities/App.js`)
- World database → App tools: uses app tools (evidence: `src/server/db.js`)
- Server entry → Server asset loader: configures world
- Client entry → Runtime lockdown: imports runtime guard (evidence: `src/client/world-client.js`)
- Client world setup → Client actions: registers (evidence: `src/core/createClientWorld.js`)
