Skip to content

Minecraft plugin

The first-party Tickr plugin pushes player sessions, custom events and health heartbeats from your Minecraft server to the Tickr API. Outbound HTTPS only: no inbound ports, no database, and nothing ever runs on the main server thread.

Latest release: 1.0.1

DownloadTarget
tickr-paper-1.0.1.jarPaper / Spigot 1.21.x (Java 21)
tickr-velocity-1.0.1.jarVelocity 3.3.x proxy

All dependencies are shaded into both jars, so there are no runtime dependencies to install.

Installation

  1. Drop the jar into your server’s plugins/ folder (Paper) or the Velocity plugins/ folder.
  2. Start the server once and the default config is created.
  3. Paste your server key from the Tickr dashboard (Server → Settings → API key) into the config and restart.

The plugin stays completely idle until an API key is configured.

Configuration

Paper / Spigot: plugins/Tickr/config.yml

KeyDefaultDescription
api-key""Your Tickr server key. Required.
api-basehttps://api.tickr.ggAPI endpoint; only change when self-hosting.
flush-interval-seconds5Flush period for the batching queue (1 to 60).
track-worldstrueRecord world switches for per-world playtime.

Velocity: plugins/tickr/config.properties

Same api-key, api-base and flush-interval-seconds keys. On Velocity, sessions are tracked at the proxy level and backend server switches are recorded with world set to the backend server name, which is ideal for networks.

What gets sent

  • Sessions: join/leave (and world/server switches) with player UUID, username, world and timestamp. Batched (max 50/request), flushed every 5 s, retried with exponential backoff on 429/5xx/network errors, bounded in-memory buffer (drop-oldest).
  • Heartbeats: every 30 s with current TPS (Paper only; Velocity sends no TPS). On a clean stop, a final cleanShutdown: true heartbeat is sent and the queue is flushed, so crash detection on the dashboard stays accurate.
  • Custom events: via the developer API below. Premium feature.

Developer API (Paper)

Third-party plugins can track custom events through the static API. Add the Tickr jar to your compileOnly classpath and declare softdepend: [Tickr] in your plugin.yml:

import gg.tickr.paper.TickrApi;
import java.util.Map;

// Anywhere in your plugin (main thread is fine — the call never blocks):
TickrApi.track("bedwars_win", "minigame", player, Map.of("map", "lighthouse"));

// Optional numeric value (e.g. economy amounts):
TickrApi.track("coins_spent", "economy", player, 249.99, Map.of("shop", "spawn"));

Pass null instead of a Player for server-level events.

Premium required: per-player custom event analytics needs a paid Tickr plan. On the Free plan the built-in session tracking and heartbeats work fully, but TickrApi.track(...) calls are dropped (with a one-time warning per event name). The license is re-checked against the API every 10 minutes, so upgrading takes effect without a restart.

Next steps