Creating Plugins for ACT

EQAditu · 10-04-2008, 07:54 PM

Plugins for ACT are standard .NET assemblies. They can either be pre-compiled (*.dll/*.exe), or ACT can compile plugin source code on-the-fly (*.cs/*.vb).

To be loaded by ACT, they must implement the plugin interface Advanced_Combat_Tracker.IActPluginV1. This interface consists of a main entry point, and a exit method to dispose resources in.

To create plugins I suggest you use an IDE like Visual Studio.
Microsoft supplies, free of charge, Express versions of their Visual Studio suites. The default download is a web installer which might require a registration key, which is free. If you wish to skip the supposed hassle of that for another hassle, you can download the express versions as ISO images which require no registration.

Documentation on ACT's API can be found here(archive). This contains the API in HTML format, and XML format. The HTML format should be obvious, the XML format can be specially used inside of IDEs to describe objects as you use them. Place the "Advanced Combat Tracker.XML" file with the ACT EXE file and Visual Studio will use it automatically.

EQAditu · 10-04-2008, 07:57 PM

When I write these things, I'm going to assume you're using Visual Studio C# Express, because it's what I'm looking at, and each language probably isn't that different.

Once in the IDE, create a new project. A class library template is probably your best bet. Name the project whatever you want... it probably won't show up anywhere within ACT, but something identifiable to yourself would be good. Although when the plugin causes exceptions within ACT the Namespace and Class name will be shown. The new project creates ClassLibrary1.Class1, so you can go ahead and rename those things now if you wish. VS comes with handy abilities to rename objects without breaking references if you right-click them.

The first thing you will want to do is add ACT as an assembly reference. In the Solution Explorer, right-click References and Add Reference... browse to where ACT, and hopefully the documentation XML, and select "Advanced Combat Tracker.exe". This will allow you access to the Advanced_Combat_Tracker namespace. You can add a "using Advanced_Combat_Tracker;" line to the top of the file to make typing easier.

As said previously, you must implement the interface IActPluginV1. This is done by adding a colon after your class's name and typing out the interface name. When the IDE recognizes the interface it will make a box appear to allow you to automatically create the interface member stubs within your class. (Shift-Alt-F10 will open the option box)

Once these methods are created, the plugin is technically ready for use, however it won't do anything. Creating plugin contents should be another post.

Each plugin should have only one class that implements this interface. When ACT scans the plugin, it will use one implementing class it finds and ignores the rest.

EQAditu · 10-04-2008, 07:58 PM

As previously mentioned, ACT plugins can come in two forms: DLLs and source files. I understand J#, Managed C++ etc can make .NET assemblies, but I didn't see a way to compile those types on the fly.

If you make a *.dll plugin, no special considerations have to be made. If you make a source file plugin, you may find yourself needing to put everything in one file, or make special assembly references.

For the case of assembly references, ACT can parse special comment tags at the beginning of the source file to add as references.

Code:

// reference:System.dll

This will add System.dll to the references from the Global Assembly Cache(GAC). If your reference is not in the GAC, you may need to supply a relative or absolute path.

Assembly attributes will also be parsed from the source file to be shown in the plugin info panel when ACT loads them. You can see examples of them in the AssemblyInfo.cs file created in your project's Properties folder.

EQAditu · 10-04-2008, 08:01 PM

How to debug plugin source using Visual Studio Express

I realize this isn't a straight forward thing to do for a class library type of thing, so I'll outline the quick steps to accomplish it.

The problem is that you cannot "start" a plugin within the IDE in order to debug it. The plugin must be loaded by ACT. Put those two together... you must have the IDE start ACT so that the plugin is executed within the IDE.

Now the Express version of VS2005 doesn't make it obvious how to do this in the GUI, so I'll just tell you how to edit your project to enable it. Go into your plugin project's folder, where VS Express keeps it, and open the .csproj file for your plugin. This is an XML file, so open it with a text editor, not with Visual Studio directly. In fact, don't have VS running at all.

Look for the <Project><PropertyGroup>nodes. There will likely be three of them. One mostly unlabeled, one marked debug, one marked release. Insert the following XML fragment into the debug labeled ProperyGroup node:
<StartAction>Program</StartAction>
<StartProgram>C:\Program Files\Advanced Combat Tracker\Advanced Combat Tracker.exe</StartProgram>
<StartWorkingDirectory>C:\Program Files\Advanced Combat Tracker\</StartWorkingDirectory>
If you have ACT in a different location, change the paths accordingly.

The end result might look like the following:
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
<DebugSymbols>true</DebugSymbols>
<DebugType>full</DebugType>
<Optimize>false</Optimize>
<OutputPath>bin\Debug\</OutputPath>
<DefineConstants>DEBUG;TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<UseVSHostingProcess>true</UseVSHostingProcess>
<StartAction>Program</StartAction>
<StartProgram>C:\Program Files\Advanced Combat Tracker\Advanced Combat Tracker.exe</StartProgram>
<StartWorkingDirectory>C:\Program Files\Advanced Combat Tracker\</StartWorkingDirectory>
</PropertyGroup>
Save the file, open your plugin project like normal... and run the project with the F5 key or corresponding toolbar button. Initially after starting ACT, there will be nothing to debug. Once ACT loads your plugin, the IDE will lock the source code file and you will be able to use breakpoints and examine exceptions as they happen. Along with all of the other things you'd expect to do while debugging an application; except it will be your plugin.

EQAditu · 10-04-2008, 08:02 PM

One word of warning for creating plugins with GUIs. Most of the events that come from ACT will not come from a UI thread, therefore it is not safe to modify Windows.Forms.Controls within the event handler. It is not disastrous to do so, but can occasionally stop rendering of that control until restart. Perhaps even cause an application crash.

Code:

Control.CheckForIllegalCrossThreadCalls

Changing this boolean to true will cause all cross thread calls to raise an exception. By default this is off within ACT, but you can temporarily turn it on to test your plugin code.

Since you are not supposed to modify UI elements from other threads, there is a way to ask the UI thread to do so.

Code:

delegate void ControlSetTextCallback(Form parent, Control target, string text);
public static void ControlSetText(Form parent, Control target, string text)
{
    if (target.InvokeRequired)
    {
        ControlSetTextCallback d = new ControlSetTextCallback(ControlSetText);
        parent.Invoke(d, new object[] { parent, target, text });
    }
    else
    {
        target.Text = text;
    }
}

These Form.Invoke() calls while safe are expensive to perform and should not be done often for performance reasons. You should perhaps instead limit UI updates or buffer them someplace to be performed by the UI thread later without an Invoke call.

You can find a collection of these helper methods in the Advanced_Combat_Tracker.ThreadInvokes class.

EQAditu · 02-27-2010, 01:23 AM

I added a download of a good starting point for creating a new ACT plugin. The plugin is an instance of a UserControl and saves a settings file.

ACT_Plugin-Sample.zip

Since it is a UserControl, you can double-click the .cs file in Visual Studio and change the UI in the designer. It comes with one sample TextBox that is saved to a configuration file... just use it as an example on how to add other controls to the XML settings file.

The .csproj file comes pre-configured to start ACT as the debugging process as described above but only if ACT is in the default install location. If it is not, edit the file manually and give it the correct paths. To make things easier, remember to copy the Advanced Combat Tracker.XML file to ACT's folder so that Visual Studio will load the Intellisense. (As described earlier)

The sample .cs file can be distributed as-is. As long as Visual Studio does not force any long strings into the .resx file, the .cs file has no dependencies and can be loaded directly as a plugin instead of compiling to a DLL.