SimpleChannel - Revision history

Ferri Arnus: /* Registering Packets */

2023-08-28T21:21:11Z

Registering Packets

Random832: /* Registering Packets */ fix errors and demonstrate new builder

2023-03-10T03:01:01Z

Registering Packets: fix errors and demonstrate new builder

ChampionAsh5357: There's your code example shrimp!

2022-03-29T00:30:35Z

There's your code example shrimp!

Nokko: /* Handling Packets */ Add proper titles for warning boxes + reorganize into “Common Pitfalls” section

2021-09-04T02:59:29Z

Handling Packets: Add proper titles for warning boxes + reorganize into “Common Pitfalls” section

Nokko: /* Handling Packets */ add warning about not registering encoders on the physical client. hopefully save someone 3 valuable hours of their life.

2021-09-03T21:17:05Z

Handling Packets: add warning about not registering encoders on the physical client. hopefully save someone 3 valuable hours of their life.

ChampionAsh5357: Update to 1.17

2021-08-02T19:24:02Z

Update to 1.17

Przemyk: changed name of EntityPlayerMP to ServerPlayerEntity

2021-01-03T13:04:55Z

changed name of EntityPlayerMP to ServerPlayerEntity

SciWhiz12: SciWhiz12 moved page Using SimpleChannel to SimpleChannel: rename to remove Using prefix

2020-11-08T16:26:55Z

SciWhiz12 moved page SimpleChannel to SimpleChannel: rename to remove Using prefix

Unbekannt: Inital Import dokuwiki

2020-10-24T20:42:31Z

Inital Import dokuwiki

New page

SimpleChannel is the name given to the packet system that revolves around the <code><nowiki>SimpleChannel</nowiki></code> class. Using this system is by far the easiest way to send custom data between clients and the server.

== Getting Started ==

First you need to create your <code><nowiki>SimpleChannel</nowiki></code> object. We recommend that you do this in a separate class, possibly something like <code><nowiki>ModidPacketHandler</nowiki></code>. Create your <code><nowiki>SimpleChannel</nowiki></code> as a static field in this class, like so:

<syntaxhighlight lang="java">
private static final String PROTOCOL_VERSION = "1";
public static final SimpleChannel INSTANCE = NetworkRegistry.newSimpleChannel(
new ResourceLocation("mymodid", "main"),
() -> PROTOCOL_VERSION,
PROTOCOL_VERSION::equals,
PROTOCOL_VERSION::equals
);
</syntaxhighlight>

The first argument is a name for the channel. The second argument is a <code><nowiki>Supplier<String></nowiki></code> returning the current network protocol version. The third and fourth arguments respectively are <code><nowiki>Predicate<String></nowiki></code> checking whether an incoming connection protocol version is network-compatible with the client or server, respectively.
Here, we simply compare with the <code><nowiki>PROTOCOL_VERSION</nowiki></code> field directly, meaning that the client and server <code><nowiki>PROTOCOL_VERSION</nowiki></code>s must always match or FML will deny login.

== Protocol Versions ==
If your mod does not require the other side to have a specific network channel, or to be a Forge instance at all, you should take care that you properly define your version compatibility checkers (the <code><nowiki>Predicate<String></nowiki></code> parameters) to handle additional "meta-versions" (defined in <code><nowiki>NetworkRegistry</nowiki></code>) that can be received by the version checker. These are:
* <code><nowiki>ABSENT</nowiki></code> - if this channel is missing on the other endpoint. Note that in this case, the endpoint is still a Forge endpoint, and may have other mods.
* <code><nowiki>ACCEPTVANILLA</nowiki></code> - if the endpoint is a vanilla (or non-Forge) endpoint.

Returning <code><nowiki>false</nowiki></code> for both means that this channel must be present on the other endpoint. If you just copy the code above, this is what it does. Note that these values are also used during the list ping compatibility check, which is responsible for showing the green check / red cross in the multiplayer server select screen.

== Registering Packets ==

Next, we must declare the types of messages that we would like to send and receive. This is done using the <code><nowiki>INSTANCE.registerMessage</nowiki></code> method, which takes 5 parameters.

* The first parameter is the discriminator for the packet. This is a per-channel unique ID for the packet. We recommend you use a local variable to hold the ID, and then call registerMessage using <code><nowiki>id++</nowiki></code>. This will guarantee 100% unique IDs.
* The second parameter is the actual packet class <code><nowiki>MSG</nowiki></code>.
* The third parameter is a <code><nowiki>BiConsumer<MSG, PacketBuffer></nowiki></code> responsible for encoding the message into the provided <code><nowiki>PacketBuffer</nowiki></code>
* The fourth parameter is a <code><nowiki>Function<PacketBuffer, MSG></nowiki></code> responsible for decoding the message from the provided <code><nowiki>PacketBuffer</nowiki></code>
* The final parameter is a <code><nowiki>BiConsumer<MSG, Supplier<NetworkEvent.Context>></nowiki></code> responsible for handling the message itself

The last three parameters can be method references to either static or instance methods in Java. Remember that an instance method <code><nowiki>MSG.encode(PacketBuffer)</nowiki></code> still satisfies <code><nowiki>BiConsumer<MSG, PacketBuffer></nowiki></code>, the <code><nowiki>MSG</nowiki></code> simply becomes the implicit first argument.

== Handling Packets ==

There are a couple things to highlight in a packet handler. A packet handler has both the message object and the network context available to it. The context allows access to the player that sent the packet (if on the server), and a way to enqueue threadsafe work.

<syntaxhighlight lang="java">
public static void handle(MyMessage msg, Supplier<NetworkEvent.Context> ctx) {
ctx.get().enqueueWork(() -> {
// Work that needs to be threadsafe (most work)
EntityPlayerMP sender = ctx.get().getSender(); // the client that sent this packet
// do stuff
});
ctx.get().setPacketHandled(true);
}
</syntaxhighlight>

Note the presence of <code><nowiki>setPacketHandled</nowiki></code>, which used to tell the network system that the packet has successfully completed handling.

{{Colored box|title=Alert|content=Packets are by default handled on the network thread.
 
That means that your handler can _not_ interact with most game objects directly.
Forge provides a convenient way to make your code execute on the main thread instead using <code><nowiki>IThreadListener.addScheduledTask</nowiki></code>.
Simply call <code><nowiki>ctx.get().enqueueWork(Runnable)</nowiki></code>, which will call the given <code><nowiki>Runnable</nowiki></code> on the main thread at the next opportunity.}}

{{Colored box|title=Alert|content=Be defensive when handling packets on the server. A client could attempt to exploit the packet handling by sending unexpected data.
 
A common problem is vulnerability to <code>arbitrary chunk generation</code>. This typically happens when the server is trusting a block position sent by a client to access blocks and tile entities. When accessing blocks and tile entities in unloaded areas of the world, the server will either generate or load this area from disk, then promply write it to disk. This can be exploited to cause <code>catastrophic damage</code> to a server's performance and storage space without leaving a trace.
 
To avoid this problem, a general rule of thumb is to only access blocks and tile entities if <code><nowiki>world.isBlockLoaded(pos)</nowiki></code> is true.}}

== Sending Packets ==

=== Sending to the Server ===

There is but one way to send a packet to the server. This is because there is only ever *one* server the client can be connected to at once. To do so, we must again use that <code><nowiki>SimpleChannel</nowiki></code> that was defined earlier. Simply call <code><nowiki>INSTANCE.sendToServer(new MyMessage())</nowiki></code>. The message will be sent to the handler for its type, if one exists.

=== Sending to Clients ===

Packets can be sent directly to a client using the <code><nowiki>SimpleChannel</nowiki></code>: <code><nowiki>HANDLER.sendTo(MSG, entityPlayerMP.connection.getNetworkManager(), NetworkDirection.PLAY_TO_CLIENT)</nowiki></code>. However, this can be quite inconvenient. Forge has some convenience functions that can be used:

<syntaxhighlight lang="java">
// Sending to one player
INSTANCE.send(PacketDistributor.PLAYER.with(playerMP), new MyMessage());

// Send to all players tracking this chunk
INSTANCE.send(PacketDistributor.TRACKING_CHUNK.with(chunk), new MyMessage());

// Sending to all connected players
INSTANCE.send(PacketDistributor.ALL.noArg(), new MyMessage());
</syntaxhighlight>

There are additional <code><nowiki>PacketDistributor</nowiki></code> types available, check the documentation on the <code><nowiki>PacketDistributor</nowiki></code> class for more details.

@@ Line 63: / Line 63: @@
     .encoder(MessagePacket::encoder)
     .decoder(MessagePacket::decoder)
-    .consumerMainThread(MessagePacket::messageConsumer);
+    .consumerMainThread(MessagePacket::messageConsumer)
 // You can use consumerMainThread or consumerNetworkThread.
 // If you use consumerMainThread, the builder will take care of the enqueueWork and setPacketHandled.

@@ Line 38: / Line 38: @@
 <syntaxhighlight lang="java">
-// A class MessagePacket
+class MessagePacket {
-public void encoder(FriendlyByteBuf buffer) {
+   public void encoder(FriendlyByteBuf buffer) {
-   // Write to buffer
+      // Write to buffer
-−
+   }
-public static MessagePacket decoder(FriendlyByteBuf buffer) {
+   public void messageConsumer(Supplier<NetworkEvent.Context> ctx) {
-  // Create packet from buffer data
+      // Handle message
+}
-public void messageConsumer(Supplier<NetworkEvent.Context>> ctx) {
+// Original direct registration syntax
-  // Handle message
+INSTANCE.registerMessage(id, MessagePacket.class,
+   MessagePacket::encoder,
-// For some SimpleChannel channel
+// New builder-based definition
-channel.registerMessage(id, MessagePacket::encoder, MessagePacket::decoder, MessagePacket::messageConsumer);
+INSTANCE.messageBuilder(MessagePacket.class, id)
 </syntaxhighlight>

← Older revision		Revision as of 00:30, 29 March 2022
Line 36:		Line 36:

	The last three parameters can be method references to either static or instance methods in Java. Remember that an instance method <code><nowiki>MSG.encode(FriendlyByteBuf)</nowiki></code> still satisfies <code><nowiki>BiConsumer<MSG, FriendlyByteBuf></nowiki></code>, the <code><nowiki>MSG</nowiki></code> simply becomes the implicit first argument.		The last three parameters can be method references to either static or instance methods in Java. Remember that an instance method <code><nowiki>MSG.encode(FriendlyByteBuf)</nowiki></code> still satisfies <code><nowiki>BiConsumer<MSG, FriendlyByteBuf></nowiki></code>, the <code><nowiki>MSG</nowiki></code> simply becomes the implicit first argument.
		+
		+	<syntaxhighlight lang="java">
		+	// A class MessagePacket
		+	public void encoder(FriendlyByteBuf buffer) {
		+	// Write to buffer
		+	}
		+
		+	public static MessagePacket decoder(FriendlyByteBuf buffer) {
		+	// Create packet from buffer data
		+	}
		+
		+	public void messageConsumer(Supplier<NetworkEvent.Context>> ctx) {
		+	// Handle message
		+	}
		+
		+	// For some SimpleChannel channel
		+	channel.registerMessage(id, MessagePacket::encoder, MessagePacket::decoder, MessagePacket::messageConsumer);
		+	</syntaxhighlight>

	== Handling Packets ==		== Handling Packets ==

@@ Line 72: / Line 72: @@
 Note the presence of <code><nowiki>#setPacketHandled</nowiki></code>, which used to tell the network system that the packet has successfully completed handling.
-{{Colored box|title=Alert|content=Packets are by default handled on the network thread.
+=== Common Packet Handling Pitfalls ===
-<br><br>
-That means that your handler can _not_ interact with most game objects directly.
+{{Colored box|title=Know that packets are by default handled on the network thread.|content=
 Forge provides a convenient way to make your code execute on the main thread through the supplied <code><nowiki>NetworkEvent$Context</nowiki></code>.
 Simply call <code><nowiki>NetworkEvent$Context#enqueueWork(Runnable)</nowiki></code>, which will call the given <code><nowiki>Runnable</nowiki></code> on the main thread at the next opportunity.}}
-{{Colored box|title=Alert|content=Be defensive when handling packets on the server. A client could attempt to exploit the packet handling by sending unexpected data.
+{{Colored box|title=Be defensive when handling packets on the server.|content=
-<br><br>
+A client could attempt to exploit the packet handling by sending unexpected data.
 A common problem is vulnerability to <code>arbitrary chunk generation</code>. This typically happens when the server is trusting a block position sent by a client to access blocks and block entities. When accessing blocks and block entities in unloaded areas of the level, the server will either generate or load this area from disk, then promply write it to disk. This can be exploited to cause <code>catastrophic damage</code> to a server's performance and storage space without leaving a trace.
 <br>
 To avoid this problem, a general rule of thumb is to only access blocks and block entities if <code><nowiki>Level#hasChunkAt</nowiki></code> is true.}}
-{{Colored box|title=Alert|content=Remember that DistExecutor runs on the '''physical side''', not the logical side.
+{{Colored box|title=Register encoders on the physical client, as well as the physical server.|content=
 If you only register an encoder for a clientbound packet on the physical server, your mod will likely crash or present unintended behaviour in single-player worlds. ''Forge will happily send packets that have no encoder defined, '''without a warning or error message!''''' They will be encoded as a 256-long byte buffer filled only with null bytes, by default.
 <br>}}

@@ Line 83: / Line 83: @@
 <br>
 To avoid this problem, a general rule of thumb is to only access blocks and block entities if <code><nowiki>Level#hasChunkAt</nowiki></code> is true.}}
 == Sending Packets ==

@@ Line 31: / Line 31: @@
 * The first parameter is the discriminator for the packet. This is a per-channel unique ID for the packet. We recommend you use a local variable to hold the ID, and then call registerMessage using <code><nowiki>id++</nowiki></code>. This will guarantee 100% unique IDs.
 * The second parameter is the actual packet class <code><nowiki>MSG</nowiki></code>.
-* The third parameter is a <code><nowiki>BiConsumer<MSG, PacketBuffer></nowiki></code> responsible for encoding the message into the provided <code><nowiki>PacketBuffer</nowiki></code>
+* The third parameter is a <code><nowiki>BiConsumer<MSG, FriendlyByteBuf></nowiki></code> responsible for encoding the message into the provided <code><nowiki>FriendlyByteBuf</nowiki></code>
-* The fourth parameter is a <code><nowiki>Function<PacketBuffer, MSG></nowiki></code> responsible for decoding the message from the provided <code><nowiki>PacketBuffer</nowiki></code>
+* The fourth parameter is a <code><nowiki>Function<FriendlyByteBuf, MSG></nowiki></code> responsible for decoding the message from the provided <code><nowiki>FriendlyByteBuf</nowiki></code>
 * The final parameter is a <code><nowiki>BiConsumer<MSG, Supplier<NetworkEvent.Context>></nowiki></code> responsible for handling the message itself
-The last three parameters can be method references to either static or instance methods in Java. Remember that an instance method <code><nowiki>MSG.encode(PacketBuffer)</nowiki></code> still satisfies <code><nowiki>BiConsumer<MSG, PacketBuffer></nowiki></code>, the <code><nowiki>MSG</nowiki></code> simply becomes the implicit first argument.
+The last three parameters can be method references to either static or instance methods in Java. Remember that an instance method <code><nowiki>MSG.encode(FriendlyByteBuf)</nowiki></code> still satisfies <code><nowiki>BiConsumer<MSG, FriendlyByteBuf></nowiki></code>, the <code><nowiki>MSG</nowiki></code> simply becomes the implicit first argument.
 == Handling Packets ==
@@ Line 45: / Line 45: @@
      ctx.get().enqueueWork(() -> {
          // Work that needs to be threadsafe (most work)
-         ServerPlayerEntity sender = ctx.get().getSender(); // the client that sent this packet
+         ServerPlayer sender = ctx.get().getSender(); // the client that sent this packet
          // do stuff
      });
@@ Line 52: / Line 52: @@
 </syntaxhighlight>
-Note the presence of <code><nowiki>setPacketHandled</nowiki></code>, which used to tell the network system that the packet has successfully completed handling.
+Packets sent from the server to the client should be handled in another class and wrapped via <code>DistExecutor#unsafeRunWhenOn</code>.
 {{Colored box|title=Alert|content=Packets are by default handled on the network thread.
 <br><br>
 That means that your handler can _not_ interact with most game objects directly.
-Forge provides a convenient way to make your code execute on the main thread instead using <code><nowiki>IThreadListener.addScheduledTask</nowiki></code>.
+Forge provides a convenient way to make your code execute on the main thread through the supplied <code><nowiki>NetworkEvent$Context</nowiki></code>.
-Simply call <code><nowiki>ctx.get().enqueueWork(Runnable)</nowiki></code>, which will call the given <code><nowiki>Runnable</nowiki></code> on the main thread at the next opportunity.}}
+Simply call <code><nowiki>NetworkEvent$Context#enqueueWork(Runnable)</nowiki></code>, which will call the given <code><nowiki>Runnable</nowiki></code> on the main thread at the next opportunity.}}
 {{Colored box|title=Alert|content=Be defensive when handling packets on the server. A client could attempt to exploit the packet handling by sending unexpected data.
 <br><br>
-A common problem is vulnerability to <code>arbitrary chunk generation</code>. This typically happens when the server is trusting a block position sent by a client to access blocks and tile entities. When accessing blocks and tile entities in unloaded areas of the world, the server will either generate or load this area from disk, then promply write it to disk. This can be exploited to cause <code>catastrophic damage</code> to a server's performance and storage space without leaving a trace.
+A common problem is vulnerability to <code>arbitrary chunk generation</code>. This typically happens when the server is trusting a block position sent by a client to access blocks and block entities. When accessing blocks and block entities in unloaded areas of the level, the server will either generate or load this area from disk, then promply write it to disk. This can be exploited to cause <code>catastrophic damage</code> to a server's performance and storage space without leaving a trace.
 <br>
-To avoid this problem, a general rule of thumb is to only access blocks and tile entities if <code><nowiki>world.isBlockLoaded(pos)</nowiki></code> is true.}}
+To avoid this problem, a general rule of thumb is to only access blocks and block entities if <code><nowiki>Level#hasChunkAt</nowiki></code> is true.}}
 == Sending Packets ==
@@ Line 74: / Line 92: @@
 === Sending to Clients ===
-Packets can be sent directly to a client using the <code><nowiki>SimpleChannel</nowiki></code>: <code><nowiki>HANDLER.sendTo(MSG, entityPlayerMP.connection.getNetworkManager(), NetworkDirection.PLAY_TO_CLIENT)</nowiki></code>. However, this can be quite inconvenient. Forge has some convenience functions that can be used:
+Packets can be sent directly to a client using the <code><nowiki>SimpleChannel</nowiki></code>: <code><nowiki>HANDLER.sendTo(MSG, serverPlayer.connection.getConnection(), NetworkDirection.PLAY_TO_CLIENT)</nowiki></code>. However, this can be quite inconvenient. Forge has some convenience functions that can be used:
 <syntaxhighlight lang="java">
 // Sending to one player
-INSTANCE.send(PacketDistributor.PLAYER.with(playerMP), new MyMessage());
+INSTANCE.send(PacketDistributor.PLAYER.with(serverPlayer), new MyMessage());
-// Send to all players tracking this chunk
+// Send to all players tracking this level chunk
-INSTANCE.send(PacketDistributor.TRACKING_CHUNK.with(chunk), new MyMessage());
+INSTANCE.send(PacketDistributor.TRACKING_CHUNK.with(levelChunk), new MyMessage());
 // Sending to all connected players

← Older revision	Revision as of 16:26, 8 November 2020
(No difference)