脚本节点与流程控制

Galgo 的脚本系统由 Script、Node 和 Step 组成。Script 是整部作品的剧情表，Node 是一个可跳转的片段，Step 是片段里的具体动作。

Script 和 Node

script := galgo.NewScript()

script.AddNode("start", []galgo.Step{
    galgo.Text("", "故事开始。"),
    galgo.Jump("chapter_1"),
})

script.AddNode("chapter_1", []galgo.Step{
    galgo.Text("Aria", "欢迎来到第一章。"),
})

Run(script, "start") 会从 start 节点开始。Jump("chapter_1") 会切换到目标节点。

节点 ID 建议使用稳定的英文或拼音，例如 start、chapter_01、aria_route_good。不要用会频繁改动的显示文案当节点 ID。

Step 的阻塞规则

Step 的 Execute(engine *Engine) bool 返回值表示是否阻塞脚本：

• 返回 true：当前 Step 会等待用户操作或交互结束，例如对话、选项、输入框、拖放。
• 返回 false：执行后立刻进入下一步，例如切背景、显示立绘、播放音乐、设置变量。

常见阻塞 Step：

• Text
• TextBubble
• TextWithVoice
• TextBubbleWithVoice
• Choice
• Input
• DragDrop

常见非阻塞 Step：

• Bg
• Sprite
• HideSprite
• PlayBGM
• StopBGM
• PlaySE
• SetVariable
• UnlockAchievement
• Jump
• Camera

Callback 是否阻塞由回调返回值决定。

对话

普通对话：

galgo.Text("Aria", "你好。")

旁白：

galgo.Text("", "窗外传来蝉鸣。")

气泡台词：

galgo.TextBubble("Aria", "这句话会显示在角色附近。")

带语音：

galgo.TextWithVoice("Aria", "我回来了。", "aria_home", "assets/voice/aria_home.ogg")

角色名和文本都会经过 ResolveText，因此可以传翻译 key 或含变量的文本。

背景和立绘

切换背景：

galgo.Bg("classroom", "assets/bg/classroom.png")

显示立绘：

galgo.Sprite("Aria", "aria_happy", "assets/char/aria_happy.png", galgo.PosCenter)

隐藏立绘：

galgo.HideSprite("Aria")

内置位置：

• galgo.PosLeft
• galgo.PosCenter
• galgo.PosRight

Bg 会调用 Engine.SetBackground，成功设置背景时也会解锁同 key 的 CG。

镜头

镜头可以平移和缩放：

galgo.Camera(0, 40, 1.25, 40)

参数含义：

• x：横向偏移。
• y：纵向偏移。
• zoom：缩放倍率，1.0 表示原始大小。
• duration：过渡帧数，0 表示立即生效。

回到默认镜头：

galgo.Camera(0, 0, 1.0, 30)

音频 Step

播放 BGM：

galgo.PlayBGM("school_life", "assets/bgm/school_life.ogg")

停止 BGM：

galgo.StopBGM()

播放音效：

galgo.PlaySE("door", "assets/se/door.ogg")

语音通常跟文本绑定，用 TextWithVoice 或 TextBubbleWithVoice。

选择和跳转

galgo.Choice(
    galgo.ChoiceOption{
        Text:     "陪她回家",
        TargetID: "walk_home",
    },
    galgo.ChoiceOption{
        Text:     "去社团",
        TargetID: "club",
    },
)

ChoiceOption 可以带 Callback：

galgo.ChoiceOption{
    Text:     "接受",
    TargetID: "accepted",
    Callback: func(e *galgo.Engine) {
        e.SetVariable("accepted", true)
    },
}

如果 TargetID 为空，只执行 callback，然后脚本继续走下一步。

Callback

Callback 可以接入任意 Go 逻辑：

galgo.Callback(func(e *galgo.Engine) bool {
    e.Flash(color.RGBA{255, 255, 255, 255}, 20)
    e.Shake(8, 15)
    return false
})

返回 false 表示继续执行后续 Step。返回 true 表示阻塞；这种用法适合你自己在回调中打开某种交互，并在交互完成后手动推进。

推荐脚本组织

小项目可以把脚本写在 main.go。中大型项目建议拆分：

script/
  start.go
  aria_route.go
  endings.go

每个文件暴露一个函数：

func AddAriaRoute(script *galgo.Script) {
    script.AddNode("aria_start", []galgo.Step{
        galgo.Text("Aria", "走吧。"),
    })
}

这样可以避免一个巨大 main.go 难以维护。