154 lines
5.4 KiB
Markdown
154 lines
5.4 KiB
Markdown
# <img src="public/logo.svg" alt="天书" height="36" style="vertical-align: middle"> 天书 TianShu
|
||
|
||
> 天书不晦，落笔成途。
|
||
> *剧本由你执笔，命运自有分岔。*
|
||
|
||
基于 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/my_story/
|
||
scene_1/video.mp4 ← 视频文件 (MP4 H.264, 1280×720)
|
||
scene_2/video.mp4
|
||
shared/bgm.mp3 ← 跨场景共享素材
|
||
```
|
||
|
||
### 2. 写剧情 JSON
|
||
|
||
创建 `public/scenes/my_story.json`：
|
||
|
||
```json
|
||
{
|
||
"assetBase": "my_story/",
|
||
"startScene": "scene_1",
|
||
"variables": { "trust": 50 },
|
||
"scenes": {
|
||
"scene_1": {
|
||
"id": "scene_1",
|
||
"videoUrl": "scene_1/video.mp4",
|
||
"choices": [
|
||
{ "text": "帮助他", "targetScene": "help_end" },
|
||
{ "text": "离开", "targetScene": "leave_end" }
|
||
]
|
||
},
|
||
"help_end": {
|
||
"id": "help_end",
|
||
"videoUrl": "scene_2/video.mp4",
|
||
"choices": []
|
||
},
|
||
"leave_end": {
|
||
"id": "leave_end",
|
||
"videoUrl": "shared/video.mp4",
|
||
"choices": []
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 运行
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
浏览器打开 `http://localhost:5173/?scene=my_story.json`。
|
||
|
||
## 引擎功能
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 视频分支播放 | A/B 双缓冲无缝切换，300ms 交叉淡化 |
|
||
| 选择系统 | 限时选择、条件分支（根据变量显示/隐藏） |
|
||
| 选择提示 (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 / SceneManager
|
||
│ ├── systems/ # QTE / Choice / Audio / Achievement / Save
|
||
│ └── types.ts
|
||
├── src/ # Vue UI 层
|
||
│ ├── components/ # 所有界面组件
|
||
│ ├── composables/ # 引擎 ↔ UI 桥接
|
||
│ ├── stores/ # Pinia 状态
|
||
│ └── locales/ # UI 翻译（开发者维护）
|
||
├── editor/ # 可视化剧情编辑器
|
||
├── 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/ # 文档
|
||
│ ├── guide/ # 游戏制作引导
|
||
│ └── electron/ # 打包配置
|
||
├── scripts/ # 打包脚本
|
||
└── ROADMAP.md
|
||
```
|
||
|
||
## 命令
|
||
|
||
```bash
|
||
npm run dev # 启动开发服务器
|
||
npm run build # 构建生产版本
|
||
npm run preview # 预览构建结果
|
||
npm run pack:html # 打包 Web 版
|
||
npm run pack:mac # 打包 macOS 桌面应用
|
||
npm run pack:win # 打包 Windows 桌面应用
|
||
```
|