HyperProtect-Mixin

HyperProtect-Mixin - 面向 Hytale 的服务端事件拦截

拦截。保护。扩展。HyperProtect-Mixin 通过 Hyxin 字节码混入将 27 个保护钩子注入 Hytale 服务端，并通过无锁桥接 API 将其公开，任何模组均可消费 —— 无需编译时依赖。

零配置。故障开放性安全。只需放入即可，你的保护模组会处理其余部分。

 

为何选择 HyperProtect-Mixin？

• 27 个保护钩子 - 涵盖建造、战斗、物品、实体、容器、交通、世界地图、命令和日志记录
• 30 个混入拦截器 - 每个钩子有多个注入点，确保捕获全面，整合交互门涵盖 26 种交互类型
• 无锁桥接 - AtomicReferenceArray 实现零争用读取 —— 无 ConcurrentHashMap 开销
• 故障开放安全性 - 错误、缺失钩子或否定判定始终允许操作 —— 永远不会锁定玩家
• 零配置 - 服务端启动时自动初始化。无需配置文件。
• 无需编译时依赖 - 消费模组通过 System.getProperties() 注册钩子 —— 可跨类加载器边界工作

 

与 OrbisGuard-Mixins 对比

	HyperProtect-Mixin	OrbisGuard-Mixins
钩子数量	27 个钩子 (30 个拦截器)	11 个钩子
桥接类型	AtomicReferenceArray (无锁)	ConcurrentHashMap
安全模型	故障开放 (错误 = 允许)	各有不同
旁路处理	钩子决定 (解耦)	混入检查权限
消息格式化	内置 &-码 + 十六进制颜色	无
功能检测	每个拦截器属性	单一属性
出生点保护	可配置的启动阻塞	无
OG共存	自动检测 OG，禁用冲突混入	不感知其他混入模组

 

钩子覆盖范围

建造 (8 个钩子)

• block_break (插槽 0) — 方块破坏和交互物品拾取
• explosion (插槽 1) — 爆炸方块损坏
• fire_spread (插槽 2) — 火焰流体蔓延
• builder_tools (插槽 3) — 建造者工具粘贴操作
• block_place (插槽 18) — 方块放置
• hammer (插槽 19) — 锤子方块循环 (变体旋转)
• use (插槽 20) — 方块状态更改、耕种、捕获笼和 NPC 交互
• fluid_spread (插槽 25) — 非火焰流体蔓延 (水，熔岩)

物品 (3 个钩子)

• item_pickup (插槽 4) — 近距和手动物品拾取
• death_drop (插槽 5) — 死亡保留物品行为
• durability (插槽 6) — 物品耐久度损耗预防

容器 (4 个钩子)

• container_access (插槽 7) — 制作/工作台访问
• container_open (插槽 17) — 存储容器打开
• crafting_resource (插槽 23) — 配方级别制作资源验证
• barter_trade (插槽 29) — 以物易物/交易 NPC 交互过滤

战斗 (2 个钩子)

• entity_damage (插槽 16) — 玩家发起的伤害 (PvP 和 PvE)
• projectile_launch (插槽 27) — 弹射物发射拦截

实体 (4 个钩子)

• mob_spawn (插槽 8) — NPC/生物生成 (4 个拦截器: 标记，区块，NPC，实体加载)
• respawn (插槽 22) — 玩家重生位置覆盖 (返回坐标，而非判定)
• prefab_spawn (插槽 26) — 从存档数据生成预制实体
• mount (插槽 28) — 骑乘/乘坐实体交互

交通 (3 个钩子)

• teleporter (插槽 9) — 传送方块使用
• portal (插槽 10) — 所有传送门和实例交互 (6 种交互类型)
• seat (插槽 21) — 方块坐具 (椅子，长凳)

世界地图 (1 个钩子)

• map_marker (插槽 24) — 按玩家过滤地图标记可见性 (玩家标记 + 共享标记)

命令和日志记录 (2 个钩子)

• command (插槽 11) — 命令执行过滤
• interaction_log (插槽 12) — 去同步日志抑制

 

架构

桥接设计

桥接是一个 30 元素的 AtomicReferenceArray<Object>，存储在 System.getProperties() 的 "hyperprotect.bridge" 键下。消费模组将钩子对象放在指定的插槽索引处；拦截器在运行时通过缓存的 MethodHandle 查找从这些插槽读取数据。

判定协议

值	名称	行为
0	ALLOW	操作正常进行
1	DENY_WITH_MESSAGE	已阻止；调用 fetch*DenyReason() 并发送格式化消息
2	DENY_SILENT	已阻止，无消息
3	DENY_MOD_HANDLES	已阻止，消费模组处理消息
负数	ALLOW	故障开放安全性

功能检测

每个拦截器在加载时设置一个系统属性。消费模组可以精确检查哪些钩子可用：

boolean loaded = "true".equals(System.getProperty("hyperprotect.bridge.active"));
boolean hasBlockBreak = "true".equals(System.getProperty("hyperprotect.intercept.block_break"));

 

面向服务端管理员

1. 在服务端目录中创建 earlyplugins/ 文件夹
2. 将 Hyxin 和 HyperProtect-Mixin JAR 文件放入 earlyplugins/ (而非 mods/)
3. 在服务端启动脚本中添加 --accept-early-plugins
4. 将你的保护模组 (例如 HyperFactions) 放入 mods/

Linux:

DEFAULT_ARGS="--accept-early-plugins --assets ../Assets.zip"

Windows:

set DEFAULT_ARGS=--accept-early-plugins --assets ../Assets.zip

仅此而已。 零配置要求。HyperProtect-Mixin 自动初始化，消费模组自动注册钩子。

 

面向开发者

无需编译时依赖即可注册钩子：

@SuppressWarnings("unchecked")
AtomicReferenceArray<Object> bridge = (AtomicReferenceArray<Object>)
    System.getProperties().get("hyperprotect.bridge");

// 在插槽 0 注册一个方块破坏钩子
bridge.set(0, new Object() {
    public int evaluate(UUID playerUuid, String worldName, int x, int y, int z) {
        if (isProtected(worldName, x, y, z)) return 1; // DENY_WITH_MESSAGE
        return 0; // ALLOW
    }

    public String fetchDenyReason(UUID playerUuid, String worldName, int x, int y, int z) {
        return "&#FF5555你不能在这里破坏方块！";
    }
});

查阅完整文档获取所有 27 个钩子签名和集成模式。

 

集成

• HyperFactions — 主要消费模组。使用所有 27 个钩子实现领地保护、PvP 控制、保留物品、出生点阻塞、地图标记过滤等。
• 任何模组 — 桥接 API 是开放的。任何模组都可以在任何插槽注册钩子，以实现自定义保护逻辑。

 

要求

• Hytale 服务端 (抢先体验版)
• Hyxin (v0.0.11+) — Hytale 混入框架
• --accept-early-plugins 服务端启动标志

 

链接

• HyperSystems 网站
• GitHub 仓库
• 文档
• 问题追踪器
• Discord

 

HyperSystems 套件的一部分 —— 为 Hytale 构建，开源，并积极维护。