Official Hyperfy SDK for Node.js - Build immersive 3D worlds and virtual reality experiences
npm install hyperfy-sdk


Official Hyperfy SDK for Node.js - Build immersive 3D worlds and virtual reality experiences on the Hyperfy platform.
``bash`
npm install hyperfy-sdk
`javascript
import { HyperfyClient } from 'hyperfy-sdk';
// Connect to a Hyperfy world
const client = new HyperfyClient({
wsUrl: 'ws://localhost:3000',
authToken: 'your-auth-token',
name: 'YourName',
avatar: 'https://example.com/avatar.png'
});
client.on('connected', () => {
console.log('Connected to Hyperfy world!');
// Listen for events
client.on('entityAdded', (entity) => {
console.log('New entity:', entity);
});
client.on('chatAdded', (message) => {
console.log('New message:', message);
});
});
// Start connection
client.connect();
`
- ๐ Real-time Communication - WebSocket-based real-time connectivity
- ๐ฎ Entity Management - Create, modify, and delete 3D entities
- ๐ฌ Chat System - Send and receive chat messages
- ๐ฅ Player Management - Handle player joins, leaves, and interactions
- ๐ File Upload - Upload assets and files to your worlds
- ๐ง Event-Driven - Comprehensive event system for world changes
- ๐ก๏ธ Type Safety - Full TypeScript support with comprehensive definitions
- ๐ Plugin System - Extensible architecture for custom functionality
The Hyperfy SDK provides a clean, event-driven interface for interacting with Hyperfy worlds:
- NetworkClient - Handles WebSocket communication and protocol management
- EntityManager - Manages 3D entities in the world
- PlayerManager - Handles player state and interactions
- ChatManager - Manages chat messages and history
- FileManager - Handles file uploads and downloads
All major actions emit events that you can listen to:
`javascript
// Entity events
client.on('entityAdded', (entity) => {});
client.on('entityModified', (entity) => {});
client.on('entityRemoved', (entityId) => {});
// Player events
client.on('playerJoined', (player) => {});
client.on('playerLeft', (playerId) => {});
client.on('playerTeleport', (data) => {});
// Chat events
client.on('chatAdded', (message) => {});
// World events
client.on('snapshot', (worldData) => {});
client.on('settingsModified', (settings) => {});
`
#### Constructor
`typescript`
new HyperfyClient(options: HyperfyClientOptions)
Options:
- wsUrl (string): WebSocket server URLauthToken
- (string): Authentication tokenname
- (string): Display nameavatar
- (string): Avatar URL (optional)
#### Methods
##### connect()
Connect to the Hyperfy world.
`javascript`
client.connect();
##### disconnect()
Disconnect from the world.
`javascript`
client.disconnect();
##### sendPacket(type, data)
Send a packet to the server.
`javascript`
client.sendPacket('command', { action: 'spawn', type: 'box' });
##### createEntity(options)
Create a new entity in the world.
`javascript`
const entity = client.createEntity({
type: 'box',
position: [0, 1, 0],
scale: [1, 1, 1],
color: '#ff0000'
});
##### updateEntity(id, changes)
Update an existing entity.
`javascript`
client.updateEntity('entity-id', {
position: [5, 2, 0],
color: '#00ff00'
});
##### removeEntity(id)
Remove an entity from the world.
`javascript`
client.removeEntity('entity-id');
##### sendChat(message)
Send a chat message.
`javascript`
client.sendChat('Hello, world!');
##### teleport(position)
Teleport your player to a position.
`javascript`
client.teleport([10, 0, 5]);
#### Properties
- connected (boolean): Connection statusid
- (string | null): World ID when connectedentities
- (Map): All entities in the worldplayers
- (Map): All players in the worldchat
- (Array): Chat message history
Run the test suite:
`bash`
npm test
Run tests with coverage:
`bash`
npm run test:coverage
`bash`
npm run build
`bash`
npm run dev
`bash`
npm run lint
npm run lint:fix
`javascript
import { HyperfyClient } from 'hyperfy-sdk';
const client = new HyperfyClient({
wsUrl: 'ws://localhost:3000',
authToken: process.env.HYPERTY_TOKEN,
name: 'BotUser'
});
client.on('connected', () => {
// Create a spinning cube
const cube = client.createEntity({
type: 'box',
position: [0, 2, 0],
scale: [1, 1, 1],
color: '#4287f5'
});
// Animate it
let rotation = 0;
setInterval(() => {
rotation += 0.05;
client.updateEntity(cube.id, {
rotation: [0, rotation, 0]
});
}, 50);
});
`
`javascriptCurrent time: ${new Date().toLocaleString()}
client.on('chatAdded', (message) => {
if (message.body.startsWith('!ping')) {
client.sendChat('Pong! ๐');
}
if (message.body.startsWith('!time')) {
client.sendChat();`
}
});
`javascript
import fs from 'fs';
// Upload an image
const imageBuffer = fs.readFileSync('./my-image.png');
client.uploadFile(imageBuffer, 'my-image.png', 'image/png')
.then(url => {
console.log('File uploaded:', url);
// Use the uploaded image as an entity texture
client.createEntity({
type: 'box',
position: [0, 1, 0],
texture: url
});
})
.catch(error => {
console.error('Upload failed:', error);
});
`
We welcome contributions! Please see our Contributing Guide for details.
1. Fork the repository
2. Clone your fork
3. Install dependencies: npm installgit checkout -b feature/amazing-feature
4. Create a feature branch: npm test`
5. Make your changes
6. Run tests:
7. Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
- ๐ Documentation
- ๐ Issue Tracker
- ๐ฌ Discussions
- Hyperfy Platform
- API Documentation
- Examples
---
Made with โค๏ธ for the Hyperfy community