ExtensionContext（下文简称 ctx）是扩展与引擎交互的统一入口。运行时接口按用途拆分在 ctx.flow、ctx.variables、ctx.scene 等命名空间下，每个命名空间都有独立页面和带输入、输出的完整案例。

​
获取 ctx

​
React UI

在 React 组件中使用 useExtensionContext()： 
import { useExtensionContext } from "@avg-studio/sdk";

export function StatusPanel() {
  const ctx = useExtensionContext();
  const [affection] = ctx.variables.useValue<number>("affection");

  return <span>好感度：{affection ?? 0}</span>;
}

​
剧本方法

方法的 run() 会把 ctx 作为第一个参数传入： 
static run(ctx, params: { amount: number }) {
  const current = ctx.variables.get<number>("gold") ?? 0;
  ctx.variables.set("gold", current + params.amount);
}

​
注册阶段

自主扩展可以在 static onRegister(ctx) 中注册事件、输入动作或界面控制器： 
static onRegister(ctx) {
  ctx.input.registerAction({
    id: "my.extension.open-panel",
    label: "打开面板",
    defaultKeys: ["KeyM"],
  });
}

​
接口索引

分类入口用途
流程控制ctx.flow跳转片段、重新开始
剧本读取ctx.story读取章节目录、单章或完整剧本
变量ctx.variables读写并订阅剧本变量
场景ctx.scene切换、显示与销毁场景
角色ctx.character查询角色并控制立绘
对话ctx.dialogue读取对话、选项和播放状态
音频ctx.sound播放、暂停和停止音频
摄像机ctx.camera平移、缩放、震动和复位
幕布ctx.curtain控制幕布与淡入淡出
存档ctx.archive存档、读档和档案数据
历史记录ctx.history读取对话与选择历史
引擎配置ctx.config读写音量、文字速度等玩家配置
程序 UIctx.ui显示和隐藏 React 程序 UI
可视化界面ctx.visualUI打开并控制编辑器产物界面
游戏壳层ctx.game读取作品信息、退出和全屏
系统插槽ctx.system调用标题、对话工具栏、存读档、设置等系统入口
输入管理ctx.input注册动作和绑定快捷键
扩展设置ctx.settings读写当前扩展的项目级设置
素材ctx.asset把素材 URI 解析为可访问 URL
场景渲染ctx.sceneRender在扩展容器中隔离渲染场景
事件订阅ctx.subscribe监听引擎状态变化
宿主对象ctx.getHost访问不稳定的宿主内部对象

​
快速案例

输入： 项目中已经存在数值变量 gold，当前值为 10；方法收到 { amount: 5 }。 
static run(ctx, params: { amount: number }) {
  const before = ctx.variables.get<number>("gold") ?? 0;
  ctx.variables.set("gold", before + params.amount);
  return ctx.variables.get<number>("gold");
}
输出： 方法返回 15，变量 gold 的运行时值也变为 15。订阅了该变量的 React 组件会自动重新渲染。

​
通用约定

  • use... 开头的方法是 React Hook，只能在 React 组件或自定义 Hook 顶层调用。
  • 返回 Promise 的方法建议使用 await，需要避免阻塞时可以显式写成 void ctx.xxx()。
  • ctx.settings、ctx.ui 等接口会绑定到当前扩展作用域；通常只需使用模块内的短 id。
  • 方法签名中的 void | Promise<void> 表示不同宿主可以同步或异步完成操作；不要依赖其具体实现方式。