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!


If you just type in "label" in the search bar, you will find in the Extensions button
0 9 years, 7 months ago
I have installedg the Labels Extension ?but still can't find the Label blocks under the Custom category.what should I do?
0 9 years, 11 months ago
For those of you using the Label Extension and code blocks to create new lines etc, though the documentation says \n is the newline character its actually \\n so the syntax is:
actor.say("Label","_ customBlock_SetLabelText", ["Line1 \\n Line2"]);

That will then display:

Using this type of logic can be useful for the credits in your games.

1 10 years, 2 weeks ago
I've updated the article for 3.0 and tried to address most of the issues raised in the update.
0 10 years, 5 months ago
in S3.0 does it support multiple line text? text wrap?
1 11 years, 3 months ago
Losh started a topic here for those who want to localize games. ( .php/topic,19118.0.html)
0 11 years, 3 months ago
0 11 years, 5 months ago
how do you update "drawing" scripts, like text=attributes?
0 11 years, 7 months ago
can you explain in the "how to change a label's text and font" category, where exactly to put those blocks?

this process is not working at all for me :/

1 12 years, 3 months ago
It's possible to have multiline Text, Alignment and something for i18n?

Would like to use iStencyl for some Multimedia eBook iPad app like one we have already created (

1 12 years, 6 months ago

Sign In to Comment