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







Adding Custom Blocks (via an extension)

by Jon (Updated on 2015-10-25)

Engine Extensions
Advanced Topics
Toolset Extensions


This is the spec for blocks.xml, the file used to add custom blocks to an extension.

Note: Making changes to blocks.xml requires you to close and reopen the game for your changes to be reflected in the block palette.

Credit: Thanks to ETHproductions for documenting this feature. We've based portions of this guide on his forum guide.

Example (for reference)

Suppose that we wanted to remake the print block. This is what the definition would look like.

Don't worry about the details for now. This will be useful to refer back to as you read through this article.

  <block tag="print" spec="print %0" code="System.print(~);" type="action" color="gray" returns="void">
      <text order="0"/>

Adding a Block

<palette> is the root tag for the document -- it contains a list of <block> entries.


To add a block, add a <block> tag with the following properties.


Property Description
tag Unique name for block, only ABC and - (dash) allowed (no spaces!)
spec Like what you see in our language files, use %0, %1, etc. to specify where the spaces go
code Output code, use ~ to specify the blanks. Must match the order in which fields are specified.
type Any of these [normal, action, wrapper, event]
returns A type (see available types below)


Property Description
help Displayed in the bottom bar when the mouse hovers over this block.
color Any of these [blue, cyan, green, lime, purple, red, gray, charcoal, yellow]
hidden If true, the block will not display in the palette. Used in conjunction with attached-block


<block tag="print" spec="print %0" code="System.print(~);" type="action" color="gray" returns="void"></block>


These are the available types you can use for the returns property of <block> and the list of <fields>.

  • actor
  • actortype
  • animation
  • anything
  • boolean
  • color
  • control
  • filter
  • font
  • group
  • image
  • image-instance
  • joint
  • list
  • map
  • number
  • region
  • scene
  • shader
  • sound
  • text
  • void (only applies to returns)
  • dropdown (only applies to fields)
  • code-block (only applies to fields - see explanation under Code Blocks)
  • attached-block (only applies to fields - see explanation under Attached Blocks)

Input Fields

Each <block> contains <fields> as a child. <fields> is a list of block input fields (the blank spaces in a block).

<block tag="print" spec="print %0" code="System.print(~);" type="action" color="gray" returns="void">
    <text order="0"/>

Each child of <fields> is a tag, whose name corresponds to a type (the ones mentioned above). For example, if you want to make a number field, the tag would be <number>.

Ordering Fields

Fields are ordered using order attribute, starting at zero and incremented by 1. Don't skip numbers.

  <text order="0"/>
  <text order="1"/>
  <text order="2"/>

Dropdown Fields

If you wish to use a dropdown, look at the example below for syntax.

The text attribute specifies what's visible to the end user. The code attribute specifies the literal value that will be output into code.

<block tag="number-dropdown" spec="%0" code="~" type="normal" returns="number">
    <dropdown order="0">
        <c text="Pressed" code="1"/>
        <c text="Released" code="2"/>

Attached Blocks

Attached Blocks are the embedded blocks in wrapper blocks that are meant to be used only within the context of the wrapper block.

Here's how you define one.

  • First, define the inner (embedded) block. It must be above the definition for the wrapper.

  • Set the inner block's hidden attribute to true, so it won't show up in the palette.

  • Add an <attached-block> field to the wrapper block definition.

  • Inside the tag for <attached-block>, add a tag attribute whose value is the tag for the inner block.

Here's an example of this in action.

<block tag="save-successful" spec="save successful" code="success" type="normal" returns="boolean" hidden="true">

<block tag="save-game" spec="save game and then... %1" code="saveGame('mySave', function(success:Bool){~});" type="wrapper" returns="void">
        <code-block order="0"/>
        <attached-block order="1" tag="save-successful"/>

Code Blocks

This is a special type of field that can only show up inside a wrapper block (such as if). It has nothing to do with literal code and is used to allow a wrapper block to contain a bunch of fields before the wrapped stack of blocks is accepted (in other words, this field always comes last).

<block tag="if" spec="if %0" code="if (~) {~}" type="wrapper" returns="void">
        <boolean order="0"/>
        <code-block order="1"/>

Additional Reading

A more thorough reference is available here.

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!


Do you need Notepad to create an xml file?
0 3 years, 7 months ago
also, variables which subject to scene's variables like (g:G) must be included in the code line in xml file as (g) not (~).
these ones also need not be include in spec or fields.

1 6 years, 8 months ago

Sign In to Comment