快速开始

本文从零创建一个最小可运行的 Galgo 游戏，并说明 example 如何运行。

环境要求

需要安装 Go。进入仓库根目录后先验证：

go test ./...

运行示例：

go run ./example

如果系统缺少图形环境或音频设备，Ebitengine 运行窗口时可能失败；这属于运行环境问题，编译测试仍可用于验证代码。

最小游戏

package main

import (
    "log"

    "github.com/WindyPear-Team/galgo"
    "github.com/WindyPear-Team/galgo/style"
)

func main() {
    engine, err := galgo.NewEngine(galgo.Config{
        ScreenWidth:     1280,
        ScreenHeight:    720,
        Title:           "My Galgo Game",
        FontSize:        18,
        TypewriterSpeed: 2,
        SaveDir:         "./saves",
        Style:           style.DefaultUIStyle(),
    }, nil)
    if err != nil {
        log.Fatal(err)
    }

    script := galgo.NewScript()
    script.AddNode("start", []galgo.Step{
        galgo.Bg("room", "assets/bg_room.png"),
        galgo.Sprite("heroine", "heroine_smile", "assets/heroine.png", galgo.PosCenter),
        galgo.Text("heroine", "你好，欢迎来到 Galgo。"),
    })

    if err := engine.Run(script, "start"); err != nil {
        log.Fatal(err)
    }
}

NewEngine 的第二个参数是 *embed.FS。如果资源直接从本地文件读取，传 nil 即可。

推荐目录

my-game/
  go.mod
  main.go
  assets/
    bg/
    char/
    bgm/
    se/
    voice/
  saves/

如果资源要打包进二进制，可以使用 embed：

//go:embed assets/*
var assets embed.FS

engine, err := galgo.NewEngine(config, &assets)

注意资源路径要和 embed 中的路径一致，例如 assets/bg/classroom.png。

配置默认值

Config 会自动补一些默认值：

• ScreenWidth 默认 1280。
• ScreenHeight 默认 720。
• Title 默认 Galgo Game。
• FontSize 默认 18。
• SaveDir 默认 ./saves。
• TypewriterSpeed 默认 2。
• Style 未设置时使用 style.DefaultUIStyle()。

如果没有指定 FontPath，Galgo 会尝试找系统字体。找不到可用字体时 NewEngine 会返回错误。

第一个分支

script.AddNode("start", []galgo.Step{
    galgo.Text("Aria", "一起回家吗？"),
    galgo.Choice(
        galgo.ChoiceOption{Text: "好", TargetID: "yes"},
        galgo.ChoiceOption{Text: "不了", TargetID: "no"},
    ),
})

script.AddNode("yes", []galgo.Step{
    galgo.Text("Aria", "那走吧。"),
})

script.AddNode("no", []galgo.Step{
    galgo.Text("Aria", "下次吧。"),
})

Choice 会阻塞脚本，直到玩家点击一个选项。被点击的选项会执行 Callback，然后跳到 TargetID。

常见问题

资源加载失败时，先确认当前工作目录。go run ./example 的工作目录通常是仓库根目录，因此示例资源路径是 assets/bg_classroom.jpg。

文本显示乱码时，优先检查源文件编码和字体。Go 源码应保存为 UTF-8，FontPath 应指向支持目标语言字符的 TTF/TTC/OTF 字体。

如果 UI 看起来太大或太小，先检查 ScreenWidth、ScreenHeight 和样式字段。Galgo 的 UI 默认以 720p 高度做比例缩放。