线程、错误、超时、回收

这页只关心运行风险，不关心 UI 长什么样。

线程边界

• Bukkit API 操作必须留在主线程
• 你的 handler 不要在未受控异步线程里直接碰 Bukkit 对象
• 客户端跨线程更新 UI 时，使用 Scheduler.sync 或 nextTick

错误处理

• command / query / event 处理器都应该返回可读错误
• 错误日志至少带上 storeId、动作名、关键 payload

BUIServerAPI.action().command().register("shop/main", "shop.buy") { player, _, storeId, payload ->
    runCatching { shopService.buy(player, payload) }
        .getOrElse { ex -> throw IllegalStateException("shop.buy failed: storeId=$storeId, message=${ex.message}") }
}

超时意识

• query 和 command 应该快返回
• 重 IO 任务建议异步准备结果，再同步状态
• 客户端存储读取是异步回调，不要当同步 API 用

回收

• 玩家退出时，会话会清理 UI 与 store scope
• 插件重载时，记得清理自己注册的 handler
• 客户端热键、任务、监听器在卸载时回收