How to Create Extensions

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 to fit its unique needs, so that the core team can focus on what it does best.

Extensions will appear in Stencyl 1.1. The topics covered in this document include the following:

• What do you need to know?
• 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

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. What can't be done at this time is extending the Stencyl (Flash) engine, although we have separate plans to tackle that.

Planned extensions that will be officially developed by the Stencyl Team include:

• A game backup service
• A notepad
• A TODO list
• A template for building extensions that upload a Stencyl game to a website
• A template for building an extension that executes something on the command line

Today, since Extensions can only be accessed from the Extensions menu, this constraints 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 takes about half an hour. You will need the following before you begin.

• Java Development Kit (JDK) 1.5 or later
• Stencyl 1.1 or later
• 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

Download

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.

Developing

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.

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

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

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

onInstall()
Happens when the extension is first installed.

onUninstall()
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!

showProgressSpinner()
Shows the progress spinner. Use it in conjunction with doLongTask.

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

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 will be distributed via StencylForge. Unlike other kinds of resources, Extensions will be submitted using a different process and will be manually approved. 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. E-mail us a link to that forum topic at webteam [at] stencyl.com

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

Please allow several business days for us to review your extension.

Commenting Guidelines