跳到主要内容

进阶功能:MODSDK(PythonRPC)包的使用与交互

从客户端开发来看,这套方案沿用中国版 Add-On 的原生 MOD SDK 写法。资源包和行为包仍按 Add-On 的目录结构组织,客户端脚本照常注册系统,用 NotifyToServer 发出自定义事件,用 ListenForEvent 监听引擎事件和服务端回复。

在 Paper + Geyser 部署中,由 Paper 插件实现原生 MOD SDK 服务端系统负责的玩法逻辑,包括接收客户端事件、处理请求和发送回复。Geyser 和配套 Floodgate 负责转发 PythonRPC 消息,两端仍按约定的命名空间、系统名、事件名和参数通信。

客户端进服后向 Paper 查询提示键 welcome,再从资源包取出「欢迎进入服务器!PythonRPC 联通成功。」示例用 SetTipMessage 在快捷栏上方显示文案,同时用 SetLeftCornerNotify 在本机左上角显示聊天通知。SetTipMessage 接口文档、SetLeftCornerNotify 接口文档

示例项目​

在 GeyserDemo 的 pythonrpc-demo/ 子目录可以找到两个包和完整的 Paper 插件。行为包清单通过资源包的 header.uuid 和版本声明依赖。GeyserDemo 仓库

中国版 MOD SDK 脚本仅支持 Python 2.7。示例中的 basestring 和 unicode 用来处理 2.7 中的字符串类型。

pythonrpc-demo/
├── packs/
│ ├── behavior_packs/
│ │ └── RpcDemo_BP/
│ │ ├── manifest.json
│ │ └── RpcDemoScripts/
│ │ ├── __init__.py
│ │ ├── modMain.py
│ │ └── client.py
│ └── resource_packs/
│ └── RpcDemo_RP/
│ ├── manifest.json
│ └── modconfigs/
│ └── geyser_rpc_demo.json
├── src/main/
│ ├── java/com/example/rpcdemo/
│ │ ├── RpcDemoPlugin.java
│ │ └── RpcPacket.java
│ └── resources/plugin.yml
└── build.gradle

使用前文的 Paper 1.21.11、Velocity、布吉岛版 Geyser 和配套 Floodgate。Velocity 端启用 send-floodgate-data: true,Velocity 与 Paper 使用同一份 key.pem。项目部署、配套 Geyser、配套 Floodgate

两端怎样交换事件​

方向命名空间系统名事件参数
客户端 → PaperRpcDemoRpcDemoClientSystemQueryServerMessagerequestId
Paper → 客户端RpcDemoRpcDemoServerSystemServerMessagerequestId、tipKey

modMain.py 从 @Mod.InitClient() 注册 RpcDemoClientSystem,类路径为 RpcDemoScripts.client.RpcDemoClient。client.py 先注册 ServerMessage 的监听,然后在 OnLocalPlayerStopLoading 回调里执行下方代码。这个事件在出生点地形加载完成时触发。Python 脚本开发入门、世界事件文档、NotifyToServer 接口文档

data = self.CreateEventData()
data["requestId"] = "demo-1"
self.NotifyToServer("QueryServerMessage", data)

Paper 的 RpcDemoPlugin 用 Bukkit Messenger 监听 floodgate:netease。RpcPacket 解码请求,核对事件名和 requestId。回包沿用同一个 requestId,并指定 tipKey 为 welcome。下面用 JSON 表示回包结构。插件会将它编码为 MessagePack,再用 GZIP 压缩,通过配套 Floodgate 的 neteaseCustomChannel 发回该玩家。

[
"ModEventS2C",
["RpcDemo", "RpcDemoServerSystem", "ServerMessage", {"requestId": "demo-1", "tipKey": "welcome"}],
null
]

客户端显示资源包里的提示​

在资源包的 modconfigs/geyser_rpc_demo.json 中用 welcome 作为文案的键。

RpcDemo_RP/modconfigs/geyser_rpc_demo.json
{
"welcome": "欢迎进入服务器!PythonRPC 联通成功。"
}

client.py 核对 requestId 后按 tipKey 查找文案,并把 unicode 转成 UTF-8 编码的 str。用本地玩家 ID 创建 Game 组件显示快捷栏提示,再用 GetLevelId() 创建 TextNotifyClient 组件显示本机的聊天通知。print 用于记录脚本日志。GetModConfigJson 接口文档、客户端 API 索引

def on_reply(self, args):
if args.get("requestId") != "demo-1":
return

tip_key = args.get("tipKey")
if not isinstance(tip_key, basestring):
return

tips = clientApi.GetModConfigJson("modconfigs/geyser_rpc_demo.json")
text = tips.get(tip_key)
if not isinstance(text, basestring) or not text:
print("[RpcDemo] Tip missing in resource pack: {}".format(tip_key))
return

if isinstance(text, unicode):
text = text.encode("utf-8")
factory = clientApi.GetEngineCompFactory()
game = factory.CreateGame(clientApi.GetLocalPlayerId())
if game.SetTipMessage(text):
print("[RpcDemo] Displayed tip: {}".format(tip_key))
else:
print("[RpcDemo] Could not display tip: {}".format(tip_key))

notify = factory.CreateTextNotifyClient(clientApi.GetLevelId())
if not notify.SetLeftCornerNotify("[RpcDemo] " + text):
print("[RpcDemo] Could not show chat notice: {}".format(tip_key))

部署与联调​

  1. 安装 JDK 21。将配套 floodgate-spigot.jar 放入 pythonrpc-demo/libs/,在该项目目录运行 .\gradlew.bat build。Linux 或 macOS 使用 sh ./gradlew build。
  2. 将生成的 build/libs/pythonrpc-demo-1.0.0.jar 放入 Paper 子服的 plugins/。启动 Paper,检查 RpcDemo 和 floodgate 是否加载成功。
  3. 把示例 packs/ 中的 RpcDemo_RP/、RpcDemo_BP/ 分别放进网易服务器预下载模板的 resource_packs/、behavior_packs/,一起打包,上传到服务器编辑界面并自测。通过自测后下载加密 ZIP,部署到 Geyser 的 packs/Encryption/。打包与部署步骤
  4. 用目标中国版客户端进服,检查快捷栏上方的提示和左上角带 [RpcDemo] 前缀的聊天通知。可以对照 Paper 日志 QueryServerMessage -> ServerMessage (demo-1) 和脚本日志 [RpcDemo] Displayed tip: welcome。退出并重新进服即可再次触发。
现象排查位置
客户端没有输出 Client system ready检查预下载中是否包含行为包,以及 modMain.py、RegisterSystem 的类路径。
客户端脚本已启动,Paper 没有记录请求检查配套 Floodgate、代理的数据转发、频道注册和 C2S 事件名。
Paper 已回包,客户端提示资源包里缺少文案检查资源包是否随包体加载,核对 modconfigs/geyser_rpc_demo.json 路径和 welcome 键。
更新包后文案仍是旧版更新资源包版本及行为包中的依赖版本,再核对预下载版本和 Geyser 加载的加密包。