Skip to content

19 networking ​

一句话定位:给 mod 提供"命名通道 + 自定义负载"的点对点收发层,并在登录后自动交换双方通道表,让你能判断"对面到底会不会收"。

项值
模块 idnetworking
Mavennet.ornithemc.osl-gen2:networking:0.12.0+mc13w41a-mc18w30b
版本0.12.0+mc13w41a-mc18w30b(1.12.2 命中该子工程)
端双端(客户端 / 服务端都有 API,包 fabric.mod.json 的 environment 为 *)
依赖ploceus.dependOslModule('networking', '0.24.0');传递依赖 core、executors、text-components

OSL networking 在 Vanilla 的 CustomPayload(1.12.2 的 CustomPayloadC2SPacket / CustomPayloadS2CPacket)之上加了一层"通道注册表 + 监听器 + 握手"。通道是 NamespacedIdentifier(如 example:cookie);收发时可以选择直接读写 PacketBuffer、自己实现 PacketPayload、或传 byte[]。模块在登录时会用一个内部保留通道(osl:handshake)交换双方的监听器列表,因此 send 默认只在"对面确实监听这个通道"时才真正发包,避免刷屏与无意义流量。

关键语义(线程 / 大小 / 握手) ​

主题说明
监听器运行线程监听器默认在网络线程上被调用(即 Vanilla 处理 CustomPayload 的线程),不是主线程。要改到主线程,请在回调第一行调用 context.ensureOnMainThread();它检测到不在主线程时会抛异常,OSL 捕获后把同一个负载重新投递到主线程任务队列(Minecraft#execute / MinecraftServer#execute),监听器会被再次调用一次,第二次才在主线程上。因此 ensureOnMainThread() 必须放在回调最前面(在它之前做的读写会在网络线程上执行一遍)。如果不需要触碰世界 / 渲染状态,可以不调用,省一次调度。
负载大小OSL 只限制通道名字符串长度:命名空间与标识各最多 Byte.MAX_VALUE(127),完整 namespace:identifier 最多 255 字符(StringChannelIdentifierParser.MAX_LENGTH)。Vanilla 原本只允许 20 字符的通道名,OSL 通过 mixin 把读取上限放宽到 255。负载(payload)本身 OSL 不做长度检查,上限由 Minecraft 自己的 custom payload 包决定(源码未明确说明具体数值)。
握手时机客户端在 ClientPlayNetworkHandler#handleLogin 结束时发一次 osl:handshake(内容是客户端已注册的监听器通道列表);服务端收到后先回一份自己的列表、再登记"客户端监听哪些通道",然后触发服务端 PLAY_READY;客户端收到回包后登记"服务端监听哪些通道",再触发客户端 PLAY_READY。
通道表只交换一次通道表来源是已注册的监听器集合(不是注册表)。登录之后再注册的监听器不会重新通告,isPlayReady(channel) 会一直是 false,直到重新连接。请把监听器注册写在 mod 初始化器里。
对端没有 OSL如果对面是纯 Vanilla 客户端 / 服务端,握手不会发生,isPlayReady(...) 恒为 false,所有 send(带检查的)都会静默丢弃;只有 sendNoCheck 会真的发出去(由 Vanilla 自己忽略 / 处理)。
缓冲区生命周期回调拿到的 PacketBuffer 是数据包内容的副本,回调返回后由 OSL 释放;不要在回调外保留引用(需要留存请 copy())。自己传进 send(channel, PacketBuffer) 的缓冲区会被包对象直接引用(不再复制),发送后不要再写入或 release()。

通道标识符 ​

ChannelIdentifiers ​

Reference: net.ornithemc.osl.networking.api.ChannelIdentifiers

作用:创建 / 校验通道标识符的唯一推荐入口。通道名约定为 <modid>:<snake_case 名>。

成员作用需要(参数 / 前置条件)返回
DEFAULT_NAMESPACE默认命名空间常量,值为 "minecraft"—String
MAX_LENGTH_NAMESPACE / MAX_LENGTH_IDENTIFIER命名空间 / 标识的最大长度,均为 Byte.MAX_VALUE(127)—int
register(String identifier)用默认命名空间构造、校验并注册通道(双端可收发)标识合法;同通道重复注册且设置不同会抛 IllegalArgumentException注册后的 NamespacedIdentifier
register(String namespace, String identifier)同上,指定命名空间命名空间 / 标识合法同上
register(String identifier, boolean clientbound, boolean serverbound)构造、校验并注册,同时指定可收发方向同上同上
register(String namespace, String identifier, boolean clientbound, boolean serverbound)同上,指定命名空间同上同上
from(String identifier) / from(String namespace, String identifier)只构造并校验,不注册命名空间 / 标识合法,否则抛运行时异常(ChannelIdentifierException / NamespacedIdentifierException,均在 impl 包)NamespacedIdentifier
legacy(String identifier) / legacy(String namespace, String identifier)构造 1.13-pre2 及以下的旧式通道名(namespace|identifier),不做任何校验无(允许大写、允许空命名空间)NamespacedIdentifier(实际是 LegacyChannelIdentifier)
validate(NamespacedIdentifier id)校验并原样返回;不合法则抛异常命名空间 / 标识合法传入的 NamespacedIdentifier
validateNamespace(String) / validateIdentifier(String)单独校验长度与字符集只允许 [a-z0-9-._],标识额外允许 /校验通过的字符串

注意:DEFAULT_NAMESPACE 是 minecraft,所以 register("foo") 得到的是 minecraft:foo。自己的通道务必显式给命名空间,否则会和 Vanilla / 别的 mod 撞名。

java
public static final NamespacedIdentifier COOKIE = ChannelIdentifiers.register("example", "cookie");
// -> example:cookie,双向通道

ChannelRegistry ​

Reference: net.ornithemc.osl.networking.api.ChannelRegistry

作用:底层通道注册表。想在注册时直接给一个已构造好的 NamespacedIdentifier 时用它;一般用 ChannelIdentifiers 就够。

需要:通道必须先注册,才能在其上注册监听器;未注册的通道被视为 closed,收不到也发不出。

成员作用需要(参数 / 前置条件)返回
register(NamespacedIdentifier channel)以默认设置注册:clientbound = true、serverbound = true同一通道不得以不同设置重复注册,否则抛 IllegalArgumentException;相同设置重复注册是幂等的注册后的通道(原样返回)
register(NamespacedIdentifier channel, boolean clientbound, boolean serverbound)以指定方向注册。clientbound:期望客户端收(服务端才能发往客户端);serverbound:期望服务端收(客户端才能发往服务端)同上同上
java
// 只允许客户端 -> 服务端
ChannelRegistry.register(ChannelIdentifiers.from("example", "input"), false, true);

LegacyChannelIdentifier ​

Reference: net.ornithemc.osl.networking.api.LegacyChannelIdentifier

作用:NamespacedIdentifier 的一个子类型,表示 1.13-pre2 及以下那种没有强格式约束的旧式通道名(约定用 | 分隔,例如 MC|Brand、REGISTER)。

需要:namespace() 允许为空字符串;此时 toString() 只输出标识本身(不带分隔符)。不需要实现它,用 ChannelIdentifiers.legacy(...) 构造即可。

成员作用需要(参数 / 前置条件)返回
SEPARATOR旧式分隔符 '|'(仅约定,不做强制)—char
separator()返回 SEPARATOR—char
namespaced(String) / prefixed(String) / suffixed(String)复制出改命名空间 / 加前缀 / 加后缀的新标识参数为 null 时的行为(源码未明确说明)新的 LegacyChannelIdentifier
subidentifier(int beginIndex) / subidentifier(int beginIndex, int endIndex)对标识部分取子串,复制出新标识下标越界抛 StringIndexOutOfBoundsException新的 LegacyChannelIdentifier

StringChannelIdentifierParser ​

Reference: net.ornithemc.osl.networking.api.StringChannelIdentifierParser

作用:通道标识符与 String 的互转。协议里传的就是字符串,自己实现负载或调试时用得上。

成员作用需要(参数 / 前置条件)返回
MAX_LENGTH字符串形式的最大长度 = 127 + 1 + 127 = 255—int
fromString(String s)解析字符串:先找 |(有则视为旧式),否则找 :;都找不到则当作"空命名空间 + 该字符串"的旧式标识。不做校验,结果可能不合法非 nullNamespacedIdentifier(可能不合法)
fromStringOrThrow(String s)同上,但新式标识会走 ChannelIdentifiers.validate;旧式分支仍不校验非 null合法的 NamespacedIdentifier;解析失败抛运行时的 ChannelIdentifierParseException(impl 包)
toString(NamespacedIdentifier id)转成字符串(等价于 id.toString())非 nullString

IdentifierChannelIdentifierParser ​

Reference: net.ornithemc.osl.networking.api.IdentifierChannelIdentifierParser

作用:通道标识符与 Minecraft 的 net.minecraft.resource.Identifier 互转(1.12.2 映射名;子工程专属类,仅在 1.12.2 这类有 Identifier 的版本存在)。

成员作用需要(参数 / 前置条件)返回
fromIdentifier(Identifier id)用 id.getNamespace() / id.getPath() 构造,不校验非 nullNamespacedIdentifier(可能不合法)
fromIdentifierOrThrow(Identifier id)同上但做校验非 null合法的 NamespacedIdentifier;失败抛 ChannelIdentifierParseException(impl 包,运行时)
toIdentifier(NamespacedIdentifier id)转成 new Identifier(namespace, identifier)非 nullnet.minecraft.resource.Identifier

缓冲区与负载序列化 ​

PacketBuffer ​

Reference: net.ornithemc.osl.networking.api.PacketBuffer

作用:OSL 的读写缓冲,直接 extends io.netty.buffer.ByteBuf:既保留了 Netty 的全部字节操作(转发给内部的 net.minecraft.network.PacketByteBuf),又补上了 Minecraft 风格的 VarInt / 字符串 / NBT / 物品 / 文本 / 坐标等便携读写方法。

需要:监听器回调里由 OSL 提供;发送时用 PacketBuffers.make() 自己造,或直接传 PacketBuffer 给 send。写入顺序必须和读取顺序完全一致(自描述格式,没有字段名)。

成员作用需要(参数 / 前置条件)返回
PacketBuffer(ByteBuf delegate) / PacketBuffer(PacketByteBuf delegate)包装一个已有缓冲区(不复制)非 null—
readVarInt() / readVarLong()读 7 bit/字节、最高位为续位的变长整数数据完整int / long;超长(>5 / >10 字节)抛 RuntimeException
writeVarInt(int) / writeVarLong(long)写变长整数—this(ByteBuf)
readByteArray() / readByteArray(int maxLength)先读 VarInt 长度,再读该数量的字节无参时 maxLength = 剩余可读字节数byte[];长度超限抛 RuntimeException
writeByteArray(byte[])写 VarInt 长度 + 原始字节非 nullByteBuf
readIntArray() / readIntArray(int maxLength) / writeIntArray(int[])长度前缀 + 每个元素 VarInt同上int[] / ByteBuf
readLongArray() / readLongArray(int maxLength) / writeLongArray(long[])长度前缀 + 每个元素 VarLong同上long[] / ByteBuf;长度超限时抛的是 IllegalStateException(与其它数组的 RuntimeException 不同,源码如此)
readString() / readString(int maxLength)读 VarInt 字节长度 + UTF-8 内容无参上限 Short.MAX_VALUE(32767);解码时字节层允许 maxLength * 4String;超限 / 负数长度抛 RuntimeException
writeString(String) / writeString(String, int maxLength)写 VarInt 字节长度 + UTF-8 内容无参上限 Short.MAX_VALUE;UTF-8 字节数超 maxLength 抛 RuntimeExceptionByteBuf
readEnum(Class<T> type) / writeEnum(Enum<?> value)按序号 VarInt 读写枚举type 有常量T / ByteBuf;读到越界序号抛 ArrayIndexOutOfBoundsException(源码未做范围检查)
readCollection(IntFunction<C> constructor, Function<PacketBuffer,T> reader) / readList(Function<PacketBuffer,T> reader)先读 VarInt 元素个数,再逐个用回调读读写顺序对称集合 / List
writeCollection(Collection<T>, BiConsumer<PacketBuffer,T> writer)写元素个数 + 逐个写入—ByteBuf
readDate() / writeDate(Date)按 long(毫秒)读写—Date / ByteBuf
readUuid() / writeUuid(UUID)按两个 long 读写—UUID / ByteBuf
readBlockPos() / writeBlockPos(BlockPos)按 long 打包读写坐标仅当该 MC 版本的 BlockPos 支持 toLong() / fromLong();1.12.2 的 BlockPos 继承 Vec3i,支持BlockPos / ByteBuf;不支持时抛 UnsupportedOperationException
readIdentifier() / writeIdentifier(Identifier)以字符串形式读写 net.minecraft.resource.Identifier字符串合法Identifier / ByteBuf
readNamespacedIdentifier() / writeNamespacedIdentifier(NamespacedIdentifier)以 namespace:path 字符串形式读写读取时会走 core 的解析(失败抛运行时异常)NamespacedIdentifier / ByteBuf
readText() / writeText(Text)以 JSON 字符串读写 net.minecraft.text.TextJSON 长度上限 0x40000Text / ByteBuf
readTextComponent() / writeTextComponent(TextComponent)以 JSON 字符串读写 OSL 的 TextComponent(text-components 模块)同上TextComponent / ByteBuf
readNbtCompound() / writeNbtCompound(NbtCompound)读写 NBT 复合标签(转发给 PacketByteBuf)—NbtCompound / ByteBuf
readItem() / writeItem(ItemStack)读写物品堆(转发给 PacketByteBuf)—ItemStack / ByteBuf
其余 ByteBuf 方法capacity()、readerIndex()、readableBytes()、copy()、retain()、release()、各定长读写等全部原样转发到内部缓冲区—与 Netty ByteBuf 一致

PacketBuffers ​

Reference: net.ornithemc.osl.networking.api.PacketBuffers

作用:PacketBuffer 的工厂与转换工具。

成员作用需要(参数 / 前置条件)返回
make()新建一个空的堆缓冲区(Unpooled.buffer() 包装)—PacketBuffer
make(IOConsumer<PacketBuffer> writer)新建并立刻用 writer 写入writer 抛 IOException 会向外传播已写入的 PacketBuffer
wrap(byte[] bytes)把字节数组包装成缓冲区(不复制,不加长度前缀)非 nullPacketBuffer
unwrap(PacketBuffer buffer)取出 [0, writerIndex) 的字节并释放该缓冲区调用后 buffer 不可再用byte[]
wrapped(ByteBuf buffer)包装任意 Netty ByteBuf非 nullPacketBuffer
unwrapped(PacketBuffer buffer)取出内部的 PacketByteBuf(不复制、不释放)非 nullnet.minecraft.network.PacketByteBuf

PacketPayload ​

Reference: net.ornithemc.osl.networking.api.PacketPayload

作用:把"一组字段"封装成可序列化负载的接口。实现它就能用 send(channel, payload) 发送、用 registerListener(channel, initializer, listener) 接收,不用手写缓冲区代码。

需要:实现 read / write,两者顺序必须严格对称;同时提供一个无参构造(或一个 Supplier 工厂)供接收端实例化。类不必是 public 的,但接收端要通过 Supplier 拿到实例。

成员作用需要(参数 / 前置条件)返回
read(PacketBuffer buffer)从缓冲区反序列化自身字段与 write 的顺序严格一致无(void),可抛 IOException
write(PacketBuffer buffer)把自身字段序列化进缓冲区同上无(void),可抛 IOException
java
public class CookiePayload implements PacketPayload {
    public int count;

    public CookiePayload() { }
    public CookiePayload(int count) { this.count = count; }

    @Override public void read(PacketBuffer buffer) throws IOException { this.count = buffer.readVarInt(); }
    @Override public void write(PacketBuffer buffer) throws IOException { buffer.writeVarInt(this.count); }
}

客户端收发(仅客户端可用的类) ​

ClientPlayNetworking ​

Reference: net.ornithemc.osl.networking.api.client.ClientPlayNetworking

作用:客户端侧的收 / 发入口。监听器在 mod 初始化器里注册;发送时默认先检查"服务端是否在监听该通道"。

需要:通道必须已用 ChannelIdentifiers / ChannelRegistry 注册;服务端监听器对应的通道必须 serverbound = true,客户端监听器对应的通道必须 clientbound = true。

成员作用需要(参数 / 前置条件)返回
registerListener(NamespacedIdentifier channel, Supplier<T> initializer, ClientPacketListener.Payload<T> listener)以负载对象方式接收:先用 initializer 造实例,再 payload.read(buffer),再回调通道已注册且 clientbound;同一通道只能有一个监听器,重复注册抛 IllegalArgumentException;通道不是 clientbound 也抛 IllegalArgumentException无(void)
registerListener(NamespacedIdentifier channel, ClientPacketListener.Buffer listener)直接拿到 PacketBuffer 自己读同上无(void)
registerLegacyListener(NamespacedIdentifier channel, ClientPacketListener.Bytes listener)拿到 byte[]。实现是 buffer.readByteArray(),即按"VarInt 长度前缀 + 原始字节"解析同上无(void)
unregisterListener(NamespacedIdentifier channel)移除该通道的监听器通道已注册无(void)
isPlayReady()连接是否已就绪(已完成握手、可以安全发送)—boolean;未连接或握手未完成时为 false
isPlayReady(NamespacedIdentifier channel)该通道是否可发:连接就绪且服务端有该通道的监听器通道已注册boolean
send(NamespacedIdentifier channel, PacketPayload payload)发送负载对象仅当 isPlayReady(channel) 为真才真正发送,否则静默丢弃(payload.write 不会被调用)无(void)
send(NamespacedIdentifier channel, IOConsumer<PacketBuffer> writer)用 writer 现场写入负载同上无(void)
send(NamespacedIdentifier channel, PacketBuffer buffer)直接发送缓冲区(包对象引用它,不复制)同上无(void)
send(NamespacedIdentifier channel, byte[] bytes)直接发送原始字节(不加长度前缀)同上无(void)
sendNoCheck(...)(4 个重载,参数同上)跳过通道检查直接发。慎用:对面没监听时会白发包、刷日志通道仍需注册且方向匹配(serverbound)无(void);写负载抛 IOException 时只记日志

send(channel, byte[]) 与 registerLegacyListener 的格式并不对称:前者发原始字节,后者按带 VarInt 长度前缀的格式读。要对接 registerLegacyListener,发送端应自己 writeByteArray(bytes),或收端改用 registerListener(channel, Buffer) 自行读取(源码如此,未做额外说明)。

ClientPacketListener ​

Reference: net.ornithemc.osl.networking.api.client.ClientPacketListener

作用:客户端收包回调的父接口,按收到的数据类型分成三个 @FunctionalInterface 子接口。

需要:不需要直接实现父接口,用 ClientPacketListener.Buffer / .Bytes / .Payload<T> 之一,或用 lambda;handle 抛出的 IOException 会被 OSL 记录为警告,不会中断连接。

成员作用需要(参数 / 前置条件)返回
handle(Context ctx, T data)收到数据时调用ctx 由 OSL 传入无(void),可抛 IOException
Payload<T extends PacketPayload>声明 T 为负载对象T 有可用的 Supplier—
Buffer声明 T = PacketBuffer——
Bytes声明 T = byte[]——
Context#minecraft()当前 net.minecraft.client.Minecraft 实例—Minecraft
Context#networkHandler()收到该包的 net.minecraft.client.network.handler.ClientPlayNetworkHandler—ClientPlayNetworkHandler
Context#ensureOnMainThread()断言当前在主线程;不在则抛内部异常,OSL 捕获后把同一负载重新投递到主线程并再调用一次回调应作为回调第一行调用无(void)

ClientConnectionEvents ​

Reference: net.ornithemc.osl.networking.api.client.ClientConnectionEvents

作用:客户端连接生命周期事件(含连接整合服务器 / 单人世界)。

需要:在 mod 初始化器里 XXX.register(listener);Event 类型来自 core 模块,重复注册会按注册顺序全部调用。

成员作用需要(参数 / 前置条件)返回
LOGIN登录成功时触发(ClientPlayNetworkHandler#handleLogin 末尾)。此时客户端刚发出通道表,还不能安全发数据回调类型 Consumer<LoginContext>无(void)
PLAY_READY收到服务端通道表、通道登记完成后触发。这是可以安全发数据的时刻Consumer<PlayReadyContext>无(void)
DISCONNECT客户端离开世界时触发:在 Minecraft#setWorld(null, ...) 之前(此时世界字段尚未清空)。断开原因取自此前收到的断开包 / ClientPlayNetworkHandler#onDisconnect 的文本Consumer<DisconnectContext>无(void)
ConnectionContext#minecraft()当前 Minecraft—Minecraft
ConnectionContext#worldName()单人世界名;连远程服务器时为 null—String
ConnectionContext#serverAddress() / #serverPort()服务器地址 / 端口;单人世界时分别为 null / -1—String / int
ConnectionContext#isMultiplayer()是否连的远程服务器(单人整合服务器为 false)—boolean
ConnectionContext#isServerLocal()(已废弃,请改用 isMultiplayer())等价于 !isMultiplayer()—boolean
DisconnectContext#disconnectReason()断开原因文本;自己退出 / 关游戏时为 null—TextComponent(text-components 模块)
java
ClientConnectionEvents.PLAY_READY.register(ctx -> {
    if (ClientPlayNetworking.isPlayReady(COOKIE)) {
        ClientPlayNetworking.send(COOKIE, new CookiePayload(3));
    }
});

服务端收发 ​

ServerPlayNetworking ​

Reference: net.ornithemc.osl.networking.api.server.ServerPlayNetworking

作用:服务端侧的收 / 发入口。除单播外还提供"发给一组玩家 / 某个维度 / 全员"的批量发送(即广播)重载。

需要:通道必须已注册;服务端监听器的通道需 serverbound = true,发往客户端的通道需 clientbound = true。所有 send 都按"该玩家是否在监听此通道"逐个过滤。

成员作用需要(参数 / 前置条件)返回
registerListener(NamespacedIdentifier channel, Supplier<T> initializer, ServerPacketListener.Payload<T> listener)以负载对象方式接收通道已注册且 serverbound;同一通道只能一个监听器,重复注册或方向不对抛 IllegalArgumentException无(void)
registerListener(NamespacedIdentifier channel, ServerPacketListener.Buffer listener)直接拿 PacketBuffer同上无(void)
registerLegacyListener(NamespacedIdentifier channel, ServerPacketListener.Bytes listener)拿 byte[](按 VarInt 长度前缀解析)同上无(void)
unregisterListener(NamespacedIdentifier channel)移除监听器通道已注册无(void)
isPlayReady(ServerPlayerEntity player)该玩家的连接是否已就绪player 非 null 且在线boolean
isPlayReady(ServerPlayerEntity player, NamespacedIdentifier channel)该玩家是否监听该通道通道已注册boolean
send(ServerPlayerEntity player, NamespacedIdentifier channel, PacketPayload | IOConsumer<PacketBuffer> | PacketBuffer | byte[])发给单个玩家(4 个重载)仅当 isPlayReady(player, channel) 为真才发无(void)
send(Iterable<ServerPlayerEntity> players, NamespacedIdentifier channel, ...)发给指定玩家集合(4 个重载)逐个过滤:只发给在监听该通道的玩家;若一个都没有,负载不会被写入无(void)
send(int dimension, NamespacedIdentifier channel, ...)发给某个维度的所有玩家(4 个重载)同上,额外按 player.dimension == dimension 过滤无(void)
send(NamespacedIdentifier channel, ...)发给服务器上所有玩家(4 个重载)——这就是"广播"同上无(void)
sendNoCheck(...)与上面四组一一对应的 16 个重载,跳过通道检查。慎用通道仍需注册且 clientbound无(void)

批量发送的返回值与副作用:PacketPayload / IOConsumer 版本会为整批只构造一个包对象,再逐个 sendPacket;写负载抛 IOException 时只记日志,不抛给调用方。若目标是"所有玩家",本方法在每个调用点都会遍历一次在线玩家(1.12.2 的 PlayerManager 列表)。

java
// 广播给所有在监听 example:cookie 的玩家
ServerPlayNetworking.send(COOKIE, new CookiePayload(7));
// 只发给某个玩家
ServerPlayNetworking.send(player, COOKIE, buf -> buf.writeVarInt(42));

ServerPacketListener ​

Reference: net.ornithemc.osl.networking.api.server.ServerPacketListener

作用:服务端收包回调的父接口,结构与客户端版对应,额外能拿到发包玩家。

需要:用三个 @FunctionalInterface 子接口之一实现;handle 抛的 IOException 会被记录为警告。

成员作用需要(参数 / 前置条件)返回
handle(Context ctx, T data)收到数据时调用—无(void),可抛 IOException
Payload<T extends PacketPayload> / Buffer / Bytes三种数据类型声明——
Context#server()当前 net.minecraft.server.MinecraftServer—MinecraftServer
Context#networkHandler()收到该包的 net.minecraft.server.network.handler.ServerPlayNetworkHandler—ServerPlayNetworkHandler
Context#player()发来该包的 net.minecraft.server.entity.living.player.ServerPlayerEntity—ServerPlayerEntity
Context#ensureOnMainThread()同客户端:非主线程时抛内部异常,OSL 会把负载重新投递到主线程并再调用一次回调应作为回调第一行调用无(void)

ServerConnectionEvents ​

Reference: net.ornithemc.osl.networking.api.server.ServerConnectionEvents

作用:服务端连接生命周期事件(含整合服务器)。

需要:在 mod 初始化器里注册;LOGIN 在 PlayerManager#onLogin 末尾触发,DISCONNECT 在 PlayerManager#remove 头部(以及服务器停机)触发。

成员作用需要(参数 / 前置条件)返回
LOGIN玩家登录成功时触发。此时尚未收到客户端通道表,还不能安全发数据Consumer<LoginContext>无(void)
PLAY_READY收到客户端通道表、登记完成后触发。这是可以安全发数据的时刻Consumer<PlayReadyContext>无(void)
DISCONNECT玩家断开时触发(PlayerManager#remove 头部)。服务器停机时还会在 MinecraftServer#stop 末尾对所有在线玩家补发一次Consumer<DisconnectContext>无(void)
ConnectionContext#server()当前 MinecraftServer—MinecraftServer
ConnectionContext#player()本次连接对应的 ServerPlayerEntity—ServerPlayerEntity
DisconnectContext#disconnectReason()断开原因文本;自己退出时为 null—TextComponent
java
ServerConnectionEvents.PLAY_READY.register(ctx -> {
    // 此刻 ctx.player() 已确认在监听我们注册过的通道
    ServerPlayNetworking.send(ctx.player(), COOKIE, new CookiePayload(1));
});

典型组合:C→S 请求 / S→C 回应 ​

java
// 共享
public static final NamespacedIdentifier REQ = ChannelIdentifiers.register("example", "req");

// 客户端 initClient()
ClientPlayNetworking.registerListener(REQ, (ctx, buf) -> {
    ctx.ensureOnMainThread();              // 第一行,保证后续在主线程
    int answer = buf.readVarInt();
});

// 服务端 init()
ServerPlayNetworking.registerListener(REQ, (ctx, buf) -> {
    ctx.ensureOnMainThread();
    int n = buf.readVarInt();
    ServerPlayNetworking.send(ctx.player(), REQ, b -> b.writeVarInt(n * 2));
});

基于 Ornithe Standard Libraries 0.24.0(MC 1.12.2)源码整理