Track Player Events

Player events are the foundation of understanding your server’s activity. This guide shows you how to track the most common player interactions using Hoglin.

1. Set up your event listener class

   Create a class to handle all your player events:

   Kotlin

   class PlayerEventListener(private val analytics: Hoglin) : Listener {
       // Event handlers will go here
   }

   Java

   public class PlayerEventListener implements Listener {
       private final Hoglin analytics;
   
       public PlayerEventListener(Hoglin analytics) {
           this.analytics = analytics;
       }
   
       // Event handlers will go here
   }

2. Register your listener

   Don’t forget to register your event listener in your plugin’s onEnable():

   Kotlin

   override fun onEnable() {
       val analytics = Hoglin.Builder("<your server key>")
           .autoFlushInterval(5_000L)
           .maxBatchSize(50)
           .build()
   
       server.pluginManager.registerEvents(
           PlayerEventListener(analytics),
           this
       )
   }

   Java

   @Override
   public void onEnable() {
       Hoglin analytics = new Hoglin.Builder("<your server key>")
           .autoFlushInterval(5_000L)
           .maxBatchSize(50)
           .build();
   
       getServer().getPluginManager().registerEvents(
           new PlayerEventListener(analytics),
           this
       );
   }

Common Player Events

Player Joins

Track when players join your server:

Kotlin

@EventHandler
fun onPlayerJoin(event: PlayerJoinEvent) {
    analytics.track("player_join", mapOf(
        "player_uuid" to event.player.uniqueId,
        "first_join" to !event.player.hasPlayedBefore()
    ))
}

Java

@EventHandler
public void onPlayerJoin(PlayerJoinEvent event) {
    Map<String, Object> properties = new HashMap<>();
    properties.put("player_uuid", event.getPlayer().getUniqueId());
    properties.put("first_join", !event.getPlayer().hasPlayedBefore());
    analytics.track("player_join", properties);
}

Player Leaves

Track when players disconnect:

Kotlin

@EventHandler
fun onPlayerQuit(event: PlayerQuitEvent) {
    analytics.track("player_quit", mapOf(
        "player_uuid" to event.player.uniqueId
    ))
}

Java

@EventHandler
public void onPlayerQuit(PlayerQuitEvent event) {
    Map<String, Object> properties = new HashMap<>();
    properties.put("player_uuid", event.getPlayer().getUniqueId());
    analytics.track("player_quit", properties);
}

Chat Messages

Track player chat activity:

Kotlin

@EventHandler
fun onPlayerChat(event: AsyncPlayerChatEvent) {
    analytics.track("player_chat", mapOf(
        "player_uuid" to event.player.uniqueId,
    ))
}

Java

@EventHandler
public void onPlayerChat(AsyncPlayerChatEvent event) {
    Map<String, Object> properties = new HashMap<>();
    properties.put("player_uuid", event.getPlayer().getUniqueId());
    analytics.track("player_chat", properties);
}

Player Deaths

Track player deaths and their causes:

Kotlin

@EventHandler
fun onPlayerDeath(event: PlayerDeathEvent) {
    analytics.track("player_death", mapOf(
        "player_uuid" to event.entity.uniqueId,
        "death_cause" to event.entity.lastDamageCause?.cause?.name,
    ))
}

Java

@EventHandler
public void onPlayerDeath(PlayerDeathEvent event) {
    Map<String, Object> properties = new HashMap<>();
    properties.put("player_uuid", event.getEntity().getUniqueId());
    properties.put("death_cause",
        event.getEntity().getLastDamageCause().getCause().name());

    analytics.track("player_death", properties);
}

Player Commands

Track command usage:

Kotlin

@EventHandler
fun onPlayerCommand(event: PlayerCommandPreprocessEvent) {
    val command = event.message.split(" ")[0].removePrefix("/")

    analytics.track("player_command", mapOf(
        "player_uuid" to event.player.uniqueId,
        "command" to command,
        "arg_count" to event.message.split(" ").size - 1,
        "is_op" to event.player.isOp
    ))
}

Java

@EventHandler
public void onPlayerCommand(PlayerCommandPreprocessEvent event) {
    String command = event.getMessage().split(" ")[0].substring(1);

    Map<String, Object> properties = new HashMap<>();
    properties.put("player_uuid", event.getPlayer().getUniqueId());
    properties.put("command", command);
    properties.put("arg_count", event.getMessage().split(" ").length - 1);
    properties.put("is_op", event.getPlayer().isOp());

    analytics.track("player_command", properties);
}

_{Note: You can also detect specific commands and send custom events that way. Think /gamemode or /ban.}

Best Practices

Tip

Event Naming: Use consistent naming like player_join, player_quit, player_death to make dashboard filtering easier.

Include Essential Data: Include relevant metadata but avoid excessive properties that could impact performance.

Recommended Properties

For all player events, consider including:

• player_uuid - The UUID of the player, the Hoglin dashboard uses this to automatically display usernames.
• world - Which world the event occurred in

What’s Next?

Now that you’re tracking player events, you might want to:

View your analytics dashboard

Learn about the Explore page