Highrise SDK Addon

A modular extension for the Highrise SDK providing advanced tools to manage your room in Highrise Virtual Reality

📦 Installation

npm install highrise.sdk.addons

⚙ Version Explain

This package uses Semantic Versioning in the format: 1.2.3

| Position | Symbol | Name | Description | |----------|--------|-----------|-----------------------------------------------------------------------------| | 1 | ⟳ | Major | Static core version — only changes for major rewrites or breaking changes. | | 2 | ⇨ | **Minor** | Increased when new features or addons are added. | | 3` | ⇆ | Patch | For bug fixes, small improvements, or type corrections. |

🔁 Example Versions

| Version | Meaning | |---------|-------------------------------------------------------| | 1.0.0 | Initial stable release | | 1.1.0 | Adds a new addon like EmotesManager | | 1.1.1 | Fixes a bug or improves type safety | | 1.2.0 | Adds a new feature like RolesEventManager | | 1.2.1 | Minor patch or performance tweak |

📚 Features

This addon currently includes:

✅ Emotes Manager

A powerful emote management system:

• Get emotes by ID, name, or index.
• Iterate through all available emotes.
• Useful for bots that need to animate characters or map emotes to commands.

const { Emotes } = require('highrise.sdk.addons');

const emote = Emotes.getById('sit-idle-cute');
console.log(emote?.name); // "Rest"

const emote = Emote,

✅ Roles Manager

A fully-featured role management utility with persistent storage, auto-fetch, and events:

• Track owner and moderator roles.
• Add/remove/clear moderators.
• Automatically sync roles with Highrise API or local files.
• Emit events when moderators change.

const { Roles } = require('highrise.sdk.addons');

const room_id = "6359782e37135a4092d2794a"
const roles = new Roles(room_id, {
  autoFetch: true,
  filePath: './roles.json',
  loadFromFile: true,
  saveInterval: 60_000,
  fetchInterval: 60_000
});

bot.on("chatCreate", (user, message) => {
  if (roles.isModerator(user.id)) {
    // grant permission
  }
})

🔔 Role Events

Subscribe to moderator changes:

roles.on('roleAdded', (newRole) => {
  console.log('Added role:', newRole);
});

roles.on('userRoleAdded', (user_id, roleName) => {
  console.log('New user with role: ', user_id, roleName);
});

roles.on('userRoleRemoved', (user_id, roleName) => {
  console.log('Removed user with role: ', user_id, roleName);
});

✅ CommandHandler

A robust command management system designed to streamline the creation, registration, and execution of commands in your Highrise bot. It provides a clean interface for handling user input and ensures commands are processed efficiently with proper permission checks.

Key Features:

• Dynamic Command Registration: Easily register new commands with minimal boilerplate.
• Role-Based Access Control: Restrict commands to specific roles (e.g., Admin-only commands).
• Cooldown Management: Prevent spam by setting cooldowns on commands.
• Aliases Support: Allow multiple ways to invoke the same command.
• Error Handling: Gracefully handle invalid or unauthorized commands.

Example Usage:

const { CommandHandler } = require('highrise.sdk.addons')
const { Highrise, Events } = require('highrise.sdk.dev')

const bot = new Highrise({
    Events: [
        Events.Messages,
        Events.Joins,
        Events.DirectMessages,
        Events.Tips
    ],
    AutoFetchMessages: true,
    Cache: true
})

const roles = new Roles("6359782e37135a4092d2794a", {
    autoFetch: true,
    customRoles: ['vip', 'admin']
})

const handler = new CommandHandler({
    prefix: false,
    roles: roles,
    bot: bot
})

// Register a simple command
handler.register('hello', (user, args, context) => {
  handler.bot.message.send('Hello!');
}, {
  requiredRole: 'mod', // required role for the user to use it
  aliases: ['hi'], // other names for this command
  cooldown: 5000, // cooldown between each use for each user
  description: 'Says hello!'
});

// Handle incoming messages
bot.on("chatCreate", (user, message) => {
  if (user.id === bot.info.user.id) return
  handler.handleMessage(user, message);
});

✅ CommandLoader

A dynamic command loader that monitors your commands directory for changes and automatically updates the bot's command set in real-time without requiring a restart. Perfect for developers who want fast iteration cycles and reliable error recovery.

Key Features:

• File Watching: Automatically detects new, modified, or deleted command files.
• Validation & Fallback: Ensures only valid commands are loaded; falls back to previous versions if errors occur.
• Real-Time Updates: Commands are instantly available after saving changes.
• Detailed Logging: Provides clear feedback when commands fail to load or have issues.

How It Works:

1. Save a new command file (e.g., hello.js) in the commands folder.
2. The system validates the file, registers the command, and logs any issues.
3. If you edit the file but introduce an error, the bot restores the last working version and logs a warning.

Example Workflow:

Command File (hello.js):

module.exports = {
  name: 'hello',
  description: 'Says hello!',
  aliases: ['hi'],
  requiredRole: 'user',
  cooldown: 5000,
  execute(user, args, context) {
    const { bot } = context
    bot.message.send('Hello!');
  }
};

Using CommandLoader:

const { CommandLoader, CommandHandler } = require('highrise.sdk.addonss')
const { Highrise, Events } = require('highrise.sdk.dev')

const bot = new Highrise({
    Events: [
        Events.Messages,
        Events.Joins,
        Events.DirectMessages,
        Events.Tips
    ],
    AutoFetchMessages: true,
    Cache: true
})

const roles = new Roles("6359782e37135a4092d2794a", {
    autoFetch: true,
    customRoles: ['vip', 'admin']
})

const handler = new CommandHandler({
    prefix: false,
    roles: roles,
    bot: bot
})
// folder path most be absolute
// will Start watching the commands folder immediately 
new CommandLoader('/root/bots/yahya/src/commands', handler); 

When you save hello.js, the bot will:

1. Validate the file.
2. Register the hello command.
3. Log success or fallback to the previous version if there’s an issue.

if you removed or add new file command, the bot will unlink the file and unregister it from the saved commands

🧩 Planned Addons

This SDK is modular and designed for future enhancements. Upcoming modules include:

• 🎶 Music bot — Manage radio/music queues per room.
• 🔍 User Cache — Real-time user tracking and event hooks.
• ⚙️ Plugin System — Load and isolate third-party logic at runtime.

🧠 TypeScript Support

Full native TypeScript typings included — no need to install additional type packages.

📁 Project Structure

.
├── lib/         # Core WebApi or helper utilities
├── src/         # Main modules (Emotes, Roles, CommandHandler, CommandLoader, etc.)
├── errors/      # Custom error classes and messages
└── typings/     # Global typings for public APIs

📄 License

MIT © [Yahya Ahmed]