世界管理 API

QueDPAPI.worlds() 提供快速世界创建和管理功能，利用 QueDP 的优化复制机制。

---

快速创建世界

从模板创建（推荐）

// 创建临时世界
val world: World? = QueDPAPI.worlds().createWorld("arena_template")

if (world != null) {
    player.teleport(world.spawnLocation)
    
    // 使用完毕后删除
    QueDPAPI.worlds().deleteWorld(world)
}

从文件创建

// 支持世界文件夹和 schematic 文件
val worldFolder = File("D:/maps/pvp_arena")
val world: World? = QueDPAPI.worlds().createWorld(worldFolder)

// 或从 schematic
val schematic = File(plugin.dataFolder, "maps/arena.schem")
val world: World? = QueDPAPI.worlds().createWorld(schematic)

优势：

• ⚡ 极快 - 利用 QueDP 优化的复制算法
• 🎯 简单 - 一行代码创建世界
• 🔄 自动清理 - 用完即删，不占空间

---

模板管理

注册外部模板

// 注册你的地图模板
val myMapFolder = File(plugin.dataFolder, "maps/arena")
val success = QueDPAPI.worlds().registerTemplate(
    templateName = "my_arena",
    worldFolder = myMapFolder,
    source = plugin.name  // 插件名，用于管理
)

if (success) {
    logger.info("模板注册成功: my_arena")
}

获取可用模板

val templates: List<String> = QueDPAPI.worlds().getAvailableTemplates()
templates.forEach { println("模板: $it") }

查询模板来源

// 获取模板来源（哪个插件注册的）
val source: String? = QueDPAPI.worlds().getTemplateSource("my_arena")
if (source != null) {
    println("模板来自: $source")
}

// 获取某插件注册的所有模板
val myTemplates: List<String> = QueDPAPI.worlds().getTemplatesBySource(plugin.name)

注销模板

// 注销单个模板
QueDPAPI.worlds().unregisterTemplate("my_arena")

// 批量注销（插件卸载时）
val count: Int = QueDPAPI.worlds().unregisterTemplatesBySource(plugin.name)
logger.info("已注销 $count 个模板")

---

地图导入/删除

导入地图

// 导入地图到 QueDP 的 maps 文件夹
val source = File("D:/downloads/pvp_arena")
if (QueDPAPI.worlds().importMap(source, "pvp_arena")) {
    logger.info("地图导入成功！")
}

删除地图

// 删除地图（如果有实例在使用会失败）
if (QueDPAPI.worlds().deleteMap("old_arena")) {
    logger.info("地图已删除")
}

---

持久化世界（编辑器用）

获取或创建世界

// 如果世界存在则返回，不存在则创建
val editWorld: World? = QueDPAPI.worlds().getOrCreateWorld(
    worldName = "edit_arena",
    templateName = "arena_template"
)

// 地牢专属编辑世界
val editWorld: World? = QueDPAPI.worlds().getOrCreateWorld(
    worldName = "edit_dungeon1",
    dungeonId = "dungeon1",
    templateName = "default_template"
)

---

统计信息

val stats: Map<String, Any> = QueDPAPI.worlds().getStatistics()
println("可用模板: ${stats["availableTemplates"]}")
println("模板列表: ${stats["templates"]}")

---

完整示例：小游戏插件

class MiniGamePlugin : JavaPlugin() {
    
    private val activeGames = mutableMapOf<UUID, GameWorld>()
    private val MY_MAP_TEMPLATE = "minigame_arena"
    
    override fun onEnable() {
        // 注册地图模板
        val mapFolder = File(dataFolder, "maps/arena")
        
        val success = QueDPAPI.worlds().registerTemplate(
            MY_MAP_TEMPLATE,
            mapFolder,
            name
        )
        
        if (success) {
            logger.info("✓ 地图模板注册成功")
        }
    }
    
    override fun onDisable() {
        // 清理所有游戏
        activeGames.keys.toList().forEach { endGame(it) }
        
        // 注销模板
        QueDPAPI.worlds().unregisterTemplatesBySource(name)
    }
    
    fun startGame(players: List<Player>) {
        val gameId = UUID.randomUUID()
        
        // 创建世界
        val world = QueDPAPI.worlds().createWorld(MY_MAP_TEMPLATE)
        if (world == null) {
            players.forEach { it.sendMessage("§c游戏创建失败") }
            return
        }
        
        // 传送玩家
        players.forEach { 
            it.teleport(world.spawnLocation)
            it.sendMessage("§a游戏开始！")
        }
        
        // 记录游戏
        activeGames[gameId] = GameWorld(gameId, world, players)
        
        // 5分钟后自动结束
        server.scheduler.runTaskLater(this, Runnable {
            endGame(gameId)
        }, 5 * 60 * 20L)
    }
    
    fun endGame(gameId: UUID) {
        val game = activeGames.remove(gameId) ?: return
        
        // 传送玩家离开
        val mainWorld = server.worlds[0]
        game.players.forEach { 
            it.teleport(mainWorld.spawnLocation)
            it.sendMessage("§e游戏结束！")
        }
        
        // 删除世界
        QueDPAPI.worlds().deleteWorld(game.world)
        
        logger.info("✓ 游戏结束，世界已清理")
    }
}

data class GameWorld(
    val id: UUID,
    val world: World,
    val players: List<Player>
)

---

工作流程

1. 插件启动
   └─ 注册模板到 QueDP

2. 创建游戏
   └─ createWorld("my_template")
      └─ QueDP 从你的插件文件夹复制（极快）

3. 游戏结束
   └─ deleteWorld(world)
      └─ 临时世界被删除

4. 插件卸载
   └─ 注销所有模板

---

为什么快？

• 优化的复制算法 - QueDP 内部优化了文件复制
• 模板复用 - 同一模板可快速创建多个世界
• 地图留在原处 - 不需要放到 QueDP 文件夹
• 自动清理 - 用完自动删除，不占空间

---

返回值说明

• 返回 null 表示操作失败
• Boolean 返回值表示成功/失败
• 集合方法返回空集合而不是 null

---

注意事项

• ⚠️ 世界创建必须在主线程执行
• ⚠️ 删除世界前确保所有玩家已离开
• ⚠️ schematic 文件需要 WorldEdit 插件支持