Private server for Hero Zero - browser RPG
The original Flash client runs through Ruffle.rs WebAssembly — no Flash Player needed.
Features · Screenshots · Installation · Socket Server · Admin Panel · CLI Scripts
Built on top of xReveres/HeroZServer v0.2. The original base had the core game loop but a lot was either broken or missing on PHP 8.x. This project rewrites and extends the server to get it closer to how the real game works, including systems that were never implemented in the original code.
| Feature | Description |
|---|---|
| Ruffle.rs | Flash SWF client runs natively in Chrome, Firefox, Edge — no plugins |
| WebSocket Server | Real-time push notifications for messages, goals, guild events, world boss |
| Email System | PHPMailer + MySQL async queue, password reset flow with tokens |
| Admin Panel | Bootstrap 5 dark theme, 9 management controllers |
| Multi-Language | Polish, English, Portuguese (PT-BR) on all pages |
| CDN Proxy | Serves Akamai game assets locally, bypasses CORS |
| System | Status | Details |
|---|---|---|
| Quests, Duels, Training, Work | ✅ | All core gameplay loops |
| Guild Battles | ✅ | Team fights with tactics and projectiles |
| Guild Leader Elections | ✅ | Vote-based leadership transfers with majority resolution |
| Guild Artifacts | ✅ | Release artifacts for premium currency with cooldown |
| Goals & Achievements | ✅ | 243 achievements, 9 reward types, real-time sync |
| Herobook Objectives | ✅ | 3 daily + 2 weekly rotating challenges (level 40+) |
| Tournaments | ✅ | Weekly events with XP/honor leaderboards and rewards |
| World Boss | ✅ | Server-wide boss fights with damage rankings |
| Sewing Machine | ✅ | Change item skins for gold or donuts |
| Costume Collections | ✅ | 33 themed sets with milestone rewards |
| Guild Dungeons | ✅ | Full attack/join flow with NPC team battles |
| Guild Battle History | ✅ | View past guild battles and dungeon fights |
| Surprise Box | ✅ | 1-3 random equipment pieces (rare/epic) |
| Daily Login Rewards | ✅ | Consecutive login bonuses |
| Slot Machine | ✅ | 7 reward types (coins, XP, stat points, energy, training, boosters, items), anti-exploit protection |
| Sidekicks | ✅ | Equip, merge, rename, release, reorder |
| Message Ignore | ✅ | Block/unblock characters from messaging you |
| Messages | ✅ | Send, delete, claim item attachments |
| Account Management | ✅ | Change password/email, delete account, stat redistribution |
| Voucher / Promo Codes | ✅ | Code validation, usage limits, level/locale restrictions, expiry |
| Leaderboards | ✅ | Character XP, honor, guild rankings |
| Event Quests | ✅ | 13 themed events with objectives and rewards |
URL: http://localhost/admin/ · Login: admin / admin
| Module | Features |
|---|---|
| Dashboard | Server stats, player count, recent activity |
| Users | Ban/unban, reset password, add currency, view details |
| Characters | Edit stats, appearance, level, quick actions, give items (bag/bank) |
| Guilds | Members, currency, settings |
| Items | Read-only catalog of 779 templates (search, filter by type/quality/pattern) |
| Messages | Compose, broadcast to all players |
| Queue, log, broadcast, SMTP settings | |
| Events | Activate/deactivate events with date picker, auto-expires player records |
| Config | Server config viewer, cache clear |
About 89% of the game client's actions are implemented. The remaining actions require external components we don't have (friend bar SWF).
Not planned: Payments, Advertising, SSO/Platform, Kongregate, Game Testing, Friend System (requires external friendbar.swf we don't have), Resource Requests (depends on Friend System).
┌──────────────────────────────────────────────────┐
│ Browser │
│ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │
│ │ Ruffle.rs│ │ SWF Game │ │ Language Switch│ │
│ │ (WASM) │ │ (Flash) │ │ (PL/EN/BR) │ │
│ └────┬─────┘ └────┬─────┘ └────────────────┘ │
└───────┼─────────────┼────────────────────────────┘
│ │
WebSocket HTTP POST
(port 9998) (port 80)
│ │
┌───────┼─────────────┼───────────────────────────┐
│ ▼ ▼ Server │
│ ┌─────────┐ ┌────────────┐ ┌───────────────┐ │
│ │ Node.js │ │ Apache │ │ Admin Panel │ │
│ │ Socket │ │ PHP 8.x │ │ Bootstrap 5 │ │
│ │ :9999 │ │ request/ │ │ /admin/ │ │
│ └────┬────┘ └─────┬──────┘ └───────────────┘ │
│ │ │ │
│ └──────┬──────┘ │
│ ▼ │
│ ┌────────────┐ ┌─────────────────┐ │
│ │ MySQL 8.x │ │ CDN Proxy │ │
│ │ (hz) │ │ (Akamai assets) │ │
│ └────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────┘
- Windows: Laragon (recommended), XAMPP, WAMP, or manual Apache + PHP + MySQL
- Linux: LAMP (
apt install apache2 php php-mysql php-curl mysql-server) or LEMP (Nginx) - Node.js 18+ (for the real-time socket server)
- Composer (for PHP dependencies)
- PHP extensions:
curl,pdo_mysql
# 1. Clone the repository
git clone https://github.com/xReveres/HeroZServer.git
cd HeroZServer
# 2. Install PHP dependencies
composer install
# 3. Create database and import schema
mysql -u root -e "CREATE DATABASE hz;"
mysql -u root hz < hzpriv.sql
# 4. Install socket server
cd socket-server && npm install && cd ..MySQL strict mode — Edit my.ini / my.cnf, add under [mysqld]:
sql_mode=NO_ENGINE_SUBSTITUTIONRestart MySQL after this change. Without it, INSERTs on legacy tables fail silently.
Server config — Edit server/config.php:
'public_url' => 'http://localhost/',
'request_url' => 'http://localhost/server/request.php',
'resource_cdn' => 'cdn/proxy.php?a=', // proxies Akamai CDN
'socket_url' => 'http://localhost:9999',Cache permissions (Linux only):
chmod -R 777 server/cache/# Start the socket server (required for real-time features)
node socket-server/server.js
# Or use the platform-specific scripts:
# Windows: double-click socket-server/start.bat
# Linux: chmod +x socket-server/start.sh && ./socket-server/start.shThen open http://localhost/ in your browser. Create an account, create a character, play.
For password reset and notifications, install MailPit for local development:
# Start MailPit (SMTP on :1025, Web UI on :8025)
mailpitEmails are sent automatically — when Mail::queue() is called, it inserts into the queue and sends immediately. If sending fails (SMTP down, network issue), the email stays as pending in the queue. To retry failed emails:
- Admin panel: Email → Process Queue button
- CLI:
php server/process-email-queue.php - Scheduled (optional): cron or Task Scheduler to auto-retry every 5 minutes
Email config is in server/config.php under the email block.
Real-time push notifications to connected game clients.
SWF Client ──► Ruffle socketProxy ──► ws://localhost:9998 ──► TCP localhost:9999
(proxy) (Socket.IO EIO=2)
| Port | Protocol | Purpose |
|---|---|---|
| 9999 | Socket.IO (EIO=2) | Main server — HTTP polling handshake + WebSocket upgrade |
| 9998 | WebSocket | Ruffle proxy — tunnels raw TCP bytes from browser to port 9999 |
Why two ports? Browsers can't make raw TCP connections. Ruffle's
socketProxytunnels SWF'sflash.net.SocketTCP through a browser WebSocket.
| Event | Description | Used by |
|---|---|---|
syncGameImmediate |
Refresh game state (messages, quests, goals) | Socket::syncGame(), Socket::syncGameAll() |
syncGameAndGuild |
Refresh game + guild data | Socket::syncGameAndGuild() |
syncGuildLog |
Real-time guild chat messages and log updates | Socket::syncGuildLog() |
syncWorldboss |
Real-time world boss HP updates | Socket::syncWorldboss() |
syncSlotmachineChat |
Broadcast slot machine wins to all players | Socket::syncSlotmachineChat() |
The SWF client also supports
syncFriendBarbut it is not currently sent by the server.
use Srv\Socket;
Socket::syncGame($userId); // notify specific user
Socket::syncGameAll(); // broadcast to all
Socket::syncGameAndGuild($userId); // sync game + guild
Socket::syncGuildLog($guildId, $excludeUserId); // guild chat/log to members
Socket::syncWorldboss($eventId, $hpCurrent); // world boss HP broadcast
Socket::syncSlotmachineChat($message); // slot machine win broadcastcurl http://localhost:9999/status
# Returns connected clients and user mapSchedule these with cron (Linux) or Task Scheduler (Windows) for automatic operation.
| Script | Command | Description |
|---|---|---|
| World Boss | php server/process-worldboss.php spawn |
Spawn a new boss event (4h duration) |
php server/process-worldboss.php process |
Generate rewards when boss dies or time expires — must run periodically | |
php server/process-worldboss.php check |
Check event status (HP, time remaining) | |
| Tournament | php server/process-tournament.php start |
Start weekly tournament |
php server/process-tournament.php end |
End current tournament and generate rewards | |
php server/process-tournament.php status |
Check tournament status | |
php server/process-email-queue.php |
Process pending emails |
Important:
process-worldboss.php processmust run regularly (every 5-10 min) via Task Scheduler or cron. Without it, rewards are never generated and players cannot claim them after the boss is defeated. The boss HP formula assumes at least 100 active players — for solo testing, reduce HP manually after spawning:UPDATE worldboss_event SET npc_hitpoints_total = 5000, npc_hitpoints_current = 5000 WHERE status = 1;
| Scenario | What to clear |
|---|---|
| Config changes | server/cache/data/*.tmp |
| GameSettings changes | server/cache/cache.json + server/cache/data/*.tmp |
| initEnvironment changes | server/cache/data/*.tmp |
The admin panel has a Clear Cache button under Config.
| Check | Command |
|---|---|
| Test API | curl -X POST http://localhost/server/request.php -d "action=initGame&client_version=flash_123" |
| CDN proxy | curl http://localhost/cdn/proxy.php?a=assets/sounds/ui_dialog_open.mp3 |
| Socket status | curl http://localhost:9999/status |
| MySQL mode | SELECT @@sql_mode; — must NOT contain STRICT_TRANS_TABLES |
| PHP errors | Comment out error_reporting(0) in server/request.php (breaks JSON) |
See CHANGELOG.md for the full changelog.
| Version | Date | Highlights |
|---|---|---|
| 2.0.1 | 2026-03-29 | Fix self-duel bug (opponent list + server crash) |
| 2.0.0 | 2026-03-21 | Event quest system (13 themed events, 11 objective types, event item drops) |
| 1.1.0 | 2026-03-19 | Message ignore system (ignore/unignore, server-side blocking) |
| 1.0.6 | 2026-03-18 | Quick win handlers (locale, ToS, quest refresh, logout, error logging), league fight fix |
| 1.0.5 | 2026-03-15 | Guild battle history, voucher/promo codes with admin panel, item validation |
| 1.0.4 | 2026-03-15 | 10 new handlers (guild elections, artifact release, message items, account management), Config::get() fix |
| 1.0.3 | 2026-03-14 | Slot machine (7 reward types, anti-exploit), world boss attack flow, tournament fixes |
| 1.0.2 | 2026-03-13 | World boss attack flow fixes, admin items/characters improvements |
| 1.0.1 | 2026-03-13 | Message system bug fixes |
| 1.0.0 | 2026-03-10 | Major rewrite — Ruffle.rs, email, admin, socket server, goals, herobook, tournaments, world boss, sewing, costumes, guild dungeons, surprise box |
| 0.2 | 2018 | Guild battles, energy limits, training, daily rewards, slot machine |
| 0.1 | 2018 | Original engine rewrite by xReveres |
This is a hobby project but contributions are welcome. Feel free to open issues or submit pull requests.
If you'd like to support the project, you can support me on Ko-fi.
This project is licensed under the GNU General Public License v3.0.
Developed by Owryn · Built on xReveres/HeroZServer · Flash emulation by Ruffle.rs