Geyser Networking API

api/src/main/java/org/geysermc/geyser/api/connection/GeyserConnection.java

@@ -36,6 +36,7 @@
 import org.geysermc.geyser.api.entity.EntityData;
 import org.geysermc.geyser.api.entity.type.GeyserEntity;
 import org.geysermc.geyser.api.entity.type.player.GeyserPlayerEntity;
+import org.geysermc.geyser.api.network.NetworkManager;
 import org.geysermc.geyser.api.skin.SkinData;
 
 import java.util.NoSuchElementException;
@@ -122,6 +123,15 @@ public interface GeyserConnection extends Connection, CommandSource {
      */
     void sendCommand(String command);
 
+    /**
+     * Gets the {@link NetworkManager} used for handling
+     * network channels and sending messages.
+     *
+     * @return the network manager
+     */
+    @NonNull
+    NetworkManager networkManager();
+
     /**
      * Gets the hostname or ip address the player used to join this Geyser instance.
      * Example:
@@ -132,7 +142,7 @@ public interface GeyserConnection extends Connection, CommandSource {
      * </ul>
      *
      * @throws NoSuchElementException if called before the session is fully initialized
-     * @return the ip address or hostname string the player used to join 
+     * @return the ip address or hostname string the player used to join
      * @since 2.8.3
      */
     @NonNull
@@ -147,7 +157,7 @@ public interface GeyserConnection extends Connection, CommandSource {
      * </ul>
      *
      * @throws NoSuchElementException if called before the session is fully initialized
-     * @return the port the player used to join 
+     * @return the port the player used to join
      * @since 2.8.3
      */
     @Positive

api/src/main/java/org/geysermc/geyser/api/event/bedrock/SessionDefineNetworkChannelsEvent.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2025 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.event.bedrock;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.geyser.api.connection.GeyserConnection;
+import org.geysermc.geyser.api.event.connection.ConnectionEvent;
+import org.geysermc.geyser.api.network.NetworkChannel;
+import org.geysermc.geyser.api.network.message.MessageBuffer;
+import org.geysermc.geyser.api.network.message.MessageCodec;
+import org.geysermc.geyser.api.network.message.MessageFactory;
+
+/**
+ * Called whenever Geyser is registering network channels.
+ * @since 2.8.2
+ */
+public abstract class SessionDefineNetworkChannelsEvent extends ConnectionEvent {
+
+    public SessionDefineNetworkChannelsEvent(@NonNull GeyserConnection connection) {
+        super(connection);
+    }
+
+    /**
+     * Registers a new network channel with a message factory.
+     *
+     * @param channel the channel to register
+     * @param messageFactory the factory to create messages from the buffer
+     */
+    public abstract void register(@NonNull NetworkChannel channel, @NonNull MessageFactory<MessageBuffer> messageFactory);
+
+    /**
+     * Registers a new network channel with a message factory.
+     *
+     * @param channel the channel to register
+     * @param codec the codec to use to encode/decode the buffer
+     * @param messageFactory the factory to create messages from the buffer
+     */
+    public abstract <T extends MessageBuffer> void register(@NonNull NetworkChannel channel, @NonNull MessageCodec<T> codec, @NonNull MessageFactory<T> messageFactory);
+}

api/src/main/java/org/geysermc/geyser/api/event/java/ServerReceiveNetworkMessageEvent.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright (c) 2025 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.event.java;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.event.Cancellable;
+import org.geysermc.geyser.api.connection.GeyserConnection;
+import org.geysermc.geyser.api.event.connection.ConnectionEvent;
+import org.geysermc.geyser.api.network.MessageDirection;
+import org.geysermc.geyser.api.network.NetworkChannel;
+import org.geysermc.geyser.api.network.message.Message;
+
+/**
+ * Called when Geyser receives a network message from the server.
+ * @since 2.8.2
+ */
+public final class ServerReceiveNetworkMessageEvent extends ConnectionEvent implements Cancellable {
+    private final NetworkChannel channel;
+    private final Message<?> message;
+    private final MessageDirection direction;
+    private boolean cancelled = false;
+
+    public ServerReceiveNetworkMessageEvent(@NonNull GeyserConnection connection, @NonNull NetworkChannel channel, @NonNull Message<?> message, @NonNull MessageDirection direction) {
+        super(connection);
+
+        this.channel = channel;
+        this.message = message;
+        this.direction = direction;
+    }
+
+    /**
+     * Gets the channel that received the message.
+     * <p>
+     * See {@link NetworkChannel} for more information.
+     *
+     * @return the channel that received the message
+     */
+    @NonNull
+    public NetworkChannel channel() {
+        return this.channel;
+    }
+
+    /**
+     * Gets the message that was received.
+     *
+     * @return the received message
+     */
+    @NonNull
+    public Message<?> message() {
+        return this.message;
+    }
+
+    /**
+     * Gets the direction of the message.
+     *
+     * @return the direction of the message
+     */
+    @NonNull
+    public MessageDirection direction() {
+        return this.direction;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean isCancelled() {
+        return this.cancelled;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void setCancelled(boolean cancelled) {
+        this.cancelled = cancelled;
+    }
+}

api/src/main/java/org/geysermc/geyser/api/network/ExtensionNetworkChannel.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2025 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.network;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.geyser.api.extension.Extension;
+import org.geysermc.geyser.api.util.Identifier;
+
+import java.util.Objects;
+
+/**
+ * Represents a network channel associated with an extension.
+ * @since 2.8.2
+ */
+public class ExtensionNetworkChannel implements NetworkChannel {
+    private final Extension extension;
+    private final String channel;
+
+    protected ExtensionNetworkChannel(@NonNull Extension extension, @NonNull String channel) {
+        this.extension = extension;
+        this.channel = channel;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    @NonNull
+    public Identifier identifier() {
+        return Identifier.of(this.extension.description().id(), this.channel);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean isPacket() {
+        return false;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (o == null || !NetworkChannel.class.isAssignableFrom(o.getClass())) return false;
+        NetworkChannel that = (NetworkChannel) o;
+        return Objects.equals(this.identifier(), that.identifier());
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.identifier());
+    }
+
+    @Override
+    public String toString() {
+        return "ExtensionNetworkChannel{" +
+                "extension=" + this.extension.description().id() +
+                ", channel='" + this.channel + '\'' +
+                '}';
+    }
+}

api/src/main/java/org/geysermc/geyser/api/network/ExternalNetworkChannel.java

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2025 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.network;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.geyser.api.util.Identifier;
+
+import java.util.Objects;
+
+/**
+ * Represents a network channel not associated with any specific extension.
+ * <p>
+ * This can be used for external communication channels, like mods or plugins.
+ * @since 2.8.2
+ */
+public class ExternalNetworkChannel implements NetworkChannel {
+    private final Identifier identifier;
+
+    protected ExternalNetworkChannel(@NonNull Identifier identifier) {
+        this.identifier = identifier;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    @NonNull
+    public Identifier identifier() {
+        return this.identifier;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public boolean isPacket() {
+        return false;
+    }
+
+    @Override
+    public boolean equals(Object o) {
+        if (o == null || !NetworkChannel.class.isAssignableFrom(o.getClass())) return false;
+        NetworkChannel that = (NetworkChannel) o;
+        return Objects.equals(this.identifier(), that.identifier());
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(this.identifier());
+    }
+
+    @Override
+    public String toString() {
+        return "ExternalNetworkChannel{" +
+                "identifier='" + this.identifier + '\'' +
+                '}';
+    }
+}