AuroraUI 公开 API

设计理念

快速上手

依赖（pom.xml）：

<dependency>
  <groupId>aurora.studio.aurora.ui</groupId>
  <artifactId>auroraui-api</artifactId>
  <version>LATEST</version>
  <scope>provided</scope>
</dependency>

最小可用示例 — 一个"商店"锚点，带画布、权限、点击事件：

import aurora.studio.aurora.ui.api.*
import org.bukkit.plugin.java.JavaPlugin

class MyShopPlugin : JavaPlugin() {
    override fun onEnable() {
        AuroraUI.declare("myshop:shop", this) {
            permission = "myshop.use"
            captureScroll = true
            tickEvery = 2

            onActivate { evt ->
                // this == AuroraUIRealm，直接访问上下文
                server.broadcast("${player.name} 进入商店")
                cursor(true)
            }

            onScroll { evt ->
                // 滚轮翻页
            }

            onClose { evt ->
                // evt.reason ∈ AuroraUICloseReason
            }
        }
    }
}

通过命名空间路由打开锚点（或从 HTML 菜单用 open-app: myshop:shop）：

AuroraUI.route("myshop:shop", this, AuroraUIRoute { player, args ->
    AuroraUI.show(player, "myshop:shop", args, AuroraUIShowKind.ANCHOR)
})

AuroraUI.declare(id, owner) { ... }

声明一个锚点（独立于菜单的、由第三方插件托管的 UI 会话）。DSL 块里可写以下属性与回调：

AuroraUI.declare 返回 AuroraUIAnchorHandle：

val handle: AuroraUIAnchorHandle = AuroraUI.declare("myshop:shop", this) { ... }
handle.alive          // 是否已注册
handle.remove()       // 手动注销（插件禁用时自动移除）
// handle.close() 等价于 remove()

AuroraUI.route / AuroraUI.dispatch

轻量命名空间路由 —— 菜单 open-app: myshop:shop args... 的入口。

// 注册
AuroraUI.route("myshop:shop", this, AuroraUIRoute { player, arguments ->
    AuroraUI.show(player, "myshop:shop", arguments, AuroraUIShowKind.ANCHOR)
})
// 也可以直接打开菜单
AuroraUI.route("myshop:quick-help", this, AuroraUIRoute { player, args ->
    AuroraUI.show(player, "help", args, AuroraUIShowKind.MENU)
})

// 查询/移除
AuroraUI.namespaces()      // Set<String>
// 插件禁用时自动移除其所有 route

AuroraUI.show / AuroraUI.hide / AuroraUI.back

指针模式

AuroraUI.modeOf(player)                      // AuroraUIMode
AuroraUI.modeOf(player, AuroraUIMode.MOUSE)       // Boolean（是否成功切换）
AuroraUI.policy()                            // AuroraUIPolicy

// 查询当前画布/指针
AuroraUI.surfaceOf(player)                   // AuroraUISurface?
AuroraUI.pointOf(player)                     // AuroraUIPoint?

DSL 事件 —— 生命周期

onActivate

onActivate { evt ->
    // this@AuroraUIRealm 可用
    val p: Player = player
    val point: AuroraUIPoint? = evt.point
    val button: AuroraUIButton = evt.button      // LEFT / RIGHT / SHIFT_LEFT ...
    val sneaking: Boolean = evt.sneaking
    cursor(true)
    // 打开子锚点：
    showAnchor("myshop:detail", listOf("item=5"))
}

onClose

onClose { evt ->
    val reason: AuroraUICloseReason = evt.reason
    // REQUESTED / BACK / REPLACED / PLAYER_QUIT / PLUGIN_DISABLE / ERROR ...
}

DSL 事件 —— 指针

onPointerMove { evt ->
    val current: AuroraUIPoint? = evt.point
    val prev:    AuroraUIPoint? = evt.previous
}
onPointerModeChange { evt ->
    val prev = evt.previous    // AuroraUIMode
    val now  = evt.current
}
onScroll { evt ->
    val steps: Int = evt.steps  // 正=上, 负=下
}

DSL 事件 —— 画布 & Tick

onSurfaceChange { evt ->
    val surface: AuroraUISurface = evt.surface
    val initial: Boolean    = evt.initial   // true = 首次建立
}
onTick { evt ->
    val tick: Long = evt.tick
}

AuroraUIRealm —— 事件 receiver 的上下文

所有 DSL lambda 的 receiver 都是 AuroraUIRealm，自带 player、画布、指针等能力：

导航与生命周期管理

从旧 API 迁移

旧代码

AuroraUIApi ui = Bukkit.getServicesManager().load(AuroraUIApi.class);

AuroraUIApplicationHandle handle = ui.registerApplication(
    this, "myshop:shop",
    AuroraUIApplicationOptions.builder()
        .permission("myshop.use")
        .captureMouseScroll(true)
        .build(),
    context -> new ShopSession(context)
);

// ShopSession 继承 AuroraUIApplicationSession，重写 onActivate / onClose ...

新代码（等价）

AuroraUI.declare("myshop:shop", this) {
    permission = "myshop.use"
    captureScroll = true

    onActivate { evt ->
        // 原来写在 ShopSession.onActivate 的逻辑
    }
    onClose { evt ->
        // 原来写在 ShopSession.onClose 的逻辑
    }
}

对照表