src/index.tsx 中。还没有程序入口时，先在扩展树中选中「程序」，点击「初始化程序」。第一次开发扩展建议先完成 Hello World。
按想做的功能选择
界面反馈与玩家操作
常驻工具栏、任务 HUD、成就通知、可视化任务面板
玩法数据与成长系统
好感度、背包、解锁作用域、提示次数
剧情流程与演出控制
一键转场、支线调用、回忆跳转、角色对话配色
系统界面与玩家设备
标题画面、快存快读、存档截图、全屏与音量
收藏、图鉴与媒体
人物图鉴、CG 鉴赏、音乐室、语音历史、剧本统计
案例与 SDK 能力
| 范例 | 最终效果 | 自然覆盖的能力 |
|---|---|---|
| 跟随对话显隐的工具栏 | 对话出现时显示，离开对话时收起 | onRegister、事件、设置、ctx.ui |
| 当前任务 HUD | 剧本更新任务，画面角落实时显示 | method()、saveSchema、变量 Hook |
| 成就解锁通知 | 新成就出现时弹出短暂提示 | shared 存档、变量 Hook、React 状态 |
| 可视化任务面板 | 布局在编辑器中制作，代码注入动态内容 | ctx.visualUI、元素引用、清理 |
| 好感度里程碑 | 达到阈值后只记录一次里程碑 | 方法、角色参数、设置、slot 存档 |
| 可增减的背包 | 发放、消耗物品并保持数据不可变更新 | 多方法、列表存档、文本候选 |
| 可切换的解锁范围 | 作者决定解锁跟随存档还是跨周目 | 设置、slot/shared 双作用域 |
| 调查提示次数 | 作者配置上限，玩家消耗次数 | 设置与存档的职责边界 |
| 一键完成转场演出 | 黑场、换景、立绘、音乐、镜头连续执行 | 幕布、场景、角色、声音、镜头 |
| 可返回的支线剧情 | 支线结束后回到原剧本继续播放 | ctx.flow.callFragment |
| 回忆录跳转 | 放弃当前流程并从已解锁片段重放 | unsafe_goToFragment、shared 存档 |
| 角色专属名字颜色 | 每句对话按角色代表色改变名字牌 | ctx.dialogue.useStyle、角色数据 |
| 自定义标题画面 | 替换标题并调用读档、设置等入口 | 系统插槽、ctx.system、ctx.game |
| 可改键的快存快读 | F5/F9 默认，玩家可以重新映射 | 语义动作、ctx.archive |
| 打开存档页前截图 | 缩略图不被存档界面本身遮挡 | onInit、onClose、截图缓存 |
| 玩家控制中心 | 调整音量、跳过策略和全屏 | ctx.config、ctx.game.window |
| 人物图鉴 | 已遇见角色显示档案，其他角色显示剪影 | ctx.character、shared 存档 |
| CG 鉴赏预览 | 在弹窗中渲染收藏场景，不改变主舞台 | ctx.sceneRender、资源图层、清理 |
| 音乐室 | 解锁曲目并在界面中试听 | 素材参数、ctx.asset、ctx.sound |
| 可重放语音的历史页 | 展示已播放台词并重放语音 | ctx.history、响应式快照 |
| 全剧本台词统计 | 按章节统计项目中的全部对话 | ctx.story、异步按需加载 |
阅读约定
- 每个范例的代码只保留核心组合，通用样式和错误提示会适当省略。
- 示例中的
manifest.id来自扩展根目录的extension.json，不要把随机生成的完整扩展 id 写死。 - 存档列表按只读数据处理，使用新数组整体
set，不要原地push或splice。 - React 组件中使用 Hook；注册阶段和剧本方法中使用命令式 API。
- API 类型以当前扩展目录中的
sdk/为准。Studio 版本较旧时，部分新范例可能需要提高sdkVersion。