How to Create Extensions

by Jon (Updated on 2014-02-02)

Note: This guide talks about building plugins for our toolset. This process is completely different from building extensions for our engine.



  • What do you need to know?
  • What exists today?
  • Can _ be an extension?
  • Concepts - Hooks and Callbacks
  • Getting Started- How to Create an Extension
  • API Documentation
  • Callback Reference
  • GUI API Reference
  • Data API Reference
  • How to Submit an Extension



Extensions are small applications or controls that add new functionality to Stencyl. They serve the same purpose as extensions for web browsers, such as Firefox and Chrome.

Extensions allow the community to extend the utility of Stencyl itself to fit its unique needs.


What Extensions exist today?

The highest profile extensions being built at the moment include the following.


What do you need to know?

To develop an extension, you need to know Java and preferably have some working knowledge of Swing or GUI programming.

Although we provide an API that makes it simple to build a GUI with no Swing knowledge, knowing it will give you the ability to create more powerful extensions.


Can ___ be an extension?

As long as the extension has something to do with Stencyl, it's generally doable. If you're looking to extend the engine, look here instead.

Today, since Extensions can only be accessed from the Extensions menu, this constraint means that extensions that deal with productivity or general use will work the best. Keep that in mind when developing your extension.


Concepts - Hooks and Callbacks

Developing an extension is simple once you master two key concepts: hooks and callbacks.

Hooks determine where your extension is displayed in Stencyl' GUI. For the initial cut, extensions can only appear in the Extensions menu. In the future, we will extend this to the toolbar, Game Center and more.

Callbacks are functions that you implement inside your extension. These are functions that are called at specific times in Stencyl's lifecycle. For example, there are callbacks for when a user opens the app, opens a game, saves a game, and so forth. Every callback is documented at the end of this manual and inside our API docs.


Getting Started - How to Create an Extension

Creating a simple extention doesn't take much time. You will need the following before you begin.

  • Java Development Kit (JDK) 1.6.x. Do not use Java 7.
  • Stencyl 3.0 or later. Please do not target older versions.
  • Eclipse, Netbeans or any setup that can run an ANT Build. If you have no idea what ANT is, don't worry.


Get the Stencyl Extensions SDK


The SDK consists of a sample project and our API docs for extensions.


First Steps

  1. First, navigate to [STENCYL_FOLDER]/plaf/sw/ - This folder contains all of your extensions.
  2. Open up the Sample Project in your IDE by creating a new, existing project. Peek at the README, which contains specific instructions for the nitty gritty project setup. Add sw.jar to the project's classpath and edit build.xml as directed.
  3. After that is done, run the "dist" ANT task. This builds a JAR file that Stencyl recognizes as an extension.
  4. Launch your copy of Stencyl, and you will see the Sample Extension appear in the Extensions menu and also inside the Extensions Manager. Play around with it.



  1. Now that the sample extension runs, flip to SampleExtension.java, the source that defines the extension itself.
  2. Do you see how it impplements a bunch of callback functions that all start with "on"?
  3. Make a simple edit to it.
  4. Rebuild and rerun in Stencyl. Does your change show up?


API Documentation

You can view the API Documentation here.


Callback Reference

Many callbacks exist in order to provide a wide array of functionality for extensions. Consult the API for the full reference. We're just going to cover the important ones. The majority are named to be self-explanatory.


Called when StencylWorks is launching. Try not to do anything intense, or it will slow down launch.

Called when the extension is told to display or "do work"

Called when StencylWorks is being quit out of. Usually, you'd use this to save stuff out.

onGameSave(Game game)
Happens whenever a game is saved.

onGameOpened(Game game)
Happens whenever a game is opened.

onGameClosed(Game game)
Happens whenever a game is closed.

OptionsPanel onOptions()
Returns a configuration panel for this extension that's shown when the Options button is clicked in the extensions manager. View the API for the Options Panel as well as the source to the Sample Extension for usage samples.

Happens when the extension is first installed.

Happens when the extension is uninstalled. Do cleanup.


GUI API Reference

We provide a set of functions to help you build a GUI or perform common tasks.


showMessageDialog(String title, String text)
Pops up a modal dialog with the given title and text.

doLongTask(final Runnable mainTask, final Runnable onFinish)
Perform a long task that would have hung/frozen the GUI. Pass in 2 Runnables. Runnables look like this:

Runnable r = new Runnable() {
    public void run() {
        //Do Stuff


setProgressMessage(final String msg)
Sets the message shown inside the progress spinner. Keep it brief!

Shows the progress spinner. Use it in conjunction with doLongTask.

Hides the progress spinner.


Data API Reference

If you need to store data, use our data API to save out this data to disk. Do not attempt to write out to other locations using the plain Java API's. This will only confuse users, and we'll reject such approaches on the spot.

Note: Starting in Stencyl 3.0, there's a better place to store data - directly in a game's extras subfolder. This is now the preferred place to store data and is being used by all our top extensions.


String readData()
Reads the extension's data into a String. No file path is provided because it all comes from a pre-determined location on disk.

byte[] readDataAsBytes()
Reads the exension's data into a byte array.

boolean saveData(String data)
Saves data, provided as text, to the data store.

boolean saveDataAsBytes(byte[] b)
Saves data, provided as a byte array, to the data store.


How to Submit an Extension

Extensions are distributed through our Developer Center. Extensions must be manually approved to show up on that site. To do this, you must do two things.

  1. Post your extension on the forums (inside the Extensions forum) for a community review. This will help us pre-vet the extension.
  2. If it's great, one of us will notice fairly quickly. If not, contact us.

Include the following details in the forum topic.

  • A description of your extension
  • Your extension in JAR form
  • A 48x48 PNG icon for your extension
  • At least 1 screenshot of your extension

It's prefereable that you either build documentation into the forum topic, attach it to the topic or provide a link to a site that does. 

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!

1 Comment

Is this still the most recent documentation for this? The API docs linked are pretty scant and have a generation date of 2011.
0 1 month, 4 weeks ago

Sign In to Comment