Custom Blocks

by captaincomic (Updated on 2014-08-03)


  • What are Custom Blocks?
  • How to Make Custom Blocks
  • Using Custom Blocks
  • Global Custom Blocks


What are Custom Blocks?

Programmers: Custom Blocks are equivalent to Functions (or Methods)

A Custom Block is a wrapper block (like the "Always" or "When Created" wrappers) that can hold virtually any blocks that you need it to. You can then use this block anywhere else in the behavior.

So what? What is the benefit of that?

  • Code Reuse - You can reuse the same bunch of code across the behavior. Bugs frequently happen when you copy the same code everywhere, make a change and forget to edit it all the places.
  • Data In/Out - You can pass data (parameters) to a Custom Block and take back a return value.


How to Make Custom Blocks

Let's make a custom block that returns the distance between 2 actors.


Step 1: Getting Started

Pick out the "Event" for Custom Blocks.

You'll now see this.

Custom Blocks Opener


Step 2: Give the block a Name

Self explanatory.


Step 3: Give it Fields (Parameters)

Just click the + button in the block fields and you can select what parameters will be added to the list expected by the Custom Block.


Step 4: Define the Block's Appearnce (some call this a "signature")

This one's tricky to put into words. Basically, this is how the block will appear to the user. The % fields are the blanks in the field. You can see in the Fields table what the % fields are.

Custom Blocks Wrapper


Final Step: Choose a "Return Type"

At the bottom, you can also select a Return Type, which is what will be given back to the behavior whenever this block is used.

Note that you can select None, in which case the block will just perform its actions but not give you anything back.

Programmers: This is equivalent to "void"

In this example, we want the block to calculate the distance between actors and give us back a positive number, so I've selected the Return Type of Number. As a result, the custom block can now be used anywhere a Number attribute would go in the behavior!


Using Custom Blocks

Now that it's been created, you can find the new Custom Block wrapper (shown above) in your behavior at the very bottom below the other wrappers, and the custom block that you use to invoke it is in the palette as shown below.


Custom Blocks reside inside the "Custom" category of the Palette

Notice that there are other custom blocks that I made before, they're listed by the name of the behavior they're created inside of.

You may even notice that one is shaped like the True/False blocks, which is because it returns a Boolean value (which is either true or false, of course).

Custom Blocks Palette


Using a Custom Block

Like any ordinary block, just draw a Custom Block in to use it.

Note: The rest of this section completes the "distance between actors example that the original author started. Feel free to follow along or skip down to "Global Custom Blocks" to continue with the rest.

Now, we still haven't actually done anything yet to tell the custom block to actually DO anything. Below, you can see an image where I've grabbed all the necessary blocks for our needs. Notice there are two arrows that show you how to use the parameters.

You can grab the "Actor1" and "Actor2" blocks from the Custom Block's wrapper and use them inside of it as necessary anywhere an Actor attribute would be used. If you had used different parameter types (such as Number, etc) then you could use those in their appropriate fields instead.

Custom Blocks Detail

Below you can see it in it's final assembled state. Notice that the calculations have been put into a Return block (found under Messaging > Custom Blocks > Return Values) that will return the result of those calculations.

Custom Blocks Assembled

Now you can drag your custom block from the palette anywhere you want to use it! Using this block, I can now measure the X distance between any two actors.

Custom Blocks Final

In this case I set a Number Attribute called "Distance" to the result of the custom block (the returned value), but you could just as easily use it elsewhere where numbers are needed.

Examples would be things like the following:

  1. Inside an IF conditional check that compares the distance between two actors to another number value, such as AI trigger (have the enemy start chasing the player when he gets too close!).
  2. To add the distance values to a list for all enemies in the scene (using the "For each actor of type" wrapper and the "The Actor" block as the second parameter).
  3. As the width of a line or box being drawn between two actors.
  4. Converted to text and displayed on the screen as a measurement.
  5. and many many more!


Global Custom Blocks

Programmers: Global Custom Blocks are equivalent to static functions

Global Custom Blocks are custom blocks that can be "called" from any behavior. You may have noticed this as an option when first creating the custom block.

The catch? You can't refer to any of a behavior's attributes from within the custom block's implementation.

Why do you think this is the case?

A global custom block isn't tied to any behavior at all. It lacks a "home," so it's unable to refer to a behavior's attributes. On the flip side, the advantage to a global custom block is that it can be used from anywhere. This can be convenient for game-wide functionality such modifying the a game's "score."

Disclaimer: All articles are geared towards Stencyl 3.0 and above. 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!


Found a bug when creating a global custom block. When tried to use getter of a game attribute, game gives a compile error, saying getGameAttribute() or whatever that function is called, is an unknown identifier. I believe this shouldn't be the case, since game attributes should be able to be referenced from anywhere.
1 1 year, 3 months ago
Check this topic: http://community.stencyl.com/index. php/topic,29344.0.html
0 1 year, 7 months ago
KelvinZhao: I've clarified the point you raised.
2 1 year, 8 months ago
I saw a Parameter that was named "text" I didn't see it on my stencyl. :(
0 2 years, 1 month ago
@farah you have to make a "custom block" and not a custom event.
0 2 years, 10 months ago
whenever i make a custom event i do not have the option of "number" as a return type or even in block field.and i could not test my game.what to do plz......... help
0 3 years, 1 month ago
I think a little more explanation or perhaps an example can be given for global custom blocks? Seems a little hastily explained in just 1 line "You can't refer to any of a behavior's attributes from within the custom block's implementation. Why do you think this is?". Not too sure what that means...
2 3 years, 3 months ago
Code blocks can also be used inside custom blocks. To refer to the inputs, use the name with two underscores. In the above example, "Actor1" would be referred to as "__Actor1" in a code block. This can make it a bit easier to use code not supported by blocks, especially when sharing on StencylForge to those who may not understand the code at all.
4 3 years, 6 months ago

Sign In to Comment