# Plan C Galgame 引擎 · 完整说明书
—
## �� 用户手册
### 第1章：快速入门与基础
#### 1.1 引擎获取与启动
Plan C Galgame 引擎为**单 HTML 文件**，无需安装。使用现代浏览器（Edge / Chrome 推荐）直接打开 `Plan_C_Galgame.html` 即可运行。初次加载约需 1 秒，界面自动显示默认场景“开场”。
**系统要求**：
– 操作系统：Windows 7+ / macOS 10.12+ / Linux（任意桌面发行版）
– 浏览器：Chrome 80+ / Edge 80+ / Firefox 75+
– 内存：建议 4GB 以上（处理大尺寸素材时）
– 无需网络连接（完全离线可用）
#### 1.2 编辑器界面概览
“`
┌─────────────────────────────────────────────────┐
│ 工具栏 (toolbar) ▲ 场景 ▼ 保存 ■ 导出 ▶ 运行 │
├────────┬───────────────────────────┬────────────┤
│ 场景列表│ 预览区 (4:3) │ 属性面板 │
│ 分支地图│ ┌─────────────┐ │ 舞台状态 │
│ 角色库 │ │ 背景 / 立绘 │ │ │
│ 素材库 │ │ 对话框 │ │ │
│ 工程保存 │ └─────────────┘ │ │
│ │ │ │
│ │ 时间线 (脚本行) │ │
│ │ [bg] [sy] [ch] [ci] … │ │
└────────┴───────────────────────────┴────────────┘
“`
**核心区域说明**：
– **工具栏**：创建场景、保存/导入工程、导出游戏、运行预览、加载插件。
– **左侧面板**：管理场景标签、查看分支地图、角色库（含立绘状态）、素材库（图片/音频）。
– **中央预览区**：实时显示当前舞台画面（背景 + 立绘 + 对话框），支持滚轮回退。
– **中央时间线**：列出当前场景的所有脚本行，可添加、编辑、删除、排序。
– **右侧属性面板**：编辑选中行的详细参数，下方显示当前舞台状态摘要。
#### 1.3 核心概念
| 概念 | 说明 | 类比 |
|——|——|——|
| **场景 (Scene)** | 以标签命名的独立剧情段落，包含一组有序的脚本行 | Ren’Py 的 `label` |
| **脚本行 (Line)** | 时间线上的单条指令，类型包括 bg/music/char/say/choice 等 | 导演脚本的一条命令 |
| **舞台状态 (Stage)** | 当前背景、音乐、立绘的集合。背景/音乐/立绘设置后持续存在，直到被新指令覆盖 | 真实舞台上的布景和演员 |
| **角色立绘 (Sprite)** | 角色的视觉表现，支持多个状态（动作 + 表情 + 图片） | 演员的不同服装和表情 |
#### 1.4 你的第一个项目
1. **打开引擎**：双击 `Plan_C_Galgame.html`，自动进入“开场”场景。
2. **添加背景**：点击时间线工具栏的 `��` 按钮，右侧属性面板出现背景编辑区。点击 `�� 本地图片` 选择一张图片，预览区立即显示。
3. **添加对话**：点击 `��` 按钮，在右侧“说话者”下拉菜单选择或输入角色名，在“文本”区输入台词。点击“应用”。
4. **运行预览**：点击工具栏 `▶ 运行` 按钮，然后在预览区点击文本框推进剧情。
5. **导出游戏**：点击 `�� 导出` → `�� HTML网页`，浏览器自动下载一个独立的 `.html` 文件。双击即可玩。
—
### 第2章：资源工作流
#### 2.1 资源导入规范
**支持的格式**：
– 图片：JPG、PNG、GIF、WebP、BMP（浏览器原生支持的格式）
– 音频：MP3、WAV、OGG、AAC（浏览器原生支持的格式）
**命名规范建议**：
– 使用英文或拼音命名，避免特殊字符（如空格、中文标点）。
– 示例：`bg_park.jpg`、`sakura_smile.png`、`bgm_main.mp3`
**目录结构建议**（仅用于本地管理，引擎不强制目录）：
“`
项目文件夹/
├── assets/
│ ├── backgrounds/
│ ├── characters/
│ │ ├── sakura/
│ │ └── mei/
│ └── music/
├── Plan_C_Galgame.html
└── project_backup.json
“`
#### 2.2 素材库管理
**上传素材**：
– 左侧面板 → 素材库 → 点击 `��` 或 `��` 标签 → 选择本地文件（支持多选）。
– 上传后自动生成素材 ID（如 `@img1`、`@mus1`），并转为 Base64 内嵌。
**使用素材**：
– 编辑背景/音乐节点时，点击属性面板的 `�� 素材库` 或 `�� 素材库` 按钮，弹出可视化选择器，点击缩略图即可填入 ID。
– 也可在素材列表中直接点击素材名称，自动应用到当前选中的节点（类型匹配时）或添加新行。
**删除素材**：
– 素材列表中每个素材右侧有 `×` 按钮，点击确认删除。
– **注意**：被引用的素材删除后，对应节点会回退到默认背景色（`#1a1a2e`）或停止音乐。
#### 2.3 角色与立绘
**创建角色**：左侧面板 → 点击 `+ 角色` → 输入名称（如 `さくら`）。
**添加立绘状态**：角色列表中每个角色旁有 `+` 按钮 → 选择本地图片 → 输入动作（如 `默认`）和表情（如 `普通`）。一个角色可以有多个状态（如 `默认/普通`、`默认/微笑`、`生气/普通`）。
**使用立绘**：在时间线添加 `��` 节点 → 属性面板下拉选择角色 ID、位置（左/中/右）、动作、表情。也可点击 `�� 本地立绘` 直接上传并应用。
—
### 第3章：功能模块指南
#### 3.1 脚本系统——可执行的事件类型
| 类型 | 图标 | 功能 | 参数 |
|——|——|——|——|
| 背景 | �� | 切换当前背景 | 颜色值（如 `#1a1a2e`）或素材 ID（如 `@img1`）|
| 音乐 | �� | 切换当前 BGM | 素材 ID 或音频 URL；留空停止 |
| 立绘 | �� | 显示/隐藏/改变角色立绘 | 角色 ID、位置、动作、表情 |
| 对话 | �� | 显示一段台词 | 说话者、文本（支持换行） |
| 选项 | �� | 分支暂停点 | 问题文本、多个选项（每行：`选项文本 -> 目标标签`）|
| 跳转 | ↗ | 强制跳转标签 | 目标标签名 |
| 标签 | �� | 定义跳转目标 | 标签名 |
| 结束 | ⏹ | 场景结束 | 无 |
**执行逻辑**：
– `bg`、`music`、`char` 是“舞台状态操作”，执行后立即生效并继续。
– `say` 是“推进事件”，显示后等待用户点击（或自动模式下等待延迟）。
– `choice` 暂停剧本，等待玩家选择，选择后跳转到目标标签或继续。
#### 3.2 引擎运行时功能
**预览区控件**（右上角）：
– `A`：自动模式，对话显示后等待设定时间自动继续。
– `S`：跳过已读模式，快速跳转到未读内容。
– `QS` / `QL`：快速存档 / 读档（快捷键 Ctrl+S / Ctrl+L）。
– `L`：打开历史对话日志。
– `⚙`：打开设置面板（文本速度、音量、自动延迟）。
**滚轮交互**：
– 向下滚动：推进剧情（等同于点击文本框）。
– 向上滚动：回退到上一句（历史快照恢复）。
#### 3.3 分支与跳转
**选项节点**：添加时弹出数量输入框，自动生成目标标签（如 `开场_分支1`）。在属性面板编辑选项文本和目标标签。
**分支地图**：左侧面板自动显示所有场景的跳转关系树，点击可快速切换场景。
—
### 第4章：发布与构建
#### 4.1 导出游戏
点击工具栏 `�� 导出` → 选择 `�� HTML网页`，浏览器自动下载一个完整的独立游戏文件。
**导出文件特性**：
– 所有图片/音频以 Base64 内嵌，无外部依赖。
– 包含完整的引擎运行时（存档、设置、自动、跳过、回退全保留）。
– 文件可直接双击运行，也可部署到任意静态 Web 服务器。
**导出前检查**：
– 确保所有素材已正常显示（预览区可见）。
– 删除不再使用的场景和素材（减小体积）。
– 建议使用压缩图片（JPG 质量 70-80%，分辨率不超过 1024px 宽）。
#### 4.2 工程文件保存/导入
**保存工程**：点击 `�� 保存` → 下载 `.json` 文件。包含所有场景、角色、素材的 Base64 数据。
**导入工程**：点击 `�� 导入` → 选择之前保存的 `.json` 文件 → 恢复完整工作状态。
—
## ��️ 开发者工具指南
### 第1章：可视化编辑器
#### 1.1 时间线编辑器
– 点击脚本行选中，右侧面板显示属性表单。
– 鼠标悬停显示删除按钮（✕）。
– 使用 ▲ / ▼ 按钮上下移动脚本行顺序。
– 修改属性后必须点击“应用”才能保存。
#### 1.2 舞台状态实时预览
– 点击任意脚本行，舞台预览区自动累计计算到该行为止的状态。
– 右侧面板“舞台状态”摘要显示当前背景、音乐、立绘概况。
#### 1.3 素材选择器
– 编辑背景/音乐节点时，点击 `��` / `��` 按钮弹出可视化选择器。
– 选择器显示所有已上传素材的缩略图，点击即可选用。
—
### 第2章：调试与诊断
#### 2.1 浏览器开发者工具
– 按 F12 打开开发者工具，在 Console 面板查看引擎日志。
– 所有 Toast 提示也会同步输出到控制台。
#### 2.2 常见问题诊断
| 问题 | 可能原因 | 检查步骤 |
|——|———-|———-|
| 预览区黑屏 | 背景节点值无效 | 检查背景节点属性面板的值是否正确设置了素材 ID 或颜色 |
| 立绘不显示 | 角色未添加状态 | 在角色库中为该角色添加至少一个状态（动作+表情+图片） |
| 说话者无法保存 | 下拉菜单未联动 | 确保选择下拉选项后，下方输入框的值已同步更新 |
| 导出游戏无响应 | 素材过大 | 压缩图片后重新导入或导出 |
#### 2.3 引擎自检系统
引擎内置自检功能（右上角状态灯）：
– **DOM**：检查所有必需 HTML 元素是否存在。
– **DATA**：检查默认场景和角色是否正确初始化。
– **EVENTS**：检查所有按钮是否绑定事件。
– **ENGINE**：检查引擎对象是否完整。
—
### 第3章：自动化与协作
#### 3.1 命令行工具
引擎本身为纯浏览器应用，不包含命令行工具。导出游戏可通过任何 HTTP 服务器部署。
#### 3.2 版本控制集成
建议使用 Git 管理工程文件（`.json`）和素材源文件：
– `.gitignore` 建议忽略 `Plan_C_Galgame.html`（保持引擎版本独立）。
– 工程文件中已包含 Base64 素材，可直接用于协作交接。
—
## ⚙️ 二次开发手册
### 第1章：架构与环境
#### 1.1 引擎架构设计
“`
┌──────────────────────────────────┐
│ HTML / CSS (UI) │
├──────────────────────────────────┤
│ JavaScript 核心引擎 (ES5) │
│ ┌───────────────────────────┐ │
│ │ 数据模型 (SC/CH/AI等) │ │
│ ├───────────────────────────┤ │
│ │ 渲染系统 (RT/RPP/AP等) │ │
│ ├───────────────────────────┤ │
│ │ 引擎核心 (EG) │ │
│ ├───────────────────────────┤ │
│ │ 导出与存储 (DEH/SPJ/LPJ) │ │
│ └───────────────────────────┘ │
└──────────────────────────────────┘
“`
#### 1.2 开发环境搭建
– 无需编译工具，直接编辑 `.html` 文件。
– 推荐使用 VS Code + Live Server 插件进行开发调试。
– 打开浏览器开发者工具（F12）进行断点调试。
#### 1.3 编码规范
– **语言标准**：ES5（`var` 声明、传统函数、无箭头函数/模板字符串），保证最广泛兼容。
– **变量命名**：使用缩写（如 `SC`=scenes, `CH`=characters, `AI`=assets.images），核心函数名前缀大写。
– **内存管理**：文件导入使用 `FileReader` 异步读取，完成后在 `onload` 回调中处理。全局缓存字典 `AD` 存储 Base64 数据。
—
### 第2章：核心模块扩展
#### 2.1 新增指令类型（以“音效”为例）
1. **数据模型**：在 `AL()` 函数的 `defaults` 中添加 `sound: { v: ” }`。
2. **属性面板**：在 `RPP()` 中添加音效节点表单（类似音乐节点）。
3. **属性保存**：在 `APL()` 中添加 `sound` 分支。
4. **引擎执行**：在 `EG.rn()` 中添加 `else if (c.tp === ‘sound’) { … }`（创建新 Audio 对象播放，不停止 BGM）。
5. **时间线渲染**：在 `RT()` 中添加对应图标和显示。
6. **导出支持**：在 `DEH()` 的脚本生成中添加 `sound` 类型。
#### 2.2 自定义导出模板
修改 `DEH()` 函数中的 `gjs` 字符串——即导出游戏的内嵌 JavaScript。可在此处添加新功能（如新的存档格式、高级设置项）。
—
### 第3章：编辑器扩展
#### 3.1 插件系统
引擎提供轻量级插件入口：
– **注册插件**：调用 `registerPlugin(‘插件名’, 初始化函数)`。
– **加载插件**：点击工具栏 `�� 加载插件`，选择本地 `.js` 文件。
– 插件代码在全局作用域执行，需自行保证安全性。
**示例插件**：
“`javascript
// my_plugin.js
registerPlugin(“示例插件”, function() {
console.log(“插件已启动，引擎数据: “, SC, CH);
// 可以扩展全局函数或修改 DOM
});
“`
#### 3.2 自定义面板与菜单
可通过直接修改 HTML 结构（在 `<div id=”left-panel”>` 等区域添加按钮）并在 `BE()` 函数中绑定事件来扩展编辑器界面。
—
## �� 维修手册
### 第1章：常见故障排查
| 故障现象 | 诊断步骤 | 解决方案 |
|———-|———-|———-|
| 页面空白 / 按钮无反应 | 1. 按 F12 查看控制台红色报错；2. 检查 `INIT()` 函数是否执行 | 确认浏览器为 Chrome/Edge 最新版；使用本地服务器而非 `file://` 打开 |
| 背景图导入后黑屏 | 检查属性面板背景值是否为素材 ID（`@img1`）；检查素材库中该素材是否正常显示 | 重新上传图片；确保 `RBG()` 函数正确返回 data URI |
| 说话者选择后无法保存 | 检查下拉菜单 `pss` 与输入框 `ps2` 的联动事件是否绑定 | 确认 `RPP()` 中 `sy` 分支包含 `pss.addEventListener(‘change’, …)` |
| 导出游戏后音乐不播放 | 浏览器自动播放策略限制 | 确保用户点击过游戏画面后再播放；或在设置中调高音量 |
| 工程文件导入失败 | 检查 JSON 文件格式是否正确 | 使用保存工程重新导出；检查控制台错误信息 |
### 第2章：维护与优化
#### 2.1 性能优化建议
– **图片压缩**：使用 JPG 格式，分辨率不超过 1024px 宽，可显著减小导出体积。
– **音频压缩**：使用 MP3 格式，比特率 128kbps 以下。
– **删除无用资源**：定期清理素材库中不再使用的图片/音频。
– **导出优化**：导出前确保所有素材已转为 Base64（避免 `blob URL` 残留）。
#### 2.2 兼容性矩阵
| 浏览器 | 最低版本 | 推荐版本 | 已知问题 |
|——–|———-|———-|———-|
| Chrome | 80 | 100+ | 无 |
| Edge | 80 | 100+ | 无 |
| Firefox | 75 | 90+ | 部分 CSS 动画可能略有差异 |
| Safari | 14 | 15+ | `localStorage` 限制可能影响存档 |
#### 2.3 版本升级
引擎为单文件，无需复杂迁移：
1. 下载新的 `Plan_C_Galgame.html` 文件。
2. 使用旧版本导出工程文件（`.json`）。
3. 在新版本中导入工程文件。
4. 检查所有素材和脚本是否正常。
### 第3章：维护记录与反馈
#### 3.1 问题反馈流程
提交 Bug 报告时请包含：
1. **引擎版本**（工具栏右下角显示）。
2. **操作步骤**：详细描述导致问题的操作顺序。
3. **预期结果** vs **实际结果**。
4. **浏览器控制台截图**（F12 → Console 面板）。
#### 3.2 版本更新日志
**v1.4（当前）**：
– 修复 `sy` 节点说话者选择后无法保存的 bug。
– 优化本地文件导入的异步回调顺序。
– 增强初始化错误捕获。
**v1.3**：
– 添加下拉菜单与手动输入的实时联动。
– 修复导出游戏中的转义问题。
**v1.2**：
– 改进素材库调用逻辑（点击素材自动应用或添加行）。
– 添加插件系统入口。
—
# Plan C Galgame 引擎 · 变量含义对照表
为便于阅读和二次开发，以下是引擎核心变量的详细注释。
—
## 一、全局数据模型
| 变量名 | 类型 | 含义 |
|——–|——|——|
| `AI` | `Object` | **图片素材元数据**，键为素材ID（如`@img1`），值为`{url, nm}` |
| `AA` | `Object` | **音频素材元数据**，键为素材ID（如`@mus1`），值为`{url, nm}` |
| `AIc` | `Number` | 图片素材计数，每次上传自增 |
| `AAc` | `Number` | 音频素材计数，每次上传自增 |
| `AD` | `Object` | **素材Base64数据**，键为素材ID，值为dataURI字符串（保证离线可用） |
| `CH` | `Object` | **角色库**，键为角色ID（如`c1`），值为`{nm(姓名), st(状态数组)}` |
| `NC` | `Number` | 角色ID计数器 |
| `SC` | `Object` | **场景容器**，键为标签名，值为`{ls(脚本行数组)}` |
| `SO` | `Array` | **场景有序列表**，保持场景的显示顺序 |
| `CS` | `String` | **当前选中场景**的标签名 |
| `SLI` | `Number` | **当前选中脚本行索引**，`-1`表示未选中 |
| `DBG` | `String` | 默认背景颜色，值为`’#1a1a2e’` |
—
## 二、引擎运行时状态
| 变量名 | 类型 | 含义 |
|——–|——|——|
| `GS` | `Object` | **游戏设置**，包含`ts`(文本速度)、`bv`(音量)、`ad`(自动延迟) |
| `HS` | `Array` | **历史快照栈**，用于滚轮向上回退。每帧存储脚本索引和舞台状态 |
| `HL` | `Array` | **对话日志**数组，每项为`{sp(说话者), tx(文本)}` |
| `AM` | `Boolean` | 自动模式标志 |
| `SM` | `Boolean` | 跳过已读模式标志 |
| `RH` | `Object` | **已读文本哈希表**，键为文本特征哈希，值为`true` |
| `CBG` | `String` | **当前背景**的实际值（颜色或图片URL/dataURI） |
| `CMU` | `String` | **当前音乐**的值（音频URL或素材ID） |
| `CSC` | `Object` | **当前立绘集合**，键为角色ID，值为`{url, pos}` |
—
## 三、引擎对象 (EG) 属性
| 属性名 | 类型 | 含义 |
|——–|——|——|
| `EG.idx` | `Number` | **当前脚本索引**，指向正在执行的脚本行 |
| `EG.sc` | `Array` | **当前展开的脚本**（扁平化后的指令数组） |
| `EG.tm` | `Number` | 打字效果的**定时器ID** |
| `EG.au` | `Audio` | 当前**音乐播放器**实例 |
| `EG.ca` | `Boolean` | 选项激活状态（`true`表示正在显示选项） |
—
## 四、渲染函数缩写
| 函数名 | 全称 | 作用 |
|——–|——|——|
| `RA` | `renderAll` | 刷新全部UI（时间线、属性面板、场景列表、分支地图、路径栏） |
| `RT` | `renderTimeline` | 渲染当前场景的**时间线**脚本行 |
| `RPP` | `renderPropsPanel` | 渲染右侧**属性面板**（根据选中节点类型生成表单） |
| `RSL` | `renderSceneList` | 渲染左侧**场景列表** |
| `RBM` | `renderBranchMap` | 渲染**分支地图**树状图 |
| `RPB` | `renderPathBar` | 渲染时间线上方的**路径栏**（来自→当前→可前往） |
| `AP` | `applyPreview` | **应用舞台状态**到预览区（背景、立绘） |
| `PSF` | `previewSceneFromStart` | 从场景开头开始预览舞台状态 |
| `SLL` | `selectLine` | 选中某条脚本行 |
| `RML` | `removeLine` | 删除某条脚本行 |
| `ML` | `moveLine` | 上下移动脚本行顺序 |
—
## 五、引擎核心函数缩写
| 函数名 | 全称 | 作用 |
|——–|——|——|
| `EN` | `ensureScene` | 确保场景存在（不存在则创建，并自动添加默认背景） |
| `GL` | `getLines` | 获取某场景的所有脚本行 |
| `AL` | `addLine` | 添加一条脚本行 |
| `APL` | `applyPropsLine` | 应用属性面板的修改到数据模型 |
| `ACB` | `applyCurrentBg` | 将当前背景值渲染到预览区 |
| `EG` | `engine` | 引擎核心对象，包含`ld(load)`、`rn(run)`、`tt(typeText)`、`ad(advance)`等方法 |
| `PH` | `pushHistory` | 压入历史快照 |
| `PPH` | `popHistory` | 弹出并恢复历史快照 |
—
## 六、导出与存储函数
| 函数名 | 全称 | 作用 |
|——–|——|——|
| `DEH` | `doExportHTML` | 导出独立HTML游戏文件 |
| `SPJ` | `saveProjectJSON` | 保存工程文件为JSON |
| `LPJ` | `loadProjectJSON` | 从JSON文件导入工程 |
| `AFS` | `applyFullScript` | 编译所有场景为完整脚本，并加载到预览引擎 |
—
## 七、工具函数
| 函数名 | 对应角色 | 作用 |
|——–|———-|——|
| `Z` | `$` | 等同于`document.getElementById`，获取DOM元素 |
| `TM` | `toast` | 显示底部提示消息（自动消失） |
| `ES` | `esc` | HTML转义，防止XSS |
| `RBG` | `resolveBg` | 解析背景值（将素材ID转换为实际URL或dataURI） |
| `SP` | `showPrompt` | 显示文本输入弹窗 |
| `SC2` | `showConfirm` | 显示确认对话弹窗 |
| `PA` | `pickAsset` | 打开素材选择器 |
| `HU` | `handleUpload` | 处理素材文件上传 |
—
## 八、常用的局部简写
在函数内部，常用单字母或双字母简写来指代参数，便于对照：
| 简写 | 含义 |
|——|——|
| `l` | label / scene label（场景标签名） |
| `d` | data（脚本行的数据对象） |
| `ln` | line（脚本行对象） |
| `tp` | type（脚本行类型：bg/mu/ch/sy/ci/go/la/en） |
| `v` | value（背景/音乐节点的值） |
| `ci` | charId（角色ID） |
| `sp` | speaker（说话者） |
| `tx` | text（对话文本） |
| `po` | position（立绘位置：left/center/right） |
| `ac` | action（立绘动作） |
| `ex` | expression（立绘表情） |
| `nm` | name（角色名/素材名） |
| `st` | states（角色立绘状态数组） |
—
*提示：阅读代码时，建议从 `INIT()` 函数开始，顺着调用链逐步理解各模块交互。*