sprite
game/sprite 负责加载打包好的精灵图集、按固定步长播放帧动画,并按 Z 顺序将精灵批次绘制到 NSGo 的 core.Canvas 中。
import "github.com/nsgo-dev/game/packages/game/sprite"
从 TexturePacker 和 Aseprite 加载图集
Atlas 把一张打包图片(Image)、按名称索引的帧(Frames)和可选的按名称索引的动画(Animations)组合在一起。
LoadAtlas(img, data) 读取以下工具导出的 JSON:
- TexturePacker:“JSON (Hash)” 和 “JSON (Array)”
- Aseprite:
json-hash和json-array(开启 frame tags 导出后会自动填充Animations)
把打包好的 PNG 放到 resources/ 下供 NSGo 以 "asset:..." 加载,用 //go:embed 将 JSON 直接嵌入二进制:
//go:embed resources/hero.json
var heroJSON []byte
atlas, err := sprite.LoadAtlas(core.Src("asset:hero.png"), heroJSON)
if err != nil {
return err
}
导出设置与缩放
- 关闭旋转:
LoadAtlas会拒绝被打包工具旋转过的帧并返回错误。 - 帧名称唯一:重复的帧名称会返回错误。
- 高倍图(
meta.scale):所有帧矩形、偏移量和原始尺寸都会除以meta.scale(默认为1)。以"scale": "2"导出的 2x 图集会换算为 1x 点坐标,与 NSGo 的点坐标系一致。
手写图集
对于简单的规则精灵表、原型或测试,可以直接手写 Atlas 字面量,不需要 JSON:
sheet := &sprite.Atlas{
Image: core.Src("asset:sheet.png"),
Frames: map[string]sprite.Frame{
"hero": {Name: "hero", X: 0, Y: 0, W: 16, H: 16, Width: 16, Height: 16},
"coin": {Name: "coin", X: 16, Y: 0, W: 8, H: 10, OffsetX: 4, OffsetY: 3, Width: 16, Height: 16},
},
}
裁剪帧(Trimmed frames)
打包工具通常会裁掉每帧四周的透明边缘以节省图集空间。Frame 同时记录图集里的裁剪矩形和未裁剪时的原始画框:
type Frame struct {
Name string
X, Y, W, H float32 // 图集图片中的裁剪矩形,单位为点
OffsetX, OffsetY float32 // 裁剪矩形在未裁剪画框内的偏移
Width, Height float32 // 未裁剪时的帧尺寸(未裁剪时等于 W、H)
}
Sprite 的 OriginX、OriginY、FlipX、FlipY、旋转和缩放都以未裁剪画框(Width、Height)为准。因此裁剪透明边缘绝不会让角色在切换动画帧时脚底漂移或错位。
Animation
Animation 依次播放一组 AnimationFrame,每帧都有自己的 Duration,在 game.Loop.Update 中通过 Update(dt) 推进:
type Animation struct {
Frames []AnimationFrame
Loop bool
// ...
}
type AnimationFrame struct {
Frame Frame
Duration time.Duration
}
Animation 是一个保存播放状态(当前帧索引、已播放时长和完成标志)的值类型。从 atlas.Animations 复制一份给每个实体,就能各自独立播放:
walk := atlas.Animations["walk"]
attack := atlas.Animations["attack"]
Animation 的方法:
Update(dt):向前推进dt,跨过dt所覆盖的所有帧(乃至多个完整循环)。Frame():返回当前显示的Frame(无帧时返回零值Frame)。Index():返回当前帧在Frames中的索引。Done():报告不循环的动画是否已经把最后一帧显示满该帧的时长。Reset():重置到第 0 帧并清除Done()。
Aseprite 帧标签
加载 Aseprite 导出文件时,meta.frameTags 中的每个标签都会成为 atlas.Animations 中的一项:
- 每帧时长取自导出数据中的毫秒数
duration(标签覆盖的每一帧都必须有正的时长)。 - 支持的播放方向:
"forward"(默认)、"reverse"、"pingpong"和"pingpong_reverse"。 - 未设置
repeat(或repeat: 0)时Loop为true;设置了repeat: N时展开为播放N趟的非循环动画(Loop: false)。往返(ping-pong)标签把每一趟计作一次重复,且折返端点的帧不会连续显示两次。
手写动画
对于不带帧标签的 TexturePacker 图集,可以从 atlas.Frames 手动组装 Animation:
spin := sprite.Animation{
Loop: true,
Frames: []sprite.AnimationFrame{
{Frame: atlas.Frames["coin_0.png"], Duration: 100 * time.Millisecond},
{Frame: atlas.Frames["coin_1.png"], Duration: 100 * time.Millisecond},
{Frame: atlas.Frames["coin_2.png"], Duration: 100 * time.Millisecond},
},
}
Sprite 摆放与变换
Sprite 把一帧放到 core.Drawing 中。它的零值 ScaleX、ScaleY 和 Alpha 都是 0,所以不会绘制任何内容;用 sprite.NewSprite(frame) 可以得到原始尺寸(1, 1)、完全不透明(1)的精灵:
hero := sprite.NewSprite(walk.Frame())
hero.OriginX = hero.Frame.Width / 2
hero.OriginY = hero.Frame.Height // 把原点锚定在角色脚底
hero.X, hero.Y = 120, 200
Sprite 的字段:
| 字段 | 含义 |
|---|---|
Frame |
当前要绘制的 Frame;零值帧(W <= 0 或 H <= 0)不绘制。 |
X、Y |
精灵原点在绘图中的坐标,单位为点。 |
OriginX、OriginY |
未裁剪帧内的锚点,从左上角起算。 |
Rotation |
绕原点顺时针旋转的弧度。 |
ScaleX、ScaleY |
绕原点的缩放比例;负值表示绕原点镜像;0 不绘制。 |
FlipX、FlipY |
在摆放前将画面在未裁剪画框内左右/上下翻转,原点位置保持不变。 |
Alpha |
不透明度,范围 [0, 1];<= 0 不绘制。绘制该精灵时会替换当前绘图的透明度。 |
Z |
批次中的前后顺序;Z 越大越靠前绘制。 |
精灵暂时还不支持着色(#29)。
Batch 与 Z 排序
Batch 把来自同一个 Atlas 的一组精灵绘制到 *core.Drawing 中:
batch := &sprite.Batch{
Atlas: atlas,
Sprites: []*sprite.Sprite{&shadow, &hero, &weapon},
}
// 在 core.Canvas.Draw 中:
batch.Draw(d)
- 排序:
Draw在内部临时切片上按Z从小到大做稳定排序(Z最小的先画,Z相同的保持Sprites中的顺序)。batch.Sprites本身的顺序不会被修改。 - 绘图状态:
Draw会把d的变换矩阵和透明度恢复成绘制前的样子,仅对发生旋转、镜像或半透明的精灵使用Save/Restore。无旋转、无镜像且完全不透明的精灵会直接绘制,不额外压入变换。 - 绘制调用:目前每个可见精灵调用一次
DrawImageFrom;改用 NSGo 的批量DrawAtlas见 #28。
使用 nsgotest 测试
因为 Batch.Draw 记录的是 core.Canvas 上普通的 core.DrawOp 指令,你可以用 nsgotest 无头检查批次实际绘制了什么:
app := nsgotest.Start(t, func(cx *core.Scope) core.Node {
return core.Canvas{
TestID: "stage",
Style: core.Style{Width: core.Pt(320), Height: core.Pt(240)},
Draw: func(d *core.Drawing, _ core.Size) {
batch.Draw(d)
},
}
})
ops := app.Find("stage").Ops
if len(ops) == 0 {
t.Fatal("expected sprite draw operations")
}