Plugin API – Creating Overlap2D Plugins


Overlap2D Editor itself is a very minimalist tool, and is built with philosophy of things being on top of it. Whenever you are lone indie dev, big game dev studio, or game engine developer, at some point you may need a customization level for the editor that is not meant for everyone, but only for your particular case. That’s where Overlap2D open plugin API comes in.

Possible use cases include:

  • You are creating a game and need level editor build specifically for that game, with advanced functionality to support your game logic.
  • You want to be able to play your game inside the editor, to have your logic playable while you edit the level
  • You have your own game engine and need overlap2d to save in your specific data format
  • You are a big team, and minimalistic features of o2d are just not enough for your team.

In this section of documentation I will show how to create your own plugin for Overlap2D.


How plugins work

Overlap2D Plugins are simple jar files with added logic. In order to add a plugin to Overlap2D you have to put that jar file inside a “plugins” folder near the overlap2d executable. During startup Overlap2D automatically scans that directory for plugins and initiates ones that work. Plugins have access to editor core functions, and can modify different UI menus, add new dialogs and sandbox functionality. Some plugins are already included with Overlap2D when you download it, for example Performance plugin and NinePatch plugin. You can remove them by just removing their jar files from plugin directory.


Project Setup

In order to start developing Overlap2D plugins, you have to first checkout the editor sources itself. (while not necessary it’s the easiest way t do it), so head to our github and either download or git clone the repo. There are several directories inside, one of which is overlap2d-common-api which you will need later during plugin development. It contains all the core classes and interfaces of plugin API.

Create an Empty Java project for your plugin, good location is near the overlap2d repo, but it’s up to you. This is going to be a gradle project. And you need to make sure your project can see important things like common-api project, as well as overlap2d-runtime and so on. Here is an example of working gralde configuration: build.gradle and settings.gradle

Next is to create your main class. Something like MyPlugin:

That’s it you have created your first empty plugin!


Running your plugin on editor

Now that you have working project we need to learn how to build it and test inside the editor. For that first download latest editor from our website here and extract the archive somewhere on your local. Now you can see that plugins directory that comes with it already contains some jar files, and we need to make our project jar file to be built to that directory. To do that simply edit your build.gradle file to have line :

Here you should put the path to plugin folder of overlap2d that you have just downloaded. This line will make gradle build your jar to that path. Now you can simple run “jar” task of your project, and it will build jar file to that location.

All that is left is – run overlap2d editor, and it will also load your plugin. That is not visible in any way though, so you can’t yet confirm that all works. Unless you put  System.out.println to your initPlugin method, and ran editor from console to make sure you see the output.


Debugging your plugin

Making sure your plugin works is good, but what if you need to debug it. For that you cannot just use editor jar file, you need to run editor from sources. Luckily it’s not that hard, you have editor sources, all you have to do is open that project and run it in your favorite IDE. Although you will easily find that beacuse it is run from IDE, it doesnot load any plugins, in order to “quick fix” that, head to class and change this line

to this line:

Now when you start editor from sources, it will load plugin you built previously, and you will be able to debug it.


Plugin API

Here we will learn what kind of API is availible for plugin dev, and what your plugin can possibly do.

API main access

Because your main class extends O2DPluginAdapter it will have method calld getAPI() which will be your point of destination for whatever you want to do. it Will contain variety of methods for interacting with the editor, and doing what you need to do.

Top bar menu utem

O2D plugins can add menu items to the top bar. Here is a snippet of code to do that:

In order to make this menu items to “do something” you need to provide appropriate action string. In Overlap2D we use pure MVC framework for things to communicate with each other, so each action is done via command or notification that is described by a unique string.  Best practice for this string is to use you plugin package name class name and unique string describing the action.

You can then create Mediator and View class to listen for this particular action and react when menu item is clicked (for example show a dialog).

A good example of this can be found in Performance plugin sources in overlap2d repository on github. It’s just short 3 classes, so take a look.


Modifying contextual menu behavior

Whenever you right click on an item or empty space in overlap2d, a drop down contextual menu is shown, you can add new items to it for your plugin.

In order to do that you need to first create action constants and text’s for this new items.

This will tell overlap2D about new action constant, and should be done during plugin init.

Now conext menu is always different depending on situation, so you have to edit it’s content on the moment it was created for a particular situation. Lets say we want to only add a new menu item for case when user right clicks on an image. To track if menu was opened we need to override a method in our plugin class. And do some checks. Here is a working code example:

Again a great working example to take a look at, is NinePatch plugin that is provided with overlap2d sources in it’s github repo, take a look at how it creates additional contextual menu item for 9 patch images only.


Modifying the export data

If you want Overlap2D to export different data. You can make plugin that interrupts current Export command. Currently Export is done via MVC Command

In order to interrupt it your plugin has to use facade to remove this command, and then add it’s own that will have different behavior.  Your alternative command will be extended from SimpleCommand and should override execute method in order to do it’s thing. From there on you can take the export location, the source data location, and do the “data patch” and “data copying”


Working with entities

Now that you can create sub menu items, and dialogs, you may want to influence the scene somehow, all you need to do that is access to the engine, to start getting entities, and working with them in standard Ashley way. To do that, simply call getEngine() on pluginAPI object, and do not forget to explore what other methods are available to you.



This section of documentation as well as API itself will be constantly updated. If you have questions or suggestions, simple ask me by email, and I will be happy to help in enabling you to have your very own breed of overlap2d.