# texture-font

**Repository Path**: seraph2047/texture-font

## Basic Information

- **Project Name**: texture-font
- **Description**: 游戏用图形文字生成器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-27
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="./app/icons/texture-font-256.png" width="92" alt="Texture Font 图标">
</p>

<h1 align="center">Texture Font</h1>

<p align="center">
  面向游戏 HUD、战斗数值和风格化标题的本地 SDF / BMFont 字体工作台
</p>

<p align="center">
  <code>SDF Atlas</code>
  <code>BMFont</code>
  <code>PNG + JSON</code>
  <code>Multi-Sheet</code>
  <code>GLSL</code>
  <code>.tfontproj</code>
  <code>MCP</code>
  <code>Windows EXE</code>
</p>

![Texture Font 编辑器](./docs/images/editor-overview.png)

Texture Font 把普通 BMFont 工作流中分散的字体取样、字符整理、视觉效果、SDF
生成、图集排版和导出校验收在一个本地编辑器里。它不只生成一张固定颜色的字体图，
还可以把描边、渐变、投影、材质和 SDF 参数写入扩展数据，方便自绘文本组件在运行时
继续调整。

所有字体、项目和导出文件都在本机处理，不依赖远程字体服务。

## 核心能力

| 模块 | 能力 |
| --- | --- |
| 字体与字符 | 系统字体、TTF/OTF/WOFF、常用字符多选、全屏字符集编辑、Excel/CSV/TXT/JSON 中文提取 |
| SDF 与烘焙 | 单通道 SDF、抗锯齿开关、自动紧凑分页、每页最大 `2048 × 2048`、固定分辨率 |
| 视觉样式 | 552 套预设、四段/径向/环形渐变、多层描边与阴影、发光、浮雕、轮廓光、挤出、材质与图案 |
| 多 Sheet 工作簿 | 顶部标签切换、新建、复制、双击命名、独立字体/字符集/样式，所有 Sheet 合并为单 PNG + 单 JSON |
| 游戏输出 | SDF/烘焙 PNG、BMFont `.fnt`、扩展 JSON、参考 GLSL、多页元数据、可编辑 `.tfontproj` |
| 运行时检查 | 默认 `1:1` 像素预览、最高 `100×` 放大、深色/浅色/棋盘格背景、拖动画布 |
| AI 工作流 | 本地 stdio MCP、项目级 skill、系统字体扫描、中文提取、项目修改和导出静态检查 |
| 桌面发布 | Windows/macOS Electron 目录版、Windows ZIP，以及带完整运行时和 SHA-256 的单文件便携 EXE |

## 界面

### 图集预览

自动分页会在 256 / 512 / 1024 / 2048 候选尺寸中选择尽量紧凑的结果，也可以锁定
每张贴图的宽高。预览会直接显示最终样式合成后的图集，并可切回原始 SDF。

![图集预览](./docs/images/atlas-preview.png)

### 国风与游戏配色

样式库分为 21 个类别。国风细分为传统、仙侠、水墨、宫廷、民俗和节气；每种基础
配色提供标准、柔光、深压、霓虹、纯色五种变体。

<p align="center">
  <img src="./docs/images/style-library.png" width="330" alt="国风仙侠样式库">
</p>

样式库支持按描边、渐变、发光和阴影筛选。纯色变体会关闭渐变、外发光、投影和
浮雕，适合需要稳定、轻量输出的静态 BMFont。

## 工作流

![Texture Font 工作流](./docs/images/workflow.png)

1. 通过顶部字体页标签新建、复制或切换 Sheet。
2. 为当前 Sheet 选择本机字体或导入字体文件。
3. 指定字符集，或从表格、文本、JSON 中提取中文。
4. 调整字号、字距、抗锯齿、图集尺寸和视觉样式。
5. 在 `1:1` 运行时预览中检查边缘、基线和缩放效果。
6. 保存 `.tfontproj`，按 Sheet 数量导出单字体包或多字体共享图集。
7. 在目标引擎中验证材质、纹理方向、透明混合和性能。

## 快速开始

环境要求：Node.js 20 或更高版本。

```powershell
git clone https://gitee.com/seraph2047/texture-font.git
cd texture-font
npm install
npm run ui
```

默认打开地址为 `http://localhost:5180`。端口被占用时会自动向后寻找空闲端口。

也可以直接指定端口并打开浏览器：

```powershell
node .\bin\texture-font.js --port 5188 --open
```

## 使用说明

1. 在“字体来源”中选择系统字体，或拖入 TTF/OTF/WOFF。
2. 多选大写字母、小写字母、数字和符号分组，或直接在字符集文本框中编辑。
3. 需要从项目中收集中文时，导入 XLS/XLSX/XLSM、CSV、TXT、JSON/JSONL。
4. 在“字形”面板设置字号、字间距、抗锯齿和图集策略。
5. 在“样式”面板选择预设，或单独调整渐变、描边、阴影、内效果和材质。
6. 切换运行时预览、图集预览和字符表，检查最终结果。
7. 保存 `.tfontproj` 继续编辑，或点击“导出”生成字体 ZIP。

### 字间距

字间距最终写入 BMFont 的 `xadvance`，影响游戏中的排版推进量，不改变 PNG 中字形
本身的像素。大描边会自动增加效果避让，避免相邻字符粘连。

### 渐变

- 垂直线性渐变跨整段文字连续计算。
- 非垂直线性、径向和环形渐变按单个字符计算，避免长字符串产生不可控的横向色阶。

### 静态优先

界面保留 P0/P1/P2 实验效果，但新增样式和 MCP 项目写入默认采用静态方案。动画、
粒子、故障、波动和元素动态需要目标引擎支持对应 shader；普通 BMFont 渲染器不能
直接消费这些动态能力。

## 导出内容

```text
texture-font-1_0.png
texture-font-1.fnt
texture-font-1.json
shader/
├── sdf_font.frag
└── sdf_font.vert
README.txt
```

- `.fnt`：标准 BMFont 字符度量和图集引用。
- `.json`：权威扩展数据，包含 SDF、样式、页和字符矩形。
- `.png`：原始 SDF 图集或烘焙后的 RGBA 图集。
- shader：浏览器参考渲染实现，不是 LayaAir 专用组件。

字段和兼容规则见 [字体导出格式](./docs/font-format.md)。

### 多字体单页包

数字 HUD 的多套样式采用类似 Excel 的多 Sheet 编辑方式。顶部菜单栏横向展示
字体页标签，可新建、复制和直接切换 Sheet；每个 Sheet 都有独立的字体来源、
字符集、字号、模式和样式，最终统一生成一个 PNG 和一个 JSON：

```text
damage.zip
├── damage.png
└── damage.json
```

包内 `damage/gold`、`damage/critical` 等字体分别保留自己的度量、样式和字符矩形，
共享同一张图集。bundle 不导出 `.fnt`，因为标准 BMFont 无法表达多套字体度量共用
一页；需要 FNT 时使用单字体导出。完整契约见
[多字体单页包](./docs/font-format.md#多字体单页包)。

`.tfontproj` v2 会保存全部 Sheet 的完整编辑参数。文件字体仍以内嵌 Data URL
保存，因此重新打开项目后可以继续编辑任意 Sheet，不依赖生成时使用的字体仍安装
在本机。旧版单字体项目会自动迁移成一个 Sheet。

## LayaAir 3 客户端

[`runtime/layaair3`](./runtime/layaair3/README.md) 提供可直接放入 LayaAir 3.4
工程的图像文字组件：

```ts
await TextureFontText.load('battle', {
  jsonUrl: 'resources/font/Battle/battle.json',
  fntUrl: 'resources/font/Battle/battle.fnt',
  pageUrls: ['resources/font/Battle/battle_0.png'],
});

const label = new TextureFontText();
label.font = 'battle';
label.text = '1,024 +250';
label.fontSize = 96;
```

组件以 BMFont 的字符矩形和推进量为布局基线。baked 图集使用普通 LayaAir 材质，
SDF 图集使用 linear 距离纹理和自定义 2D Shader，可在运行时调整填充、渐变、
描边、辉光和投影。单页文字合并为批量三角形命令，不按字符创建节点。

已在真实 LayaAir 3.4.2 WebGL1/WebGL2 构建中完成资源加载、Shader 编译、透明
混合、多实例样式隔离和缩放验证。真机 GPU、WebGPU 与目标游戏项目仍需单独验收。

多字体包加载和调用：

```ts
const damage = await TextureFontPackage.load('damage', {
  jsonUrl: 'resources/font/damage.json',
  pageUrls: ['resources/font/damage.png'],
});

const gold = damage.createText('gold', {
  text: '888 250',
});

const critical = damage.createText('critical', {
  text: '999 888',
});
```

`TextureFontPackage` 是推荐统一入口：JSON 与 PNG 只加载一次，包内所有 Sheet 共享
纹理，再通过 Sheet 的运行时字体 ID 选择样式。

## MCP

仓库内置无第三方 MCP SDK 依赖的本地 stdio server：

```powershell
npm run mcp
```

注册到 Codex：

```powershell
codex mcp add texture-font -- node "D:\MyWorkspaces\codex\tools\texture-font\bin\texture-font-mcp.js"
codex mcp list
```

注册后重启 Codex 或新建任务，即可使用 `texture_font_*` 工具。

| 工具 | 用途 |
| --- | --- |
| `texture_font_get_info` | 读取版本、能力和产品边界 |
| `texture_font_list_styles` | 查询 552 套样式和 21 个分类 |
| `texture_font_create_project` | 创建 `.tfontproj`，支持内嵌字体 |
| `texture_font_read_project` | 读取并校验项目摘要 |
| `texture_font_update_project` | 修改字符集、字体、样式和设置 |
| `texture_font_manage_sheets` | 列出、新增、复制、改名、切换或删除字体 Sheet |
| `texture_font_extract_text` | 从表格、文本和 JSON 提取中文 |
| `texture_font_list_system_fonts` | 扫描 MCP 运行电脑的系统字体 |
| `texture_font_start_editor` | 启动内嵌编辑器并返回 URL |
| `texture_font_inspect_export` | 检查 JSON、PNG、FNT 和导出目录 |

MCP 不执行 Canvas 渲染，也不会把“项目已创建”表述成“图集已生成”。最终生成和
ZIP 导出仍在浏览器编辑器中完成。

完整工具参数、静态效果策略和 ZIP 检查边界见 [MCP 文档](./docs/mcp.md)。

## AI Skill

项目内提供两个层级的 skill：

- [Codex 项目 skill](./.codex/skills/texture-font/SKILL.md)：在仓库内自动发现。
- [可复用 skill](./ai/texture-font/SKILL.md)：用于复制到其他 AI 工作环境。

涉及 LayaAir 时还必须读取
[texture-font-layaair](./.codex/skills/texture-font-layaair/SKILL.md)。

## 桌面入口

开发模式启动 Electron：

```powershell
npm run desktop
```

构建脚本：

```powershell
npm run build:desktop:win
npm run build:desktop:mac:x64
npm run build:desktop:mac:arm64
```

Windows 构建会输出：

- `export/windows-exe/TextureFont-<version>-portable-x64.exe`：单文件便携 EXE。
- `export/windows-exe/TextureFont-<version>-portable-x64.exe.sha256`：SHA-256 校验文件。
- `export/desktop-win-x64/TextureFont-win32-x64/`：含 `TextureFont.exe` 的便携目录。
- `export/TextureFont-<version>-win-x64.zip`：完整便携目录 ZIP。

单文件 EXE 首次运行会解压到
`%LOCALAPPDATA%\TextureFont\Portable\<version>`，后续复用该版本缓存。可用
`--smoke-test` 执行无界面自检并返回退出码。

Windows 单文件启动器基于系统自带的 .NET Framework 4.8，支持 Windows 10/11。
它不会把源码、Node.js 或 Electron 安装步骤暴露给最终用户。

macOS 最终发布包仍需在真实 Mac 上完成启动验证、签名和公证。当前仓库不宣称已
提供签名安装包。Windows EXE 当前也未进行代码签名，首次运行可能触发 SmartScreen
提示。

## 架构

| 路径 | 职责 |
| --- | --- |
| `app/font-core.js` | 字符、装箱、SDF、BMFont、ZIP 纯逻辑 |
| `app/atlas-builder.js` | Canvas 字形测量与图集生成 |
| `app/runtime-preview.js` | WebGL SDF 与 Canvas 烘焙预览 |
| `app/style-library.js` | 21 类、552 套样式预设 |
| `app/main.js` | 编辑器状态、项目、预览和导出流程 |
| `src/server.js` | 本地静态服务、字体扫描和文本提取接口 |
| `src/mcp-server.js` | MCP JSON-RPC、项目工具和导出检查 |
| `desktop/` | Electron 主进程和文件保存桥接 |
| `runtime/layaair3/` | LayaAir 3.4 图像文字组件、SDF Shader 和运行时验收 |
| `build/` | 图标、Electron 打包、ZIP 和 Windows 单文件便携 EXE |
| `tests/` | 核心、浏览器和 MCP 自动化验收 |

## 验证

```powershell
npm test
npm run test:browser
npm run test:all
npm audit --omit=dev
```

重新生成 README 配图：

```powershell
npm run readme:images
```

当前测试覆盖 SDF、BMFont/JSON、ZIP、真实 XLS/XLSX、系统字体解析、MCP stdio、
浏览器画布、项目保存和下载链路。

## 兼容边界

- 原始 SDF PNG 必须由理解距离场的自绘组件采样，普通 BMFont 组件不会自动支持
  SDF 描边。
- 烘焙 PNG + FNT 更接近普通 BMFont 消费方式，但运行时不能无损修改描边和颜色。
- `.fnt` 只描述布局，不包含扩展 JSON 中的全部视觉效果。
- 浏览器 WebGL 预览通过不等于 LayaAir 已接入。
- 动态效果依赖目标引擎的顶点/片元 shader、材质和混合模式支持。
- 尚未完成真实 LayaAir 3.4 工程、真实手机 GPU 和桌面签名包验收。

## 当前限制

- 不支持 MSDF、彩色字面 + 距离场遮罩或 kerning 编辑器。
- 不提供 LayaAir 原生自定义文本组件。
- 不自动把字库转换为完整 Unicode 字符全集，字符集必须明确指定。
- MCP 导出检查只做静态契约验证，不代替引擎渲染验收。

## 文档

- [`.tfontproj` 项目格式](./projectformat.md)
- [运行时导出格式](./docs/font-format.md)
- [MCP 使用说明](./docs/mcp.md)
- [项目规则](./agent.md)
- [验收清单](./checklist.md)
- [文件清单](./filelist.md)

## License

当前项目标记为 `UNLICENSED`。未声明开源许可证，未经授权不得复制、分发或用于
商业发布。