# 交互式电影游戏引擎

基于 Vue 3 + TypeScript 的浏览器端交互式电影游戏引擎。
克隆项目 → 放视频 → 写 JSON → 打包上线。

## 快速开始

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

浏览器打开 `http://localhost:5173/` 预览示例游戏。
打开 `http://localhost:5173/editor/` 使用可视化编辑器。

## 制作你的游戏

### 1. 放视频

把你的视频文件放到 `public/videos/` 目录。推荐 MP4 (H.264)，1280×720，2-5Mbps。

### 2. 编写剧情 JSON

编辑 `public/scenes/demo.json`（或创建新 JSON 文件，修改 `src/App.vue` 中的加载路径）。

```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": [] }
  }
}
```

这 15 行 JSON 就是一个完整可玩游戏。

### 3. 完整字段参考

详见 [场景 JSON 规范文档](docs/SCENE_JSON_SPEC.md)。引擎支持：

- 分支叙事 / 条件分支 / QTE 快速反应事件 / 循环等待
- 独立 BGM + Ducking / 跳过已看 + 倍速 / 章节选择
- 成就系统 / 结局画廊 / 章节回顾 / 字幕多语言
- 关键选择提示 / 键盘全导航 / 可访问性设置
- 图片/视频热点交互 / 全屏模式

### 4. 预览和调试

```bash
npm run dev       # Vite 实时预览，改代码自动刷新
```

### 5. 打包上线

```bash
npm run pack:html  # Web 版 → release/mygame.zip（上传 itch.io）
npm run pack:mac   # macOS → release/MyGame-darwin-*/
npm run pack:win   # Windows → release/MyGame-win32-x64/
```

Web 版上传 itch.io 选 "HTML" 类型。桌面版为可运行文件夹，双击即用。

## 自定义 UI

引擎的 UI 组件在 `src/components/` 目录中，可自由修改 Vue 组件、CSS 样式。
引擎核心 `engine/` 目录也可修改。

## 目录结构

```
mygame/
├── engine/                      # 核心引擎（可自由修改）
├── src/                         # Vue UI 组件（可自由修改）
│   ├── components/              # GamePlayer、ChoicePanel 等
│   ├── composables/             # 桥接引擎 ↔ UI
│   ├── stores/                  # Pinia 状态
│   ├── locales/                 # 多语言翻译
│   └── App.vue                  # 入口组件
├── editor/                      # 可视化剧情编辑器
├── public/
│   ├── videos/                  # 放你的视频
│   ├── audio/                   # 放你的 BGM
│   ├── images/                  # 放缩略图、热点图
│   ├── subtitles/               # 放字幕 .vtt
│   └── scenes/
│       └── demo.json            # 你的剧情定义 ← 主要编辑这个
├── electron/                    # 桌面打包配置
├── docs/                        # JSON 规范文档
├── scripts/                     # 打包脚本
└── package.json
```

## 视频制作建议

| 参数 | 建议值 |
|------|--------|
| 格式 | MP4 (H.264) |
| 分辨率 | 1280×720 或 1920×1080 |
| 帧率 | 25fps 或 30fps |
| 码率 | 2-5 Mbps |
| 循环段 | 正文段 + 循环段合成为一个文件，用 `loopStart`/`loopEnd` 标记区间 |
| 背景音乐 | 不要在视频中嵌入 BGM，用独立 .mp3 + `bgmUrl` 字段 |
| 字幕 | WebVTT 格式（.vtt），时间轴精确到毫秒 |