[NATIVE] Guide/Reference for Creating Extension Blocks

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.
Getting Started

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.

Block Basics

If the extension you just opened is a new one, you should see something like this in the file:

Code: [Select]

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- There may be a comment here. -->
<palette>
<block tag="test-print" spec="print %0 to console %1" code="Test.print(~);" type="action" color="gray" returns="void">
<fields>
<text order="0"></text>
<dropdown order="1">
<choices>
<c text="Enabled" code="true"></c>
<c text="Disabled" code="false"></c>
</choices>
</dropdown>
</fields>
</block>
</palette>

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 <!-- and --> 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.

Block Attributes

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.)

Code: [Select]

<block tag="test-abc"
spec="abc"
code="&quot;abc&quot;"
help="Returns the text 'abc'."
type="normal"
color="green"
returns="text">
<fields/>
</block>

You may have noticed the &quot;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.

Input Fields

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:

Code: [Select]

<fields>
<number order="0"/>
<text order="1"/>
<actor order="2"/>
</fields>

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:

Code: [Select]

<block tag="set-actor-x" spec="set x to %1 for %0" code="~.setX(~);" type="normal" returns="void">
<fields>
<actor order="0"/>
<number order="1"/>
</fields>
</block>

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 and return 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.

Thanks!

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....

Extension Block Creation Reference

Block Attributes

Required:
tag - The name of the block, used internally in Stencyl. If you change this, any instances of this block already in a game will disappear, so choose wisely! Most built-in blocks are named something like block-name, but you can name yours however you like.
spec - The text to display on the block. To display an input field, use %x, replacing x with the order of the input.
code - The Haxe code that the block represents. To retrieve code from an input field, use ~.
type - The basic type of the block. This can currently be one of three options: normal, action or wrapper.
returns - The field type which the block returns. If block is an action- or wrapper-type block, it should return void.

Optional:
help - The text to display at the bottom when the block is moused over.
color - The color of the block. Any of these options are allowed: blue, cyan, green, lime, purple, red, gray, charcoal, or yellow (3.2+).
hidden (3.2+) - If this is set to true, the block will not show in the block palette. Added in conjunction with the attached-block field type.

Special Characters

Some characters will glitch the extension if used incorrectly in blocks.xml. Here's a list of most of these troublemakers, and their workarounds:

" quotation mark - &quot;
< lesser sign / left arrow - &lt;
> greater sign / right arrow - &gt;
& ampersand - &amp;
# number sign - &#35;

Field Types

There are many different field types, most of which can be used as both inputs and return types. The full list is quite long, so I've elected not to insert it here. Instead, click here to see the complete list.

Special Types

void - Should only be used as a return type for action- and wrapper-type blocks.

dropdown - Can be used as an input, but has its own special layout. Example:

Code: [Select]

<block tag="boolean-dropdown" spec="%0" code="~" type="normal" returns="boolean">
<fields>
<dropdown order="0">
<choices>
<c text="true" code="true">
<c text="false" code="false">
</choices>
</dropdown>
</fields>
</block>

code-block - For the inside of wrapper-type blocks. Used the same way as a normal field type, but only as an input. Example if block:

Code: [Select]

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

attached-block (3.2+) - A special type that allows a small block to be attached to a wrapper-type one. It's much different to use from the normal field types. Here's how you can:
- First, create the small block you want attached. This block must be in the file above the wrapper block!
- Set the small block's hidden attribute to true. Also, make sure your block's type attribute is set to normal, or an error will pop up when you try to use it.
- Next, on the wrapper block, add an attached-block field, as you would a normal field.
- Finally, inside the attached-block tag, add a tag="abc" attribute (replacing abc with the tag of the smaller block).
Example save game/save successful block:

Code: [Select]

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

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


Block Icons

Some blocks, you may have noticed, have little icons on them:



There is a way to use these icons on extension blocks:

Code: [Select]

<block spec="some text [i:some-icon]">
<block spec="some text [e:some-icon]">
To find the icon you want, first unzip sw.jar (the way I did this was by re-saving it as sw.zip). Then go to the folder you want:

- For [i:___], go to /res/designer
- For [e:___], go to /res/snippet/events

Finally, find the name of image you want and insert that in place of the some-icon in the above snippet. If you don't want to go mucking around in the .jar file, here are all of the images available for [i:___] in my version of Stencyl (b9300):



And for [e:___]:

Custom Block Icons

In 3.3+, you can use custom icons with this code:

Code: [Select]

<block spec="some text [c:some-icon]">
The image you want to use should be located at

Code: [Select]

[folder of extension]/block-icons/some-icon.png

Hello ETHproductions,

Thank you very much for this documentation.
You have given me insight in most of the information already, but it is cool to have a reference here and can be extended once more functionality ( Tab inside panel  ) comes available!

Wrapper code blocks and dropdown lists are the most powerfull in my opinion.
And that you can use direct code in the blocks.xml is really powerfull!

Again, thank you for your efforts!

Best regards from
M.E.

Thanks for your support! I have a few projects going on right now, but when they're finished, I'll update this with information about block icons. I'll also be sure to document any new features when they come out!

Noticed that the info on block icons was never posted here.

Code: [Select]

<block spec="some text [c:some-icon]">
The image can then be found here.

Code: [Select]

[workspace]/my extension/block-icons/some-icon.png
Also, you can include icons that Stencyl uses if you want to.

If you use [i:___] it looks in sw.jar/res/designer/___.png
And if you use [e:___] it looks in sw.jar/res/snippet/events/___.png

Thanks Justin and ETH!

I take the opportunity to ask how we can manage optional arguments directly in a block.

Thank you

Currently, there's no capability of optional arguments in Design Mode.

The only way you could get that right now is by writing some java code to perform some custom code conversion.

How is defined the order of the blocks?

What do you mean?

The order that the blocks are show in Stencyl.

The order of options is "order="0",  "order="1",  etc.

And of blocks in Stencyl?

They not follow alphabetical order, not the order of the written code.
They are displayed in random order?

Right now the order is undefined. In the future we'll let another file be used to place blocks into the palette wherever you want.

Got it. Thanks.

Currently, there's no capability of optional arguments in Design Mode.

The only way you could get that right now is by writing some java code to perform some custom code conversion.

Thanks to tell,  I understand why I failed !

but even I were Java literate, I would know from where to start .. any documentation somewhere ?
and ?? ... any Java Gurus around   ?

Could you expect a

Code: [Select]

Events for 'demo': Unexpected :
from scripts.SceneEvents_127
line: 91
columns: 31-32
??
What is it wrong with my block

Code: [Select]

        <block tag="save-successful" spec="if successful" code="success" type="normal" returns="boolean" hidden="true">
<fields/>
</block>
<block tag="save-load-game" spec="%0 %1 %2 [i:save] " code="~( ~, function(~:Bool):Void { ~ } );" type="wrapper" returns="void">
<fields>
<text order="1"/>
<code-block order="3"/>
<attached-block order="2" tag="save-successful"/>
<dropdown order="0">
<choices>
<c text="Save" code="saveGame"/>
<c text="Load" code="loadGame"/>
</choices>
</dropdown>
</fields>
</block>