Hyperfy ⚡️

Build, deploy, and experience interactive 3D virtual worlds

What is Hyperfy?

Hyperfy is an open-source framework for building interactive 3D virtual worlds. It combines a powerful physics engine, networked real-time collaboration, and a component-based application system to create immersive experiences that can be self-hosted or connected to the wider Hyperfy ecosystem.

🧬 Key Features

Standalone persistent worlds - Host on your own domain
Realtime content creation - Build directly in-world
Interactive app system - Create dynamic applications with JavaScript
Portable avatars - Connect via Hyperfy for consistent identity
Physics-based interactions - Built on PhysX for realistic simulation
WebXR support - Experience worlds in VR
Extensible architecture - Highly customizable for various use cases

🚀 Quick Start

Prerequisites

Node.js 22.11.0+ (via nvm or direct install)

Installation

# Clone the repository
git clone https://github.com/hyperfy-xyz/hyperfy.git my-world
cd my-world
Copy example environment settings
cp .env.example .env
Install dependencies
npm install
Start the development server
npm run dev

Docker Deployment

For containerized deployment, check DOCKER.md for detailed instructions.

🧩 Use Cases

Virtual Events & Conferences - Host live gatherings with spatial audio
Interactive Showrooms - Create product displays and demos
Social Spaces - Build community hubs for collaboration
Gaming Environments - Design immersive game worlds
Educational Experiences - Develop interactive learning spaces
Creative Showcases - Display 3D art and interactive installations

📚 Documentation & Resources

Community Documentation - Comprehensive guides and reference
Website - Official Hyperfy website
Sandbox - Try Hyperfy in your browser
Twitter/X - Latest updates and announcements

📏 Project Structure

docs/              - Documentation and references
src/
  client/          - Client-side code and components
  core/            - Core systems (physics, networking, entities)
  server/          - Server implementation
CHANGELOG.md       - Version history and changes

🛠️ Development

Key Commands

# Development mode
npm run dev
Production build
npm run build
npm start
Clean orphaned assets (experimental)
npm run world:clean
Viewer only (development)
npm run viewer:dev
Client only (development)
npm run client:dev
Linting
npm run lint
npm run lint:fix

🖊️ Contributing

Contributions are welcome! Please check out our contributing guidelines and code of conduct before getting started.

Fork the repository
Create your feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a pull request

🌱 Project Status

This project is still in alpha as we transition all of our reference platform code into fully self hostable worlds. Most features are already here in this repo but still need to be connected up to work with self hosting in mind. Note that APIs are highly likely to change during this time.

🔗 More in this category