# Galgame 剧本格式

把剧本写成 **Markdown / 纯文本** 文件，图片（立绘、背景、音乐）放在**工作区根目录**的约定位置：

| 素材 | 位置 |
| --- | --- |
| 剧本文档 | 根目录任意 `.md` / `.txt` |
| 人物立绘 | `img_human/` |
| 背景图片 | `img_bg/` |
| 背景音乐 | `audio/` |
| 开局/结束动画、CG 插图动画 | `img_cg/` |
| **开始界面素材（标题背景、标题音乐）** | **`img_ui/`（可选）** |

## 结构

```md
# 游戏标题                    ← 第一行 # 为标题（可选，也可用「标题:」）

标题: 游戏标题                 ← 可选
简介: 一句话介绍                ← 可选，显示在标题页

## 角色                         ← 角色区（位置也用于自动立绘）
小美: img_human/mei.png @ right   ← 名字: 立绘文件 [@ 位置 left/center/right]
小明: img_human/ming.png @ left

## 背景                         ← 背景区
教室: img_bg/classroom.png
天台: img_bg/rooftop.png

## 开始界面                     ← 开始界面（标题页）设计区（可选，见下文「开始界面设计」）
背景: img_ui/title.png          ← 标题页背景图（放 img_ui/）
音乐: audio/title.mp3           ← 标题页背景音乐（可留空）
布局: 立绘                      ← 人物展示布局：立绘（大图站位）或 头像（默认）
显示人物: 是
人物: 小美 @ 右, 小明 @ 左       ← 在标题页展示哪些人物、站在哪（@ 左/中/右）

## 剧本                         ← 正文区（以下内容按顺序执行）
[bg 教室]                      ← 切换背景
[bgm audio/bgm.mp3]            ← 播放音乐（循环）
[变量 好感度 0]                 ← 变量赋值（也可 [变量 好感度 = 0]）
小明: 唉，又是无聊的数学课……      ← 自动显示小明立绘
（小美把一张纸拍在课桌上）        ← 旁白：立绘全部淡出
小美: 帮我写一首诗！这是委托！     ← 自动显示小美立绘
[选项]                         ← 选项块开始
- 接下委托 → 天台线
- 委婉拒绝 → 教室线

### 天台线                       ← 标签（跳转目标）
[bg 天台]
[show 小美 @ center]           ← 显式标注：锁定小美居中
[变量 好感度 + 1]
小明: 所以……为什么非要我写诗？     ← 小美被锁定，小明自动出现
[if 好感度 >= 1]
小美: 你果然愿意来。谢谢你。
[endif]
[结束 结局·天台上的诗]
```

## 语法速查

| 写法 | 含义 |
| --- | --- |
| `# 标题`（首行）或 `标题: xxx` | 游戏标题 |
| `简介: xxx` | 标题页简介 |
| `## 角色` / `## 背景` / `## 剧本` | 分区 |
| `## 开始界面`（可选） | 开始界面（标题页）设计区：`背景` / `音乐` / `布局`（立绘|头像）/ `显示人物`（是|否）/ `人物`（名字[@左中右]，可含·表情） |
| `名字: 文件.png`（角色/背景区） | 定义角色立绘 / 背景图（含默认位置） |
| `名字·表情: 文件.png`（角色区） | 定义角色**多张立绘**（变体），如 `小美·开心: img_human/mei_happy.png` |
| `名字: 台词` | 角色台词（**自动显示该角色立绘**） |
| `（旁白）` 或纯文本行 | 旁白（**立绘全部淡出**） |
| `[bg 名字]` | 切换背景 |
| `[show 名字 @ left/center/right]` | 显式显示并**锁定**立绘（多人同屏：连续 `[show]` 多个角色） |
| `[hide 名字]`（或 `[隐藏]`/`[取消显示]`/`[取消]`/`[移除]`） | 隐藏该角色（解锁；再说话会自动出现） |
| `[退场 名字]`（或 `[离开]`） | 该角色**彻底离场**：之后不再自动出现，直到 `[show 名字]` 重新拉回 |
| `[位置 名字 左/右/中]` | **变换立绘站位**（多人同屏时随时换边，如 `[位置 小明 右]`；位置随存档保存） |
| `[表情 名字 表情名]` | **切换角色立绘**为指定变体（如 `[表情 小美 开心]`；也可 `[表情 小美·开心]`） |
| `[bgm 文件.mp3]` / `[bgm play 文件.mp3]` | **开始播放**（循环） |
| `[bgm off]` / `[bgm stop]` / `[bgm 停止]` | **停止音乐** |
| `[bgm 文件.mp3 0.5]` | 播放并设置音量（0–1） |
| `[op img_cg/opening.gif]` | **开局动画**：全屏播放，播完或点击「跳过」进入正文 |
| `[cg img_cg/cg1.gif]` | **CG 插图动画**：剧情中全屏展示，点击继续 |
| `[ed img_cg/ending.gif]` | **结束动画**：结局前全屏播放，播完或点击后进入结局 |
| `[存档 5]` | 设置**存档槽位数**（1–20，默认 9；播放器存档/读档面板按此显示） |
| `[输出 html]` | 输出格式（默认 html；`[输出 exe]` 暂未支持，会提示后按 html 输出） |
| `[变量 名字 = 值]` 或 `[变量 名字 值]` | 变量赋值（数字 / 字符串 / true / false） |
| `[变量 名字 + 1]` / `[变量 名字 - 1]` / `[变量 名字++]` | 变量增减 |
| `[if 变量 >= 2]` | 条件开始（也可用中文：`[如果]`） |
| `[else]`（可选） | 否则分支（`[否则]`） |
| `[endif]` | 条件结束（`[结束if]`） |
| `[选项]` + `- 文本 → 标签` | 分支选项（无 → 则继续往下） |
| `### 标签名` | 定义跳转点 |
| `[跳转 标签名]` | 跳转 |
| `[结束 结局名]` | 结束游戏 |
| `// 注释` | 注释行 |

## 立绘：自动跟随说话人（默认）

**不用写任何指令**，立绘会自动：

- **谁说话显示谁的立绘**（用角色区定义的位置）；
- **不说话的没有立绘**（自动淡出隐藏）；
- **旁白（无说话人）时没有任何立绘**（全部淡出）；
- **切换平滑不闪**（0.35s 淡入淡出）。

`[show 名字]` / `[hide 名字]` 是**显式标注**：`[show]` 会把该角色**锁定显示**（即使别人说话或旁白也保持在场），`[hide]` 解除锁定并隐藏。

## 开始界面设计（标题页，可选）

默认情况下，标题页是「渐变底色 + 游戏名 + 简介 + **全部角色的头像** + 开始/读档按钮」。如果你想自定义游戏开始界面（标题页）的布局，可以在剧本里加一个 **`## 开始界面`** 区（也可以写 `## 标题界面` / `## Title UI`）：

```md
## 开始界面
背景: img_ui/title.png        ← 标题页背景图（把图放进 img_ui/）
音乐: audio/title.mp3         ← 标题页音乐（进入游戏后自动切回剧本 [bgm]）
布局: 立绘                    ← 人物展示方式：立绘（大图按站位）或 头像（默认）
显示人物: 是                  ← 是否在标题页展示人物（是/否）
人物: 小美 @ 右, 小明 @ 左     ← 展示哪些人物、站哪边（@ 左/中/右；也可 小美·开心@右 指定表情变体）
```

- **`背景:`（也可 `标题背景` / `bg`）** —— 标题页背景图路径。通常放 `img_ui/title.png`（也支持 jpg / webp / gif 等）。不写则用默认渐变底色。
- **`音乐:`（也可 `标题音乐` / `标题bgm` / `music` / `bgm`）** —— 标题页背景音乐（放 `audio/`）。进入正文后按剧本 `[bgm]` 指令切换。
- **`显示人物:`（也可 `展示人物` / `showcast` / `show`）** —— `是` / `否`。`否` 表示标题页完全不展示人物。
- **`布局:`（也可 `人物样式` / `layout`）** —— `立绘`（sprite：人物以立绘大图形式站在画面左/中/右，标题文字叠在上层）或 `头像`（avatar：一排圆形头像，默认值）。
- **`人物:`（也可 `立绘` / `出场人物`）** —— 标题页要展示的人物清单，逗号/顿号分隔，每个条目可带站位 `@ 左|中|右` 与表情变体 `名字·表情`，如 `人物: 小美 @ 右, 小明·微笑 @ 左`。**不写则展示全部已定义角色**。写 `人物: 全部`（或 `所有`）等价于全部角色。

> **默认值即当前默认外观**：剧本里完全不写 `## 开始界面`（或写了但某项省略），该项就沿用默认 —— 渐变背景、无标题音乐、全部角色头像居中排布、游戏名/简介/按钮叠加显示。因此旧剧本不需要任何改动，外观与现在完全一致。

开始界面区独立生效：不执行台词、不改变存档，只在标题页渲染时读取；`[bg]` / `[bgm]` 只作用于进入游戏后的正文。

## if 条件线

配合 `[变量]` 使用，做 Galgame 的 flag / 好感度系统（支持嵌套）：

```md
[变量 好感度 0]
[选项]
- 送她礼物 → 送礼线
- 什么都不做 → 日常线

### 送礼线
[变量 好感度 + 1]
[if 好感度 >= 2]         ← 支持 = == != > >= < <=，中文：等于/不等于/大于/小于…
小美: 你居然记得我的生日……
[else]
小美: 谢谢你的礼物。
[endif]
[结束 结局A]
```

- 变量参与 `[if]` 判断；变量随**槽位存档一起保存**。
- `[if 变量名]`（不带运算符）= 变量为真时进入。

## 动画与 CG（img_cg/）

`img_cg/` 里放**开局动画、结束动画、CG 插图动画**（支持 gif / svg / mp4 / webm，静态 png/jpg 也可以作为插图）：

```md
## 剧本
[op img_cg/opening.gif]      ← 开局动画：进入正文前全屏播放，点击「跳过」或播完继续
[bg 教室]
小美: 剧情进行中……
[cg img_cg/cg1.gif]          ← CG 插图动画：全屏展示（视频则循环），点击继续
小美: 这一瞬间，我会记住的。
[ed img_cg/ending.gif]       ← 结束动画：结局前全屏播放，播完/点击后进入结局画面
[结束 结局·永远的夏天]
```

- `[op 文件]`（开局动画）与 `[ed 文件]`（结束动画）：全屏播放一遍，可点击跳过；视频播完自动继续。
- `[cg 文件]`（CG 插图动画）：全屏展示，点击任意处继续；视频循环播放。
- 动画文件同样随独立网页**内嵌**导出；GUI 播放器与独立网页行为一致。

## 9 槽位存档读档

- 游戏内「💾 存档」→ 选择**槽位 1–9** 保存；「📂 读档」→ 选择槽位读取。
- 标题页「⏵ 继续游戏（读档）」→ 直接进入槽位选择。
- 每个槽位保存：进度、立绘、背景、BGM、**变量**与历史。

## 注意事项

- 支持图片：png / jpg / jpeg / webp / gif / svg；音乐：mp3 / ogg / wav / m4a / mp4 / flac。
- 开始界面素材（标题背景等）建议放 `img_ui/`；不写 `## 开始界面` 时标题页保持默认外观。
- 找不到立绘/背景/音乐文件时，工具会给出警告；缺失立绘的角色在说话时会以「首字头像」占位。
- 分支跳转的目标必须用 `### 标签名` 定义，否则会报「跳转目标不存在」。
- 独立网页的存档存在浏览器 localStorage（按游戏 + 槽位区分）；`file://` 打开时 Chrome / Edge / Firefox 均支持。