管理员文档 · 扩展与 API
给开发者和服主的 Dominion API、事件与扩展开发入口。
扩展边界
Dominion 的数据库、缓存、UI 和事件处理都由插件内部统一维护。其他插件需要读取或联动领地时，应优先使用公开 API、事件或 PlaceholderAPI。不要直接读取 dominion.db，也不要依赖内部缓存类或 NMS 类。
Dominion 提供 API 模块，并暴露领地 DTO、成员、组、flag 与位置等数据访问能力。开发扩展时应把 Dominion 作为可选依赖处理。服务器没有 Dominion 时，扩展不应阻塞核心启动。
完整的附属开发指南请阅读 DominionAPI 开发指南，其中包含依赖配置、API 模块、常用 API、事件和实现示例。
社区开发的附属插件目录请查看社区附属插件。
推荐的扩展方式
- 用 Dominion API 查询当前位置领地、领地主人、成员和边界；
- 监听项目提供的事件来响应领地创建、删除、边界变化或权限变化；
- 用 PlaceholderAPI 把当前领地信息接入记分板、聊天、TAB 或菜单；
- 通过配置项让服务器管理员决定联动行为，而不是把规则写死在扩展里；
- 在目标 Paper、Spigot 或 Folia 服务端验证事件线程、异步任务和传送行为。
PlaceholderAPI 的边界
PlaceholderAPI 的安装、完整占位符列表和显示排错已经单独整理到PlaceholderAPI 文档。扩展通常不需要自己查询数据库即可使用其中的占位符；如果占位符需要传入领地名称，名称中包含特殊字符时应按 PlaceholderAPI 与目标插件的参数规则处理，不要直接拼接未经验证的玩家输入。
API 使用边界
Dominion 包含 NMS 实现。扩展直接使用 NMS 会降低可移植性。优先依赖 Dominion API 和 Bukkit/Paper 抽象。更新 Dominion 后，重新检查 API 签名、事件取消时机和异步回调。
报错信息收集
向扩展作者或 Dominion 维护者反馈问题时，请提供：运行环境信息、相关配置（隐藏密码）、完整异常堆栈、复现命令、玩家身份类型，以及已安装的 WorldGuard、Vault、PlaceholderAPI 等可选依赖。不要只提供一张“不能用”的截图。