这页专门讲 attributes/*.yml 里 属性映射（mapping） 的公式变量和当前推荐写法。

---

一、当前推荐格式

当前文档统一按这套结构书写：

strength:
  display: "&c力量"
  priority: 100
  mapping:
    targets:
      attack_damage:
        operation: ADD
        formula: "total * 0.5"

也就是说：

• mapping 是映射入口
• targets 下面列出所有目标属性
• 每个目标属性再写自己的 operation 和 formula

---

二、可用变量

在 mapping.targets.<目标属性>.formula 中，公式可以使用以下变量：

变量	含义	类型
total	源属性的总值	浮点数
value	total 的别名	浮点数
source_value	total 的别名	浮点数

最常用的就是 total。

---

三、适用场景

属性映射用于把一个属性派生到一个或多个目标属性，例如：

• 力量 → 攻击力
• 体质 → 最大生命值
• 智力 → 法力值 / 魔法伤害
• 中间属性 → 最终战斗属性

配置文件位置：plugins/HNAttribute/attributes/*.yml

---

四、示例

示例 1：简单线性映射

strength:
  display: "&c力量"
  priority: 100
  mapping:
    targets:
      attack_damage:
        operation: ADD
        formula: "total * 0.5"
        # 每点力量 = 0.5 攻击力

---

示例 2：固定基础值 + 百分比

intellect:
  display: "&9智力"
  priority: 100
  mapping:
    targets:
      max_mana:
        operation: ADD
        formula: "10 + total * 2"
        # 基础 10 法力值 + 每点智力 2 法力值

---

示例 3：分段增长

intellect:
  display: "&9智力"
  priority: 100
  mapping:
    targets:
      magic_damage:
        operation: ADD
        formula: |-
          if (total <= 50) {
            return total * 0.8
          } else if (total <= 100) {
            return 40 + (total - 50) * 1.2
          } else {
            return 100 + (total - 100) * 1.5
          }
        # 0-50 智力：每点 = 0.8 魔法伤害
        # 51-100 智力：每点 = 1.2 魔法伤害
        # 100+ 智力：每点 = 1.5 魔法伤害

---

示例 4：递减增长（平方根）

vitality:
  display: "&a体质"
  priority: 100
  mapping:
    targets:
      max_health:
        operation: ADD
        formula: "10 * Math.sqrt(total)"
        # 增长率递减

---

示例 5：指数增长

level:
  display: "&e等级"
  priority: 200
  mapping:
    targets:
      max_health:
        operation: ADD
        formula: "Math.pow(1.1, total) * 10"

---

示例 6：限制上限

agility:
  display: "&2敏捷"
  priority: 100
  mapping:
    targets:
      dodge_rate:
        operation: ADD
        formula: "Math.min(total * 0.5, 50)"
        # 最高 50% 闪避率

---

示例 7：限制范围

luck:
  display: "&6幸运"
  priority: 100
  mapping:
    targets:
      critical_rate:
        operation: ADD
        formula: "Math.max(5, Math.min(total * 0.3, 80))"
        # 最低 5%，最高 80%

---

示例 8：一个属性映射到多个目标

intellect:
  display: "&9智力"
  priority: 100
  mapping:
    targets:
      max_mana:
        operation: ADD
        formula: "total * 2"
      magic_damage:
        operation: ADD
        formula: "total * 0.8"
      mana_regen:
        operation: ADD
        formula: "total * 0.05"

---

示例 9：链式派生

# 第一层：主属性 -> 中间属性
intellect:
  display: "&9智力"
  priority: 200
  mapping:
    targets:
      spell_power:
        operation: ADD
        formula: "total * 1.5"

# 第二层：中间属性 -> 最终属性
spell_power:
  display: "&d法术强度"
  priority: 100
  mapping:
    targets:
      magic_damage:
        operation: ADD
        formula: "total * 0.8"
      heal_power:
        operation: ADD
        formula: "total * 0.5"

---

五、注意事项

1）priority 决定计算顺序

• 主属性的 priority 要高于派生属性
• 链式派生时，上游属性的 priority 必须更高

# ✅ 正确
intellect:
  priority: 200
  mapping:
    targets:
      spell_power:
        operation: ADD
        formula: "total * 1.5"

spell_power:
  priority: 100
  mapping:
    targets:
      magic_damage:
        operation: ADD
        formula: "total * 0.8"

2）除零保护

当你拿 total 做除数时，记得保护：

# ❌ 危险
formula: "100 / total"

# ✅ 安全
formula: "total > 0 ? 100 / total : 0"

六、调试方法

可以用这些命令看映射结果：

/hnattr lookup          # 看最终属性值
/hnattr trace <属性ID>  # 看属性计算过程，包括 mapping 来源
/hnattr source          # 看属性来源汇总

如果你在 trace 里看到类似：

mapping:strength

说明这个属性值里包含了来自 strength 的映射贡献。

---

七、相关文档

• 公式系统概述 - 了解公式语法
• 运算符与函数参考 - 查看可用函数
• 如何注册属性 - 属性配置完整教程
• 属性配置字段速查 - 快速查看字段说明