A modern social hotel runtime with a clean CMS, launcher handoff, and original long-term architecture.
Architecture · Compatibility · Changelog · Roadmap
Epsilon Emulator is a clean-room hotel emulator project built to preserve classic client behavior while replacing fragile legacy runtime assumptions with a modern, versioned, testable architecture.
The public web layer now runs as Epsilon Web Management System: a modern CMS runtime with a retro-inspired 2007 visual skin, official Epsilon pixel branding, and a strict launcher handoff boundary.
The target is not an old runtime. The target is the hotel contract:
- protocol behavior
- room simulation rules
- item and catalog behavior
- social flows
- moderation flows
- content loading rules
Older emulator projects proved that the game could be revived, but they also repeated the same problems:
- hardcoded packets and content metadata
- weak authentication and authorization boundaries
- fragile in-memory runtime state
- database schema treated as domain design
- CMS, launcher, admin, and hotel runtime mixed together
Epsilon exists to fix those problems directly.
Epsilon is being built as a multi-era hotel platform.
Long term, the project should be able to:
- run multiple Habbo compatibility families through explicit adapters
- preserve classic hotel behavior without inheriting legacy emulator structure
- add modern infrastructure, security, observability, and deployment discipline
- support new original features such as roleplay systems, modern social features, and future client surfaces
The mission is not “one retro clone per version.” The mission is one stable hotel platform with:
- version-aware protocol adapters
- version-aware content visibility
- stable core hotel domains
- room for original product evolution
| Pillar | Meaning |
|---|---|
| Compatibility-first | The emulator preserves hotel behavior, not legacy code structure. |
| Modern runtime | .NET 10, explicit module boundaries, typed configuration, centralized package management. |
| Data-driven rules | Protocol and content behavior should live in manifests, pipelines, and importable definitions. |
| Security-aware | Gameplay correctness and trust boundaries are treated as first-class concerns. |
| Long-term survivability | The project is designed to remain maintainable across years, not just to boot quickly. |
| Area | Choice |
|---|---|
| Runtime | .NET 10 |
| Version | 0.4.0-alpha.6 |
| Architecture | Modular monolith |
| Primary persistence | PostgreSQL |
| Cache / transient infra | Redis |
| Admin/API | ASP.NET Core |
| Protocol model | External packet and command manifests |
| Compatibility family | RELEASE63 |
| CMS identity | Epsilon Web Management System |
Epsilon starts with one strong baseline and expands outward.
- first stable adapter target:
RELEASE63 - long-term target: multi-version support across classic, Flash-era, and later compatible hotel surfaces
- expansion rule: each client family gets its own adapter layer instead of leaking revision logic into hotel services
That means:
Epsilon.CoreGame,Epsilon.Rooms,Epsilon.Content, andEpsilon.Gamesstay mostly stable- compatibility-specific behavior is isolated in protocol, launcher, content, and rendering adapters
- new technology can be added without breaking old hotel contracts
Epsilon is already beyond scaffold stage. The repository currently includes:
- protocol packet and command registries
- room entry state machine
- room runtime snapshots and mutable room interaction services
- bootstrap/session surfaces
- housekeeping and support slices
- package and asset import pipelines
- security hardening for current gameplay endpoints
Current release focus in 0.4.0-alpha.6:
- official Epsilon pixel logo installed for the CMS and repository presentation
- retro 2007 CMS skin applied on top of the modern CMS runtime
- language selection narrowed to English, Spanish, Portuguese, French, and Russian
- CMS runtime sanitization now removes low-value legacy vendor residue from active views/settings
- CMS entry flow remains separated from launcher, loader, and emulator-confirmed hotel presence
- release documentation now states requirements, version, risks, and progress clearly for community review
Recent hardening already covered:
- forged in-room identity for movement and chat
- missing capability checks on room-affecting commands
- runtime concurrency issues in the in-memory room slice
- unsafe
signandcarrypayload handling - missing flood control in room chat
- basic actor and furni collision checks
Recent runtime expansion now covered:
:pickallreturns room items to inventory- room presence migrates cleanly when an actor enters another room
- moderation commands now cover kick, mute, ban, transfer, and alert paths
- room inspection and directed chat commands now exist in the runtime layer
The percentages below are current engineering estimates of implemented, verified, and operable coverage. They are intended to show actual module maturity, not issue-count vanity metrics.
| Scope | Progress | Notes |
|---|---|---|
| Global emulator operativity | 98% |
The project spans gameplay, CMS, launcher, and native app surfaces, but public-facing stability is still not production grade. |
| Architecture quality | 99% |
Core boundaries between CMS, launcher, client, and emulator are now explicit and defensible. |
| Repository hygiene | 99% |
Naming, staging discipline, and runtime separation are in strong condition. |
Epsilon.Gateway |
90% |
Main runtime/API surface is broad and stable, but protocol parity is still incomplete. |
Epsilon.Protocol |
54% |
Packet and command manifests exist, but live gameplay still trails the HTTP/runtime path. |
Epsilon.Auth |
86% |
Session/auth boundaries and modern password hashing are in place; full production auth migration is pending. |
Epsilon.CoreGame |
91% |
Hotel flows, commands, moderation, commerce, room entry, and snapshots are heavily developed. |
Epsilon.Rooms |
82% |
Room definitions, runtime interaction, and presence handling are solid; deeper furni mutation is still incomplete. |
Epsilon.Content |
91% |
Catalog, badges, avatar content, campaign/content modeling, and import structures are advanced. |
Epsilon.Persistence |
58% |
Architecture is strong, but too much live behavior still depends on InMemory. |
Epsilon.Games |
75% |
Game definitions and BattleBall lifecycle exist, but full live loops are still missing. |
Epsilon.Launcher |
90% |
Client bootstrap, access-code flow, channels, profiles, telemetry, and published client routing are now in place. |
Epsilon.AdminApi |
74% |
Admin/runtime inspection works, but full moderation and operational tooling is not complete. |
| CMS platform | 72% |
CMS backend, public portal, branding, language surface, and launcher access exist; registration/access still needs production hardening. |
| Desktop launcher apps | 74% |
Native Avalonia launcher and Electron reference shell exist; final launch targets are still pending. |
| Asset/content ingest pipeline | 94% |
Client roots, builds, avatar bundles, figures, badges, and related manifests are organized and reproducible. |
| Multi-process runtime integrity | 84% |
Shared sessions improved, but shared room presence/state still needs stronger distributed handling. |
| Feature area | Progress | Notes |
|---|---|---|
| Authentication and session lifecycle | 87% |
Modern password hashing, ticket/session stores, heartbeats, and disconnect flow exist; production auth migration is still pending. |
| Protocol-driven hotel execution | 54% |
Protocol manifests and command execution bridge exist, but too much live behavior still runs through HTTP-first paths. |
| Room runtime and mobility | 82% |
Entry, presence, chat, directed commands, and adjacency movement are in place; full path queues and rich furni mutation are still incomplete. |
| Chat and command system | 93% |
Rank-aware commands, moderation commands, whisper/shout, link handling, and normalization are working. |
| Moderation and staff tooling | 78% |
Room-present moderation is real, but offline/account-wide workflows and case tooling are still missing. |
| Bot runtime | 69% |
Deterministic runtime bots, scripted replies, and service actions exist; pathing, scheduling, and admin configuration still need expansion. |
| Groups and social foundations | 72% |
Group creation, membership, and linked private rooms work; forums and richer role management remain incomplete. |
| Catalog, economy, and inventory | 88% |
Catalog content, purchases, vouchers, and inventory slices are advanced; full trading-grade mutation is still not finished. |
| Avatar, badges, and collectible content | 92% |
Badge catalog, avatar asset digestion, figure manifests, and collectible-ready content models are in strong shape. |
| Public rooms and hotel world features | 85% |
Public-room definitions, behaviors, bots, and package inventories are strong; more interactive venue logic is still needed. |
| Games | 75% |
BattleBall lifecycle and game session foundations are in place; deeper live loops for all game families are still pending. |
| Launcher and connection policy | 90% |
Client profiles, launcher access codes, desktop launcher contracts, and device-aware connection policies are now in place. |
| CMS, launcher app, and access flow | 73% |
Access logic is correct, branding is cleaner, and CMS handoff is usable; both CMS and launcher still need another hardening pass. |
| Configuration platform | 90% |
Root configuration layering and service templates are in place; more feature sections need to be fully bound into runtime. |
| Multi-version compatibility foundation | 63% |
The adapter strategy, client/build manifests, and launcher profiles are in place; only RELEASE63 is currently the strong baseline. |
| Roleplay and original Epsilon features | 22% |
The platform direction is defined, but dedicated roleplay systems are still future work. |
Current weakest points, in order:
Epsilon.Persistencestill relies too heavily onInMemoryfor live state and CMS continuity.Epsilon.Protocolstill trails the HTTP/runtime path for real gameplay execution.- CMS and launcher app surfaces are functional but still unstable.
Epsilon.Gamesstill needs deeper live round loops beyond lifecycle control.Epsilon.Roomsstill needs full furni placement, pickup, and trading-grade mutation paths.
xychart-beta
title "Epsilon alpha coverage by system"
x-axis ["Architecture", "CoreGame", "Launcher", "Content", "Rooms", "CMS", "Persistence", "Protocol"]
y-axis "Coverage %" 0 --> 100
bar [99, 91, 90, 91, 82, 72, 58, 54]
Architecture [################################################# ] 99%
CoreGame [############################################## ] 91%
Launcher [############################################# ] 90%
Content [############################################## ] 91%
Rooms [######################################### ] 82%
CMS [#################################### ] 72%
Persistence [############################# ] 58%
Protocol [########################### ] 54%
The graph is intentionally conservative. It highlights the important truth for contributors: the platform architecture is strong, but the CMS still needs work before it should be treated as production ready.
0.4.0-alpha.6 is the first release where the Epsilon identity is consistent across the repository and active CMS runtime.
Delivered in this release:
- CMS:
- official Epsilon CMS logo
- Epsilon Web Management System naming
- retro 2007 visual skin over the modern runtime
- English, Spanish, Portuguese, French, and Russian language selector
- sanitized settings, views, and active branding residue
- launcher backend:
- desktop config
- update channels
- launch profiles
- client-started telemetry
- access rule:
- CMS never claims hotel presence
- launcher never claims hotel presence
- only emulator-confirmed runtime presence counts as real entry
Known instability in this release:
- CMS presentation and registration/access flow still need hardening
- launcher native packaging exists, but final package targets are still not published
game-loaderis provisional and does not represent the final social/isometric client- production durability is still blocked by remaining
InMemoryslices
Gateway
-> Protocol
-> Auth
-> CoreGame
-> Rooms
-> Content
-> Persistence
-> AdminApi
Each module has a narrow responsibility:
Epsilon.Gatewayhandles HTTP/runtime entry surfacesEpsilon.Protocolowns compatibility manifests and command mappingEpsilon.Authowns tickets, sessions, and authentication boundariesEpsilon.CoreGameowns hotel flows and gameplay servicesEpsilon.Roomsowns room and layout definitionsEpsilon.Contentowns catalog, item, package, and asset definitionsEpsilon.Persistenceowns replaceable storage providersEpsilon.AdminApiowns administrative surfaces
src/— production codetests/— automated testsapps/— desktop launcher app sourcesvendor/cms-runtime-base/— ignored local CMS/assets/DB base adopted for bootstrapconfiguration/— shared and per-service configuration templatesdocs/architecture/— architecture and domain designdocs/requirements/— local SDK and project execution requirementsdocs/releases/— release snapshots and alpha release notesdocs/compatibility/— protocol and target-client materialdocs/roadmap/— execution roadmapcatalog/— schemas and generated manifeststools/— maintenance, verification, and local CMS runtime scriptsreferences/— source handling rules and reference hygiene
- Architecture Overview
- Module Boundaries
- CMS Platform
- Launcher Access
- Desktop Launcher
- Project Requirements
- Launcher Handoff Flow
- Local Runtime
- CMS Runtime Base
- Design Principles
- Client Platform
- Hotel Domains
- Protocol Baseline
- Target Client
tools/clean_workspace.sh— removes generated local artifacts.tools/verify_workspace.sh— runs hygiene, naming, language scope, tests, launcher build, optional Node check, and optional runtime health check.tools/weight_report.sh— reports the largest local files and folders.tools/check_language_scope.sh— keeps non-primary languages limited to their intended layer.tools/cms_runtime_start.sh— starts the temporary CMS/assets/runtime base.tools/cms_runtime_check.sh— verifies CMS, client, assets, imager, and realtime health.tools/cms_runtime_sanitize.sh— applies the Epsilon CMS identity, language surface, and active runtime cleanup.tools/cms_runtime_audit.sh— checks the active CMS for runtime health and common residue.tools/package_launcher_macos.sh— packages the native launcher as a macOS DMG.
Epsilon should stay conservative with languages:
- C# is the main runtime language for backend, gateway, domain, persistence, protocol, and tests.
- VB is limited to the native launcher shell until that launcher is replaced or rewritten.
- JavaScript is limited to the Electron launcher shell and static launcher/client assets.
- SQL is limited to database schema and seed material.
- Shell/Python are maintenance-only and must not become product runtime code.
The source tree is now organized by service and domain so each project is easier to scan and maintain.
src/Epsilon.Auth/—Abstractions,Configuration,Contracts,Services,Storage,Startupsrc/Epsilon.Content/—Badges,Catalog,Client,Collectibles,Effects,Interfaces,Items,Localization,Navigator,Pets,PublicRooms,Voucherssrc/Epsilon.CoreGame/—Access,Accounts,Badges,Bots,Chat,Commerce,Groups,Hotel,Interface,Inventory,Moderation,Navigator,Packets,Pets,Roles,Rooms,Studio,Subscriptions,Support,Walletsrc/Epsilon.Games/—BattleBall,SnowStorm,WobbleSquabble,Core,Runtime,Sessions,Startupsrc/Epsilon.Gateway/—Configuration,Console,Contracts,Startupsrc/Epsilon.Launcher/—Configuration,Models,Services,Startupsrc/Epsilon.Persistence/—Configuration,InMemory,Postgres,Redis,Runtime,Seed,Startupsrc/Epsilon.Protocol/—Configuration,Manifests,Registry,SelfCheck,Startupsrc/Epsilon.Rooms/—Contracts,Models
The test tree follows the same approach:
tests/Epsilon.CoreGame.Tests/— grouped intoAuth,Badges,Chat,Commands,Commerce,Games,Groups,Hotel,Moderation,Rooms,Runtime
Epsilon is a preservation and interoperability project.
This repository does not aim to:
- redistribute proprietary assets without review
- normalize cracked or malware-risk archive material
- present low-trust sources as production dependencies
- misrepresent affiliation with Habbo or Sulake
Reference material may inform behavior and formats, but it must not become runtime inheritance by accident.
Epsilon is still alpha software. It compiles, runs, and already exposes real gameplay services, but the security surface is still being tightened as more game behavior is added.
Near-term priorities include:
- replacing development-only authentication
- reducing diagnostic exposure in production
- binding every mutable action to authenticated session state
- moving more mutable runtime state away from in-memory storage
- enforcing authorization consistently across gateway and services
.NET SDK 10- Docker or Docker Desktop
- Node.js and npm for CMS/tooling and launcher shell work
- Unity Hub / Unity Editor only for the future Unity client package, not for the CMS itself
- macOS packaging tools only when producing a
.dmg
The repository includes a local development stack in compose.yaml:
- PostgreSQL
16 - Redis
7
Environment defaults live in .env.example.
cp .env.example .env
docker compose up -d
dotnet restore
dotnet build
dotnet test
dotnet run --project src/Epsilon.Gateway/Epsilon.Gateway.csprojcurl http://127.0.0.1:5100/healthThe next major milestones are:
- complete authenticated session flow and remove development auth assumptions
- wire more gameplay actions through the protocol layer
- implement inventory and furni mutation with anti-duplication guarantees
- expand persistence beyond the current read-heavy slices
- continue package, public-room, icon, and visual asset pipelines
- add compatibility adapters beyond
RELEASE63 - add original hotel extensions, including roleplay-oriented systems, without polluting compatibility layers
- cloning a specific legacy emulator architecture
- copying legacy SQL schemas into the core domain
- embedding compatibility rules directly inside gameplay code
- mixing research artifacts into production execution
- depending on Adobe Flash as a required runtime
Epsilon Emulator is an independent software project. It is not affiliated with, endorsed by, or represented as an official Habbo or Sulake product.