GameplayMod

游玩模组入口接口，继承 Mod，扩展游玩阶段的能力提供钩子。所有方法默认返回 null / false（不提供），模组按需覆写。宿主在每次进入游玩场景、构造 GameplayModHost 时按启用顺序调用这些钩子，每个钩子独立 try/catch，单个钩子异常不影响其它模组。相关能力接口见 GameplayHud 与 LaneInputMapper。

方法速览

完整签名

public interface GameplayMod extends Mod {

    default boolean replacesDisorderProgressBar();

    default GameplayHud createGameplayHud();

    default LaneInputMapper createLaneInputMapper();
}

replacesDisorderProgressBar()

签名：

default boolean replacesDisorderProgressBar();

行为：返回 true 时游戏隐藏内置的无序模式进度条（充能条与剩余时间条），由模组自行渲染进度表现。宿主在构造游玩托管实例时对每个已启用 GameplayMod 调用一次并缓存结果：任一模组返回 true 即隐藏；钩子抛异常按 false 处理。运行期再改返回值不会生效（下次进入游玩才重新计算）。

示例：

@Override
public boolean replacesDisorderProgressBar() {
    return true;
}

createGameplayHud()

签名：

default GameplayHud createGameplayHud();

行为：返回一个 GameplayHud 实现以隐藏并自绘原版 HUD 组件（分数 / 连击 / 准度 / HP 条）；返回 null（默认）表示不提供。多模组叠加生效：所有返回非 null 的实例按启用顺序收集，渲染时可见性声明取「任一隐藏即隐藏」（最严格），覆盖渲染依次调用、可互相叠加。宿主还会在列表末尾追加经 ModContext.capabilities().register(GameplayHud.class, ...) 注册的实例（同类型只保留最后注册的一个）。钩子抛异常视为该模组不提供。

示例：

@Override
public GameplayHud createGameplayHud() {
    return new MyCompactHud();   // 实现 GameplayHud：控制可见性 + renderOverlay
}

createLaneInputMapper()

签名：

default LaneInputMapper createLaneInputMapper();

行为：返回一个 LaneInputMapper 实现以接管「按键 → 轨道」映射，使按键不再仅由固定快捷键绑定触发，而是按模组定义的分区规则（如把键盘横向均分成多个区域）触发对应轨道；返回 null（默认）表示不接管，游戏沿用内置固定键位映射。

多模组按键级路由叠加：游玩开始时按启用顺序逐个调用 init(laneCount)；每个物理键由声明管辖它（triggerKeys()）的第一个模组负责映射，未声明管辖键的旧实现按启用顺序回退询问（第一个 mapKeyToLanes 结果非空的生效）。同一物理键被多个模组声明管辖时，仅更早的模组生效并输出限频告警。列表为空时使用内置键位映射器。

示例：

@Override
public LaneInputMapper createLaneInputMapper() {
    return new MyTwoSideMapper();   // 实现 init / triggerKeys / mapKeyToLane / mapKeyToLanes
}

线程：钩子在游玩场景构造时调用（宿主线程）；具体能力回调的线程约束见各自页面。

稳定性：2.0 起冻结：2.x 内只增不破（禁止删签名 / 改签名 / 改语义）；破坏性变更只在 major 版本发生且须提供迁移指南与至少一个大版本的弃用期。3.x 内继续只增不破。