秦淮系列文档

简体中文

English

简体中文

English

外观

属性与数值（AttributePlus 桥接） ​

所属：服主指南　·　相关：核心概念 · 配置文件

QI 的属性系统是它与众不同的一点：QI 不计算战斗数值，只负责把属性挂上物品并交给 AttributePlus（AP）作用到玩家。本章讲透这套机制。

1. 三个关键名词 ​

  • AP（AttributePlus）：第三方属性插件，QI 的数值后端。物品装备时，QI 把属性交给 AP，AP 真正把它加到玩家面板。
  • ICVM：QI 内部对核心属性的「标准词汇表」（如 attack_damage / health / defense）。
  • 属性映射（attribute-mapping）：把 ICVM 键映射到你在 AP 里实际起的显示名。
物品 providers.ap = {"attack_damage":18}
        │
        │ ICVM 键 attack_damage ──(config.yml attribute-mapping)──► AP 显示名 "物理伤害"
        ▼
装备时 → EquipmentScanner 读取 → 格式化成 "物理伤害: 18" → 交给 AttributePlus

2. 给物品加属性：两种方式 ​

方式 A：直接写 providers.ap（推荐手写） ​

属性是一段 JSON，键是 AP 显示名或 ICVM 键（取决于你的映射），值是数字或范围：

yaml
demo_guard_plate:
  type: armor
  material: iron_chestplate
  providers:
    ap:
      value: '{"defense":8,"health":40}'
  • 值可以是数字（8）或范围（"10-20"，范围值不会被基础值覆盖）。
  • 比率类（含 rate 且在 0–1）显示时转百分比。

方式 B：用基础值 base_values（GUI 常用） ​

基础值是 QI 管理的三个核心属性，会被 AttributeCompiler 自动编译进 ap blob：

yaml
demo_armor:
  base_values:
    base_attack_damage: 8
    base_health: 40
    base_defense: 12

三个内置基础值：

baseKey映射 ICVM显示名编辑器图标
base_attack_damageattack_damage基础攻击伤害DIAMOND_SWORD
base_healthhealth基础生命值HEART_OF_THE_SEA
base_defensedefense基础防御力SHIELD

基础值与 providers.ap 会合并：编译时把基础值按 ICVM→AP 名转换后并入 ap blob，但已存在的范围值不会被覆盖。

3. 配置属性映射 ​

在 config.yml 的 attribute-mapping 段，把 ICVM 键映射到你 AP 里的属性显示名：

yaml
attribute-mapping:
  # 核心三项（基础值 / 成长计算用）
  attack_damage: "物理伤害"
  health: "生命"
  defense: "防御"
  # 可选项（MMOItems 导入等会用到）
  attack_speed: "攻击速度"
  magic_damage: "魔法伤害"
  armor_penetration: "护甲穿透"
  max_mana: "最大魔法"
  mana_regen: "魔法恢复"
  critical_rate: "暴击率"
  dodge: "闪避率"
  block_rate: "格挡率"
  lifesteal: "生命偷取"

为什么要映射？ 因为每个服在 AP 里给属性起的名字不同。映射让 QI 配置保持可移植：你换服只改这张表，不用改每个物品。

重载时 QI 会向 AP 查询有效属性名（ApAttributeReader），如果你映射到一个 AP 里不存在的名字，控制台会警告。

4. 内置 ICVM 标准词汇 ​

ICVM 键默认中文ICVM 键默认中文
attack_damage物理伤害max_mana最大魔法
health生命mana_regen魔法恢复
defense防御critical_rate暴击率
attack_speed攻击速度dodge闪避率
magic_damage魔法伤害block_rate格挡率
armor_penetration护甲穿透lifesteal生命偷取

5. 属性怎么上身：装备扫描 ​

QI 监听装备变化（穿戴、换手、点击背包、捡起、护甲变更、物品损坏），通过 EquipmentWatcher + EquipmentScanner 把属性同步到玩家：

装备变化事件 → EquipmentWatcher 比对「装备签名」是否变化
            → 变了才 refresh()
            → 逐槽位读取 QI 物品的 providers.ap
            → 解析成属性行 → backend.apply(player, "qi:equip:mainhand", lines)
            → AttributePlus 应用
  • 六个槽位各有独立属性源：qi:equip:mainhand / offhand / head / chest / legs / feet。
  • 套装加成单独用 qi:set:<套装ID> 源。
  • 玩家退出时清除所有 qi:equip:* 与 qi:set:* 源。

属性应用前会校验玩家是否满足物品的被动需求；不满足则该件不加属性。

6. 没装 AttributePlus 会怎样？ ​

QI 用 AttributeBackend 抽象屏蔽后端：

后端何时使用行为
AttributePlusBackend检测到 AP（自动）真正应用属性，支持 AP 3.3.x 源 API 与旧版 API
NoopAttributeBackend没有 AP永远「成功」但什么都不做

在 config.yml：

yaml
combat:
  enabled: true              # false = 纯物品库模式（不加属性）
  attribute-backend: auto    # auto | attributeplus | noop
  • auto：检测到 AP 用 AP，否则 noop。
  • 启动日志会显示 属性后端: attributeplus (已接入) 或 noop。

纯物品库模式（combat.enabled: false 或没 AP）下：物品照常造、动作照常触发、Lore 照常显示属性数字，只是不真正加到玩家面板。

7. 常驻药水效果（perm_effects） ​

穿戴时常驻的药水效果，用 perm_effects provider：

yaml
my_armor:
  providers:
    perm_effects:
      value: '{"strength":1,"speed":0}'   # 效果名:放大等级，0=I 级
  • 由 PermEffectSync 在装备变化后应用，每 6 秒（120 tick）刷新续期。
  • 多件 / 套装的同名效果取最高等级。
  • 套装也能提供 perm 效果，见 套装。

7.（补）被动需求 ​

被动需求指「不满足就不给属性 / 效果」的条件，比如等级。开发者可用 QinhItemsAPI.meetsPassiveRequirements(player, item) 判断。装备扫描时会自动跳过不满足的件。

8. 开发者：读属性 ​

kotlin
// 是否启用战斗
QinhCombatAPI.isEnabled(): Boolean
// 强制刷新某玩家装备属性，返回应用的源数量
QinhCombatAPI.refreshEquipmentAttributes(player): Int
// 当前后端
QinhCombatAPI.activeAttributeBackend(): AttributeBackend
// 注册自定义后端（接其它属性系统）
QinhCombatAPI.registerAttributeBackend(backend)
kotlin
// 玩家身上装备的所有 QI 物品
EquipmentScanner.equippedQinhStacks(player): List<ItemStack>
// 套装件数
EquipmentScanner.countSetPieces(player, setId): Int

接自定义属性系统的完整示例见 Provider 与桥 与 API 参考。

下一步 ​

  • 变量：随机数值、动态文本
  • 套装：套装属性 / 效果 / 技能
  • 配置文件：combat / attribute-mapping 全配置