API 参考 / spi 包：游戏模式、谱面扩展与内容
GameModeContext
想先跑起来？
这一页是签名与行为参考。模式回调里能读到的最小状态集。直接做一遍：教程 · 添加游戏模式。
游戏模式回调上下文，在模式生命周期钩子中由宿主传入，提供模式当前可读取的最小状态集。宿主复用同一个快照实例、在每次回调前刷新，因此不要保存或在回调之外读取它。模式要改变游戏状态应经能力接口（capabilities）完成，而不是通过本上下文写状态。相关类型：GameModeDefinition。
方法速览
| 方法 | 用途 |
|---|---|
musicTimeMs() | 当前音乐时间（毫秒） |
isPaused() | 是否处于暂停 |
services() | 宿主注入的模式服务标记（通常无需消费） |
musicTimeMs()
签名：
java
long musicTimeMs();行为：返回当前音乐时间（毫秒）。宿主在每次模式回调前用最新帧状态刷新快照，同一帧的 onUpdate 参数与本方法同值。
示例：
java
long t = ctx.musicTimeMs();isPaused()
签名：
java
boolean isPaused();行为：返回当前是否处于暂停。常规游玩更新帧不会在暂停时派发，但渲染与其他回调仍可能读到 true，实现可据此跳过动画推进。
示例：
java
if (!ctx.isPaused()) {
// 推进本模式的逻辑
}services()
签名：
java
default GameModeServices services();行为：返回宿主注入的模式服务。该值仅供宿主内置模式注入使用，模组也可读：返回空标记接口 GameModeServices（spi 包），具体能力面由宿主内核侧声明（对模组类加载隔离不可见）；模组可安全做 null 判别，通常无需消费。未注入（模组自定义上下文实现 / 宿主未接入）时返回 null。默认实现返回 null。
示例：
java
GameModeServices services = ctx.services();
if (services != null) {
// 仅有身份意义：具体能力面在宿主内核侧，模组不可见
}完整签名
java
public interface GameModeContext {
long musicTimeMs();
boolean isPaused();
default GameModeServices services();
}线程：源码未声明额外线程约束；快照只在游玩主线程的回调内被刷新与读取。
生命周期阶段：运行期模式回调（onEnter / onUpdate / onHandleInput / onExit / renderOverlay）内使用。
稳定性：2.0 起冻结：2.x 内只增不破（禁止删签名/改签名/改语义）；services() 为 2.0 加性扩展（新增 default 方法 + 新标记类型，符合只增不破）。