BreakoutMods 英灵神殿客户端/服务器网络辅助API。

BreakoutMods BreakoutNet

BreakoutMods Valheim 模组套件的一部分。

BreakoutNet 是一个用于 Valheim 模组的小型客户端/服务器辅助库。它封装了重复的 BepInEx 和 ZRoutedRpc 大多数服务器感知模组都需要的粘合层：侧端检测、对等端查找、类型化RPC消息、服务器权威设置同步、 proximity广播、日志记录以及基础滥用防护。

GitHub： 突围模组/突围网络

社区： 突围模组 Discord

支持开发： BreakoutMods Patreon

BreakoutNet存在的理由

瓦尔海姆的模组通常需要相同的网络构建模块：

• 客户端向服务器发起请求。
• 服务器验证请求并回复。
• 服务器向所有玩家或附近玩家广播事件。
• 客户端应用服务器拥有的设置并拒绝伪造的设置。

BreakoutNet让这些模式保持简单通用、可重复使用，以便模组能共用同一网络层。

限定模组上下文

当mod需要使用BreakoutNet拥有的事件、钩子和未来对模块友好的API时，请使用限定作用域上下文：

private BreakoutModApp app; private void Awake() { app = BreakoutNet.ForPlugin(this, "com.breakoutmods.valheim.example") .AddShared<SharedModule>() .AddServer<ServerModule>() .AddClient<ClientModule>() .Build(); }

对于没有模块所有权的轻量级集成：

BreakoutModuleContext context = BreakoutNet.ForMod("com.breakoutmods.valheim.example");

术语

• 专用服务器： 无头服务器进程。它应负责中继和验证，但不创建仅客户端使用的UI、音频或输入系统。
• 客户端： 一个连接到服务器的普通游戏客户端。
• 监听服务器： 在本地托管世界的玩家。此端既是服务器权威端，也是可游玩的客户端。
• 在世界中： 网络 和 路由RPC 可使用。

RPC类型化快速入门

public sealed class JoinCheckRequest : IBreakoutSerializable { public string ModListHash; public void Write(ZPackage package) => package.Write(ModListHash ?? string.Empty); public void Read(ZPackage package) => ModListHash = package.ReadString(); } BreakoutRpc.Server.Register<JoinCheckRequest>( "joinguard.check", (context, request) => { if (string.IsNullOrWhiteSpace(request.ModListHash)) { context.Reject("客户端未发送模组列表哈希值。"); return; } BreakoutRpc.Server.SendToClient( context.SenderPeerId, "joinguard.ok", new JoinCheckResult(), "com.breakoutmods.valheim.joinguard"); });

客户端向服务器发送：

BreakoutRpc.Client.SendToServer( "joinguard.check", new JoinCheckRequest { ModListHash = localHash }, "com.breakoutmods.valheim.joinguard");

设置同步

BreakoutSettingsSync.RegisterServerSettings( "joinguard.settings", () => new JoinGuardSettings { RequireMatchingMods = true }); BreakoutSettingsSync.Client.Register<JoinGuardSettings>( "joinguard.settings", settings => ApplyServerSettings(settings));

服务器会定期广播已注册的设置，并在有会话可用时进行广播。客户端只应用来自服务器对等端的设置数据包。

侧边与同伴助手

如果 (BreakoutSide.IsDedicatedServer) { // 仅服务器中继。 } foreach (ZNetPeer peer in BreakoutPeers.ConnectedPeers) { // 服务器可见的对等端。 }

安全默认值

每个BreakoutNet套餐均包含：

• 协议版本
• RPC 名称
• 发送者模组GUID
• 信息类型名称
• 序号

BreakoutNet会拒绝未知协议版本、未注册的RPC名称、来自非服务器对等端的客户端消息、不匹配的DTO类型以及过多的入站客户端RPC。

服务器RPC默认使用保守的入站客户端速率限制。语音帧等高频流可以选择使用更大的令牌桶：

BreakoutRpc.Server.Register<VoiceFrame>( "voip.voice.frame", OnVoiceFrame, BreakoutRpcRateLimit.ForMessagesPerSecond(60f, 3f));

扩展事件

模组可以发布本地类型化事件，用于模块内部通信：

Context.Events.Subscribe<MyEvent>(OnEvent); Context.Events.Publish(new MyEvent());

命名事件可用于公共扩展点：

Context.Events.Subscribe<MyEvent>("joinguard.policy.checked", OnPolicyChecked); Context.Events.Publish("joinguard.policy.checked", new MyEvent());

只读核心钩子暴露 BreakoutNet 生命周期和 RPC 观测：

Context.Hooks.OnNetworkReady(OnReady); Context.Hooks.OnPeerJoined(OnPeerJoined); Context.Hooks.OnRpcRejected(OnRpcRejected);

更多详情： 文档/扩展.md

建造

.\build.ps1 -Configuration Release

仅在您明确要求时，才部署到此 Valheim 服务器安装中：

.\build.ps1 -Configuration Release -Deploy

依赖项

• BepInEx 5.x
• 英灵神殿程序集