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.
At a glance
Section titled “At a glance”| 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 |
Quick start
Section titled “Quick start”With player, a ServerPlayer on the server thread:
// 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));NetworkChannel
Section titled “NetworkChannel”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:
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.
ClientNetworking
Section titled “ClientNetworking”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:
// 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());See also
Section titled “See also”- Platform and integrations: whether another mod is loaded.
- Config files and settings screens.
- Send data from server to client: a guide that sends settings step by step.