物品提示
Tooltip 模板、名称与 Lore 排版、布局引用和物品数据路径
Tooltip 用于物品悬停提示，只排版发给客户端的显示副本，并插入图文布局；服务端原始名称、Lore 和业务属性保持不变。模板位于 core/template/tooltips/，支持子目录，顶层节点是模板 ID。
插件不附带 Tooltip 模板或美术资源，可自行制作，或安装配件套。可视化制作见编辑物品提示，手写配置见制作物品提示。
游戏内使用需要 Minecraft 1.21.2 或以上版本。
启用与模板
在 config.yml 中设置 feature.tooltip.enable: true，制作完成后执行 /xerr pack 并让客户端加载资源包。
defaults:
font: pixel
item_card:
mode: insert
name-align: center
lore-align: left未设置 layout 时，只排版原有名称和 Lore。宽度根据名称、Lore 与布局内容自动测量，不填写固定宽度；每条 Lore 对应一行，不自动换行。
| 字段 | 类型 / 默认值 | 作用 |
|---|---|---|
font | 字符串 / 无 | 已配置的 Xerr TTF 字体；可继承文件 defaults.font 或引用布局的默认字体 |
mode | insert | 布局插入方式，支持 insert、append |
layout | 字符串 / 无 | 普通布局的顶层 ID，不是文件名 |
name-align | left | 名称对齐，支持 left、center |
lore-align | left | 原 Lore 对齐，支持 left、center、right |
variables | 映射 / 空 | 静态变量默认值 |
data | 映射 / 空 | 将物品数据路径映射为布局变量 |
match | 映射 / 空 | 自动应用模板的匹配规则；留空时手动绑定 |
style | 字符串 / 无 | 可选原生 Tooltip 样式 ID，如 my_pack:weapon；对应图片由自己的资源包提供 |
insert 与 append
假设原 Lore 为：
lore:
- "&7物品说明"
- "<<tooltip:item_card>>"
- ""
- "&8不可交易"insert：移除标记行，在原位置插入布局；后面的空行和文字保留。append：移除标记行，先显示其余 Lore，再把布局放到最后。- 没有标记、通过命令或 API 绑定时，两者都将布局放在原 Lore 后面。
标记仅在客户端显示副本中移除，服务端原始 Lore 保留。一个物品只绑定一个模板。标记须单独占一行，并由物品插件原样保留。若物品插件自身会解析尖括号，优先使用自动匹配或 API 绑定。
静态参数可写为 <<tooltip:item_card::category=工具>>。读取物品属性时不需要把数值拼进标记。
布局与数据映射
在模板中填写：
layout: item_details
data:
attack: nbt.WeaponData.attack对应布局由你创建：
defaults:
font: pixel
item_details:
attack:
condition: "item-data has attack"
x: 0
y: 0
value: "&f攻击 +{{ item-data get attack }}"布局使用局部 X/Y，不使用屏幕锚点，也不用登记到常驻 HUD。支持文字、静态图片、文字背景、list 和 lines。
item-data get attack 读取模板映射的 attack，也可以直接写 {{ item-data get nbt.WeaponData.attack }}。缺失值返回空，0 和 false 不算缺失；使用 condition 控制对应内容是否显示。
声明在 data 中的变量不会回退到 variables 的静态值，显式绑定参数仍可覆盖。读取到的文字不会作为第二层 Kether 脚本执行。
可用路径
| 路径 | 读取内容 |
|---|---|
item.material | 材质 ID，小写形式，如 iron_sword |
item.amount | 堆叠数量 |
item.damage | 已损耗耐久，不是物品攻击力 |
item.source / item.id | 只有一个数据源识别物品时的来源与物品 ID |
data.damage | 单一物品库数据源的业务属性 |
nbt.WeaponData.attack | 自定义 NBT；新版本对应 minecraft:custom_data 内部内容 |
pdc["weapons:attack"] | Bukkit 持久化数据，保留完整命名空间 |
data.effects[0].power | 列表中的第一个元素 |
nbt["a.b"].value | 键名本身含点号的情况 |
providers.zaphkiel.data.damage | 显式指定数据源 |
nbt 不是整个物品的序列化结果，不包含所有原版组件。路径只访问对象键和非负列表下标，不支持表达式、过滤器或通配查询。存为 JSON 字符串的字段仍是字符串，需要通过数据读取器转换后才能访问其内部属性。
手持自己的物品，查询实际字段：
/xerr tooltip data
/xerr tooltip data nbt.WeaponData.attack名称与多行 Lore
| 变量 | 内容 |
|---|---|
@item_name | 原物品名称 |
@item_lore | 移除标记后的原 Lore 列表 |
@item_amount | 物品数量 |
@item_material | 小写材质 ID |
列表可交给 lines.content，每个元素作为一行文字，不继续执行其中的脚本：
lines:
content: "item-data get data.description"
offset:
y: -10原 Lore 在插入和追加模式中都会保留；再次用 get @item_lore 绘制它会重复显示。Tooltip 使用物品快照，不提供查看者的玩家上下文。
自动匹配物品
match:
item.source: [zaphkiel]
item.id: [my_sword]
data:
attack: data.damage不同路径之间全部满足，同一路径的列表满足一项即可，匹配值支持 *。多个模板同时匹配会报告冲突，不按文件加载顺序选择。命令、API 或标记显式绑定优先于自动匹配。
已内置 Zaphkiel / Zaphkiel-Plus 的可选读取器，未安装不影响其它方式使用。只读取已保存属性，不重新生成数值；临时 data-mapper 显示变量不等于已保存数据。其它物品库可直接使用 NBT/PDC 路径，或注册读取器。
多个数据源同时识别物品时，用 providers.<来源>.data.<属性> 明确指定，不使用含糊的 data.*。
刷新与支持范围
- 背包打开、操作、拾取、切换手持物品时触发检查；数据未变则复用结果，不每 tick 扫描背包。
- 其它插件在后台改动属性时，应在写回物品后通过 API 请求刷新。
- 需要已有自定义名称的物品，名称与 Lore 使用文字组件，不猜测客户端翻译组件的宽度。
- 排版只作用于出站显示副本，物品库与数据库仍读取原始名称、Lore 和业务属性。
- 名称居中使用对称留白；所选字体也会应用于快捷栏上方的手持物品名称。
- 原生附魔、属性和调试信息可能扩大提示框，自动测量只覆盖模板管理的内容。
- 不支持整框替换、名称右对齐、头像、人物、进度条、罗盘、动画或切块图片。静态图片须符合原生单字形尺寸限制。
- 较早版本已写入排版、且保留原始快照的物品会还原一次；之后不再向真实物品写入显示字形，无法安全还原时不会猜测覆盖。