JudgeInputState

每帧判定回调（onJudgeTick）收到的输入快照，由宿主在分发前构造。模组无需自行订阅按键事件即可实现连按、按住、松开等组合判定。键码与 java.awt.event.KeyEvent 一致。

方法速览

pressedKeys()

签名：

java.util.Set<Integer> pressedKeys();

行为：本帧新按下的物理键码集合，来源是输入管理器本帧消费的按下事件，可能包含未绑定轨道的键（用 keyToLane 过滤）。只读：宿主在构造期做防御性拷贝，模组 add / clear 立即抛 UnsupportedOperationException。

示例：

for (Integer key : state.pressedKeys()) {
    int lane = state.keyToLane(key);
}

heldKeys()

签名：

行为：当前按住、且在键位表中已绑定的物理键集合（宿主只轮询 keyToLane 中的键）。只读集合。

示例：

boolean holding = !state.heldKeys().isEmpty();

releasedKeys()

签名：

行为：本帧松开的物理键集合，按「上一帧按住 − 本帧按住」差分得到，因此只包含已绑定键。只读集合。

示例：

if (!state.releasedKeys().isEmpty()) { /* 松手反馈 */ }

keyToLane(int keyCode)

签名：

int keyToLane(int keyCode);

行为：查询物理键到逻辑轨道的映射（来自玩家键位设置）。未绑定到任何轨道的键返回 -1。映射为物理映射，不套用镜像类模式的轨道翻转，模组按需自行处理。

示例：

int lane = state.keyToLane(keyCode);
if (lane >= 0) {
    // 该键已绑定到轨道 lane
}

完整签名

public interface JudgeInputState {

    java.util.Set<Integer> pressedKeys();

    java.util.Set<Integer> heldKeys();

    java.util.Set<Integer> releasedKeys();

    int keyToLane(int keyCode);
}

线程：源码未声明额外线程约束；宿主在游玩更新线程每帧构造并同步传入。快照只在该帧回调内有效，不要跨帧持有。

生命周期阶段：运行期每帧判定回调（onJudgeTick）内使用。

稳定性：2.0 起冻结：2.x 内只增不破（禁止删签名/改签名/改语义）。