How to Track Custom Minecraft Plugin Events with Analytics

While default server metrics (TPS, player count, connections) provide a solid baseline for server operations, they don’t capture the unique gameplay features that make your Minecraft server stand out. If you have custom economy plugins, unique questlines, faction territory captures, or custom mini-games, you need specialized telemetry.

Fortunately, ShardAnalytics allows you to send Custom Events directly from your Java plugins and server code. In this guide, we will cover how custom event ingestion works, show you examples of what events you should track, and explain how the system infers, curates, and registers your custom data onto the Semantic Layer for real-time querying.

1. Beyond Default Analytics: Why Custom Events Matter

Default analytics are great for general monitoring, but they are blind to your custom business logic. For example:

• You can see that player count drops at 8:00 PM, but you can’t see if that drop was caused by players getting frustrated by a specific custom boss fight.
• You know your shop is bringing in virtual currency, but you don’t know which specific shop category or item is the most popular.

By sending custom events to ShardAnalytics, you bridge the gap between technical server health and game design analytics. This enables you to build custom dashboards, map player progression funnels, and make decisions based on empirical gameplay data.

2. What Is a Custom Event?

A custom event is a data packet sent to ShardAnalytics when a specific action occurs in-game. Each event consists of:

1. Event Name: A unique identifier (e.g. quest_completed, crate_opened).
2. Telemetry Context: Automatically attached fields like player_uuid, server_id, world, and timestamp.
3. Event Payload: A flat JSON object containing custom properties (e.g., the quest ID, item rarity, or purchase cost).

To ensure high-performance querying, event payloads should be kept flat. Avoid nested JSON structures or complex arrays when sending custom events.

3. High-Value Custom Events to Track

Depending on your server’s game mode, here are the most valuable events you should instrument in your plugins:

Onboarding & Progression

• tutorial_step_completed: Track fields like step_id and time_taken to find where new players get stuck or log off during onboarding.
• quest_completed: Track quest_id, reward_type, and difficulty to map player progression speed.

Server Economy & Monetization

• crate_opened: Track crate_type, key_source (store purchase vs. in-game reward), and reward_id to audit your server’s drop rates.
• shop_purchase: Track item_id, category, price, and currency_type to see what virtual goods drive your economy.

Gameplay & Competition

• boss_killed: Track boss_type, party_size, and time_to_kill to verify combat balance.
• region_capture: On Factions or Towny servers, track region_id, capturing_faction, and duration to monitor active gameplay.
• island_upgrade: On Skyblock servers, track island_level, upgrade_type, and cost.
• minigame_round_finished: Track game_mode, map_name, and winner_uuid.

4. The Data Catalog: Automatic Event Discovery

When your custom plugin sends a new event type to the ShardAnalytics ingestion endpoint, you do not need to pre-register the schema.

[ Custom Plugin Event ] ──> [ Ingestion Endpoint ] ──> [ Data Catalog Auto-Discovery ]
                                                                   │
                                                                   ▼
                                                       [ Schema Preview & Inference ]
                                                                   │
                                                                   ▼
                                                       [ Semantic Layer Dimensions ]

The ShardAnalytics Data Catalog automatically discovers the new event name and starts indexing the incoming stream. It records the first time the event was seen and keeps a live log of incoming payloads, allowing developers to start tracking new metrics instantly.

5. Schema Preview, Inference, and Curation

Once the Data Catalog discovers a new event type, it appears in your dashboard under the Data Catalog -> Schema Preview tab.

Here, ShardAnalytics parses sample payloads and infers:

• Data Types: The system automatically identifies properties as strings, numbers, booleans, or arrays.
• Cardinality: It evaluates how many unique values a property has. For example, a rarity field (common, rare, legendary) has low cardinality, while a quest_id might have medium cardinality, and a coordinate has high cardinality.

You can then curate these fields—giving them human-readable names, assigning units of measurement, or marking sensitive data fields.

6. Semantic Layer Registration

Curation does not just make your schema look neat; it registers your custom properties on the Semantic Layer.

• Dimensions: Categorical fields (like item_id, world_name, or rarity) are registered as Dimensions. These are used to group, filter, and segment your data.
• Measures: Numeric fields (like purchase_price or seconds_to_complete) are registered as Measures. These are used to calculate aggregates like sums, averages, minimums, maximums, and percentiles.

Once registered, these custom dimensions and measures are immediately available in the custom dashboard widget builder and query interfaces. You can instantly drag a new quest_id dimension onto a chart to see quest popularity, or sum purchase_price to track economic velocity.

7. Common Instrumenting Mistakes to Avoid

When setting up custom event tracking, avoid these pitfalls:

1. Tracking Raw Coordinates in Event Names: Do not name your events dynamically (e.g. block_break_102_64_205). Keep event names static (e.g. block_broken) and put coordinate context inside the payload.
2. Inconsistent Field Naming: Ensure all plugins use the same casing for properties (e.g., don’t use questId in one plugin and quest_id in another). Consistent names make cross-event analysis simple.
3. Missing Context: Always include key metadata like the world, server instance, or player state. A crate_opened event is much more valuable if it includes whether the player was in the Lobby or a Survival world.

8. Start Instrumenting Your Server Today

Take control of your server’s gameplay data. ShardAnalytics provides a simple Java SDK and REST API to send custom telemetry events, curate schemas, and build custom dashboards in minutes.

• Automatic Schema Inference: Send payloads and watch ShardAnalytics parse and register data types.
• Semantic Layer Integration: Turn raw JSON fields into queryable dimensions and measures instantly.
• Developer-First SDK: Native support for Paper, Spigot, and Folia connectors.

Start Tracking Custom Events with ShardAnalytics.