A master server for reconnecting the community

Discovery is the missing bridge

A dedicated server can be healthy and still feel invisible. Players need a current list of reachable matches, useful names, map and mode information, occupancy, version compatibility, and enough health context to avoid repeatedly joining dead endpoints.

Hosts need the opposite side of that exchange: a simple way to announce a server, refresh its presence, update match metadata, and disappear naturally when heartbeats stop. The master server’s first responsibility is to make that exchange boring, fast, and reliable.

A deliberately narrow service

The master server should not simulate matches, stream VXL maps, resolve combat, or become a mandatory gameplay dependency after connection. Those jobs belong to BattleSpades and other compatible dedicated servers.

Its core domain is registration and discovery. A host presents an endpoint and public metadata. The service validates what it safely can, records a short-lived listing, and exposes an efficient read model to compatible clients and web tools.

• Register or refresh a dedicated server listing
• Expire stale records when signed heartbeats stop
• Expose filtered, paginated discovery for clients
• Report map, mode, occupancy, region, build, and compatibility
• Keep administrative moderation separate from ordinary listing writes

The first API contract

The write path is intentionally small: registration establishes a verified listing, heartbeat refreshes liveness and mutable match data, and deregistration allows a clean shutdown. A read endpoint returns normalized listings without exposing internal moderation fields or unnecessary host information.

Versioning belongs in the URL or negotiated schema from day one. The clients and server binaries will not all update together, so additive evolution and explicit compatibility ranges are safer than silently changing a payload used by live builds.

1. 01
   Register

   The host supplies its public endpoint, server identity, compatibility range, and initial match summary.

2. 02
   Verify

   The service challenges or observes the endpoint so arbitrary third parties cannot list servers they do not control.

3. 03
   Heartbeat

   A short-lived lease is refreshed with occupancy, current map, mode, and health information.

4. 04
   Discover

   Clients request a compact, cache-friendly list and make the final game connection directly to the host.

Abuse resistance without needless surveillance

Public registration attracts spoofing, floods, misleading names, and endpoints that disappear. Rate limits, short leases, endpoint verification, payload limits, audit trails, and operator tools are basic reliability requirements—not optional polish.

The service should collect the minimum information required to operate discovery. Public server metadata is expected to be public; private player data is not. Logs need bounded retention, secrets need rotation, and moderation decisions need enough history to be reviewable without turning the service into a player tracking system.

• No plaintext administrative credentials in registration payloads
• Bounded names, descriptions, tags, and heartbeat sizes
• Per-identity and per-network rate limits with sensible burst capacity
• Short expiration windows so stale servers remove themselves
• Health and moderation signals kept distinct from public claims

A staged route to production

The contract, persistent registration store, public directory, operator controls, and server-scoped credentials are now in place. The next production gate is exercising UDP verification and lease renewal with real community hosts across home, cloud, and hosted networks.

A fallback matters. Players should still be able to connect directly by address when discovery is unavailable. That single decision prevents an outage in a convenience service from becoming an outage in every independent match.