PureGDK Plugin Framework Tutorial

Software you'll need before you begin

GDKLib Builder (puregdk root/plugin sdk)
PureGDK (http://puregdk.com)
PureBasic (http://purebasic.com)
Resource Hacker (http://angusj.com/resourcehacker)
TailBite (http://tailbite.com)

Preparing your files

For this tutorial I'm going to demonstrate with the Advanced Terrain plugin from The Game Creators. You'll need the AdvancedTerrain.dll plugin from your ..\Documents and Settings\YourUsername\Application Data\PureGDK\plugins-licensed folder. You will also need to create a file with the .gdt (GDK dependency template) file extension.

Open the plugin using Resource Hacker and copy the contents of the entire string table into your .gdt template file. There may be more than one table in a single dll.


Here is what the template should look like at this point. Notice that the last two commands have a preceding semicolon. This "comments out" the commands and they are ignored by GDKLib Builder. These commands have been commented because they do not appear in the documentation.


Here are some examples of how to properly setup your GDKTable:
An important difference between DarkBasic functions and PureGDK functions is that in a PureBasic function the optional parameters can only be at the end or the parameter list. The command Move Camera() in DarkBasic Professional has two sets of possible parameters: Move Camera(Distance) and Move Camera(CameraID, Distance). This is not compatible with PureBasic optional parameters. To reorder the parameters there is a second optional parameter list after the last % sign.



PureGDK supports the Long, Float, String, and Double data types from plugins. When using a specific type in the parameter list it's important to identify the type (.f, .s, .d) if the type is not of a Long. You do not need to use .l to identify a Long because this is the default variable type.



To return a variable use an open bracket ( [ ) before the first percent sign that separates the function name from the parameter types string. The first type in this string will be the type that this function returns.



If a function passes nothing and returns nothing then use a 0 for the parameter types string.



Another important thing you need to know about optional parameters is how to order them properly in the GDKTable.txt. If you have three functions MyFunc(Param1) and two other functions of the same name with optional parameters at the end MyFunc(Param1, Param2) and MyFunc(Param1, Param2, Param3). You must identify this by listing the functions consecutively in the GDKTable.txt and by adding a value at the end of the function name to signify that it is of the same name but should be called only if its optional parameter is called. Here is an example of how to set this up properly:



If the function has parameters that need to be reordered simply add another % at the end of the parameter list and add the reordered parameters.

Put all of that together and this is the completed GDKTable.txt for Advanced Terrain. Notice how there is an extra command Set Terrain Split() at the top of the GDKTable. It's very important that you include one command with parameters from the original DBTable as the first line of the GDKTable. This command is used to resolve the plugin's dependencies at compile-time. The plugin will fail without this and not run.



To create the source code required to compile the plugin you need to pass the .gdt template file to GDKLib Builder.exe. It can be passed from the command line or by simply dragging and droping the file onto GDKLib Builder.exe.
 
GDKLib Builder will output two directories: Sources and Dependencies. The dependency file must be copied into the PureGDK compiler commands folder within your PureBasic program directory (typically located in ..\Program Files\PureBasic\PureGDK\commands).
 
The next step is to compile the generated source from the Sources directory. To do this, you must first have TailBite installed. Don't forget to restart the IDE if it was open during the TailBite installation otherwise you may encounter problems. To compile with TailBite after opening the source file go to Tools -> TailBite to compile. If you have a help file that you would like to have called when a user hits F1 for help while highlighting your command in the PureBasic IDE you can enter it in the following window that pops up, otherwise just hit OK.



The library that's generated by TailBite will be written to your ..\PureBasic\PureLibraries\UserLibraries folder.



If you plan to compile a threadsafe executable using this plugin then you must compile a threadsafe Tailbite library. You can enable this option in the TailBite manager (TBManager.exe). After changing this setting you must restart the PureBasic IDE for the changes to take effect. PureGDK plugins compiled as threadsafe must be copied into the PureGDKThreadSafe subsystem. Its location is ..\PureBasic\SubSystems\PureGDKThreadSafe\PureLibraries.

With your new library prepared, restart the PureBasic compiler to recognize that a new library exists by going to Compiler -> Restart Compiler from the PureBasic IDE. If you did everything correctly then your plugin should now work! That's all there is to it. :)

 

Outputting command syntax

PureGDK provides a tool for quickly outputting the syntax of a command generated by GDKLib Builder. This file is located in the plugins-sdk directory along with GDKLib Builder. To output a syntax file simply drag and drop your .gdt file on top of the executable or pass it from the command line. The syntax file will output to your current working directory.