scene
game/scene 按顺序组合世界空间与屏幕空间图层,在视图坐标中对精灵和自定义绘制项做命中测试,并管理场景生命周期、叠加栈和过渡动画。
import "github.com/nsgo-dev/game/packages/game/scene"
Scene、图层与 Drawable
Scene 持有一个共享的 *tilemap.Camera 和一组按 Order 稳定升序绘制的 *Layer。每个图层可以运行在 SpaceWorld(受 Scene.Camera 变换)或 SpaceScreen(直接以视图坐标绘制,适合 HUD):
sc := scene.NewScene(cam)
terrain := sc.AddLayer(scene.NewLayer("terrain", scene.SpaceWorld, 0))
terrain.AddTilemap(levelMap)
actors := sc.AddLayer(scene.NewLayer("actors", scene.SpaceWorld, 10))
actors.AddBatch(actorBatch)
hud := sc.AddLayer(scene.NewLayer("hud", scene.SpaceScreen, 100))
hud.AddDrawable(scene.NewDrawable(func(d *core.Drawing) {
drawMinimap(d)
}))
- 图层项:通过
AddTilemap、AddBatch、AddDrawable或显式AddItem(scene.Item{...})添加。同一图层内的各项按Z稳定升序绘制。 Drawable:封装自定义Draw、Update、Hit、OnPress和OnTouch回调,自带Z与Visible字段。零值的Visible为false,建议用scene.NewDrawable(fn)创建。Scene.Update(dt)按图层顺序推进Camera、瓦片地图和自定义Drawable;Scene.Draw(d)绘制所有可见图层,并在完成后恢复d的变换与画笔状态。
命中测试与输入派发
Scene.HitTest(p) 按绘制的逆序(最高 Layer.Order 优先,再按最高项/精灵 Z 优先)测试视图坐标点 p:SpaceWorld 图层会先经由 Camera.ViewToWorld 转换,SpaceScreen 图层则直接在视图坐标下判定:
if hit, ok := sc.HitTest(ev.Position); ok {
if hit.Sprite != nil {
selectUnit(hit.Sprite, hit.Point)
}
}
需要获取穿透所有层的命中列表时,使用 HitTestAll(p)(按从顶层到底层排序)。
自定义命中区域与回调
默认情况下,精灵使用其变换后的未裁剪画框做命中测试(SpriteContains / SpriteToLocal)。可用 SetSpriteHit 覆盖判定形状或绑定按压/触摸回调(用 ClearSpriteHit 移除):
sc.SetSpriteHit(&coinSprite, scene.HitOptions{
Hit: scene.SpriteLocalHit(&coinSprite, scene.CircleHit(core.Point{X: 8, Y: 8}, 7)),
OnPress: func(hit scene.HitResult, ev core.PressEvent) {
collectCoin()
},
})
内置的 HitFunc 辅助函数包括 RectHit(bounds)、CircleHit(center, radius)、PolygonHit(vertices...) 和 SpriteLocalHit(sp, local)。将 HitOptions{Ignore: true} 设为 true 可让装饰性精灵忽略点击和触摸。
调用 sc.DispatchPress(ev) 和 sc.DispatchTouch(ev) 可直接把视图事件派发给最顶层的命中目标(若目标只设置了 OnPress 而未设置 OnTouch,DispatchTouch 会在 TouchStart 时回退调用 OnPress)。
Manager、场景栈与过渡动画
Manager 在父级 *core.Scope 下管理 *Controller 场景栈。每个进入的场景都会在 Enter(cx) 中获得独立的子 *core.Scope,在该子作用域下创建的循环、信号、计时器和音频会在场景退出时自动释放:
mgr := scene.NewManager(cx)
play := &scene.Controller{
Scene: gameScene,
Enter: func(scx *core.Scope) {
// 归属本场景子作用域的资源
startLevelMusic(scx)
},
Pause: func() { pauseSimulation() },
Resume: func() { resumeSimulation() },
Exit: func() { cleanupLevel() },
Update: func(dt time.Duration) {
gameScene.Update(dt)
},
}
pauseMenu := &scene.Controller{
Scene: pauseScene,
Transparent: true, // 在下方继续绘制被暂停的场景
}
mgr.Switch(play, scene.Fade(400*time.Millisecond, core.RGB(0x000000)))
// 之后压入暂停界面而不退出主场景:
mgr.Push(pauseMenu)
// 弹出并恢复主场景:
mgr.Pop()
过渡动画
向 mgr.Switch(next, tr) 传入 *Transition:
| 构造函数 | 视觉效果 |
|---|---|
Fade(d, color) |
前半段将旧场景淡出到 color,后半段从 color 淡入新场景(color 为透明或 0 时直接交叉淡化)。 |
Crossfade(d) |
在 d 时长内直接从旧场景交叉淡化到新场景。 |
Wipe(d, dir) |
沿 DirectionLeft、DirectionRight、DirectionUp 或 DirectionDown 方向擦除切换。 |
CustomTransition(d, draw) |
按缓动后的 progress([0, 1])调用自定义绘制函数,并传入 drawOld 与 drawNew。 |
可将 tr.Curve 设为任意 core.Curve 缓动曲线。过渡进行期间(mgr.Transitioning() 为 true),新场景会立即进入,旧场景保留至过渡结束再退出并销毁其子作用域。
在 game.Loop 和 core.Canvas 中驱动管理器:
// 在 Loop.Update 中:
mgr.Update(dt)
// 在 Canvas.Draw 中(自动订阅场景切换与过渡帧):
mgr.Draw(d, size, alpha.Get())