API 参考

AreaModuleAPI 是面向外部的统一 API 入口，位于 me.kzheart.areamodule.api 包下。

查询

获取关卡

// 按 ID 获取
val level = AreaModuleAPI.getLevel("关卡ID")

// 获取所有关卡
val levels = AreaModuleAPI.getLevels()

// 按位置查找
val level = AreaModuleAPI.getFirstLevelAt(location)
val levels = AreaModuleAPI.getLevelsAt(location, onlyRunning = true)

查询状态

AreaModuleAPI.isLevelRunning("关卡ID")       // Boolean
AreaModuleAPI.isLevelCompleted("关卡ID")     // Boolean
AreaModuleAPI.getCurrentSubLevelId("关卡ID") // String?
AreaModuleAPI.getLevelType("关卡ID")         // String?

参与者查询

// 获取关卡参与者
val players = AreaModuleAPI.getParticipants("关卡ID")

// 获取玩家所在的关卡
val levels = AreaModuleAPI.getLevelsByPlayer(player, onlyRunning = true)
val level = AreaModuleAPI.getFirstLevelByPlayer(player)

// 获取包含子关卡信息的上下文
val ctx = AreaModuleAPI.getFirstLevelContextByPlayer(player)
// ctx.level → GameLevel
// ctx.currentSubLevel → GameSubLevel?

// 快捷方法
val levelId = AreaModuleAPI.getPlayerCurrentLevelId(player)
val subLevelId = AreaModuleAPI.getPlayerCurrentSubLevelId(player)

控制

启动关卡

val result = AreaModuleAPI.startLevelDetailed("关卡ID", ignoreCooldown = false)
if (result.success) {
    // 启动成功
} else {
    when (result.reason) {
        StartFailReason.NOT_FOUND -> // 关卡不存在
        StartFailReason.ALREADY_RUNNING -> // 已在运行
        StartFailReason.COOLDOWN -> // 冷却中
        StartFailReason.REGION_LOCKED -> // 区域被占用
        StartFailReason.NO_SUBLEVELS -> // 没有子关卡
    }
}

停止/失败

AreaModuleAPI.stopLevel("关卡ID")        // Boolean
AreaModuleAPI.failLevel("关卡ID", LevelFailEvent.FailReason.MANUAL)

推进子关卡

when (val result = AreaModuleAPI.advanceSubLevel("关卡ID")) {
    is AdvanceResult.Advanced -> // 进入下一关: result.newSubLevelId
    is AdvanceResult.Finished -> // 全部完成
    is AdvanceResult.NotRunning -> // 未在运行
}

硬重置

AreaModuleAPI.hardResetLevel("关卡ID", allowImmediateTrigger = true)
AreaModuleAPI.hardResetAll(allowImmediateTrigger = true)
AreaModuleAPI.hardResetSubLevel("关卡ID", "子关卡ID")
AreaModuleAPI.hardResetModule("关卡ID", "子关卡ID", moduleOrder = 0)

分数

AreaModuleAPI.getScore("关卡ID", "key")                // Int?
AreaModuleAPI.setScore("关卡ID", "key", 10)            // Boolean
AreaModuleAPI.addScore("关卡ID", "key", 5)             // Boolean
AreaModuleAPI.getScoreProgressString("关卡ID", "key")  // String? ("10/20")

子关卡与模块

val subLevel = AreaModuleAPI.getSubLevel("关卡ID", "子关卡ID")