Skip to content

Server Heartbeats

gokz-top-servers is the SourceMod plugin that pushes live server status into the GOKZ.TOP API. It sends richer data than A2S alone can provide, including per-player GOKZ timer state.

Requirements

  • gokz-top-core must already be installed and configured.
  • cfg/sourcemod/gokz-top/gokz-top-core.cfg must contain a valid gokz_top_server_group_key.
  • The server must push from its real public IPv4 and hostport.

Configuration

gokz-top-servers adds one server-side cvar:

  • gokz_top_servers_push_interval
  • Default: 4.0
  • Minimum: 2.0
  • Maximum: 10.0

Generated config files live under cfg/sourcemod/gokz-top/:

  • gokz-top-core.cfg
  • gokz-top-servers.cfg

The plugin sends periodic heartbeats on that interval and also queues immediate pushes on map start plus player connect and disconnect events.

On the first accepted heartbeat for a server-group key, the API will automatically:

  • create a missing server row for that (ip, port) endpoint, or
  • claim an existing unassigned discovered row for that endpoint.

Explicitly disabled servers and endpoints already assigned to a different server group are still rejected.

Public IP Cache

The plugin stores its public-IP cache at addons/sourcemod/data/gokz-top/public_ip_cache.json.

Cached fields:

  • public_ip
  • last_refresh

Refresh behavior:

  1. If the cache is less than 24 hours old, the cached IP is reused.
  2. Otherwise the plugin requests http://ip-api.com/json with an approximately 3 second timeout and reads query.
  3. If that fails, it requests https://myip.wtf/json with an approximately 3 second timeout and reads YourFuckingIPAddress.
  4. If both fail, public IP remains unset and /v1/servers/status pushes are skipped until a later refresh succeeds.

This avoids pushing private or stale endpoints to the API.

Heartbeat Payload

Each heartbeat includes the server endpoint and a player list:

  • ip
  • port
  • observed_at
  • hostname
  • map
  • player_count
  • max_players
  • players

Each player row includes:

  • tag
  • mode
  • name
  • score
  • status
  • duration_seconds
  • is_paused
  • steamid64
  • teleports
  • timer_time
  • stage

status values:

  • not_started
  • in_progress
  • finished
  • aborted

Pause state is sent separately in is_paused; paused players still report status: "in_progress".

Troubleshooting

  • If the server never appears online, confirm the GOKZ.TOP server entry uses the same public IPv4 and hostport the plugin resolves.
  • If player-session events work but server heartbeats do not, check that the server-group key is still valid and that the public-IP cache is not empty after both providers fail.
  • If status updates look delayed, verify gokz_top_servers_push_interval is not set above the default and check for repeated public-IP refresh failures in the SourceMod logs.