Packet Listeners - rodrigoo-r/Harmony GitHub Wiki

Warning

This feature requires ProtocolLib.

Explanation

Harmony includes a built-in packet listening API for Client and Server bound packets. If you don't want to use this API, you can implement your own API using the ProtocolLib API.

Setup

To setup it, you'll need to add ProtocolLib into your project. To do so, you'll need to modify your plugin.yml file located at the resources directoy.

Make sure you have a depend field and inside is ProtocolLib

depend:
  - ProtocolLib
  # If you require any other stuff, you can put it here as well

After that, you need to add ProtocolLib as a library into your project. To do so:

1. If you're using Gradle

Locate your build.gradle file at the root directoy of your project and locate dependencies into your file. If you don't have any yet, add them. Your file must contain this:

Important

Replace Version with the latest version of ProtocolLib. You can find the latest version at their repository

dependencies {
    // Other stuff here
    // IMPORTANT: Use "compileOnly" instead of "implementation"
    // this way you don't increase the size of your plugin JAR
    // anyways if the server has ProtocolLib installed, the library will
    // be available at runtime 
    compileOnly 'com.comphenix.protocol:ProtocolLib:Version'
}

2. If you're using Maven

Locate your pom.xml file at the root directory of your project and locate <dependencies> into your file. If you don't have any yet, add them. Your file must contain this:

<dependencies>
    <!-- Other stuff here -->
    <!-- IMPORTANT: Use "<scope>provided</scope>" -->
    <!-- this way you don't increase the size of your plugin JAR -->
    <!-- Deanyways if the server has ProtocolLib installed, the library will -->
    <!-- be available at runtime -->
    <dependency>
        <groupId>com.comphenix.protocol</groupId>
        <artifactId>ProtocolLib</artifactId>
        <version>Version</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Usage

Inside your plugin class, there's a method named initPacketMode() that returns a RegisteredPacketMode instance.

You can add and remove packet listeners using the ProtocolLib API with this mode. Example:

public final class Example extends BackendPlugin {

    @Override
    public void whenInitialize() {
        RegisteredPacketMode packetMode = initPacketMode();

        packetMode.addStandardListener(new a());
    }

    @Override
    public void whenUnloaded() {
        // Plugin shutdown logic
    }

}

public class a extends StandardPacketListener {

    public a() {
        super(
                // You can add ListenerPriority here
                // ListenerPriority.HIGHEST
                // If you don't specify any priority, it will be set to NORMAL
                PacketType.Play.Client.KEEP_ALIVE
                // Any other stuff you need
        );
    }

    @Override
    public void whenClientBoundFired(PacketEvent event) {
        // This is the same as override onPacketReceiving
        // Do something with the packet
    }

    @Override
    public void whenServerBoundFired(PacketEvent event) {
        // This is the same as override onPacketSending
        // Do something with the packet
    }

}

Using the Server and Client Handlers

You can use the alternative packet listening API provided by Harmony. It's separated on:

Server Handler - Listens for Server sent/Client bound packets
Client Handller - Listens for Client sent/Server bound packets

Example:

public final class Example extends BackendPlugin {

    @Override
    public void whenInitialize() {
        // You just need to instance the class
        // The listener is automatically registered
        new a();
    }

    @Override
    public void whenUnloaded() {
        // Plugin shutdown logic
    }

}

public class a extends StandardServerHandler {

    @Override
    public void whenServerHandleSystemChat(PacketEvent event) {
        // You can do whatever you want
        // This packet will be of SYSTEM_CHAT type
    }

}

The logic here is very simple:

The server handles the packet -> "whenServerHandle"
The packet type you're listening -> SYSTEM_CHAT -> "SystemChat"

Result: "whenServerHandleSystemChat"

The same logic applies to the client handler:

public class a extends StandardClientHandler {

    @Override
    public void whenClientHandleChat(PacketEvent event) {
        // You can do whatever you want
        // This packet will be of CHAT client packet
    }

}