交互式电影游戏引擎

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

快速开始

git clone <repo-url> mygame
cd mygame
npm install
npm run dev

打开 http://localhost:5173/，你会看到示例剧情。

制作你的游戏

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。

2. 编写剧情 JSON

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

{
  "startScene": "intro",
  "variables": { "trust": 50 },
  "scenes": {
    "intro": {
      "id": "intro",
      "videoUrl": "/videos/intro.mp4",
      "choices": [
        { "text": "帮助他", "targetScene": "help_end" },
        { "text": "离开", "targetScene": "leave_end" }
      ]
    },
    "help_end": {
      "id": "help_end",
      "videoUrl": "/videos/help.mp4",
      "choices": []
    },
    "leave_end": {
      "id": "leave_end",
      "videoUrl": "/videos/leave.mp4",
      "choices": []
    }
  }
}

完整字段参考见 docs/SCENE_JSON_SPEC.md。

3. 实时预览

npm run dev

Vite 会启动热重载服务器，修改 JSON 或视频后自动刷新。

4. 可视化编辑剧情

浏览器打开 http://localhost:5173/editor/，可以用节点图编辑器拖拽编辑场景分支。

打包发布

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 合法性。

引擎功能

功能	说明
视频分支播放	A/B 双缓冲无缝切换，300ms 交叉淡化
选择系统	限时选择、条件分支（根据变量显示/隐藏选项）
QTE 快速反应事件	视频中插入限时按键挑战，成功/失败跳转不同场景
图片/视频热点	点击画面区域触发分支，视频热点按时间轴显隐
循环等待	视频结束后自动循环指定片段，保持画面动态
独立 BGM	背景音乐独立驱动，场景切换时交叉淡化，不受画面循环影响
BGM Ducking	选择/QTE/热点出现时 BGM 自动降低音量
字幕系统	WebVTT 解析，多语言字幕切换
章节系统	分章节管理剧情，到达即解锁，可跳转
成就系统	变量满足条件时自动解锁，底部弹窗提示
结局画廊	所有结局缩略图展示，已解锁/未解锁状态
章节回顾	每章完成度百分比 + 未解锁分支条件提示
关键选择提示	重要选项前置金色标识 + 选后浮现提示文字
跳过已看 + 倍速	已看场景可跳过，1x/2x/4x 倍速播放
全屏模式	一键全屏沉浸式浏览器体验
键盘导航	方向键选选项，Esc 菜单，Space 暂停
多语言 i18n	UI + 字幕支持中英文切换
可访问性	字幕字号/背景、QTE 时限放宽/按键简化、防误触延迟
存档系统	IndexedDB 多槽位，跨会话持久化

目录结构

mygame/
├── engine/                     # 引擎核心（纯 TS，不依赖 Vue）
│   ├── core/                   # Engine / VideoManager / StateManager / SceneManager
│   ├── systems/                # QTE / Choice / Audio / Achievement / Save
│   └── types.ts                # 类型定义
├── src/                        # Vue UI 层
│   ├── components/             # 所有界面组件
│   ├── composables/            # 引擎 ↔ UI 桥接
│   ├── stores/                 # Pinia 状态管理
│   └── locales/                # 翻译文件（zh.json / en.json）
├── editor/                     # 可视化剧情编辑器
├── electron/                   # 桌面应用打包（Electron）
├── public/                     # 你的素材
│   ├── videos/                 # 视频文件（.mp4）
│   ├── audio/                  # 背景音乐（.mp3）
│   ├── images/                 # 缩略图
│   ├── subtitles/              # 字幕（.vtt）
│   └── scenes/demo.json        # 剧情定义
├── docs/                       # 文档
│   └── SCENE_JSON_SPEC.md      # JSON 完整字段参考
├── scripts/                    # 打包脚本
└── ROADMAP.md                  # 开发路线图

视频制作建议

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

命令参考

npm run dev            # 启动开发服务器（实时预览）
npm run build          # 构建生产版本
npm run preview        # 预览构建结果
npm run pack:html      # 打包 Web 版
npm run pack:mac       # 打包 macOS 桌面应用
npm run pack:win       # 打包 Windows 桌面应用