Geyser Networking API

[Redned235]

Introduces a networking API to Geyser which can be used in extensions. This supports both sending and listening for plugin messages, and allows Geyser to intercept these, as well as intercepting and sending packets.

Plugin Messages

In order to start sending and listening for plugin messages, you need to tell Geyser which channels to listen for. This can be done by listening on the SessionDefineNetworkChannelsEvent and registering the channel for the connection.

Registering the channel

Example:

public class NetworkExtension implements Extension {
    private final NetworkChannel myChannel = NetworkChannel.of(this, "my_channel");

    @Subscribe
    public void onDefineChannels(SessionDefineNetworkChannelsEvent event) {
        event.register(this.myChannel, MyMessage::new);
    }
}

In the register method, you also need to define the creator of the message that will be sent. This effectively turns the content from a MessageBuffer into your type.

As a recommended principle, this should be a record with two constructors: one creating the object just using its values (an all-args constructor), then one for the MessageBuffer. It should also extend Message.Simple.

Example:

public record MyMessage(String name, int entityId) implements Message.Simple {

    public MyMessage(MessageBuffer buffer) {
        this(buffer.read(DataType.STRING), buffer.read(DataType.INT));
    }

    @Override
    public void encode(MessageBuffer buffer) {
        buffer.write(DataType.STRING, this.name);
        buffer.write(DataType.INT, this.entityId);
    }
}

A MessageBuffer supports both reading and writing, with built-in DataTypes for common values (int, string, long, varint, etc.). Custom DataTypes can easily be added with DataType#of.

Sending the message

Now that your channel and its corresponding message creator is registered, it can now be either listened for, or sent out. This can easily be sent out by fetching the NetworkManager from a GeyserConnection, and running the #send method.

Example:

@Subscribe
public void onSessionJoin(SessionJoinEvent event) {
    GeyserConnection connection = event.connection();
    connection.networkManager().send(this.myChannel, new MyMessage(connection.name(), connection.entities().playerEntity().javaId()), MessageDirection.SERVERBOUND);
}

Note: When sending a message to the server, ensure the direction is SERVERBOUND as that will specify that the server should receive the message. If you were to use CLIENTBOUND for example, that would send it to the client.

Now on your server, you can listen for this message! Here is an example using Bukkit:

this.getServer().getMessenger().registerIncomingPluginChannel(this, "network_extension:my_channel", new PluginMessageListener() {

    @Override
    public void onPluginMessageReceived(@NotNull String s, @NotNull Player player, @NotNull byte[] bytes) {
        System.out.println("Received over channel " + s);
        System.out.println("Content: " + new String(bytes, StandardCharsets.UTF_8));
    }
});

Listening for messages

In some cases, it may be more desirable to do the opposite of what was shown above - sending information to your Geyser extension. This too is supported! In that case, you just need to listen for the ServerReceiveNetworkMessageEvent and ensure that the value coming in is the same message. As an example:

@Subscribe
public void onReceiveMessage(ServerReceiveNetworkMessageEvent event) {
    // Ensure message is clientbound (coming from the server)
    if (event.direction() == MessageDirection.CLIENTBOUND && event.channel().equals(this.myChannel)) {
        MyMessage myMessage = (MyMessage) event.message(); 
        // Your code
    }
}

And for plugin messages, that is about it!

Packets

This API also supports listening for packets. This works alongside the plugin messaging component to it. There are two methods: defining the packet structure using API, or using the Cloudburst API. Both are explained in more detail below.

Packet Structure Using API

When constructing your NetworkChannel, a special method needs to be used: NetworkChannel#packet. This creates a NetworkChannel that is capable of listening for packets.

Example:

private static final NetworkChannel ANIMATE_CHANNEL = NetworkChannel.packet("animate", 44, AnimateMessage.class);

The first parameter is the name of the packet - this is not particularly important and at this point in time can be anything. The following two are very important though: the packet ID and the actual message. These should correspond to real packets in Minecraft: Bedrock Edition. Like above, this should be registered in the SessionDefineNetworkChannelsEvent.

The AnimateMessage on the other hand from the example, is the actual implementation of the animate packet in Bedrock. Here is how that looks:

public record AnimateMessage(int type, long entityId, float rowingTime) implements Message.Packet {

    @Override
    public void encode(@NotNull MessageBuffer buffer) {
        buffer.write(DataType.VAR_INT, this.type);
        buffer.write(DataType.UNSIGNED_VAR_LONG, this.entityId);
        buffer.write(DataType.FLOAT, this.rowingTime);
    }

    public static AnimateMessage decode(@NonNull MessageBuffer buffer) {
        int type = buffer.read(DataType.VAR_INT);
        long entityId = buffer.read(DataType.UNSIGNED_VAR_LONG);
        float rowingTime = (type == 128 || type == 129) ? buffer.read(DataType.FLOAT) : 0.0f;
        return new AnimateMessage(type, entityId, rowingTime);
    }
}

Now that the AnimateMessage has been created, we can now send it:

@Subscribe
public void onSessionJoin(SessionJoinEvent event) {
    event.connection().networkManager().send(ANIMATE_CHANNEL, new AnimateMessage(1, -1, 0f), MessageDirection.SERVERBOUND); // Swing main hand
}

Or if you wanted to listen for other players swinging their arms:

@Subscribe
public void onReceiveMessage(ServerReceiveNetworkMessageEvent event) {
    // Ensure message is originating from the server and not us
    if (event.direction() != MessageDirection.CLIENTBOUND) {
        return;
    }

    if (event.channel().equals(ANIMATE)) {
        AnimateMessage message = (AnimateMessage) event.message();
        if (message.type() == 1) {
            // Swing arm
        }
    }
}

It is also worth noting that the ServerReceiveNetworkMessageEvent is Cancellable, meaning if you wanted to intercept a packet and cancel it outright, simply run ServerReceiveNetworkMessageEvent#setCancelled(true) and the packet will be cancelled.

Packet Structure Using Cloudburst Protocol Library.

While the first example required a bit more manual work, in some cases that may be more desired for fine-turning the entire process. However, it is also possible to simply just use the raw packet objects themselves as provided by the Cloudburst Protocol Library.

In addition to depending on the Geyser API, depending on Cloudburst Protocol too is all that is required here - no need to rely on any Geyser internals!

Creating the channel is nearly identical as above, except rather than a custom AnimateMessage, just use the packet directly like so:

private static final NetworkChannel ANIMATE_CHANNEL = NetworkChannel.packet("animate", 44, AnimatePacket.class);

When registering the channel though, it's a tad different. This can be done like so:

event.register(ANIMATE_CHANNEL, Message.Packet.of(AnimatePacket::new));

And sending can be done like so:

AnimatePacket packet = new AnimatePacket();
packet.setAction(AnimatePacket.Action.SWING_ARM);
packet.setRowingTime(0.0f);

event.connection().networkManager().send(ANIMATE_CHANNEL, Message.Packet.of(packet), MessageDirection.CLIENTBOUND);

However, if you want to listen for one of these, it can be a tad more complicated. But, it can be done like so:

@Subscribe
public void onReceiveMessage(ServerReceiveNetworkMessageEvent event) {
    if (event.direction() != MessageDirection.CLIENTBOUND) {
        return;
    }

    if (event.channel().equals(ANIMATE_CHANNEL) && event.message() instanceof Message.PacketWrapped<?> wrapped && wrapped.packet() instanceof AnimatePacket packet) {
        AnimatePacket packet = (AnimatePacket) wrapped.packet();
        // Handle the animate packet
    }
}

Note that this is only an initial draft and subject to change! Testing and feedback are more than welcome.

A gist of what was covered above with slightly more can be found here: https://gist.github.com/Redned235/3cf05b62290fa9eec70d8b4f3fa22f67

[onebeastchris]

This looks very promising! Left some notes. A few more things that don't fit anywhere:

• it might be worth to separate listening / receiving packet listeners? This could be used to avoid extra processing for packets that are sent both ways (where one is only interested in one direction)
• Currently; some bedrock packet (de)serializers are modified by Geyser. This would result in incorrect values for some packets... do we want to note that / have a mechanism to disable that?

[onebeastchris]

let's make this an interface + geyser impl?

[onebeastchris]

Maybe worth marking this as a functional interface?

[onebeastchris]

Suggested change

	* This channel is used for communication of packets between the server and client.
	* This channel is used for listening to communication over packets between the server and client, and can be used to send or receive packets.

[onebeastchris]

missing javadocs

[onebeastchris]

This assumes that all sent packets are strictly Bedrock edition packets; which could pose an issue if we at some point want to allow the same for Java edition packets :(

[Redned235]

I feel like supporting Java packets here would end up being relatively niche. Since we are only dealing with Bedrock users, it makes the most sense that only Bedrock packets would work here when being sent to the client.

That being said, if we wanted to support one or the other, it would be rather challenging to distinguish them unless we want to make this declared in the network channel. Currently, unless you are using MCPL or Cloudburst and wrapping the packet, only custom Bedrock packet messages are supported. Having both may cause some confusion, but I am open to ideas.

[onebeastchris]

could also be solved using an instanceof check - is there a reason for explicitly forcing declaring whether a channel is a packet channel opposed to instanceof checking?

[Redned235]

Small optimization - checking a boolean is cheaper than an instanceof, especially with hot code where I could see people calling this method.

[onebeastchris]

Another thing that came up recently is whether we'd allow forwarding packets to a backend server - even without an extension present. This could be combined with this PR, assuming we'd want to do that.. thoughts?

[dima-dencep]

😢😢😢😢