Tutorial:Fonts and Text

Adding and using fonts in LÖVE isn't very complicated, but what you have to keep in mind is that you need to set the font before you can use it. There is no way to render text directly from a font object, it must always be done via the love.graphics.draw() function which will render text based on the current font. There are three types of fonts available in love:

• The default font (Bitstream Vera Sans)
• Any font file supported by FreeType 2
• An image containing glyphs (ImageFont)

Creating a font object using the default font

The default font is available for everyone and anyone and can be created using the following code:

font = love.graphics.newFont(14) -- the number denotes the font size

Creating a font object using a font file

Font files are just normal files that you download from the internet (or create yourself) that contains font information. They can be used just like the default font, just that you specify the filepath along with the font size:

font = love.graphics.newFont("AwesomeFont.ttf", 15)
Keep in mind the that some fonts you download come with restrictions on when/how you can use them.

Creating a font object using an image

An image font is a little tougher to explain, as it all depends on a specifically formatted image. If you look at this example image you will see that it contains glyphs along one row, each separated by a specific color. This color is used to separate the glyphs and needs to be found at between every character and at the beginning of the list (all the way to the left). Creating a font based on this image would be as follows:

font = love.graphics.newImageFont("imagefont.png",
    " abcdefghijklmnopqrstuvwxyz" ..
    "ABCDEFGHIJKLMNOPQRSTUVWXYZ0" ..
    "123456789.,!?-+/():;%&`'*#=[]\"")

Warning: Make sure that the image starts and also ends with the separation color or else the last character (in this case " ) won't work.

Using the font object

Now that you have created your font object, you need to set it as the current font before it can be used. That is done with the following code:

-- font = the font object you made before
love.graphics.setFont(font)

One can also immediately use a TTF-font by calling

love.graphics.setFont(filename, size)

Or, in the case of the default font,

love.graphics.setFont(size)

This latter method is however strongly discouraged. Each time setFont is called without a font object, a new font object is created. Doing so each frame will use up a huge amount of RAM. It's okay if you use it once, but doing it multiple times is a bad idea. Instead, try this:

myFont = love.graphics.newFont(size)
love.graphics.setFont(myFont) -- you can use this line each frame without eating too much memory

Drawing and formatting text

So now that you have your wonderful new font object, you want to use it for something. To draw text, you simply call the love.graphics.print function:

love.graphics.print("This is some awesome text", 100, 100)
You can easily draw numbers as well: 
num = 15
love.graphics.print(num, 100, 150)

The default text rendering function can handle line breaks (the '\n' character) and will draw text aligned to the left:

love.graphics.print("This is the first line\nThis is the second one.\n(and a third)\n\nfifth", 100, 200)

The parameters '100' and '200' are the x- and y-locations of the text, respectively. In LÖVE versions prior to 0.6.0, love.graphics.draw was instead used to draw text.

However, LÖVE can also draw text with word wrapping and alignment by using the more complicated love.graphics.printf function:

love.graphics.printf("A really long sentence which will probably be broken into many pieces by my love.", 500, 100, 250, 'right')

Where, here, the parameters '500' and '100' are x- and y-locations, '250' is the maximum text width, and 'right' is the text alignment.

This way it is relatively easy to draw completely centered text if you pass the width of the window as the word-wrap limit and 0 as the x-position:

love.graphics.printf("This text will be centered no matter what.\n(and you LOVE it)", 0, 400, 800, 'center')

Text will always align to the left by default if you omit the alignment value:

love.graphics.printf("Aligned to the left, yes very much so.", 100, 500, 150)

That is how to draw text. For more information about the specific functions and their use, please visit the documentation.

Note: All fonts (even the image font) will be affected by the current color, there is no need to set the color mode to 'modulate'.