Extension Block Creation Guide
Note: This post is intended for those who don't yet know how to create and customize extension blocks. For the Block Reference, see the next post.
First, you'll need an engine extension. To learn how to start a new extension, see this page
To find an extension's folder from Stencyl, click Debug > View > View Workspace Folder
, then open stencylworks/engine-extensions/name-of-your-extension
. Once you have the correct folder, open blocks.xml
If the extension you just opened is a new one, you should see something like this in the file:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- There may be a comment here. -->
<block tag="test-print" spec="print %0 to console %1" code="Test.print(~);" type="action" color="gray" returns="void">
<c text="Enabled" code="true"></c>
<c text="Disabled" code="false"></c>
This is a bit complex, so let's break it down line by line.<?xml version="1.0" encoding="UTF-8" standalone="no"?>
This tells the program that it can use this file to define the blocks. It needs
to come before anything else.<!-- There may be a comment here. -->
The program ignores anything between the <!--
tags. You can use these to comment out parts of the file.<palette>...</palette>
This is the area where blocks are defined.<block tag="test-print"...>...</block>
This is a block definition. Inside this tag, the block's attributes
are defined. There's more on that in the next section.<fields>...</fields>
This area is where any input fields
should be defined.<text order="0"></text>
This is an example of an input field. There's more about that a little later.
Each block has a set of attributes
, with values that need to be set. Each attribute should have syntax in the form of attr="value"
. You can find a full list in the next post, under Block Attributes
Here's an example of a block that returns the text "abc". (Note: I prefer to put each attribute in its own line. This doesn't have to be the way you do it.)
help="Returns the text 'abc'."
You may have noticed the "
s in place of quotation marks in the code
attribute. This is because real quotation marks can't be used there, or the block will become glitched. You can find a full list of characters like this (as well as their workarounds) in the next post, under Special Characters
Inside each <block>
tag, there should be a <fields>
tag. Inside this tag, you can place any inputs you need. The input fields should be organized like this:
As you can see, the fields each have a different order
attribute, in the order 0, 1, 2....
The inputs are referenced in the block's code
, in order, with ~
. This is why the order of the inputs is important. The inputs will end up in the block's code in the order you place them in the file.
I.e., the input with order="0"
will be the first ~, order="1"
will be the second, and so on...
Fortunately, the inputs are referenced in the block's spec
by using %
with the order
value of the input. This allows them to be placed in any desired order on the visible part of the block. Here's an example block that sets an actor's X value:
<block tag="set-actor-x" spec="set x to %1 for %0" code="~.setX(~);" type="normal" returns="void">
You may have noticed that the return
type of each block is also a field type. This is so that the block fits into the correct blanks when being used. For example, a block with a return type of number
will fit into a number input.
There are many different field types, most of which can be used as both inputs
types. Click here for a complete list of field types.
For instructions on how to use the special input types, see the next post, under Special Types
Thank you for reading this topic. It was originally written to be an all-in-one guide, so I am planning to update it in the near future, in order to make it more beginner-friendly. If you have any questions, comments or suggestions, feel free to post them below!
Also, special thanks to:
mdotedot, for encouraging me to share this information
captaincomic, for adding cool features and squashing tons of bugs
Justin, for his continual awesome updates to Stencyl's extension support
I'll be sure to document any new extension features as they come out! I've heard that there will be a bunch more in 3.4....