debug
game/debug 为 NSGo 游戏提供开发期调试浮层:快捷键开关的帧耗时柱状图、实时场景/图层检查器,以及世界空间碰撞体与精灵包围盒线框;使用 -tags release 构建时全部裁剪为零开销空操作。
import "github.com/nsgo-dev/game/packages/game/debug"
接入调试浮层与帧耗时图
通过 debug.New 创建 *Overlay,用 WrapLoop 包装 game.Loop,并把 overlay.View(cx) 叠放在游戏画布上方:
overlay := debug.New(debug.Options{
ToggleKey: "F3", // 为空时默认 "F3"
TargetFPS: 60, // 帧耗时图的参考线
LineWidth: 1,
Scenes: func() []debug.SceneSnapshot {
return []debug.SceneSnapshot{
{
Name: "world",
Layers: []debug.LayerSnapshot{
{Name: "terrain", Space: "world", Objects: 1},
{Name: "actors", Space: "world", Objects: len(actorsBatch.Sprites)},
{Name: "hud", Space: "screen", Objects: 3},
},
},
}
},
})
overlay.WrapLoop(loop)
loop.Run(cx)
return core.View{
Style: core.Style{FlexGrow: 1, FlexShrink: 1},
Children: []core.Node{
gameCanvas,
overlay.View(cx), // 在 -tags release 下返回 nil
},
}
WrapLoop(l)会包装l.Update和l.Draw,自动计时并调用RecordFrame(total, update, draw)写入固定容量环形缓冲区FrameStats(FrameHistory = 120帧,每帧零堆分配)。overlay.Stats()暴露FPS()、Average()、Latest()、MaxTotal()、Len()、At(i)、Samples(dst)、Reset()及DrawGraph(d, size, targetFPS),方便在其他位置复用统计数据。- 显示切换:按下
ToggleKey(默认"F3")或调用overlay.Toggle()/overlay.SetVisible(true)。在响应式视图或Canvas.Draw中读取overlay.Visible()会自动订阅开关状态。
绘制碰撞体与精灵包围盒线框
在 core.Canvas.Draw 中保持相机/视口变换生效时绘制调试线框。ShapeOverlay 会自动将 LineWidth 除以当前绘制变换的缩放比例,确保任意相机缩放下线宽始终均匀:
d.Save()
cam.Apply(d)
worldScene.Draw(d)
// 仅在浮层可见时执行,并自动让画布订阅开关切换
overlay.DrawShapes(d, func(s *debug.ShapeOverlay) {
s.DrawBox(d, playerBounds, core.RGB(0x22c55e))
s.DrawCircle(d, aggroX, aggroY, aggroRadius, core.RGB(0xf59e0b))
s.DrawBatchBounds(d, actorsBatch, core.RGB(0x38bdf8))
})
d.Restore()
也可以直接调用 *Overlay 上的快捷方法:DrawBox、DrawCircle、DrawSpriteBounds 与 DrawBatchBounds。
场景检查器
提供实时场景结构有两种方式:
- 拉取模式(
Options.Scenes):若回调中读取了 NSGo signal,检查器会自动响应式刷新;否则随帧记录以及手动调用overlay.RefreshScenes()时刷新。 - 推送模式(
overlay.SetScenes(snapshots)):当Options.Scenes为 nil 时,立即更新检查器列表。
在发布构建中彻底裁剪
发布构建时传入 -tags release:
go build -tags release ./...
启用 -tags release 后,debug.Enabled() 返回 false,Overlay.View(cx) 返回 nil,Overlay、FrameStats 和 ShapeOverlay 的所有方法均替换为空实现,浮层 UI、帧耗时图与线框绘制代码不会被链接进发布包。