How to Use Custom Fonts in Corona
As great as mobile devices are these days, let’s face it, they can’t always come with the exact font that’s just right for your game or app.
Thankfully, with the Corona SDK, you can use custom fonts with minimal hassle. But first, there are a couple prerequisites you must meet before using any custom font (I’ll cover each of the points below in-depth):
- You must have the legal right to use the font.
- iOS: Custom fonts are only supported on version 3.2 and later.
- iOS: You must have the font filename specified in your build.settings file.
Step 1: Initial Settings
Once you have your font file handy (ex. Harrowprint.ttf), you’ll need to first place it in your project directory (the same place your main.lua resides).
Next, there’s a few things you’ll need to add to your build.settings file if your target platform is iOS. If you don’t have that file, just create a blank text file and save it as build.settings (in your project folder) and continue reading.
NOTE: For Android apps, nothing needs to be done apart from including the font in your project folder.
Notice how the exact font filename is specified? This is so iOS knows what file to look for when that specific font is requested by your app. This is the only place you’ll specify the filename (if your target is iOS).
Elsewhere in your project (outside of build.settings), you’ll specify the actual font name (not the filename), but more on that in a moment.
Step 2: Using the Font
Before you use the font, it’s important that you get the exact font name for your custom font. This is often different from the font’s filename that you specified in your build.settings file, so before you do anything, type these two lines into your main.lua file:
for k,v in pairs(sysFonts) do print(v) end
That should output a list of available font names into your terminal. From there, find your custom font and make note of its name (this is case-sensitive). Now you can remove the lines above from your project and use the font!
Android NOTE: Due to platform differences, with Android, you will actually need to specify the FILE name when using the font, rather than the font name.
Here’s an example (iOS):
NOTE: Some fonts do not display for whatever reason. Often, it’s how the font file was built (slightly corrupted—sometimes you get these from free font sites), so if you just can’t get the font to show up (be sure to test on device), then try another custom font to rule out file corruption.
Step 3: Handling Older Devices
Remember, custom fonts only work on iOS version 3.2 and later, but your app might still be available to those using an older version of iOS than that. Here’s an easy workaround:
In the example above, the reason why I check if the user is on the simulator is due to the fact that “platformVersion” will actually return the version of Mac OS X (or Windows) while in the simulator.
You can easily install the font on your desktop OS to have it show up on the simulator, so you really only need to display an alternate font if the user is on device, and is using an older version of iOS.
Free Font Resources
So the prospect of using non-standard fonts in your app sounds appealing does it? Here are a few websites that have plenty of free fonts to keep you busy:
Keep in mind that not all of the fonts on those websites are freely available to use in your apps. Each font listed on Dafont.com let’s you know whether it’s free, paid, or free for personal use only. If you’re ever unsure, you can always contact the owner and get their written permission to use the font in your app.
Many times, the downloaded font archive (usually a zip file) will come with a readme.txt file that let’s you know exactly what you can or can’t do with it.
To avoid potential issues in the future, it’s always best to err on the side of safety and be 100% certain that you can use the font legally before using it in your game or app.
RSS feed
@Jonathan Beebe, thank you for the tutorials! Please keep them coming! Maybe next you can talk about RSS feeds and how to parse them using Corona?
FYI, converting fonts from TTF to OTF can resolve issues as well. I downloaded a completely FREE font, and it would not work in the Xcode sim, nor on any device. After I converted it to an OTF format using a program like FontLab, it worked perfectly. ( Devices I tested on were iPod 2nd gen, 4th gen & iPhone 4 )
Thanks for your suggestion Daniel, I’ve added that to the list
@David Zoeller: Awesome tip! Thanks for sharing. That’ll help out tons of users I’m sure.
Excellent info, thanks so much!
Nicely written Mr. Beebe.
There are a few things that should be pointed out though. Firstly, folks are already asking on the twitterz about how to get fonts on Android. While it’s true that you don’t have to include anything on the build.settings file, for Android you must specify the FILE name, rather than the font NAME.
For ease of use, either rename your file name to be the same as the font name, or use a different name for whether you’re on iOS or Android. For easier ease of use, see the Crawl Space Library… ( crossPlatformFilename )
As a quick note, native.getFontNames() will NOT print anything to your terminal, it only returns the list. You will need to cache that value to a table and the print each value of the table. For ease of use, see the Crawl Space Library ( just write print(“fonts”) )
Lastly, to avoid the inevitable headaches, check your platform version more accurately!! Isn’t it very possible to be running iOS version 4.0.1? That cannot be converted to a number, though our lovely Lua will try to and fail and it will crash your app with not much output for debugging. The best part of that error is that because you’re already checking to see if you’re on the simulator, you’ll never see the error on your computer, but your device will still crash miserably.
Cheers,
a.
@Adam: Thanks for your corrections! I’ve updated the article with the Android information you suggested, and also updated the printing font names and platform-checking code
I don’t understand what – local olderVersion = tonumber(string.sub( platformVersion, 1, 1 )) < 4
and why isn't 'if not onSimulator and olderVersion then' this
'if not onSimulator and olderVersion < 3.2 then' ?
Thanks for any feedback
Hi Tom,
The first line you mentioned will return true or false, depending on if the statement is true or not. Here’s a quick breakdown:
tonumber() – This function converts a string to a number, so the number can be compared (in this case, with the number 4).
string.sub() – This function takes a string (platformVersion), and returns from the 1st character, to the 1st character. I used this so I can determine right off the bat if the user is using less than iOS 4 (since iOS 4 and above can use custom fonts).
The reason why we can’t use “if not onSimulator and olderVersion < 3.2 then…” is — as Adam pointed out — because if a user is on a version such as 3.2.1, which is not a real number, the app will crash because you can’t compare a number with a string (such as “3.2.1″). Therefore, if the user is on less than iOS 4, we take the first 3 characters of the string (using string.sub), and check to see if it is 3.2. If it’s not, we can assume the user’s device doesn’t support custom fonts.
Hope that clarifies things a bit for you! Thanks for your questions as I’m sure it helps other members as well.
Any tips or sites for how to use bitmap fonts? Basically, the whole idea of “jazzing” up a font in Photoshop with drop shadows, outline, beveling, etc – and then being able to use the bitmap font in the app?
Also, if you use a bitmap font, are there other considerations? I imagine there’s something to be said about the size of the letters so that it scales well?
@Thy: It’s a little too in-depth for a comment thread, but there are samples that use bitmap fonts. I recently released the source code to my Tilt Monster game which uses a bitmap font for the score display, and there’s another sample out there that uses it as well (having trouble remembering which one it is at the moment).
What if I look through the native.getFontNames() and I don’t see the custom fonts that I have dropped in? I have placed the file in the project directory, and made the build.settings file as you specified, but the fonts doesn’t show up testing as Android or iOS…
I am testing with King, Aldotheapache, Philosopher, imagine and Telegraphem. I CANNOT get a font that I put in my project folder to show up in that list. And of course it can’t find the font when I try to write with it either. Can you zip a sample workspace?
@GreenCastle: Check out the posts in the Forums. There are several in there with various solutions (though a summary of all the different things to check would be nice to go into the official documentation
. For me, it turned out that I need to do two things: Install the font to my system (not just copy the file), and then do a full shutdown of the simulator (not just a restart).
Thanks, Thy! Works now.
Seems that corona can’t handle all Fonts types equal.
I have the Font Cabin Sketch (http://www.google.com/webfonts/specimen/Cabin+Sketch)
Both in Regular and in Bold.
I copied the fonts in the project folder and created two text labels
display.newText(“The Regular Font”, 160, 90, “Cabin Sketch”, 16)
display.newText(The Bold Font”, 160, 40, “CabinSketch”, 16)
The fonts are named “Cabin Sketch” and “CabinSketch” I fund the names out by calling native.getFontNames()
The Regular font is working as expected but not the bold one. Also the emulator hangs by loading the Bold font.
There is NO font warning displayed in the emulator.
I am also not able to see the fonts on the android device. Calling native.getFontNames() on android
prints a list of fonts but without these two fonts. Also android doesn’t display a Warning that the font which is used can’t be found. Never the less the default font is used.
settings =
{
iphone =
{
plist =
{
CFBundleIconFile = “Icon.png”,
CFBundleIconFiles = {“icon.png”},
UIAppFonts ={“Harrowprint.ttf”,
“CabinSketch-Bold.ttf”,
“CabinSketch-Regular.ttf”}
},
},
androidPermissions =
{
“android.permission.VIBRATE”,
“android.permission.INTERNET”
},
}
I ran into a problem with nearly all custom fonts not displaying in Windows or OSX. System fonts like Arial, Arial Black, Times New Roman, etc. would all display, but nothing custom.
Finally, I tried building it for the XCode simulator, and that worked. The fonts showed up.
I’ve done step by step this tutorial…
and does not work for me, i’m using the “Nexus One” emulator, and installing the apk in my Android phone, and does not show the custom Font anyway….
Please, Help Me !
I’ve done step by step this tutorial… TOO!
And does not work for me neither!
It’s not work even in simulator.
Following is my situation.
None of the three text show with proper font.
All three only display with small default font.
I’ve also tried one by one font respectively without success.
What’s wrong with it??
[main.lua]
display.setStatusBar( display.HiddenStatusBar )
display.newText(“Harrowprint Font”, 0, 0, “Harrowprint”, 64)
display.newText(“GAMECUBEN Font”, 100, 100, “GAMECUBEN”, 64)
display.newText(“SAF Font”, 100, 200, “SAF”, 64)
[build.settings]
settings =
{
iphone =
{
plist =
{
UIAppFonts =
{
“Harrowprint.ttf”,
“gamecuben.ttf”,
“SAF.otf”
}
},
},
}
[my files]
main.lua
build.settings
Harrowprint.ttf
gamecuben.ttf
SAF.otf
Oh, I found the reason why it is not working!
I’ve tested only my simulator.
on simulator non of them worked.
But it works on my iPhone device.
And on Android, “Harrowprint.ttf” works, but “gamecuben.ttf” and SAF.otf didn’t.
*********************
[ this work on device only ]
*********************
hi，I’ve done step by step this tutorial,but it is not work whether simulator or my Galaxy Nexus,where am i wrong?is anywhere need more notifaction,eg if the font is chinese(simplified) what need i do ?
You also have to make sure u’ve got installed the font on your OS…having font only in the root folder of your project isn’t enough.
Well, lost lots of time to make custom fonts working.
1) To make it work in the emulator you have to install the font on the PC (restart the emulator after that)
2) the Android NOTE (use font filename) is not working for me BUT if I use the font name it works
My conclusion:
Always use the FONT NAME.
You get it with this code
local sysFonts = native.getFontNames()
for k,v in pairs(sysFonts) do print(v) end
Another case study:
(Using Corona SDK 704b from 2012-03-20.)
I used the font “Fava Black” from here:
http://www.dafont.com/fava.font
The filename is “Fava-black.ttf”.
In order to see it in the Windows Simulator, I first had to install the font on the system. (Right-click on the .ttf file, “Install”.)
Using “native.getFontNames()” in the Windows simulator returns “Fava” as the name for this font.
Using “native.getFontNames()” on Android only returned names for the preinstalled fonts.
Using “Fava” with the “newRetinaText()” function, it works in the Windows simulator, but not on the Android device. Using the filename, “Fava-black.ttf”, doesn’t work either. But this works on Android: “Fava-black”.
So, in order to check whether the code runs on Android or not, I use this:
– use global variable Font when using newRetinaText()
if system.getInfo(“platformName”) == “Android” then
Font = “Fava-black”
else
Font = “Fava”
end
display.newRetinaText(“Hello”, 50, 50, Font, 24)
I’ve hit a wall with custom fonts in my project and I’m really at a loss as to what to do (short of just using default fonts). I’m trying to use the fonts “Helsinki” (found at http://www.dafont.com/helsinki.font) and “Playtime with Hot Toddies” (found at http://www.fontsquirrel.com/fonts/Playtime-With-Hot-Toddies).
I’ve followed all the steps and tricks I’ve been able to find online (here and elsewhere) and nothing has shown up either in simulator or device. I’ve tried using Harrowprint but that hasn’t shown up either. I’m wondering if it might be in the build settings, which can be found below.
– Supported values for orientation:
– portrait, portraitUpsideDown, landscapeLeft, landscapeRight
settings =
{
orientation =
{
default = “landscapeRight”,
supported = { “landscapeRight”, }
},
iphone =
{
plist =
{
UIStatusBarHidden = false,
UIPrerenderedIcon = true, — set to false for “shine” overlay
UIApplicationExitsOnSuspend = true,
UIAppFonts =
{
“Helsinki.ttf”
“Playtime With Hot Toddies.ttf”
“PlaytimeOblique.otf”
“Harrowprint.ttf”
},
},
},
–[[ For Android:
androidPermissions = {
"android.permission.INTERNET",
},
]]–
}
Any thoughts? Thank you in advance for the help!
Stephen,
it looks like you have forget some “,” in your settings.
Try with :
UIAppFonts =
{
“Helsinki.ttf”,
“Playtime With Hot Toddies.ttf”,
“PlaytimeOblique.otf”,
“Harrowprint.ttf”
},
That did it Jonathan, thanks! I had some weird problems with my build file (the UIAppFonts block was crashing my program) but I managed to get it and my fonts working. Thanks for your help!