Skip to content

Networking

A NetworkChannel sends a mod’s own packets between server and client on every loader, with a protocol version that keeps mismatched clients out. Use it when the server must tell clients something vanilla does not sync, or a client must ask the server.

Type Summary Status Since Side Thread
ClientNetworking Sends and receives a NetworkChannel’s packets on the client. Experimental 2.0.0 client render
ClientPacketHandler Handles a decoded clientbound packet. Experimental 2.0.0 client netty-handoff
NetworkChannel A mod’s network channel with a protocol version. Experimental 2.0.0 both setup
PacketType One packet declared on a NetworkChannel, used to send it. Experimental 2.0.0 both any
ServerPacketHandler Handles a decoded serverbound packet. Experimental 2.0.0 server netty-handoff

With player, a ServerPlayer on the server thread:

Show a message from the server above a client's hotbar
// Common initialization:
static final NetworkChannel NET = NetworkChannel.create(id("main"), 1);
public static final PacketType<String> NOTICE =
NET.clientbound("notice", (key, buf) -> buf.writeUtf(key), FriendlyByteBuf::readUtf);
// Server thread: the message is a translation key, so each client shows its own language.
NET.sendToPlayer(player, NOTICE, "notice.mymod.paths_off");
// Client initialization:
ClientNetworking.receive(NOTICE,
key -> Minecraft.getInstance().gui.setOverlayMessage(Component.translatable(key), false));

ClientPacketHandler: Experimental · Since 2.0.0 · Side: client · Thread: netty-handoff

NetworkChannel: Experimental · Since 2.0.0 · Side: both · Thread: setup

PacketType: Experimental · Since 2.0.0 · Side: both · Thread: any

ServerPacketHandler: Experimental · Since 2.0.0 · Side: server · Thread: netty-handoff

NetworkChannel carries a mod’s own packets in both directions. Declare the channel and its packets in common initialization. Here a client asks for the server’s settings, and the server answers from Settings.FILE, the mod’s ConfigFile. The records and the packet types are public because client code, in the mod’s client package, reads them:

Declare a query the server answers
public record SettingsQuery() {}
public record ServerSettings(boolean pathsEnabled, float wearRate) {
// The one place the packet is built from the settings file's view.
public static ServerSettings of(Settings settings) {
return new ServerSettings(settings.pathsEnabled(), settings.wearRate());
}
void write(FriendlyByteBuf buf) {
buf.writeBoolean(pathsEnabled);
buf.writeFloat(wearRate);
}
static ServerSettings read(FriendlyByteBuf buf) {
return new ServerSettings(buf.readBoolean(), buf.readFloat());
}
}
static final NetworkChannel NET = NetworkChannel.create(id("main"), 1);
public static final PacketType<ServerSettings> SETTINGS =
NET.clientbound("settings", ServerSettings::write, ServerSettings::read);
public static final PacketType<SettingsQuery> QUERY = NET.serverbound("query",
(query, buf) -> {}, buf -> new SettingsQuery(),
// Answer with the settings this server loaded.
(query, player) -> NET.sendToPlayer(player, SETTINGS, ServerSettings.of(Settings.FILE.get())));
  • A decoder that returns null drops the packet, as one that throws does.
  • Both ends of a connection always run the same loader.
  • The wire format differs between loaders.

Experimental · Since 2.0.0 · Side: client · Thread: render

With SETTINGS and QUERY from the NetworkChannel example, and serverSettings, a static ServerSettings field in a client-only class that the mod’s settings screen reads:

Receive and send packets on the client
// Client initialization:
ClientNetworking.receive(SETTINGS, settings -> serverSettings = settings);
// Leaving a world drops its server's settings; the next server sends its own.
ClientDisconnectCallback.EVENT.register(() -> serverSettings = null);
// When the player opens the settings screen while connected:
if (ClientNetworking.canSend(QUERY)) ClientNetworking.send(QUERY, new SettingsQuery());