docs: reorganize docs into guide/ and electron/, add 6 new guide docs, update README

2026-06-10 17:01:48 +08:00
parent 99f80147c7
commit 686b1b45ea
11 changed files with 950 additions and 75 deletions
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # 交互式电影游戏引擎

 基于 Vue 3 + TypeScript 的浏览器端交互式电影游戏引擎。
-**零代码门槛**：你只需要会剪视频和写 JSON，不需要前端知识。
+**零代码门槛**：你只需要会剪视频和写 JSON。

 ## 快速开始

@@ -12,33 +12,35 @@ npm install
 npm run dev
 ```

-打开 `http://localhost:5173/`，你会看到示例剧情。
+打开 `http://localhost:5173/` 看示例剧情。
+打开 `http://localhost:5173/editor/` 使用可视化剧情编辑器。

 ## 制作你的游戏

 ### 1. 准备素材

-| 素材 | 目录 | 格式要求 |
-|------|------|---------|
-| 视频文件 | `public/videos/` | MP4 (H.264)，1280×720，30fps，2-5Mbps |
-| 背景音乐 | `public/audio/` | MP3 |
-| 缩略图 | `public/images/` | JPG/PNG，320×180 |
-| 字幕 | `public/subtitles/` | WebVTT (.vtt) |
+按场景组织素材，每个场景一个文件夹：

-> `public/videos/` 已在 `.gitignore` 中，视频文件不需要提交到 Git。
+```
+public/my_story/
+  scene_1/video.mp4      ← 视频文件 (MP4 H.264, 1280×720)
+  scene_2/video.mp4
+  shared/bgm.mp3         ← 跨场景共享素材
+```

-### 2. 编写剧情 JSON
+### 2. 写剧情 JSON

-编辑 `public/scenes/demo.json`，定义你的场景和分支。**最小可玩示例只需 20 行 JSON**：
+创建 `public/scenes/my_story.json`：

 ```json
 {
-  "startScene": "intro",
+  "assetBase": "my_story/",
+  "startScene": "scene_1",
  "variables": { "trust": 50 },
  "scenes": {
-    "intro": {
-      "id": "intro",
-      "videoUrl": "/videos/intro.mp4",
+    "scene_1": {
+      "id": "scene_1",
+      "videoUrl": "scene_1/video.mp4",
      "choices": [
        { "text": "帮助他", "targetScene": "help_end" },
        { "text": "离开", "targetScene": "leave_end" }
@@ -46,105 +48,100 @@ npm run dev
    },
    "help_end": {
      "id": "help_end",
-      "videoUrl": "/videos/help.mp4",
+      "videoUrl": "scene_2/video.mp4",
      "choices": []
    },
    "leave_end": {
      "id": "leave_end",
-      "videoUrl": "/videos/leave.mp4",
+      "videoUrl": "shared/video.mp4",
      "choices": []
    }
  }
 }
 ```

-完整字段参考见 **[docs/SCENE_JSON_SPEC.md](docs/SCENE_JSON_SPEC.md)**。
-
-### 3. 实时预览
+### 3. 运行

 ```bash
 npm run dev
 ```

-Vite 会启动热重载服务器，修改 JSON 或视频后自动刷新。
-
-### 4. 可视化编辑剧情
-
-浏览器打开 `http://localhost:5173/editor/`，可以用节点图编辑器拖拽编辑场景分支。
-
-## 打包发布
-
-```bash
-npm run pack:html    # Web 版 → release/mygame.zip  → 上传 itch.io / Netlify
-npm run pack:mac     # macOS → release/MyGame-darwin-arm64/
-npm run pack:win     # Windows → release/MyGame-win32-x64/
-```
-
-打包前会自动验证 JSON 合法性。
+浏览器打开 `http://localhost:5173/?scene=my_story.json`。

 ## 引擎功能

 | 功能 | 说明 |
 |------|------|
 | 视频分支播放 | A/B 双缓冲无缝切换，300ms 交叉淡化 |
-| 选择系统 | 限时选择、条件分支（根据变量显示/隐藏选项） |
-| QTE 快速反应事件 | 视频中插入限时按键挑战，成功/失败跳转不同场景 |
-| 图片/视频热点 | 点击画面区域触发分支，视频热点按时间轴显隐 |
-| 循环等待 | 视频结束后自动循环指定片段，保持画面动态 |
-| 独立 BGM | 背景音乐独立驱动，场景切换时交叉淡化，不受画面循环影响 |
-| BGM Ducking | 选择/QTE/热点出现时 BGM 自动降低音量 |
-| 字幕系统 | WebVTT 解析，多语言字幕切换 |
-| 章节系统 | 分章节管理剧情，到达即解锁，可跳转 |
-| 成就系统 | 变量满足条件时自动解锁，底部弹窗提示 |
-| 结局画廊 | 所有结局缩略图展示，已解锁/未解锁状态 |
-| 章节回顾 | 每章完成度百分比 + 未解锁分支条件提示 |
-| 关键选择提示 | 重要选项前置金色标识 + 选后浮现提示文字 |
-| 跳过已看 + 倍速 | 已看场景可跳过，1x/2x/4x 倍速播放 |
-| 全屏模式 | 一键全屏沉浸式浏览器体验 |
-| 键盘导航 | 方向键选选项，Esc 菜单，Space 暂停 |
-| 多语言 i18n | UI + 字幕支持中英文切换 |
-| 可访问性 | 字幕字号/背景、QTE 时限放宽/按键简化、防误触延迟 |
+| 选择系统 | 限时选择、条件分支（根据变量显示/隐藏） |
+| 选择提示 (Prompt) | 重要选项前置金色标识 + 选后浮现提示文字 |
+| QTE 快速反应事件 | 视频中限时按键挑战，成功/失败导向不同分支 |
+| 图片/视频热点 | 像素级精准定位，视频热点按时间显隐 |
+| 循环等待 | 指定片段反复播放直到玩家做选择 |
+| 独立 BGM | 背景音乐独立轨道，场景切换交叉淡化 |
+| BGM Ducking | 选择/QTE/热点出现时 BGM 自动压低 |
+| 字幕系统 | WebVTT 解析，多语言字幕一键切换 |
+| 多语言 i18n | UI + 数据层双语体系，支持动态扩展语言 |
+| 章节系统 | 分章节管理，到达即解锁 |
+| 成就系统 | 条件触发自动解锁，底部 Toast 弹窗 |
+| 故事进度总览 | 章节完成度 + 结局解锁状态 + 条件提示 |
 | 存档系统 | IndexedDB 多槽位，跨会话持久化 |
+| 开场视频 + 菜单背景 | 电影级启动流程 |
+| 暂停菜单 | Esc 呼出暂停面板：继续/存档/设置/主菜单 |
+| 可访问性 | 字幕字号/背景、QTE 时限放宽/按键简化、防误触 |
+| 跳过/倍速 | 已看场景可跳过，1x/2x/4x 倍速 |
+| 全屏模式 | 一键全屏沉浸式体验 |
+| 键盘导航 | 方向键选选项，Esc 暂停/菜单，P 暂停 |
+| 自动隐藏 UI | 3s 无操作隐藏顶栏和光标 |
+| Electron 打包 | macOS / Windows 桌面应用 |
+
+## 文档索引
+
+| 文档 | 内容 | 适合 |
+|------|------|------|
+| [**快速开始**](docs/guide/QUICK_START.md) | 5 分钟做一个游戏 | 新手 |
+| [**JSON 字段参考**](docs/guide/SCENE_JSON_SPEC.md) | 全部字段 + 类型说明 | 必读 |
+| [**分支叙事**](docs/guide/BRANCHING.md) | 选项/条件/变量/效果/Prompt | 进阶 |
+| [**交互指南**](docs/guide/INTERACTIONS.md) | QTE / Hotspot / Loop | 进阶 |
+| [**国际化**](docs/guide/I18N.md) | 多语言 UI + 数据层 | 进阶 |
+| [**打包发布**](docs/guide/PUBLISHING.md) | Web + macOS + Windows | 分发 |
+| [**编辑器**](editor/README.md) | 可视化剧情编辑 | 可选 |
+| [**开发路线图**](ROADMAP.md) | 已实现/待实现功能 | 参考 |

 ## 目录结构

 ```
 mygame/
 ├── engine/                     # 引擎核心（纯 TS，不依赖 Vue）
-│   ├── core/                   # Engine / VideoManager / StateManager / SceneManager
+│   ├── core/                   # Engine / VideoManager / SceneManager
 │   ├── systems/                # QTE / Choice / Audio / Achievement / Save
-│   └── types.ts                # 类型定义
+│   └── types.ts
 ├── src/                        # Vue UI 层
 │   ├── components/             # 所有界面组件
 │   ├── composables/            # 引擎 ↔ UI 桥接
-│   ├── stores/                 # Pinia 状态管理
-│   └── locales/                # 翻译文件（zh.json / en.json）
+│   ├── stores/                 # Pinia 状态
+│   └── locales/                # UI 翻译（开发者维护）
 ├── editor/                     # 可视化剧情编辑器
-├── electron/                   # 桌面应用打包（Electron）
-├── public/                     # 你的素材
-│   ├── videos/                 # 视频文件（.mp4）
-│   ├── audio/                  # 背景音乐（.mp3）
-│   ├── images/                 # 缩略图
-│   ├── subtitles/              # 字幕（.vtt）
-│   └── scenes/demo.json        # 剧情定义
+├── electron/                   # Electron 桌面打包
+├── public/                     # 你的素材（唯一需要编辑的目录）
+│   ├── demo/                   # 示例数据（参考用）
+│   │   ├── scenes/demo.json
+│   │   └── locales/{zh,en,ja}.json
+│   ├── your_story/             # 你的游戏
+│   │   ├── scene_1/video.mp4
+│   │   └── locales/zh.json
+│   └── scenes/config.json      # 默认加载哪个 JSON
 ├── docs/                       # 文档
-│   └── SCENE_JSON_SPEC.md      # JSON 完整字段参考
+│   ├── guide/                  # 游戏制作引导
+│   └── electron/               # 打包配置
 ├── scripts/                    # 打包脚本
-└── ROADMAP.md                  # 开发路线图
+└── ROADMAP.md
 ```

-## 视频制作建议
-
-| 参数 | 建议值 |
-|------|--------|
-| 视频不包含 BGM | 背景音乐用独立 .mp3 文件 + `bgmUrl` 字段，画面循环时 BGM 不中断 |
-| 循环片段 | 正文段 + 循环段合成为一个文件，用 `loopStart`/`loopEnd` 标记 |
-| 字幕 | WebVTT 格式，时间轴精确到毫秒 |
-
-## 命令参考
+## 命令

 ```bash
-npm run dev            # 启动开发服务器（实时预览）
+npm run dev            # 启动开发服务器
 npm run build          # 构建生产版本
 npm run preview        # 预览构建结果
 npm run pack:html      # 打包 Web 版