Differences

This shows you the differences between two versions of the page.

--- zh_cn:tutorial:networking [2022/01/28 06:46] – created solidblock
+++ zh_cn:tutorial:networking [2024/07/05 10:58] (current) – solidblock
@@ Line 1: / Line 1: @@
-====== 页面信息 ======
+**注意：**本页已经取代旧版页面。建议使用本页描述的新的网络API。旧的页面参见[[tutorial:legacy:networking-v0|此处（英文）]]。
-本页已经取代旧版页面。建议使用本页描述的新的网络API。旧的页面参见[[tutorial:legacy:networking-v0|此处（英文）]]。
+对于 1.20.5 引入的新的网络通信 API，请参见 [[#1.20.5 中的网络通信]]。
 ====== 网络通信 ======
@@ Line 43: / Line 43: @@
 要修复崩溃，你需要了解 Minecraft 如何在客户端和专用服务器之间通信（communication）。
-[[Minecraft 的逻辑段|{{tutorial:sides.png?700}}]]
+[[Minecraft 的逻辑端|{{tutorial:sides.png?700}}]]
 从上面这张图可以看到，游戏客户端和专用服务器是相互分离的系统，并使用数据包（packets，注意不是 datapack）桥接在一起。这个数据包桥（packet bridge）不仅存在于游戏客户端和专用服务器之间，还存在于您的客户端和通过 LAN 连接的另一个客户端之间。注意即使是单人游戏也有数据包桥，这是因为游戏客户端会启动一个特殊的集成服务器实例来运行游戏。下表显示了三种连接类型之间的主要区别：
@@ Line 74: / Line 74: @@
 </code>
-接下来，我们需要将数据包发送到游戏客户端。首先需要定义一个用于识别数据包的 ''Identifier''。对于本例，我们的标识符为 ''wiki_example:highlight_block''。为将数据包发送到游戏客户端，需要指定要哪个玩家的游戏客户端接收数据包。由于该操作发生在逻辑服务器上，所以可以将 ''player'' 向上强转为 ''ServerPlayerEntity''。
+接下来，我们需要将数据包发送到游戏客户端。首先需要定义一个用于识别数据包的 ''Identifier''。对于本例，我们的标识符为 ''tutorial:highlight_block''。为将数据包发送到游戏客户端，需要指定要哪个玩家的游戏客户端接收数据包。由于该操作发生在逻辑服务器上，所以可以将 ''player'' 向上强转为 ''ServerPlayerEntity''。
+<code java>
+public class TutorialNetworkingConstants {
+    // 存储数据包的 id 以便后面引用
+    public static final Identifier HIGHLIGHT_PACKET_ID = Identifier.of("tutorial", "highlight_block");
+}
+</code>
 要将数据包发送到玩家，我们使用 ''ServerPlayerNetworking'' 中的一些方法。我们使用该类中的以下方法：
@@ Line 83: / Line 89: @@
 </code>
-数据包将会被发送到此方法中的玩家。通道名称是你之前决定用来识别数据包的 ''Identifier''。''PacketByteBuf'' 用于存储数据包的数据。We will return later to writing data to the packet's payload via the buf.
+数据包将会被发送到此方法中的玩家。通道名称是你之前决定用来识别数据包的 ''Identifier''。''PacketByteBuf'' 用于存储数据包的数据。然后我们返回，以通过 buf 将数据写入数据包的有效负载。
 由于我们没有向数据包写入任何数据，所以现在，我们将发送带有空有效负载的数据包。可以使用 ''PacketByteBufs.empty()'' 创建带有空有效负载的 buf。
@@ Line 96: / Line 102: @@
 虽然你已经向游戏客户端发送了一个数据包，但游戏客户端无法对数据包做任何事情，因为客户端不知道如何接收数据包。关于游戏客户端接收数据包的信息请参见下方：
-==== Receiving a packet on the game client ====
+==== 在游戏客户端接收数据包 ====
-To receive a packet from a server on the game client, your mod needs to specify how it will handle the incoming packet.
+要从游戏客户端上的服务器接收数据包，你的模组需要指定客户端将如何处理收到的数据包。在客户端入口点中，使用 ''ClientPlayNetworking.registerGlobalReceiver(Identifier channelName, ChannelHandler channelHandler)'' 为你的数据包注册接收器。
-In your client entrypoint, you will register the receiver for your packet using ''ClientPlayNetworking.registerGlobalReceiver(Identifier channelName, ChannelHandler channelHandler)''
-The ''Identifier'' should match the same Identifier you use to send the packet to the client. The ''ChannelHandler'' is the functional interface you will use to implement how the packet is handled. **Note the ''ChannelHandler'' should be the one that is a nested interface of ''ClientPlayNetworking''**
+''Identifier'' 应该可你用来将数据包发送到客户端的标识符匹配。你将会实现 ''ChannelHandler'' 这个函数型接口，以处理数据包。**注意 ''ChannelHandler'' 应该是嵌套在 ''ClientPlayNetworking'' 中的那个！**
-The example below implements the play channel handler as a lambda:
+下面的例子以匿名函数的形式实现玩家通道处理器：
 <code java [enable_line_numbers="true"]>
@@ Line 111: / Line 116: @@
 </code>
-However, you cannot draw the highlight box immediately. This is because the receiver is called on the netty event loop. The event loop runs on another thread, and you must draw the highlight box on the render thread.
+但是，你还不能立即绘制高亮框。这是因为接收器是在网络事件循环中调用的。事件循环在另一个线程上运行，你必须在渲染线程上绘制高亮框。
-In order to draw the highlight box, you need to schedule the task on the game client. This may be done with the ''client'' field that is provided in the channel handler. Typically you will run the task on the client by using the ''execute'' method:
+要绘制高亮框，你需要在游戏客户端上安排任务。这可以由通道处理器提供的 ''client'' 字段来完成。通常，你将使用 ''execute'' 方法在客户端上运行任务：
 <code java [enable_line_numbers="true"]>
 ClientPlayNetworking.registerGlobalReceiver(TutorialNetworkingConstants.HIGHLIGHT_PACKET_ID, (client, handler, buf, responseSender) -> {
     client.execute(() -> {
-        // Everything in this lambda is run on the render thread
+        // 此 lambda 中的所有内容都在渲染线程上运行
         ClientBlockHighlighting.highlightBlock(client, target);
     });
@@ Line 124: / Line 129: @@
 </code>
-You may have noticed you are not told where the block to highlight is. You can write this data to the packet byte buf. Instead of sending ''PacketByteBufs.empty()'' to the game client in your item's ''use'' method, instead, you will create a new packet byte buf and send that instead.
+你可能已经注意到你并不知道要高亮哪个方块。你可以将此数据写入数据包字节 buf。不再在你的物品的 ''use'' 方法中向游戏客户端发送 ''PacketByteBufs.empty()''，而是创建一个新的数据包字节 buf 并将其发送。
 <code java [enable_line_numbers="true"]>
@@ Line 130: / Line 135: @@
 </code>
-Next, you need to write the data to the packet byte buf. It should be noted that you must read data in the same order you write it.
+接下来，您需要将数据写入数据包字节buf。应该注意的是，你必须以和写入数据相同的顺序读取数据。
 <code java [enable_line_numbers="true", highlight_lines_extra="3"]>
@@ Line 138: / Line 143: @@
 </code>
-Afterwards, you will send the ''buf'' field through the ''send'' method.
+之后，你将通过 ''send'' 方法发送 ''buf'' 字段。
-To read this block position on the game client, you can use ''PacketByteBuf.readBlockPos()''.
+要读取游戏客户端上的方块坐标，你可以使用 ''PacketByteBuf.readBlockPos()''。
-You should read all data from the packet on the network thread before scheduling a task to occur on the client thread. You will get errors related to the ref count if you try to read data on the client thread. If you must read data on the client thread, you need to ''retain()'' the data and then read it on the client thread. If you do ''retain()'' the data, make sure you ''release()'' the data when you no longer need it.
+你应该先从网络线程上的数据包中读取所有数据然后再在客户端线程上安排任务。如果你尝试在客户端线程上读取数据，将收到与 ref count 有关的错误。如果一定要在客户端线程上读取数据，则需要 ''retain()''（保留）这些数据，然后在客户端线程上读取。如果你 '' retain()'' 了数据，请确保在不再需要时 ''release()''（释放）数据。
-In the end, the client's handler would look like this:
+最后，客户端的处理程序将如下所示：
 <code java [enable_line_numbers="true"]>
 ClientPlayNetworking.registerGlobalReceiver(TutorialNetworkingConstants.HIGHLIGHT_PACKET_ID, (client, handler, buf, responseSender) -> {
-    // Read packet data on the event loop
+    // 在事件循环上读取数据包数据
     BlockPos target = buf.readBlockPos();
     client.execute(() -> {
-        // Everything in this lambda is run on the render thread
+        // 此 lambda 中的所有内容都在渲染线程上运行
         ClientBlockHighlighting.highlightBlock(client, target);
     });
@@ Line 157: / Line 162: @@
 </code>
-==== Sending packets to the server and receiving packets on the server ====
+==== 向服务器发送数据包并在服务器上接收数据包 ====
-Sending packets to a server and receiving a packet on the server is very similar to how you would on the client. However, there are a few key differences.
+将数据包发送到服务器并在服务器上接收数据包与在客户端上的操作非常相似。但是，有一些关键的区别。
-Firstly sending a packet to the server is done through ''ClientPlayNetworking.send''. Receiving a packet on the server is similar to receiving a packet on the client, using the ''ServerPlayNetworking.registerGlobalReceiver(Identifier channelName, ChannelHandler channelHandler)'' method. The ''ChannelHandler'' for the server networking also passes the ''ServerPlayerEntity'' (player) who sent the packet through the ''player'' parameter.
+首先，将数据包发送到服务器是通过 ''ClientPlayNetworking.send'' 完成的。在服务器接收数据包与在客户端接收数据包比较类似，使用 ''ServerPlayNetworking.registerGlobalReceiver(Identifier channelName, ChannelHandler channelHandler)'' 方法。用于服务器网络通信的 ''ChannelHandler'' 也会通过 ''player''参数传入发送该数据包的 ''ServerPlayerEntity''（玩家）。
+===== 追踪的概念以及为什么只有你看到高亮的方块 =====
-===== The concept of tracking and why you only see the highlighted block =====
-Now that the highlighting wand properly uses networking so the dedicated server does not crash, you invite your friend back on the server to show off the highlighting wand. You use the wand and the block is highlighted on your client and the server does not crash. However, your friend does not see the highlighted block. This is intentional with the code that you already have here. To solve this issue let us take a look at the item's use code:
+现在，高亮魔杖恰当地使用了网络，因此专用服务器不会崩溃。你邀请你的朋友回到服务器上来炫耀高亮魔杖，你使用魔杖，并且该方块也在你的客户端上高亮了，并且服务器没有崩溃。但是，你的朋友没有看到高亮。这是你在此处已有的代码有意为之的。为解决此问题，看一下物品的 ''use'' 代码：
 <code java [enable_line_numbers="true"]>
     public TypedActionResult<ItemStack> use(World world, PlayerEntity user, Hand hand) {
-        // Verify we are processing the use action on the logical server
+        // 确认我们是否是在逻辑服务器上进行操作
         if (world.isClient()) return super.use(world, user, hand);
-        // Raycast and find the block the user is facing at
+        // 视线追踪并找到玩家朝向的方块
         BlockPos target = ...
         PacketByteBuf buf = PacketByteBufs.create();
@@ Line 182: / Line 185: @@
 </code>
-You may notice the item will only send the packet to the player who used the item. To fix this, we can use the utility methods in ''PlayerLookup'' to get all the players who can see the highlighted block.
+你可能注意到了，该物品只会将数据包发送给使用了该物品的玩家。为解决此问题，我们可以使用 ''PlayerLookup'' 中的实用方法来获取所有可以看到高亮方块的玩家。
-Since we know where the highlight will occur, we can use ''PlayerLookup.tracking(ServerWorld world, BlockPos pos)'' to get a collection of all players who can see that position in the world. Then you would simply iterate through all players in the returned collection and send the packet to each player:
+因为我们知道高亮会出现在哪个位置，所以我们可以使用 ''PlayerLookup.tracking(ServerWorld world, BlockPos pos)'' 来获取所有可以在世界上看到该位置的玩家的集合。然后，您只需在返回的集合中遍历所有玩家，并将数据包发送给每个玩家：
 <code java [enable_line_numbers="true", highlight_lines_extra="10,11,12,13"]>
     public TypedActionResult<ItemStack> use(World world, PlayerEntity user, Hand hand) {
-        // Verify we are processing the use action on the logical server
+        // 确认我们是否是在逻辑服务器上进行操作
         if (world.isClient()) return super.use(world, user, hand);
-        // Raycast and find the block the user is facing at
+        // 视线追踪并找到玩家朝向的方块
         BlockPos target = ...
         PacketByteBuf buf = PacketByteBufs.create();
         buf.writeBlockPos(target);
-        // Iterate over all players tracking a position in the world and send the packet to each player
+        // 迭代世界上所有追踪位置的玩家，并将数据包发送给每个玩家
         for (ServerPlayerEntity player : PlayerLookup.tracking((ServerWorld) world, target)) {
             ServerPlayNetworking.send(player, TutorialNetworkingConstants.HIGHLIGHT_PACKET_ID, buf);
@@ Line 205: / Line 208: @@
 </code>
-After this change, when you use the wand, your friend should also see the highlighted block on their own client.
+这样修改之后，当你使用魔杖时，你的朋友也应该在他们自己的客户端上看到高亮方块。
-====== Advanced Networking topics ======
+===== 1.20.5 中的网络通信 =====
+自 1.20.5 开始，网络通信的逻辑被大改。在 1.20.5 中，''RegistryByteBuf'' 现在用于游玩阶段网络，你需要定义一个 ''Payload''。首先，定义一个包含了 ''BlockPos'' 的 ''Payload''：
-The Networking system Fabric API supplies is very flexible and supports additional features other than just sending and receiving simple packets. As some of these more advanced topics are long, here are links to their specific pages:
+<code java>
+public record BlockHighlightPayload(BlockPos blockPos) implements CustomPayload {
+  public static final Id<BlockHighlightPayload> ID = new CustomPayload.Id<>(TutorialNetworkingConstants.HIGHLIGHT_PACKET_ID);
+  public static final PacketCodec<PacketByteBuf, BlockHighlightPayload> CODEC = PacketCodec.tuple(BlockPos.PACKET_CODEC, BlockHighlightPayload::blockPos, BlockHighlightPayload::new);
+  // 或者，你也可以这样写：
+  // public static final PacketCodec<PacketByteBuf, BlockHighlightPayload> CODEC = PacketCodec.of((value, buf) -> buf.writeBlockPos(value.blockPos), buf -> new BlockHighlightPayload(buf.readBlockPos()));
-^ Networking Topic ^ Description ^
+  @Override
-| [[tutorial:networking:connection_events|Connection Network connection events]] | Events related to the the lifecycle of a connection to a client or server |
+  public Id<? extends CustomPayload> getId() {
-| [[tutorial:networking:channel_events|Channel registration events]] | Events related to a server of client declaring the ability to receive a packet on a channel of a specific name |
+    return ID;
-| [[tutorial:networking:login|Login phase networking]]| Sending requests to a client during login; and allowing delay of login for a short amount of time |
+  }
-| [[tutorial:networking:dynamic_handlers|Dynamic registration of channel handlers]]| Allowing for a connection to receive a packet with a special handler |
+}
+</code>
+然后，像这样注册 receiver：
+<code java>
+PayloadTypeRegistry.playS2C().register(BlockHighlightPayload.ID, BlockHighlightPayload.CODEC);
+ClientPlayNetworking.registerGlobalReceiver(BlockHighlightPayload.ID, (payload, context) -> {
+  context.client().execute(() -> {
+    ClientBlockHighlighting.highlightBlock(client, target);
+  });
+});
+</code>
+现在，在服务器一端，你可以像这样把数据包发送给玩家：
+<code java>
+    public TypedActionResult<ItemStack> use(World world, PlayerEntity user, Hand hand) {
+        if (world.isClient()) return super.use(world, user, hand);
+        // ...
+        for (ServerPlayerEntity player : PlayerLookup.tracking((ServerWorld) world, target)) {
+            ServerPlayNetworking.send(player, new BlockHighlightPayload(blockPos));
+        }
+        return TypedActionResult.success(user.getHandStack(hand));
+    }
+</code>