As of late 2021, we are in the process of updating Stencylpedia and fixing up outdated & broken content. Thanks for your patience!







Using Labels

by Jon (Updated on 2014-01-30)


  • Introduction
  • Installing the Labels Extension
  • Creating a Label
  • Changing a Label's Text and Font
  • Moving a Label Around
  • FAQ



Most games draw text to the screen using our draw blocks. This remains the recommended way of doing things.

However, in some games, it would be nice if text were like an actor, so you could easily tween its position, rotation and opacity. That's what labels are for.

Labels are a special kind of actor that can display text. You can specify a font and text to draw for this actor. Like any other actor, a label has a position, rotation, opacity, and can have behaviors attached to it.

Note: In Stencyl 3.0 and later, it is now OK to draw text directly. You can still use labels (described below), but drawing text directly is simpler and just as performant.


Installing the Labels Extension (Stencyl 3.0 and later)

In Stencyl 3.0+, labels are now housed under an optional extension, rather than a behavior on StencylForge.

1) Go to Settings > Extensions and enable the Labels extension.


2) Close and reopen your game.

3) Open up any Behavior or Event. You'll now find the Label blocks under the Custom category.



How to Create a Label

Labels are mounted to actors. To exist, you must mount them to an actor by applying a label block to them. The following describes the best practice for creating labels.

1) Create a blank Actor with a blank Animation.

2) Add the actor to the desired scene. If you find it inconvenient that the Actor is "invisible", you can assign a dummy animation to the Actor. It won't display in-game.

3) Through events or behaviors, attach a label to the actor using the attach label block under the Custom category.



How to Change a Label’s Text and Font (and more)

After you have attached a label to an actor as decribed above, you can perform operations on it, including...

  • Change the text
  • Change the font
  • Enable text wrapping
  • Set the alignment to left/center/right

These blocks are located under the Custom category, the same one housing the attach label block.

Here's a complete example of the whole process of attaching a label to an actor (via the when created event) and setting some properties.


Tip: Avoid excesssively changing a label's text. This can degrade performance on mobile devices.


How to Move a Label Around (and more)

Labels are actors!

You can move them around just like you’d move a regular actor around, setting the label’s position, setting the label’s speed, or a using motion tween, for example.

You can tween them in other ways - spin them around, fade them out and whatever else suits your needs.



Do labels support text wrapping? How about alignment?

Yes, they do. There's a block for both of these in the Label extension.


Has someone written up a dialog system?

Yes. See this.


How do I support localization?

See this ongoing discussion for ideas.

The gist is that it's easiest if you ask your user what language they prefer, set that in a text Game Attribute and then alter your text based on that value of the Game Attribute. There are ways to automatically pull the locale, but these require code. The discussion covers the exact details.


Disclaimer: Use comments to provide feedback and point out issues with the article (typo, wrong info, etc.). If you're seeking help for your game, please ask a question on the forums. Thanks!


Is there an amount of text you can draw directly before it lags?
1 11 years, 1 month ago

Sign In to Comment