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. Firstly, we will go over how to send a custom message.

Registering the channel

Example:

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

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

In the define 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. Then calling register will actually register it into the network manager.

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 Network from a GeyserConnection, and running the #send method.

Example:

@Subscribe
public void onSessionJoin(SessionJoinEvent event) {
    GeyserConnection connection = event.connection();
    connection.network().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 from a server. This too is supported! In that case, when registering the channel, you will need to register a clientbound handler inside your channel definition.

As an example:

@Subscribe
public void onDefineChannels(SessionDefineNetworkChannelsEvent event) {
    event.define(this.myChannel, MyMessage::new)
            .clientbound(message -> {
                String name = message.name()
                // ...
                return MessageHandler.State.HANDLED; // Indicates this handler handled the message
            })
            .register();
}

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 (and class) needs to be used: PacketChannel#java, orPacketChannel#bedrock. This creates a NetworkChannel that is capable of handling packets for either of the two platforms.

Example:

private final NetworkChannel animateChannel = PacketChannel.bedrock(this, 44, AnimateMessage.class);

It is important to understand that these only work in Extensions. The this seen in the example represents an Extension instance, assuming the NetworkChannel is constructed in the extension.

The following two parameters are also quite important: the packet ID and the actual message. These should correspond to real packets in the corresponding platform. Like above, this should be registered in the SessionDefineNetworkChannelsEvent in the same way.

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().network().send(this.animateChannel, 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 onDefineChannels(SessionDefineNetworkChannelsEvent event) {
    event.define(this.animateChannel, AnimateMessage::decode)
            .clientbound(message -> {
                if (message.type() == 1) { // Swing arm
                    System.out.println("Entity " + message.entityId() + " swung their arm!");
                }
                    
                return MessageHandler.State.UNHANDLED;
            })
            .register();
}

It is also worth noting that the MessageHandler.State controls the behavior of the packet once intercepted, meaning if you return UNHANDLED, the message will still make it back to the client. Additionally, returning HANDLED will cause the client to never receive the packet.

Important Note for Registering Java Packets

When registering packets for Java, it is a hard requirement that the ProtocolState also be specified. This is because in Java Edition, there are multiple protocol states in which packet IDs differ, or don't exist at all (i.e. login packets do not exist in the game state).

To specify the protocol state, simply call protocolState after defining the packet in SessionDefineNetworkChannelsEvent and set the state it belongs to. An example is provided below:

@Subscribe
public void onDefineChannels(SessionDefineNetworkChannelsEvent event) {
    event.define(this.animateChannel, ClientboundAnimateMessage::decode)
            .protocolState(ProtocolState.GAME)
            .clientbound(message -> ...)
            .register();
}

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 animateChannel = PacketChannel.bedrock(this, 44, AnimatePacket.class);

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

event.define(this.animateChannel, Message.Packet.of(AnimatePacket::new)).register();

And sending can be done like so:

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

event.connection().network().send(this.animateChannel, Message.Packet.of(packet), MessageDirection.CLIENTBOUND);

However, if you want to listen for one of these, the process is very similar as earlier, except you need to obtain the packet from the message (as opposed to it being the message), like so:

@Subscribe
public void onDefineChannels(SessionDefineNetworkChannelsEvent event) {
    event.define(this.animateChannel, Message.Packet.of(AnimatePacket::new))
            .clientbound(message -> {
                AnimatePacket packet = message.packet();
                if (packet.getAction() == AnimatePacket.Action.SWING_ARM) {
                    System.out.println("Entity " + packet.getRuntimeEntityId() + " swung their arm!");
                }
                return MessageHandler.State.HANDLED;
            })
            .register();
}

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]

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]

😢😢😢😢

[Copilot]

Pull Request Overview

This PR introduces a comprehensive networking API for Geyser that enables extensions to send and listen for plugin messages, as well as intercept and send packets. The API provides a flexible event-driven architecture with support for message priorities, pipeline tags, and both custom and Cloudburst protocol-based packet handling.

Key Changes

• Adds networking API interfaces and implementations for plugin messages and packet handling
• Introduces event system for registering network channels with configurable handlers and priorities
• Provides message encoding/decoding infrastructure with built-in and custom data types

Reviewed Changes

Copilot reviewed 44 out of 44 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
api/src/main/java/org/geysermc/geyser/api/event/bedrock/SessionDefineNetworkChannelsEvent.java	Defines event for registering network channels with builder pattern for handlers
api/src/main/java/org/geysermc/geyser/api/network/*.java	Core networking API interfaces (NetworkChannel, NetworkManager, MessageDirection)
api/src/main/java/org/geysermc/geyser/api/network/message/*.java	Message handling infrastructure (Message, MessageBuffer, MessageCodec, DataType, handlers)
core/src/main/java/org/geysermc/geyser/network/*.java	Implementation of network channels and manager with packet/message handling
core/src/main/java/org/geysermc/geyser/network/message/*.java	ByteBuf-based message buffer and codec implementations
core/src/main/java/org/geysermc/geyser/session/UpstreamSession.java	Integration of network manager into packet sending flow
core/src/main/java/org/geysermc/geyser/translator/protocol/java/*.java	Plugin message registration and handling for custom payloads
core/src/test/java/org/geysermc/geyser/network/MessageRegistrationOrderTest.java	Tests for message handler priority and pipeline ordering
core/src/test/java/org/geysermc/geyser/util/*.java	Refactored test utilities to common util package

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[onebeastchris]

Might be neat to have our own exception type in the API?

[Redned235]

What would the usecase be?

[onebeastchris]

Being able to catch specific exceptions to e.g. display a warning :p
We have custom exception types for other api things too; like the ResourcePackRegistrationException

[onebeastchris]

Continuing from #5685 (comment) - we could split Message.Packet into Message.BedrockPacket (and therefore leave a spot open for Message.JavaPacket if we desire to add it in the future?)

[Redned235]

I'm not a huge fan of that from the API side. Message.BedrockPacket.of(AnimatePacket::new)) for instance just doesn't seem great. If we are to introduce a Java packet system, it's probably best to define in the NetworkChannel#packet method.

[onebeastchris]

IMO introducing a Java packet system that isn't a Message.Packet would be more confusing :p
Can we add a field / enum or something to Message.Packet to indicate whether it is Bedrock or Java?

[dima-dencep]

I haven't really looked into what's going on here yet, but for emotecraft it's very important to get byte[] from the packet (or at least ByteBuffer)

And, of course, sending packets during the configuration state

[Redned235]

I haven't really looked into what's going on here yet, but for emotecraft it's very important to get byte[] from the packet (or at least ByteBuffer)

And, of course, sending packets during the configuration state

At what point during the config stage? During login or switching into the state while previously in the game state?

[Copilot]

Pull Request Overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull Request Overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dima-dencep]

At what point during the config stage? During login or switching into the state while previously in the game state?

At the state where fabric/neoforge mods are configured

[Copilot]

Pull Request Overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The send() method always sends messages as ServerboundCustomPayloadPacket (line 180-185), regardless of the direction parameter. This means that messages intended to be CLIENTBOUND will also be sent to the server, which is incorrect. The direction parameter should determine whether to send upstream (to client) or downstream (to server).

[Copilot]

The line unpinnedBlock.clear() after adding all items to ordered is unnecessary since the list is not reused after this point. While not a bug, removing this line would improve code clarity.

Suggested change

unpinnedBlock.clear();

[Copilot]

Inefficient channel lookup: The code fetches all registered channels and then iterates through them to find matching ones. Consider maintaining a map from channel identifier to NetworkChannel in GeyserNetworkManager for O(1) lookup instead of O(n) iteration.

Suggested change

	List<NetworkChannel> identifiedChannels = new ArrayList<>();
	for (NetworkChannel registeredChannel : channels) {
	if (!registeredChannel.isPacket() && registeredChannel.identifier().toString().equals(channel)) {
	identifiedChannels.add(registeredChannel);
	}
	}
	if (identifiedChannels.isEmpty()) {
	// Build a map from identifier string to NetworkChannel for O(1) lookup
	java.util.Map<String, List<NetworkChannel>> channelMap = new java.util.HashMap<>();
	for (NetworkChannel registeredChannel : channels) {
	if (!registeredChannel.isPacket()) {
	String identifier = registeredChannel.identifier().toString();
	channelMap.computeIfAbsent(identifier, k -> new ArrayList<>()).add(registeredChannel);
	}
	}
	List<NetworkChannel> identifiedChannels = channelMap.get(channel);
	if (identifiedChannels == null || identifiedChannels.isEmpty()) {

[Copilot]

The channel identifier is concatenated using namespace() + ":" + path() instead of using the toString() method. While this works, it's better to use channel.identifier().toString() for consistency with how it's used elsewhere (e.g., in JavaCustomPayloadTranslator line 165).

Suggested change

	.map(channel -> channel.identifier().namespace() + ":" + channel.identifier().path())
	.map(channel -> channel.identifier().toString())

[Copilot]

Pull request overview

Copilot reviewed 51 out of 51 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

core/src/main/java/org/geysermc/geyser/registry/loader/ProviderRegistryLoader.java:1

• Corrected spelling of 'Cloud' to 'Could'.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[onebeastchris]

Ideally this would be configurable... maybe with optionallyBefore (or alternatively e.g. requiredBefore) to forcibly throw if the specified handler isn't found?
Pipeline order can be a tricky thing, detecting breaks would be difficult if it'll fall back silently

[Redned235]

This seems quite niche IMO - what would the usecase here be?

[Copilot]

Pull request overview

Copilot reviewed 51 out of 51 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 51 out of 51 changed files in this pull request and generated 9 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

handleMessages only processes channels that are BaseNetworkChannel (otherwise it silently skips handling). Since the public API accepts any NetworkChannel implementation, consider validating this at registration time (and throwing a clear exception) or refactoring so GeyserNetwork doesn’t depend on the concrete channel implementation for type checks.

Suggested change

	for (Message<T> message : messages) {
	for (MessageDefinition<?, ?> def : ordered) {
	if (!(channel instanceof BaseNetworkChannel base)) {
	continue;
	}
	if (!(channel instanceof BaseNetworkChannel base)) {
	throw new IllegalArgumentException("Unsupported NetworkChannel implementation: "
	+ channel.getClass().getName() + "; expected BaseNetworkChannel");
	}
	for (Message<T> message : messages) {
	for (MessageDefinition<?, ?> def : ordered) {

[Copilot]

createMessages(channel, buffer) passes the same buffer instance to every registered definition. If more than one definition exists for a channel, the first message factory will advance the reader index and later factories will decode from the wrong position (often producing invalid messages). Consider creating a fresh buffer per definition (e.g., from the original byte[]), or resetting/copying the buffer before each decode.

Suggested change

	return this.createMessages0(channel, def -> buffer);
	byte[] data = buffer.toByteArray();
	return (List<Message<T>>) (List<?>) this.createMessages(channel, data);

[Copilot]

createMessages0 decodes one message per registered definition, but handleMessages then iterates every decoded message over every definition, causing handlers to run multiple times for a single incoming payload (O(n^2) calls) and potentially decoding the same payload repeatedly. Decoding should generally be done once per incoming payload, with all handlers invoked against that single decoded message instance.

[Copilot]

The ByteBuf allocated via Unpooled.buffer() is never released after packet.serialize(buffer). This risks leaking direct buffers. Use try/finally to release() the buffer after message decoding/handling, consistent with other parts of the codebase that explicitly release Unpooled buffers.

[Copilot]

The Javadoc for MessagePriority#of(int) says it "creates a custom priority", but the implementation actually buckets the value into one of the predefined enum constants (FIRST/EARLY/NORMAL/LATE/LAST). Update the Javadoc to reflect the bucketing behavior, or change the API if true custom numeric priorities are intended.

[Copilot]

The Message#encode Javadoc says it "Reads the message from the provided buffer", but the method name/signature indicate it writes/encodes the message into the buffer. This is likely inverted wording and can confuse API consumers implementing messages.

Suggested change

	* Reads the message from the provided buffer.
	*
	* @param buffer the buffer to read from
	* Encodes this message into the provided buffer.
	*
	* @param buffer the buffer to write to

[Copilot]

The Javadoc for Message.Packet.of(...) methods repeatedly mentions "and direction", but none of these overloads take a direction parameter. Consider removing the direction wording to avoid confusion about how direction is determined/applied.

[Copilot]

Network#send ignores the direction parameter for non-packet (custom payload) channels and always sends a ServerboundCustomPayloadPacket downstream. This contradicts the API contract/docs that imply direction affects where the message is delivered; either enforce direction == SERVERBOUND here (e.g., throw/return) or implement clientbound injection behavior explicitly.

[Copilot]

The ByteBuf allocated via Unpooled.buffer() is never released. Since Netty may allocate direct buffers here, this can lead to memory leaks under leak detection / high throughput. Wrap serialization + message creation in a try/finally and release() the buffer once handlers are done (or use a heap buffer allocator explicitly).