DebugFontKit

DebugFontKit is a C++ CLI for Super Mario Odyssey (SMO) debug text font assets. The executable is named dfkit.

The tool does not install assets or assume a mod layout; it reads and writes the files you specify.

What Are Small and JIS1?

SMO's debug text renderer can use two font asset sets:

• small: compact ASCII atlas, usually named nvn_font.ntx.
• JIS1: larger UTF-16/codepoint atlas, usually named nvn_font_jis1.ntx plus nvn_font_jis1_tbl.bin.

Use small for simple ASCII debug text. Use JIS1 when you need more glyphs, custom private-use icons, or broader text coverage.

Build

Requirements:

• CMake 3.21+
• Ninja
• C++23 compiler

Windows default build:

build.bat

build.bat defaults to windows-msvc. It builds in parallel using %NUMBER_OF_PROCESSORS% jobs. Pass a second argument to override that:

build.bat windows-msvc 8

Presets:

• windows-msvc: Windows, Visual Studio cl.exe. This is the default Windows path.
• windows-clang-cl: Windows, clang-cl with the MSVC ABI.
• linux-gcc: Linux, g++.
• linux-clang: Linux, clang++.
• native: whatever compiler CMake finds in your current shell. Useful for local experiments, less explicit for releases.

Examples:

build.bat windows-clang-cl

cmake --preset linux-gcc
cmake --build --preset linux-gcc

If CMake reports that a cache was created from another source directory, delete out/build/<preset> and build again.

Help

dfkit --help

Full command reference: docs/COMMANDS.md.

Most output paths are optional. If you omit them, the tool writes a default output name. Font/table commands write next to the input file, for example unpack-jis1-png font.ntx writes font.png and map-jis1 table.bin writes table_map.png. render-glyph writes to the current directory.

Quick Examples

Placeholders:

• <small.ntx>: small font file
• <jis1.ntx>: JIS1 font file
• <jis1_tbl.bin>: JIS1 table file
• <atlas.png>: full font atlas image
• <icon.png>: one custom icon image
• <font_file>: TrueType/OpenType/TTC font file
• <out>: output file or folder

Inspect:

dfkit info <jis1.ntx>

Generate a JIS1 layout map without owning any font files:

dfkit map-jis1-default <out.png>

Generate a JIS1 layout map from an existing table:

dfkit map-jis1 <jis1_tbl.bin> <out.png>

Unpack/edit/repack small:

dfkit unpack-small-png <small.ntx> <atlas.png>
dfkit pack-small-png <small.ntx> <atlas.png> [out.ntx|--in-place]

Unpack/edit/repack JIS1:

dfkit unpack-jis1-png <jis1.ntx> <atlas.png>
dfkit pack-jis1-png <jis1.ntx> <atlas.png> [out.ntx|--in-place]

Patch custom icons:

dfkit patch-jis1-icon <jis1.ntx> <jis1_tbl.bin> U+E000 <icon.png> <out.ntx> <out_tbl.bin>
dfkit patch-jis1-icons <jis1.ntx> <jis1_tbl.bin> docs/icons.example.json <out.ntx> <out_tbl.bin>

Font icons in JSON can use render tuning fields such as scale, xScale, yScale, x, y, padding, and fitWidth.

Create fresh assets:

dfkit create-small-from-ttf <font_file> <out_dir>
dfkit create-jis1-from-ttf <font_file> <out_dir>
dfkit create-small-from-png <atlas.png> <out_dir>
dfkit create-jis1-from-png <atlas.png> <out_dir>

Create commands use built-in compatible defaults for the selected font profile, so they do not need an existing .ntx template.

Tune Latin glyphs:

dfkit fit-jis1-latin --extract-preset latin.json
dfkit fit-jis1-latin <jis1.ntx> <jis1_tbl.bin> <font_file> <out.ntx> --use-preset
dfkit fit-jis1-latin <jis1.ntx> <jis1_tbl.bin> <font_file> <out.ntx> --use-config latin.json

Without --use-preset or --use-config, the command measures the current Latin glyphs and searches for a fit with its scoring rules. --use-preset replays the built-in A-Z/a-z tuned values. --extract-preset writes those values as editable JSON without writing a font. Replay edited values with --use-config. The JIS1 table is read to find Latin slots; it is not modified by Latin fitting.

TTF render tuning options for render-font-* and create-*-from-ttf:

--fit-width
--scale N
--x N
--y N
--padding N
--missing-report path

Use --in-place only on copies. It overwrites input files.

Source Layout

src/main.cpp      CLI routing
src/core/         file IO, NTX parsing, image IO, JSON
src/codecs/       BC4 and Tegra/NVN swizzle
src/fonts/        font/table/icon/TTF/create logic
src/generated/    embedded default table and shader bytes
vendor/           lodepng and stb_truetype
docs/             command reference and sample config

Format Notes

Small font:

• 128x128
• format 1
• payload offset 0x200
• payload size 0x4000
• 8-bit grayscale
• block-linear storage, blockHeight=16
• printable ASCII 0x20..0x7E, 16 columns, 8x16 cells

JIS1 font:

• width 1280
• visible/header height 1298
• decoded storage height 1536
• format 0x49 / BC4
• payload offset 0x200
• payload size 0xF0000
• block-linear storage, blockHeight=16
• 64 columns, 20x22 cells

The storage height is padded for texture/block layout and can be larger than the visible/header height.

JIS1 table:

• little-endian UTF-16 codepoint table
• sorted for runtime lookup
• custom private-use icons replace selected table slots; the table remains sorted for runtime lookup

Third-party

DebugFontKit vendors:

• LodePNG by Lode Vandevenne, used for PNG read/write.
• stb_truetype by Sean Barrett / RAD Game Tools and contributors, used for TTF/TTC glyph rendering.

See the headers in vendor/ for the full upstream notices.

License

DebugFontKit is released under the MIT License. See LICENSE.