BGText: A BGE Dynamic Text Utility

Get BGText On GitHub

Hey! Today I bring an utility for BGE game developers: it’s called BGText.

BGText is a Blender Game Engine and UPBGE utility aiming to enhance the experience with text objects.

Video about main features and how to use

BGText being used in an actual game


In the old days of BGE there was a feature known as bitmap text. It allowed you to setup a font texture to a plane, map its UV to a single character, enable the Text option on its material, add an Text property to the object and then show a text based on the property, pretty complicated. Then, it was replaced by the dynamic text, now based on True Type fonts, where you add a text, a property named Text to it and then show a text based on this property.

Although the dynamic texts are much easier to use than the bitmap texts, both have their pros and cons. The main cons are:

  • Bitmap texts

    • No support for latin characters.
    • Pretty hard and clunky to setup, even to make a functional font texture.
  • Dynamic texts

    • Text resolution is frequently a problem.
    • When scaled at runtime, the text must be redrawn, slowing down the engine a lot.
    • The text is bound to be flat, with no custom styles besides the color.
  • Both

    • No support for text alignment and justify.
    • Horizontal and vertical distance between characters are fixed.
    • No automatic text wrapping.

Obs: UPBGE fixed the resolution issues on dynamic texts, allowing you to change its resolution at runtime.

I’ve used dynamic texts over a long time due to its ease, and I know some people that still uses the bitmap text due to the ability to stylize the text with outlines and other stuff. Based on this, I thought to work in some way to overcome those issues.

BGText’s Features

BGText tries to mix the pros and fix most of the cons on bitmap texts and dynamic texts, also providing an easy interface to setup each feature (by using game properties). The main features are:

  • Easy to use, but also complex if you need.
  • Text styles based on textures, so it’s highly customizable.
  • Character size based on each character origin.
  • Horizontal and vertical character offset (distance between characters).
  • Automatic text wrap based on number of characters per line.
  • Left, center and right text alignment (justify).
  • Literal text or Python expressions (a huge time saver!).
  • Color based on predefined color names or RGBA vectors.
  • Static text or updated by an specified interval.
  • Update texts without the need of constant processing with the message UpdateText.
  • UpdateText messages can update All texts or the ones with specific Id properties.

BGText is compatible with both vanilla BGE and UPBGE. BGText uses shape keys actions to switch between character values.

How To Use

It’s simple: on your blend file, link the group BGText from BGText blend file (File > Link), then you’re ready to use it. To setup the text, all you have to do is to add properties to the group instance of BGText, and when you play the game the given properties will be applied.

All the characters on BGText instance will automatically be parented to the group object, so you can do whatever logic you want to on top of the instance, even change the text at runtime (see the use of UpdateText messages below).


BGText can trigger specific actions by using messages. To use this functionality, just send a message with a specific subject and you’re ready to go.

  • Subject: UpdateText
    Description: Updates the text at command without the need of processing the text each frame with the Update property.
    Body: All to update all texts or an Id value to update only texts with this value (see Id property below).


This reference shows which attributes you could use on BGText group instance to change its behavior. You don’t need to add all the attributes, only those you want to setup.

  • Text
    Description: String literal or Python expression (when starting with > character).
    Type: String

  • Size
    Description: Individual character size multiplier.
    Type: Float

  • Offset
    Description: Distance multiplier between each character.
    Type: Float

  • OffsetH
    Description: Horizontal distance multiplier between each character. Overrides Offset.
    Type: Float

  • OffsetV
    Description: Vertical distance multiplier between each character. Overrides Offset.
    Type: Float

  • Wrap
    Description: Number of characters before line break.
    Type: Integer

  • Justify
    Description: Text alignment. Can be left (default), right or center (case insensitive).
    Type: String

  • Update
    Description: Updates values constantly (for example, time or life). The value is the number of skipped frames. If value is less than 0, it disables Update.
    Type: Integer

  • Style
    Description: Which font style (texture) to use in the current text. Currently supports from 1 to 5. Defaults to 1 if style doesn’t exist.
    Type: Integer

  • Color
    Description: Name of color or vector. Currently supports red, green, blue, white, black, yellow, purple, cyan (case insensitive) or a tuple or list like (1, 0.5, 0.1, 1) representing RGBA values.
    Type: String

  • Id
    Description: Identifier of current text. Can be used to update texts with specific identifiers with UpdateText messages.
    Type: String

Known Issues

There’s some issues I noticed when using BGText, so they are on the list to be fixed or amenized on the future.

Script performance is not optimal

For portability reasons, I chose to use the Script mode on Python controller instead of Module mode. This fixes some script import issues and gives freedom for the developer to put BGText blend file wherever it wants to, but it comes with a price. As the Script mode makes the script be parsed at runtime, it’s much slower than the module Mode, and this can be a serious issue when using lots of BGText instances with the Update property. I don’t plan to change the controller mode for the already mentioned reasons, but the script is already in a module format, so if the performance becomes a serious issue to you, you could only change the entry points on the Python controllers of BGText blend file to fit your needs. The comments on the last lines of the will explain what to do.


Font Generator

BGText comes with a text generator utility named fontgen.blend. You can set the font from the object CharacterFont on Blender editor, run BGE’s standalone player, setup the size, offset and position of the characters using the controls and then saving it by pressing Spacebar. It’s simple, but pretty handy to start from a sketch.

Image Overlays

If you want to design your fonts by hand, BGText comes with some image overlays for you. They are at the source directory, and comes with a single overlay (TextStyleOverlay.png, image below) or multiple overlays (directory TextStyleOverlay). Those are useful when you’re working with a image editor that supports layers.

The character’s order is the following:

! " # $ % & ' ( ) * + , - . / 0
1 2 3 4 5 6 7 8 9 : ; < = > ? @
Q R S T U V W X Y Z [ \ ] ^ _ `
a b c d e f g h i j k l m n o p
q r s t u v w x y z { | } ~ ¡ ¢
£ ¥ © ® À Á Â Ã Ç É Ê Í Ñ Ó Ô Õ
Ú Ü à á â ã ç é ê í ñ ó ô õ ú ü

Added a font generator utility, where you can set a font to a single character on Blender editor, run BGE’s standalone player, setup the size, offset and position of the characters using the controls and then saving it by pressing Spacebar. The blend file is named fontgen.blend.

Keep in mind that it simply takes a screenshot, so the resolution of the resulting texture depends on your screen resolution.

1 Like

The fact, that you put some effort in the BGEs Text system definetely deserves some applause! :clap:

I can’t check it out before mid next week (currently just on mobile) though. Nevertheless, it seems you have the skillset and motivation to get also some distance field font rendering implemented, maybe you can have a look if that is somehow feasible. You’d need textures which contain the distance to an actual character shape (the tricky part I guess) and a material node to “alpha out” everything above a certain distance.

1 Like

Thanks! Actually I thought about some ways to implement the font generator (including by using blf or something outside of Blender), but I don’t think I should put that much effort on a helper tool, as its goal is to provide an initial placeholder for the user to design the font texture by its own way. But who knows, maybe I’ll try to make something better someday. :wink:

Hi, can you use a custom font texture that has more colors? Like an outline and shading?
I’m really looking for a custom font that’s not just one color.

Currently not… I’m working in a more advanced version of BGText, containing better features, and different colors in the same text is something possible to include on this version.

Thanks, this dynamic text looks really great. Too bad it can’t handle multi colored textures.

1 Like

Update: BGText v0.0.2

What’s new on this release?

New logic behind characters and new features.

  • New character logic using LibNew and replaceMesh instead of actions and shape keys. This fixes the text blinking when rapidly updating.
  • Use > character at start of text to get text from a Python expression.
  • Id properties identify specific texts.
  • Messages with subject UpdateText will update texts. Message bodies with All will update all texts and bodies with an specific Id will update only the given texts.
  • Text was rotated and transformed.
  • Code refactoring.

Update: BGText v0.0.3

What’s new on this release?

This version is a important bugfix update! If you use the latest version, update to this version.

  • Due to problems with LibFree, the new version of BGText returned to the shape keys method again
  • All the improvements made by the previous version are still present, including the text flickering fix and the new Id and UpdateText features
  • Code refactoring