ngal · 终端视觉小说引擎

纯终端｜全彩立绘｜语音+BGM｜变量分支｜亚克力沉浸

Rust + Ratatui 立绘/背景叠加 mpv 音频脚本+变量背景色/动画

什么是 ngal？

ngal 是一个纯终端环境下的跨平台 Galgame / 视觉小说引擎。使用 Rust 编写，提供精美的双边框 UI、角色立绘/背景分层、变量系统、分支选项、十槽位存档/读档、背景音乐及角色语音。开发者只需编写简单的文本脚本，即可在终端里享受属于自己的故事。

轻量快速
无需图形界面，SSH 或 Termux 上流畅运行

脚本极简
对话/图片/音乐/选项皆可一行命令搞定

完全沉浸
支持 mpv 背景音乐 + 角色独立语音

完善功能
文字动画、历史回溯、自动播放、鼠标滚轮…

安装 & 运行

依赖：Rust + Cargo + mpv (用于音频)

# 从 crates.io 安装
cargo install ngal

# 或从 GitHub 编译
git clone https://github.com/nasyt233/ngal.git
cd ngal
cargo build --release

# 运行游戏 (会在当前目录生成 assets/ 及默认配置)
ngal
ngal ./mygame        # 指定游戏目录
ngal --version       # 显示版本

首次运行自动创建 `assets/` 相关资源文件夹，放入对应的立绘、音乐、语音即可开始创作。

亮点特性

全彩双线边框 + 亚克力/纯色背景(可切换)

立绘位置/缩放控制 (左/中/右 + 百分比)

背景与角色图片叠加，支持透明通道

BGM/语音独立音量，设置菜单实时调节

变量系统 + 用户输入 (`input:提示语:变量`)

十槽位存档/读档 (带时间戳信息)

自动播放 / 逐字动画 / 动画速度调节

历史记录弹窗 (H键) + 鼠标滚轮支持

完全开源 MIT 协议，可二次开发

游戏目录结构

your_game/
├── assets/
│   ├── game.json          # 标题、底部提示、入口文件配置
│   ├── dialog/
│   │   └── dialogue.txt   # ⭐主演剧情脚本 (核心)
│   ├── portraits/         # 立绘 & 背景图片 .png/.jpg
│   ├── music/             # 背景音乐 .mp3/.ogg
│   └── voices/            # 角色语音 .mp3
├── save/                  # 存档 slot1~10.json (自动生成)
└── ngal (可执行文件)

📌 `game.json` 示例：
{"title": "终端奇缘", "footer": "按回车继续 | H历史", "index": "dialog/dialogue.txt"}

首次试玩

按上述结构放好脚本和资源，执行 `ngal` 即可。自带默认剧情演示（变量、分支、立绘切换）。

小窍门：支持 `ngal ./你的项目` 切换游戏根目录，便于管理多项目。

脚本编写 · 从零到完整演示

剧情文件位于 assets/dialog/dialogue.txt，游戏从 [welcome] 场景启动。下方是一个包含音乐、立绘/背景、变量、选项、跳转等全部指令的示例：

[welcome]
music:title.mp3
img:NAS油条.png:3:50%
NAS油条:本项目由Rust语言开发\n按回车键继续:nas_intro.mp3
img:
input:请输入你的名字:name
NAS油条:好的，{name}，哪个游戏牛逼?:gamenb.mp3
choose:原神牛逼:ysnb|鸣朝牛逼:mcnb|终末地牛逼:zmd

[ysnb]
bg:91.png
img:鸣朝.png:3:35%
鸣朝:鸣朝才牛逼😡:mcnb.mp3
鸣朝:原神不牛逼🤓:ys_no_nb.mp3
原神:原神才牛逼🤓👍:ysnb.mp3
原神:鸣朝不牛逼😡:mc_no_nb.mp3
load:ytnb

[mcnb]
img:原神.png
原神:原神才牛逼🤓👍:ysnb.mp3
原神:鸣朝不牛逼😡:mc_no_nb.mp3
鸣朝:鸣朝才牛逼😡:mcnb.mp3
鸣朝:原神不牛逼🤓:ys_no_nb.mp3
load:ytnb

[zmd]
img:终末地.png
终末地:我最牛逼
end

[ytnb]
img:我.png
{name}:😋他们产的片才牛逼😋:ysmcnb.mp3
bg:
NAS油条:游戏结束
end

命令完全手册

对话 + 语音
钟离:随便聊聊 / 派蒙:好吃:voice_paimon.mp3
旁白直接写文本即可。

变量 / 输入
input:输入名字:player
{player}你好 / 好感=3

立绘 (sprite)
img:角色.png (居中100%)
img:角色.png:1:70% (左, 70%)
img: 清除

背景图片
bg:校园.jpg (拉伸填充)
bg: 清除背景

音乐 & 音效
music:bgm.mp3 播放 / music: 停止

选项分支
choose:去森林:forest|去城镇:town

流程控制
load:场景ID / end 结束游戏
支持注释 // 或 #

换行 & 特效
对话中 \n 强制换行。
文字动画、速度可在设置调节。

⚠️ 注意：场景名只使用字母/数字/下划线，文本编码UTF-8无BOM。所有图片/音乐/语音文件放在 assets 下的正确子目录。

立绘高级用法

支持透明背景PNG，可叠加在背景图片上。位置参数: 1(左) / 2(中) / 3(右)，缩放百分比后显示效果实时适应终端尺寸。例如 img:heroine.png:3:80% 在右侧显示，大小为原图80%。

背景图通过 bg:场景.jpg 拉伸填满整个立绘区域，营造沉浸环境。清除背景用 bg:。

游戏内快捷键

␣ / Enter 推进对话 / 确认选项

↑ / ↓ 选择选项 / 清单滚动

ESC 返回上级 / 关菜单

S 存档 / L 读档

H 历史记录弹窗

A 自动播放开关

T 文字动画开关

3 / 4 文字速度 -10ms / +10ms

B 背景色循环 (深紫/深蓝/深绿/深红/深灰/无色)

q 主菜单退出/游戏中退回菜单

命令行参数

ngal                     # 当前目录运行
ngal ./mygame            # 跳转到游戏根目录
ngal --version   / -V    # 显示版本信息
ngal -h / --help         # 帮助信息