Distance fields are used in LibGDX for being able to make fonts clearer when resizing them, which allows you to have clearer text using just one font size on all devices instead of needing to include several (or have low quality looking text)
LibGDX Wiki Instructions, or what not to do
The LibGDX official wiki does a good job of explaining what and how to use distance field for clearer font in LibGDX: https://github.com/libgdx/libgdx/wiki/Distance-field-fonts, but seems to be unbelievably vague about using the Hiero font tool, with links to 2012 pre- “distance field” versions of hiero, and no apparent way to find or run a version that works. They even so far as to suggest use github to download the entire LibGDX source project, re-compiling it to get access to from the gdx-tools project.
I installed the windows version to connect to github, cloned the repository and downloaded the 1GB source, changed my workspace in eclipse, and tried to compile the source, only to be met with 1000s of compiling errors, hours into getting it to work, and no closer to running a “version of Hiero that supports distance fields”.
How to actually get a supported version of Hiero
Luckily I was able to find an article written by Packt Publishing on how to run Hiero(https://www.packtpub.com/books/content/scaling-friendly-font-rendering-distance-fields).
But it’s actually somewhat simple:
- Download the latest stable version of LibGDX from their site (not through Maven/ Gradle/ GitHub/ Google Code/ flavor of the week, but through the link they say “We strongly discourage using these old release builds….”): http://libgdx.badlogicgames.com/releases/
- Unzip that into a temp folder (or just copy it from the zip into the folder in the next step)
- Create a folder where you want to run Hiero from- prob just a folder in your working directory called “hiero”
- Copy the following files into that folder:
- gdx.jar
- gdx-backend-lwjgl.jar
- gdx-backend-lwjgl-natives.jar
- gdx-natives.jar
- gdx-tools.jar
- Now Right click in the folder, create a new text document, and rename it to: Hiero.bat (Make sure you can see the .jar on the other files in the folder, or you have to turn off “hide extensions for known file types” in windows folder options)
- Open the Hiero.bat by right clicking on it, and opening it with a text editor(right click and hit edit)
- Inside the text document put this: java -cp gdx.jar;gdx-natives.jar;gdx-backend-lwjgl.jar;gdx-backend-lwjgl-natives.jar;gdx-tools.jar com.badlogic.gdx.tools.hiero.Hiero
- Close the text editor and double click on the Hiero.bat, and it should run Hiero! (you should see ‘Distance field’ on the bottom of the effects section on the right side)
Now the LibGDX Wiki can be helpful again!
Now that we actually have a version of Hiero running that we can follow along with the wiki article, the article becomes useful again. Follow the directions under:
Generating the font
I found that this works reasonable for generating fonts down to size 18, with the same values that the wiki uses (spread=4, padding =4 for all, x, y =-8, but scale looked best for me at 24, probably because I used a smaller font size)
The rest of the article was pretty straight forward for me, and I was able to get distance fields working pretty well in the game (low distortion at larger or smaller font size, with minimal artifacts around lowercase t’s, but overall much better than normal scaling).
The only real disadvantage is that I was using Hiero to generate drop shadows to make text more readable before, but distance fields don’t allow you to export it with Hiero (have to clear all effects aside from distance field). The article hints at being able to add directional drop shadows “using the texture’s gradient”, but offers no additional information.
Let me know if you find a way to get drop shadows or other effects working! Text isn’t the central focus of games, but is necessary for a lot of communication, and for now I just put a black transparent box behind any text field to allow it to be readable without drop shadows.
