跳到主要内容

客户端资源版本与连接信息

萌芽引擎在客户端连接服务端时，会把客户端信息同步给 GermPlugin。服务端可以据此判断玩家资源是否过旧，也可以在插件开发中读取玩家当前客户端版本和资源版本。

这套能力由双端配合完成：

  • GermMod 读取客户端 GermMod.cfg 中的 clientVersion、resourceVersion。
  • 玩家连接完成后，GermMod 将这些字段上报给 GermPlugin。
  • GermPlugin 按服务端 Config.yml 判断是否允许进入，并在 GermClientLinkedEvent 中暴露字段。

客户端配置​

客户端配置位于：

.minecraft/config/GermMod.cfg

常用字段：

settings {
    # 客户端版本标识，可以用于区分整包、渠道或定制客户端。
    S:clientVersion=pc-vlatest

    # 客户端资源版本号，建议每次发布新资源包时递增。
    I:resourceVersion=1
}

clientVersion 更适合写可读的客户端标识，例如 pc-v2025-09、launcher-a、rpg-pack-2。

如果 clientVersion 中包含 dev，客户端会被视为开发/测试客户端。开发客户端适合直接调试 .minecraft/GermCache 中的明文资源；正式玩家使用的客户端不要包含 dev，这样才能按正式资源加载规则读取加密后的本地 source。

resourceVersion 对应客户端 EngineConfig.resourceVersion，建议只写整数。每次发布新的正式客户端资源包、调整加密资源或替换客户端本地 source 后，都应该同步递增这个值。服务端的最低版本检测只会比较这个数字，不会自动逐个校验客户端文件内容。

例如正式资源包从 10 更新到 11 后，客户端需要同步修改：

settings {
    I:resourceVersion=11
}

服务端最低资源版本​

服务端配置位于：

plugins/GermPlugin/Config.yml

在 Settings 下配置：

Settings:
  resourceVersionCheck: 10
  resourceVersionMsg: "§c你的客户端资源过旧，请更新客户端"

含义：

配置作用
resourceVersionCheck最低资源版本。设置为 -1 时不检测。
resourceVersionMsg玩家资源版本过低时的踢出提示。

例如服务器当前资源包版本是 10，玩家客户端 GermMod.cfg 中仍是 8，连接时会被服务端拒绝，并显示 resourceVersionMsg。

开发者强制下发配置​

正常情况下，sendSrcDebug: false 时会按 sendSrcBlackList、sendSrcWhiteList 过滤要下发给客户端的配置或资源索引。

如果正在调试某个玩家的客户端资源，可以把玩家名加入 sendSrcDevList：

Settings:
  sendSrcDebug: false
  sendSrcDevList:
    - "GermMC"

列表中的玩家会强制接收服务端 src 配置，适合用于：

  • 调试新 GUI、模型、物品配置是否正确同步。
  • 让开发者账号接收测试目录，普通玩家继续按黑白名单过滤。
  • 在不全服开启 sendSrcDebug 的情况下进行资源排查。

与客户端本地 source 配合​

如果把固定 source 放进客户端资源包，可以用黑白名单减少服务端下发量。典型配置如下：

Settings:
  sendSrcDebug: false
  sendSrcDevList:
    - "GermMC"
  sendSrcBlackList:
    - "item/fixed/"
    - "animation/fixed/"
    - "misc/client/"

普通玩家不会收到这些被黑名单过滤的服务端 source，需要客户端资源中已经存在对应文件，例如：

.minecraft/GermCache/src/item/fixed/sword.yml
.minecraft/GermCache/src/animation/fixed/weapon.yml
.minecraft/GermCache/src/misc/client/display.yml

正式分发时，把这些文件通过 /gp misc encrypt pack 打进 mcpack.uze，或通过 /gp misc encrypt folder 生成 resourcepacks/GermMod 加密目录。正式客户端加载加密资源后，会把其中的 src/<类型>/<配置文件名> 注册为客户端本地 source。

sendSrcDevList 中的玩家仍会收到服务端完整 source。服务端下发同名 source 时会覆盖客户端本地同名 source，所以测试人员可以看到服务端最新配置，普通玩家则使用客户端加密资源中的稳定配置。

注意

黑白名单只控制服务端是否下发 source，不会自动检查玩家客户端是否真的带了对应本地文件。把某个 source 从服务端下发中过滤前，需要确认正式客户端资源包中已经包含同名 src 文件，并同步更新 resourceVersion 或启动器资源版本。

开发 API​

插件开发者可以监听 GermClientLinkedEvent，读取玩家上报的客户端信息：

@EventHandler
public void onClientLinked(GermClientLinkedEvent event) {
    Player player = event.getPlayer();
    String modVersion = event.getModVersion();
    String clientVersion = event.getClientVersion();
    int resourceVersion = event.getResourceVersion();

    player.sendMessage("客户端版本: " + clientVersion);
    player.sendMessage("资源版本: " + resourceVersion);
}

注意事项：

  • 事件发生时，萌芽客户端已经完成连接握手。
  • resourceVersionCheck 是服务端内置的最低版本校验；如果需要更复杂的分组、渠道、灰度策略，可以在事件中自行判断。
  • 代理模式下跨服事件可能没有完整客户端字段，开发者需要对空值或 -1 做兼容处理。