渲染钩子和屏幕覆盖

Galgo 提供两类 UI 扩展方式：局部渲染钩子和完整屏幕覆盖。优先使用粒度更小的配置，只有默认系统无法满足时再覆盖整屏。

渲染钩子

Config.Hooks 提供几个关键绘制点：

galgo.Config{
    Hooks: galgo.Hooks{
        OnDrawBackground: func(screen *ebiten.Image, bgKey, bgPath string, alpha float64) bool {
            return false
        },
        OnDrawSprite: func(screen *ebiten.Image, sprite *galgo.SpriteRuntimeState) bool {
            return false
        },
        OnDrawDialogueBox: func(screen *ebiten.Image, x, y, w, h float64) bool {
            return false
        },
        OnPostProcess: func(screen *ebiten.Image) {
        },
    },
}

返回 true 表示你已经完成该部分绘制，引擎会跳过默认绘制。返回 false 表示继续默认绘制。

背景钩子

适合做自定义转场、滤镜、动态背景：

OnDrawBackground: func(screen *ebiten.Image, bgKey, bgPath string, alpha float64) bool {
    if bgKey != "dream" {
        return false
    }
    screen.Fill(color.RGBA{12, 10, 28, 255})
    return true
}

立绘钩子

适合做角色描边、特殊位置、额外动画：

OnDrawSprite: func(screen *ebiten.Image, sprite *galgo.SpriteRuntimeState) bool {
    if sprite.CharacterName != "Aria" {
        return false
    }
    return false
}

如果你只是想注册眨眼/说话变体，优先用：

engine.RegisterCharacterVariants("Aria", "aria_blink", "assets/aria_blink.png", "aria_talk", "assets/aria_talk.png")

对话框钩子

接管对话框背景，但保留文字绘制：

OnDrawDialogueBox: func(screen *ebiten.Image, x, y, w, h float64) bool {
    vector.DrawFilledRect(screen, float32(x), float32(y), float32(w), float32(h), color.RGBA{0, 0, 0, 180}, true)
    return true
}

后处理

OnPostProcess 在整帧绘制之后执行，适合边框、扫描线、色调覆盖、debug 信息：

OnPostProcess: func(screen *ebiten.Image) {
    w, h := float32(screen.Bounds().Dx()), float32(screen.Bounds().Dy())
    vector.StrokeRect(screen, 4, 4, w-8, h-8, 2, color.RGBA{244, 63, 94, 90}, true)
}

屏幕覆盖注册

ScreenRegistry 允许注册特殊屏幕覆盖：

engine.Screens.Register(galgo.ScreenPreferences, &galgo.ScreenOverride{
    Render: func(e *galgo.Engine, screen interface{}) bool {
        img := screen.(*ebiten.Image)
        img.Fill(color.RGBA{0, 0, 0, 255})
        return true
    },
    HandleClick: func(e *galgo.Engine, cx, cy int) bool {
        return true
    },
})

特殊屏幕名包括：

• ScreenSay
• ScreenChoice
• ScreenMainMenu
• ScreenGameMenu
• ScreenSave
• ScreenLoad
• ScreenPreferences
• ScreenHistory
• ScreenConfirm
• ScreenNotify
• ScreenCGGallery
• ScreenMusicGallery
• ScreenAchievements

选择扩展方式

推荐优先级：

1. 只是颜色、尺寸、圆角：改 style.UIStyle。
2. 标题页按钮或首页模块：改 Config.TitleMenu。
3. 设置页分组、组件、排序：改 Config.Settings。
4. 背景、立绘、对话框局部绘制：用 Config.Hooks。
5. 完全不同的整屏 UI：用 ScreenRegistry。

这样扩展成本最低，也最不容易被后续引擎更新影响。