HyBaubles

HyBaubles

Hytale的饰品,支持API

图书馆

HyBaubles

为你的 Hytale 服务器提供八个饰品槽位——戒指、项链、手镯和护符——采用数据驱动系统来授予属性和被动效果。专为被依赖而构建。

image

image

image

兼容 RPG Leveling 和 Stats/Skills:

image

功能说明

HyBaubles 为每位玩家添加八个"饰品"槽位,通过 /baubles(或 Alt + 9)打开:

# 槽位 所属类别
0 RING_1 戒指
1 RING_2 戒指
2 NECKLACE 项链
3 BRACELET 手镯
4 TALISMAN_1 护符
5 TALISMAN_2 护符
6 TALISMAN_3 护符
7 TALISMAN_4 护符

槽位按类别锁定:项链永远无法放入戒指槽。护符在其类别内互斥,因此你不能佩戴同一个护符两次。

装备状态跨会话持久保存,在装备时施加效果,在卸下时干净地移除效果。

与大多数装饰性饰品模组不同,这里的槽位确实有作用:每个饰品都在 JSON 中声明其效果,HyBaubles 将其解析为真实的属性和伤害修正。


兼容模组:


内置物品

模组自带十二件物品。它们用于演示框架——每个数值都可配置,你无需修改 HyBaubles 的代码即可添加自己的物品。

物品 槽位 稀有度 效果
血叶戒指 戒指 普通 每秒恢复最大生命值的 1%
风暴戒指 戒指 稀有 每秒恢复最大体力的 2%
铜手镯 手镯 普通 +3 伤害
铁手镯 手镯 罕见 +5 伤害
钍手镯 手镯 稀有 +7 伤害
精金手镯 手镯 稀有 +9 伤害
秘银手镯 手镯 史诗 +11 伤害
缟玛瑙手镯 手镯 史诗 +13 伤害
丝绸项链 项链 罕见 +10 法力
烬布项链 项链 稀有 +15 法力
速度护符 护符 罕见 +20% 速度
防御护符 护符 稀有 +5% 物理抗性

每件物品都可合成,稀有度遵循其原版金属对应物——铜手镯为普通,因为铜制工具和护甲为普通;秘银为史诗,因为秘银装备为史诗,依此类推。所有十二件物品都有自定义 3D 模型和精心调整的纹理。


合成

物品 工作台 材料
血叶戒指 炼金 血花瓣 x8
风暴戒指 奥术 风暴丝线 x2 + 金锭 x2
铜手镯 工作台 铜锭 x4
铁手镯 工作台 铁锭 x6
钍手镯 工作台 钍锭 x6
精金手镯 工作台 精金锭 x6
丝绸项链 工作台 丝绸线 x2 + 钴锭 x2
烬布项链 奥术 烬布线 x2 + 精金锭 x2
秘银手镯 奥术 秘银锭 x8 + 虚空之心 x1
缟玛瑙手镯 奥术 缟玛瑙锭 x8 + 虚空之心 x3
防御护符 护甲 铁锭 x6 + 生命精华 x4
速度护符 炼金 生命精华 x6 + 银锭 x2

命令

命令 描述
/baubles 打开饰品界面
/baubles list 列出你已装备的饰品及其效果

该界面是普通的 Hytale 容器窗口,因此物品可用常规背包操作进出。你也可以点击饰品来卸下它,或点击背包物品来装备它。


致模组作者

这是一个库模组。它专为被依赖而设计,附带文档化的公共 API 和完全数据驱动的定义格式。

通过提供两个文件来添加饰品——一个物品资源和一个定义:

// Server/HyBauble/Baubles/My_Ring.json
{
  "Item": "MYMOD_Amethyst_Ring",
  "Slot": "Ring",
  "Apply": "None",
  "Effects": [
    { "Type": "STAT_ADD", "Stat": "Intelligence", "Amount": 5 },
    { "Type": "REGEN_PERCENT", "Stat": "Health", "Amount": 1 }
  ]
}

普通属性和被动效果无需 Java。通过 BaubleEffectProvider 也支持自定义效果类型。

参见 API.md 了解完整的定义架构、效果类型参考、公共 API 接口以及完整示例。


要求

Hytale 服务器 0.6.8 或更高版本
仅服务端 玩家无需安装任何内容
Java 25

安装

  1. 将 HyBaubles-1.0.0.jar 放入服务器的 mods/ 文件夹。
  2. 重启服务器。
  3. 玩家在游戏中运行 /baubles。

模组自带资源包(物品、模型、纹理、图标和本地化),因此无需安装其他内容。


说明与限制

如实记录,而非留待你自行发现:

  • 移动速度以可逆增量方式应用。 加成被合并到 MovementSettings.baseSpeed 中,并在卸下时撤销,而不是存储每位玩家的原始配置。
  • 抗性上限为 95%,因此叠加抗性饰品永远无法使玩家免疫。
  • /baubles list 以英文输出。 命令帮助行已本地化;列表输出尚未本地化。
  • 挖掘速度被有意不实现。 早期的采集护符被移除,因为方块破坏事件能识别方块和工具,但从不识别挥动的玩家,因此加成无法可靠归因。

兼容性

HyBaubles 是服务端且自包含的。它添加自己的槽位,不修改原版背包,因此不会与存储或背包模组冲突。

如果你基于 HyBaubles 构建,请在清单中声明依赖:

"Dependencies": { "HyBaubles:HyBaubles": "^1.0.0" }

支持

发现 bug,或想要添加饰品?请附上服务器日志和你使用的物品或定义提交 issue。

为你的模组添加 HyBaubles 支持

HyBaubles 为每位玩家添加八个饰品槽位。你的模组无需在编译时依赖它即可将物品放入这些槽位——将一个小型 JSON 文件放入你的资源包,该物品就成为饰品。


我应该使用哪种方式?

方式 A:资源文件 方式 B:代码
编译时依赖 无 HyBaubles jar
语言 JSON Java
最适合 大多数模组 生成的物品、条件定义、覆盖其他模组
是否覆盖方式 A? - 是,代码总是优先

从方式 A 开始。 它无需依赖也无需代码,HyBaubles 自身所有十四个饰品都使用它。


方式 A - 资源文件(无代码)

HyBaubles 在路径 HyBauble/Baubles 注册了一个资源存储,因此你的资源包中同一路径下的文件会与其自身的文件一起自动加载:

YourMod/
  Server/
    HyBauble/
      Baubles/
        MyMod_AmuletOfHaste.json     <-- 你的定义

你无需将 HyBaubles 作为依赖,也无需注册任何内容——当资源存储加载时,文件会被发现。唯一要求是你的模组已加载且 HyBaubles 存在。

你的物品仍需存在

定义装饰一个物品;它不创建物品。以正常方式提供物品本身:

YourMod/Server/Item/Items/Baubles/MyMod_AmuletOfHaste.json

并确保两个文件在物品 id 上一致。


定义架构

{
  "Item": "MyMod_AmuletOfHaste",
  "Slot": "Talisman",
  "TalismanFamily": "Haste",
  "Apply": "None",
  "Effects": [
    { "Type": "SPEED_PERCENT", "Amount": 15 }
  ]
}
键 必需 类型 含义
Item 是 string 此定义适用的物品 id
Slot 是 string 物品可占据的槽位类别
TalismanFamily 否 string 护符的互斥组(见下文)
Apply 否 string 装备加成的应用方式。默认 NONE
Effects 否 array HyBaubles 为此物品运行的动态行为

Slot 值

槽位布局固定且有序。Slot 命名的是类别,而非单个槽位——HyBaubles 将物品放入该类别的第一个空槽位。

Slot 值 可用槽位 备注
"Ring" 2
"Necklace" 1
"Bracelet" 1
"Talisman" 4 受下文类别规则约束

不属于这四种的值会使物品无法装备;HyBaubles 将拒绝放置并告知玩家原因。

Apply 值

值 发生什么
"None" HyBaubles 在装备时不应用任何内容。当物品自身的 JSON 携带其加成,或你仅使用 Effects 时使用此项。
"VanillaArmor" 你的物品 JSON 在其原版 Armor 块(StatModifiers、DamageResistance 等)中声明加成。服务器原生应用和移除它;HyBaubles 仅强制槽位。属性加成最兼容的选项。
"Code" HyBaubles 从你的 Effects 列表自行应用加成。

值不区分大小写。

注意。 某些效果根本不是实体属性——固定伤害、移动速度、抗性。无论 Apply 如何,这些始终由 Effects 驱动。


效果参考

Effects 中的每一项为 { "Type": ..., "Stat": ..., "Amount": ... }。Stat 仅对下方标记的效果类型必需;DamageCause 由 RESISTANCE_PERCENT 使用。

Type 需要 Stat 需要 DamageCause 含义
STAT_ADD 是 否 属性最大值的固定加成。"Mana"、Amount: 10 = +10 最大法力
STAT_PERCENT 是 否 按比例缩放属性最大值。Amount: 20 = +20%
REGEN_FLAT 是 否 每秒恢复固定量的属性,上限为其最大值
REGEN_PERCENT 是 否 每秒恢复属性最大值的百分比。Amount: 1 = 1%/秒
DAMAGE_FLAT 否 否 玩家每次命中造成的固定伤害加成
DAMAGE_PERCENT 否 否 按比例缩放造成的伤害。Amount: 10 = +10%
SPEED_PERCENT 否 否 按比例缩放移动速度。Amount: 20 = +20%
RESISTANCE_PERCENT 否 可选 减少匹配原因的 incoming 伤害。Amount: 50 = 50% 减免。无 DamageCause 时,适用于物理类伤害
CUSTOM 是 否 委托给你在代码中注册的提供者。Stat 是提供者名称。参见自定义效果

Type 不区分大小写。未识别的 Type 会被跳过(该条目被忽略),而不会使整个定义失败。

{
  "Item": "MyMod_Bulwark_Talisman",
  "Slot": "Talisman",
  "Apply": "None",
  "Effects": [
    { "Type": "STAT_ADD", "Stat": "Health", "Amount": 25 },
    { "Type": "RESISTANCE_PERCENT", "DamageCause": "Fire", "Amount": 50 }
  ]
}

护符类别

有四个护符槽位可用,但 HyBaubles 禁止同时装备同一类别的两个护符。这防止堆叠同一物品的四个相同副本。

TalismanFamily 行为
省略 物品自身的 id 即为类别,因此同一护符永远无法装备两次。这是常用选择。
"Haste" 所有声明 "Haste" 的护符彼此冲突。用于建模仅有最佳一个生效的层级链。

该规则仅适用于护符。戒指、项链和手镯除槽位数量外无同等限制。


自定义效果

内置效果类型涵盖属性、伤害、速度和恢复。对于其他任何内容,注册一个提供者并从你的定义中引用它。这需要在编译时依赖 HyBaubles。

1. 注册提供者

import com.hybaubles.effect.BaubleCustomEffect;
import com.hybaubles.effect.BaubleEffectProvider;
import com.hybaubles.effect.BaubleEffects;

// 在你插件的 setup() 或之后:
BaubleEffects.register("MyMod_Glow", new BaubleEffectProvider() {

    @Override
    public void onApplied(UUID player, BaubleCustomEffect effect,
                          Ref<EntityStore> ref, Store<EntityStore> store) {
        // 启动效果。effect.amount() 是你的 JSON 中的数值。
    }

    @Override
    public void onRemoved(UUID player, BaubleCustomEffect effect,
                          Ref<EntityStore> ref, Store<EntityStore> store) {
        // 停止它并释放你分配的任何资源。这是唯一保证的清理。
    }
});

2. 从定义中引用它

{
  "Item": "MyMod_Glowing_Ring",
  "Slot": "Ring",
  "Apply": "None",
  "Effects": [
    { "Type": "CUSTOM", "Stat": "MyMod_Glow", "Amount": 3 }
  ]
}

Stat 是提供者名称。提供者名称未知的效果是无作用的而非错误,因此定义可以引用未安装模组的提供者。

生命周期保证

HyBaubles 在每次装备变更时协调你的效果,这是值得依赖的部分:

情况 回调
饰品装备,效果新激活 onApplied
Amount 或 DamageCause 变更(换为更强的饰品) onUpdated(默认为移除 + 应用)
饰品卸下,或效果不再存在 onRemoved
玩家断开连接,或所有饰品被清除 每个激活效果的 onRemoved

效果实例由从槽位、物品 id 和提供者名称派生的稳定 id 标识。这种差异比较正是你的回调在每次重新计算时不会被重复调用的原因——只有真正的变更才会到达你。

将 onRemoved 视为你唯一获得的清理来实现。 它在卸下和断开连接时被调用,但崩溃后没有任何东西保证回调,因此避免泄漏任何超出会话的生命周期对象。实现还必须容忍被多次调用——永远不要假设只有一对应用/移除。

如果你的提供者抛出异常,HyBaubles 会记录失败并继续处理玩家的其他加成,因此一个提供者的 bug 不会破坏无关的饰品。

方式 B - 编程 API

如果你需要从代码注册,或覆盖另一个模组的定义,请将 HyBaubles 添加为依赖。代码注册总是优先于解析的资源定义,因此这也是修补你不拥有的定义的方式。

import com.hybaubles.bauble.BaubleApplyMode;
import com.hybaubles.bauble.BaubleDefinition;
import com.hybaubles.bauble.BaubleEffect;
import com.hybaubles.bauble.BaubleEffectType;
import com.hybaubles.bauble.BaubleRegistry;

// 在你插件的 setup() 或 start() 中:
BaubleRegistry.get().register("MyMod_RingOfHaste", new BaubleDefinition(
        "Ring",                       // 槽位类别
        null,                         // 护符类别(null = 从物品 id 派生)
        BaubleApplyMode.CODE,         // 加成的应用方式
        new BaubleEffect[] {
                BaubleEffect.of(BaubleEffectType.SPEED_PERCENT, 10)
        }));

注册表方法

方法 用途
register(itemId, definition) 注册或覆盖定义。优先于资源文件
unregister(itemId) 移除代码注册,恢复任何已解析的定义
definitionOf(itemId) 定义,或当物品不是饰品时返回 BaubleDefinition.NONE
isBauble(itemId) 当物品由 HyBaubles 处理时返回 true
talismanFamilyOf(itemId) 护符的互斥类别键
knownItemIds() 所有已知饰品 id,包括解析的和代码注册的

效果工厂方法

调用 用途
BaubleEffect.of(type, amount) 无需额外字段的效果
BaubleEffect.stat(type, stat, amount) 以实体属性为键的效果
BaubleEffect.cause(type, damageCause, amount) RESISTANCE_PERCENT

从 setup() 或之后调用 register。 从静态初始化器注册可能在模组加载之前运行。


完整示例

一个授予 +15% 移动速度并从代码注册自身的护符。

1. 物品 - YourMod/Server/Item/Items/Baubles/MyMod_AmuletOfHaste.json

{
  "TranslationProperties": {
    "Name": "server.items.MyMod_AmuletOfHaste.name",
    "Description": "server.items.MyMod_AmuletOfHaste.description"
  },
  "Icon": "Icons/ItemsGenerated/MyMod_AmuletOfHaste.png",
  "MaxStack": 1,
  "Quality": "Rare"
}

2. 定义 - YourMod/Server/HyBauble/Baubles/MyMod_AmuletOfHaste.json

{
  "Item": "MyMod_AmuletOfHaste",
  "Slot": "Talisman",
  "TalismanFamily": "Haste",
  "Apply": "None",
  "Effects": [
    { "Type": "SPEED_PERCENT", "Amount": 15 }
  ]
}

3. 图标 - YourMod/Common/Icons/ItemsGenerated/MyMod_AmuletOfHaste.png

4. 可选文本 - YourMod/Server/Languages/en-US/server.lang

items.MyMod_AmuletOfHaste.name = Amulet of Haste
items.MyMod_AmuletOfHaste.description = A humming talisman that quickens your step.

注意键不包含 server. 前缀:域来自文件名。物品的 TranslationProperties 应引用包含 server. 的完整键。

这就是全部所需。无代码,无依赖。


加载机制

当某些内容未出现时,理解这一点会有帮助。

  1. HyBaubles 注册一个 id 路径为 HyBauble/Baubles 的资源存储,以文件名作为键,并声明在物品之后加载。
  2. 当该存储加载时,每个定义被解析,运行时注册表由完整集合构建。该集合是替换而非合并,因此删除 JSON 文件也会移除饰品。
  3. 命名缺失 Item 或 Slot 的定义会被跳过并在日志中记录警告。

由于存储是基于路径且全局的,你的文件会被拾取而无需你侧任何注册——但这也意味着物品必须在定义读取之前加载,声明的加载顺序处理了这一点。


疑难解答

物品无法放入槽位。 检查日志中是否有命名你资源的行。通常原因是 Slot 值不是 Ring、Necklace、Bracelet、Talisman 之一,或 Item id 与你的物品不完全匹配(id 区分大小写)。

"Only a ring can go in RING 2" 或类似提示。 你的定义未加载,因此每个槽位都拒绝该物品。验证文件位于 Server/HyBauble/Baubles/ 下且存储已加载——HyBaubles 在启动时记录 registered N bauble definition(s).,N 应包含你的。

效果无作用。 如果 Apply 为 "Code",效果必须是 HyBaubles 能表达的。属性效果还要求命名的属性存在;对照游戏的属性资源检查属性名称。如果 Apply 为 "VanillaArmor",加成必须在物品自身的 Armor 块中——HyBaubles 不会应用它。

两个护符意外冲突。 你省略了 TalismanFamily,因此每个护符是自身类别且重复被阻止。如果你想要仅有层级链中一个生效,请设置显式类别。

编辑文件无效果。 资源存储在启动或重载时读取。重启,或触发资源重载。