LaneInputMapper

轨道输入映射器，接管「按键 → 轨道」映射。模组经 GameplayMod.createLaneInputMapper() 提供实现，把物理键映射到逻辑基础轨道（与内置 keyToLane 的 value 含义一致），之后再经游戏模式 mapLane 套用镜像等翻转。没有模组映射器时游戏沿用内置固定键位映射。

方法速览

完整签名

public interface LaneInputMapper {

    default void init(int laneCount);

    int mapKeyToLane(int keyCode);

    default int[] mapKeyToLanes(int keyCode);

    default java.util.Set<Integer> triggerKeys();
}

init(int laneCount)

签名：

void init(int laneCount);

行为：游玩开始、轨道数已知时调用一次（可缓存分区结果，如把键盘横向均分成若干区域）。单个映射器抛出的异常由宿主隔离（该映射器仍会被使用，只是未完成初始化）。默认空实现。

示例：

private int laneCount;

@Override
public void init(int laneCount) {
    this.laneCount = laneCount;
}

mapKeyToLane(int keyCode)

签名：

int mapKeyToLane(int keyCode);

行为：把物理键映射为逻辑轨道索引（0 起）。返回 -1 表示该键不触发任何轨道（宿主按「未绑定」处理，跳过判定）；keyCode 与 java.awt.event.KeyEvent.VK_* 一致。多模组场景下本方法由宿主经链式映射器转调 mapKeyToLanes，通常覆写后者即可。

示例：

@Override
public int mapKeyToLane(int keyCode) {
    if (keyCode == java.awt.event.KeyEvent.VK_A) return 0;
    if (keyCode == java.awt.event.KeyEvent.VK_S) return 1;
    return -1;
}

mapKeyToLanes(int keyCode)

签名：

int[] mapKeyToLanes(int keyCode);

行为：物理键 → 逻辑轨道集合，支持「一个键触发多条轨道」。数组中的每条轨道都会像被单独按下一样参与本帧判定：press 触发判定、按住保持 HOLD、轨道按压高亮；宿主逐轨道套用游戏模式的 mapLane（镜像等）。返回数组不得包含负值；空数组表示不触发。

默认实现回退到 mapKeyToLane 的单轨语义（-1 映射为空数组），旧实现无需修改即可继续工作。

示例：

@Override
public int[] mapKeyToLanes(int keyCode) {
    return keyCode == java.awt.event.KeyEvent.VK_SPACE ? new int[]{0, 3} : new int[0];
}

triggerKeys()

签名：

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

行为：返回本模组可能触发判定的物理键集合；宿主据此构建 heldLanes 与轨道按压高亮，每帧读取，应返回只读 / 不可变视图。默认空集。

键级路由规则：

• 每个物理键由声明管辖它的第一个映射器（按模组启用顺序）负责映射；该映射器即使返回空数组也终局，不再回退后续映射器。
• 无任何映射器声明管辖的键，按启用顺序回退询问各映射器的 mapKeyToLanes，第一个映射非空的生效；都为空即未绑定。
• 多个模组声明同一物理键时只有更早的模组生效，宿主输出一次诊断日志。
• 列表为空时游戏沿用内置固定键位。

示例：

@Override
public java.util.Set<Integer> triggerKeys() {
    return java.util.Set.of(java.awt.event.KeyEvent.VK_A, java.awt.event.KeyEvent.VK_S);
}

线程：init 在谱面加载阶段调用一次；mapKeyToLane / mapKeyToLanes / triggerKeys 在游玩热路径每帧调用，应轻量且不分配大对象。回调异常由宿主隔离（映射视为空）。

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