ESL Wire Plug-in Developer Guide Overview This document gives an introduction to the development of plug-ins for ESL Wire. After explaining the plug-in basics, we give a step-by-step guide to programming your fist plug-in. However, this document only covers the first steps. An in-depth reference of the plug-in interface is available here. More information can be found on our ESL Wire Plug-in portal. What’s a plug-in? Plug-ins allow users to extend and customize ESL Wire according to their needs. A plug-in can integrate into the GUI (graphical user interface) of ESL Wire by adding an icon to the “plug-in bar” at the bottom of the main window. A plug-in is notified whenever a mouse click occurs on its icon, so it can react to mouse clicks by opening a window, showing a context menu, changing the icon or by some other action. The Plug-in bar of ESL Wire. The icon in the red circle was added by a plug-in. How do plug-ins work? Plug-ins for ESL Wire a are implemented as .Net class libraries. This means that a plug-in is a DLL file that is written in a programming language that uses the .Net Common Language Runtime (CLR) . This includes languages like C#, C++/CLI, VB.Net, Boo, Ruby.Net etc. Languages that use the Dynamic Language Runtime (DLR), on the other hand, are currently not supported. This includes IronPython, IronRuby. An overview of .Net languages can be found here. The DLL of a plug-in is not loaded directly into ESL Wire, but executed in a host-process, the so-called plug-in container. This way a faulty plug-in cannot affect the stability of ESL Wire or other plug-ins. Furthermore this allows you start, stop and restart your plug-in during development without having to restart ESL Wire. The plug-in container uses inter-process communication (IPC) to communicate with ESL Wire. This allows plug-ins to use functions of ESL Wire like normal, local functions. The IPC-system that is currently used for this, is D-Bus. The inter-process communication scheme for plug-ins. Multiple plug-in containers can communicate with ESL Wire via D-Bus. Where are the plug-ins? The plug-in DLLs are located in the “plugins” sub-directory of the ESL Wire installation directory. If you installed ESL Wire in “C:\Program Files\EslWire”, the plug-ins will be located in “C:\Program Files\EslWire\plugins”. ESL Wire tries to run all plug-ins that are found in this directory during start-up. However, as we will later explain, it is also possible to start a plug-in manually when ESL Wire is already running, which is useful for debugging a plug-in. How do I make a plug-in? The following paragraphs guide you step-by-step through the creation of a simple plug-in. The resulting plug-in will display an icon with tool tip text in ESL Wire and can be used as basis for developing more advanced plug-ins. What do I need? Obviously, first of all you need to have the latest version of ESL Wire installed to develop plug-ins (available at http://www.esl.eu/wire), at least version 1.7. There is no separate Plug-In SDK (Software Development Kit), since the necessary library is already included in the standard installation. A technical reference of the plug-in interface is available at http://dev.esl.eu/wire/plugin_api_reference/ Furthermore you will need a programming environment (IDE) that allows you to create a .Net class library. The following development environments have been successfully used for plug-in development: ● SharpDevelop (http://sharpdevelop.com/OpenSource/SD/Default.aspx) - A completely free and open source IDE that supports many CLR languages (C#, C++, VB.Net, Boo, etc.). If you are looking for a free development tool, this is our recommendation. ● Visual Studio Express Edition (http://www.microsoft.com/express/Windows/) - The free edition of Visual Studio. Unfortunately this edition does not support debugging of class libraries that are loaded by external application. Therefore we currently do not recommend the Express Edition. ● Visual Studio 2005 or 2008 - The commercial editions of Visual Studio are maybe the most complete and feature rich development environment for .Net, but also relatively expensive. ● Monodevelop (http://monodevelop.com/) - This open-source IDE was originally a port of SharpDevelop to Linux. Now it’s an independent project that is also available for Windows. Step by step Guide The following paragraphs walk you through the first steps towards developing you own plug-in. In this guide, we use C# and SharpDevelop 3.2. However, Visual Studio and Monodevelop have similar interfaces, and it should be possible to follow this guide with these programs as well. Step 1: Create a new class library project In the “File” menu, select “New” -> “Solution...”. In the “New Project” dialog, select the “C#” category and “Class Library” from the “Templates” list. Enter a name for your new project, e.g. MyFirstPlugin and click the “Create” button. Make sure you select “.Net Framework 3.0” or “.Net Framework 3.5” as the target framework. Plug-ins written for version 4.0 of the .Net Framework will not work! Step 2: Add necessary references Select “Add Reference” from the “Project” menu. In the GAC (Global Assembly Cache) tab, select the “System.Drawing” Reference, and click the “Select” button. In the “.Net Assembly Browser” tab of the “Add Reference” dialog, click the “Browse...” button. Navigate to the “pluginContainer” directory of your ESL Wire installation (typically “C:\Program Files\EslWire\pluginContainer”), select the file “PluginInterface.dll”, and click the “Open” button. Now close the “Add Reference” dialog by clicking the “OK” button. Step 3: Make your class inherit Wire.Plugin Now that you’ve added the PluginInterface reference, you can start editing your code. Add “: Wire.Plugin” to your class declaration to inherit the plug-in baseclass. Step 4: Override abstract members of Wire.Plugin The Wire.Plugin class has four abstract members you have to override: the string properties “Author”, “Version”, “Title” and the “init” method. When you have added overrides for these, you already have a working plug-in, albeit one with no functionality. Step 5: Embed an icon in your class library To add an existing icon file, select “Add” -> “Existing Item...” from the “Project” menu. Find an image file that is roughly 16x16 pixels in size. Supported image formats are PNG, JPEG, and BMP (For icons, the PNG format has the advantage that it supports alpha transparency). In this example, we added a file named “brick.png”. When asked “Do you want to copy the file(s) to the target directory...”, click the “Copy” button. An example icon can be found here. Now the image has to be embedded as a resource to the plug-in DLL. This is accomplished by setting the Build action field in the “Properties” view for the image file to “EmbeddedResource”. Step 6: Set the icon and tool tip In the “init” method of your plug-in, use the “setIcon” and “setTooltip” base class methods to define an icon with tooltip for your plug-in. Step 7: Build your plug-in Before compiling, you should change the project setting to support all CPU types (32-bit and 64-bit): Select “Project Options...” in the “Project” menu. On the “Compiling” tab, choose “Any processor” in the “Target CPU” field. Now, select “Build Solution” from the “Build” menu to compile your plug-in. You can copy the resulting DLL (MyFirstPlugin.dll) to the plugins\wire folder and restart ESL Wire to see your first plug-in in action. The icon of your plug-in should appear in the plug-in bar of the main window. How do I debug a plug-in? For any non-trivial plug in development, it will be necessary to debug your code. Fortunately this is easily done. Step 1: Change the debug settings of your project Go back to the project options (“Project” -> “Project Options...”), and open the “Debug” tab. Select the “Start external program” option and click the “...” button next to it. In the file dialog, select the “wire- plugin.exe” file in the “pluginContainer” directory of your ESL Wire installation. In the “Command line arguments” add the full path of your plug-in DLL in, enclosed in double quotes, e.g. "D:\SharpDevelop Projects\MyFirstPlugin\bin\Debug\MyFirstPlugin.dll". Step 2: Set a breakpoint To add a breakpoint in the first line of your “init” method, place the text cursor in the corresponding line and press the F7 button. Step 3: Start the debugger Make sure ESL Wire is running. Hit the F5 button to start the debugger. After a short while, the execution should pause at your break point. You can now step through each line by pressing F10. Adding more functionality To react to an event from ESL Wire, a plug-in only needs to add a handler method for a specific event. If you want your plug-in to do something whenever a game is started, just add the following code to the “init()” method: Wire.GameInterface gi = Wire.InterfaceFactory.gameInterface(); gi.GameStarted += new Wire.GameInterface.GameStartedHandler(gameStarted); For information about all available methods, please see the Wire plug-in reference: http://dev.esl.eu/wire/ plugin_api_reference/ The image below shows an example event handler. When you start a game it lists all by Wire detected games in the debug output. Another example is the following. It shows the name of the started game inside the debug output.