2.2 KiB
Hearthmod Modernization Notes
This workspace contains the Hearthmod stack (game server, lobby server, web UI, and supporting components). The current goal is to stabilize the development environment and improve maintainability without changing client protocol compatibility.
Component-by-Component Replacement Plan
Replacing services incrementally is the safest path. It preserves existing behavior while enabling modernization behind compatibility boundaries.
- Baseline and observability: document startup order, ports, and data flows; add basic health checks and structured logs.
- Gateway layer: introduce a thin gateway that speaks the legacy protocol and routes to existing lobby/game services.
- Lobby replacement: implement lobby endpoints behind the gateway, canary traffic to validate parity.
- Game server replacement: implement the game loop and compare deterministic state snapshots with the legacy server before shifting traffic.
- Data layer swap: add a DAL in new services, mirror writes to a new store, then flip reads after validation.
- Decommission legacy: remove unused services and dependencies once traffic is fully migrated.
Maintainability Priorities
- Keep configuration centralized (env or config files).
- Prefer a single entrypoint script or container orchestration for local dev.
- Add small smoke tests to validate service health and database connectivity.
Local Dev (C Services)
If Couchbase is running on localhost:8091 with bucket hbs (password aci),
use the repo-local entrypoint to build and run the core servers:
./dev build
./dev start
./dev logs
Override targets via env vars:
HM_GAMESERVER_IP=127.0.0.1 HM_GAMESERVER_PORT=3724 ./dev start
Stop with:
./dev stop
For the full Ubuntu install flow (Couchbase + web + client), use
hearthmod/host_ctl_ubuntu.sh.
Docker Dev
Docker runs Couchbase plus the C servers. Start with:
./dev docker-build
./dev docker-start
./dev docker-logs
Stop with:
./dev docker-stop
Protocol Notes
See PROTOCOL-NOTES.md for the current opcode decoder map and client-derived
learnings used for compatibility work.