跳转到内容
ESEngine

位图文本

BitmapText 组件使用预烘焙的位图字体图集（BMFont 格式）渲染文本。与 Text 组件每帧通过 Canvas 2D 光栅化字体不同，BitmapText 直接从预渲染的字形图集在 GPU 上绘制。

属性

属性类型默认值说明
textstring''显示的文本内容
colorColor{r:1, g:1, b:1, a:1}着色 RGBA（0–1）
fontSizenumber1.0相对于字体原始大小的缩放因子
alignnumber0水平对齐：0=左对齐，1=居中，2=右对齐
spacingnumber0字符间额外间距（像素）
layernumber0渲染层级，用于绘制排序
fontnumber0assets.loadBitmapFont() 返回的字体句柄

字体格式

BitmapText 支持两种字体格式：

.fnt（BMFont 文本格式） — 标准 BMFont 文本描述文件，配合 .png 图集图片使用：

assets/
  my-font.fnt
  my-font_0.png

.bmfont（JSON 元数据） — 引用 .fnt 和图集路径的 JSON 文件：

{
  "font": "my-font.fnt",
  "textures": ["my-font_0.png"]
}

两种格式都使用相同的 assets.loadBitmapFont() 调用加载。

LabelAtlas

LabelAtlas 是一种简化的字体创建模式，用于等宽网格字形图集——非常适合计分器、计时器等只需要数字或少量符号的显示场景。所有字形共享相同的单元格大小。

编辑器工作流

  1. 在 Content Browser 中右键 → New → BitmapFont 创建 .bmfont 文件
  2. 在 Content Browser 中选中该字体文件，检查器显示字体编辑面板
  3. 选择 LabelAtlas 类型
  4. 在字形列表中将每个字符映射到图片文件（如 0 → zero.png，1 → one.png）
  5. 点击 Build Atlas — 编辑器将所有字形图片打包为单张图集 PNG 并自动生成 .fnt 文件

生成的字体在运行时通过与标准 BMFont 相同的 loadBitmapFont() 路径加载。

.bmfont 格式（LabelAtlas）

{
  "version": "1.0",
  "type": "label-atlas",
  "glyphs": {
    "0": "digits/zero.png",
    "1": "digits/one.png",
    "2": "digits/two.png"
  },
  "generatedFnt": "my-digits.fnt"
}
字段说明
type"label-atlas" — 告知编辑器使用 LabelAtlas 工作流
glyphs字符 → 图片路径的映射
generatedFnt自动生成的 .fnt 文件路径（由 Build Atlas 创建）

加载位图字体

在启动系统中加载字体，然后将句柄赋给 BitmapText 组件：

import { defineSystem, addStartupSystem, Res } from 'esengine';
import { Assets } from 'esengine';


addStartupSystem(defineSystem(
    [Res(Assets)],
    async (assets) => {
        const font = await assets.loadBitmapFont('assets/my-font.fnt');
        // font 是用于 BitmapText.font 的句柄
    }
));

字体资源 API

方法返回值说明
loadBitmapFont(path)Promise<number>加载 .fnt 或 .bmfont 文件及其纹理，返回字体句柄
getFont(path)number | undefined获取已缓存的字体句柄，未加载则返回 undefined
releaseFont(path)void从内存中释放字体及其纹理

运行时修改 BitmapText

使用 Mut() 查询 BitmapText 组件，在游戏运行时修改文本或样式：

import { defineSystem, addSystem, Query, Mut } from 'esengine';
import { BitmapText } from 'esengine';


addSystem(defineSystem(
    [Query(Mut(BitmapText))],
    (query) => {
        for (const [entity, bitmapText] of query) {
            bitmapText.text = '你好！';
            bitmapText.fontSize = 2.0;
            bitmapText.color = { r: 1, g: 0.8, b: 0, a: 1 };
        }
    }
));

渲染顺序

BitmapText 遵循与 Sprite 相同的绘制排序规则：

  1. Z 坐标 (transform.position.z) — Z 值越小越先绘制（在后面）
  2. Layer (bitmapText.layer) — layer 值越大越在上面

下一步