Kzeroko KTM2

装备目录运行机制

用一份装备定义统一注册、默认资源与可重载的平衡数值。

更新于 2026/10/23 8 分钟阅读

装备目录负责物品标识、类型、稀有度、图标和默认数值。启动时完成注册,并在内存中提供默认资源;服务端数据包随后可覆盖属性加成与存储限制。

它做什么

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_versioninteger必填必须为2,其他版本使启动失败。
collectionsarray<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"
      }
    ]
  }
]
字段类型默认值作用
idstring必填目录内唯一的路径,匹配[a-z0-9_]+,注册到isekaiexpansion命名空间。
rarityenum必填IsekaiCore枚举:COMMON、UNCOMMON、RARE、EPIC、LEGENDARY、UNIQUE。最后两种使物品防火。
roleenum必填设计元数据:VANGUARD、BULWARK、MARKSMAN、HUNTER、ARCANIST、CLERIC、PRIEST、UTILITY。不会施加职业使用要求。
kindenum必填RING、PENDANT、BELT、RELIC、SPELLBOOK、WAND、STAFF、MACE、HAMMER。最后四种属于施法主手。
iconobject必填默认模型和资源检查使用的贴图声明。
icon.textureidentifier必填含命名空间、不含.png的贴图标识,位于assets/<namespace>/textures/。禁止父目录跳转。
icon.sizeinteger必填声明正方形贴图边长,范围16–256像素。当前批次使用50,资源测试会核对实际图像。
weaponobject不存在施法主手必填,其他类型禁止。
weapon.damageinteger必填通用施法主手构造时传入的非负攻击伤害值。
weapon.speednumber必填有限的攻击速度修正量,必须大于-4。
vesselobject不存在施法主手和SPELLBOOK必填,其他类型禁止。完整内部字段见平衡数据页。
lightobject不存在可选的客户端发光声明。省略时不注册物品光源,需要安装LambDynamicLights。它属于启动目录,不属于平衡覆盖格式。
light.luminanceinteger必填光照等级0–15;0表示不注册光源。越界或小数使启动失败。
light.water_sensitivebooleanfalse标记光源可被水熄灭;实际行为还要求LambDynamicLights启用遇水检查。非布尔值使启动失败。
concealsenum不存在仅戒指可用:EAR、HORN、TAIL、WING、OTHER、ALL。选择隐藏部位的饰品实现。
statsarray<object>必填属性加成列表,可为空。重复属性ID使校验失败。
stats[].attributeidentifier必填已注册的属性ID,每次接受平衡快照时统一解析。
stats[].amountnumber必填有限、非零的带符号数值,按属性单位或小数倍率解释。
stats[].operationenum必填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后,分别在主手与副手持握发光法杖,换成不发光物品,确认光照随持握物品变化。对遇水熄灭声明检查水中行为,并在未安装可选模组时重复启动检查。

在开发客户端装备饰品和容器,加入有效的平衡覆盖后重载,确认不必重新装备,双端属性和存储提示就已更新。再提供无效覆盖,确认重载失败且旧值保留。降低存储限制后,超限铭刻应仍在物品内但无法施放;恢复限制后应重新可用。连接独立服务器并重新登录后重复这些检查。

相关