跳到主要内容
Release Notes

萌芽引擎更新记录

最新稳定版4.5.3
2026 年 7 月

GermEngine 4.5.3

4.5.3 补齐 GUI 颜色块组件的多边形线框绘制能力说明,新增 GUI 自定义组件能力,同步玩家背包 JEI 配置,完善客户端本地 source 资源分发说明,并扩展 MythicMobs 模型技能。

GUI 自定义组件

GUI yml 顶级 components 节点会作为公共组件库加载,某个 GUI 的 options.components 可以定义当前 GUI 私有组件。组件使用 props 定义参数,root 定义内部根部件;普通 GUI 中通过 type: component 引用组件,运行时会创建真实的 component 容器。

复用商品条目组件
components:
  商品条目:
    props:
      id: "unknown"
      name: "商品"
      price: "0"
    root:
      type: canvas
      width: "180"
      height: "64"
      relativeParts:
        名称:
          type: label
          texts:
            - "&f${props.name}"
        购买:
          type: button
          width: "40"
          height: "24"
          clickScript: |
            var itemId = '${props.id}';
            Log.chat('准备购买商品: ' + itemId);

商店界面:
  商品列表画布:
    type: canvas
    width: "400"
    height: "180"
    layout:
      type: FLOW
      gapX: "10"
      gapY: "8"
    relativeParts:
      商品_1:
        type: component
        component: 商品条目
        props:
          id: "diamond_sword"
          name: "钻石剑"
          price: "100"
      商品_2:
        type: component
        component: 商品条目
        props:
          id: "heal_potion"
          name: "治疗药水"
          price: "80"

颜色块组件支持多边形

color 组件的 shape 用来选择绘制形状:rectangle 为矩形色块,line 为线条。line 配合 points 时,会按点位顺序绘制多边形线框;points 坐标相对当前组件的 locationX/locationY。

绘制一个多边形线框
colorPolygon:
  type: color
  locationX: "w*0.4"
  locationY: "h*0.15"
  shape: "line"
  points:
    - "0<->0"
    - "80<->20"
    - "60<->90"
    - "10<->70"
  color: 0xFFFFAA00

玩家背包 JEI 显示配置

自定义玩家背包的 private.other 配置补齐 jeiEnable 和 jeiPadding 示例。jeiEnable 用来控制萌芽背包界面是否显示 JEI,默认关闭;jeiPadding 用来调整 JEI 区域边距,数值越大 JEI 可用区域越小。

在自定义玩家背包中开启 JEI
private:
  other:
    jeiEnable: true
    jeiPadding: 8

伤害悬浮字总开关

3DDamageDisplay 新增 enable 总开关。关闭后默认伤害显示和 CustomDamageDisplayChannel 都不会继续显示,适合给玩家选项或性能预设统一控制伤害悬浮字。

通过配置或 DOS 控制伤害悬浮字
ClientOptions:
  3DDamageDisplay:
    enable: true

# 运行时控制
updateClient<->damageSystem@true/false

客户端本地 source 与省流量分发

客户端资源分发文档补齐本地 source 配置链路。固定、变化少且不敏感的 item、misc、animation、gui、entity、effect 等 source 可以先放入客户端 GermCache/src 调试,再通过 pack 或 folder 加密方式随正式客户端资源分发,减少普通玩家进服时服务端下发的 source 数据量。

把固定 source 前置到客户端资源
.minecraft/GermCache/src/item/fixed/sword.yml
.minecraft/GermCache/src/animation/fixed/weapon.yml
.minecraft/GermCache/src/misc/client/display.yml

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

MythicMobs 模型技能扩展

MythicMobs 拓展新增指定槽位基岩物品动画技能,可以让怪物手持的远程武器、枪械、弓弩等模型直接播放 attack、reload 等物品动画;同时补齐骨骼隐藏、显示与显隐设置技能,并修复骨骼替换技能只记录状态但没有稳定下发的问题。

让怪物主手物品播放攻击动画
Skills:
  - ItemAnimation{name=attack;slot=main;speed=1.2} @self ~onAttack
  - BoneHide{bone=rightArm} @self ~onSpawn
  - BoneShow{bone=rightArm} @self ~onDamaged

修复与稳定性优化

优化伤害悬浮字渲染缓存与清理逻辑,修复 GUI 物品预览旋转速度不生效、GUI 自定义组件缓存生命周期、实体模型改名事件干扰和模型替换包延迟应用问题;同时补充 folder 加密超长资源路径提示、验证服务器静默重连、实体状态首次同步与原版容器子界面层级提示。

2026 年 6 月

GermEngine 4.5.2

4.5.2 继续补齐 GUI 文本与图片组件的缩放、旋转锚点控制,补充 icon 物品动态旋转,并优化客户端地图的本地调试和正式分发流程。

文本组件缩放锚点

label 文本组件新增 scaleAnchor,用来控制 scale 缩放时围绕文字盒的哪个点变化。未配置 scaleAnchor 时保持旧版逻辑:align 同时决定文字水平排版和缩放锚点,left 按 left_top 缩放,center 按 top 缩放,right 按 right_top 缩放。配置 scaleAnchor 后,缩放锚点由 scaleAnchor 接管,align 继续只控制文字水平排版。

让文本按中心缩放
label:
  type: label
  align: "center"
  scale: "2"
  scaleAnchor: "center"

图片组件尺寸与变换锚点

texture、gif、frame 图片组件新增 sizeAnchor、scale、scaleAnchor、rotateAnchor;button 和 checkbox 新增 sizeAnchor、scale、scaleAnchor、rotateX、rotateY、rotateZ、rotateAnchor,checkbox 的 checked 图片额外支持 checkedSizeAnchor、checkedScale、checkedScaleAnchor、checkedRotateX、checkedRotateY、checkedRotateZ、checkedRotateAnchor。sizeAnchor 用来控制 width/height 尺寸变化时固定哪个点,默认 left_top,未配置时保持旧版左上角定位表现。

让图片按中心应用 width 和 height
texture:
  type: texture
  path: "local<->textures/misc/logo.png"
  locationX: "w*0.5"
  locationY: "h*0.5"
  width: "200"
  height: "80"
  sizeAnchor: "center"
  rotateZ: "45"
  rotateAnchor: "center"

icon 物品动态旋转

icon 物品的 transformSetting 新增 rotateSpeedX、rotateSpeedY、rotateSpeedZ,可按视角配置动态旋转速度,单位为度/秒,并会叠加 rotateX、rotateY、rotateZ 的初始角度。

让图标物品在 GUI 中自转
default_icon_item:
  type: "icon"
  path: "textures/misc/logo.png"
  transformSetting:
    gui:
      scaleX: 0.5
      scaleY: 0.5
      scaleZ: 0.5
      rotateSpeedY: 90

客户端地图支持未加密调试

客户端地图不再对开发客户端删除 GermCache/worlds。clientVersion 包含 dev 时,可以直接把未加密地图放进 GermCache/worlds 测试;正式客户端会在资源加载时清理旧地图,再从 mcpack.uze 或 folder 加密目录同步客户端地图。

2026 年 6 月

GermEngine 4.5.1

4.5.1 集中修复特殊武器动作、实体模型特效重载、客户端地图区块隔离和玩家飞行动作判断,并补齐原版槽位颠覆的批量配置、变量替换和物品缩放锚点。

特殊武器动作参数修复

specialItem 的 triggerHandlers.duration、lockMove、lockCamera、lockView、lockQuickbar、disableSprint 继续支持 50%、90% 这类百分比写法,会按玩家动画时长换算,不再因为百分比文本解析失败而退回 0。playerAnimations 的播放速度也支持变量解析,例如 jian_1;%xa_aps% 或 name=jian_1;speed=%xa_aps%,不会再退回默认 1 倍速。

按动画时长衔接,并用攻速变量控制动画速度
triggerHandlers:
  attack1:
    duration: "50%"
    lockMove: "90%"
    playerAnimations:
      - "jian_1;%xa_aps%"

原版槽位颠覆支持批量配置

玩家背包、箱子和熔炉颠覆的槽位配置支持 Default、Groups 和 Slot_数字 三层写法。Slot_数字 用来单独覆盖某个槽位,Groups 可以按 slots 范围批量排布,Default 用来给剩余槽位提供默认值。批量配置支持 columns、offsetX、offsetY,并在表达式、贴图路径和 tooltip 中替换 %slot_index%、%slot_relative%、%slot_row%、%slot_column%。

按 9 列批量排布 0-35 号槽位
SlotSettings:
  Groups:
    main:
      slots: "0-35"
      show: true
      columns: 9
      size: "16"
      locationX: "10"
      locationY: "30"
      offsetX: "18"
      offsetY: "18"
      fillPath: "textures/gui/slot_fill_%slot_index%.png"

原版槽位物品缩放锚点

槽位颠覆新增 itemSizeAnchor,用来控制 itemSize 缩放时以哪个点为基准。默认值仍是 left_top,保持旧版左上角缩放逻辑;如果希望物品缩放效果和 fillPath、emptyPath 这类槽位贴图一样从中心变化,可以配置为 center。

让物品按中心缩放
Slot_0:
  size: "32"
  itemSize: "24"
  itemSizeAnchor: "center"

实体模型 bindEffects 重载后自动重绑

修复实体模型通过 bindEffects 绑定到实体上的特效,在 source reload 或 GPU reload 后当前视距内实体看不到,需要离远再回来的问题。4.5.1 起,资源重载后已加载实体会在下一次渲染时重新执行首次渲染绑定逻辑,自动恢复绑定特效。

客户端地图区块加载隔离优化

客户端地图的区块加载流程做了隔离处理,减少客户端地图区块对原版世界和实体加载流程的干扰,降低使用客户端地图时实体闪烁或状态被临时覆盖的风险。

玩家飞行动作判断修复

修复特殊物品 redirectAnim 将玩家动作指向 flying 时,自己视角能正确播放 Flying,但其他玩家视角可能仍循环 Jump 的问题。现在本地玩家优先使用客户端状态,其他玩家使用离地时间判断,飞行动画同步更稳定。

2026 年 6 月

Camera2 运行时镜头命令

Camera2 新增运行时镜头命令。服务器可以通过 DOS 给玩家下发临时镜头效果,例如震屏、后坐力、冲刺拉镜、落地冲击、镜头聚焦目标,以及多条镜头命令批量播放。

play / patch / clear 三类镜头命令

play 适合一次性镜头冲击,patch 适合持续修改第三人称构图,clear 用来按频道淡出或清除镜头效果。每条命令都有 channel,重复使用同一 channel 可以覆盖旧效果,避免堆出不可控的镜头状态。

播放一次技能后坐和冲刺镜头
camera<->immersive@play@skill.recoil@preset=recoil@duration=220@out=180@motionPitch=-1.2@motionFov=1.4
camera<->immersive@play@skill.dash@preset=dash@duration=360@motionZ=-0.32@motionFov=1.85
camera<->immersive@clear@skill.recoil@out=180

用 patch 临时调整构图、偏肩和镜头姿态

patch 不只用来叠加震动,也可以临时调整第三人称镜头构图。配置作者可以按频道设置偏移、距离、偏肩、FOV、俯仰、旋转和 roll,并通过 delay、priority、in/out、curve 控制进入顺序和混合节奏。它适合技能蓄力、NPC 对话、Boss 注视、载具镜头和特殊场景构图。

技能蓄力时切到右肩并拉近镜头
camera<->immersive@patch@skill.aim@duration=-1@priority=80@shoulder=right@offsetX=0.35@offsetY=-0.1@distance=3.2@fov=4@in=180@out=220@curve=smoothstep
camera<->immersive@play@skill.fire@delay=160@duration=420@preset=recoil@motionPitch=-1.4@motionFov=1.2
camera<->immersive@clear@skill.aim@out=240

按频道管理镜头状态

Camera2 命令通过 channel 管理生命周期。默认情况下,同一个 channel 的新命令会替换旧命令,适合持续刷新技能镜头;需要多个镜头效果同时保留时,可以给它们不同 channel,或者显式使用 merge=additive。clear 支持精确频道、前缀通配和全量清理,方便在技能结束、副本退出或玩家死亡时恢复镜头。

按技能前缀统一清理镜头效果
camera<->immersive@patch@boss.phase1.focus@duration=-1@subject=entity@entityId=128@focusYaw=0.35
camera<->immersive@play@boss.phase1.hit@preset=shake@duration=650

# 只淡出 boss.phase1 这一组镜头
camera<->immersive@clear@boss.phase1.*@out=260

# 紧急恢复:清理所有 Camera2 运行时镜头命令
camera<->immersive@clear@*@out=180

预设快捷命令

如果只是想快速给玩家播放常见镜头反馈,可以直接使用 preset 快捷命令,不需要手写完整的 play / patch 参数。它适合技能测试、服主配置效果、脚本里快速触发后坐力、震屏、冲刺拉镜、落地冲击、聚焦和偏肩演示。

直接播放常用 Camera2 预设
camera<->immersive@preset@recoil
camera<->immersive@preset@dash
camera<->immersive@preset@land
camera<->immersive@preset@focus
camera<->immersive@preset@focusOff
camera<->immersive@preset@clear

预设组合、偏肩演示和分组清理

preset 也可以用来快速演示一组镜头效果。preset@all 会按顺序播放后坐力、冲刺、落地和震屏,适合确认客户端镜头系统是否生效;preset@shoulder 会把镜头短暂切到右肩再回中,适合测试偏肩构图。需要恢复时,可以只清聚焦,也可以清理 preset、test、effect 和 server.skill 这些常用镜头频道。

快速演示并恢复镜头状态
camera<->immersive@preset@all
camera<->immersive@preset@shoulder

# 只关闭持续聚焦
camera<->immersive@preset@focusOff

# 清理常用测试和技能镜头频道
camera<->immersive@preset@clear

目标聚焦与批量镜头

subject 可以让镜头柔和看向实体或世界坐标,不强制旋转玩家本体。json / batch 可以一次下发多条命令,适合技能、过场动画、Boss 机制中同时叠加构图、震动和聚焦。

聚焦实体并叠加镜头冲击
camera<->immersive@patch@boss.focus@duration=-1@profile=focus@subject=entity@entityId=128@focusYaw=0.35@focusPitch=0.22@maxYaw=9@maxPitch=5
camera<->immersive@play@boss.hit@preset=shake@duration=650@amp=1.0@freq=15
camera<->immersive@clear@boss.focus@out=220

JSON / batch 一次下发多条镜头命令

Camera2 命令可以直接接收 JSON。配置作者可以用一个对象表示单条命令,也可以用数组或 commands 包装对象一次下发多条命令。这样 Boss 技能、剧情演出和 GUI 按钮不需要连续写很多行 DOS,也更容易把震屏、构图、聚焦和收尾清理放在同一个配置块里维护。

把聚焦、震屏和清理写成一个批量命令
camera<->immersive@batch@{
  "commands": [
    {
      "action": "patch",
      "channel": "boss.focus",
      "durationMs": -1,
      "priority": 60,
      "subject": {
        "type": "entity",
        "entityId": 128,
        "yawStrength": 0.35,
        "pitchStrength": 0.22,
        "maxYaw": 9,
        "maxPitch": 5
      }
    },
    {
      "action": "play",
      "channel": "boss.hit",
      "delayMs": 180,
      "durationMs": 650,
      "motion": {
        "preset": "shake",
        "amplitude": 1.0,
        "frequency": 15
      }
    },
    {
      "action": "clear",
      "channel": "boss.focus",
      "delayMs": 1200,
      "blend": { "outMs": 220 }
    }
  ]
}
2026 年 6 月

镜头路径编辑输入保护

镜头路径编辑器补齐快捷键和输入保护。录制时可以用 P 快速标点;编辑器接管 Space、Tab、WASD、Q/E、左右箭头、加减号和滚轮,避免调整镜头时误触原版按键、切换快捷栏或触发缓存重载。

P 键快速标记路径点

录制镜头路径时,按 P 会直接把当前镜头状态记录为一个路径点,不再需要每次手动发送 mark DOS。只有在路径录制中才会接管 P;编辑器打开时也会吞掉 P,避免误触其他客户端功能。

用快捷键录制路径点
camera<->immersive@path@record@start
# 调整镜头位置后按 P 标记第 1 个点
# 再移动到下一处镜头位置,继续按 P 标记
camera<->immersive@path@record@stop

编辑器接管快捷键和滚轮

编辑模式暂停时,WASD、Q/E、左右箭头、加减号和滚轮会直接用于调整当前镜头点。客户端会拦截这些输入,并清理原版按键触发状态,避免原版移动、快捷栏滚动、其他按键绑定或缓存重载一起触发。

暂停后用键盘微调当前点
camera<->immersive@path@edit@start@mode=remote@start=current
camera<->immersive@path@edit@pause
# Space 保存当前点并继续预览
# Tab 切换姿态/点位模式
# 滚轮调整 FOV,+/- 调整当前点速度

编辑期间保护原版按键状态

编辑器现在会把 Space、Tab、P、WASD、Q/E、左右箭头、加减号和滚轮限制在镜头编辑用途里。按住这些键微调镜头时,不会同时积压原版按键触发状态,也不会在结束编辑后突然触发跳跃、切换物品栏或缓存重载。

安全地连续调整镜头点
camera<->immersive@path@edit@start@mode=remote@start=current
camera<->immersive@path@edit@pause
# 连续按住 W/S/A/D/Q/E 调整点位或姿态
# 用滚轮调 FOV,不会切换快捷栏
camera<->immersive@path@edit@stop

编辑退出自动恢复玩家视角

编辑路径时经常会进入分离镜头和第一人称预览。现在停止编辑会兜底恢复玩家原来的视角和相机控制,即使编辑预览过程中多次暂停、切换点位或从当前镜头接入,也不会把玩家留在远程镜头状态。

编辑完成后直接停止并回到玩家视角
camera<->immersive@path@edit@start@mode=remote@start=current@duration=8000
camera<->immersive@path@edit@pause
# 调整并保存当前点
camera<->immersive@path@edit@stop
2026 年 6 月

沉浸式第三人称角色活动区

沉浸式第三人称镜头新增角色活动区开关。开启后,玩家在镜头中心附近小范围移动时镜头不会立刻平移,接近活动区边界后才开始柔和跟随,适合动作服、RPG 服和需要更稳定观感的第三人称玩法。

角色小幅移动时镜头保持稳定

GermMod 会记录玩家在镜头局部坐标中的移动偏移,并把偏移限制在前后左右的活动区内。玩家停止移动后,偏移会平滑回到中心,避免镜头因为轻微走位或微调方向频繁晃动。

在服务端 Config.yml 中开启
ClientOptions:
  PlayerPerspective:
    immersiveDeadZone: true
    immersiveDeadZoneXZ: [0.35, 2.05, 1.0, 4.0]

服务端统一配置开关

角色活动区开关和范围由服务端第三人称视角配置管理。比如副本、剧情、主城展示区可以开启活动区,PVP 或需要传统镜头反馈的玩法中关闭。

关闭角色活动区
ClientOptions:
  PlayerPerspective:
    immersiveDeadZone: false
2026 年 6 月

镜头路径运镜

新增 Camera2 镜头路径能力。客户端可以录制点位、预览和编辑运镜;服务端可以保存路径、下发给玩家播放,也可以通过 API 在剧情、过场动画、副本开场或教学引导中复用同一条镜头路线。

客户端录制和播放镜头路径

GermMod 会把当前镜头位置、朝向、roll、FOV 和点位速度记录成路径点。路径至少需要 2 个点,播放时会自动插值成平滑镜头,可选择第三人称镜头或分离镜头模式。

录制一条本地镜头路径并播放
updateClient<->engineConfig@enableImmersiveThirdPersonCamera@true
camera<->immersive@path@record@start
camera<->immersive@path@mark@speed=1.0
camera<->immersive@path@mark@speed=1.4@fov=8
camera<->immersive@path@record@stop
camera<->immersive@path@play@duration=6000@mode=remote@ease=smooth

录制起点和后续标点都能覆盖镜头参数

开始录制时,record@start 会立即把当前镜头记录为第一个路径点;后续每次 mark 再追加新的路径点。配置作者可以在 start 或 mark 上覆盖 yaw、pitch、roll、fov 和 speed,用来修正起点朝向、给关键帧加横滚、临时拉 FOV,或者让某个点附近播放得更慢。

录制时直接指定起点和关键点参数
camera<->immersive@path@record@start@yaw=90@pitch=8@fov=4@speed=0.8
camera<->immersive@path@mark@roll=5@fov=8@speed=1.4
camera<->immersive@path@mark@yaw=130@pitch=12@speedScale=0.65
camera<->immersive@path@record@stop
camera<->immersive@path@play@mode=remote@ease=smooth

分离镜头播放与视角恢复

mode=remote 会让镜头脱离玩家本体,按路径点直接移动相机位置和朝向,适合剧情过场、Boss 登场、地图展示和教学引导。播放结束时可以自动恢复玩家原来的视角,也可以保留分离镜头状态交给后续 DOS 继续控制。

从当前镜头平滑接入过场路径
camera<->immersive@path@play@mode=remote@start=current@duration=7000@ease=smooth@restore=true@view=first

# 如果要把镜头交给后续 remoteCamera 或其他 DOS 继续控制
camera<->immersive@path@play@mode=remote@duration=5000@restore=false

自动时长、点位速度和缓动曲线

路径播放可以显式指定 duration,也可以省略时长交给客户端按路径距离自动计算。每个路径点的 speed 会参与路段耗时计算,适合让镜头在重点画面附近慢下来、在普通飞行段加快;ease=smooth 会把整段播放改成缓入缓出的节奏。

让同一条路径按画面重点变速
camera<->immersive@path@record@start
camera<->immersive@path@mark@speed=0.6@fov=4
camera<->immersive@path@mark@speed=1.8
camera<->immersive@path@mark@speed=0.8@roll=6
camera<->immersive@path@record@stop

# 不写 duration 时按距离和 speed 自动估算时长
camera<->immersive@path@play@mode=remote@ease=smooth@restore=true

# 需要卡剧情时间轴时,再显式指定 duration
camera<->immersive@path@play@mode=remote@duration=9000@ease=smooth@restore=true

路径命令支持简写和参数别名

为了方便把镜头路径接进已有 GUI、脚本或技能配置,路径播放参数支持多种等价写法。播放时可以直接把一个纯数字当作 duration;mode 也可以写成 driver,remote 也可以写成 sp 或 spectator;start 也可以写成 from,current 也可以写成 now 或 camera;collision 也可以写成 collide,ease 也可以写成 timeCurve 或 speedCurve。录制点位时,FOV 和点位速度也支持 fovOffset、speedScale 这类更贴近配置语义的名字。

用简写播放同一条路径
# 完整写法
camera<->immersive@path@play@duration=7000@mode=remote@start=current@collision=false@ease=smooth

# 等价简写,适合塞进较短的 DOS 配置
camera<->immersive@path@play@7000@driver=sp@from=now@collide=false@timeCurve=smooth

# 标点时也可以使用语义更明确的别名
camera<->immersive@path@mark@fovOffset=6@speedScale=1.35

分离镜头连续接入与 FOV / roll 保留

分离镜头播放时,路径点里的 FOV 和 roll 会继续作用到实际相机上;如果当前已经处在分离镜头或远程观察状态,start=current 会从当前相机位置继续接入下一段路径,减少多段过场之间突然跳镜头的问题。

把两段过场镜头连续接起来
# intro_a / intro_b 的 duration、start、restore 等参数写在各自 options 中
camera<->immersive@path@server@play@intro_a
camera<->immersive@path@server@play@intro_b

# 路径点里的 roll / fov 会在分离镜头中继续生效
camera<->immersive@path@mark@roll=8@fov=6@speed=1.2

路径碰撞与默认恢复行为

路径播放可以决定是否保留第三人称镜头碰撞。分离镜头默认不受墙体回缩影响,镜头会严格按路径点飞行;如果想让展示镜头避开墙体遮挡,可以显式开启 collision=true。编辑模式退出时默认恢复玩家原视角,避免调完镜头后把玩家留在分离镜头状态。

按过场需求选择碰撞和恢复
# 完整过场:按路径飞行,结束后恢复玩家视角
camera<->immersive@path@play@mode=remote@duration=7000@collision=false@restore=true

# 狭窄室内展示:保留第三人称碰撞,避免镜头穿进墙体
camera<->immersive@path@play@mode=remote@duration=5000@collision=true@restore=true

# 多段镜头衔接:播放结束后暂不恢复,交给后续 DOS 接管
camera<->immersive@path@play@mode=remote@duration=5000@restore=false

内置镜头路径编辑器

路径可以进入编辑模式,客户端会显示编辑 HUD。玩家可以暂停到当前镜头点,调整姿态、点位、FOV 和点位速度,再继续预览,适合边看效果边修过场镜头。

从当前镜头进入编辑预览
camera<->immersive@path@edit@start@mode=remote@start=current@duration=8000@ease=smooth
camera<->immersive@path@edit@pause
camera<->immersive@path@edit@mode
camera<->immersive@path@edit@stop

编辑 HUD 显示状态、模式和当前可用操作

进入路径编辑后,客户端会在屏幕左侧显示镜头路径编辑面板。面板会告诉配置作者当前是预览飞行还是暂停编辑、正在使用分离镜头还是第三人称、路径点数量、播放时长、时间曲线,以及暂停时当前点的速度。这样调过场时不用反复看聊天栏,也能知道下一步应该按哪个键。

进入编辑器后按 HUD 提示调整路径点
camera<->immersive@path@edit@start@mode=remote@start=current@duration=8000@ease=smooth

# HUD 显示“预览飞行”时
# Space 暂停到当前镜头点,Tab 切换姿态/点位模式

# HUD 显示“已暂停”时
# 姿态模式:W/S 调俯仰,A/D 调横滚,Q/E 调偏航,滚轮调 FOV
# 点位模式:W/S 前后,A/D 左右,Q/E 上下,滚轮调 FOV
# +/- 调整当前点速度,Space 保存并继续预览

服务端保存、加载和播放路径

GermPlugin 会把镜头路径保存为 misc source 中的 immersiveCameraPath 配置。OP 可以把客户端当前路径保存到服务端,后续通过路径名加载、播放、编辑、删除或列出;播放和编辑参数写在该路径的 options / editOptions 中,方便随服务器配置一起维护。

把路径保存到服务端并让玩家播放
camera<->immersive@path@server@save@spawn_intro
camera<->immersive@path@server@list
camera<->immersive@path@server@play@spawn_intro
camera<->immersive@path@server@edit@spawn_intro
camera<->immersive@path@server@delete@spawn_intro

路径状态与服务端反馈

路径命令会把当前状态和服务端处理结果反馈到玩家聊天栏。配置作者可以直接查看当前是否正在录制、播放、编辑、暂停、使用哪种模式、路径点数量和播放时长;服务端路径不存在、保存失败、权限不足等问题也会返回明确提示。

检查当前路径状态和服务端路径库
camera<->immersive@path
camera<->immersive@path@server@list
camera<->immersive@path@server@load@spawn_intro

调试时可单独停止、清空或导入路径

路径调试不一定每次都要完整走保存和播放流程。配置作者可以随时查看状态、停止当前播放、清空本地路径点,或者只把服务端路径 source 下发到客户端命名缓存,随后再按名称播放或进入编辑器。

调试路径时先导入,再决定下一步
# 查看当前录制、播放、编辑和点位状态
camera<->immersive@path

# 停止当前路径播放,不清空已经录制或导入的点位
camera<->immersive@path@stop

# 清空客户端当前路径点和播放状态
camera<->immersive@path@clear

# 只把服务端路径 source 下发到客户端命名缓存,不立即播放
camera<->immersive@path@server@load@spawn_intro
camera<->immersive@path@server@import@spawn_intro

# 下发后再按名称播放或编辑
camera<->immersive@path@play@spawn_intro
camera<->immersive@path@edit@start@spawn_intro

插件 API 调用镜头路径

插件开发者可以通过 GermPacketAPI 保存、读取、删除、列出、下发、播放和编辑镜头路径,不需要自己处理底层 77 号网络包。适合把过场动画接到 NPC 对话、剧情任务、副本开场或技能展示中。

在插件中播放已保存的镜头路径
GermPacketAPI.playCameraPath(player, "spawn_intro");

服务端路径库 API 全流程

GermPacketAPI 补齐了服务端路径库的常用操作:保存路径 JSON、读取路径、列出路径名、删除路径、只下发路径、下发后播放、下发后进入编辑。插件可以把镜头路径当作服务器资源来管理,不必让每个玩法模块自己读写文件或拼网络包。

在插件里维护并复用一条路径
GermPacketAPI.saveCameraPath("spawn_intro", pathJson);

List<String> paths = GermPacketAPI.listCameraPaths();
String json = GermPacketAPI.loadCameraPath("spawn_intro");

GermPacketAPI.sendCameraPath(player, "spawn_intro", json);
GermPacketAPI.editCameraPath(player, "spawn_intro");
GermPacketAPI.playCameraPath(player, "spawn_intro");

GermPacketAPI.deleteCameraPath("old_spawn_intro");

路径 JSON 与插件下发

镜头路径可以用 JSON 表示,插件既可以把 JSON 保存到服务端路径库,也可以临时下发给某个玩家。这样剧情插件、任务插件或副本插件可以在代码里生成路径,不必要求配置作者先在客户端录制。

直接保存并播放一条插件生成的路径
String pathJson = "{\"version\":1,\"points\":["
    + "{\"x\":0,\"y\":72,\"z\":0,\"yaw\":0,\"pitch\":8,\"roll\":0,\"fov\":0,\"speed\":1},"
    + "{\"x\":8,\"y\":74,\"z\":-6,\"yaw\":45,\"pitch\":12,\"roll\":0,\"fov\":6,\"speed\":1.4}"
    + "]}";

GermPacketAPI.saveCameraPath("boss_intro", pathJson);
GermPacketAPI.playCameraPath(player, "boss_intro");
2025 年 9 月

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

客户端连接服务端时会同步客户端版本和资源版本。服务端可以拒绝资源过旧的玩家,也可以在连接事件中读取这些字段,方便做资源包更新提示、渠道判断和开发调试。

客户端上报 clientVersion / resourceVersion

GermMod 会从客户端 GermMod.cfg 中读取 clientVersion 与 resourceVersion,并在完成连接握手时发送给 GermPlugin。clientVersion 适合标记整包或渠道,resourceVersion 适合做资源包最低版本判断。

在客户端 GermMod.cfg 中维护资源版本
settings {
    S:clientVersion=pc-v2025-09
    I:resourceVersion=10
}

服务端最低资源版本检测

GermPlugin 在收到客户端连接信息后,会读取 Settings.resourceVersionCheck。该值不是 -1 且玩家 resourceVersion 低于要求时,会直接使用 resourceVersionMsg 踢出并提示玩家更新客户端。

在 Config.yml 中要求最低资源版本
Settings:
  resourceVersionCheck: 10
  resourceVersionMsg: "§c你的客户端资源过旧,请更新客户端"

开发者 src 强制下发白名单

sendSrcDevList 可以在 sendSrcDebug 关闭时,为指定玩家强制下发服务端 src 配置。这样开发者可以接收调试配置,普通玩家仍然按黑白名单过滤。

只让开发者账号接收调试配置
Settings:
  sendSrcDebug: false
  sendSrcDevList:
    - "GermMC"

GermClientLinkedEvent 暴露更多客户端字段

插件开发者可以在 GermClientLinkedEvent 中读取 getClientVersion() 和 getResourceVersion(),结合已有的 modVersion、机器码、IP 等信息做兼容检查、统计或二次验证。

监听客户端连接事件
@EventHandler
public void onClientLinked(GermClientLinkedEvent event) {
    String clientVersion = event.getClientVersion();
    int resourceVersion = event.getResourceVersion();
}
2025 年 4 月

客户端本地 source 配置

客户端加密资源开始支持本地 source 配置。除 misc 外,GUI、物品、实体、特效等配置可以随客户端资源一起加密分发,适合把纯展示层配置前置到客户端资源包中。

加密资源内置 src 配置

正式客户端加载 folder 加密资源时,会扫描 src/<类型>/<配置文件名>。例如 src/gui/menu.yml 会注册为 GUI source,src/item/sword.yml 会注册为物品 source。这样服务端可以只负责打开或引用配置,客户端负责加载随资源包分发的前端配置。

把 GUI 配置作为客户端资源分发
GermCache:
  src:
    gui:
      menu.yml
      hud/status.yml
    item:
      sword.yml

GermCache 加载缓存优化

GermCache 的本地文件扫描和缓存加载做了优化,减少资源重载时重复读取带来的卡顿,并让本地调试资源、网络缓存资源和加密资源的加载顺序更稳定。

2024 年 5 月

GermEngine 4.4.0 资源分发

4.4.0 维护线补充 folder 加密资源、base64 图片加载和资源分发链路优化,让客户端资源更适合配合启动器或更新器做增量分发。

folder 加密资源

新增 folder 加密方式,会把资源散列到 resourcepacks/GermMod 目录下,并隐藏文件名和目录名。客户端加载时根据加密文件中的真实路径重建资源索引,适合更新器只替换变化文件。

生成 folder 加密目录
/gp misc encrypt folder

base64 图片加载

资源加载链路补充 base64 图片读取能力,适合少量动态图片或插件侧临时生成图片,不需要先把图片写成传统本地文件再引用。

2023 年 6 月

GermEngine 4.3.7 客户端地图与二次加密

4.3.7 开始引入客户端地图、本地地图加载和资源二次加密能力,为大型副本、场景展示和客户端本地渲染补全提供基础。后续版本继续优化匹配方式、区块加载隔离和 folder 分发支持。

客户端地图

客户端可以读取 GermCache/worlds 下的本地世界区块,并在服务端切换到指定世界时用本地地图补全渲染。该能力适合大型副本、展示地图或不希望服务端实时发送全部区块的场景。

配置服务端世界到客户端地图的映射
ClientOptions:
  ClientWorlds:
    fuben1:
      name: fuben1
      world: world

资源二次加密

资源加密链路补充二次加密能力,用于提高客户端资源的保护强度。早期版本主要围绕 uze 资源包和本地地图加载逐步完善,后续再扩展到 folder 加密、音效、source 配置等更多资源类型。

CameraDos 与 RemoteCamera

同一时期补充 cameraDos 和 remoteCameraDos,为客户端镜头移动、远程镜头和场景展示提供基础入口。这些能力后来演进为更完整的沉浸式镜头和镜头路径系统。

2023 年 5 月

GUI 展示层点击控制

展示型 GUI 组件补齐点击吞噬控制。背景图、文字、颜色块、实体预览等组件默认保持点击穿透,需要阻止底层按钮或槽位响应时再显式开启。

展示组件新增 swallow

texture、color、gif、frame、video、label、entity、item 均支持 swallow。它用于决定鼠标点到该组件区域时,是否继续把点击传给更底层的组件。

在需要拦截点击的展示层上开启
popupMask:
  type: texture
  path: textures/gui/mask.png
  locationX: 0
  locationY: 0
  width: w
  height: h
  swallow: true

拖动区域保留 dragSwallow

options.dragSwallow 仍用于窗口拖动条区域。当玩家点住拖动条移动窗口时,它可以避免点击同时穿透到其他组件。

在 options 中保护拖动区域
options:
  dragSwallow: true
  drag:
    locationX: 0
    locationY: 0
    width: 180
    height: 28
2023 年 5 月

掉落物旋转与晃动开关

服务端 Config.yml 新增客户端掉落物渲染开关,可统一控制玩家客户端中的掉落物是否上下晃动、是否持续旋转。

ClientOptions.Drop.shake

控制掉落物是否沿用原版上下晃动效果。关闭后,掉落物会保持更稳定的位置,适合展示型掉落物、模型掉落物或希望降低视觉干扰的服务器。

关闭掉落物上下晃动
ClientOptions:
  Drop:
    shake: false
    rotate: true

ClientOptions.Drop.rotate

控制掉落物是否持续旋转。关闭后,掉落物仍会显示模型,但不会随着 tick 持续转动,适合需要固定朝向的自定义物品展示。

固定掉落物朝向
ClientOptions:
  Drop:
    shake: true
    rotate: false