公共 API

Symphony 通过 Bukkit ServicesManager 注册 SymphonyApi。附属插件应把 API 设为 compileOnly，不要把 Symphony 类打进自己的 JAR。

val api = Bukkit.getServicesManager().load(SymphonyApi::class.java)
    ?: error("属性服务尚未就绪")

必须安装 Symphony 时，在 plugin.yml 中使用 depend；仅在存在时启用兼容功能，则使用 softdepend 并处理服务为空的情况。

选择需要的服务

可运行的附属示例

源码仓库提供两个独立插件：

• 简单等级插件：注册、刷新和注销 LevelProvider；
• 外置符文系统：注册外部属性，维护稳定来源，并响应等级变化。

示例目录各自包含构建、配置、命令和安装说明。

注册项的清理

registerProvider、registerAttribute 等方法会返回 RegistrationHandle。附属插件应保存这些对象，并在停用时调用 close()。

close 可以重复调用。即使忘记手动关闭，Symphony 也会在提供注册项的插件停用时移除它们；主动关闭仍能让重载过程更清晰。

主要事件

伤害事件的选择和字段较多，单独见主动伤害与伤害事件。

线程规则

• 实体、物品栏、Bukkit 事件、伤害、技能、等级刷新和来源写入都应在合法 Bukkit 主线程调用；
• AttributeProvider 与 LevelProvider 不应等待数据库或网络；
• combatPower.cached(UUID) 可以供异步只读调用，缓存不存在时不要在异步线程强制计算实体；
• Symphony 不支持 Folia，本节规则不适用于 RegionScheduler。

Java 调用

公开接口可以从 Java 直接使用。按攻击者当前属性发起普通攻击时，可以省略伤害倍率，也可以显式传入倍率：

api.getDamage().attack(attacker, victim);
api.getDamage().attack(attacker, victim, 1.5D);

固定数值的单通道伤害提供四参数和五参数重载：

api.getDamage().damage(
    attacker,
    victim,
    "arcane",
    15.0,
    "myplugin:spell"
);

等级与属性 Provider 都是普通接口，Java 和 Kotlin 附属插件均可实现。