API 参考

扩展入口导航

OvertureAPI 同时包含日常物品操作和第三方扩展注册。扩展入口都要求传入 Bukkit Plugin 与属于该插件的 NamespacedKey，并返回可注销的 RegistrationHandle。

注册入口	适合解决的问题	配置中的引用位置	是否需要重载	接口稳定性
`registerRenderEntry`	根据玩家、物品和实例数据生成名称/Lore 文本	Display 的 `<namespace:key>` 或 `<namespace:key...>`	下一次渲染即可使用；模板缓存可能需要刷新	稳定 API
`registerTrigger`	把第三方 Bukkit 事件接入物品动作	`event.namespace:key`	新增后需要重载物品快照	稳定入口；结果中的 `signals` 仍是低层类型
`registerBehavior`	用类型安全 Kotlin/Java 逻辑处理物品触发器；回调必须自行过滤 `context.trigger`	`behaviors.namespace:key`	下一次触发即可解析	稳定 API
`registerItemComponent`	校验第三方 YAML，并持久化 definition/instance 数据	`components.namespace:key`	新增或注销后需要重载	稳定 API
`registerProvider`	从数据库、缓存或其他来源提供完整物品定义	不直接引用；Provider 返回物品 ID 映射	必须重载后提交新快照	低层、同版本耦合
`registerMeta`	参与 ItemTag、ItemMeta 与释放阶段，管理原版物品属性	`meta.namespace:key`	必须重载后重新创建 Meta	低层、同版本耦合
`registerMapperFunction`	把扁平物品数据纯函数映射为一个字符串	`data-mapper` 中的 `namespace:key(...)`	下一次展示重建即可使用	低层、同版本耦合

注册优先级、生命周期、完整回调字段和端到端示例见扩展注册。选择扩展点时优先使用稳定的Component、Behavior 和 RenderEntry；只有确实需要替换物品来源、进入原生 Meta 生命周期或增加高频纯字符串函数时，才使用 Provider、Meta 或 Mapper。

特别注意：behaviors.namespace:key 表示“给物品绑定这个处理器”，不表示“只在某个 Trigger 调用”。同一物品进入右键、攻击、构建、释放或外部 Trigger 时，绑定的 Behavior 都可能收到回调；处理器应先比较 context.trigger，对无关触发器返回 ItemBehaviorResult.PASS。

注册成功只表示扩展进入注册表，不等于已经修改当前物品快照。Provider、Meta、Trigger 与组件 codec 在运行期新增后，必须在主线程调用 reloadWithReport()，并且仅在 success == true 时认为新定义已经生效。

import priv.seventeen.artist.overture.api.OvertureAPI

查询与生成

方法	返回	说明
`getItemIds()`	`List<String>`	获取全部物品 ID
`generateItem(id, player?)`	`ItemStack?`	生成实例；构建取消时返回 `null`
`getItemName(id)`	`String?`	获取缓存的默认模板名
`getItemLore(id)`	`List<String>?`	获取缓存的默认模板 Lore
`getTemplateItem(id)`	`ItemStack?`	获取只用于展示的模板 clone
`isOvertureItem(item)`	`Boolean`	判断是否为 Overture 物品
`getOvertureId(item)`	`String?`	读取物品 ID

首次调用 getItemName、getItemLore 或 getTemplateItem 可能生成默认模板，并触发 Build/Release Bukkit 生命周期事件；Overture 自身的 Aria 与 Behavior 会因模板信号而跳过。返回模板只用于展示，不应直接发放。

val generated = OvertureAPI.generateItem("diamond_sword", player)
val id = generated?.let(OvertureAPI::getOvertureId)

getTemplateItem 只适合菜单图标。唯一 UUID、随机值等实例数据不会重新生成，不能把模板 clone 直接发给玩家。

getItemName、getItemLore 与 getTemplateItem 使用 player = null 的模板缓存，不包含玩家条件展示或实例数据变量。模板仍经过 Meta、Display 和 Bukkit 构建事件，但不会执行 Behavior、on_build 或 on_release 动作。

读取与修改实例数据

val result = OvertureAPI.mutateItem(itemStack, player) { data ->
    val level = (data.get("custom.level") as? ItemDataNode.Integer)?.value ?: 0L
    data.put("custom.level", ItemDataNode.Integer(level + 1))
}
 
when (result) {
    is ItemMutationResult.Success -> player.inventory.setItemInMainHand(result.itemStack)
    is ItemMutationResult.Failure -> logger.warning(result.reason)
}

mutateItem 只修改 clone，并在提交前按当前定义重建名称、Lore 与 Meta。成功结果必须写回原槽位；失败时输入 ItemStack 保持不变。

序列化

val json = OvertureAPI.serialize(itemStack)
val restored = OvertureAPI.deserialize(json)

schema v2 保存物品 ID、数量、data 与 unique 等持久化数据。名称、Lore 和 Bukkit ItemMeta 会在反序列化时按当前定义重新构建。

serialize 也接受原版物品：输出使用 kind: "minecraft"，保存材质、数量，并在 Asteroid 可正常读取时附带完整 NBT；反序列化会优先从 NBT 恢复，缺少 NBT 时退回材质与数量。

非法 schema、未知数据类型或超出大小限制时，deserialize 返回 null。

schema v2 的主要边界为：JSON 最长 1,048,576 字符、深度 32、节点 16,384、字符串 32,767 字符、数组 65,536 项、物品 ID 256 字符，数量范围 1–127。

稳定组件数据 API

方法	说明
`readItemData(item)`	获取不可变 `ItemDataView`
`mutateItem(item, player?, mutation)`	在 clone 上原子修改并重建
`rebuildItem(item, player?)`	按当前定义重建 clone，保留实例数据

成功修改或重建会返回新的 ItemStack，调用方必须写回原背包槽、容器或实体；失败不会部分修改原物品。

mutateItem 接受 ItemDataMutation，回调中的 MutableItemData 提供相对 overture.data 的 get、put 与 remove。结果为 ItemMutationResult.Success(itemStack) 或 ItemMutationResult.Failure(reason, cause)。

ItemDataView.itemId 是可空值：非 Overture 物品返回空视图且 itemId = null。component(key) 读取 overture.data.<namespace>.definition.<key>，namespace(name) 返回整个命名空间快照。所有返回节点均不可变。

MutableItemData.get/put/remove 的路径相对 overture.data，必须由 1 至 32 个非空点分段组成。Failure.reason 是可展示的失败原因，cause 仅用于日志诊断；调用失败后不得写回任何中间结果。

ItemDataNode 只包含 Compound、ListNode、Text、Integer(Long)、Decimal(Double) 与 Bool。ItemDataLimits 定义最大深度 32、节点 16,384、字符串 32,767 字符、列表 65,536 项；NBT 列表必须同构，小数必须为有限值。

重载

OvertureAPI.reloadWithReport() 只能在主线程调用。它会重建物品、事件模型、Display 与分组快照；成功后再刷新 rarity.yml 和 drop-labels.yml，但不会读取 config.yml 或 language.yml。失败时旧快照继续生效。

返回的 ReloadReport 包含成功状态、耗时、物品/模型数量、issues、conflicts 与 rolledBack。ReloadIssue 通过 ReloadIssueSeverity.WARNING/ERROR 标记问题，并可定位来源、物品、路径、组件和 owner；ReloadConflict 会给出冲突资源、前后 ResourceOrigin、来源与裁决策略。非主线程调用会直接返回失败报告，不会触发重载事件。

线程边界

背包或实体写回、GUI 与外部触发器 dispatch 必须在主线程执行。
异步生成应使用 player = null。
Aria、Behavior 和事件监听器必须自行遵守 Bukkit 线程规则。
第三方 RenderEntry 只在主线程执行，异步构建会跳过并记录警告。

面向普通附属插件的稳定扩展面是组件与实例数据、RenderEntry、Trigger 和 Behavior。持久状态应通过组件 codec、ItemDataView 与 MutableItemData 操作。

不要自行构造、缓存或跨线程传递 ItemStream，也不要通过 Asteroid NBT 或 Bukkit YAML 直接操作实例数据。

当前 ItemProvider 返回的 OvertureItem、自定义 Meta/Mapper factory、ExternalTriggerResult.signals 以及部分生命周期事件仍会暴露 core.* 类型。这些接口的包名、构造参数和执行阶段都可能随 Overture 版本调整，附属插件必须针对服务端实际安装的 Overture 版本编译，并在目标 Paper 版本上运行测试。事件中的 stream 仅在当前回调内有效。