三种形态
| 形态 | 包含内容 | 适合场景 |
|---|---|---|
| 纯界面扩展 | extension.json + ui/ | 标题页、菜单、HUD、弹窗和系统界面皮肤 |
| 程序扩展 | TypeScript、SDK 和构建产物 | 剧本方法、复杂动态 UI、小游戏和服务接入 |
| 混合扩展 | 可视化 UI + TypeScript 控制器 | 用编辑器排版，再由代码补充动态行为 |
扩展能做什么
| 能力 | 说明 | 典型用途 |
|---|---|---|
| 可视化界面 | 用 27 种元素搭建 UI，不需要构建程序 | 标题、存读档、设置、菜单、HUD |
| 程序 UI | 通过 Extension 的 render() 渲染 React 组件 | 小游戏、Canvas、复杂动态界面 |
| 剧本方法 | 提供可在剧本中调用的逻辑 | 发放奖励、解锁内容、调用外部服务 |
| 章节调度策略 | 为高级调度选择下一章或结束流程 | 地图选点、日程、回合和周目结构 |
| 设置与存档 | 声明项目设置和随存档持久化的数据 | 背包、成就、周目和解锁记录 |
| 项目数据 | 声明数据集合依赖，通过 ctx.database 共用结构化数据 | 道具目录、图鉴、任务与数值表 |
| 系统接管 | 替换系统插槽或内置对话组件 | 完整游戏壳、特殊对话交互 |
Extension 基类声明。一个扩展可以导出多个子模块，也可以让程序通过 ctx.visualUI控制可视化界面，或通过项目数据库 API使用项目绑定的数据集合。
默认游戏壳
Studio 自带不能卸载的「默认游戏壳」扩展（avg.internal.default-shell），提供：
- 标题画面；
- 存档和读档；
- 设置；
- 历史记录与语音重放；
- CG、音乐和剧情片段鉴赏；
- 剧情选项和玩家输入界面；
- 游戏工具栏、输入对话框和消息框。
scheduleStrategy()。
程序扩展的技术栈
只有初始化程序后，扩展才会加入以下工具链：- TypeScript：扩展源码；
- React：程序 UI；
- Vite：以 ESM 库模式构建；
- @avg-studio/sdk：Extension 基类、运行时 API 和类型定义。
npm run build 单次构建，或使用 npm run watch 持续监听。
从哪条路开始
只做界面
新建扩展后直接创建 UI，不需要 npm 和代码。
编写程序
初始化 TypeScript 工程，开发方法、逻辑或 React UI。
混合控制
给可视化元素设置引用名，再由程序动态控制。
替换系统界面
把标题、存读档等位置绑定到自己的实现。