项目概览

Galgo 的目标是提供一个 Go 原生的视觉小说引擎。你用 Go 代码声明脚本、资源、UI 配置和交互逻辑，Galgo 负责运行窗口、绘制场景、处理输入、播放音频、保存进度和展示系统菜单。

适合的项目

Galgo 适合下面这些项目：

• 视觉小说、galgame、剧情互动 demo。
• 需要脚本分支、角色立绘、背景切换、音乐和存档的 2D 叙事项目。
• 希望用 Go 写业务逻辑，而不是引入独立脚本语言的游戏原型。
• 需要把 UI 和流程扩展到比较定制化的项目，例如自定义标题页、设置页组件、画廊和成就。

它不试图成为完整 2D 动作游戏框架。底层 Ebitengine 能做很多事，但 Galgo 的抽象重点是叙事流程和视觉小说常用系统。

核心概念

Engine 是运行时主体。它实现了 Ebitengine 的游戏循环，内部管理资源、音频、脚本、存档、UI、Steamworks 和全局解锁状态。

Config 是初始化入口。窗口大小、标题、字体、UI 样式、启动页、标题页、设置页、画廊、成就、存档目录和 Steamworks 都从这里配置。

Script 是剧情脚本。脚本由多个 Node 组成，每个节点包含一组 Step。Step 可以显示文字、切背景、显示立绘、播放音乐、显示选择、跳转节点、执行 Go 回调等。

ResourceManager 管理图片、字体、音频和外部资源根。它会先查 embed FS，再查本地路径，再查额外资源根。

ScreenAction 和 ScreenValue 是 UI 扩展基础。标题页按钮、设置页按钮、滑块、开关和选项组都可以绑定 action/value。

典型执行流程

1. 创建 style.UIStyle 和 i18n.Translator。
2. 创建 galgo.Config，设置窗口、标题、资源、UI、画廊、成就等。
3. 调用 galgo.NewEngine(config, fs)。
4. 用 galgo.NewScript() 创建脚本。
5. 用 script.AddNode("start", []galgo.Step{...}) 添加节点。
6. 调用 engine.Run(script, "start")。
7. 引擎显示启动页和标题页；玩家点击开始后进入脚本。

默认体验和可扩展点

Galgo 内置了可直接使用的标题页、设置页、存档页、历史页、画廊页和成就页。你可以只改颜色和背景，也可以更深入地自定义：

• 使用 Config.Hooks 替换背景、立绘、对话框或后处理绘制。
• 使用 Config.TitleMenu 自定义首页按钮、排序和首页模块。
• 使用 Config.Settings 自定义设置页分组、组件、排序和交互。
• 使用 engine.Screens.Register 覆盖完整特殊屏幕。
• 在脚本中使用 Callback 直接调用 Go 逻辑。

当前包结构

核心实现位于 internal/galgo。根包 github.com/WindyPear-Team/galgo 保留公开 API，通过类型别名和函数转发对外暴露能力。用户正常导入根包：

import "github.com/WindyPear-Team/galgo"

辅助包保留为公开包：

• github.com/WindyPear-Team/galgo/config
• github.com/WindyPear-Team/galgo/style
• github.com/WindyPear-Team/galgo/i18n
• github.com/WindyPear-Team/galgo/effect

开发建议

新增功能时尽量先判断它属于哪一层：

• 剧情流程能力：加 Step 或 Engine 方法。
• UI 组件能力：优先扩展 ScreenAction、ScreenValue、TitleMenuConfig 或 SettingsConfig。
• 资源加载能力：扩展 ResourceManager。
• 平台能力：独立成子系统，例如 Steamworks。

这样可以避免把所有功能都塞进 Engine 或 ui.go，后续维护会更清晰。