# 从零制作可发布的互动剧情

这是之前逐步教学的书面版本。每一步给出操作、验收和建议回复；可以自己完成，也可以让 Codex 每次只带着做一步。示例复用第一集素材来验证功能，正式剧情应替换为对应镜头与 UI 图片。

从编辑器 0.3.5 起，可以直接点击页头“教程 ↗”或左下角“?”打开内置教程中心。教程在新页面中显示，支持全文搜索、步骤定位及 Markdown/Skill 源文件下载；本地默认地址为 `http://127.0.0.1:8790/help/index.html`，服务器部署时使用编辑器所在站点的同一路径。文档快照随编辑器发行包提供，不要求服务能读取本 Git 仓库。

## 开始之前

需要 STORY STUDIO 0.3.4、Python 3.10+、一个可写的章节仓库，以及可使用的第一集素材。内置浏览器当前地址为 `http://127.0.0.1:8790/`。换到另一台机器时先启动自己的编辑器服务；这个 localhost 地址只代表本机。

编辑器源码与本仓库相邻时，可在二者的父目录运行：

```powershell
./story-editor/start.ps1 -Workspace ./story-chapters -Port 8790
```

或在已解压的编辑器目录中运行：

```sh
python server.py --port 8790
```

0.4 起服务器只提供静态网页。进入“章节库”选择本机仓库根目录（含 story.repository.json 与 chapters/），或使用浏览器章节库后逐章导入。目录模式写访问者本机，浏览器模式写 IndexedDB；两者均不向编辑器服务器上传。跨章练习须导入关联的所有章节。

## 学习路径

| 篇目 | 内容 | 完成结果 |
| --- | --- | --- |
| [第一篇](tutorials/01-basics.md) B01–B12 | 空工程、素材、节点、两条分支、图片按钮、时机、广告、导出导入 | 一章可玩的分支剧情和独立工程副本 |
| [第二篇](tutorials/02-actions-and-memories.md) A01–A18 | 动作成功失败、重试、奖励、同章回忆、提示、跨章回放 | 主线章节与回忆录章节相互配合 |
| [第三篇](tutorials/03-publishing.md) P01–P07 | 封面、依赖打包、配置合并、手工上传、客户端验收 | 可交付的多章客户端剧情包 |
| [Skill 使用教程](skills-guide.md) | 安装、调用、续课、维护 | 其他成员也能使用同样的教学和交付流程 |

每步完成后再向下一步推进。没有通过验收时先定位当前问题，不要通过叠加新节点掩盖旧配置。

## 本次重新学习的命名

| 用途 | 新练习建议 | 此前教程中的实际工程 |
| --- | --- | --- |
| 基础章节 | `tutorial-001` | `chapter-001` |
| 工程副本及进阶练习 | `tutorial-001-copy` | `chapter-001-restore-test` |
| 独立回忆录 | `tutorial-album` | `memory-album` |
| 共享解锁变量 | `practice_memory_1` | `practice_memory_1` |
| 积分变量 | `练习积分` | `练习积分` |

目录、章节 ID、工程 ID 是不同概念。新建时目录名会作为初始章节 ID，工程 ID 自动生成；同一仓库不能重复章节 ID。重学若这些目录已存在，换一个后缀，并在后续跨章配置中始终使用实际创建的章节。

`practice_memory_1` 用来有意共享奖励和回忆状态；若同时做多套独立练习，可把整套练习统一换成 `tutorial2_memory_1` 等新名称。不要只改奖励一端，漏改回忆登记或卡片。

## 编辑器的三个概念

- **章节工程**：固定目录及素材，可继续编辑、进 Git，不能直接当游戏配置发布。
- **客户端剧情包**：编译后的配置和媒体，给游戏读取；不支持作为目录工程直接导入编辑器。
- **预览状态**：当前浏览器里的奖励、回忆等试走变量。重新试走不会清空；与线上游戏存档独立。

界面默认深色，页头太阳/月亮按钮切换主题。节点、画布、属性始终三列，拖动分隔线调整宽度、双击恢复；窗口过窄时从工作区底部横向滚动。主题与列宽不会写入剧情工程。

## 继续上次学习

复制 [学习记录模板](learning-record.md) 到自己的笔记或 `.studio/tutorial-progress.md`，记录实际目录、最后通过的步骤和问题。`.studio/` 已被 Git 忽略；要把记录共享给团队，可另存到 `docs/learning-records/` 并明确提交。

向 Codex 提供“已完成 A08，主线工程是 tutorial-001-copy，现在教 A09”，比只说“继续”更容易准确续课。单句验收回复也可使用，但需要保留对应对话上下文。

## 文档依据与范围

本教程对照当前的 `src/web/app.js`、`workflows.js`、`behaviors.js`、`src/repository.py` 和三个现有练习工程编写。客户端封面路径特例及动作失败时机已纳入正文；未把网页预览通过等同于真实广告或线上客户端验收通过。

之前的编辑器源码位于相邻 `story-editor/src/`；发行包也包含 `src/`，故安装版可核对同名文件。skills 内另附精简协议说明，不依赖固定盘符或此对话。