Tracking

Record player sessions, replay them with particles and draw them on BlueMap.

Freev0.11World & building

RequiresTypeWriter0.9PacketEventsBlueMapoptional

DownloadSource codeSupport

Overview

Tracking records the position of every player at a regular interval. Each time a player joins, a new session starts, and the extension adds a point (coordinates, world and time) to it every few seconds until the player leaves. Sessions are saved in an artifact.

Admins can then inspect a session. The path is replayed as an animated trail of dust particles around the admin, and, if you use BlueMap, drawn on the web map as a line with a marker on every point. It is a good tool to understand how players move through a build, where they get lost, or to review a suspicious session.

Features

• Session recording — one session per player per login, with coordinates, world and timestamp.
• Configurable interval — one point every pointIntervalSeconds seconds, 20 by default.
• In-game replay — an animated particle trail that only the inspecting admin sees.
• BlueMap display — a path line in a colour taken from the player, and optional point markers.
• Persistent storage — sessions are written to a TypeWriter artifact a few seconds after each change.
• Bounded size — at most 10,000 points are kept per session.
• Folia-safe — the recording and particle loops use region-safe schedulers.

Installation

1. Install PacketEvents, which TypeWriter already requires. The particle trail is sent with it.
2. Optional: install BlueMap to see sessions on the web map.
3. Put the Tracking JAR in plugins/Typewriter/extensions/ and restart the server.

Getting started

1. In the TypeWriter web panel, open a manifest page and add a Tracking Artifact. Keep its artifactId (the default is tracking_storage).
2. Add a Tracking Manifest and link the artifact in storage. Without a linked artifact, nothing is recorded.
3. Set pointIntervalSeconds (for example 10) and check that trackingEnabled is on.
4. Publish. Players who join from now on get a session. Players who were already online when you published do not have one until they reconnect.
5. After a while, run /tracking sessions <player> to list the session ids of a player.
6. Run /tracking inspect <player> <session> to replay a session. With BlueMap installed, the path also appears on the map.
7. Run /tracking with no argument to stop the inspection.

Privacy

Tracking stores the exact coordinates of your players, without an expiry. Mention it in your rules where your local law requires it, and clear the artifact file when you no longer need the data.

How it works

Session ids are numbers handed out in order across all players (1, 2, 3...), not per player. A session ends when the player quits.

Commands

The command is a standard server command registered as /tracking (also /typewriter:tracking), not a sub-command of /typewriter. It can only be used by players and needs typewriter.tracking.inspect.

Command	Description
/tracking sessions <player>	List the session ids recorded for a player.
/tracking inspect <player>	List the session ids of a player.
/tracking inspect <player> <session>	Start inspecting a session: particle trail for you and, if enabled, BlueMap markers.
/tracking	Stop your inspection and remove its BlueMap markers.

You can inspect players who are offline, as long as their name is known to the server.

Permissions

Permission	Grants
typewriter.tracking.inspect	Every /tracking command.

Configuration

All settings are in the Tracking Manifest entry. Only the first manifest found is used, and changes are picked up within a few seconds.

• trackingEnabled turns recording on or off. Turning it off stops adding points. New sessions are only created for players who join while it is on.
• blueMapEnabled, showBlueMapPoints and showBlueMapPath control what is drawn on BlueMap. If both show options are off, nothing is drawn.
• The trail is drawn only for segments within about 30 blocks of the admin, in the world where the admin is.

Entries

2 entries, generated from the extension source.

Artifacts1

• Tracking ArtifactStores player tracking sessions and points

Manifests1

• Tracking ManifestMaster configuration for Player Tracking

Troubleshooting

No session is recorded. The manifest must exist, have trackingEnabled on and a storage artifact linked. Sessions start when a player joins, so players who were online before you published need to reconnect.

/tracking inspect says "No tracking sessions found". The player has no recorded session yet, or the name is wrong. Run /tracking sessions <player>. Sessions need at least one point to be useful: the first point is recorded after pointIntervalSeconds.

The particle trail is invisible. You need at least 2 points in the world you are standing in, and you must be within about 30 blocks of the path. The trail is only visible to the admin who runs the inspection.

Nothing shows on BlueMap. BlueMap must be installed and enabled, blueMapEnabled must be on with at least one of the show options, and the world of the points must be a world known to BlueMap. Markers are removed when you run /tracking.

A session stops growing. A session keeps at most 10,000 points. At the default interval, that is more than 55 hours of play.

Data disappeared after a crash. Data is saved 5 seconds after the last change and on unload. A crash within that window can lose the latest points.