NeoKolors.Tui.Fonts
2026.4.0-preview.4
dotnet add package NeoKolors.Tui.Fonts --version 2026.4.0-preview.4
NuGet\Install-Package NeoKolors.Tui.Fonts -Version 2026.4.0-preview.4
<PackageReference Include="NeoKolors.Tui.Fonts" Version="2026.4.0-preview.4" />
<PackageVersion Include="NeoKolors.Tui.Fonts" Version="2026.4.0-preview.4" />
<PackageReference Include="NeoKolors.Tui.Fonts" />
paket add NeoKolors.Tui.Fonts --version 2026.4.0-preview.4
#r "nuget: NeoKolors.Tui.Fonts, 2026.4.0-preview.4"
#:package NeoKolors.Tui.Fonts@2026.4.0-preview.4
#addin nuget:?package=NeoKolors.Tui.Fonts&version=2026.4.0-preview.4&prerelease
#tool nuget:?package=NeoKolors.Tui.Fonts&version=2026.4.0-preview.4&prerelease
NeoKolors.Tui.Fonts
NeoKolors.Tui.Fonts is the core font engine for the NeoKolors Text User Interface (TUI) framework.
It provides parsing, serializing, measuring, and rendering capabilities for stylized ASCII and ANSI
fonts. It enables terminal interfaces to render custom typography, word wrap, alignment, and
formatting with high performance.
Key Features
- Rich Text Rendering: Full support for rendering plain strings and AnsiString values to keep colors, formatting, and styles (strikethrough, underline) intact.
- Custom Font Formats: Supports both raw XML definition directories (easy to edit) and
high-performance pre-compiled MessagePack binary
.nkfassets. - Advanced Spacing Control: Supports variable-width (with custom word spacing and kerning) and monospaced font configurations.
- Ligatures & Alignment Points: Replaces character groups (ligatures) with single composite
glyphs and aligns glyphs using anchor markers (e.g.
+or*) to maintain clean baselines. - Dynamic Layout & Alignment: Handles text wrapping, boundary restrictions, horizontal/vertical alignment (Left, Center, Right; Top, Middle, Bottom), and overflow settings.
- MSBuild Compiler Integration: Provides a CompileFontsTask which compiles XML font representations during target builds.
Core Architecture
The font system is built around several key types:
-
IAsciiFont: The base interface defining string measurement and rendering logic onto a canvas, with support for TextRenderingOptions for detailed alignment and formatting.
- NKFont: The primary implementation of the font system, containing layout, ligature dictionary mapping, character effects (underline, strikethrough), and cell-level rendering.
FontAtlas:
A central registry where active fonts (such as Default or custom loaded fonts) are registered and
resolved.
-
NKFontSerializer: Handles serialization and deserialization, capable of loading XML folders, packaged zip archives, web URIs, or binary streams.
Getting Started
1. Basic Rendering
To render a text string with a custom font onto a canvas:
using Metriks;
using NeoKolors.Tui.Core;
using NeoKolors.Tui.Fonts;
// Get a font from the Atlas
if (FontAtlas.TryGet("Future", out var font))
{
var canvas = new NKCharCanvas(80, 20);
var bounds = new Rect2D(new Point2D(0, 0), new Point2D(80, 20));
// Draw the string with Center alignment
font.DrawString(
"HELLO WORLD",
canvas,
bounds,
new NKStyle(),
HorizontalAlign.CENTER,
VerticalAlign.CENTER
);
}
2. Serialization and Compilation
You can load a font from an XML package or compile it into a binary .nkf file for fast load times:
using NeoKolors.Tui.Fonts;
using NeoKolors.Tui.Fonts.Serialization;
// Load font from an XML directory
NKFont? xmlFont = NKFontSerializer.DeserializeXml("Paths/MyFontDirectory");
// Serialize font to a binary format (.nkf)
if (xmlFont != null)
{
NKFontSerializer.SerializeBinary(xmlFont, "MyFont.nkf");
}
// Fast deserialization of the binary font file
NKFont? binaryFont = NKFontSerializer.DeserializeBinary("MyFont.nkf");
3. FIGlet Fonts & Metadata Support
NeoKolors supports deserializing FIGlet (.flf) fonts directly. Metadata (author, license, custom
attributes) can be attached and loaded automatically using a hybrid strategy:
- Embedded FIGlet Comments: Extracted directly from the comment lines in the
.flfheader (e.g.Author: ...,License: ...,Date: ...,Year: ...). - Directory Manifest XML (
manifest.xmlorFiglet.manifest.xml): Defines metadata for multiple fonts in a single file:<FigletManifest> <Font Name="Shadow" Author="Glenn Chappell" LicenseType="Attribution / Permissive" SourceFormat="Figlet" Year="1993"> <Description>Shadow font by Glenn Chappell</Description> </Font> </FigletManifest> - Sidecar XML (
<FontName>.meta.xml): Per-font metadata file located next to the.flffile or embedded as a resource:<Font Author="Glenn Chappell" LicenseType="Attribution"> <Metadata> <Year>1993</Year> </Metadata> </Font> - Explicit
FigletMetadata: Passed directly toNKFontSerializer.DeserializeFiglet(..., metadata: customMeta).
The resulting
NKFontInfo
exposes:
SourceFormat: A string identifier ("NKFont","Figlet").Author,LicenseType,LicenseFile,LicenseContent.Metadata: AnIReadOnlyDictionary<string, string>holding arbitrary metadata attributes (accessible viafont.Info.GetMetadata("Year")with case-insensitive key lookup).
Both SourceFormat and Metadata are fully preserved during binary .nkf serialization.
MSBuild Compilation Task
The project implements a custom MSBuild task
CompileFontsTask.
This task is invoked during project compilation to automatically convert source XML font structures
(containing configs, mapping, and text-based .nkg glyphs) into binary Protobuf .nkf files to be
packaged as embedded resources.
Task Properties
| Property | Type | Description |
|---|---|---|
SourceDir |
string |
Base directory containing font source directories (defaults to current directory). |
OutputDir |
string |
Base directory where compiled .nkf files are written (defaults to SourceDir). |
Fonts |
ITaskItem[] |
List of font items to compile. Supports per-item metadata (OutputPath, OutputDir, FontName). If omitted or empty, auto-discovers font folders in SourceDir. |
ForceRebuild |
bool |
When true, forces recompilation of all fonts regardless of whether the output files are up-to-date (default: false). |
OutputFiles |
ITaskItem[] (Output) |
Emits the generated or verified .nkf files with metadata (FontName, LogicalName, SourceDir). |
Example MSBuild Invocation
<CompileFontsTask
SourceDir="$(MSBuildProjectDirectory)"
OutputDir="nkf"
Fonts="@(Font)">
<Output TaskParameter="OutputFiles" ItemName="CompiledFonts" />
</CompileFontsTask>
<ItemGroup>
<EmbeddedResource Include="@(CompiledFonts)">
<LogicalName>$(RootNamespace).%(Filename)%(Extension)</LogicalName>
</EmbeddedResource>
<FileWrites Include="@(CompiledFonts)" />
</ItemGroup>
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
-
net10.0
- JetBrains.Annotations (>= 2026.2.0)
- Metriks (>= 2026.4.0)
- NeoKolors.Common (>= 2026.4.0-preview.4)
- NeoKolors.Extensions (>= 2026.4.0-preview.4)
- NeoKolors.Tui.Core (>= 2026.4.0-preview.4)
- protobuf-net (>= 3.4.30)
-
net11.0
- JetBrains.Annotations (>= 2026.2.0)
- Metriks (>= 2026.4.0)
- NeoKolors.Common (>= 2026.4.0-preview.4)
- NeoKolors.Extensions (>= 2026.4.0-preview.4)
- NeoKolors.Tui.Core (>= 2026.4.0-preview.4)
- protobuf-net (>= 3.4.30)
-
net8.0
- JetBrains.Annotations (>= 2026.2.0)
- Metriks (>= 2026.4.0)
- NeoKolors.Common (>= 2026.4.0-preview.4)
- NeoKolors.Extensions (>= 2026.4.0-preview.4)
- NeoKolors.Tui.Core (>= 2026.4.0-preview.4)
- protobuf-net (>= 3.4.30)
NuGet packages (3)
Showing the top 3 NuGet packages that depend on NeoKolors.Tui.Fonts:
| Package | Downloads |
|---|---|
|
NeoKolors.Tui
Package Description |
|
|
NeoKolors.Tui.Fonts.Assets
Package Description |
|
|
NeoKolors.Tui.Elements
Package Description |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2026.4.0-preview.4 | 71 | 11/15/2026 |
| 2026.4.0-preview.3 | 94 | 11/1/2026 |
| 2026.4.0-preview.2 | 84 | 10/30/2026 |
| 2026.4.0-preview.1 | 89 | 10/23/2026 |
| 2026.2.0-rc2.2 | 96 | 6/8/2026 |
| 2026.2.0-rc2.1 | 102 | 6/5/2026 |
| 2026.2.0-rc2 | 71 | 6/4/2026 |
| 2026.2.0-rc1 | 104 | 6/2/2026 |