Q3Font

Broken out from Font Conversion & Repair, originally by Fidcal 2009. Made into separate article by Geep, 2024.

TIP: As of 2024, there's a new open-source tool Refont available, that builds on q3font's ability to correct font metrics, but is easier to use.

The third-party "q3font" command-line utility allows creation, inspection, and alteration of font metrics in a font's DAT file. Version 1.52, the final release, is discussed here. For TDM font work, q3font has traditionally been an important tool - and at one time pretty much the only tool - for making changes to a font's binary DAT file. It is still fine for correcting font metrics of a few characters at a time. On the other hand, if planning a wholesale rearrangement or expansion of characters within a bitmap, you are much better off now using either Refont or Font Patcher.

While a Windows utility, q3font runs fine under Wine.

For Conversions from TrueType to DAT and TGA Files

Note - TDM fonters, like Fidcal, generally preferred to use ExportFontToDoom3 for this conversion. This section is here for completeness, and adapted from q3font's readme file.

q3font -create -size <fontsize> <fontname>.ttf

where

• <fontname> is the TrueType font name
• <fontsize> for TDM is one of 12, 24, 48

This renders characters of the given size into

• a "fontimage_<fontsize>.dat" file
• one or more <fontname>_n_<fontsize>.tga files, where n is 0, 1, 2..., as needed.

So for TDM, to get a complete font set of 12 pt, 24 pt, and 48 pt sizes, you'd do this command 3 times.

If you are converting multiple different .ttf files in a common directory, the resulting .dat files, because they don't include the font name, might overwrite each other. By version 1.52, an additional feature addresses that: Use "createex" instead of "create" to generate the .dat filename using the font's name as prefix, rather than standard "fontimage". Additional later command-line options, perhaps of less interest to TDM:

-imagesize <size>
-tcdebug

A q3font (or ExportFontToDoom3) conversion is just the first step for font-making. For TDM, there will be conversion of each .tga to corresponding .dds, and significant bitmap editing (of .tga and/or .dds) using an editor like GIMP or Photoshop. As well as .dat tweaking discussed next.

For Inspection & Correction of DAT files

For Viewing Only

q3font -info -detailed <path to given .dat file>

This creates a compact report, with each codepoint’s data on its own line. It includes an ASCII+ character for each line, though perhaps not from the Windows codepage you’d expect.

To Get the Data in Readable, Editable Form as a FNT File

q3font -decompile <path to given .dat file>

This creates a q3font-specific "<dat-name>.fnt" file, for viewing and altering in a text editor. For each block’s data, every item gets its own line. Unlike the compact report, this does not show an ASCII+ character for each block, only the codepoint integer (regrettably just in decimal form, not hex).

To Move Changed FNT Data Back to a DAT

q3font -compile <path to given .fnt file>

This reverses the -decompile process, to create a <fnt-name>.dat file. Importantly, this decompile/compile cycle leaves .tga/.dds files untouched.

Tools Needed for Successful Correction

You are going to be apply manual corrections to TDM font metric values. Be sure you understand what those metrics mean. See Font Metrics & DAT File Format and Font Bitmaps in DDS Files. It is easy to screw the required calculations up, so be careful and organized!

You are going to need:

• Codepoint tables. At a minimum, an ASCII table or listing, preferably with decimal rather than hex counts. You may also need the custom TDM table in I18N - Charset and whatever codepoint table was in effect during TrueType conversion (e.g., with ExportFont2Doom3). Typical are ISO-8851-1 (Latin 1), Windows-1252 (Western Europe; same as ISO-8851-1 but adds chars in range 128-159), Windows-1250 (Eastern Europe). Google them.
• Often, a calculator (manual or app) capable of showing 6+ digits after the decimal point in the range 0.0 - 1.0. If you need to edit an s, s2, t or t2 value, multiply the original value by 256, to reveal its value in bitmap pixels. Then decide on a revised pixel value, and divide by 256 to get the revised value to enter.

A Simple Example

This example is due to Fidcal, originally found in Font Conversion & Repair. Since the extension ".exe" is being mentioned explicitly, Fidcal is presumably running this under Linux. And under the Wine package, using the "binfmt" feature that allows running Windows programs directly, without having to say "wine q3font.exe...".

Copy the dat file(s) to the q3font folder and use this syntax to get a readable .fnt file:

q3font.exe -decompile fontImage_24.dat

A common problem is this:

Characters have an actual width but they also have a distance value from where they start being 'written' to the start of the next letter (xskip in the readable .fnt files.)

The TrueType font to Doom font convertor named ExportFontToDoom3 appears to calculate this based on the character width (Fidcal's guess.)

If lower case letters have descenders that curl back under the previous letter on the line, eg, f, g, j, p, y (q is OK because it curls forward) then the actual width of the character is greater than the distance from its start point to the start of the next character.

So, ExportFontToDoom3 makes xskip too big in the case of the above letters. Reducing xskip in the .fnt files and restoring them to .dat files cures the problem.

In the readable .fnt files the characters are ASCII numbers.

A to Z are 65 to 90
a to z are 97 to 122
f = 102
g = 103
j = 106
p = 112
y = 121

Search the net for an ascii code list for others, or use "ascii" on the Linux console to get a list.

They fnt file can be converted back to .dat files using...

q3font.exe fontImage_24

You will need to relaunch Doom after each adjustment as there is no quick way to reload fonts.

Example: Say you want to reduce the space after letter j

• q3font.exe -decompile fontImage_24.dat to produce a readable .fnt file
• In the .fnt file search down for the character header, eg, char 106.
• Within the curly brackets below the header are the various values.
• Look for xSkip.
• Say it has a value of 12. Try reducing it to 9 to reduce the offset.
• Convert back to .dat format, reload Dark Mod and check in-game.

Accessing Q3Font

A zip file containing the executable and readme files of the final version 1.52 is available via either:

1. Wolf Files Tools
2. Google Drive direct link, presumably a backup of (1)

Where these are discoverable via...

1. https://www.wolffiles.de/index.php?filebase&fid=1868 , a link described as "Download that currently works" on page https://modwiki.dhewm3.org/GUI_fonts
2. searching for "q3font_1-52.zip" within text file https://github.com/wolffiles/FileBaseIndex/blob/master/README_ET_.md

The source code evidently was never released publicly.

Tool History & Credits

Q3Font is the creation of commercial game developer Arnout 'RR2DO2' van Meer, while he was with Splash Damage, Ltd., a game studio he co-founded. During 2001-2004, Q3Font was developed in parallel with and in support of the idTech3-engine-based "Wolfenstein: Enemy Territory", a multiplayer spinoff of "Return to Castle Wolfenstein". Q3Font uses the FreeType library of that era to read in a TTF file, as well as some id Studio code. The FreeType library is built-in (i.e., static-linked so no dll needed).

For more:

• Original 2001 documentation about Q3Font v1.0, at "Q3F - Power through Teamplay.htm". (The info there is essentially the same as the readme. The link comes from https://modwiki.dhewm3.org/GUI_fonts)
• Version 1.0 exe and readme
• Bug forum during Q3Font development