ctx.performance 让扩展感知演出段：一段用开始标记和结束标记框住、按时间轴自动播放的内容。演出进行中玩家不能推进剧情；打开菜单、窗口最小化或 Steam 浮层弹出时，整段暂停。
扩展通常用它做这几件事：
- 演出开始时收起挡画面的浮层，结束后再显示；
- 演出暂停时，同步暂停自己的计时或动画；
- 避免在演出中调用会等待玩家或跳转剧情的功能。
API
| 方法 | 返回值 | 说明 |
|---|
isActive() | boolean | 当前是否有演出段正在播放，暂停中也算 |
isPaused() | boolean | 当前演出是否暂停，不在演出中时返回 false |
getInfo() | PerformanceSegmentInfo | null | 当前演出段的快照，不在演出中时返回 null |
onChange(listener) | 取消订阅函数 | 订阅演出的开始、结束、暂停和恢复 |
| 字段 | 说明 |
|---|
id | 演出段 id，也就是开始标记的块 id |
name | 开始标记上填写的演出名，没有名字时不含这个字段 |
time | 已经播放到的段内时间（毫秒），暂停期间不前进 |
duration | 演出总长度（毫秒） |
paused | 读取时演出是否暂停 |
onChange 事件
回调收到 { type, id }，其中 id 是演出段 id：
type | 触发时机 |
|---|
start | 演出开始播放 |
end | 演出结束：正常播完、玩家快进跳过，以及被读档等操作打断都会发出 |
pause | 因菜单、窗口最小化、Steam 浮层等原因暂停 |
resume | 从暂停恢复 |
- 只通知订阅之后发生的变化。订阅时需要当前状态，先调用
isActive()。
- 回调同步执行，不要在里面做耗时操作。
- 界面或功能提前停用时，调用返回的函数取消订阅。
案例：演出时收起状态栏
输入： 扩展有一个常驻 HUD status-hud，剧本进入演出段「开场」。
@extension({ id: "status-hud", label: "状态栏", autonomous: true })
export class StatusHud extends Extension {
static onRegister(ctx: ExtensionContext) {
ctx.performance.onChange((event) => {
if (event.type === "start") void ctx.ui.hide("status-hud");
if (event.type === "end") void ctx.ui.show("status-hud");
});
}
}
案例：读取演出进度
const info = ctx.performance.getInfo();
console.log(info && {
name: info.name,
progress: info.time / info.duration,
paused: info.paused,
});
{ "name": "开场", "progress": 0.42, "paused": false }；不在演出中时输出 null。
声明方法可在演出中使用
剧本方法可以放进演出段里调用，但如果它会等待玩家或跳转剧情，演出可能无法正常进行。方法很快执行完、不等待玩家操作（不打开需要玩家关闭的界面、不等点击），也不改变剧情流程时，声明 performanceSafe: true：
static flashBadge = this.method({
title: "闪一下徽章",
performanceSafe: true,
run(ctx) {
// 只更新自己的界面状态，立即返回
},
});
BlockExtension 在类上声明 static performanceSafe = true。
演出中的限制
| 调用 | 演出段进行中的行为 |
|---|
ctx.flow.callFragment() | 被拒绝：控制台告警，不调用片段，Promise 直接正常结束，不抛错 |
ctx.flow.unsafe_goToFragment() | 被拒绝：控制台告警，当前流程保持不变 |
ctx.dialogue.hideBox() | 不生效 |
ctx.flow.restart() | 允许 |
使用这组接口需要新版 SDK。老扩展先在程序开发界面「同步 SDK」，并把 extension.json 的 sdkVersion 声明为 >=3.0.0。需要兼容旧版 Studio 时，用 ctx.performance?.isActive() 这类可选链读取。
