非官方项目: 本插件是公开 Servux 协议的独立 Bukkit 兼容实现。它不是 Servux 的官方版本,也与上游作者无关。
Servux Plugin Edition 允许 Paper 和 Folia 服务器向支持 Masa 客户端模组提供 Servux 数据和服务端功能,而无需在服务器上安装 Fabric Loader 或 Servux 服务端模组。
独立实现
本项目并非 Servux JAR 的分叉或重新上传。它是专为 Bukkit API 编写的独立 Bukkit 插件实现,并打包在其自己的 jp.michijp.servuxpe 命名空间下。分发的 JAR 不包含也不重新分发 Servux JAR、Fabric 类或上游 Servux 类。
该实现通过 Servux 的公开网络协议与支持客户端通信,并使用 Bukkit 事件、Bukkit 数据 API、受保护的运行时桥接以及插件特定的安全限制来重建适用的服务端行为。其架构和行为必然与 Fabric Servux 不同:17 项功能被明确记录为 Bukkit 近似实现,3 项底层 Mixin 功能不可用。
Servux 采用 LGPL-3.0-only 许可证分发。Servux Plugin Edition 使用相同的 LGPL-3.0-only 许可证,并在分发的 JAR 中包含许可证文本、上游署名和第三方声明。
支持环境
- 当前构建版: Minecraft 26.1.2 和 26.3
- 已验证服务器: Minecraft 26.1.2 和 26.3 上的 Paper 和 Folia
- Shiroha: 调度器检测由单元测试回归测试覆盖;尚未在 Shiroha 服务器上测试启动过程
- Java: 25
- 早期构建版: 历史兼容性报告涵盖其他 1.21 和 26.x 版本
- 服务端依赖: 无
如果 Bukkit 内部机制或公开 Servux 有线协议发生变化,未来的 Minecraft 版本可能需要更新。
Folia 功能限制
Folia 读取加载的结构起始点,并将 Litematica 图纸放置在拥有目标区块的区域上。Litematica NBT 查询、Easy Place(简易放置)、实体 NBT 查询、mob-cap(生物上限)日志记录以及全世界范围的 Allay mobGriefing 绕过方案仅在 Paper 上可用。当 Folia server-info 查找不可用时,区域化的 Shiroha 服务器通过服务器名称进行检测。
安装所需的功能对应的客户端模组:
已实现的协议
| 频道 |
协议 |
主要用途 |
servux:structures |
3 (旧版注册:2) |
MiniHUD 结构边界框 |
servux:hud_metadata |
2 |
出生点、天气、种子、配方、TPS 和生物上限 |
servux:entity_data |
1 |
实体、玩家和方块实体的 NBT |
servux:litematics |
1 |
NBT 叠加层、图纸保存和服务端粘贴 |
servux:tweaks |
1 |
物品栏预览和可堆叠潜影盒元数据 |
这些是用于本项目的公开 Servux 版本中检查的稳定有线版本。
功能对等性
目前发布的 Servux 功能集被划分为 41 个独立可见的服务端功能:
| 状态 |
数量 |
| 完全实现 |
21 |
| 可用的 Bukkit 近似实现或部分实现 |
17 |
| 不可用 |
3 |
| 总可用 |
38/41 |
完全实现的领域
- 提供者配置和管理命令
- Bukkit 权限和 LuckPerms 兼容的权限节点
- 出生点、天气、种子和配方元数据
- 原生实体、玩家和方块实体 NBT 检索
- 玩家物品栏和末影箱 NBT 过滤
- Litematica 方块/实体叠加层和区块批量 NBT
- 内联和 gzip
.litematic 文件传输粘贴
- 粘贴原点、子区域、镜像、旋转、替换模式、渲染层、区域启用和忽略实体处理
- 结构注册、注销、过滤、间隔、距离和超时处理
- Tweakeroo 物品栏预览 NBT
已记录的近似实现
这 17 项部分实现故意不计入完全对等:
- 面向玩家的消息目前仅支持英语。
- Easy Place V3 支持主要的
BlockData 属性和验证,但不支持每一个底层 Fabric Mixin 放置情况。
- TPS/MSPT 从插件刻计算得出;内部冲刺/冻结状态不可用。
- 生物上限数据根据 Bukkit 实体类别进行近似,而不是精确的 vanilla
SpawnState。
- Allay 回退方案每 5 刻扫描 1.5 水平 / 1.0 垂直方块内的范围。它不能重现基于大脑的远距离搜索。
- 尽可能使用原生 NBT,并为常见方块实体提供便携式回退方案。不能保证每个方块实体实现都有效。
- 实体和递归乘客恢复支持常见状态和经过测试的乘客树,但不是每种实体类型的完整编解码器。
- 待处理方块和流体刻使用延迟的 Bukkit 物理机制。未恢复原生目标和优先级;不声称原生水/岩浆调度对等。
- 铁轨和楼梯变换使用通用的 Bukkit
BlockData 变换。它们的配置切换未连接到当前的粘贴路径。
- 镜像箱子状态和两个物理库存部分已成功测试,但仍属于 Bukkit 级别实现。
- 结构序列化尝试原生路线并回退到 Bukkit 边界框;不保证在每个服务端实现上输出字节完全一致。
- 可堆叠潜影盒和漏斗处理使用受保护的 Bukkit 事件模拟,而非全局 Mixins。其他物品栏插件可能会影响结果。
不可用的功能
以下功能需要 Bukkit 无法一致暴露的底层钩子:
- Vanilla NBT 查询 OP 检查覆盖
- 粘贴期间的底层方块更新抑制
- 粘贴期间的底层物品掉落抑制
Servux 的遗留调试服务被单独跟踪为 0/15,不包含在 41 个功能的分母中。它依赖许多 Fabric Mixins,并从 Minecraft 1.21.9 开始的公开 Servux 版本中被移除。
安装
- 将
ServuxPluginEdition-0.2.3.jar 放入服务器的 plugins 目录。
- 启动服务器。
- 查看
plugins/ServuxPluginEdition/config.yml。
- 重启服务器或运行
/servux reload。
请勿将此插件与 Fabric Servux 服务器模组一起安装。
命令
| 命令 |
用途 |
/servux 或 /servux status |
显示版本、握手状态和提供程序状态 |
/servux reload |
重新加载配置 |
/servux save |
保存配置 |
/servux set <provider:setting> <value> |
更改并保存设置 |
/servux info <provider:setting> |
显示设置的值、类型和范围 |
/servux list [provider] |
列出设置 |
/servux search <query> |
搜索设置 |
/servux sendmeta |
向在线玩家重新发送元数据 |
/servuxpe 也可作为别名使用。管理命令使用 servux.commands.*;提供程序访问使用 servux.provider.*,并与 LuckPerms 等 Bukkit 权限管理器兼容。
原版行为与安全
HUD、NBT 查询/预览、配方、日志记录器和结构数据功能均为只读。以下可选功能有意地与游戏玩法或世界内容交互:
- Easy Place:默认启用,但仅重写有效的编码 Easy Place 请求。
- 悦灵收集回退:默认启用,且仅在
mobGriefing=false 时生效。
- Litematica 粘贴:默认启用,当获得授权的创造模式玩家请求时会更改方块/实体。
- 可堆叠潜影盒:默认禁用;启用它会改变空潜影盒的物品栏和漏斗行为。
Litematica 粘贴始终需要创造模式和 servux.provider.litematic_data.paste 权限。该权限当前默认为 true。公共创造模式服务器应明确拒绝不信任组的此权限或禁用粘贴:
litematic-data:
enable-paste: false
传入的 NBT 和数据传输具有大小、片段、超时、会话和全局预留限制。文件传输限制为 64 个全局会话和每个玩家 16 个会话,并包含在总字节预算中。方块实体、递归乘客和待处理刻数在每个粘贴操作中限制为 min(max-paste-blocks, 16384) 辅助操作。
验证
版本 0.1.0(早期兼容性构建)已通过其最终分发 JAR 验证:
- SHA-256:
00FE9C269B4E0B6EA59DCB16790CC116EA65DA19E769D0C30DBB7531211672D1
- 自动化测试: 36/36 通过
- 启动矩阵: 18/18 通过
- 来自 Minecraft 1.21 到 26.2 的 14 个 Paper 服务器版本
- Spigot 和 CraftBukkit 在 1.21.1 和 26.2 两个版本上
- 经过身份验证的真实玩家测试: 40 通过 / 0 失败
- Litematica 粘贴模式检查: 6/6 通过
完整的真实玩家功能套件使用了隔离的在线模式 Paper 26.2 服务器和带有 MiniHUD、Litematica、MaLiLib 和 Tweakeroo 的 Fabric 26.2 客户端。其他 Minecraft 版本仅接收启动、插件启用、握手、状态命令和干净停止的兼容性测试,而不是在每个版本上重复完整的玩家套件。
0.2.3 版本在 Paper 和 Folia 上针对 Minecraft 26.1.2 和 26.3 通过了 49 项自动化测试和直接 Litematica 粘贴测试。Folia 26.1.2 测试使用 Minecraft 26.3 客户端通过 ViaFabricPlus 进行,包括一个 196,608 方块的放置和一个初始未加载的远处目标区块。
致谢与许可
根据 GNU 宽通用公共许可证 v3.0 仅 (LGPL-3.0-only) 授权。
分发的插件未捆绑 Fabric Loader、Servux、Paper、Spigot API、CraftBukkit、Netty、MiniHUD、Litematica、Tweakeroo 或仅限开发环境的测试依赖项。
结构叠加兼容性
MiniHUD 26.3 使用结构协议 3 和长度前缀的 gzip 命名 NBT。旧的协议 2 注册保留其原始编码。在 Folia 上,仅包含扫描半径内已加载区块中的结构起点。
当通过 ViaFabricPlus 从 Minecraft 26.3 连接到 Folia 26.1.2 时,请在 ViaFabricPlus 配置中启用 send-player-details: true 以获取结构元数据和 Litematica 粘贴支持。
MiniHUD 0.41.2 可以在连接或重连期间清除自身的待定注册标志并忽略有效的服务器回复。在其设置中关闭再打开叠加层以重新注册;客户端重启也可能有帮助。这种客户端行为仍然是已知限制。NONE 热键意味着客户端未分配按键,并且不会阻止点击布尔按钮。
Unofficial project: This plugin is an independent Bukkit-compatible implementation of the public Servux protocols. It is not an official Servux release and is not affiliated with the upstream authors.
Servux Plugin Edition allows Paper and Folia servers to provide Servux data and server features to supported Masa client mods without installing Fabric Loader or the Servux server mod on the server.
Independent implementation
This project is not a fork or reupload of the Servux JAR. It is a separate Bukkit plugin implementation written for the Bukkit API and packaged under its own jp.michijp.servuxpe namespace. The distributed JAR does not contain or redistribute the Servux JAR, Fabric classes, or upstream Servux classes.
The implementation communicates with supported clients through Servux's public network protocol and recreates applicable server behavior using Bukkit events, Bukkit data APIs, guarded runtime bridges, and plugin-specific safety limits. Its architecture and behavior necessarily diverge from Fabric Servux: 17 features are explicitly documented as Bukkit approximations and 3 low-level Mixin features are unavailable.
Servux is distributed under LGPL-3.0-only. Servux Plugin Edition uses the same LGPL-3.0-only license and includes the license text, upstream attribution, and third-party notices in the distribution JAR.
Supported environments
- Current build: Minecraft 26.1.2 and 26.3
- Verified servers: Paper and Folia on Minecraft 26.1.2 and 26.3
- Shiroha: scheduler detection is covered by a unit regression test; startup has not been tested on a Shiroha server
- Java: 25
- Earlier builds: historical compatibility reports cover additional 1.21 and 26.x versions
- Server dependencies: None
Future Minecraft releases may require an update if Bukkit internals or the public Servux wire protocol change.
Folia feature limits
Folia reads loaded structure starts and places Litematica schematics on the regions that own the target chunks. Litematica NBT queries, Easy Place, entity NBT queries, mob-cap logging, and the all-world Allay mobGriefing workaround are available on Paper. Regionized Shiroha servers are detected by server name when Folia server-info lookup is unavailable.
Install the client mods needed for the features you want to use:
Implemented protocols
| Channel |
Protocol |
Main use |
servux:structures |
3 (legacy registration: 2) |
MiniHUD structure bounding boxes |
servux:hud_metadata |
2 |
Spawn, weather, seed, recipes, TPS, and mob caps |
servux:entity_data |
1 |
Entity, player, and block-entity NBT |
servux:litematics |
1 |
NBT overlays, schematic saving, and server-side paste |
servux:tweaks |
1 |
Inventory previews and stackable-shulker metadata |
These are the stable wire versions used by the public Servux releases inspected for this project.
Feature parity
The currently published Servux feature set was divided into 41 independently visible server features:
| Status |
Count |
| Fully implemented |
21 |
| Usable Bukkit approximation or partial implementation |
17 |
| Unavailable |
3 |
| Usable total |
38/41 |
Fully implemented areas
- Provider configuration and management commands
- Bukkit permissions and LuckPerms-compatible permission nodes
- Spawn, weather, seed, and recipe metadata
- Native entity, player, and block-entity NBT retrieval
- Player inventory and Ender Chest NBT filtering
- Litematica block/entity overlays and chunk-bulk NBT
- Inline and gzip
.litematic file-transmit paste
- Paste origin, subregion, mirror, rotation, replace mode, render layer, region enable, and ignore-entities handling
- Structure registration, unregistering, filtering, interval, distance, and timeout handling
- Tweakeroo inventory-preview NBT
Documented approximations
The 17 partial implementations are deliberately not counted as full parity:
- Player-facing messages are currently English only.
- Easy Place V3 supports major
BlockData properties and validation, but not every low-level Fabric Mixin placement case.
- TPS/MSPT is calculated from plugin ticks; internal sprint/freeze state is unavailable.
- Mob-cap data is approximated from Bukkit entity categories instead of the exact vanilla
SpawnState.
- The Allay fallback scans within 1.5 horizontal / 1.0 vertical blocks every 5 ticks. It does not reproduce long-distance Brain-based searching.
- Native NBT is used where possible, with portable fallbacks for common block entities. Every block-entity implementation cannot be guaranteed.
- Entity and recursive-passenger restoration supports common state and tested passenger trees, but is not a complete codec for every entity type.
- Pending block and fluid ticks use delayed Bukkit physics. Native targets and priorities are not restored; native water/lava scheduling parity is not claimed.
- Rail and stair transforms use generic Bukkit
BlockData transforms. Their configuration toggles are not connected to the current paste path.
- Mirrored chest states and both physical inventory halves were tested successfully, but remain a Bukkit-level implementation.
- Structure serialization attempts a native route and falls back to Bukkit bounding boxes; byte-exact output is not guaranteed on every server implementation.
- Stackable shulkers and hopper handling use guarded Bukkit event emulation rather than global Mixins. Other inventory plugins may affect the result.
Unavailable features
The following require low-level hooks that Bukkit does not expose consistently:
- Vanilla NBT-query OP-check override
- Low-level block-update suppression during paste
- Low-level item-drop suppression during paste
Servux's legacy debug service is tracked separately as 0/15 and is not included in the 41-feature denominator. It depended on many Fabric Mixins and was removed from public Servux releases beginning with Minecraft 1.21.9.
Installation
- Put
ServuxPluginEdition-0.2.3.jar in the server's plugins directory.
- Start the server.
- Review
plugins/ServuxPluginEdition/config.yml.
- Restart the server or run
/servux reload.
Do not install the Fabric Servux server mod alongside this plugin.
Commands
| Command |
Purpose |
/servux or /servux status |
Show version, handshake, and provider state |
/servux reload |
Reload configuration |
/servux save |
Save configuration |
/servux set <provider:setting> <value> |
Change and save a setting |
/servux info <provider:setting> |
Show a setting's value, type, and range |
/servux list [provider] |
List settings |
/servux search <query> |
Search settings |
/servux sendmeta |
Resend metadata to online players |
/servuxpe is also available as an alias. Administrative commands use servux.commands.*; provider access uses servux.provider.* and works with Bukkit permission managers such as LuckPerms.
Vanilla behavior and safety
HUD, NBT query/preview, recipe, logger, and structure-data features are read-only. The following optional features intentionally interact with gameplay or world contents:
- Easy Place: enabled by default, but only rewrites a valid encoded Easy Place request.
- Allay gathering fallback: enabled by default and only acts while
mobGriefing=false.
- Litematica paste: enabled by default and changes blocks/entities when an authorized Creative player requests it.
- Stackable shulkers: disabled by default; enabling it changes empty-shulker inventory and hopper behavior.
Litematica paste always requires Creative mode and servux.provider.litematic_data.paste. That permission currently defaults to true. Public Creative servers should explicitly deny it to untrusted groups or disable paste:
litematic-data:
enable-paste: false
Incoming NBT and file transfers have size, fragment, timeout, session, and global reservation limits. File transmit is limited to 64 global and 16 per-player sessions and is included in the total byte budget. Block entities, recursive passengers, and pending ticks are capped at min(max-paste-blocks, 16384) auxiliary operations per paste.
Verification
Version 0.1.0 (earlier compatibility build) was verified with its final distribution JAR:
- SHA-256:
00FE9C269B4E0B6EA59DCB16790CC116EA65DA19E769D0C30DBB7531211672D1
- Automated tests: 36/36 passed
- Startup matrix: 18/18 passed
- 14 Paper server releases from Minecraft 1.21 through 26.2
- Spigot and CraftBukkit at both 1.21.1 and 26.2
- Authenticated real-player tests: 40 PASS / 0 FAIL
- Litematica paste-mode checks: 6/6 passed
The full real-player feature suite used an isolated online-mode Paper 26.2 server and a Fabric 26.2 client with MiniHUD, Litematica, MaLiLib, and Tweakeroo. The other Minecraft versions received startup, plugin-enable, handshake, status-command, and clean-stop compatibility tests rather than repeating the complete player suite on every version.
The 0.2.3 release passed 49 automated tests and direct Litematica paste tests on Paper and Folia for Minecraft 26.1.2 and 26.3. The Folia 26.1.2 test used a Minecraft 26.3 client through ViaFabricPlus and included a 196,608-block placement and an initially unloaded, distant target chunk.
Credits and license
Licensed under GNU Lesser General Public License v3.0 only (LGPL-3.0-only).
The distributed plugin does not bundle Fabric Loader, Servux, Paper, Spigot API, CraftBukkit, Netty, MiniHUD, Litematica, Tweakeroo, or development-only test dependencies.
Structure overlay compatibility
MiniHUD 26.3 uses structures protocol 3 and length-prefixed gzip named NBT. Older
protocol 2 registrations retain their original encoding. On Folia, only structure
starts in loaded chunks within the scan radius are included.
When connecting from Minecraft 26.3 to Folia 26.1.2 through ViaFabricPlus, enable
send-player-details: true in the ViaFabricPlus configuration for structure metadata and Litematica paste.
MiniHUD 0.41.2 can clear its own pending-registration flag during connection or reconnection and
ignore a valid server reply. Turn the overlay off and on in its settings to register again;
client restart may also help. This client-side behavior remains a known limitation. A NONE hotkey means
no key is assigned in the client and does not prevent clicking the boolean button.
评论 0
登录后参与评分
还没有评论,来抢沙发吧