伤害数字

伤害数字负责把一次攻击的结果显示出来：普通伤害、暴击、物理伤害、魔法伤害、真实伤害、元素伤害都可以做成不同样式。

建议先用最简单的文本跑通，再逐步加字体图、动画和属性插件映射。这样排查最快，也不会一开始就被资源包、属性名和显示 provider 混在一起。

最小可用配置

先确认普通伤害数字能显示：

hologram:
  mode: auto
  display-time: 60
  height-offset: 2.5
  random-offset:
    enabled: true
    x: 0.5
    y: 0.5
    z: 0.5
  animation:
    enabled: true
    types:
      - float

format:
  decimal-places: 1
  thousands-separator: ","
  decimal-separator: "."
  min-display-value: 0.1

range:
  view-distance: 30
  only-for-combatants: false

filter:
  ignored-damage-causes: []
  ignored-entity-types: []
  min-damage: 0.0
  ignore-self-damage: true

保存后执行：

/gtdamage reload

然后打一只普通怪物。正常情况下，怪物头顶会出现类似下面的数字：

18,400.0

显示 provider

hologram.mode 决定伤害数字用什么方式显示。

mode	适合场景
auto	日常使用，自动选择可用方案
ady	已安装 Adyeshach，优先使用虚拟实体
packet	使用 ProtocolLib 发包显示，适合需要低版本兼容
native	高版本原生 TextDisplay

推荐先用：

hologram:
  mode: auto

如果高版本 TextDisplay 有黑色背景，开启：

text:
  transparent-background: true

如果想强制走 ProtocolLib 虚拟 ArmorStand：

hologram:
  mode: packet

如果服务器已经稳定使用 Adyeshach：

hologram:
  mode: ady

伤害类型样式

伤害类型写在 damage-types 里。每个类型都可以单独设置颜色、前缀、后缀和显示倍率。

damage-types:
  physical:
    color: "§f"
    prefix: ""
    suffix: ""
    scale: 1.0
    scale-enabled: false

  critical:
    color: "§6"
    prefix: "§l✦ "
    suffix: "§c暴击"
    scale: 1.0
    scale-enabled: false

  magic:
    color: "§b"
    prefix: "✧ "
    suffix: ""
    scale: 1.0
    scale-enabled: false

效果示例：

18,400.0
✦ 18,400.0暴击
✧ 12,500.0

显示倍率

scale 只影响显示出来的数字，不改变实际伤害。

例如实际伤害是 1000，想让暴击显示成 1500：

damage-types:
  critical:
    color: "§6"
    prefix: "§l✦ "
    suffix: "§c暴击"
    scale: 1.5
    scale-enabled: true

这适合做视觉强化。实际扣血仍然以属性插件或 Bukkit 事件结算为准。

属性映射

GTDamage 会把属性插件返回的属性名映射成伤害类型。映射写在 crane-attribute 节点，虽然名字叫 crane-attribute，但 AttributePlus、CraneAttribute、SX-Attribute 等适配器都会使用这套映射。

crane-attribute:
  trigger-attributes:
    "暴击率": "critical"
    "暴击几率": "critical"
    "Crit": "critical"
  attribute-type-mapping:
    "物理伤害": "physical"
    "物理攻击力": "physical"
    "魔法伤害": "magic"
    "真实伤害": "true"
  default-type: "physical"
  type-weights:
    true: 15
    critical: 10
    magic: 7
    physical: 1

AttributePlus 示例

AP 中属性名是 暴击几率、物理伤害，可以这样写：

crane-attribute:
  trigger-attributes:
    "暴击几率": "critical"
  attribute-type-mapping:
    "物理伤害": "physical"
    "魔法伤害": "magic"

如果 AP 事件已经告诉 GTDamage “这次是暴击”，GTDamage 会直接按 critical 类型显示。

CraneAttribute 示例

CA 中属性名是 暴击率、物理攻击力：

crane-attribute:
  trigger-attributes:
    "暴击率": "critical"
  attribute-type-mapping:
    "物理攻击力": "physical"
    "魔法攻击力": "magic"

SX-Attribute 示例

SX 常见英文属性：

crane-attribute:
  trigger-attributes:
    "Crit": "critical"
    "Lightning": "lightning"
  attribute-type-mapping:
    "Damage": "physical"
    "Real": "true"

新增一种伤害类型

例如要做“冰霜伤害”：

damage-types:
  frost:
    color: "§b"
    prefix: "❄ "
    suffix: ""
    scale: 1.0
    scale-enabled: false

再把属性名映射过去：

crane-attribute:
  attribute-type-mapping:
    "冰霜伤害": "frost"
    "frost_damage": "frost"

效果：

❄ 8,520.0

资源包字体图

如果资源包里已经把数字做成图片或字体字符，可以启用 font-mapping。

font-mapping:
  enabled: true
  papi-support: false
  groups:
    default:
      permission: ""
      weight: 0
      mapping:
        "0": "<image:shanghaiziti:zt0>"
        "1": "<image:shanghaiziti:zt1>"
        "2": "<image:shanghaiziti:zt2>"
        "3": "<image:shanghaiziti:zt3>"
        "4": "<image:shanghaiziti:zt4>"
        "5": "<image:shanghaiziti:zt5>"
        "6": "<image:shanghaiziti:zt6>"
        "7": "<image:shanghaiziti:zt7>"
        "8": "<image:shanghaiziti:zt8>"
        "9": "<image:shanghaiziti:zt9>"
        ".": "<image:shanghaiziti:dot>"
        ",": "<image:shanghaiziti:comma>"

多个字体组可以用权限区分：

font-mapping:
  enabled: true
  groups:
    normal:
      permission: ""
      weight: 0
      mapping:
        "0": "<image:normal:0>"
    vip:
      permission: "gtdamage.font.vip"
      weight: 10
      mapping:
        "0": "<image:vip:0>"

有多个组同时满足时，weight 高的优先。

动画调法

轻量上浮：

hologram:
  animation:
    enabled: true
    types:
      - float
    float-speed: 0.02
    float-distance: 0.8

爆开效果：

hologram:
  animation:
    enabled: true
    types:
      - burst
    burst-distance: 1.0
    burst-gravity: 0.05

多人副本推荐使用轻量上浮，不建议让所有伤害都使用复杂动画。

高密度场景配置

怪物多、攻速快、伤害段数多时，用下面这种配置更稳：

range:
  view-distance: 24
  only-for-combatants: true

performance:
  max-holograms: 80
  cleanup-interval: 80
  async-processing: true
  max-events-per-tick: 40

hologram:
  display-time: 40
  animation:
    enabled: true
    types:
      - float

含义：

• 只在 24 格内显示。
• 优先显示战斗相关玩家能看到的数字。
• 限制同时存在的数字数量。
• 显示时间缩短，减少堆积。

测试流程

1. 关闭 font-mapping.enabled。
2. hologram.mode 设置为 auto。
3. 打普通怪，看是否出现白色数字。
4. 开启属性插件，打开 debug.enabled 和 debug.log-damage-events。
5. 看控制台里的伤害类型是否正确。
6. 添加 damage-types 样式。
7. 最后再开启字体图。

常见问题

没有伤害数字

检查：

1. /gtdamage reload 是否成功。
2. filter.min-damage 是否设置过高。
3. filter.ignored-damage-causes 是否过滤了当前伤害来源。
4. range.view-distance 是否太小。
5. 当前 provider 是否可用。

暴击一直显示或一直不显示

打开：

debug:
  enabled: true
  verbose: true
  log-damage-events: true

然后攻击一次，看控制台输出的伤害类型和暴击状态。

如果属性插件事件返回的就是暴击，GTDamage 会按暴击显示；如果属性插件没有返回暴击，需要在 trigger-attributes 里补上对应属性名。

伤害类型变成奇怪名字

把属性插件里的实际属性名映射到自定义类型：

crane-attribute:
  attribute-type-mapping:
    "CRIT_CHANCE": "critical"
    "物理伤害": "physical"

类型名必须能在 damage-types 找到，否则会使用默认显示。

动画不流畅

优先调整：

hologram:
  display-time: 40
  animation:
    types:
      - float

performance:
  max-holograms: 80
  max-events-per-tick: 40

同时减少字体图数量和显示范围。字体图越复杂，客户端渲染压力越高。