项目结构

本文说明 Galgo 仓库结构，以及新功能应该放在哪里。

根目录

galgo/
  go.mod
  exports.go
  internal/galgo/
  config/
  style/
  i18n/
  effect/
  example/
  assets/
  docs/
  saves/

exports.go 是根包公开入口。核心实现移动到 internal/galgo 后，根包用类型别名和函数转发保持外部导入路径稳定。

internal/galgo

这里是引擎核心实现。主要文件职责：

• engine.go：Config、Engine、主循环、绘制流程、状态恢复、窗口设置。
• script.go：Script、Node、Step 和所有内置脚本步骤。
• ui.go：默认对话框、菜单、画廊、点击处理等 UI 绘制。
• custom_ui.go：模块化标题页和设置页渲染/点击处理。
• screen.go：ScreenAction、ScreenValue、标题页/设置页配置类型、屏幕覆盖注册。
• resource.go：图片、字体、音频资源查找和缓存。
• audio.go：BGM、SE、Voice 播放和音量。
• save.go：存档结构、读写和 slot 检查。
• variables.go：变量插值和类型读取辅助。
• input.go：文本输入框。
• dragdrop.go：拖放交互。
• gallery.go：CG、BGM、成就解锁状态。
• startup.go：启动页和加载页。
• steam.go、steam_disabled.go、steam_steamworks.go：Steamworks 抽象和平台实现。

公开辅助包

config 包提供偏好设置和存档配置。style 包提供 UI 样式结构。i18n 包提供简单翻译器。effect 包提供文本描边、阴影、发光和渐变绘制辅助。

example

example/main.go 是功能展示项目。它尽量覆盖自定义样式、i18n、启动页、标题页模块、设置页组件、输入框、变量插值、背景、立绘、镜头、拖放、选择分支、成就和画廊。

改动引擎功能时，应尽量把 example 更新成可见示例，而不是只写 API。

文档目录

新增文档建议按主题放入：

• 入门：docs/getting-started/
• 剧情脚本：docs/scripting/
• 资源和音频：docs/resources/
• UI：docs/ui/
• 系统功能：docs/systems/
• 平台集成：docs/integrations/
• API 速查：docs/reference/

增加新功能时的放置建议

新增脚本步骤时，通常修改 internal/galgo/script.go，并在 exports.go 中导出构造函数和类型。

新增默认 UI 行为时，优先考虑 custom_ui.go 或 ui.go。如果是可复用的 UI 交互能力，应尽量抽成 ScreenAction 或 ScreenValue。

新增配置字段时，修改 Config，并补文档和 example。配置字段默认值应在 NewEngine 或对应的 config helper 中处理。