NSGo Game

text

game/text 通过 sprite.Batch 绘制 AngelCode BMFont 位图字体(支持字距调整、自动换行和对齐),并通过 core.Drawing.FillText 绘制平台矢量文本。

import "github.com/nsgo-dev/game/packages/game/text"

位图字体(AngelCode BMFont)

LoadBMFont 和 LoadBMFontImage 支持解析 纯文本 和 XML 两种格式的 AngelCode BMFont .fnt 文件,为每张纹理页构建一个 *sprite.Atlas 并索引字形度量与字距对:

//go:embed resources/pixel.fnt
var pixelFNT []byte

// 单页字体快捷方式:
font, err := text.LoadBMFontImage(core.Src("asset:pixel_0.png"), pixelFNT)
if err != nil {
	return err
}

// 多页字体:
multiFont, err := text.LoadBMFont(multiFNT, func(id int, file string) core.ImageSource {
	return core.Src("asset:fonts/" + file)
})

绘制、换行与对齐

在 core.Canvas.Draw 中调用 font.Draw(d, s, x, y, opts) 绘制位图文字:

font.Draw(d, "PRESS START TO CONTINUE", 160, 120, text.Options{
	MaxWidth:    200,
	Align:       text.AlignCenter,
	Scale:       1,
	Alpha:       0.95,
	LineSpacing: 2,
	Z:           10,
})

Options 字段(零值表示左对齐、缩放为 1、完全不透明且不换行):

字段 行为
MaxWidth 大于 0 时按 MaxWidth 点自动换行,并将 AlignCenter/AlignRight 对齐在 [x, x+MaxWidth] 内;<= 0 时不换行,直接相对 x 对齐(以 x 为中心或右边缘)。
Align AlignLeft(默认)、AlignCenter 或 AlignRight。
Scale 缩放字形位置与尺寸(0 表示 1,负值不绘制)。
Alpha 不透明度 [0, 1](0 表示 1,负值不绘制)。
LineSpacing 行间额外垂直间距,单位为点。
Z 传递给底层 sprite.Batch 中每个字形精灵的 Z 顺序。

测量与自定义字形效果

使用 font.Measure(s, opts) 计算对话框或布局包围盒尺寸,使用 font.Kerning(a, b) 查询字距微调,使用 font.Layout(s, x, y, opts) 获取精确的 []GlyphPlacement 以实现打字机逐字显示或波浪文字等自定义效果:

size := font.Measure(dialogue, text.Options{MaxWidth: 220})
placements := font.Layout(dialogue, boxX, boxY, text.Options{MaxWidth: 220})
for i, g := range placements {
	if i >= visibleChars {
		break
	}
	_ = g // g.Rune, g.Glyph, g.X, g.Y, g.W, g.H, g.Line
}

使用 DrawPlatform 绘制平台文本

需要在游戏画布内绘制多语言文案、中日韩文字或清晰矢量标签时,使用 DrawPlatform 和 MeasurePlatform。它们通过 core.Drawing.FillText 在当前画布变换栈下绘制(可随 screen.Viewport 或 tilemap.Camera 自动缩放),并用 Save/Restore 隔离画笔状态:

style := text.PlatformStyle{
	Font:        core.Font{Size: 14, Weight: core.FontBold},
	Color:       core.RGB(0xf8fafc),
	Align:       text.AlignCenter,
	MaxWidth:    240,
	LineSpacing: 4,
}

boxSize := text.MeasurePlatform(d, "Victory! 胜利!", style)
text.DrawPlatform(d, "Victory! 胜利!", 40, 24, style)
_ = boxSize

PlatformStyle 支持 Font、Color(0 表示沿用画布当前填充色)、Alpha(0 表示 1)、Align、Baseline(默认 core.BaselineAlphabetic)、MaxWidth、LineHeight(<= 0 时使用 d.TextMetrics 测量的行高)以及 LineSpacing。

编辑此页