Players & retention

ServersPulse tracks every player join and leave event on your server, building a per-player history that includes session times, playtime, platform information, and the domain they connected through.

Player tracking

The Players tab on each server page lists all tracked players with the following data:

Each row represents one unique player per server. A player who plays on multiple of your servers will have separate tracking entries on each.

Session history

Click on a player to view their individual session log. Each session records:

• Join time -- When the player connected
• Leave time -- When the player disconnected (blank if currently online)
• Duration -- Session length in minutes/hours
• Platform -- The client platform for this specific session
• Join domain -- The hostname/IP the player connected through for this session

Sessions are automatically reconciled -- if a player disconnects unexpectedly (server crash, network issue), the session is closed based on the last known activity.

Domain tracking

The first hostname and per-session join domain fields track which domain or IP address players use to connect. This is useful for:

• Acquisition analysis -- See which domain (e.g., play.example.com, hub.example.com) brings in the most players
• Network routing -- Understand how players are distributed across your proxy/hub domains
• Marketing attribution -- If you promote different domains in different places, track which ones drive joins

Hostnames are sanitized and stored without port numbers.

Activity heatmap

The Activity tab shows a 7x24 heatmap of when your server is busy, in the timezone you set under Settings -> Reporting timezone. Pick the timezone your players are in, not the one the machine runs in: a heatmap in UTC puts a European weekend evening peak in whichever cell UTC happens to land it in.

Two metrics are available, and they answer different questions:

They differ for any session that spans an hour boundary. A player who joins at 23:40 and leaves at 01:10 contributes one session to the 23:00 cell, but contributes playtime to 23:00, 00:00 and 01:00 -- twenty, sixty and ten minutes respectively. Use sessions started to see when people arrive, and playtime to see when the server is actually populated.

Every cell is focusable and carries its own reading, so the numbers are reachable by keyboard and by screen reader rather than only through the colour ramp.

Activity groups

Each player is scored on how much they have played recently, and that score places them in a group. The score is deliberately simple and documented here so you can reproduce it, rather than being a curve you have to take on trust.

The activity index

Take the trailing 21 days and split them into three seven-day windows, with playtime measured in hours:

• w0 -- the last 7 days
• w1 -- the 7 days before that
• w2 -- the 7 days before that

The index is:

A = 1.0 x w0 + 0.6 x w1 + 0.3 x w2

The decreasing weights mean a player who stopped playing a fortnight ago still scores above one who was never here, and that a player's score decays smoothly rather than falling off a cliff.

The groups

A player with no activity at all in the last 60 days is in no group. "Inactive" means was here and stopped, which is the population you can still win back; "gone" is not a group.

Movers

The Slipped a tier this week table recomputes every score as it stood seven days ago and compares the groups. Anyone who dropped at least one tier appears, worst fall first. This is the list to act on: a player who has just gone from Regular to Inactive left recently enough to notice they were missed.

Weekly churn alerts

The activity_group_churn notification rule fires once a week when at least threshold players who were Regular or better have become Inactive. It runs on Mondays at 09:00 UTC, after the retention cohorts refresh, and reports through whichever Discord channel or webhook the rule is configured with.

Unlike the metric rules, this one is not a threshold on a live time series -- it is a comparison of two weeks -- so it does not fire from the snapshot stream and does not leave an open incident behind.

New players and the first-session funnel

The New players section of the Activity tab takes every player whose first-ever session on the server started inside the selected range, and asks two questions at once: how long that first visit lasted, and what the server was doing at the moment they arrived.

Each new player is placed in one outcome band by the length of that first session -- under a minute, under five minutes, under half an hour, or half an hour and over. Separately, the TPS reading closest to their join timestamp puts them in one of four server-health bands:

The chart shows what share of each health band went on to stay at least half an hour. If that share falls off as the tick rate falls, the server's performance is costing you new players, and you can see how many.

The comparison sentence above the bars only appears when both the full-rate and struggling bands hold at least 25 new players. Below that a difference between them is as likely to be noise as signal, and a confident-sounding headline would be worse than none.

Where players connect from

Country resolution is off by default and is turned on per server, under Settings -> Feature opt-ins -> Player country.

When it is on, the plugin resolves the joining player's country against a database on your own machine and sends ServersPulse only the resulting two-letter country code. The IP address never leaves your server and is never stored by us.

The ranking on the Activity tab lists countries by sessions, with unique players and playtime alongside. Underneath it states how many sessions could not be placed. That figure is honest coverage, not an error: local and private addresses never resolve, so a network behind a proxy will always show some.

Sessions recorded before you turned the setting on carry no country and are not backfilled.

Playing on more than one server

A player detail page lists the other servers where the same Minecraft account has been seen, under Also plays on. The list is scoped to servers you can already open -- it will never reveal a server you do not have access to, and it excludes servers that are currently over their owner's plan limit.

Agent-reported detail

Some measurements come from the plugin on your server rather than from data ServersPulse derives itself: AFK time, latency, client brand, and time per world. What is available depends on which agent build you run and which server software it runs on.

Where an agent build cannot measure something, the dashboard shows a dash rather than a zero, and hovering or reading it with a screen reader gives the reason. That distinction is deliberate: "nobody was ever AFK" and "this build cannot see AFK time" are different facts, and a zero would assert the first when only the second is true. Update the plugin to fill those in.

The same rule applies to whole sections. A chart whose input the agent cannot measure says so in place of drawing an empty chart, while a chart whose input the agent can measure but which has no data says that the range is empty instead.

Proxy networks

A server registered with a velocity, bungeecord or waterfall platform is a proxy: it runs no world and has no tick rate, so its server page shows the network behind it in place of the usual performance charts. That view lists every backend by how much play it actually held, and every backend-to-backend transfer the proxy performed, busiest first. It is available on the Multi plan.

Retention reports

Retention reports measure how many players return to your server after their first join. Reports are generated daily and break down retention by cohort date and platform.

Cohort model

A cohort is the group of players who first joined on a specific date. Retention is measured at three intervals:

Retention rates are calculated as retained players / cohort size.

Reading retention data

Each retention report row contains:

• Cohort date -- The date this group of players first joined
• Platform -- The client platform (retention is tracked separately per platform)
• Join domain -- The address the cohort first connected through
• Cohort size -- How many new players joined on this date
• D1 / D7 / D30 retained -- Absolute counts of players who returned

For example, if 50 players first joined on March 1 and 20 of them came back within a day, the D1 retention is 40%.

Splitting by join address

The Split by control on the Retention tab switches the cohort dimension between Platform and Join address. The two views cover the same players; they just divide them differently, so the totals always agree.

Splitting by join address is what turns "our D7 is 22%" into something you can act on. If the address you advertise on a voting site retains at 31% and your network hub retains at 9%, those are two different problems with two different fixes.

Only the busiest addresses keep their own row; everything else is pooled into other, so a wildcard DNS record cannot turn one cohort per day into hundreds.

Using retention data

• Compare platforms -- See if Java and Bedrock players retain at different rates
• Compare acquisition sources -- See which advertised address brings players who stay
• Track trends -- Monitor whether retention improves or declines over time
• Evaluate changes -- Compare retention before and after server updates, events, or content additions
• Identify issues -- A sudden drop in D1 retention may indicate a problem with the new-player experience

Retention reports are available on the Retention tab of each server page.

Player sessions overview

The server-level player sessions view shows all recent sessions across all players, giving you a timeline of activity on your server. This is useful for:

• Seeing who was online during an incident
• Understanding player activity patterns throughout the day
• Identifying peak hours and quiet periods

Contributors

Thanks to everyone who keeps this docs area accurate.

bwmp