SakiEngine 是一个基于 Flutter 的现代化视觉小说游戏引擎，专为跨平台游戏开发而设计。
- 类Renpy语法：使用类似Renpy的脚本语法，降低游戏开发门槛
- 自适应窗口：游戏窗口可以自由拉伸，画面智能适配
- 低性能占用：轻量级引擎，确保流畅的游戏体验
- 强大的UI系统：丰富的界面控件和交互支持
- 模块化系统：支持项目特定的自定义模块，实现个性化定制
- 真正的跨平台：支持多个主流平台
- Windows
- Linux
- macOS
- Android
- iOS
项目目前处于积极开发中。主要功能已经实现，正在持续优化和完善：
- 基础对话系统
- 角色立绘支持
- 场景管理
- 多平台适配
- 对话记录系统
- 回滚系统
- 选择分支系统
- 存档和读档系统
- 项目模块化系统
- 自动项目创建工具
- 音乐、音效和语音系统
- 场景切换效果
- 转场动画
- 脚本内持久化变量设置
- 更多高级脚本特性
- 性能进一步优化
- 更多平台细节适配
- 自动角色站位，多角色会自动分配位置
- 自动对话框震动，检测到感叹号字符会自动震动
- 自带普通旁白和电影旁白，电影旁白会有上下黑边
- 有单独的存档格式.sakisav，市面已存在的反编译工具目前无法直接支持
- 支持切换深色/浅色模式，就像app一样改变UI的色调
- 随意拉伸窗口，内部画面会自适应
- 无限个存档位
- 支持直接播放webp动图
- 安装 Flutter SDK（建议使用最新稳定版）
- 配置相应平台的开发环境（Android Studio、Xcode等）
# macOS/Linux
./run.sh
# Windows（使用 Git Bash、WSL 或其他 bash 环境）
./run.sh首次运行时会自动：
- 检测您的操作系统（macOS/Linux/Windows）
- 扫描可用的游戏项目
- 让您选择默认游戏项目
- 自动配置并启动项目
- 选择游戏项目
./scripts/select_game.sh- 运行对应平台的传统脚本
# macOS（传统方式）
./scripts/run_legacy_macos.sh
# 或使用 Flutter 命令（需要先处理资源）
cd Engine
flutter run -d macos --dart-define=SAKI_GAME_PATH="$PWD/../Game/YourGameName"直接推送即可。github会自动编译全平台二进制文件。
./build.sh macos
./build.sh linux
./build.sh windows
./build.sh android
./build.sh ios注意： 构建前请确保已使用 ./run.sh 或 ./scripts/select_game.sh 选择了默认游戏项目。
Windows 用户需要使用以下方式之一来运行 shell 脚本：
-
Git Bash（推荐）
- 安装 Git for Windows 后自带
- 右键选择 "Git Bash Here" 然后运行
./run.sh
-
WSL (Windows Subsystem for Linux)
- 在 Microsoft Store 安装 Ubuntu 或其他 Linux 发行版
- 在 WSL 终端中运行脚本
-
PowerShell + bash
- 如果安装了 Git Bash，可在 PowerShell 中运行：
bash ./run.sh
- 如果安装了 Git Bash，可在 PowerShell 中运行：
SakiEngine/
├── run.sh # 统一启动脚本（跨平台）
├── build.sh # 构建脚本（GitHub Action）
├── default_game.txt # 默认游戏配置文件
├── scripts/ # 工具脚本目录
│ ├── select_game.sh # 游戏项目选择器
│ ├── create_new_project.sh # 新项目创建工具
│ ├── run_legacy_macos.sh # 传统macOS启动脚本
│ └── ... # 其他工具脚本
├── Engine/ # Flutter引擎主目录
│ ├── lib/ # 引擎源码
│ │ ├── src/ # 引擎核心代码
│ │ ├── projectname/ # 项目特定模块（自动创建）
│ │ └── main.dart # 主入口
│ ├── tool/ # 开发工具
│ │ └── generate_modules.dart # 模块自动生成器
│ └── pubspec.yaml # 依赖配置
└── Game/ # 游戏项目目录
├── SakiEngine/ # 默认示例游戏
├── SoraNoUta/ # 另一个示例项目
└── YourGame/ # 您的游戏项目（创建工具生成）
SakiEngine 提供了便捷的项目创建工具，可以快速搭建新的视觉小说项目：
./scripts/create_new_project.sh创建工具会自动：
- 创建完整的项目目录结构
- 生成基础的配置文件（角色、姿势、系统配置）
- 创建示例剧情脚本
- 自动生成项目专用的Flutter模块
- 配置主题颜色和Bundle ID
- 更新模块注册表
每个新项目都会自动创建对应的Flutter模块，支持：
- 自定义主题：项目特有的颜色、字体、界面风格
- 自定义界面：主菜单、游戏界面、存档界面等
- 项目配置：特殊的引擎参数和功能开关
- 智能回退：未自定义的组件自动使用引擎默认实现
项目模块位置：Engine/lib/项目名小写/项目名_module.dart
- 创建项目
./scripts/create_new_project.sh- 选择并运行
./run.sh # 选择新创建的项目- 自定义项目模块
# 编辑项目模块文件
Engine/lib/yourproject/yourproject_module.dart项目根目录包含一个专门为 SakiEngine 开发的 VSCode 语法高亮插件 vscode-sakiengine-syntax，支持以下文件类型的语法高亮：
.sks- 剧本文件 (Script Files).sks- 配置文件 (Configuration Files).sks- 坐标管理文件 (Position Management Files).sks- 角色定义文件 (Character Definition Files)
- 在 VSCode 中打开扩展视图
- 选择 "从 VSIX 安装"
- 导航到项目根目录下的
vscode-sakiengine-syntax文件夹 - 选择最新版本的
.vsix文件进行安装
通过这个插件，你可以获得更好的代码编辑体验，包括语法高亮、代码着色等功能，让脚本编写更加直观和高效。
SakiEngine 使用 .sks 脚本文件，语法简单直观，类似 Renpy，但更加简洁：
// 开始标签
label start
// 设置背景场景
scene bg school
// 角色对话（角色标识 姿势 表情 对话）
yk pose2 happy "欢迎来到SakiEngine！"
// 选择菜单
menu
"给她巧克力" choice_chocolate
"保持沉默" choice_silence
"表情测试" choice_expressions
endmenu
// 巧克力选项
label choice_chocolate
yk "呀，谢谢！"
"嘿嘿，喜欢吗？"
yk happy "当然喜欢！"
return
// 沉默选项
label choice_silence
yk sad "你怎么不说话？"
yk "不理你了。"
return
// 表情变化
label choice_expressions
yk pose1 "这是不同的姿势和表情"
yk happy "开心的表情"
yk sad "难过的表情"
return
SakiEngine 支持四种主要的图像显示方式：
// 显示背景图片，自动铺满窗口
scene bg school // 显示学校背景，铺满整个窗口
scene bg sunset_beach // 显示夕阳海滩背景，自动缩放适配
// 显示角色立绘，自动调节窗口内站位
show yk pose1 happy // 显示yk角色，引擎自动分配站位
show alice pose2 sad // 显示alice角色，自动与其他角色协调位置
show character // 多角色同时显示时自动分配最佳站位
// 播放WebP动图，自动铺满窗口，默认播放一次后消失
anime flash_effect // 播放闪光动画，播放完自动消失
anime explosion // 播放爆炸效果，默认一次性播放
// 使用参数控制播放行为
anime rain keep // 播放雨滴动画，播放完后保持显示
anime fire loop // 播放火焰动画，循环播放不停止
anime magic keep loop // 播放魔法效果，循环播放且保持显示
// 显示CG图片，结合scene和show特性：铺满窗口 + 自动识别切换
cg ending_kiss // 显示CG，自动铺满窗口
cg battle_scene // CG会自动识别和切换到对应场景
cg romantic_moment // 支持CG之间的自动过渡和识别
SakiEngine 支持在对话文本中使用特殊标签来控制显示效果：
// 在指定位置暂停文字显示
yk "你好...[w=1]我是小雪。" // 在省略号后暂停1秒
alice "等等[w=5]让我想想..." // 在"等等"后暂停5秒文字显示
// 改变文字大小
"这是[size=1.3]大字[/size]和正常字。" // 显示大字
"[size=0.8]小字提示[/size]正常对话" // 显示小字
"[size=1.5]重要提醒！[/size]" // 显示更大的字
// 跳过打字机效果，瞬间显示文字
"[pass]这段文字会瞬间显示出来！[/pass]" // 整句瞬间显示
"正常显示[pass]后面瞬间显示[/pass]" // 部分瞬间显示
SakiEngine 支持多种场景转场效果，使用 with 转场类型 语法：
// 黑屏淡入淡出转场，经典过渡效果
scene sky with fade // 先淡出到黑屏，再淡入新场景
// 图片直接渐变过渡，无黑屏阶段
scene home with diss // 旧场景溶解到新场景
scene school with dissolve // 支持 dissolve 别名
// 旋转扇形擦除效果，适合时空转换
scene flashback with wipe // 扇形旋转覆盖并显示新场景
// 从黑屏睁眼显示场景，不会遮挡UI
scene bedroom with blink // 适合醒来场景
scene reality with eyeopen // 从梦境/回忆回到现实
scene world with eye // 支持简写别名
睁眼转场特点：
- 🎬 从完全黑屏开始（已经闭眼状态）
- 👁️ 上下遮罩移开，逐渐显示新场景
- ✅ 不会遮挡UI（对话框、菜单等保持可见）
- 💡 只有睁眼过程，没有闭眼过程
睁眼转场适用场景：
- 💤 角色从睡梦中醒来
- 👁️ 失去意识后恢复
- 🔄 从回忆/幻觉回到现实
- ⚡ 从黑屏过渡到新场景
| 转场类型 | 关键词 | 视觉效果 | 是否遮挡UI | 适用场景 |
|---|---|---|---|---|
| 淡入淡出 | fade |
黑屏渐变 | ✅ 遮挡 | 通用场景切换 |
| 溶解 | diss, dissolve |
图片直接渐变 | ❌ 不遮挡 | 平滑的场景过渡 |
| 擦除 | wipe |
旋转扇形擦除 | ✅ 遮挡 | 时空转换、特效 |
| 睁眼 | blink, eyeopen, eye |
黑屏入，上下移开 | ❌ 不遮挡 | 醒来、恢复意识 |
- 无需缩进：所有命令都在同一级别
- 使用
//注释：支持单行注释说明 - 简单的角色对话语法：角色名 + 可选姿势 + 可选表情 + 对话内容
- 灵活的图像控制：支持背景、立绘、动画、CG等多种显示方式
- 富文本标签：支持等待、大小、快进等文字效果
- 直观的选择菜单系统：menu/endmenu 包围选择项
本项目使用开源许可证。详细信息请参见 LICENSE 文件。
本项目包含一个既是商业游戏也是开源游戏的游戏项目：《空之歌：每当磁针再次振动，我便在此等待》。
欢迎提交 Issues 和 Pull Requests！