How to Use the Bitmap Text Plugin

Whilst adding text to your game can be done easily using the Textfield game object there are some limitations. You are limited to one line of text, therefore a multiline sentence will need to consist of multiply Textfields. Also you are restricted to web based fonts and formatting. Now there is a new easy way to add text to your games, the BitmapText plugin.

The example below shows the use of this plugin. As the character moves (using the A and D keys) past a sign a BitmapText object appears and disappears. Each one showcases a simple feature of the plugin. The first shows basic text over multiple lines, the second uses a wider object and smaller text and the third uses a new texture to change formatting, font and color.

Download the source code for this example.

Downloading and Adding the Plugin

Download the BitmapText plugin from here. Once you have it downloaded, unzip the folder to the location of your game. We recommend containing all your plugins within a plugin folder. Inside the folder you will find two js files, a readme.txt and an example folder. Read through the readme.txt file to get an overview of the plugin. We will be using the bitmapText-1.0.0.js file for our game as it contains the plugin. There is also a minified version of the plugin if you prefer.

0.6.0 of Kiwi.JS

The latest version of the BitmapText Plugin will only work on 0.6+ versions of Kiwi.JS because of a slight API change! So make sure you are using the latest version of Kiwi.JS

To add the plugin to our game we need to add it as a script to our html file.

We also need to add the plugin to our game’s options variable. Here we specify that we are using one plugin which is called ‘BitmapText’, which corresponds to the unique name located inside the plugin. This will boot the plugin and add it to our game so we can access it easily.

Now that we have added our plugin let’s look at how to use it.

How the Plugin Works

The BitmapText plugin works by splitting an image into a textureAtlas and assigning each cell a unique letter, number or character.

Creating a BitmapText Object

To create a BitmapText object we first need to load in a textureAtlas which our text will be generated from. Any spritesheet or textureAtlas can be used for this, however, note that only mono-spaced fonts can be used as spritesheets. Other fonts will require a JSON file to specify where each letter starts and ends.

Now we can create our object. Creating a BitmapText object requires a state, and atlas, a string of text and an x and y coordinate.

Formatting Your Text

You can change the text property at any time which will update automatically.

Because we are creating the illusion of text on the screen by placing images of letters in an order, the plugin has no concept of where words begin and end. Therefore you may find that your words are split across multiple lines like the following image.


We can easily fix this by adding more spaces between words to fill in the gap to the end of the line. This can allow us to format the text into specific lines and orientations. Usually this just requires a bit of testing to get it right.


Altering the BitmapText Object

Now let’s look at some more advanced formatting. The bitmapText object is essentially a large invisible box which contains a tiled set of images in a specific order. We can change the width of this box using the maxWidth property. This will increase or decrease the amount of letters on each line of the object.

Since the BitmapText is an extended entity it means we can change any of the original entity properties also. We can scale the x and y properties, which enables us to change the size of the font without needing a new texture, and change the alpha value. We can also rotate, move and change the visibility of it.

Using and Creating Different Font Textures

By default a BitmapText object will expect the texture to adhere to the following order, where the numbers correspond to the cell number:

This is useful to know as, for example, when the ‘t’ letter appears in the string the image in cell 45 will be used. However, you can change this.

This changes which cell is used for a specific character and can be useful for creating more unique characters such as £ or ß.

To use a different font simply pass through a different texture when creating the object.


Share the joy
Comments 2

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">