Activity tracking

What it measures

A single Luau script runs on your game servers. It watches everyone in the server and keeps three running totals per visit: wall-clock minutes since they joined, chat messages they sent, and how much of that time they were idle. Every five minutes, and once more as the server shuts down, it posts those totals to Rostack.

The numbers come from your own servers rather than from anything Rostack infers. Nothing here polls Roblox to guess who is online: if a server reported it, it happened, and if no server has ever reported, the Activity page says it is not connected instead of showing a convincing zero.

From those visits Rostack derives what the rest of the product reads: minutes and active minutes, chat counts, how many distinct game servers somebody joined, and how many days in a window they were seen at all.

Setup

1. 1

   Create a workspace API key

   In your workspace, open Ranking and create an API key. One key per game is enough. It is shown once and stored only as a hash, so copy it straight into the script.

   Treat it like a password

   Anyone holding the key can post activity for your workspace. Keep it out of client scripts and out of anything you share.
2. 2

   Turn on HTTP requests

   In Studio: Game Settings, then Security, then Allow HTTP Requests. Without it the script cannot reach Rostack, and it says so in the output window rather than failing quietly.

3. 3

   Add the module to ServerScriptService

   Download rostack.app/rostack-activity.lua, which the Activity page in your workspace also links, and paste its contents into a new Script in ServerScriptService. It has to be a Script: a LocalScript runs on the client, and the module switches itself off if it finds itself there.

4. 4

   Paste your key into CONFIG.API_KEY

   The placeholder at the top of the file is rsk_live_PASTE_YOUR_KEY_HERE. The script refuses to start while that is still there, so a forgotten key is one warning in the output window rather than a week of missing minutes.

5. 5

   Publish the place

   In Studio, game.PlaceId and game.GameId are both 0 until the place has been published, and the script sends nothing without them. Publish, then join. The first report lands within five minutes.

The endpoint

POST https://rostack.app/api/v1/activity
Authorization: Bearer rsk_live_…
Content-Type: application/json

The body describes one server and the visits it is reporting:

Each entry in that array is one visit to this server:

Timestamps are epoch seconds, which is what os.time() returns. Formatted dates are rejected.

curl -X POST https://rostack.app/api/v1/activity \
  -H "Authorization: Bearer rsk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "placeId": 4922741943,
    "universeId": 1719029934,
    "jobId": "e6f1c0d2-9b64-4f0a-8f2b-1d5a7c33ab10",
    "sessions": [
      {
        "robloxUserId": 3961562630,
        "username": "xFirmastic",
        "startedAt": 1757318400,
        "endedAt": null,
        "minutes": 42,
        "chats": 17,
        "afkMinutes": 5,
        "present": true
      }
    ]
  }'

Why a retry is safe

This is the most important thing on the page. Every report carries the cumulative totals for the whole visit, never the change since the last report, and each visit is written at a document id the reporting server can reproduce from what it already knows. Sending the same report ten times writes the same document ten times.

document id   {robloxUserId}_{jobId}_{startedAt}
example       3961562630_e6f1c0d2-9b64-…-ab10_1757318400

report 1      minutes 42   ->  written
report 2      minutes 42   ->  unchanged, nothing written
report 3      minutes 47   ->  written, 47 replaces 42
retry of 2    minutes 42   ->  47 is kept, the larger of the two

Where a stored counter and an incoming one disagree, the larger wins. Counters within one visit only ever rise, so taking the maximum is idempotent, meaning a duplicate changes nothing, and order independent, meaning a retry delayed behind a newer report cannot walk somebody's minutes backwards. The day totals underneath obey the same rule: they are recomputed from the visits rather than added to, so replaying a week of reports produces the same numbers as playing them once.

Who is recorded

The module reports everybody in the server. Rostack keeps activity only for people who have a staff record in the workspace, which means they hold one of the Roblox ranks you marked as staff on the Roles page. A retired staff record is treated the same as a stranger.

Everyone else is dropped before anything is written, and nothing about them is stored. A public game is full of people your group has no employment relationship with, and keeping their names and play time would be collecting personal data on strangers for no purpose anybody asked for.

AFK time

The module takes a sample every 15 seconds. Somebody who has moved more than three studs since the last sample, or sent a chat message, counts as active. Roblox also tells the server when a player's own client has seen no input for a while, and the module uses that to backdate their last sign of life rather than waiting for the movement check to notice. Five minutes with no sign of life starts accumulating idle time from that point on, sample by sample, so a person who drifts in and out of idle is measured rather than written off from the first moment they stood still.

Idle time is reported separately and is never subtracted from the total. minutes is wall-clock time in the server and includes the AFK part; active minutes are simply minutes - afkMinutes, and Rostack recomputes that rather than trusting a stored copy. Both are kept because a community decides for itself whether idle time is paid, and a payroll rule reading the wrong one is a money bug. Payroll rules choose between them with a countAfk switch, which is off by default.

Reading the response

{
  "ok": true,
  "accepted": 1,
  "unchanged": 0,
  "ignored": 12,
  "days": 1
}

A steady stream of unchanged is healthy. It means people are in the server and their totals have not crossed a minute boundary yet. Failures carry a stable error code with a human message: missing_key or unauthorized at 401, invalid_request at 400 with the expected shape attached, and internal at 500. The module gives up on 400, 401 and 403, because a malformed body or a revoked key fails identically five seconds later, and retries anything else after 2, 5 and 15 seconds before leaving it to the next cycle.

Honest limits