Using Plugins in RPGToolkit 3.2.x

Introduction

Plugin support for the RPGToolkit has been around since 2005ish, it was added with the hope of providing further extensibility to RPGCode. A plugin is a collection of callable functions wrote in programming language which supports COM and is usually wrote by a member of the community. Typically the features contained within a plugin can never be incorporated into the RPGToolkit directly due to either complexity (online support), or because there is no real demand (file browsing).

While plugin support offered a huge amount of potential to further enhance RPGCode, it also, to the unawareness of its developers, proved to be the single biggest flaw in RPGToolkit 3.1 following the release of Windows Vista in 2007.

This document contains a brief history of The Infamous Windows 7 Issue, the solution to the issue, and lastly a step by step guide on how to use a plugin in 3.2. If you simply just want to know about how to use a plugin in 3.2 you can skip ahead to the Manifest Files section of this document, if you want to know more about the technical details surrounding the entire issue then read here on.

The Infamous Windows 7 Issue

In Windows Vista, Microsoft made some fundamentals changes to the way an application can access core system resources such as the registry. In order for RPGToolkit 3.1 to make use of a plugin it must first register the .dll file with the registry, this worked fine in XP but failed to function at all in Vista/7 without administrative rights.

Essentially every new user to the Toolkit would first have to visit the forums, sign up, start a topic, and plead for help in order just to get started. As with any free software the most likely thing the user was going to do after being told to stop posting such rubbish and search the forums was to remove the Toolkit and look elsewhere. This was single biggest issue effecting the growth rate of the Toolkit community, not the editor, but plugin support and its erratic performance on Vista/7.

Registration Free COM

99% of the plugins currently available for the Toolkit are COM based, these COM assemblies must be registered before they can be used. Prior to Vista, Microsoft introduced something called Registration Free COM for Windows XP and Server 2003, which as the name suggests removes the requirement to register a plugin before using it. Instead, using the correct manifest file an application can directly access a assembly for the duration of time it is running. The relationship between the application and assembly is only temporary.

Manifest Files

In order to be able to use a COM plugin with RPGToolkit 3.2 you will have to include an assembly manifest file along with the COM DLL. A manifest file is simply a text file with the .manifest extension containing XML. Below you will find the assembly manifest for the keyDown.dll plugin:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" 
  manifestVersion="1.0"> 
<assemblyIdentity 
   type="win32" 
   name="keyDown.dll.X" 
   version="1.0.0.0" /> 
<file name = ".\game\[Insert your project name here]\Plugin\keyDown.dll"> 
	<comClass 
    		clsid="{D2FD6152-F1F7-4649-B765-60D0127C441A}" 
    	threadingModel = "Apartment" /> 

	<typelib tlbid="{BEFEAF57-AF55-4D1F-8528-A4AC0561C020}" 
       		version="1.0" helpdir=""/> 
</file> 
<comInterfaceExternalProxyStub 
    name="_clsKeyDown" 
    iid="{EE3EC9CD-48BB-4003-9D8B-1212DDF0641E}" 
    proxyStubClsid32="{00020424-0000-0000-C000-000000000046}" 
    baseInterface="{00000000-0000-0000-C000-000000000046}" 
    tlbid = "{BEFEAF57-AF55-4D1F-8528-A4AC0561C020}" /> 
</assembly>

The only line that we are interested in here is:

<file name = ".\game\[Insert your project name here]\Plugin\keyDown.dll"> 

I have already gone to the trouble of generating the appropriate assembly manifest for all the popular plugins available for the Toolkit so all you need to do is replace the words [Insert your project name here] with the name of your project. For example, to use the keyDown.dll in the demo game I would change it to this:

<file name = ".\game\demo\Plugin\keyDown.dll">

It is very important that:

1. Your project name is correctly spelt, including casing.
2. The plugins name is correctly spelt, including casing.
3. That the plugin is actually in the named project's Plugin folder.
4. Each plugin has its own unique manifest file, they are not interchangeable.
5. The manifest file is left untouched besides the addition of your project's name.

Adding a Plugin

Now that I have explained what an assembly manifest is I will now show you exactly how to use one.

Obtaining the Plugin and Manifest

All of the popular plugins for the Toolkit can be downloaded at http://www.rpgtoolkit.net/extend/plugins. Included in each download, you will find a .dll file (a plugin) accompanied by a manifest file. In this example I used the fileBrowser_v1.3 plugin.

Move both of these files into your projects Plugin folder typically under Toolkit3\game[Your Project]\Plugin.

Modifying the Manifest

Open the manifest file that we just moved in notepad or some other text editor and find the line that reads:

<file name = ".\game\[Insert your project name here]\Plugin\FileBrowser_v1.3.dll"> 

Replace the words [Insert your project name here] with the name of your project, in my case the project was titled “Plugins”, and save the file.

Adding the Plugin

Now that we are finished with downloading and moving the needed files into our project we will need to pop into the Toolkit's editor, so fire it up. Open the project that you wish to use the plugin with and under the project's settings open the Plugins tab.

Click the Add button and locate the plugin (the .dll file) that you wish to include, and save your changes.

Testing the Plugin

Finally write a program that makes use of some of the plugin's functionality and run it. If you have completed each step correctly, you should get the desired result, otherwise go over everything again and refer to the troubleshooting section for further help.

Conclusion

Plugins provide a rich subset of features which are not currently available or cannot be made available in the Toolkit's engine, they cover everything from online support to file browsers. In this document I briefly covered the history behind plugin support in the Toolkit, how they effected the Toolkit following the release of Windows Vista, and finally I explained how to use them in RPGToolkit 3.2. Thanks to the hard work of myself and countless others they can finally be used on Windows Vista and above without administrative rights.

Troubleshooting

Problem: The plugin fails to work and produces the following error message “Failed to load the type library manifest”.

Solution: Ensure that you are using the correct manifest file for the plugin, that the file remains unchanged bar the addition of your project's name, and that the manifest file's name is in the formant [plugin name].dll.x.manifest.

Problem: Calls to the plugin fail to respond and no error message is displayed. Solution: TBD.

Problem: None of the above suggestions worked.

Solution: Please report the issue on the engine's Github issue tracker at Engine Issue Tracker or post it on the Software forum at Software Forum.