BYOND Game API

Keep your listing connected to the world.

A running DreamDaemon world can report its current public status once per minute. The token cannot compile code, operate the runtime, browse files, import SQL, read saves, or sign in to Mudhaven.

POST

Endpoint

Post the project heartbeat

POSThttps://mudhaven.net/api/v1/byond/projects/{project-key}/heartbeat

The exact project key, endpoint, and one-time token are shown inside the approved project's Game API tab.

Authentication

Bearer or associative form token

JSON clients should send Authorization: Bearer …. Dream Maker may instead include the token as the token field in an associative form POST supported by world.Export().

The token is write-only and heartbeat-only.

Keep it in server-only configuration. Rotate it immediately if it enters public source, logs, or a downloadable project.

Request body

Supported fields

FieldRequirementContract

statusRequiredonline, starting, or maintenance

playersRequiredInteger from 0 through 10,000

max_playersOptional1 through 10,000; never below current players

game_versionOptionalPublic version up to 64 characters

round_nameOptionalPublic round, mode, or phase up to 120 characters

uptime_secondsOptionalNon-negative integer capped at ten years

customOptionalUp to six owner-configured typed public facts

Dream Maker

Server-side heartbeat loop

var/const/MUDHAVEN_API_URL = "https://mudhaven.net/api/v1/byond/projects/your-project-key/heartbeat"
var/const/MUDHAVEN_API_TOKEN = "mhb_replace_with_your_token"
var/mudhaven_started_at = 0

/world/New()
    . = ..()
    mudhaven_started_at = world.realtime
    spawn(0)
        mudhaven_heartbeat_loop()

/proc/mudhaven_heartbeat_loop()
    set waitfor = FALSE

    while(TRUE)
        var/list/report = list(
            "token" = MUDHAVEN_API_TOKEN,
            "status" = "online",
            "players" = clients.len,
            "game_version" = "1.0",
            "round_name" = "Lobby",
            "uptime_seconds" = round((world.realtime - mudhaven_started_at) / 10)
        )

        world.Export(MUDHAVEN_API_URL, report, 0, null, "POST")
        sleep(600)

sleep(600) is one minute at BYOND's normal tick setting. Games that change world.tick_lag should use their existing scheduler to report once per minute without blocking latency-sensitive game work.

Response

Confirm the accepted snapshot

{
  "ok": true,
  "project": "your-project-key",
  "received_at": "2026-08-11T12:00:00+00:00",
  "recommended_interval_seconds": 60,
  "offline_after_seconds": 300,
  "accepted_custom_fields": 0
}

Each accepted report replaces the current standard and custom snapshot. Peak players remain preserved as the current count changes.

Privacy and failure

Validate without exposing players

Never report player names, BYOND keys, IP addresses, chat, save data, email addresses, credentials, or arbitrary metadata. Network failures should not stop the world loop; log only a bounded status and retry at the normal interval.

Review response codes Add weather announcements