Timeline (UTC)​

• July 29th, 9:40PM: Server being attacked privately reports the issue to Geyser and shares logs
• July 29th, 11:45PM: Preemptive patch is released to limit the number of authenticated connections per address
• July 30th, 5:36PM: Large servers continue to report attacks with newer builds of Geyser
• July 30th, 6:20PM: A server being attacked provides us with packet logs, illustrating what Bedrock packets malicious clients are using to carry out the attack
• July 30th, 6:52PM: Second patch is released to ensure the Bedrock client can only signal complete of resource pack sending once per session
• July 30th, 7:45PM: Issue regarding connections failing to close out is reported to upstream Bedrock protocol library
• July 30th, 9:35PM: Upstream Bedrock protocol library publishes patch to ensure connections are properly closed when Bedrock users are disconnected
• July 30th, 10:45PM: Third patch is released updating the upstream Bedrock protocol library and ensuring Bedrock connections that cause exceptions are closed immediately
• July 31st, 11:24PM: An @everyone ping is made in the Geyser Discord advising users to update their Geyser instances, and the initial security advisory is published to GitHub.

Initial Disclosure​

Use of this attack was first privately reported to us by multiple larger servers using Geyser. We were provided server logs showing a single user appearing to be authenticated multiple times. The logs generally took a form of:

[17:26:09.183 GeyserServerChild-4-1/INFO] Player connected with username BedrockPleyer
[17:26:09.183 GeyserServerChild-4-1/INFO] Player connected with username BedrockPleyer
[17:26:09.183 GeyserServerChild-4-1/INFO] Player connected with username BedrockPleyer
[17:26:09.183 GeyserServerChild-4-1/ERROR] BedrockPleyer is already logged in!
[17:26:09.183 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[17:26:09.183 clientNetworkSession-6-3/INFO] BedrockPlayer (logged in as: BedrockPlayer) has connected to remote java server on address 127.0.0.1
[17:26:09.183 clientNetworkSession-6-1/INFO] BedrockPlayer (logged in as: BedrockPlayer) has connected to remote java server on address 127.0.0.1
[17:26:09.183 clientNetworkSession-6-2/INFO] BedrockPlayer (logged in as: BedrockPlayer) has connected to remote java server on address 127.0.0.1
[17:26:09.184 GeyserServerChild-4-1/ERROR] BedrockPlayer is already logged in!
[17:26:09.184 clientNetworkSession-6-4/INFO] BedrockPlayer (logged in as: BedrockPlayer) has connected to remote java server on address 127.0.0.1
[17:26:09.184 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[17:26:09.184 GeyserServerChild-4-1/ERROR] BedrockPlayer is already logged in!
[17:26:09.184 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[17:26:09.184 GeyserServerChild-4-1/ERROR] BedrockPlayer is already logged in!
[17:26:09.184 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[17:26:09.184 GeyserServerChild-4-1/ERROR] BedrockPlayer is already logged in!
[17:26:09.185 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[17:26:09.185 GeyserServerChild-4-1/ERROR] BedrockPlayer is already logged in!

Based on the content of these logs, we initially suspected that packets in the early phase of the Bedrock connection were being exploited. However, we were not yet sure of what specific packets the attacker was sending. Based on these logs, we released a preemptive patch to ensure that the number of authenticated users from a single IP address at any given time was limited. This alone, however, would prove to be insufficient to mitigate the attack.

Game Packet and Code Analysis of the First Attack Vector​

Understanding this attack requires a basic understanding of the general Bedrock login process. This is detailed below:

In order to fully mitigate this attack, we required packet capture samples from a server being actively exploited. This is somewhat challenging to achieve, as traffic at the Bedrock protocol level is generally encrypted after the player has logged into the server. As a result, a modified build of Geyser is required to capture this traffic. We were fortunate to have the cooperation of a server being targeted with this attack, who installed a build of Geyser we provided to log packets. This was the resulting log, with IP addresses and usernames redacted:

[18:16:37.767 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ClientToServerHandshakePacket
[18:16:37.795 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.808 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.808 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.809 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.809 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.809 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.809 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.810 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.810 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.810 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.810 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.810 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.810 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.811 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.811 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.811 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.811 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.811 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.811 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.812 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.812 GeyserServerChild-4-1/INFO] null /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.820 clientNetworkSession-6-2/INFO] BedrockPlayer (logged in as: BedrockPlayer) has connected to remote java server on address 127.0.0.1
[18:16:37.820 clientNetworkSession-6-1/INFO] BedrockPlayer (logged in as: BedrockPlayer) has connected to remote java server on address 127.0.0.1
[18:16:37.820 clientNetworkSession-6-4/INFO] BedrockPlayer (logged in as: BedrockPlayer) has connected to remote java server on address 127.0.0.1
[18:16:37.820 clientNetworkSession-6-3/INFO] BedrockPlayer (logged in as: BedrockPlayer) has connected to remote java server on address 127.0.0.1
[18:16:37.848 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.849 GeyserServerChild-4-1/INFO] BedrockPlayer /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.849 GeyserServerChild-4-1/ERROR] BedrockPlayer is already logged in!
[18:16:37.849 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.849 GeyserServerChild-4-1/INFO] BedrockPlayer /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.850 GeyserServerChild-4-1/ERROR] BedrockPlayer is already logged in!
[18:16:37.850 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer
[18:16:37.850 GeyserServerChild-4-1/INFO] BedrockPlayer /XXX.XXX.XXX.XXX ResourcePackClientResponsePacket(packIds=[], status=COMPLETED)
[18:16:37.850 GeyserServerChild-4-1/ERROR] BedrockPlayer is already logged in!
[18:16:37.850 GeyserServerChild-4-1/INFO] Player connected with username BedrockPlayer

The above log clearly indicates that the packet being exploited is the ResourcePackClientResponsePacket. This leads to code paths in Geyser being called multiple times a way that is not intended, ultimately leading to increased resource consumption. We can essentially summarize the attack as follows:

The initial response to the ResourcePackClientResponsePacket is handled by UpstreamPacketHandler:

package org.geysermc.geyser.network;
// ...
public class UpstreamPacketHandler extends LoggingPacketHandler {
    // ...
    public PacketSignal handle(ResourcePackClientResponsePacket packet) {
        // ...
        switch (packet.getStatus()) {
            case COMPLETED -> {
                if (geyser.getConfig().getRemote().authType() != AuthType.ONLINE) {
                    session.authenticate(session.getAuthData().name());
                } else if (!couldLoginUserByName(session.getAuthData().name())) {
                    // We must spawn the white world
                    session.connect();
                }
                geyser.getLogger().info(GeyserLocale.getLocaleStringLog("geyser.network.connect", session.getAuthData().name()));
            }
            // ...
        }
        return PacketSignal.HANDLED;
    }
    // ...
}

We see in the code above that this will lead to the invocation of GeyserSession#authenticate for most connections, as most Geyser instances use AuthType.FLOODGATE:

package org.geysermc.geyser.session;
// ...
public class GeyserSession implements GeyserConnection, GeyserCommandSource {
    // ...
    public void authenticate(String username) {
        if (loggedIn) {
            geyser.getLogger().severe(GeyserLocale.getLocaleStringLog("geyser.auth.already_loggedin", username));
            return;
        }

        loggingIn = true;
        // Always replace spaces with underscores to avoid illegal nicknames, e.g. with GeyserConnect
        protocol = new MinecraftProtocol(username.replace(' ', '_'));

        try {
            connectDownstream();
        } catch (Throwable t) {
            t.printStackTrace();
        }
    }
    // ...
}

This leads to the calling of GeyserSession#connectDownstream, which triggers a variety of logic to open a connection to the Java server:

package org.geysermc.geyser.session;
// ...
public class GeyserSession implements GeyserConnection, GeyserCommandSource {
    // ...
    private void connectDownstream() {
        SessionLoginEvent loginEvent = new SessionLoginEvent(this, remoteServer, new Object2ObjectOpenHashMap<>());
        GeyserImpl.getInstance().eventBus().fire(loginEvent);
        if (loginEvent.isCancelled()) {
            String disconnectReason = loginEvent.disconnectReason() == null ?
                BedrockDisconnectReasons.DISCONNECTED : loginEvent.disconnectReason();
            disconnect(disconnectReason);
            return;
        }

        this.cookies = loginEvent.cookies();
        // Don't allow changing the remote server when it's not up to us
        // Just imagine the chaos of using an integrated world manager for an external server :)
        this.remoteServer = this.geyser.platformType() == PlatformType.STANDALONE ? loginEvent.remoteServer() : remoteServer;

        // Start ticking
        tickThread = tickEventLoop.scheduleAtFixedRate(this::tick, nanosecondsPerTick, nanosecondsPerTick, TimeUnit.NANOSECONDS);

        ClientSession downstream;
        if (geyser.getBootstrap().getSocketAddress() != null) {
            // We're going to connect through the JVM and not through TCP
            downstream = new LocalSession(geyser.getBootstrap().getSocketAddress(),
                upstream.getAddress().getAddress().getHostAddress(),
                this.protocol, this.tickEventLoop);
            downstream.setFlag(MinecraftConstants.CLIENT_HOST, this.remoteServer.address());
            downstream.setFlag(MinecraftConstants.CLIENT_PORT, this.remoteServer.port());
            this.downstream = new DownstreamSession(downstream);
        } else {
            downstream = new ClientNetworkSession(new InetSocketAddress(this.remoteServer.address(), this.remoteServer.port()), this.protocol, tickEventLoop, null, null);
            this.downstream = new DownstreamSession(downstream);

            boolean resolveSrv = false;
            try {
                resolveSrv = this.remoteServer.resolveSrv();
            } catch (AbstractMethodError | NoSuchMethodError ignored) {
                // Ignore if the method doesn't exist
                // This will happen with extensions using old APIs
            }
            this.downstream.getSession().setFlag(BuiltinFlags.ATTEMPT_SRV_RESOLVE, resolveSrv);
        }

        // Disable automatic creation of a new TcpClientSession when transferring - we don't use that functionality.
        this.downstream.getSession().setFlag(MinecraftConstants.FOLLOW_TRANSFERS, false);

        if (geyser.getConfig().getRemote().isUseProxyProtocol()) {
            downstream.setFlag(BuiltinFlags.CLIENT_PROXIED_ADDRESS, upstream.getAddress());
        }
        if (geyser.getConfig().isForwardPlayerPing()) {
            // Let Geyser handle sending the keep alive
            downstream.setFlag(MinecraftConstants.AUTOMATIC_KEEP_ALIVE_MANAGEMENT, false);
        }
        // We'll handle this since we have the registry data on hand
        downstream.setFlag(MinecraftConstants.SEND_BLANK_KNOWN_PACKS_RESPONSE, false);

        // We manually add the default listener to ensure the order of listeners.
        protocol.setUseDefaultListeners(false);

        // MCPL listener comes first to handle protocol state switching before Geyser translates packets
        downstream.addListener(new ClientListener(HandshakeIntent.LOGIN));
        // Geyser adapter second to ensure translating packets in the correct states
        downstream.addListener(new GeyserSessionAdapter(this));

        downstream.setFlag(BuiltinFlags.CLIENT_TRANSFERRING, loginEvent.transferring());
        downstream.connect(false);

        if (!daylightCycle) {
            setDaylightCycle(true);
        }
    }
    // ...
}

Notably, this allows for multiple downstream sessions (representing Geyser's connection to the Java server per player) to be created for a single Bedrock session. This is not intended behavior, as it leads to significantly increased resource consumption. This is especially true on Geyser Standalone, which, as seen in the code above, must open a TCP session to the Java server. The window of time for an attacker to pull this off is relatively short, as once Geyser completes the Java login process on behalf of the Bedrock client, GeyserSession.loggedIn is set to true, preventing further calls to GeyserSession#connectDownstream. However, this is still enough time for an attacker to create numerous downstream sessions, leading to a DoS attack. We attempted to mitigate this by disconnecting clients that send multiple ResourcePackClientResponsePacket in a single session. The following class diagram summarizes this:

Code Analysis of the Second Attack Vector​

While we thought we had addressed the root issue and provided the affected users with a patch for testing, we quickly received logs that indicated otherwise:

[18:54:29.235 GeyserServerChild-4-3/INFO] Player connected with username BedrockPlayer
[18:54:29.237 clientNetworkSession-6-2/INFO] BedrockPlayer (logged in as: BedrockPlayer) has connected to remote java server on address 127.0.0.1
[18:54:49.257 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:54:49.259 GeyserServerChild-4-3/INFO] BedrockPlayer has disconnected from remote Java server on address 127.0.0.1 because of An internal error occurred!
[18:54:52.836 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:54:55.620 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:54:56.186 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:54:56.872 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:54:59.508 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:02.551 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:03.025 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:03.619 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:04.254 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:04.922 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:05.435 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:07.662 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:08.139 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:08.650 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:11.066 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:13.498 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:14.023 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:14.466 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:15.057 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:15.712 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:16.211 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:18.431 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:18.966 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:19.443 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:21.599 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:23.904 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:24.409 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:24.971 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:25.539 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))
[18:55:26.225 GeyserServerChild-4-3/WARN] Exception caught in session of BedrockPlayer: index: 13, length: 25710 (expected: range(0, 27))

These exceptions are thrown by Geyser's InvalidPacketHandler, which is designed to quickly disconnect players that send malformed packets or packets that exceed the expected size limits. This is a security measure to prevent potential exploits or crashes caused by invalid data.

package org.geysermc.geyser.network;
// ...
public class InvalidPacketHandler extends ChannelInboundHandlerAdapter {
    public static final String NAME = "rak-error-handler";

    private final GeyserSession session;

    @Override
    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) throws Exception {
        Throwable rootCause = Stream.iterate(cause, Throwable::getCause)
                .filter(element -> element.getCause() == null)
                .findFirst()
                .orElse(cause);

        GeyserLogger logger = GeyserImpl.getInstance().getLogger();

        if (!(rootCause instanceof IllegalArgumentException)) {
            // Kick users that cause exceptions
            logger.warning("Exception caught in session of " + session.bedrockUsername() + ": " + rootCause.getMessage());
            session.disconnect("An internal error occurred!");
            return;
        }

        // Kick users that try to send illegal packets
        logger.warning("Illegal packet from " + session.bedrockUsername() + ": " + rootCause.getMessage());
        if (logger.isDebug()) {
            cause.printStackTrace();
        }
        session.disconnect("Invalid packet received!");
    }
}

This makes the aforementioned logs of particular concern, as it should not be possible for any exceptions to be triggered from this handler multiple times. The first exception should be logged and trigger an immediate disconnect, preventing further exceptions from being thrown. Despite this, the log clearly indicates that multiple exceptions are being thrown in quick succession, suggesting that the disconnect is not being handled as intended. This is summarized below:

We first followed the chain of GeyserSession#disconnect. This invokes Geyser's UpstreamSession#disconnect, which contains BedrockServerSession and invokes BedrockServerSession#disconnect. Beyond this, the disconnect logic is handled by the upstream Bedrock protocol library used by Geyser, CloudburstMC/Protocol. The overall logic is summarized below:

Upon further investigation, we found that the Bedrock protocol library did not actually close the underlying Netty channel when a disconnect was triggered:

package org.cloudburstmc.protocol.bedrock;
// ...
public class BedrockServerSession extends BedrockSession {
    // ...
    public void disconnect(@Nullable String reason, boolean hideReason) {
        this.checkForClosed();

        DisconnectPacket packet = new DisconnectPacket();
        if (reason == null || hideReason) {
            packet.setMessageSkipped(true);
            reason = BedrockDisconnectReasons.DISCONNECTED;
        }
        packet.setKickMessage(reason);
        this.sendPacketImmediately(packet);
    }
}

This allows an attacker that should have been disconnected to continue to send malicous packets that lead to expensive deserialization logic. The result is another potential denial of service (DoS) attack vector.

Patch and Mitigation​

We mitigated the first attack vector by ensuring that the Bedrock client can only signal completion of resource pack sending once per session. This was done by modifying the UpstreamPacketHandler to check if the finishedResourcePackSending flag is already set before proceeding with authentication logic:

package org.geysermc.geyser.network;
// ...
public class UpstreamPacketHandler extends LoggingPacketHandler {
    // ...
    public PacketSignal handle(ResourcePackClientResponsePacket packet) {
        // ...
        if (finishedResourcePackSending) {
            session.disconnect("Illegal duplicate resource pack response packet received!");
            return PacketSignal.HANDLED;
        }
        // ...
        switch (packet.getStatus()) {
            case COMPLETED -> {
                finishedResourcePackSending = true;
                if (geyser.getConfig().getRemote().authType() != AuthType.ONLINE) {
                    session.authenticate(session.getAuthData().name());
                } else if (!couldLoginUserByName(session.getAuthData().name())) {
                    // We must spawn the white world
                    session.connect();
                }
                geyser.getLogger().info(GeyserLocale.getLocaleStringLog("geyser.network.connect", session.getAuthData().name()));
            }
            // ...
        }
        return PacketSignal.HANDLED;
    }
    // ...
}

This ensures that any further attempts to send a ResourcePackClientResponsePacket after the first one will result in an immediate disconnect, preventing the creation of multiple downstream sessions.

The second attack vector was mitigated by ensuring that the disconnect logic in the Bedrock protocol library properly closes the underlying Netty channel. This was achieved by modifying the BedrockServerSession#disconnect method to schedule a task that closes the session after a timeout, ensuring that the channel is closed after the disconnect packet is sent. Packet serialzation is also stopped immediately for disconnected clients:

package org.cloudburstmc.protocol.bedrock;
// ...
public class BedrockServerSession extends BedrockSession {
    private static final int TIMEOUT_SECONDS = SystemPropertyUtil.getInt("org.cloudburstmc.protocol.bedrock.disconnectTimeout", 10);
    // ...
    public void disconnect(@Nullable String reason, boolean hideReason) {
        this.checkForClosed();

        DisconnectPacket packet = new DisconnectPacket();
        String finalReason;
        if (reason == null || hideReason) {
            packet.setMessageSkipped(true);
            finalReason = BedrockDisconnectReasons.DISCONNECTED;
        } else {
            finalReason = reason;
        }
        packet.setKickMessage(finalReason);
        this.sendPacketImmediately(packet);
        
        if (!this.isSubClient()) {
            this.getPeer().blackholeInboundPackets();
        }

        this.getPeer().channel.eventLoop().schedule(() -> {
            if (this.isConnected()) {
                this.close(finalReason);
            }
        }, TIMEOUT_SECONDS, TimeUnit.SECONDS);
    }
}

Logic was also added to Geyser's InvalidPacketHandler to ensure that invalid packets result in an immediate closing of the underlying Netty channel:

package org.geysermc.geyser.network;
// ...
public class InvalidPacketHandler extends ChannelInboundHandlerAdapter {
    public static final String NAME = "rak-error-handler";

    private final GeyserSession session;

    @Override
    public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause) throws Exception {
        Throwable rootCause = Stream.iterate(cause, Throwable::getCause)
                .filter(element -> element.getCause() == null)
                .findFirst()
                .orElse(cause);

        GeyserLogger logger = GeyserImpl.getInstance().getLogger();

        if (!(rootCause instanceof IllegalArgumentException)) {
            // Kick users that cause exceptions
            logger.error("Exception caught in session of " + session.bedrockUsername(), cause);
            session.disconnect("An internal error occurred!");
            session.forciblyCloseUpstream();
            return;
        }

        // Kick users that try to send illegal packets
        logger.error("Illegal packet from " + session.bedrockUsername(), cause);
        session.disconnect("Invalid packet received!");
        session.forciblyCloseUpstream();
    }
}

Long Term Impact​

All users of Geyser running outdated builds should update as soon as possible to ensure they are not vulnerable to the attacks described in this post. During the process of investigating this attack, we were made aware of multiple servers being exploited, meaning this is being exploited in the wild. Unlike the previous RakNet amplification attack, this attack is limited in scope to the selected Geyser instance. We expect the number of unpatched instances to decrease over time as Bedrock updates require server owners to update their Geyser instances. As of November 2025, we have not received any recent reports of Geyser instances being targeted by this attack vector, indicating that most instances have been patched.

Acknowledgements​

We thank the community for their patience as we addressed this issue, the server owners who responsibly disclosed this issue to us, the developers at Cloudburst and Geyser that worked to mitigate the issue, all donors for their financial support of Geyser, and Cubecraft and Open Collaboration for their continued financial and operational support of the project.

Timeline (UTC)​

• March 24th, 11:00AM: bStats data begins to show instability in the number of online Geyser instances
• March 28th, 5:00AM: First reported Geyser instance causing server suspension by OVH
• March 28th, 4:00PM: First GitHub issue is opened referencing spamming of suspicious connections
• March 28th, 5:00PM: Attack against the Global Linking Server, which also hosts the Global API and Geyser Test Server, takes all three services offline
• March 28th, 6:07PM: The Global API server is started to begin restoration of the database from the MariaDB log
• March 28th, 6:27PM: The packets sent from Geyser responsible for the suspension of the Geyser Test Server machine are identified as being 134 bytes each sent at a rate of 60,000 packets per second
• March 28th, 6:30PM: A build of Geyser with enhanced logging for the Cloudburst Network library is installed on the test server to gather data about the attack vector.
• March 28th, 7:48PM: Database restoration is completed and the Global API is brought back online, but remains unstable due to the initial backlog of requests from the downtime
• March 28th, 8:46PM: Global API stability returns to normal
• March 29th, 1:30AM: Initial rate limiting is implemented in Geyser from upstream changed in Cloudburst Network, but the specific attack vector is still unclear
• March 29th, 3:32AM: Packet responsible is identified as Connection Request Accepted, sent by Geyser in the initial RakNet handshake
• March 29th, 6:00AM: Initial proof of concept is created showing a client can maliciously spam Connection Request packets, causing the server to reply with larger Connection Request Accepted packets
• March 29th, 12:25PM: Further rate limiting is added to Geyser via Cloudburst Network, particularly for replies to Connection Request packets
• March 30th, 9:20AM: A raw packet capture is obtained from a Geyser instance under attack, unmasking the root cause of the issue as the RakNet reliability setting of the Connection Request Accepted packet in Cloudburst Network
• March 30th, 10:30AM: A final fix to Cloudburst Network is pushed to Geyser, and a previously exploited instance is monitored with full packet dumps to confirm the fix
• March 30th, 10:28PM: Security advisory is published on the Cloudburst Network GitHub repository
• March 30th, 10:31PM: First @everyone ping in 1 year is made in the Geyser Discord announcing the security advisory and requesting all server owners update their instances as soon as possible

Initial Warning Signs​

Before the issue was initially detected, a suspicious trend can be seen in Geyser’s bStats data. On March 24th starting at approximately 11:00AM UTC, noticeable dips are seen in the total number of online Geyser instances. Normally, the number of online instances smoothly climbs and falls by about 500 instances, likely correlating with when people have free time to play Minecraft. Beginning on March 24th, frequent hourly swings of as much as 2200 instances online are seen. Given hindsight, this is likely when wide scale exploitation of this attack began.

bStats chart of servers using Geyser over the month of March. Clear instability in the number of online servers reported is seen at the left starting on March 24th, at least three days before any formal reports of the attack were received.

Initial Disclosure​

Multiple users in the Geyser Discord first brought the attack to our attention by providing us with notices from their hosting provider that their server instances were suspended due to abuse. This means that their Geyser instances were sending outbound traffic interpreted by their hosting provider interpreted as a denial of service attack. Here is a snippet from one of these notices:

##############################################################################
#       DDoS-Attack detected from host XXX.XXX.XXX.XXX                       #
##############################################################################

TIME                             	SRC       	SRC-PORT  ->  DST       	DST-PORT  SIZE  PROT
----------------------------------------------------------------------------------------------------------
2024-03-28 06:49:06.493070866 +0100  XXX.XXX.XXX.XXX	19132  ->  51.75.XXX.XXX    	1   134   UDP
2024-03-28 06:49:06.50822918  +0100  XXX.XXX.XXX.XXX	19132  ->  51.75.XXX.XXX    	1   134   UDP
2024-03-28 06:49:06.515954324 +0100  XXX.XXX.XXX.XXX	19132  ->  51.75.XXX.XXX    	1   134   UDP
2024-03-28 06:49:06.519665639 +0100  XXX.XXX.XXX.XXX	19132  ->  51.75.XXX.XXX    	1   134   UDP
2024-03-28 06:49:06.523410527 +0100  XXX.XXX.XXX.XXX	19132  ->  51.75.XXX.XXX    	1   134   UDP
2024-03-28 06:49:06.526647418 +0100  XXX.XXX.XXX.XXX	19132  ->  51.75.XXX.XXX    	1   134   UDP
2024-03-28 06:49:06.53355138  +0100  XXX.XXX.XXX.XXX	19132  ->  51.75.XXX.XXX    	1   134   UDP
2024-03-28 06:49:06.537470479 +0100  XXX.XXX.XXX.XXX	19132  ->  51.75.XXX.XXX    	1   134   UDP

Abuse report from OVH regarding the suspension of server running a Geyser instance.

This is the first information we were presented with regarding the attack vector. Based on this, we can determine the rough speed of the attack by subtracting the time of the last packet in the report from the first packet (0.044399613 seconds) and dividing the packets sent in that timeframe (8 packets) by the time, we can see about 180 packets per second are being sent here. We are also given the size of the packet on the wire, which is 134 bytes. It’s important to note that this is the size of the packet as it exits the provider network, so it should only contain the destination headers for the public IP address.

Logs were also provided by another user, which show that after many repeated connection attempts, Cloudburst Network was unable to keep up and packet byte buffer handling was compromised.

[nioEventLoopGroup-5-1/ERROR] [org.cloudburstmc.netty.channel.raknet.RakChannelPipeline]: Exception thrown in RakNet pipeline
io.netty.handler.codec.DecoderException: java.lang.NullPointerException: Cannot invoke "io.netty.buffer.ByteBuf.release()" because "this.buffer" is null
  at io.netty.handler.codec.MessageToMessageDecoder.channelRead(MessageToMessageDecoder.java:98)
  at io.netty.handler.codec.MessageToMessageCodec.channelRead(MessageToMessageCodec.java:111)
  at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:442)
  at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420)
  at io.netty.channel.AbstractChannelHandlerContext.fireChannelRead(AbstractChannelHandlerContext.java:412)
  at io.netty.channel.DefaultChannelPipeline$HeadContext.channelRead(DefaultChannelPipeline.java:1410)
  at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:440)
  at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420)
  at io.netty.channel.DefaultChannelPipeline.fireChannelRead(DefaultChannelPipeline.java:919)
  at org.cloudburstmc.netty.handler.codec.raknet.server.RakServerRouteHandler.channelRead(RakServerRouteHandler.java:60)  
  ...
  at org.cloudburstmc.netty.handler.codec.raknet.AdvancedChannelInboundHandler.channelRead(AdvancedChannelInboundHandler.java:48)
  ...
  at org.geysermc.geyser.network.netty.handler.RakConnectionRequestHandler.channelRead(RakConnectionRequestHandler.java:80)
  ...
  at org.cloudburstmc.netty.handler.codec.raknet.ProxyInboundRouter.channelRead(ProxyInboundRouter.java:66)
  ...
Caused by: java.lang.NullPointerException: Cannot invoke "io.netty.buffer.ByteBuf.release()" because "this.buffer" is null
  at org.cloudburstmc.netty.channel.raknet.packet.EncapsulatedPacket.deallocate(EncapsulatedPacket.java:138)
  ... 45 more

Stacktrace from an attacked server after many hours of connection attempts, showing instability in the ability of Cloudburst Network to process packets.

Reproduction Attempts​

Given that the packet spam was occurring without Bedrock login taking place, the vulnerability was likely in the initial establishment of the RakNet connection. Minecraft Bedrock Edition uses a modified version of the RakNet protocol which has gone largely unchanged for many years and is unofficially documented at https://wiki.vg/Raknet_Protocol. Before game packets are sent, the connection is established with 7 packets, four of which are sent by the client and three of which are sent by the server. It was likely that one of these three packets was being spammed by the Geyser instance. The initial RakNet connection follows the sequence:

[Client -> Server] Open Connection Request 1
[Server -> Client] Open Connection Reply 1
[Client -> Server] Open Connection Request 2
[Server -> Client] Open Connection Reply 2

RakNet connection is established and further messages now wrapped in Frame Set Packet

(FSP) [Client -> Server] Connection Request
(FSP) [Server -> Client] Connection Request Accepted
(FSP) [Client -> Server] New Incoming Connection

Summary of the RakNet initial connection sequence. Note that the ability to utilize RakNet reliability settings begin only once packets are wrapped in a Frame Set Packet.

Given that the packet being spammed is coming from the server, and given it has a known outbound length of 134 bytes, we can analyze a normal connection to Geyser in Wireshark to determine the most likely responsible packet:

Wireshark packet capture of a Geyser server at the initial RakNet connection stage. A hex dump of the Connection Request Accepted packet, sent by the server to the client, is shown. Note that byte numbers start at 0.

We can see that on the client end, Connection Request Accepted is 148 bytes over the wire. However, if we subtract the 14 bytes of headers (bytes 0 to 13) added by the local network for routing, we get a size of 134 bytes when the packet left the provider network. Knowing this packet is likely responsible, we can consider how we might get the server to send many of them. One somewhat naive approach we took initially was sending many Connection Request packets once receiving Open Connection Reply 2 from the server. This does indeed result in the server sending many connection request accepted packets, showing there indeed was potential for abuse in Cloudburst Network’s existing implementation:

Wireshark packet capture of a Geyser instance after being sent hundreds of Connection Request packets by a single client. The Geyser instance consequently replies with an equal number of Connection Request Accepted packets.

That said, this is at best an amplification factor of two. By now, we had some bandwidth data of the attack, showing an amplification factor of at least 350 in the wild. Given this, there must have been a way to get this packet to be sent many more times.

Pterodactyl Panel dashboard of a Paper server running Geyser during an attack, showing a large outbound traffic spike. Within the short attack period, inbound traffic is only 819KiB, while outbound traffic is nearly 300MiB.

Live Analysis​

One thing that worked in our favor, ironically, was the wide scale exploitation of this vulnerability. Since our own official test server, and even some of our personal servers, were actively being attacked at regular intervals, we had ample locations to gather data about the attack. We began taking full raw packet capture of a server actively being attacked, which would ultimately unveil the root cause of the attack.

Wireshark packet capture of a Geyser instance under attack. The highlighted packet is a NAK packet sent by the client to the Geyser instance requesting the server resend packets with sequence numbers ranging from 0 to 8191. The immediately following packet is similar, requesting packets 8192 to 16383. The attacker sent these at the beginning of the connection and then simply waited while the Geyser instance continued to send thousands of packets, with each one incrementing the sequence number, leading to yet more packets being sent until the malicious NAK requests were fulfilled.

Looking at the packets sent by the attacker, we see that things largely follow the specified connection sequence. But we also see a new type of packet as well: a NAK packet with a range of 0 to 8191. This brings us to the topic of RakNet packet reliability.

Since UDP itself does not have an inbuilt handshake like TCP to ensure all data arrives bit perfect in the correct order, RakNet implements a reliability system as a substitute. For this system, each packet is sent with a reliability type. While RakNet has eight reliability types, understanding this vulnerability only requires us to understand the difference between reliable and unreliable packets. Simply put, the client can request that reliable packets be resent, while it cannot request the resend of unreliable packets. Looking at the Cloudburst Network library, we see that this packet was indeed sent as reliable.

RakServerOnlineInitialHandler#sendConnectionRequestAccepted is responsible for sending the Open Connection Request packet in the initial connection sequence. The RakReliability.RELIABLE enum causes the packet to be cached by the server before it is sent, therefore allowing the client to later re-request it via NAK.

Because the packet was marked as reliable, this means that Network allows the client to respond with an ACK (Positive Acknowledgement) or NAK (Negative Acknowledgement). At this stage in the connection, this is a vector for abuse because the client has not yet done anything to prove that we are communicating with them directly versus receiving UDP packets with spoofed IP headers. By sending a NAK with the maximum range, they force us to continuously send the Connection Request Accepted packet.

Effects​

This begs the question though: why would an attacker bother doing this? The two leading theories are UDP amplification, meaning the goal is to use Geyser instances as a means to attack other servers, or provider-based suspension, meaning the goal is to get the servers running Geyser instances suspended by their hosting provider.

UDP Amplification​

As explained earlier, UDP has no inbuilt handshake. This means that UDP allows for traffic to be sent to a given IP address without them acknowledging or accepting it. When the ratio of request size to response size is near one, this is largely a nonissue since an attacker gains very little by going through a third party to send the data. In this case, however, the attacker can send a very small amount of data (~52 bytes) and trigger a response of over 8000 134 byte packets. Because the connection sequence up to Connection Request Accepted is always the same and does not require the attacker to actually see the packets we respond with to respond correctly, the attacker can spoof the source IP header of the UDP packets it sends to the Geyser instance. This means that, because of this amplification vector, the Geyser instance can unwittingly be used to multiply the attacker's traffic by a theoretical maximum factor of 22,000. However, in practice, we saw that in the wild the actual multiplication factor was around 1000.

Provider-Based Suspension​

It is also important to consider that servers are generally hosted not locally, but with hosting providers. Hosting providers have a legitimate business interest in preventing their network from being used for abuse, as failing to do so could result in other hosting providers and ISPs blocking their traffic altogether. As a result, many hosting providers employ mechanisms to detect unusual traffic from their servers and will “black hole” traffic to and from servers on their network emitting such traffic. This means that if an attacker wishes to take down a particular server, rather than overwhelm it with a traditional denial of service attack, they can simply make it appear as though the server itself is trying to engage in a denial of service attack. This will result in outbound traffic from the server being dropped by the provider, effectively having the same effect. We saw this occur, for example, with some Geyser services hosted on Hetzer as shown by the below MTR.

mtr pe.minetropical.net -rwbc 10  	 
Start: 2024-03-28T18:24:58+0000
HOST: MS.local                                             	Loss%   Snt   Last   Avg  Best  Wrst StDev
  1.|-- 172.16.0.1                                            	0.0%	10	0.8   1.2   0.3   4.6   1.3
  2.|-- no-ptr.ziax.ltd (XXX.XXX.XXX.XXX)                       	0.0%	10	0.9   0.8   0.6   1.4   0.2
  3.|-- 62.7.117.42                                           	0.0%	10	7.5   7.6   7.2   8.4   0.3
  4.|-- core2-hu0-3-0-7.colindale.ukcore.bt.net (217.32.170.174)  0.0%	10	7.1   7.2   6.5   8.2   0.5
  5.|-- core6-hu0-3-0-15.faraday.ukcore.bt.net (109.159.252.134) 20.0%	10	7.5   7.7   7.0   9.0   0.6
  6.|-- 166-49-209-194.gia.bt.net (166.49.209.194)            	0.0%	10	7.5   7.6   7.2   8.8   0.5
  7.|-- t2c4-et-5-3-0.de-fra.gia.bt.net (166.49.195.103)      	0.0%	10   20.5  21.4  20.2  24.5   1.4
  8.|-- decix-gw.hetzner.com (80.81.192.164)                  	0.0%	10   20.8  20.8  20.3  22.0   0.4
  9.|-- core11.nbg1.hetzner.com (213.239.252.22)              	0.0%	10   25.8  26.2  25.5  29.3   1.2
 10.|-- blocked.hetzner.com (88.198.253.78)                   	0.0%	10   28.1  35.7  28.1  76.1  14.4
 11.|-- ???                                                  	100.0	10	0.0   0.0   0.0   0.0   0.0
 12.|-- blocked.hetzner.com (88.198.253.78)                  	90.0%	10  2906. 2906. 2906. 2906.   0.0

MTR (My Traceroute) shows the path packets take to a given Geyser server. In the 10th and 12th hop, we can see that the packet is being routed to the hostname blocked.hetzner.com, implying traffic to the server is being null-routed.

Mitigation​

Multiple forms of mitigation for this bug, as well as preventive measures to guard against future attacks have been introduced into Geyser and its upstream networking library. These include proper reliability handling during the early RakNet connection, early cookie verification, and rate limiting.

Proper Reliability Handling in Early RakNet Connection​

The principal mitigation was changing the reliability type of the abused packet to unreliable. This means that the server will no longer respond to NAK requests for it, effectively leading to the attackers requests going unanswered. The packet capture below is taken from an instance with the reliability type of Connection Request Accepted changed to unreliable. We can see that the attacker simply continues to increment their packet range requested by NAK, but no response is provided.

Wireshark packet capture of a Geyser instance under attack with a build mitigating the original attack vector. The attacker is seen sending NAK packets with a sequence range of as high as 40,959. However, since the packet was not sent as reliable, there is nothing for the Geyser instance to send in response.

Early Cookie Verification​

The underlying issue that allows for UDP amplification attacks is a lack of verification at an early stage of the connection. The original RakNet protocol actually specifies an optional solution for this. For context, RakNet was purchased by Oculus in 2014, and open sourced. Given the acquisition of Oculus by Facebook, the code for the original implementation is now archived by them. While Mojang’s implementation of RakNet has some differences from the original, it does share many of the same features. In the packet Open Connection Reply 1, the original specification refers to a boolean HasSecurity, followed by a four byte cookie if the boolean is true.

This is an excerpt from the original RakNet source containing the packet identifier enums. The comments above each enum define the packet structure. These packets from the initial login sequence are largely unchanged in Mojang’s RakNet implementation, though it does not appear that the client has any support for full encryption as defined in the original specification. This can be inferred because when the HasSecurity boolean and cookie is sent by the server in Open Connection Reply 1, Open Connection Request 2 by the client does include the cookie, but sets the clientSupportsSecurity boolean to false.

It turns out that if a cookie is supplied by the Bedrock server in Open Connection Reply 1, the Bedrock client will reply with the same cookie. This allows us to effectively verify that the IP of the Bedrock client is not being spoofed by the third packet. Were the IP of the Bedrock client being spoofed, the packet containing the cookie would be sent to the victim’s IP and be unknown to the attacker. If the attacker sends back an incorrect cookie, the connection can be terminated at that point.

Rate Limiting​

In addition, Cloudburst Network also implemented three main rate limits to prevent further potential abuse of the protocol. These are summarized in the table below.

Geyser initially rolled out a fix that forced these defaults, but has since been updated to allow them to be configured with system properties that are documented on the Geyser Wiki.

These defaults may present an issue to those running a reverse proxy in front of their Geyser instance, particularly those utilizing DDoS mitigation services like TCPShield and CosmicGuard, as to Network it will appear that all connections are originating from the same IP. To make configuration on these services easier, Geyser will disable these rate limits provided proxy protocol is enabled for the bedrock connection, and the Geyser instance is properly configured to only accept connections from the IPs of the proxy. To simplify this configuration, Geyser’s config can now accept a URL to specify proxy server IP ranges. Many DDoS mitigation providers have a static link to an always up to date text file of these.

advanced.bedrock:
# ...
  use-haproxy-protocol: true
  haproxy-protocol-whitelisted-ips: [ "https://cosmic.global/ips/", "https://tcpshield.com/v4/" ]

Geyser configuration using a URL pointing a new-line separated text file containing allowed IPs for haproxy-protocol usage.

Long Term Impact​

It is extremely important that all those running vulnerable instances of Geyser update as soon as possible. Failure to do so may result in your Geyser instance being used to harm others via UDP denial of service amplification. We continue to see this issue being exploited in the wild as of the writing of this post, and see no reason that will stop in the foreseeable future. The number of unpatched instances will likely decrease over time as Bedrock updates force server owners to update in order to support players on the latest Bedrock version.

Acknowledgements​

We thank the community for their patience as we addressed this issue, all those who responsibly disclosed this issue to us, the developers at Cloudburst and Geyser that worked to mitigate the issue, the server hosts that took an active role in ensuring instances on their hosting services were patched as soon as possible, all donors for their financial support of Geyser, and Cubecraft for their continued financial and operational support of the project.

New: item components​

Gone is the item NBT to serialize extra data over the network. 1.20.5 introduces data components, which replaces the guesswork of NBT with strict objects attached to each class.

We’ve also been able to get rid of unreachable code from before the server inventory rewrite, back when creative mode Bedrock had the potential ability to delete NBT from items just from moving them around.

NBT refactor​

Since items no longer have NBT, we decided it was a good time to switch to using one NBT library. Our Bedrock protocol library used Cloudburst’s NBT implementation, whereas our Java protocol library used OpenNBT. The latter has been severely neglected, and still has several cases of weird or outdated implementations, such as tag names being present in tag value objects. The entire project now uses Cloudburst’s NBT library, which is far nicer to use overall:

boolean piglinSafe = ((Number) dimension.get("piglin_safe").getValue()).byteValue() != (byte) 0;

Changes to:

boolean piglinSafe = dimension.getBoolean("piglin_safe");

Better tag extensibility​

Block and item tags are now enums - this example diff to add support for one tag…

…would now be adding one line of a new enum in the ItemTag class. And we had to add a handful of enums to add support for data-driven animal loved foods... imagine the complexity with the first style of code!

No more trim recipe hardcoding​

Because the server now sends all trim recipes through a packet as a registry, we’re able to get rid of this block of code that was required for trim recipes to be handled. Yay to no hardcoding!

Entity properties​

Bedrock’s newer entity property system has now found a use in vanilla Bedrock - it controls the armadillo’s animation state (and without it, an armadillo will default to staying inside its shell!). Kastle came through and ported some work-in-progress code so Geyser is able to work with the new system.

Special Thanks​

This update would have been a nightmare without the many hands we had to help implement everything we needed to get done.

basaigh implemented the huge item changes in MCProtocolLib in a very timely fashion, meaning that Geyser could get right to updating its own code.

AJ Ferguson and Chris both helped with implementing new features and fixing regressions.

Kastle, hot off the heels of stronger security protections on the Bedrock side, assisted with custom skull reimplementation and entity properties implementation.

Today is a super special day - it's Geyser's birthday 🥳. Geyser is now four years old and booyyy has it come a long way! This is a huge day for us and an incredible milestone. We're very proud of how far we've been able to come, the amount of servers Geyser has expanded the reach of, and the amazing community behind Geyser. Seeing millions of players being able to play with their Java friends is something I never dreamed Geyser would be able to do. The growth from day one has been amazing and we're all very grateful for everyone's support 💙

Not only is this a special day because it's our birthday, but we have some exiting news and sneak peeks to share with you all, alongside general updates on our project development. Continue reading for more information!

Project Statistics​

• Since the start of the project, there have been 3,337 commits contributed by 105 contributors
• As of just a few days ago, Geyser has hit 4,000 stars on GitHub, making it one of the top open-source Minecraft projects ever, and the #1 Minecraft Bedrock project
• Our Discord server has continued to grow, now approaching 25,000 Discord members

None of these would have been possible without our amazing community. To that, we owe a debt of gratitude for the years of support from all of you 💙

Project Development​

It's likely well-known by now that Geyser has hit a state of maturity. Since about 2021, Geyser has reached the point of full survival and creative playability for Bedrock clients on Java servers. This has allowed us to place much more focus on improving stability, fixing bugs and designing a resilient platform. We've spent the latter half of last year designing an API for Geyser, creating an extension system, and ultimately adding more for developers. A couple notable additions include custom item support and a resource pack API.

We've also made some major internal changes, one of the biggest being updating our Bedrock protocol library to version 3.0. This was a massive undertaking by the CloudburstMC organization, which we work closely with. While a bit bumpy at first, these changes modernized the internal RakNet library and brought along some sweet network optimizations on the Bedrock side.

At a steady pace, we're also working on integrating Floodgate and Geyser together! While Floodgate will still exist as a separate project for proxy and standalone instances, we are working on shipping it inside Geyser to improve setup processes and reduce complexity when creating Geyser servers. One of our goals internally has been to make the Geyser setup as seamless as possible, and this is just one way we're doing that! We'll share more on this once it gets closer to completion.

What's Next?​

With Geyser being in a state of maturity in terms of vanilla compatibility, we're shifting our attention onto expanding all the "custom" features Bedrock supports. There's a huge and growing demand for utilizing many of Bedrock's custom features, such as resource packs, entities, blocks, items and UIs. One of our biggest goals going forward is to design a platform that allows developers and server owners to bring their server to the next level for Bedrock players.

API Additions​

Recently, we added a resource pack loading API which allows for developers to fine-tune and integrate their resource packs through the Geyser API, and are actively working on even more, such as custom blocks and custom entities. These are just a few things we're doing inside the Geyser API, but that's not all we have in store!

Resource Pack Conversion​

Some of you who were around a few years ago may remember we used to maintain a resource pack conversion project. Well, we've decided to revive this project! While we know that third party projects exist now and handle conversions fairly well, we're working to make this part of mainline Geyser to further simplify the work needed by server owners and plugin developers. This means that once the project is integrated into Geyser, pack conversion will happen automatically. Contributions are most certainly welcome and please do reach out on Discord if you'd like to get involved!

Wait, there's more???​

There is! And the exciting news is we're expanding Geyser to Forge! Of all the major platforms we support, Forge is one of the ones we do not support. We want to further expand the Geyser ecosystem, and I'm happy to announce that Geyser is coming to Forge in the next couple of weeks! This will also include some improvements to the Fabric platform as well. One such change is an integrated world manager, which exists only on Spigot platforms currently. This means Geyser will use the server to retrieve things such as blocks, significantly reducing the amount of RAM used for caching world data.

Additionally, since the Forge and Fabric platforms will use a common codebase for 95% of everything, thanks to Architectury, we can update both platforms very easily and changes that happen to one in most cases will carry over to the other.

One more thing...​

Not only are we wanting to expand what Geyser can do with custom features on vanilla servers, but there's a lot we want to do with both Fabric and Forge in the near future. Keep an eye out for further announcements over the next few weeks 👀🍰🥳

And that's all I have to share for today! Once again, thank you all for your continued support over the years and we cannot wait to see the creativity you unleash on your server with these features! In typical Geyser fashion, here is a Gource render of all commits since the start of the project: https://youtu.be/ss6GlUkVgEE

2022 for Geyser was, in comparison to other years, rather unremarkable in terms of new features. Whereas 2021 had Bedrock skin support and complete inventory support, and 2020 had movement fixes, this year felt largely like a maintenance year. I think that’s a good thing; it means we’ve reached the point where the only things left to do are bug fixes, niche features/behavior, or updates. Even so, here are some of the notable points from Geyser in 2022, and what’s next.

Yearly GitHub Stats​

In 2022, we had 519 commits from 59 contributors, 85 merged PRs, and 869 new stars on the repository. The reach Geyser continues to get every year is positively astounding.

(Nearly) Every Floodgate Instance Breaking​

On February 2nd, 2022, Mojang snuck in a change to their API which resulted in almost every Floodgate instance involving the Paper server software breaking (likely due to this Paper patch) - even Floodgate instances only on the proxy. We swiftly put mitigations in place, and while I hope such an issue never has to happen again, the day presented a once-in-a-lifetime unique challenge in fixing a sudden, serious bug that we did not induce, and it’s a reminder that part of the job at Geyser is working around whatever changes Mojang throws at us, inside or outside of updates.

Custom Item Support​

Finally, Java’s CustomModelData system is now supported on Bedrock. This change is largely thanks to ImDaBigBoss, who created the PR back in February, and Kastle, who has worked to map Java packs to Bedrock as effortlessly as possible.

Dedicated Wiki​

We now have a dedicated wiki, allowing users to contribute documentation without allowing random changes from anyone.

Extensions​

After two years of theory and concepts, Geyser extensions are now possible, allowing for improved interaction with Bedrock clients to take advantage of what the Bedrock platform has to offer. These work very similar to plugins and allow for developers to write code specifically for Bedrock and Geyser features using the Geyser API. In 2023, we hope to see more API additions that allow for servers, plugins and mods to shine in creativity.

Geyser-Fabric Joins the Main Repository​

Geyser-Fabric is now a part of the main Geyser repository, instead of being relegated to a separate repository. This will ensure that the Fabric mod always gets the latest changes to Geyser, and isn’t prone to losing out on updates.

Secure Profiles and Geyser​

The 1.19 Java updates added new changes that allowed player chat to be verified and reported to Mojang. Bedrock as it stands is essentially incompatible with these changes; before 1.19.3, requiring that all players chat securely (enabling enforce-secure-profile in server.properties) would prevent Bedrock from joining. Thankfully, in 1.19.3, that same setting now allows Bedrock players to join, just without the ability to chat.

Almost 100% Day-One Updates​

I’m very proud of all our developers and contributors that are able to get updates ready before each Minecraft release. Two years ago for 1.16, we were unable to have an update ready before the release date. Now, we are in a place to be consistently prepared for supporting auto-updating Bedrock clients by having a Geyser version released by the day of. The almost exception this year was the Bedrock 1.19.21 update released in August - while it was supposed to be a patch update, it surprised the entire Bedrock community (even featured servers) by being incompatible with the prior 1.19.20 version without any notice from Mojang. There was no notable difference, and we were able to push an update in about an hour after we discovered the incompatibility.

Upcoming: Geyser and Floodgate Merge​

As we look to 2023, one of my goals as a project lead on Geyser is ensuring the setup and update process is as smooth and secure as possible. Having two plugins for users to worry about isn’t fun, and many support requests we get have no idea that they need Floodgate for Bedrock players to join without needing a Java account. While Floodgate has to stick around for backend servers and Geyser Standalone, we want to package Floodgate functionality into Geyser for improved efficiency, to fix some annoying bugs where having duplicate classes causes API errors, and to simplify how many plugins you need to install to get Geyser running.

Overall, I’m really happy and very grateful to see Geyser where it is today. We have 20,000 running Geyser instances, with 10,000 players combined on all of them. We have an amazing community, and the support of many in the wider Minecraft community. 2023 promises more good changes - here’s to it!

Welcome to the new Geyser blog! We’ll be posting new content here periodically about project updates, future plans, project announcements and really just miscellaneous development-related content around the Geyser project(s). These will be linked in our #blog-feed channel on Discord, so if you want to be notified when we make new posts and such, feel free to either follow the channel in your own Discord server, or turn on notifications.

Introduction:​

In this post, we will be covering all the changes that led up to the 1.18 release. With 1.18 came a huge set of changes for Geyser which although may not be visible to the end user, were a massive feat internally. This resulted in not only multiple project refactors of Geyser along with surrounding projects (PacketLib, MCProtocolLib, etc.) but many additional optimizations and improvements to how the code operated and ran. For the latter half of 2021 especially, we’ve been putting in a lot more time to ensure Geyser runs more smoothly and to optimize poorly performing parts of the code, so much of these changes were a direct result of that initiative.

Writing a New Java Edition Protocol Library:​

To preface, we were not initially planning to do this big refactor all at once, but one thing led to another and here we are. Our initial plans were actually quite a bit different, with us initially planning to deprecate and remove MCProtocolLib from our codebase, and instead implement support for Java Edition inside of Protocol, our Bedrock Edition protocol library. We actually got it to a point where you could join and properly send/receive packets quite well!

This was inline with our plans to continually improve performance and maintainability with Geyser, since using a library where much of the code is the same across both the Java & Bedrock protocol libraries would reduce much of the additional work we need to do in. A good example of this is inside our ItemTranslator class, where we translate NBT objects from that used inside of MCProtocolLib, to that used inside of our Bedrock protocol library. We were intending to have this done with 1.18 since the update itself was not too drastic, meaning we could spend much more time on Geyser itself, rather than trying to update to the protocol.

Taking over MCProtocolLib:​

However our plans completely changed when Steveice10, the maintainer of MCProtocolLib at the time, reached out and asked if we wanted to take over the project. At first we were a bit hesitant as we had already put in quite a bit of work to our new library, but as MCProtocolLib was already an integral part of Geyser from the very beginning and we had essentially been maintaining the library for the past year or so, we all came to the consensus that scrapping the library would be a poor idea, both for us as well as the wider community who was also using this library. We decided to take over it.

With us now being in full control of MCProtocolLib, that gave us much more freedom to update and improve the project that we previously were unable to do. Rather than go on with a new library altogether, we felt it would be better to gradually port over much of our work into MCProtocolLib. With the release of 1.18 still lingering, we decided to jump the gun and start on a massive refactor of packets, with us adopting Mojang-mapped packet names. This is something we were doing inside of Protocol for Java Edition and with more and more projects adopting these names and for the sake of unity across the board, we felt now was the best time to make this decision.

Improving Performance in MCProtocolLib:​

During the process of renaming packets to use Mojmap names, we found that most of the performance bottlenecks with MCProtocolLib & Geyser did not particularly lie with object translation, since it's relatively cheap in the grand scheme of things, but just the ways in which the library operated itself.

What we identified is that inside of MinecraftProtocol, the main class inside of MCProtocolLib, that it was re-registering the Minecraft protocol individually for every player individually, any time the protocol state changed. To give a bit more background on this - the Minecraft protocol operates over four individual state. The first is the handshaking state, which is the state set when a client first makes a connection the Minecraft server. Once the handshake has completed, the next state is either the login or the status state. The status state is set when a client pings the server from the server list and never actually joins, while the login state is for when the client is logging into the server. Once the login is complete, the server then goes on to the game state, where you actually recieve packets that let you interact with the world.

Below is an example of what MCProtocolLib was doing previously, any time you switched from the login state to the game state:

private void initGame(BiConsumer<Integer, Class<? extends Packet>> clientboundPackets, BiConsumer<Integer, Class<? extends Packet>> serverboundPackets) {
        clientboundPackets.accept(0x00, ServerSpawnEntityPacket.class);
        clientboundPackets.accept(0x01, ServerSpawnExpOrbPacket.class);
        clientboundPackets.accept(0x02, ServerSpawnLivingEntityPacket.class);
        clientboundPackets.accept(0x03, ServerSpawnPaintingPacket.class);
        clientboundPackets.accept(0x04, ServerSpawnPlayerPacket.class);
        clientboundPackets.accept(0x05, ServerAddVibrationSignalPacket.class);
        clientboundPackets.accept(0x06, ServerEntityAnimationPacket.class);
        clientboundPackets.accept(0x07, ServerStatisticsPacket.class);
        clientboundPackets.accept(0x08, ServerPlayerActionAckPacket.class);
        clientboundPackets.accept(0x09, ServerBlockBreakAnimPacket.class);
        clientboundPackets.accept(0x0A, ServerUpdateTileEntityPacket.class);
        clientboundPackets.accept(0x0B, ServerBlockValuePacket.class);
        clientboundPackets.accept(0x0C, ServerBlockChangePacket.class);
        clientboundPackets.accept(0x0D, ServerBossBarPacket.class);
        clientboundPackets.accept(0x0E, ServerDifficultyPacket.class);
        clientboundPackets.accept(0x0F, ServerChatPacket.class);
        clientboundPackets.accept(0x10, ServerClearTitlesPacket.class);
        clientboundPackets.accept(0x11, ServerTabCompletePacket.class);
        clientboundPackets.accept(0x12, ServerDeclareCommandsPacket.class);
        clientboundPackets.accept(0x13, ServerCloseWindowPacket.class);
        clientboundPackets.accept(0x14, ServerWindowItemsPacket.class);
        clientboundPackets.accept(0x15, ServerWindowPropertyPacket.class);
        clientboundPackets.accept(0x16, ServerSetSlotPacket.class);
        clientboundPackets.accept(0x17, ServerSetCooldownPacket.class);
        clientboundPackets.accept(0x18, ServerPluginMessagePacket.class);
        // this continues for more than 100 more packets

With the above code, every game packet would be registered into a new map. This was a far less than ideal situation, given that hundreds of packets would be registered, and this was something called for every client. We opted to replace this with a static registry which instead holds these values just once. Any time the sub-protocol changes, it instead just pulls from this static codec instead, rather than populating a map every time.

We also identified other areas where code was running poorly - previously, every packet was constructed through reflection, which we realized could easily be replaced with a packet factory. Nowadays, the packet registration code is only constructed once, and the player's protocol state determines which map to pull packets from.

With all these changes consolidated into an individual codec, it also opens the door for multi-version compatibility - something we were initially planning to do with our Java Edition work in Protocol. Although not officially supported yet nor something we have fully committed to, these changes will allow that capability in the future, and implementing projects technically could implement the capability to do so if they please.

Refactoring Geyser:​

With the massive changes inside MCProtocolLib already lining up, we already foresaw the changes in Geyser being quite drastic. With plans for extensions and a more streamlined API being in the plans for over a year, we felt that now was the best time to start moving along with that. This initially started with a massive refactor of the packages inside of Geyser. Previously, everything involved with the work Geyser did with packet translation and whatnot lied in the connector module of the project. This name was slightly confusing for many as Geyser does much more than just "connecting you to a server." With that being said, we decided to rename the module to core and update the packaging for it from org.geysermc.connector to org.geysermc.geyser.

Along with the package name changes, we decided to start implementing a new API. At the time of writing, this is still something that is very much a work in progress, however this will make it much easier to write projects that interop with Geyser & Floodgate in a much more streamlined fashion, and allow for extensions to have a solid base to build off of.

Improving Code in Geyser:​

As mentioned earlier in this post, one of our plans was to eventually move away from MCProtocolLib due to the additional translation we have to do between MCProtocolLib and Protocol objects. However, as we continued working on both the MCProtocolLib changes and the Geyser refactor, we identified that these translations were not the sources of most performance bottlenecks inside of Geyser itself. This led to us refactoring our entity system inside of Geyser, not solely for the sake of performance, but also for the sake of better usability and understanding.

public void updateBedrockMetadata(EntityMetadata entityMetadata, GeyserSession session) {
        switch (entityMetadata.getId()) {
            case 0:
                if (entityMetadata.getType() == MetadataType.BYTE) {
                    byte xd = (byte) entityMetadata.getValue();
                    metadata.getFlags().setFlag(EntityFlag.ON_FIRE, ((xd & 0x01) == 0x01) && !metadata.getFlags().getFlag(EntityFlag.FIRE_IMMUNE)); // Otherwise immune entities sometimes flicker onfire
                    metadata.getFlags().setFlag(EntityFlag.SNEAKING, (xd & 0x02) == 0x02);
                    metadata.getFlags().setFlag(EntityFlag.SPRINTING, (xd & 0x08) == 0x08);
                    // Swimming is ignored here and instead we rely on the pose
                    metadata.getFlags().setFlag(EntityFlag.GLIDING, (xd & 0x80) == 0x80);

                    setInvisible(session, (xd & 0x20) == 0x20);
                }
                break;
            case 1: // Air/bubbles
                setAir((int) entityMetadata.getValue());
                break;
            case 2: // custom name
                if (entityMetadata.getValue() instanceof Component message) {
                    // Always translate even if it's a TextMessage since there could be translatable parameters
                    metadata.put(EntityData.NAMETAG, MessageTranslator.convertMessage(message, session.getLocale()));
                }
                break;
            case 3: // is custom name visible
                if (!this.is(PlayerEntity.class))
                    metadata.put(EntityData.NAMETAG_ALWAYS_SHOW, (byte) ((boolean) entityMetadata.getValue() ? 1 : 0));
                break;
            case 4: // silent
                metadata.getFlags().setFlag(EntityFlag.SILENT, (boolean) entityMetadata.getValue());
                break;
            case 5: // no gravity
                metadata.getFlags().setFlag(EntityFlag.HAS_GRAVITY, !(boolean) entityMetadata.getValue());
                break;
            case 6: // Pose change - typically used for bounding box and not animation
                Pose pose = (Pose) entityMetadata.getValue();

                metadata.getFlags().setFlag(EntityFlag.SLEEPING, pose.equals(Pose.SLEEPING));
                // Triggered when crawling
                metadata.getFlags().setFlag(EntityFlag.SWIMMING, pose.equals(Pose.SWIMMING));
                setDimensions(pose);
                break;
            case 7: // Freezing ticks
                // The value that Java edition gives us is in ticks, but Bedrock uses a float percentage of the strength 0.0 -> 1.0
                // The Java client caps its freezing tick percentage at 140
                int freezingTicks = Math.min((int) entityMetadata.getValue(), 140);
                setFreezing(session, freezingTicks / 140f);
                break;
        }
    }

Looking at the code above, our previous code for translating entity metadata was extremely scattered and utilized many magic “numbers” associated with entity translation. These types of switch statements were all over various entity classes, and were quite messy.

To explain the above code in more detail - the way Minecraft Java sends entity metadata over the protocol is that it associates an id for every entity metadata “type”. Looking at the above code, id 3 for example, is associated with whether an entity’s name is visible above their head. The problem with handling our code like this is that if Mojang decides to add a new entity metadata field at id 2 for example, everything above that will be incremented by 1, so 'custom name visible' would have an id of 4, rather than 3 in future updates. Along with the code being so scattered, it meant that we would need to increment ids inside of every entity class, which was far less than ideal.

What we opted to do to remedy this issue is to instead not use massive if or switch statements on the ids, but to register these values inside of a list, and add them based on the order they should be translated in.

EntityDefinition<Entity> entityBase = EntityDefinition.builder((BaseEntityFactory<Entity>) Entity::new)
        .addTranslator(MetadataType.BYTE, Entity::setFlags)
        .addTranslator(MetadataType.INT, Entity::setAir) // Air/bubbles
        .addTranslator(MetadataType.OPTIONAL_CHAT, Entity::setDisplayName)
        .addTranslator(MetadataType.BOOLEAN, Entity::setDisplayNameVisible)
        .addTranslator(MetadataType.BOOLEAN, (entity, entityMetadata) -> entity.setFlag(EntityFlag.SILENT, ((BooleanEntityMetadata) entityMetadata).getPrimitiveValue()))
        .addTranslator(MetadataType.BOOLEAN, Entity::setGravity)
        .addTranslator(MetadataType.POSE, Entity::setPose)
        .addTranslator(MetadataType.INT, Entity::setFreezing)
        .build();

All that code shown earlier has been condensed into the following. Now, if Mojang is to add a new metadata field at id 2 for instance, we can simply just plug it in as the third value, and boom, everything else will automatically be incremented!

In regards to performance, previously all the entity data had been held in an EntityType enum, which was not the best for constructing more complex entity objects. This meant we had to use reflection for constructing entities which as mentioned earlier, was used inside of MCProtocolLib, and was slower than what we wanted. This too was replaced with an entity factory, and can be seen in the above code snippet.

New API, Extensions, and Looking Onward:​

As brought up multiple times throughout this post, we have been spending time working up a new API. We eventually want to bring in extensions to Geyser, which act as plugins on their own except they are loaded from Geyser itself. With more and more people and larger servers adopting Geyser, many more unique and niche usecases have popped up which don’t particularly fit inside of Geyser itself, but would still benefit users as a whole. As Geyser is capable of running on 6 platforms at this point in time (Spigot, Sponge, Standalone, Velocity, Fabric and BungeeCord, with Forge likely on the way), as a developer, creating a separate addon capable of running on all these platforms is far less than ideal. We’ve opted to get around this by creating a new extension system, allowing developers to create an extension one time for Geyser, and it being capable of running on any of these platforms.

This extension API has not been created yet however, and plans for the base API inside of Geyser are still being finalized. We also intend to start moving most of Floodgate into Geyser itself, so unless you are running Floodgate independently from Geyser (e.g. you use Geyser Standalone but run Floodgate on the proxy), in the near future you will only need to install Geyser, and Floodgate’s functions will all be handled automatically in Geyser.

With that coming up, we also want to design the base API to be agnostic in the sense that basic functions such as retrieving how many players are online can be done using the same API, whether the server has just Geyser installed or just Floodgate. But at the same time, we also want to make it easy to utilize a more-specific Floodgate and Geyser API.

Anyway, that about wraps up the first post! Thanks for reading and feel free to offer any feedback about the topics covered in our Discord server!