物品提示与数据接入

先按引入依赖接入 API，并让用户创建物品提示模板。公共入口为 XerrAPI.tooltips 和 XerrAPI.itemData，不依赖内部 Service。

Tooltip 展示需要 Minecraft 1.21.2 或以上版本。

绑定与排版复制章节链接

物品操作从服务端主线程调用，返回副本，不直接改写传入对象：

import com.hiusers.xerr.api.XerrAPI

val slot = player.inventory.heldItemSlot
val original = player.inventory.itemInMainHand.clone()
val bound = XerrAPI.tooltips.bind(original, "item_card")

if (player.isOnline && player.inventory.getItem(slot) == original) {
    player.inventory.setItem(slot, bound)
    XerrAPI.tooltips.refresh(player)
}

item_card 必须由用户配置，不是内置模板。上例写回的副本只改变绑定控制信息，不改写名称或 Lore。Xerr 在网络显示层准备排版副本；使用 Lore 标记或自动匹配时，无需调用 bind，原物品也不增加控制数据。

常规接入使用标记或匹配规则，再请求刷新，无需手动 render。解除绑定返回的控制副本需要调用方写回；原始 Lore（包括模板标记）保持不变。render 是高级显示接口，结果不能放回真实背包、存入数据库，或作为源物品交给物品库。

读取物品数据复制章节链接

val snapshot = XerrAPI.itemData.read(item)
val attack = snapshot["nbt.WeaponData.attack"]
val stored = snapshot["pdc[\"weapons:attack\"]"]
val present = snapshot.has("data.damage")
val paths = snapshot.paths()

read 在主线程执行，返回脱离 Bukkit/NMS 对象的只读快照；随后可异步查询。不存在的路径返回 null，0 和 false 不算缺失。完整根节点与索引语法见数据路径。

扩展物品库复制章节链接

import com.hiusers.xerr.api.XerrAPI
import com.hiusers.xerr.api.itemdata.ItemData

val registration = XerrAPI.itemData.register(plugin, "my_items") { item ->
    val saved = itemLibrary.readSaved(item)
    if (saved == null) null
    else ItemData(saved.id, mapOf("damage" to saved.damage))
}

itemLibrary.readSaved 代表接入方自己的只读接口，不是 Xerr 提供的方法。读取器仅返回已经生成并保存的属性，不重新随机、不重建物品，不执行网络或磁盘 I/O。

Java 使用同一个 ItemDataProvider SAM 接口：

AutoCloseable registration = XerrAPI.get().itemData().register(plugin, "my_items", item -> {
    SavedItem saved = itemLibrary.readSaved(item);
    if (saved == null) return null;
    Map<String, Object> values = new HashMap<>();
    values.put("damage", saved.getDamage());
    return new ItemData(saved.getId(), values);
});

SavedItem 同样代表物品库自己的类型。返回值支持字符串、数字、布尔值、空值、嵌套 Map、列表和数组。不要返回外国插件的 ItemTag 包装器或懒加载对象。

• 不识别该物品时返回 null。
• plugin 是持有注册的 Bukkit 插件实例，停用后自动注销。
• 注册、主动 registration.close() 和读取器执行都在主线程。
• 读取器收到物品副本，不应修改它；业务属性保持在原物品库中，Xerr 不写入替代数据。
• 数据源 ID 全局唯一；多个读取器同时识别物品时，使用 providers.my_items.data.damage 显式取值。

只有该来源识别物品时，模板也可用 item.source: [my_items]、item.id: [my_sword] 匹配，并从 data.damage 读取属性。

属性更新后刷新复制章节链接

在完成属性更新并写回物品之后调用：

XerrAPI.tooltips.refresh(player)

请求允许从异步发起，实际读取和应用回到主线程。物品库应先写回原始业务物品，再请求刷新，不要把显示副本写回源背包。

常规背包交互会触发检查，但 Xerr 不承诺监听任意插件的任意内存修改，也不会每 tick 全量扫描背包。

Zaphkiel 接入复制章节链接

内置可选读取器通过物品库接口读取已保存 ID 与属性，并在物品生成或重建完成后请求刷新。未安装不加载，不是其它 Tooltip 用法的依赖。

临时 data-mapper 结果不等于已保存属性。需要额外计算的数据，由物品库保存结果或通过自定义读取器提供；不要在 Tooltip 排版时重跑物品生成脚本。

与物品元数据协作复制章节链接

Xerr 只改发给客户端的显示副本，不替换权威背包中的名称、Lore 或业务属性。物品库继续更新自己的原始物品即可，网络显示与校验由 Xerr 处理，接入者不要持久化显示副本。