API 参考 / capability 包：服务、状态与游玩访问

InputAccess

输入控制能力（游玩中可用）：查询按键状态、订阅按键事件、消费指定按键。经 ctx.capabilities().get(InputAccess.class) 取用。

方法速览

方法	用途
`isKeyDown(int)`	查询按键是否按住
`subscribeKeyHandler(Consumer<InputEvent>)`	订阅按键事件
`consumeKey(int)`	标记消费指定按键（当前版本不生效，见下）
`unsubscribeKeyHandler(Consumer<InputEvent>)`	退订

完整签名

java

public interface InputAccess {

    boolean isKeyDown(int keyCode);

    void subscribeKeyHandler(java.util.function.Consumer<InputEvent> handler);

    void consumeKey(int keyCode);

    void unsubscribeKeyHandler(java.util.function.Consumer<InputEvent> handler);
}

isKeyDown(int keyCode)

签名：

java

boolean isKeyDown(int keyCode);

行为：查询按键当前是否按住（java.awt.event.KeyEvent.VK_* 键码），直接转发宿主输入管理器的按住表。

示例：

java

if (input.isKeyDown(java.awt.event.KeyEvent.VK_SHIFT)) {
    // Shift 按住
}

subscribeKeyHandler(Consumer handler)

签名：

java

void subscribeKeyHandler(java.util.function.Consumer<InputEvent> handler);

行为：订阅按键事件；宿主在游玩场景每帧收集按键并按 KEY_PRESSED / KEY_RELEASED / KEY_HELD 逐条分发（文本输入与鼠标事件不走本通道）。

同一 handler 重复订阅只保留一份（按实例去重）；handler 为 null 时忽略。
允许在分发过程中退订（含订阅者自退订）；单个订阅者抛异常由宿主隔离，不影响其它订阅者。

示例：

java

input.subscribeKeyHandler(e -> {
    if (e.keyCode() == java.awt.event.KeyEvent.VK_ESCAPE
            && e.type() == InputType.KEY_PRESSED) {
        // 处理
    }
});

consumeKey(int keyCode)

签名：

java

void consumeKey(int keyCode);

行为：把键码记入本帧消费表，帧末由宿主清空。

注意（当前实现缺口）：宿主把消费记录写入黑名单，但游玩场景的输入判定从未查询该记录，且记录在事件分发后立即清空。当前版本调用 consumeKey 不会真正阻止游戏内处理；接管轨道键请改用 LaneInputMapper，全局快捷键请用 GlobalHotkeys。

示例：

java

input.consumeKey(java.awt.event.KeyEvent.VK_SPACE);   // 当前版本仅记录，不拦截

unsubscribeKeyHandler(Consumer handler)

签名：

java

void unsubscribeKeyHandler(java.util.function.Consumer<InputEvent> handler);

行为：移除按键事件订阅；未订阅过或 handler 为 null 时无操作。

示例：

java

input.unsubscribeKeyHandler(myHandler);

线程：能力在游玩场景 onEnter / onExit 时注册 / 注销，因此只在游玩中可取到。订阅回调在游玩场景的事件分发阶段（游戏线程）触发；订阅列表允许回调内退订。

稳定性：2.0 起冻结：2.x 内只增不破。

上一页AudioAccess 下一页GameStateAccess