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







Custom Blocks

by Jon (Updated on 2015-10-15)


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

What are Custom Blocks?

As its name implies, a custom block is a block you implement yourself. It 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.

What's the benefit of a custom block?

Code Reuse

You can reuse the code across a behavior. Bugs frequently happen when you copy a portion of code and reuse it in other places. If you make a change to one copy and forget to edit all copies, that's a bug waiting to happen.

Data In/Out

You can pass data (parameters) to a Custom Block and take back a return value.

Programmers: Custom Blocks are equivalent to functions / methods.

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.

Events Menu

The custom block will appear in the working area. Click on the Create Custom Block button...

Created Template

You'll now see a dialog like this.

Custom Blocks Opener

Step 2: Give the block a Name

Self explanatory.

Step 3: Give it Fields (Parameters)

Parameters are the values that a block takes in. In this example, the values are the two actors we're trying to calculate the distance between.

First, click the + button...

Adding parameters

Then, pick what type of parameter you want (in this case, both will be Actors) and what the name is. This is the name that will appear in the block itself, so make it descriptive.

Adding parameters

Step 4: Define the Block's Appearance

The spec field describes how the block will appear to the user.

Defining the spec

The % fields correspond to the parameters you defined in Step 3, and to tell what you type in, refer back to the Reference for Block Spec Field column above. In this case, %1 corresponds to Actor1 and %2 corresponds to Actor2.

What the block looks like

Final Step: Choose a "Return Type"

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

Return Type

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

Return Type

Note that you can select None, in which case the block will just perform its actions but not report anything back. In programming languages, "none" is equivalent to "void" as a return type.

Using Custom Blocks

Now that we've created a custom block, let's use it. Where can you find it?

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

Custom blocks are organized by behavior. Those created inside an Actor/Scene versus a standalone behavior will be under a header that looks like ActorEvents_1 or SceneEvents_1.

Custom Blocks Palette

Implementing a Custom Block

Now that we've defined the wrapper for a custom block, it's time to implement it.

The short summary is this:

  1. Drag in the parameter blocks to use them in your custom block's implementation.
    Dragging in parameters

  2. If your custom block returns a value, use the return block to do so.
    Returning a value

Using a Custom Block

Custom blocks with "None" as a return value will work like action blocks.

Otherwise, custom blocks that return a value will act like blocks of that type. For example, our distance block acts like a number block because we set the return type to number.

Usage of custom block

Global Custom Blocks

Programmers: Global Custom Blocks are equivalent to static functions

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

Global Custom Blocks

What is 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. Because it lacks a "home," 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 in the game. This can be convenient for game-wide functionality such modifying a game's score, which is frequently stored inside of a game attribute.

Global Custom Blocks

Global Custom Blocks

Print Article Edit Article How to Edit an Article
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!


I saw a Parameter that was named "text" I didn't see it on my stencyl. :(
0 10 years, 9 months ago
@farah you have to make a "custom block" and not a custom event.
1 11 years, 6 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 11 years, 8 months 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 11 years, 10 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 12 years, 1 month ago

Sign In to Comment