地牢管理 API

QueDPAPI.dungeons() 提供地牢模板和实例管理功能。

---

模板查询

获取所有模板

val templates: Collection<DungeonTemplate> = QueDPAPI.dungeons().allTemplates()

获取特定模板

val template: DungeonTemplate? = QueDPAPI.dungeons().template("dungeon_id")
if (template != null) {
    println("地牢: ${template.name}")
}

注册自定义模板

QueDPAPI.dungeons().register(customTemplate)

---

实例管理

获取所有实例

val instances: Collection<DungeonInstance> = QueDPAPI.dungeons().instances()

获取特定实例

val instance: DungeonInstance? = QueDPAPI.dungeons().instance(instanceId)

获取玩家所在副本

val instance: DungeonInstance? = QueDPAPI.dungeons().instanceOf(player)
if (instance != null) {
    player.sendMessage("你在副本: ${instance.template.name}")
}

检查玩家是否在副本中

if (QueDPAPI.dungeons().isPlayerInDungeon(player)) {
    player.sendMessage("你正在副本中")
}

---

副本创建与操作

创建并启动副本

val template = QueDPAPI.dungeons().template("my_dungeon")
if (template != null) {
    val instance = QueDPAPI.dungeons().createAndStart(template, listOf(player))
    if (instance != null) {
        player.sendMessage("副本创建成功！")
    }
}

完成副本

QueDPAPI.dungeons().complete(instance)

失败副本

QueDPAPI.dungeons().fail(instance, DungeonInstance.FailReason.TIMEOUT)

清理副本

QueDPAPI.dungeons().cleanup(instance)

---

统计与查询

获取地牢摘要

// 所有地牢的摘要
val summaries: List<DungeonSummary> = QueDPAPI.dungeons().summaries()

// 特定地牢的摘要
val summary: DungeonSummary? = QueDPAPI.dungeons().summary("dungeon_id")
if (summary != null) {
    println("活跃实例: ${summary.activeInstances}")
    println("在线玩家: ${summary.onlinePlayers}")
}

检查可用槽位

if (QueDPAPI.dungeons().hasAvailableSlot("dungeon_id")) {
    player.sendMessage("可以进入！")
} else {
    player.sendMessage("副本已满")
}

获取统计信息

val stats: Map<String, Any> = QueDPAPI.dungeons().statistics()

---

完整示例

fun createDungeonForParty(leader: Player) {
    // 获取队伍
    val party = QueDPAPI.parties().get(leader)
    if (party == null) {
        leader.sendMessage("§c你不在队伍中！")
        return
    }
    
    // 获取地牢模板
    val template = QueDPAPI.dungeons().template("my_dungeon")
    if (template == null) {
        leader.sendMessage("§c地牢不存在！")
        return
    }
    
    // 检查槽位
    if (!QueDPAPI.dungeons().hasAvailableSlot("my_dungeon")) {
        leader.sendMessage("§c地牢实例已满！")
        return
    }
    
    // 创建并启动副本
    val players = party.members
    val instance = QueDPAPI.dungeons().createAndStart(template, players)
    
    if (instance != null) {
        leader.sendMessage("§a副本创建成功！")
    } else {
        leader.sendMessage("§c副本创建失败！")
    }
}

---

数据类

DungeonTemplate

data class DungeonTemplate(
    val id: String,                // 地牢ID
    val name: String,              // 显示名称
    val worldTemplate: String,     // 世界模板
    val minPlayers: Int,           // 最小人数
    val maxPlayers: Int,           // 最大人数
    val timeLimit: Long,           // 时间限制（秒）
    val maxInstances: Int          // 最大实例数（-1=无限）
    // ...
)

DungeonInstance

class DungeonInstance(
    val instanceId: UUID,          // 实例ID
    val template: DungeonTemplate, // 模板
    val world: World,              // 世界
    var status: DungeonStatus      // 状态
)

enum class DungeonStatus {
    PREPARING,   // 准备中
    ACTIVE,      // 进行中
    COMPLETED,   // 已完成
    FAILED       // 已失败
}

DungeonSummary

data class DungeonSummary(
    val template: DungeonTemplate,
    val activeInstances: Int,              // 活跃实例数
    val onlinePlayers: Int,                // 在线玩家数
    val hasAvailableSlot: Boolean,         // 是否有可用槽位
    val availableSlots: Int?               // 可用槽位数
)

---

返回值说明

• 返回 null 表示失败或不存在
• 集合类型返回空集合而不是 null
• Boolean 返回值表示操作成功/失败