admin/Archive
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0dd4f3a0200931584854d2e8fe6b61527c9568b3
Archive/retro/HABBO_RETRO_SETUP_PLAN.md

28 KiB
Raw Blame History

Complete Habbo Retro Setup Plan (2025)

Table of Contents

  1. Overview
  2. Quick Start (RageZone Method)
  3. System Components
  4. System Requirements
  5. Prerequisites Installation
  6. Database Setup
  7. Asset Conversion
  8. Emulator Setup
  9. CMS Installation
  10. Client Setup
  11. Configuration & Integration
  12. Deployment
  13. Testing & Troubleshooting
  14. Additional Resources

Overview

This guide provides a complete walkthrough for setting up a Habbo retro hotel using modern technologies and the Nitro HTML5 client. This setup includes:

  • AtomCMS - Modern Laravel-based web CMS
  • Arcturus Morningstar Extended - Java-based Habbo emulator
  • Nitro Converter - Tool for converting Flash assets to Nitro format
  • Nitro Cool UI - React-based HTML5 client

Educational Disclaimer

⚠️ This setup is provided for educational purposes only. Ensure you comply with all applicable laws and regulations when using these tools.

Quick Start (RageZone Method)

This is a streamlined production setup based on the RageZone tutorial. Use this if you want to get up and running quickly with minimal configuration.

Prerequisites Downloads

  1. Node.js & Angular

    • Windows: Download from https://nodejs.org/en/download/
    • After installing: npm install -g @angular/cli
    • macOS: brew update && brew install node && npm install -g @angular/cli

  2. Download Required Files

  3. Web Server

    • Install Xampp/Wampp/Laragon/IIS

Quick Setup Steps

1. Set Up Nitro Client

# Extract nitro-client zip
cd nitro-client/src

# Rename configuration files
mv index.html.example index.html
mv configuration.json.example configuration.json

Edit configuration.json:

{
  "socketUrl": "ws://localhost:2096",
  "assetUrl": "http://localhost/nitro-assets",
  "imageUrl": "http://localhost/c_images/album1584/"
}

Install and run:

npm install
ng serve

Access at: http://localhost:4200

2. Set Up Assets

# Extract nitro-assets to your web server
# For Xampp: copy to C:/xampp/htdocs/nitro-assets
# For other servers: copy to htdocs or www folder

3. Configure Arcturus Emulator

  1. Extract Arcturus and place WebSocket plugin in plugins/ folder
  2. Start emulator (it will create database tables)
  3. Stop emulator
  4. Configure database settings in emulator_settings table:
UPDATE emulator_settings SET value = '0.0.0.0' WHERE key = 'ws.nitro.host';
UPDATE emulator_settings SET value = '2096' WHERE key = 'ws.nitro.port';
  1. Restart emulator

4. Quick Test (Without CMS)

Add SSO ticket to test user:

-- Add auth ticket to any user
UPDATE users SET auth_ticket = 'test123' WHERE id = 1;

Access Nitro:

http://localhost:4200/?sso=test123

You should now be able to enter the client and test basic functionality!

When to Use This Method

✅ Use this for:

  • Quick testing and development
  • Understanding the basic components
  • Learning how Nitro and Arcturus work together
  • Proof of concept

❌ Don't use this for:

  • Production deployments (skip to full setup below)
  • Hotels with public registration
  • Long-term projects

For full production setup with CMS, SSL, and proper user management, continue with the detailed sections below.

System Components

1. Web CMS: AtomCMS

2. Emulator: Arcturus Morningstar Extended

3. Asset Converter: Nitro Converter

4. Client: Nitro (Multiple Options)

Option A: Nitro Cool UI (React-based)

Option B: Nitro Client (Angular-based)

Option C: Flash UI Nitro (Compiled)

Note: This guide covers the React-based Nitro Cool UI in detail, but the Quick Start section uses the Angular client for simplicity.

System Requirements

Hardware Requirements

  • CPU: 2+ cores recommended
  • RAM: 4GB minimum, 8GB recommended
  • Storage: 20GB+ for assets, database, and applications
  • Network: Stable internet connection with static IP or domain

Software Requirements

For Windows (IIS Setup)

  • Windows Server 2019+ or Windows 10/11 Pro
  • Internet Information Services (IIS) 10+
  • MariaDB 10.6+ or MySQL 8.0+
  • PHP 8.2+
  • Composer v2
  • Java JDK 17+ (for emulator)
  • Node.js 18+ (for Nitro client)
  • Git
  • Yarn package manager

For Linux (Ubuntu/Debian)

  • Ubuntu 20.04+ or Debian 11+
  • Nginx or Apache
  • MariaDB 10.6+ or MySQL 8.0+
  • PHP 8.2+ with extensions: curl, mbstring, pdo, pdo_mysql, xml, zip, gd
  • Composer v2
  • Java JDK 17+
  • Node.js 18+
  • Git
  • Yarn package manager

Prerequisites Installation

Step 1: Install Core Software

On Windows:

# Install Chocolatey (Windows package manager)
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

# Install required software
choco install git -y
choco install php --version=8.2 -y
choco install composer -y
choco install mariadb -y
choco install nodejs --version=18.0.0 -y
choco install openjdk17 -y

# Install Yarn
npm install -g yarn

# Enable IIS via PowerShell
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WebServerRole
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WebServer
Enable-WindowsOptionalFeature -Online -FeatureName IIS-ASPNET45

On Linux (Ubuntu):

# Update system
sudo apt update && sudo apt upgrade -y

# Install Git
sudo apt install git -y

# Install PHP 8.2 and extensions
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install php8.2 php8.2-fpm php8.2-cli php8.2-curl php8.2-mbstring \
  php8.2-mysql php8.2-xml php8.2-zip php8.2-gd -y

# Install Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Install MariaDB
sudo apt install mariadb-server mariadb-client -y
sudo mysql_secure_installation

# Install Java 17
sudo apt install openjdk-17-jdk -y

# Install Node.js 18+ and Yarn
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs -y
sudo npm install -g yarn

# Install Nginx
sudo apt install nginx -y

Step 2: Verify Installations

# Check versions
php -v          # Should show PHP 8.2.x
composer -V     # Should show Composer version 2.x
node -v         # Should show v18.x or higher
yarn -v         # Should show yarn version
java -version   # Should show Java 17+
git --version   # Should show git version

Database Setup

Step 1: Create Database

MySQL/MariaDB Setup:

-- Login to MySQL
mysql -u root -p

-- Create database
CREATE DATABASE habbo_retro CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- Create user
CREATE USER 'habbo_user'@'localhost' IDENTIFIED BY 'strong_password_here';

-- Grant privileges
GRANT ALL PRIVILEGES ON habbo_retro.* TO 'habbo_user'@'localhost';
FLUSH PRIVILEGES;

-- Exit
EXIT;

Step 2: Import Base Database

The Arcturus Morningstar Extended repository includes database files:

cd Arcturus-Morningstar-Extended/Default\ Database

# Import the myBoBBa database
mysql -u habbo_user -p habbo_retro < myBoBBa_LATEST.sql

# Import database updates
mysql -u habbo_user -p habbo_retro < ../Database\ Updates/UpdateDatabase.sql

Note: The myBoBBa database is mentioned in the Arcturus README and provides a complete starting point.

Asset Conversion

Before setting up the client, you need to convert Flash assets to Nitro format.

Step 1: Setup Nitro Converter

cd nitro-converter

# Install dependencies
yarn install

# Build the converter
yarn build

Step 2: Configure the Converter

# Copy configuration template
cp configuration.json.example configuration.json

Edit configuration.json:

{
  "output.folder": "./output",
  "flash.client.url": "https://images.habbo.com/gordon/",
  "furnidata.load.url": "https://www.habbo.com/gamedata/furnidata/1",
  "productdata.load.url": "https://www.habbo.com/gamedata/productdata/1",
  "figuremap.load.url": "https://images.habbo.com/gordon/figuremap.xml",
  "effectmap.load.url": "https://images.habbo.com/gordon/effectmap.xml",
  "dynamic.download.pet.url": "https://images.habbo.com/gordon/%className%.swf",
  "dynamic.download.figure.url": "https://images.habbo.com/gordon/%className%.swf",
  "dynamic.download.effect.url": "https://images.habbo.com/gordon/%className%.swf",
  "flash.dynamic.download.url": "https://images.habbo.com/dcr/hof_furni/",
  "dynamic.download.furniture.url": "https://images.habbo.com/dcr/hof_furni/%className%.swf",
  "external.variables.url": "https://www.habbo.com/gamedata/external_variables/1",
  "external.texts.url": "https://www.habbo.com/gamedata/external_flash_texts/1",
  "convert.productdata": "1",
  "convert.externaltexts": "1",
  "convert.figure": "1",
  "convert.figuredata": "1",
  "convert.effect": "1",
  "convert.furniture": "1",
  "convert.pet": "1"
}

Note: You can use official Habbo URLs or download a complete asset pack from community resources.

Step 3: Run Asset Conversion

# Download and convert all assets
yarn start

This process may take 30-60 minutes depending on your connection and the number of assets.

Step 4: Extract Converted Assets

After conversion, you'll have .nitro bundles. Extract them for hosting:

yarn start:extract

The extracted assets will be in the output folder and need to be hosted on a web server.

Emulator Setup

Step 1: Compile/Download Emulator

The repository includes a pre-compiled version:

cd Arcturus-Morningstar-Extended/Latest_Compiled_Version

Or compile from source:

cd Arcturus-Morningstar-Extended/Emulator
# Use your Java IDE (IntelliJ IDEA recommended) to compile
# Or use Maven if pom.xml is present
mvn clean package

Step 2: Configure Emulator

Create/edit config.ini:

[database]
mysql.hostname=localhost
mysql.port=3306
mysql.username=habbo_user
mysql.password=strong_password_here
mysql.database=habbo_retro

[websockets]
ws.nitro.enabled=true
ws.nitro.host=0.0.0.0
ws.nitro.port=2096
ws.nitro.ip.header=X-Forwarded-For

[server]
hotel.name=My Habbo Retro
hotel.url=http://localhost

Step 3: Install WebSocket Plugin

The WebSocket plugin is required for Nitro client compatibility:

cd Arcturus-Morningstar-Extended/Plugins

# Copy the WebSocket plugin JAR to the emulator plugins folder
# The plugin should be included in the repository

Step 4: Configure SSL/WSS (Production)

For secure WebSocket connections (wss://):

Option 1: Using Cloudflare (Recommended)

  1. Set ws.nitro.port to a Cloudflare-compatible HTTPS port: 443, 2053, 2083, 2087, 2096, or 8443
  2. Create an A record for a subdomain (e.g., ws.yourhotel.com) pointing to your server IP
  3. Enable Cloudflare proxy (orange cloud)
  4. Create a Page Rule to disable SSL for the WebSocket subdomain
  5. Configure ws.nitro.ip.header=CF-Connecting-IP in config.ini

Option 2: Direct SSL

  1. Obtain SSL certificate (Let's Encrypt recommended)
  2. Place certificate files:
    • /ssl/cert.pem
    • /ssl/privkey.pem
  3. Restart emulator

Note: Self-signed certificates will not work with the client.

Step 5: Run the Emulator

java -jar Arcturus-Morningstar-Extended.jar

The emulator should start and connect to the database. Check console for any errors.

CMS Installation

Step 1: Setup AtomCMS

cd atomcms

# Install PHP dependencies
composer install

# Install Node dependencies
yarn install

Step 2: Configure Environment

# Copy environment file
cp .env.example .env

Edit .env:

APP_NAME="My Habbo Retro"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=habbo_retro
DB_USERNAME=habbo_user
DB_PASSWORD=strong_password_here

# Nitro Client Configuration
NITRO_CLIENT_URL=http://localhost:3000
NITRO_WEBSOCKET_URL=ws://localhost:2096

# Asset URLs (from your converted assets)
GAME_ASSETS_URL=http://localhost/assets
FIGURE_IMAGER_URL=http://localhost/imaging

Step 3: Generate Application Key

php artisan key:generate

Step 4: Run Migrations

# Run AtomCMS migrations (if required)
php artisan migrate

# Note: The myBoBBa database should already have the required tables
# Run migrations only if AtomCMS has additional tables to create

Step 5: Build Frontend Assets

# Build for production
yarn build

# Or for development
yarn dev

Step 6: Configure Web Server

Nginx Configuration (Linux):

server {
    listen 80;
    server_name yourhotel.com;
    root /var/www/atomcms/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

IIS Configuration (Windows):

Create web.config in the public folder (should already exist in AtomCMS).

Step 7: Set Permissions (Linux)

# Set proper permissions
sudo chown -R www-data:www-data /var/www/atomcms
sudo chmod -R 755 /var/www/atomcms
sudo chmod -R 775 /var/www/atomcms/storage
sudo chmod -R 775 /var/www/atomcms/bootstrap/cache

Client Setup

Step 1: Configure Nitro Cool UI

cd Nitro-Cool-UI

# Install dependencies
yarn install

Step 2: Configure Client

# Rename configuration files
cp public/renderer-config.json.example public/renderer-config.json
cp public/ui-config.json.example public/ui-config.json

Edit public/renderer-config.json:

{
  "socket.url": "ws://localhost:2096",
  "asset.url": "http://localhost/assets",
  "image.library.url": "http://localhost/assets/images",
  "hof.furni.url": "http://localhost/assets/dcr/hof_furni"
}

Edit public/ui-config.json:

{
  "camera.url": "http://localhost/api/camera",
  "thumbnails.url": "http://localhost/imaging",
  "url.prefix": "http://localhost",
  "habbopages.url": "http://localhost"
}

Step 3: Update ExternalTexts.json

As mentioned in the Nitro Cool UI README, make these changes:

{
  "room.mute.button.text": "Hide chat",
  "room.unmute.button.text": "Unhide chat"
}

Step 4: Build the Client

For Development:

yarn start

This runs on http://localhost:3000 with hot-reload.

For Production:

yarn build

The production files will be in the dist folder. These need to be:

  1. Uploaded to your web server
  2. Configured in your CMS to load the client

Configuration & Integration

Step 1: Host Converted Assets

The assets from nitro-converter need to be accessible via HTTP:

# Example: Copy to web server
cp -r nitro-converter/output/* /var/www/html/assets/

# Or create a symlink
ln -s /path/to/nitro-converter/output /var/www/html/assets

Step 2: Configure Asset URLs

Ensure all components point to the correct asset URLs:

  • Nitro Client: renderer-config.json → asset.url
  • CMS: .env → GAME_ASSETS_URL
  • Database: Update emulator_settings table if needed

Step 3: Update Database Settings

Connect to your database and verify/update the emulator_settings table:

USE habbo_retro;

-- Update camera URL
UPDATE emulator_settings SET value = 'http://localhost/api/camera' WHERE key = 'camera.url';

-- Update badge imager URL
UPDATE emulator_settings SET value = 'http://localhost/imaging/badge' WHERE key = 'imager.location.badges';

-- Update figure imager URL
UPDATE emulator_settings SET value = 'http://localhost/imaging/avatar' WHERE key = 'imager.location.figure';

Step 4: Integrate Client with CMS

AtomCMS should have built-in support for Nitro. Configure the client loading in the CMS:

  1. Login to your CMS as admin
  2. Navigate to housekeeping/settings
  3. Set client type to "Nitro"
  4. Set client URL to your Nitro build location

Deployment

Step 1: Domain & DNS Setup

  1. Purchase a domain name
  2. Configure DNS records:
    • A record: @ → Your server IP
    • A record: www → Your server IP
    • A record: ws → Your server IP (for WebSockets)

Step 2: SSL Certificate (Let's Encrypt)

# Install Certbot
sudo apt install certbot python3-certbot-nginx -y

# Obtain certificate
sudo certbot --nginx -d yourhotel.com -d www.yourhotel.com

# Auto-renewal is configured automatically

Step 3: Firewall Configuration

# Allow necessary ports
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw allow 2096/tcp  # WebSocket (if not using Cloudflare)
sudo ufw allow 3306/tcp  # MySQL (only if remote access needed)

sudo ufw enable

Step 4: Start All Services

# Start/restart web server
sudo systemctl restart nginx  # or httpd/apache2

# Start PHP-FPM
sudo systemctl restart php8.2-fpm

# Start MySQL
sudo systemctl restart mariadb

# Start emulator in screen/tmux
screen -S emulator
cd /path/to/emulator
java -jar Arcturus-Morningstar-Extended.jar
# Ctrl+A, D to detach

Step 5: Production Checklist

  • All URLs use HTTPS
  • WebSockets use WSS (secure)
  • Database credentials are strong
  • APP_DEBUG=false in .env
  • Regular database backups configured
  • Firewall properly configured
  • SSL certificates auto-renew
  • Server monitoring in place
  • Error logging enabled

Testing & Troubleshooting

Step 1: Test Database Connection

# Test from CMS
php artisan tinker
>>> DB::connection()->getPdo();

# Should return PDO object without errors

Step 2: Test Emulator

  1. Check emulator console for errors
  2. Verify WebSocket port is listening: 
    netstat -an | grep 2096
  3. Check database connection in emulator logs

Step 3: Test Client

  1. Open browser developer tools (F12)
  2. Navigate to your hotel URL
  3. Check Console for JavaScript errors
  4. Check Network tab for failed requests
  5. Verify WebSocket connection is established

Step 4: Direct SSO Testing (Without CMS)

For quick testing without CMS integration, you can use direct SSO authentication:

-- Add an auth ticket to a test user
UPDATE users SET auth_ticket = 'your_test_sso_ticket' WHERE id = 1;

Then access the client with the SSO parameter:

http://yourhotel.com/client?sso=your_test_sso_ticket

Note: This bypasses CMS login and is useful for:

  • Testing client/emulator connectivity
  • Debugging WebSocket issues
  • Verifying asset loading
  • Development and troubleshooting

Step 5: WebSocket Connection Verification

Check browser console for WebSocket messages:

✅ Good: "WebSocket connection established"
❌ Bad: "WebSocket connection failed" or "ERR_CONNECTION_REFUSED"

Verify in emulator console:

✅ Good: "[WebSocket] User connected from IP: xxx.xxx.xxx.xxx"
❌ Bad: No connection messages or timeout errors

Common Issues & Solutions

Issue: Client won't connect to emulator

Solution:

  • Verify WebSocket URL in renderer-config.json
  • Check firewall allows port 2096
  • Verify emulator is running
  • Check ws.nitro.enabled=true in emulator config

Issue: Assets not loading

Solution:

  • Verify asset URLs in renderer-config.json
  • Check web server can serve files from assets directory
  • Verify nitro-converter completed successfully
  • Check CORS headers if assets on different domain

Issue: Database connection failed

Solution:

  • Verify credentials in .env and config.ini
  • Check MySQL is running: sudo systemctl status mariadb
  • Verify user has correct permissions
  • Check database exists

Issue: CMS shows white screen

Solution:

  • Check storage and bootstrap/cache permissions
  • Run php artisan config:clear
  • Run php artisan cache:clear
  • Check storage/logs/laravel.log for errors

Issue: WebSocket SSL errors

Solution:

  • Browser rejects self-signed certificates
  • Use Let's Encrypt or Cloudflare
  • Verify SSL certificate chain is complete
  • Check ws.nitro.ip.header configuration

Additional Resources

Official Documentation

Community Resources & Tutorials

Alternative Tools & Resources

Learning Resources

Asset Packs & Downloads

Check community forums for complete asset packs that include:

  • SWF archives for conversion
  • Pre-converted Nitro assets
  • Database dumps with furniture/catalog data
  • Production data files
  • Badge collections
  • Custom furniture

Maintenance & Updates

Regular Tasks

Daily:

  • Monitor server resources
  • Check error logs
  • Backup database

Weekly:

  • Review user reports
  • Update furniture/catalog
  • Security audit

Monthly:

  • Update dependencies (Composer, NPM)
  • Review and apply emulator updates
  • Database optimization
  • Security patches

Update Procedures

Updating AtomCMS:

cd atomcms
git pull origin main
composer install
yarn install
yarn build
php artisan migrate
php artisan cache:clear

Updating Arcturus Emulator:

  1. Backup database
  2. Download latest version
  3. Review changelog for breaking changes
  4. Update configuration if needed
  5. Test on staging environment first
  6. Deploy to production

Updating Nitro Client:

cd Nitro-Cool-UI
git pull origin main
yarn install
yarn build
# Deploy new build to production

Security Best Practices

  1. Never expose database credentials - Use environment variables
  2. Regular backups - Automate daily database and file backups
  3. Keep software updated - Apply security patches promptly
  4. Use strong passwords - For all accounts and database users
  5. Enable HTTPS everywhere - No mixed content
  6. Implement rate limiting - Prevent abuse and DDoS
  7. Monitor logs - Set up alerts for suspicious activity
  8. Validate user input - Prevent SQL injection and XSS
  9. Use prepared statements - For all database queries
  10. Regular security audits - Review code and configurations

Performance Optimization

Database Optimization

-- Add indexes for frequently queried columns
CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_users_online ON users(online);

-- Optimize tables monthly
OPTIMIZE TABLE users, rooms, items, furniture;

Web Server Optimization

  • Enable Gzip compression
  • Configure browser caching
  • Use CDN for static assets
  • Enable OPcache for PHP
  • Configure Redis/Memcached for session storage

Client Optimization

  • Minimize bundle size
  • Enable production builds
  • Use CDN for Nitro assets
  • Implement lazy loading
  • Optimize images

Success Criteria

Your Habbo retro is successfully set up when:

  • ✅ Users can register and login via CMS
  • ✅ Client loads without errors
  • ✅ WebSocket connection established (check browser console)
  • ✅ Users can enter rooms
  • ✅ Chat messages work
  • ✅ Furniture loads and can be placed
  • ✅ Avatar changes reflect immediately
  • ✅ No console errors in client
  • ✅ Emulator shows active connections
  • ✅ All assets load correctly

Conclusion

Setting up a Habbo retro requires patience and attention to detail. This guide covers the essential components and configuration. Remember:

  1. Start with a development environment
  2. Test each component independently
  3. Document your configuration
  4. Join community forums for support
  5. Keep everything updated and backed up

Good luck with your Habbo retro hotel! 🏨

Last Updated: December 2025 Compatible Versions:

  • AtomCMS: Latest (Laravel 10.x)
  • Arcturus Morningstar Extended: Latest
  • Nitro Client: v2.1+
  • PHP: 8.2+
  • Node.js: 18+
  • Java: 17+
Reference in New Issue View Git Blame Copy Permalink