Kzeroko KTM2
EN
English

装备技能运行时

物品模板、升级标志、觉醒、提示选择与手动技能宝石分发。

更新于 2026/9/26 8 分钟阅读

装备技能模板由物品自行实现，解锁状态保存在各物品堆叠上。本文说明 item.IUpgradable 与 util.item 内的内部辅助逻辑；手动技能宝石仍走独立的 internal.gem.proc.EquipmentSkillGemResolver 路径。

它做什么

IsekaiSkillTemplate 定义 APPP、APPL、APLL、ALLL、PPPP、AP、AL、PP、LL。名称长度决定 2 或 4 个槽位。模板不注册可执行技能；各物品在使用或命中钩子中自行检查解锁标志。

Raven 提供 APPP、升级材料数组及自身的主动与被动实现。ItemTooltipUtil 将字母映射到主动、被动、联动标签，并将 W/A/S/D 映射到槽位 1/2/3/4。玩家操作见装备技能。

运行时模型

物品状态

字段类型默认值作用
ise_upgradablelist<compound>缺省：全部锁定仅可升级物品生成槽位视图；模板名称长度决定槽数。
ise_upgradable[].skill_<n>booleanfalse从 1 开始的槽标志，从 skill_1 到模板长度。读取器遍历整个列表，后出现的重复标志覆盖前值。
ise_qualitylist<compound>缺省：计数为 0升级质量计数，独立于解锁状态。
ise_quality[].rawint0光标升级增加粗制计数。读取第一个类型正确的匹配项，不限制范围。
ise_quality[].refinedint0锻造台产物注入增加精制计数，读取规则同样取首个匹配项。
ise_awakenint0独立觉醒等级。设置要求物品已注册修正且当前为 0，只限制上限 5，不拦截负输入。

ItemUpgradeUtil.upgrade(stack, skill, quality) 忽略不可升级物品。有效的从 1 开始的技能索引会修改首个匹配标志，或按键名字典顺序插入复合标签。质量处理随后独立执行：补齐两种质量条目，再增加所选质量的每个匹配项。因此，无效技能索引仍可能增加质量；直接重复调用也会为已解锁技能增加质量。调用方必须自行保证幂等性。

isUnlocked(stack, skill) 的上界检查存在缺口：它拒绝 index > size，而非 index >= size。对非空视图查询模板长度 + 1 时可能抛出异常。调用前应验证从 1 开始的合法范围。

背包与锻造台路径

IsekaiEvents 在 testAwakened 之前注册 CommonEventFactory.OnItemClicked.upgradableClicked。升级点击消耗匹配的光标材料，并将首个对应未解锁槽升级为 RAW。UpgradeOverrideItem 解锁全部剩余槽，即使没有剩余槽也会消耗 1 个；此回调不豁免创造模式。

SmithingScreenHandlerMixin 另行读取输入索引 0 与 1，构造输出副本并应用 REFINED 升级。取出判定允许普通锻造配方匹配，或输入 0 与输出的物品类型相同。这是向原版处理器的注入，不是自定义材料布局，也不保证任意物品能放入这些槽位。调整 Minecraft 锻造台集成时须区分这两层。

觉醒点击在检查当前等级或注册资格之前扣除钻石块。因此，达到上限或不符合注册条件的物品可能消耗材料却不提升。设置器只接受 WeaponModifiers.MODIFIERS 内的物品；大于 0 且小于 5 的等级每次增加 1。这些是当前行为，不提供事务回滚保证。

精制质量还由公共侧 ItemStackMixin 的耐久逻辑读取：最大耐久乘以 1 + 0.07 * refined，再截断为整数。可损坏物品由服务端玩家使用时，若随机值小于 0.10 * refined，整个耐久损耗调用会被取消。此概率没有显式上限限制。粗制质量不参与这两项检查。

觉醒修正

IsekaiEvents 通过 IsekaiCore 的 ONE_SEC_INTERVAL 事件调用 weaponStatsModifier。回调忽略非玩家与客户端世界。优先选择已觉醒且已注册的主手物品；否则，副手条目须至少有一个修正允许副手。条件通过后会应用选中物品的整个修正列表。

觉醒等级修正层数倍率
小于 10
1–21
3–42
至少 54

内置注册表包含渡鸦每层 +2 攻击伤害、+0.1 近战暴击率的加值，两者均禁用副手。修正 UUID 在注册时固定。没有合格物品时会移除全部已注册修正；直接在合格物品之间切换时，不会先清除所有旧注册项。添加条目必须考虑此生命周期。

手动宝石分发

TriggerEquipmentSkillPacket 无载荷，在服务端调用 tryTriggerFirst。选择顺序为 MAINHAND → OFFHAND → HEAD → CHEST → LEGS → FEET，再按有效配置槽数内的镶孔索引升序查找。要求镶孔为 SKILL、未锁定且未开裂、保存的宝石兼容，定义触发器为 TRIGGERABLE。

选择早于可用性判断。第一个合格宝石的绝对镶孔冷却尚未结束，或星界能量不足时，会阻止后续宝石被尝试。创造模式仅跳过能量费用。可用性检查通过后，先支付能量，再调用 SkillPowerUtil.triggerSkill，不等待执行结果，最后写入正冷却。

冷却为 max(0, round(baseTicks * max(0, 1 - cooldownMult * skillLevel)))，基础刻数与技能等级取非负值。不抽取触发概率。完整宝石 NBT、战斗触发与冷却持久化见宝石运行时。

约定

  • 物品数组须匹配模板：显示槽位的调用方会索引材料数组。其长度必须与模板一致，技能索引也须验证。
  • 状态是可变物品 NBT：游戏写入应位于所属背包的服务端路径。辅助方法不提供锁或事务，不应从渲染代码调用。
  • 质量是计数，不是通用伤害倍率：保存 raw 或 refined 本身不会施加属性修正。
  • 觉醒独立保存：ise_awaken 不设置 ise_upgradable，也不改变镶孔或经验状态。
  • 宝石触发负责费用，不负责成功回执：所选技能内部失败时，不退还已付能量，也不取消解析器随后写入的冷却。
  • 客户端按键条件不等于服务端验证：正常输入会被界面、NPC 指令控件或动作禁用拦截；数据包处理器自身仅委托宝石解析器。

装备技能键默认未绑定。另一个 OpenUpgradableScreenPacket 检查主手可升级物品，打开携带物品堆叠的扩展处理器。其自定义界面的确认回调只关闭界面并写日志，处理器动作方法为空。旧开发按键入口已被注释。不能将该界面描述为可用的购买或升级事务。

扩展方式

新物品实现 IUpgradable，选择模板并返回等长材料数组。每个实际能力都须使用有效的从 1 开始的索引检查解锁；模板不会自行执行技能。

if (stack.getItem() instanceof IUpgradable item
        && skill >= 1 && skill <= item.getTemplate().name().length()
        && !ItemUpgradeUtil.isUnlocked(stack, skill)) {
    ItemUpgradeUtil.upgrade(stack, skill, ItemUpgradeUtil.Quality.RAW);
}

此内部示例仅修改解锁状态；调用方须验证归属、支付材料并同步变更后的背包。新增宝石能力应扩展可触发技能注册表与宝石定义，而非增加模板字母。

武器共用数值集中在数值配置中。渡鸦的能力检查、计时与提示从同一份配置读取。

验证

  • 检查全部 9 种模板与槽数，将提示选择键与物品实际使用、命中钩子对照。
  • 用对应材料逐一解锁渡鸦槽位；验证部分解锁、全部解锁及创造模式下的水晶消耗。
  • 覆盖缺失、重复、格式错误的升级与质量 NBT，明确测试索引边界及无效索引增加质量的行为。
  • 觉醒至 1–5 级，再测试满级点击的材料消耗。持有、移除并检查修正清理；新增注册武器时还须测试直接切换。
  • 双手与护甲同时装入可触发宝石，验证槽位顺序、锁定与裂纹跳过，以及首个宝石不可用时不会回退。
  • 检查能量不足、创造模式、技能拒绝与冷却缩放至 0。保存重载并取出再镶入，确认镶孔冷却保留。
  • 将锻造台槽位接受规则与自定义界面作为独立集成检查；出现输出或按钮不等于事务已经完成。

相关页面

装备技能、宝石运行时、技能运行时与锻造运行时介绍相邻系统。