扩展是项目中可复用的功能与界面容器。它既可以只包含可视化 UI，也可以包含 TypeScript 程序，或者把两者组合起来。 这意味着制作自定义标题页、设置菜单和 HUD 时，不必先学习 React；只有在需要复杂计算、小游戏、外部服务或自定义剧本逻辑时，才需要初始化程序。

​
三种形态

形态包含内容适合场景
纯界面扩展extension.json + ui/标题页、菜单、HUD、弹窗和系统界面皮肤
程序扩展TypeScript、SDK 和构建产物剧本方法、复杂动态 UI、小游戏和服务接入
混合扩展可视化 UI + TypeScript 控制器用编辑器排版，再由代码补充动态行为
Studio 新建扩展时默认从纯界面形态开始。之后可以随时「初始化程序」，原有可视化界面不会丢失。

​
扩展能做什么

能力说明典型用途
可视化界面用 27 种元素搭建 UI，不需要构建程序标题、存读档、设置、菜单、HUD
程序 UI通过 Extension 的 render() 渲染 React 组件小游戏、Canvas、复杂动态界面
剧本方法提供可在剧本中调用的逻辑发放奖励、解锁内容、调用外部服务
章节调度策略为高级调度选择下一章或结束流程地图选点、日程、回合和周目结构
设置与存档声明项目设置和随存档持久化的数据背包、成就、周目和解锁记录
系统接管替换系统插槽或内置对话组件完整游戏壳、特殊对话交互
程序能力通过同一个 Extension 基类声明。一个扩展可以导出多个子模块，也可以让程序通过 ctx.visualUI控制可视化界面。

​
默认游戏壳

Studio 自带不能卸载的「默认游戏壳」扩展（avg.internal.default-shell），提供：
  • 标题画面；
  • 存档和读档；
  • 设置；
  • 历史记录与语音重放；
  • CG、音乐和剧情片段鉴赏；
  • 剧情选项和玩家输入界面；
  • 游戏工具栏、输入对话框和消息框。
它保证每个项目开箱即可运行。默认游戏壳的主要界面也是可视化 UI，可以在当前项目中生成可编辑副本，或者绑定到你自己的界面。详见默认游戏壳与系统界面。 需要让扩展决定高级调度的下一章时，使用 scheduleStrategy()。

​
程序扩展的技术栈

只有初始化程序后，扩展才会加入以下工具链：
  • TypeScript：扩展源码；
  • React：程序 UI；
  • Vite：以 ESM 库模式构建；
  • @avg-studio/sdk：Extension 基类、运行时 API 和类型定义。
Studio 会生成配置和 SDK 本地副本。安装依赖后，使用 npm run build 单次构建，或使用 npm run watch 持续监听。

​
从哪条路开始

只做界面

新建扩展后直接创建 UI，不需要 npm 和代码。

编写程序

初始化 TypeScript 工程，开发方法、逻辑或 React UI。

混合控制

给可视化元素设置引用名，再由程序动态控制。

替换系统界面

把标题、存读档等位置绑定到自己的实现。