引擎开发约定与参考

本文档记录交互电影游戏引擎的开发规范、架构约定和工作流程，供后续开发对话中引用。

工作流程

规则	说明
先讨论再执行	功能实现前必须先讨论方案，确认后再写代码
先更新 ROADMAP 再实现	新功能先写入 ROADMAP 的 P 条目，附实现清单，再逐项完成
不自动提交	代码写完不要 `git commit` / `git push`，等用户检查通过后再操作
验证方式	`npx vue-tsc --noEmit` + `npx vite build` 通过视为基本验证
生成测试数据	新功能要生成配套的示例视频 / 音频 / JSON 数据

架构原则

原则	说明
引擎与 UI 分离	`engine/` 下纯 TS 类，不 import Vue。UI 层通过 composables 桥接
A/B 双缓冲	两个 `<video>` 元素轮换，一个播放时另一个预加载候选场景
JSON 驱动	所有剧情数据放在 JSON 中，编辑器本质是 JSON 的可视化读写工具
IndexedDB 存档	比 localStorage 容量大，可存储截屏缩略图。多槽位支持
故事图与玩家树	创作端 JSON 是有向图，展示端 BFS 投影为树（汇聚节点复制展示）

目录结构

moviegame/
├── engine/                     # 框架无关的核心引擎（纯 TS）
│   ├── core/
│   │   ├── Engine.ts           # 主循环，驱动各子系统
│   │   ├── SceneManager.ts     # 剧情节点图遍历、章节管理
│   │   ├── VideoManager.ts     # A/B 双缓冲视频播放 + 流媒体质量选择
│   │   └── StateManager.ts     # 全局状态、变量条件求值、效果执行
│   ├── systems/
│   │   ├── ChoiceSystem.ts     # 限时选择 + 倒计时
│   │   ├── QTESystem.ts        # QTE 触发、键盘监听、超时判定
│   │   ├── AudioSystem.ts      # Web Audio API BGM + Ducking
│   │   ├── AchievementSystem.ts # 纯变量成就检测 + 解锁
│   │   └── SaveSystem.ts       # IndexedDB 多表持久化
│   └── types.ts                # 全部类型定义
├── src/
│   ├── components/             # Vue 组件——玩家端 UI + 编辑器 UI
│   ├── composables/            # 引擎 ↔ UI 桥接
│   ├── stores/                 # Pinia 全局状态
│   └── locales/                # UI 文本翻译（静态 import，构建时打包）
├── editor/                     # Vue Flow 可视化编辑器（独立入口）
├── electron/                   # Electron 桌面应用打包
├── public/
│   └── demo/                   # 示例素材——按场景分目录，每场景含视频、字幕、缩略图
│       └── locales/            # 故事文本翻译（动态 fetch 加载，制作者维护）
├── docs/
│   ├── SCENE_JSON_SPEC.md      # 场景 JSON 完整字段参考
│   └── ARCHITECTURE.md         # 关键架构决策记录
├── scripts/                    # 构建与打包脚本
├── ROADMAP.md                  # 待实现功能清单
└── CHANGELOG.md                # 功能更新日志

代码约定

规则	示例
不要写注释	代码自解释，不添加多余的中英文注释
Engine 事件驱动	`this.emit('sceneChange', scene)` → composable 响应
composable 桥接	`useGameEngine.ts` 是 Engine 和 Vue store 的中间层
i18n 双文件分层	`src/locales/` 存 UI 文本，`public/demo/locales/` 存故事文本。`useI18n.t()` 先查故事消息，fallback UI 消息
选择翻译在 composable 中	`choiceRequest` 事件触发时 composable 调用 `t(textKey)` 翻译后存入 store
引擎不感知 i18n	`Choice.textKey` 和 `Hotspot.labelKey` 是数据层字段，翻译完全在 Vue 层完成
demo 素材按场景分目录	`public/demo/<scene_id>/<file>`
demo 的 assetBase	`"assetBase": "demo/"` — 所有资源路径以此为前缀

菜单系统

菜单	设计
主菜单 (MainMenu.vue)	竖排单列，开始游戏最大、继续次之、底部小字装饰行（故事进度 · 成就 · 设置）
暂停菜单 (PauseMenu.vue)	ESC 弹出的全屏暂停，包含继续 / 存档 / 设置 / 返回主菜单
设置面板 (AccessibilitySettings.vue)	语言 + 画质(仅 Web) + 字幕 + QTE 辅助 + 防误触 + 可暂停
游戏内顶栏	精简：跳过(条件显示) · 倍速(条件显示) · 全屏 · ≡菜单

视频播放模式

模式	检测方式	使用的 URL 字段	切换方式
Electron 桌面	`window.__ELECTRON__ === true`	`videoUrl`（本地 MP4）	不切换，单文件
Web 浏览器	`__ELECTRON__` undefined	`streamingUrl[quality]`（CDN HLS）	设置面板手动选择超清/高清/标清
画质切换	仅在视频播放中切换（`video.ended === false`），结束后不切换等待下一场景

关键方法：

VideoManager.resolveVideoUrl(scene, quality) — 环境检测 + URL 选择
VideoManager.switchQuality(src, seekTime) — 实时切换画质
SceneManager.getCandidateSceneIds() — 返回候选场景 ID，Engine 用 resolveVideoUrl 解析为 URL
预加载也走 resolveVideoUrl，Web 模式禁止预加载本地 MP4

场景 JSON 约定

规则	说明
单文件包含全部场景	不拆分章节为独立 JSON 文件
章节用 `startScene` 标记	无 `endScene`，BFS 遍历可达场景作为章节范围
影像场景标记	`"type": "image"`, `videoUrl` 为空
QTE 配置	`effects.success` / `effects.fail` 中附加变量修改，供成就检测
结局归属	通过 BFS 自动推导 `ending.sceneId` 属于哪个章节，不显式声明 `chapterId`

成就系统

纯变量检测，在 StateManager.apply 末尾 onAfterApply 单一检查点触发
事件型成就改写为变量型：QTE 成功 → effects 中 set: qte_succeeded, value: 1
解锁时有 toast 弹出、持久化写入 IndexedDB achievements 表

流媒体 / HLS 约定

每场景三档 HLS，目录结构：public/demo/<scene>/<quality>p/index.m3u8 + seg_000.ts
demo.json 中每场景配 streamingUrl: { "超清 (1080P)": "...", "高清 (720P)": "...", "标清 (480P)": "..." }
生成命令：ffmpeg -i source.mp4 -c:v libx264 -b:v <bitrate>k -c:a aac -b:a 128k -hls_time 2 -hls_segment_filename <dir>/seg_%03d.ts <dir>/index.m3u8
pack-html.cjs 跳过 videos/ 目录（Web 版使用 CDN 流媒体）
pack-mac / pack-win 保留完整视频文件（桌面版使用本地 MP4）

6.7 KiB Raw Permalink Blame History Unescape Escape

引擎开发约定与参考

工作流程

架构原则

目录结构

代码约定

菜单系统

视频播放模式

场景 JSON 约定

成就系统

流媒体 / HLS 约定

6.7 KiB

Raw Permalink Blame History