Events & commands

Events say what happened, how often, and to how many players. Commands are counted for you; everything else is one line.

What you see

The Events page lists every event with its count in the selected period, the change against the period before, and its reach: the share of all players (or servers, for server events) that have ever done it. Open an event to see it day by day, the values of each of its properties, and how many players or servers did it for the first time each day.

Commands, automatically

Every command your plugin declares in plugin.yml becomes an event when it's used, with no code:

• The first argument counts as a subcommand only when your command's own tab completion offers it for the first argument. So join, leave or setup count, while free text, numbers and player names never become event names.
• Subcommands must be a lowercase word of up to 20 characters (letters, digits, _ and -, starting with a letter). The list of completions is refreshed every hour, up to 50 per command.
• Commands run by a player are player events; from the console or a command block, server events.
• Only commands declared in plugin.yml and run through your executor are wrapped. For commands you register another way, call track in the handler.

Track your own events

Call track where something meaningful happens. It only increments a counter in memory, so it's fine in hot paths.

// Something the server did
analytics.track("arena_created");

// Something a player did: powers player funnels and reach
analytics.track("game_started", player);

// With properties, as key/value pairs
analytics.track("kit_selected", player, "kit", kit.getId());
analytics.track("game_finished", player, "mode", arena.getMode().id(), "result", won ? "win" : "loss");

// A server event with properties
analytics.track("arenas_reloaded", "trigger", "command");

For properties you already have in a map:

Map<String, Object> props = new HashMap<>();
props.put("mode", arena.getMode().id());
props.put("team_size", arena.getTeamSize()); // values are turned into text
analytics.track("game_started", player, props);

Player or server event?

Pass the player whenever a person did it. Player events count unique players, feed player funnels and the reach column. Leave the player out for what the server or its admin does: setup, reloads, scheduled resets. Server events feed server funnels, which start from Plugin installed. More on funnels

Naming rules

• Event names and property keys: lowercase letters, digits and _ . : -, 1 to 48 characters. Anything else is ignored silently, so Game Started is never sent.
• Names starting with $ are reserved and refused by the server.
• Property values can be any text; they're cut at 48 characters. null values are skipped.
• Up to 5 properties per call. With key/value pairs the keys are sorted, and the first 5 in alphabetical order are kept. A trailing key without a value is ignored.

Limits

Tips

• Name events object_verb in the past tense: game_started, shop_opened, reward_claimed.
• Keep property values low-cardinality: a mode, a kit, a result. Never a player name, a world name typed by an admin or a timestamp.
• Track the moment that matters, not every step of it: game_finished with a result property beats three events.
• Track setup milestones (arena_created) as server events: they show how many new servers finish setting up.