# Habland

**Habland** is a comprehensive multi-emulator development environment for Habbo Hotel retro projects. It serves as a unified research and development workspace containing multiple server implementations, modern client interfaces, and centralized management tools.

> [!TIP] > **Just want to get started?**
> Check out the [Quick Start Guide](QUICKSTART.md) to get the environment running in minutes.

## 📚 Core Documentation

- **[QUICKSTART.md](QUICKSTART.md)**: The fastest way to get servers and clients running.
- **[DOCKER_SETUP.md](DOCKER_SETUP.md)**: Detailed Docker environment configuration and troubleshooting.
- **[DOCKER_DEPLOYMENT_SUMMARY.md](DOCKER_DEPLOYMENT_SUMMARY.md)**: Deployment architecture and container details.
- **[TESTING_SUMMARY.md](TESTING_SUMMARY.md)**: Information on testing protocols and status.

## 🏗️ Project Structure

This repository is organized into distinct modules, each handling a specific part of the retro ecosystem:

### 🎮 Emulators & Servers

| Directory                | Description                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| **[`retro/`](retro/)**   | A modern, full-stack environment. See [Retro Environment Details](#retro-environment-details) below. |
| **[`kepler/`](kepler/)** | **Kepler** emulator setup. See [Kepler Environment Details](#kepler-environment-details) below.      |
| **[`havana/`](havana/)** | **Havana** emulator setup. See [Havana Environment Details](#havana-environment-details) below.      |
| **[`roseau/`](roseau/)** | **Roseau** server implementation.                                                                    |

### 🌟 Retro Environment Details

The **[`retro/`](retro/)** directory contains the most advanced and complete implementation.
👉 **[Read the Deep Dive Documentation](documentation/ARCTURUS_RETRO.md)**

### 🌌 Kepler Environment Details

The **[`kepler/`](kepler/)** directory contains the **v14 (2007 era)** Shockwave emulator.
👉 **[Read the Deep Dive Documentation](documentation/KEPLER.md)**

### 🌴 Havana Environment Details

The **[`havana/`](havana/)** directory hosts the **Havana** retro project (v31+).
👉 **[Read the Deep Dive Documentation](documentation/HAVANA.md)**

### 🏛️ Roseau Environment Details

The **[`roseau/`](roseau/)** directory implements the **v1 (2001 era)** server.
👉 **[Read the Deep Dive Documentation](documentation/ROSEAU.md)**

### 🛠️ Core Infrastructure Details

The ecosystem is glued together by shared services found in the root and specific folders:

#### 🎛️ Admin Panel (`admin-panel/`)

A custom **Next.js 16** application running on port `3000`.

- **Tech**: React 19, TailwindCSS v4, Dockerode.
- **Purpose**: Manage Docker containers, view logs, edit configurations, and manage the unified database from a GUI.

#### 🗄️ Unified Database (`unified-db/`)

A central **MariaDB** instance that can serve multiple emulators.

- **Port**: `3306`
- **Management**: Includes **phpMyAdmin** on port `8081`.
- **Scripts**: Contains initialization SQL scripts in `init/`.

#### 📦 Habbo Vault (`Habbo Vault/`)

A general storage directory for tools, plugins, and assets shared across projects.

### 🗺️ Architecture at a Glance

```
[Admin Panel (Next.js)] --docker.sock--> [Docker Engine]
         |                                   |
         |                             [Containers]
         |                          /   /    |     \ 
         |                         /   /     |      \ 
         v                        v   v      v       v
   [Unified DB] <----> [Emulators: Arcturus | Havana | Kepler | Roseau]
         ^                        ^          ^          ^
         |                        |          |          |
         +----> [Clients: Cool UI, Nitro React, Havana Web, Roseau Client]
```

Key flows: the admin panel controls containers via the Docker socket, all emulators share the unified MariaDB instance, and clients talk to their respective emulators (plus asset/CDN services).

### 🔌 Port Map (host -> container)

| Service | Port | Notes |
|---------|------|-------|
| unified-db | 3306 | MariaDB |
| phpmyadmin | 8081 | DB admin UI |
| redis | 6379 | Cache/session |
| arcturus-emulator | 30000 | Game server |
| arcturus rcon | 2096 | Remote console |
| havana-server | 12321/12322/12323 | Game / MUS / RCON |
| kepler-server | 13321/13309/13322 | Game / RCON / MUS |
| roseau-server | 37120/37119 | Game / RCON |
| cool-ui | 5174 | Modern client |
| nitro-react | 5173 | Modern client |
| havana-web | 8084 | Web client |
| roseau-client | 8082 | Web client |
| atomcms | 80 / 443 | CMS |
| asset-server | 8083 | Nitro assets |
| admin-panel | 3000 | Management UI |

### ⚙️ Environment Variables

Copy `.env.example` to `.env` and adjust for your host and credentials. A full reference lives in [documentation/ENVIRONMENT.md](documentation/ENVIRONMENT.md).

### 🌍 Resources

- **[`translation_lists/`](translation_lists/)**: A massive project to translate the Arcturus catalog from Spanish to English. See [translation_lists/README.md](translation_lists/README.md) for progress and contributing.

## 🚀 Getting Started

The recommended way to run the environment is via the provided helper script:

```bash
# Start the interactive management menu
./docker-manage.sh
```

Or start a specific stack directly:

```bash
./docker-manage.sh start arcturus
```

For full instructions, please refer to the [Quick Start Guide](QUICKSTART.md).