by Jon (Updated on 2015-10-28)
Stencyl supports user-written extensions for its the engine. Using either Haxe or a combination of Haxe and native code, extensions can be written for all of our supported targets, including iOS, Android, Windows, Mac, Linux and Flash.
Even if you don't intend to write any code, extensions can define custom blocks that expose features of Haxe (and our engine) that we don't currently have in block form.
No additional software is required to build pure Haxe or Flash extensions. Native extensions require Haxe 3.1 to be installed.
Before we dive into how to create an extension, it’s good to know where to get them and how to turn them on and off.
After downloading an extension, do the following.
The extension is now installed. You'll need to enable it in each game that needs to use it.
Note: While extensions are enabled on a per-game basis, they are installed globally, meaning that you only need to install them once.
Assume that [WORKSPACE] refers to the path to your Stencyl workspace (find it using Debug > View > View Workspace Folder).
All extensions reside inside subfolders of [WORKSPACE]/engine-extensions/. For example, check out the test-flash extension as an example.
Each extension consists of the following parts:
|blocks.xml||Defines custom blocks. More powerful than the in-editor custom blocks.|
|icon.png||32x32 PNG icon|
|include.nmml||Used to specify properties for native extensions.|
|info.txt||Various metadata for the extension. All fields are required.|
|Source files and DLL’s||The meat of the extension|
With a Haxe (cross-platform) extension, you are just adding new functionality to the engine (using just Haxe) or exposing Haxe / Stencyl-engine features in block form. For example, extensions have been written to add pathfinding, AI or date formatting.
To create a new extension, it's easiest to copy an existing one. We've created the "test" extension for this purpose.
Under [WORKSPACE]/engine-extensions/, copy the “test” extension into a new folder. Give that folder a name.
Edit info.txt and fill in the details.
name=Test Extension description=A test extension author=Jon website=http://www.stencyl.com version=1.0 compatibility=all
Replace icon.png with your own 32 x 32 icon.
Modify Test.hx and implement whatever it is you want to implement. You can create additional source files and reference them. Note that in many cases, your public API calls will need to be static.
That’s it. Once your extension is ready, open a game, enable the extension, and test the game. If you’ve done everything correctly, the extension will work.
Once an extension is enabled for a game, you can test the game (and the extension) immediately each time you make an edit.
You do not need to close and reopen Stencyl or the game to get those edits recognized, UNLESS you have made changes to the block definitions (blocks.xml).
If you encounter compile errors, use the Log Viewer to see what went wrong.
Creating a Flash extension is necessary if you wish to import a custom SWF or SWC. For example, a common use case is to import a sponsor’s API.
Read our article on Flash Extensions to learn how to create them.
Native Extensions allow Haxe code to call Objective-C, C++ or Java code, thereby allowing hooks to native functionality and APIs.
Read our article on Native Extensions to learn how to create them.
You've now finished up an extension and want to share it with the community. Here's what you need to do.
If you aren't going to open-source your extension, you should omit the project/ subfolder from your redistributed extension.
Now, ZIP up the folder containing your extension.
Start a forum topic in our Extensions forum to get feedback.
Once your extension receives sufficient feedback, contact us about getting it added to our official repository.
No. All extensions can be edited and tested without closing and reopening your game. The only exception is if you edit blocks.xml in order to change the Design Mode blocks associated with the extension.
If you hit a compile-time error, check out the Log Viewer to see what it says. Chances are good that you either goofed in the Haxe portion of the extension or possibly the custom block portion.
If your custom blocks don't load, don't come out right or prevent your game from loading at all, again, open up the Log Viewer before you load up your game to see if any errors. You probably goofed up in the custom block portion.
If you get stuck creating an extension, ask a question on the Extensions forum. Please refrain from asking here -- article comments are intended for pointing out errors in the article and suggesting improvements.