装备目录运行机制
用一份装备定义统一注册、默认资源与可重载的平衡数值。
装备目录负责物品标识、类型、稀有度、图标和默认数值。启动时完成注册,并在内存中提供默认资源;服务端数据包随后可覆盖属性加成与存储限制。
它做什么
net.kzeroko.isekaiexpansion.api中的EquipmentAPI把工作委托给internal.equipment。实现类型属于内部约定,不是供其他模组扩展的公开API。
集合定义直接提供注册信息、槽位标签、默认物品模型、施法主手低分辨率模型和战斗父资源,不需要装备数据生成步骤。配方仍单独制作。魔杖与法杖使用共享主模型和可选动画配置。
运行时模型
| 负责人 | 职责 |
|---|---|
EquipmentCatalog | 读取equipment/catalog.json及有序集合,在注册前校验定义。 |
EquipmentRegistry | 注册固定的物品标识,按类型和隐藏部位数据选用通用实现。 |
EquipmentResources / EquipmentResourcePack | 缓存默认资源字节,并将其放在普通资源包之下。显式资源包内容优先,标签默认合并,声明替换时除外。 |
EquipmentRuntime | 解析不可变平衡快照,缓存属性查询与施法主手修正量,成功重载时替换已装备加成。 |
EquipmentStorage / SpellStoragePolicy | 读取时统一容器限制,不改写铭刻;检查绑定、术式替换和施放。 |
EquipmentNetworking / ClientEquipmentAPI | 加入与重载时同步服务端平衡数据;离开远程服务器后恢复本地默认值。 |
EquipmentLightCompat | 在客户端通过LambDynamicLights的物品光源事件注册目录内的发光声明,由该可选模组负责光照更新。 |
装备每刻更新不会逐件读取文件。重载准备阶段先解析完整快照,再由服务端生命周期事件发布:移除旧加成后切换快照,最后应用新加成。
约定
- 新物品ID、物品类型、稀有度、贴图路径、武器基础数值、发光声明和隐藏部位都需要重启。客户端与服务端必须携带匹配的目录内容。
- 可重载格式只调整属性加成和容器限制。每次缺省都从内置值开始,数据包重载失败时不启用待发布快照。
- 每个施法主手都有
models/lowres/图标模型。魔杖和法杖还获得共享的models/item/父模型;显式资源覆盖默认值。施法器模型配置选择几何、纹理和可选片段,并提供缺失资源回退。 RelicItem.canEquip禁止同时装备同一种物品的第二件。子类通过canEquipRelic追加条件。hand/relic提供2个自定义遗物槽,可以分别放入不同遗物;同物品去重限制仍然生效。- 目录加成使用完整Trinkets槽位的UUID。宝石、诅咒和物品熟练度修正量也以同一槽位标识作为种子,其中包含槽位组与索引,重名槽位不会互相覆盖强化效果。
- 存储检查采用完整术式的评估阶位。降低上限保留原有铭刻,生效条目按存储顺序决定;绑定和施放读取同一份当前配置。
ICLootRarity由IsekaiCore提供。目录不添加推荐等级或适用职业提示。
扩展
在src/main/resources/equipment/collections/<name>.json添加JSON数组,并把集合名追加到src/main/resources/equipment/catalog.json。不需要同步修改Java注册列表或数据生成器。
索引字段如下:
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
schema_version | integer | 必填 | 必须为2,其他版本使启动失败。 |
collections | array<string> | 必填 | 有序且不重复的集合名,匹配[a-z0-9_]+,每个名字对应一个集合文件。 |
以下是完整的戒指条目:
[
{
"id": "duelist_kestrel_signet",
"rarity": "RARE",
"role": "VANGUARD",
"kind": "RING",
"icon": {
"texture": "isekaiexpansion:item/relic/playstyles/duelist_kestrel_signet",
"size": 50
},
"stats": [
{
"attribute": "isekaiexpansion:technique",
"amount": 9,
"operation": "ADDITION"
},
{
"attribute": "isekaiexpansion:melee_crit_chance",
"amount": 0.035,
"operation": "ADDITION"
},
{
"attribute": "isekaiexpansion:shield_break",
"amount": 8,
"operation": "ADDITION"
}
]
}
]
| 字段 | 类型 | 默认值 | 作用 |
|---|---|---|---|
id | string | 必填 | 目录内唯一的路径,匹配[a-z0-9_]+,注册到isekaiexpansion命名空间。 |
rarity | enum | 必填 | IsekaiCore枚举:COMMON、UNCOMMON、RARE、EPIC、LEGENDARY、UNIQUE。最后两种使物品防火。 |
role | enum | 必填 | 设计元数据:VANGUARD、BULWARK、MARKSMAN、HUNTER、ARCANIST、CLERIC、PRIEST、UTILITY。不会施加职业使用要求。 |
kind | enum | 必填 | RING、PENDANT、BELT、RELIC、SPELLBOOK、WAND、STAFF、MACE、HAMMER。最后四种属于施法主手。 |
icon | object | 必填 | 默认模型和资源检查使用的贴图声明。 |
icon.texture | identifier | 必填 | 含命名空间、不含.png的贴图标识,位于assets/<namespace>/textures/。禁止父目录跳转。 |
icon.size | integer | 必填 | 声明正方形贴图边长,范围16–256像素。当前批次使用50,资源测试会核对实际图像。 |
weapon | object | 不存在 | 施法主手必填,其他类型禁止。 |
weapon.damage | integer | 必填 | 通用施法主手构造时传入的非负攻击伤害值。 |
weapon.speed | number | 必填 | 有限的攻击速度修正量,必须大于-4。 |
vessel | object | 不存在 | 施法主手和SPELLBOOK必填,其他类型禁止。完整内部字段见平衡数据页。 |
light | object | 不存在 | 可选的客户端发光声明。省略时不注册物品光源,需要安装LambDynamicLights。它属于启动目录,不属于平衡覆盖格式。 |
light.luminance | integer | 必填 | 光照等级0–15;0表示不注册光源。越界或小数使启动失败。 |
light.water_sensitive | boolean | false | 标记光源可被水熄灭;实际行为还要求LambDynamicLights启用遇水检查。非布尔值使启动失败。 |
conceals | enum | 不存在 | 仅戒指可用:EAR、HORN、TAIL、WING、OTHER、ALL。选择隐藏部位的饰品实现。 |
stats | array<object> | 必填 | 属性加成列表,可为空。重复属性ID使校验失败。 |
stats[].attribute | identifier | 必填 | 已注册的属性ID,每次接受平衡快照时统一解析。 |
stats[].amount | number | 必填 | 有限、非零的带符号数值,按属性单位或小数倍率解释。 |
stats[].operation | enum | 必填 | ADDITION、MULTIPLY_BASE或MULTIPLY_TOTAL。 |
未知字段、错误类型、重复ID、缺少必填字段,以及不合法的类型组合,都会使启动失败。集合无效时不会只注册其中一部分物品。
需要发光的法杖可在目录条目中加入"light": { "luminance": 12, "water_sensitive": false }。LambDynamicLights重建物品光源时,可选客户端入口会重新注册这些声明;实现不会放置光源方块,也不会在通用端引入该模组的类。分别检查主手和副手持握,哪些携带物品的实体发光、是否启用动态光照,均由LambDynamicLights控制。
LambDynamicLights采用所有匹配物品光源中的最亮值。资源包可以追加光源,但较暗的来源不会降低目录声明的亮度;需要调暗或移除该注册光源时,修改启动目录中的声明。
把透明PNG放到声明的贴图路径。物品名写入language_assemble/categories/item_trinkets/,描述写入language_assemble/categories/weapon_tooltips/,然后运行./gradlew.bat assembleLanguageFiles。目录通用实现会接入存储信息和既有描述流程。
expedition_relics和expedition_grimoires沿用相同的注册、槽位标签、模型与描述流程。美术交接文件tools/art/equipment_expansion_20261023/design_cards.json记录结构、配色、玩法用途及与已有相近物品的区别;运行时只读取装备集合。
验证
运行./gradlew.bat compileJava assembleLanguageFiles。逐件检查新目录贴图是否存在且尺寸一致、两种语言是否都有物品名和描述,以及完整目录是否存在重复ID。在自定义槽中装备两种镶有相同属性宝石的不同遗物,确认强化效果均生效,取下一件后另一件仍保留加成。对物品熟练度加成和相同诅咒负面属性重复检查,并确认任一种遗物的第二件无法放入。启用LambDynamicLights后,分别在主手与副手持握发光法杖,换成不发光物品,确认光照随持握物品变化。对遇水熄灭声明检查水中行为,并在未安装可选模组时重复启动检查。
在开发客户端装备饰品和容器,加入有效的平衡覆盖后重载,确认不必重新装备,双端属性和存储提示就已更新。再提供无效覆盖,确认重载失败且旧值保留。降低存储限制后,超限铭刻应仍在物品内但无法施放;恢复限制后应重新可用。连接独立服务器并重新登录后重复这些检查。