Live Player Tracking: Show a Verified Online Count on Your Listing

RunePort can show a live, verified player count on your server's listing: a green "143 online" pill on your server card, a players online now stat on your profile page, and a place in the Playable Right Now strip on the RunePort homepage. The number comes straight from your own game server, updated every minute, so players know it is real and current, not a screenshot from launch week.

This guide walks through the whole setup: how the system works, where to find your secret key, how to send a test ping from your desktop, and how to add a permanent one-line scheduled task to your server. Most owners are live within ten minutes.

Why you should enable it

• Players pick active servers. The first question every player has is "is anyone actually playing this?" A live badge answers it before they even click your listing. Servers with no badge just look like an unknown.
• Homepage visibility for free. Every server that is online appears in the Playable Right Now strip at the top of the RunePort homepage, sorted by player count. That placement cannot be bought; it can only be earned by being online.
• Weekly report coverage. The State of RSPS weekly report includes a "Busiest live worlds" section built entirely from this data, including your peak and average players and week-over-week movement.
• It is completely free. No premium tier, no catch. It is one HTTP request per minute from your server.

How it works

The system is a heartbeat. Your game server sends RunePort a tiny HTTP request every 60 seconds containing two things: your secret key and your current player count. That is the entire protocol.

• While pings keep arriving, your listing shows online with the latest count.
• If no ping arrives for 5 minutes, your listing flips to offline. When your server comes back, the badge comes back with it, automatically.
• RunePort keeps one sample per minute for 14 days. That history powers your 24-hour peak (shown when players hover the badge) and the weekly report.
• Only the number is stored. No player names, no IPs, nothing from inside your game.

Step 1: Get your heartbeat key

1. Log in to RunePort and open the Owner Dashboard.
2. Go to the Callbacks tab.
3. Find the Live Players card, sitting right under the Discord settings. It shows your current status, your secret heartbeat key, and a ready-made example command with your key already filled in.
4. Click Copy key.

Step 2: Send a test ping

Before touching your server code, prove the pipeline works from any terminal (replace YOUR_KEY):

curl -s "https://runeport.online/live/heartbeat.php" \
     -d "key=YOUR_KEY" \
     -d "players=42"

A successful ping returns:

{"ok":true,"players":42}

Now open your server's RunePort profile. Within a few seconds you should see "42 players online now" in the stats and a green pill on your card in the listings. Congratulations, the hard part is done. If you stop pinging, the badge will flip to offline after 5 minutes, which is exactly what we will fix next with a permanent scheduled task.

Step 3: Add the heartbeat to your server

Java (works in any RSPS framework)

Add this class to your server and start it once during boot. It uses HttpURLConnection, which works on every Java version RSPS frameworks realistically run, including Java 8.

import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.TimeUnit;

public final class RunePortHeartbeat {

    // Your secret key from the Owner Dashboard -> Callbacks -> Live Players.
    private static final String KEY = "YOUR_KEY";
    private static final String ENDPOINT = "https://runeport.online/live/heartbeat.php";

    private static ScheduledExecutorService scheduler;

    /** Call once when your server finishes booting. */
    public static void start() {
        scheduler = Executors.newSingleThreadScheduledExecutor(r -> {
            Thread t = new Thread(r, "runeport-heartbeat");
            t.setDaemon(true); // never blocks server shutdown
            return t;
        });
        scheduler.scheduleAtFixedRate(RunePortHeartbeat::ping, 5, 60, TimeUnit.SECONDS);
    }

    private static void ping() {
        try {
            // Replace with however YOUR framework counts logged-in players:
            //   World.getPlayers().size()          (most 317/OSRS bases)
            //   PlayerHandler.getPlayerCount()     (older bases)
            int players = World.getPlayers().size();

            String body = "key=" + KEY + "&players=" + players;

            HttpURLConnection conn = (HttpURLConnection) new URL(ENDPOINT).openConnection();
            conn.setRequestMethod("POST");
            conn.setDoOutput(true);
            conn.setConnectTimeout(5000);
            conn.setReadTimeout(5000);
            conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");

            try (OutputStream out = conn.getOutputStream()) {
                out.write(body.getBytes(StandardCharsets.UTF_8));
            }
            conn.getInputStream().close();
        } catch (Exception ignored) {
            // Never let a failed ping affect the game. The next one
            // fires in 60 seconds anyway.
        }
    }

    /** Optional: call during shutdown. */
    public static void stop() {
        if (scheduler != null) {
            scheduler.shutdownNow();
        }
    }
}

Then in your server's startup sequence, after the world is initialised:

RunePortHeartbeat.start();

Three details worth copying even if you write your own version:

• Daemon thread. The heartbeat must never keep your JVM alive or delay a restart.
• Swallow every exception. A network blip, a RunePort deploy, a DNS hiccup: none of it should ever touch your game loop. Missed pings cost nothing; the next one repairs the status.
• Short timeouts. Five seconds is plenty. Never ping with an unbounded timeout from anything that matters.

Alternative: cron job (any VPS, no code changes)

If your player count is available from a website or query port, you can heartbeat from a cron job instead of the game server. For a fixed test value or a count you fetch yourself:

* * * * * curl -s "https://runeport.online/live/heartbeat.php" -d "key=YOUR_KEY" -d "players=$(cat /path/to/playercount.txt)" >/dev/null 2>&1

Anything that can make an HTTP request once a minute works: PHP, Node, Python, a Discord bot, a batch script. The endpoint does not care who sends the ping, only that the key is right.

Step 4: Confirm everything

1. Your server card (homepage and /servers) shows a pulsing green pill: "● N online".
2. Your profile page shows a fifth stat: "N players online now". Hovering the badge shows your 24-hour peak.
3. The homepage strip. While you are online you appear in Playable Right Now, ordered by player count.
4. The Owner Dashboard Live Players card shows "ONLINE · N players" with your last ping time. Use its Check status button any time.

Troubleshooting

• Response is {"ok":false,"error":"Unknown heartbeat key."}: the key is wrong or was rotated. Copy it again from the Owner Dashboard; there is no whitespace in a valid key and it is exactly 64 characters.
• Response is {"ok":false,"error":"Missing players count."}: the players field did not arrive. If you POST JSON, send {"key":"...","players":123} with no nesting.
• Badge keeps flipping to offline: your pings are arriving less often than every 5 minutes. Check that the scheduled task survived a server restart, and that your host allows outbound HTTPS (port 443) to runeport.online.
• The count looks capped: values are clamped between 0 and 50,000. Negative numbers become 0.
• You run multiple worlds: add the counts together and send one total. One server listing, one key, one number.

Frequently asked

Does the player count change my rank? No. Rank Score stays vote-and-activity based. Live counts are displayed proof of life, and they feed the weekly State of RSPS report.

What if my count is low? Should I still enable it? Yes. A verified "8 online" reads as an honest, alive server. No badge reads as unknown, and players increasingly treat unknown as dead. Everyone starts somewhere, and the weekly report highlights growth, not just size.

Can I fake the number? Please don't. Sample history makes inflated counts obvious (perfectly flat 500 players around the clock does not look like a real server), and listings caught sending fabricated counts lose the badge and get flagged for fairness review.

Questions or a framework this guide does not cover? Ask in the RunePort Discord and we will help you wire it up. See also the vote reward callback guide for rewarding players who vote for your server.