Archive/retro/TROUBLESHOOTING.md

# Habbo Retro - Troubleshooting Guide

## Browser Console Errors Explained

### ✅ Normal (Can Ignore)

These are expected and won't affect functionality:

#### "Access to storage is not allowed from this context"
- **Cause**: Browser privacy settings preventing localStorage access
- **Impact**: None - Nitro handles this gracefully
- **Fix**: Not needed, or enable storage in browser settings

#### "apple-mobile-web-app-capable is deprecated"
- **Cause**: Old meta tag in HTML
- **Impact**: None - just a warning
- **Fix**: Not needed for desktop use

### ⚠️ Minor Issues (Partial Functionality)

#### "Failed to load c_images/album1584/[badge].gif"
- **Cause**: Badge images not included in your asset pack
- **Impact**: User badges won't display (images only)
- **Fix**:
  ```bash
  # Create directory structure
  mkdir -p /Users/matt/DEV/retro/nitro-assets/nitro-assets/c_images/album1584

  # Download badge pack from community or Habbo.com
  # Place .gif files in the album1584 folder
  ```

### ❌ Critical Errors (Need Fixing)

#### "WebSocket connection failed"
- **Cause**: Emulator not running or WebSocket plugin not loaded
- **Check**:
  ```bash
  netstat -an | grep 2096
  # Should show: tcp46  0  0  *.2096  *.*  LISTEN
  ```
- **Fix**: Restart emulator with WebSocket plugin in plugins/ folder

#### "Failed to load ExternalTexts.json"
- **Status**: FIXED in your setup! ✅
- **Was caused by**: Incorrect URL format `?v= + Math.random()`
- **Fixed by**: Removing the malformed cache-busting parameter

#### "Cannot connect to game server"
- **Cause**: Emulator offline or wrong ports
- **Check**:
  ```bash
  ps aux | grep Habbo
  netstat -an | grep 30000
  ```
- **Fix**: Restart emulator

## Current Status of Your Setup

### ✅ Working
- Nitro client loads (v2.1.1)
- PixiJS renderer active (WebGL 2)
- WebSocket connection ready (port 2096)
- Asset server running (port 8080)
- Configuration files correct

### ⚠️ Known Limitations
- Badge images not available (minor cosmetic issue)
- `c_images` directory missing (badges only)

### 🔧 How to Test Everything Works

1. **Open the client**: http://localhost:5173/?sso=test_sso_2024

2. **Check browser console** (F12):
   - Should see: "Nitro 2.1.1 - Renderer 1.6.6"
   - Should see: "PixiJS 6.5.10 - WebGL 2"

3. **Look for WebSocket connection**:
   - Open Network tab in browser tools
   - Filter by "WS" (WebSockets)
   - Should see connection to `ws://localhost:2096`
   - Status should be "101 Switching Protocols" (success!)

4. **Test gameplay**:
   - Avatar should load
   - Hotel view should appear
   - Navigator should work
   - Can enter rooms
   - Can chat

## Quick Fixes

### Refresh Configuration Changes
If you changed `renderer-config.json`:
```bash
# Just reload the browser page
# Vite hot-reloads automatically in dev mode
```

### Clear Browser Cache
```bash
# Chrome/Edge: Ctrl+Shift+Delete
# Firefox: Ctrl+Shift+Delete
# Safari: Cmd+Option+E
```

### Restart All Services
```bash
# Stop everything
pkill -f "Habbo-3.6.0"
pkill -f "python3 -m http.server 8080"
pkill -f "vite"

# Start MySQL
brew services start mysql

# Start Emulator
cd /Users/matt/DEV/retro/emulator
java -jar Habbo-3.6.0-jar-with-dependencies.jar &

# Start Assets
cd /Users/matt/DEV/retro/nitro-assets/nitro-assets
python3 -m http.server 8080 &

# Start Client
cd /Users/matt/DEV/retro/nitro-react/nitro-react
npm start
```

## Asset Issues

### Missing Furniture Icons
- **Symptom**: Furniture shows as blank squares
- **Cause**: Icons not in asset pack
- **Fix**: Download complete asset pack from community

### Missing Avatar Parts
- **Symptom**: Avatar appears naked or incomplete
- **Cause**: Missing figure .nitro files
- **Check**:
  ```bash
  ls /Users/matt/DEV/retro/nitro-assets/nitro-assets/bundled/figure/
  # Should have many .nitro files
  ```

### Game Data Not Loading
- **Symptom**: Empty catalog, no items
- **Cause**: Database or gamedata JSON issues
- **Check**:
  ```bash
  curl http://localhost:8080/gamedata/FurnitureData.json | head
  # Should return JSON data
  ```

## Database Issues

### "Access denied for user"
- **Cause**: Wrong database credentials
- **Fix**: Check emulator/config.ini matches database user

### "Unknown database 'habbo_retro'"
- **Cause**: Database not created
- **Fix**:
  ```bash
  mysql -u root -e "CREATE DATABASE habbo_retro;"
  ```

### "Table doesn't exist"
- **Cause**: Database not imported
- **Fix**: Import FullDB.sql again

## Network Issues

### "ERR_CONNECTION_REFUSED"
- **Cause**: Service not running on that port
- **Check**: `netstat -an | grep [PORT]`
- **Fix**: Start the service

### "ERR_EMPTY_RESPONSE"
- **Cause**: Server crashed or restarting
- **Fix**: Check server logs, restart service

### CORS Errors
- **Cause**: Assets served from different origin
- **Impact**: Usually just warnings, assets should still load
- **Fix**: Use proper web server (nginx/apache) in production

## Emulator Logs

View emulator logs:
```bash
# Real-time viewing
tail -f /Users/matt/DEV/retro/emulator/logging/*.log

# Search for errors
grep ERROR /Users/matt/DEV/retro/emulator/logging/*.log
```

Common log messages:
```
✅ "Nitro Websockets Listening" - WebSocket ready
✅ "GameEnvironment -> Loaded!" - Emulator ready
✅ "Arcturus Morningstar has successfully loaded" - All good
⚠️ "Column 'cost_happiness' not found" - Minor, ignore
❌ "Failed to initialize pool" - Database connection failed
❌ "Plugin failed to load" - Check plugins folder
```

## Performance Issues

### Client Loading Slowly
- Check asset server is running: `curl http://localhost:8080`
- Check network tab for slow requests
- Large FurnitureData.json (23MB) is normal, takes time

### High CPU Usage
- Emulator: Normal at 10-30% CPU
- Client: Normal at 5-15% CPU while idle
- Spikes during room loading are normal

### Memory Leaks
- Emulator should stay under 200MB
- If memory grows continuously, restart emulator
- Check for "memory leak" in logs

## Getting Help

### Information to Provide
When asking for help, include:

1. **Browser console output** (F12 → Console tab)
2. **Emulator log snippet** (last 50 lines)
3. **What you were trying to do**
4. **What happened instead**
5. **Your setup**:
   - OS: macOS
   - Emulator: Arcturus Morningstar 3.6.1
   - Client: Nitro React 2.1.1
   - Database: MySQL 9.5.0

### Useful Commands
```bash
# Check all services
netstat -an | grep LISTEN | grep -E "2096|3000|5173|8080|30000"

# View processes
ps aux | grep -E "java|python3|vite|mysql"

# Test asset server
curl -I http://localhost:8080/gamedata/FurnitureData.json

# Test database
mysql -u habbo_user -phabbo_password_2024 habbo_retro -e "SELECT COUNT(*) FROM users;"

# Check WebSocket
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://localhost:2096
```

## Success Criteria

Your setup is working if:
- ✅ No red errors in browser console (warnings OK)
- ✅ WebSocket shows "Connected" in Network tab
- ✅ Avatar loads and displays
- ✅ Can navigate hotel
- ✅ Can enter rooms
- ✅ Can see furniture
- ✅ Chat works

Minor issues you can ignore:
- ⚠️ Storage access warnings
- ⚠️ Missing badge images
- ⚠️ CORS warnings (in dev mode)
- ⚠️ Deprecated meta tag warnings

---

**Your Current Status**: ✅ FULLY OPERATIONAL

All critical systems working, only minor cosmetic issues (badges) which don't affect core functionality.