NeoKolors.Tui.Fonts 2026.4.0-preview.4

This is a prerelease version of NeoKolors.Tui.Fonts.
dotnet add package NeoKolors.Tui.Fonts --version 2026.4.0-preview.4
                    
NuGet\Install-Package NeoKolors.Tui.Fonts -Version 2026.4.0-preview.4
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="NeoKolors.Tui.Fonts" Version="2026.4.0-preview.4" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="NeoKolors.Tui.Fonts" Version="2026.4.0-preview.4" />
                    
Directory.Packages.props
<PackageReference Include="NeoKolors.Tui.Fonts" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add NeoKolors.Tui.Fonts --version 2026.4.0-preview.4
                    
#r "nuget: NeoKolors.Tui.Fonts, 2026.4.0-preview.4"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package NeoKolors.Tui.Fonts@2026.4.0-preview.4
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=NeoKolors.Tui.Fonts&version=2026.4.0-preview.4&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=NeoKolors.Tui.Fonts&version=2026.4.0-preview.4&prerelease
                    
Install as a Cake Tool

NeoKolors.Tui.Fonts

Build & Test NuGet Version NuGet Downloads License

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 .nkf assets.
  • 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:

  1. Embedded FIGlet Comments: Extracted directly from the comment lines in the .flf header (e.g. Author: ..., License: ..., Date: ..., Year: ...).
  2. Directory Manifest XML (manifest.xml or Figlet.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>
    
  3. Sidecar XML (<FontName>.meta.xml): Per-font metadata file located next to the .flf file or embedded as a resource:
    <Font Author="Glenn Chappell" LicenseType="Attribution">
        <Metadata>
            <Year>1993</Year>
        </Metadata>
    </Font>
    
  4. Explicit FigletMetadata: Passed directly to NKFontSerializer.DeserializeFiglet(..., metadata: customMeta).

The resulting NKFontInfo exposes:

  • SourceFormat: A string identifier ("NKFont", "Figlet").
  • Author, LicenseType, LicenseFile, LicenseContent.
  • Metadata: An IReadOnlyDictionary<string, string> holding arbitrary metadata attributes (accessible via font.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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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