Skip to content
Text module for LÖVE
Latest commit 452e4d9 Jun 11, 2016 @adonaac committed on GitHub Update
Failed to load latest commit information.
API No commit message Jun 9, 2016 Regenerate CHANGELOG Jul 16, 2015
LICENSE Initial commit Jan 18, 2015 Update Jun 11, 2016
Text.lua No commit message Jun 11, 2016
Text3.lua No commit message Jun 9, 2016
kappa.png No commit message Jun 11, 2016
main.lua No commit message Jun 11, 2016
pixelmix.ttf No commit message Jun 10, 2016
utf8-l.lua ~ Mar 9, 2015
visitor.ttf No commit message Jun 10, 2016


This library is currently undergoing a rewrite and will not work correctly


A character based programmable text module for LÖVE. Simplifies text operations by providing a way for manipulating how each character in a string behaves and is drawn.


The module and the utf8-l files should be dropped on your project and required like so:

Text = require 'Text'

An object is returned and from that you can create multiple text objects.

Table of Contents


Creating a text object

Creates a text object and then updates and draws it:

function love.load()
  text = Text(10, 10, 'Test text')

function love.update(dt)

function love.draw()
  text:draw(10, 10) -- if x, y are omitted here then it will use the x, y passed in the Text object creation step


When creating a text object, a table can be passed as the second argument (after the text string) to specify settings for this text. One of those settings allows to change the text's font:

text = Text(10, 10, 'Popo popO', {
  font ='DJB Almost Perfect.ttf', 72),

popo popo 1

You can use multiple fonts by adding a new font to the configuration table like this:

text = Text(10, 10, '[Popo](bold) [popO](italic)', {
  font ='DJB Almost Perfect.ttf', 72),
  bold ='DJB Almost Perfect Bold.ttf', 72),
  italic ='DJB Almost Perfect Italic.ttf', 72),


You can also create functions that will change the text in some way:

text = Text(10, 10, '[Popo popO](randomColor)', {
  font ='DJB Almost Perfect.ttf', 72),

  randomColor = function(dt, c), 222), math.random(32, 222), math.random(32, 222))

And that should do this:

popo popo 2

All functions defined in this way receive two arguments: dt and c. The first is just the normal dt you see in update functions, the second is the character table, which contains general information about the current character. For instance, if we want to make the character move randomly based on how big its position is in the text string (meaning characters more to the right will move more):

text = Text(10, 10, '[Popo popO](move)', {
  font ='DJB Almost Perfect.ttf', 72),

  move = function(dt, c)
    c.x = c.x + c.position*math.random(-1, 1)/5
    c.y = c.y + c.position*math.random(-1, 1)/5

popo popo 3

Multiple functions

Multiple functions can operate on a single piece of text and multiple pieces of text be created:

text = Text(10, 10, '[Popo](move) [popO](move; rotateScale)', {
  font ='DJB Almost Perfect.ttf', 72),

  move = function(dt, c)
    c.x = c.x + c.position*math.random(-1, 1)/5
    c.y = c.y + c.position*math.random(-1, 1)/5

  rotateScale = function(dt, c)
    c.r = math.random(-1, 1)/10 = math.random(10, 20)/10 = math.random(10, 20)/10

popo popo 4

Init functions

Functions act every update and the character table holds information about each character. If you want to set some state that can be updated or used on the update functions you'll need to use Init functions. They're just like normal functions except they have Init after their name and they only receive the character table as an argument. So, for instance:

text = Text(10, 10, '[Popo popO](shake)', {
  font ='DJB Almost Perfect.ttf', 72),

  shakeInit = function(c)
    c.anchor_x = c.x
    c.anchor_y = c.y

  shake = function(dt, c)
    c.x = c.anchor_x + c.position*math.random(-1, 1)/2
    c.y = c.anchor_y + c.position*math.random(-1, 1)/2

popo popo 5

In this example the shakeInit function gets called as the text object gets created, which means that for every character in the string, the anchor_x, anchor_y attributes are set to the character's initial positions. Then, the shake function gets called every update and uses those values to shake the characters. In the next example, the Init function is used to set some state that will then be changed in the update function:

text = Text(10, 10, '[Popo popO](textbox)', {
  font ='DJB Almost Perfect.ttf', 72),

  textboxInit = function(c)
    c.t = 0

  textbox = function(dt, c)
    c.t = c.t + dt
    local r, g, b, a =, g, b, 0)
    if c.t > c.position*0.2 then, g, b, 255)

popo popo 6

So in this case a textbox effect can be created by setting a time variable for each character and then only drawing that character (alpha = 255) if this time is over a certain value based on its string position.

Passing values to functions

Values can also be passed to functions that are defined to receive them:

text = Text(10, 10, '[Popo popO](color: 222, 222, 222)', {
  font ='DJB Almost Perfect.ttf', 72),

  color = function(dt, c, r, g, b)
    local n_characters = #c.str_text
    local i = n_characters - c.position + i*16*r/255, 32 + i*16*g/255, 32 + i*16*b/255)

popo popo 7

And changing the parameters to color: 222, 111, 222:

popo popo 8

Currently values that can be passed are numbers, strings and booleans. I haven't gotten around to implementing tables yet.

Custom draw function

In case you want to have even more control over how each character is drawn you can also specify a custom draw function:

text = Text(10, 10, 'Popo popO', {
  customDraw = function(x, y, c), (x or c.text.x) + c.x, (y or c.text.y) + c.y, c.r or 0, or 1, or 1, 0, 0)

This function should be named customDraw and it should receive the x, y position as well as the character being drawn. The function above is the default draw call that Popo uses for each character.


[]: brackets are used to envelop a piece of text so that functions can be applied to it

(): parenthesis envelop the functions which specify how the text behaves, they must come right after the brackets

(function): functions with no arguments simply need their name specified

(function1; function2): multiple functions applied to the same brackets are separated by ;

(function: arg1, arg2, ..., argn): multiple arguments are separated by , and start after a :

(function1: arg1, arg2; function2: arg1): multiple functions with arguments just follow the previous definitions

@: the @ character is used to escape special characters in text, for instance:

text = Text('@[Popo popO@]')

Will produce [Popo popO]. To escape @ itself use @@. It's also used to break into a new line via @n.


The text object has a few variables that can be specified on its configuration table:

font: sets the font to be used by default. You can also set other types of fonts directly (bold, bold_italic, italic, light, etc) and they will work like a function inside a tag:

text = Text(10, 10, '[Light text](light) [bold + italic text](bold_italic) normal text', {
  font ='DJB Almost Perfect.ttf', 72),
  light ='DJB Almost Perfect Light.ttf', 72),
  bold_italic ='DJB Almost Perfect Bold Italic.ttf', 72),

line_height: the actual line height drawn in pixels is the multiplication of this number by the font height, so, for instance, if your font is of size 20 and you want the line height to be a bit bigger than that, like, let's say 28, you want to set line_height to 20*x = 28 -> x = 28/20 = 1.4

wrap_width: maximum width in pixels that this text can go, after that it will wrap to the next line

align_right: if wrap_width is set, will align text to the right if set to true

align_center: if wrap_width is set, will align text to the center if set to true

justify: if wrap_width is set, will align text to be perfectly aligned to both left and right if set to true

Here's an example of some of those settings being used:

text = Text(10, 10, 'Popo popO', {
  font ='DJB Almost Perfect.ttf', 72),
  wrap_width = 250,
  justify = true,
  line_height = 2,

The text object also has a few read-only variables:

config: reference to the configuration table passed on this text object's creation

str_text: the text string as it will be printed on the screen

n_lines: the number of lines this text has

new_line_positions: an array containing all new line positions in the text string, so, for instance, if on the first line of this text the character 24 breaks into a new line because wrap_width is set, then the number 24 will be the first value in this array


The character table has a few variables that might be useful:

x, y: the x, y position of the character

r: this character's rotation, isn't set to anything initially

sx, sy: this character's x and y scales, aren't set to anything initially

character: the character string

position: this character's position in relation to the entire string, starts at 1

text: reference to the text object

str_text: the string representation of the text this character belongs to

line: the line number this character belongs to if the text has more than one line


You can do whatever you want with this. See the LICENSE.

Something went wrong with that request. Please try again.