Sorry your browser is not supported!

You are using an outdated browser that does not support modern web technologies, in order to use this site please update to a new browser.

Browsers supported include Chrome, FireFox, Safari, Opera, Internet Explorer 10+ or Microsoft Edge.

PureGDK / Tips for wrapping plugins

Author
Message
Vax Tracker
12
Years of Service
User Offline
Joined: 24th Jul 2005
Location:
Posted: 10th Apr 2012 19:38 Edited at: 11th Apr 2012 19:44
So through much trial and error I've gathered together some tricks for getting plugins to work with PureGDK. Now I've only tried these to extend the base DarkNet commands and to add in two more Matrix1Utils not already supported in PureGDK.

Things you will need
1. PureGDK installation. Duh I know but just covering my bases.
2. Dependency Walker http://www.dependencywalker.com/ This is to find the plugin commands undecorated names.
3. Plugin documentation. This is really essential since as far as I know you can't extract the variable/return types from a dll.


Adding a user (non-liscensed) plugin
1) Add a new template for the plugin or append to an existing plugin. (for instance for adding the matrix1utils I simply appended to the existing Matrix1Util template)
a)To add a new template navigate to your PureGDK installation usually at C:\Program Files (x86)\PureGDK
-Open the libraries folder
-Open the plugins-user folder
-Create a new text document and save it as "[Some name].gdt"(remove quotes and insert your plugin name in place of [Some name])
b)Or to append to an existing template file simply open the file of choice and scroll to the bottom of the template.
Continue once you have the template file open you will be using.

2)Create the template commands.
This is the hardest part. For this you'll need to use both Dependency walker and your plugin documentation.

a)Syntax:
; - this denotes a comment in the template file. Anything written on the line after ; is completely ignored by the puregdk compiler

basic layout of a command is:
pluginName.dll%YourCommandName[%VariableTypes%UndecoratedDllName%VariableList[\code]

All of the above parts are required for every command except the [ after YourCommandName. The [ is only there for commands that return a value.

-pluginName.dll should be pretty self explanatory it's the name of the dll
-YourCommandName is whatever you want to call the command. Since all this is is a wrapper for the dll, this name doesn't matter except so you know what it's referencing.
-[ as said before this is there if the command returns a value. Knowing if this should be there is totally dependent on the documentation of the plugin you have. If the documentation says it returns a value you put the [ there. If the documentation says it does not return a value then do not put the [ there as it will mess up the compiler.
-VariableTypes This is also dependent on the documentation in order to know what variables the return type, and parameters are. This will simply be a list of the types of the parameters with the return type of the function at the beginning if the function returns a variable. See Variable Types to learn more about the various options I've discovered.
-UndecoratedDllName You'll need to use dependency walker to get this as this is how PureGDK references the function within the plugin. Scroll down to Using Dependency Walker to see how to get this name.
-VariableList This is a comma delimited list of the Parameters required for the command. I believe the name of the Parameters don't matter, but the types have to match the types in the VariableTypes list and what the documentation says. See Variable Types to see the tags needed to match data types.

b)Example:
Matrix1Util_31.dll

Matrix1Util_31.dll%M1U_ClearLookup%L%ClearLookup%LookupID
Matrix1Util_31.dll%M1U_CombineLookup%LL%CombineLookup%LookupID, TargetLookupID
Matrix1Util_31.dll%M1U_DeleteLookup%LS%DeleteLookupValue%LookupID, Key.s
Matrix1Util_31.dll%M1U_DeleteLookup%L%DeleteLookup%LookupID
Matrix1Util_31.dll%M1U_DuplicateLookup%LL%DuplicateLookup%SourceLookupID, TargetLookupID
Matrix1Util_31.dll%M1U_FindFreeLookup[%LLL%FindFreeLookupRange%Start, RangeSize
Matrix1Util_31.dll%M1U_FindFreeLookup[%L%FindFreeLookup
Matrix1Util_31.dll%M1U_GetLookupGetMode[%LL%GetLookupGetMode%LookupID
Matrix1Util_31.dll%M1U_GetLookupSetMode[%LL%GetLookupSetMode%LookupID
Matrix1Util_31.dll%M1U_LookupExist[%LLS%LookupKeyExists%LookupID, Key.s
Matrix1Util_31.dll%M1U_LookupExist[%LL%LookupExist%LookupID
Matrix1Util_31.dll%M1U_LookupReserved[%LL%LookupReserved%LookupID
Matrix1Util_31.dll%M1U_LookupSize[%LL%LookupSize%LookupID
Matrix1Util_31.dll%M1U_Lookup[%SLSS%GetLookupValueDefault%LookupID, Key.s, Default.s
Matrix1Util_31.dll%M1U_Lookup[%SLS%GetLookupValue%LookupID, Key.s=""
Matrix1Util_31.dll%M1U_MakeLookup%L%MakeLookup%LookupID
Matrix1Util_31.dll%M1U_ReleaseReservedLookup%L%ReleaseReservedLookup%LookupID
Matrix1Util_31.dll%M1U_ReserveFreeLookup[%LLL%ReserveFreeLookupRange%Start, RangeSize
Matrix1Util_31.dll%M1U_ReserveFreeLookup[%L%ReserveFreeLookup
Matrix1Util_31.dll%M1U_SetLookup%LSS%SetLookupValue%LookupID, Key.s, Value.s
Matrix1Util_31.dll%M1U_SetLookupGetMode%LL%SetLookupGetMode%LookupID, Mode
Matrix1Util_31.dll%M1U_SetLookupSetMode%LL%SetLookupSetMode%LookupID, Mode
Matrix1Util_31.dll%M1U_FirstLookup%L%LookupFirst%LookupID
Matrix1Util_31.dll%M1U_LastLookup%L%LookupLast%LookupID
Matrix1Util_31.dll%M1U_LookupCurrentKey[%SL%GetLookupCurrentKey%LookupID
Matrix1Util_31.dll%M1U_LookupCurrentValue[%SL%GetLookupCurrentValue%LookupID
Matrix1Util_31.dll%M1U_LookupIsValid[%LL%LookupValid%LookupID
Matrix1Util_31.dll%M1U_NextLookup%L%LookupNext%LookupID
Matrix1Util_31.dll%M1U_PrevLookup%L%LookupPrev%LookupID
Matrix1Util_31.dll%M1U_SearchLookup[%LLS%LookupFind%LookupID, Key.s
Matrix1Util_31.dll%M1U_IsValidIniKey[%LS%IsValidIniKey%Key.s
Matrix1Util_31.dll%M1U_MakeLookupFromIni%LS%MakeLookupFromIni%LookupID, IniFilename.s
Matrix1Util_31.dll%M1U_SaveLookupToIni%LS%SaveLookupToIni%LookupID, IniFilename.s
[\code]

Here is the code I appended to the Matrix1Util.gdt template to add support for the 31st Matrix1Util. Extracting two to take a look at:


Matrix1Util_31.dll%M1U_DeleteLookup%LS%DeleteLookupValue%LookupID, Key.s
Matrix1Util_31.dll%M1U_Lookup[%SLS%GetLookupValue%LookupID, Key.s=""

You can see how this is done.
-Matrix1Util_31.dll as the plugin that I'm refencing
-%
-M1U_DeleteLookup and M1U_Lookup are the names I chose to use as it follows the standard Mistrel was already following though I could have easily called them anything else
-now here is where you see the difference between a command that returns a value and one that does not. This first command I listed does not have the [ as it does not return a value, though the second one does.
-LS and SLS for the first one this means that the function takes two parameters a 32bit integer(L), and a string(S) and for the second one this means that it returns a string(s), and requires two other parameters a 32bit integer(L), and a string(S).
-%
-DeleteLookupValue and GetLookupValue as you can see here the Undecorated names do not always follow the convention written in the documentation so you have to be careful when using Dependency Walker to make sure you are referencing the correct function.
-%
-LookupID, Key.s(="") though both similar, the second is different as it adds a default value to the variable. So if it's not set it will default to "". Also note the .s after the Key parameter. This signifies that it is a string parameter.

Continue once all commands have been converted. You can run the "Compile Headers And Libraries" .bat file in the root directory to see if any errors arise. Save and close the template file.

3)Verify your dll is in the right spot.
a)Navigate to your root PureGDK install location again.
b)From there open engine
c)open plugins-user
d)Verify your plugin is here if not, copy it to this directory.

4)Add it to the compiler list
a)Navigate to yoru root PureGDK install location again.
b)Open Bin
c)Open the libraries file in Notepad or text Editor of your choice
d)Append your plugin to the end of the User plugins list in the form pluginName.dll%Unique reference name. where the Unique reference name can be whatever you want.
e)Save and close this file.

5)Finally compile engine with plugins and enjoy!
Finally run the "compile engine with plugins" .bat file in the root install and everything should compile correctly and your plugin is ready to use.

Licensed plugins
Everything is exactly the same as user plugins except you just change folders from plugins-user to plugins-licensed. And you have to make sure all the appropriate certificates are available to the compiler
1) To make sure all the certificates are available:
a) Navigate to your root Dark Basic Install
b) Open Compiler
c) Open certificates
d) Select all files and copy them to [%PureGDKRoot]/engine/certificates
e) If after this the plugin still doesn't work try running TGCOnline.exe in the PureGDK/engine folder to verify the certificates.

Variable Types
L - 32bit Integer also used in place of a boolean return type (0 = false, 1 = true) parametertag: (none)
R - 64bit variable(DWORD) parametertag: .r
S - string variable parametertag: .s
F - float variable parametertag: .f
O - double variable parametertag: .d
P - void pointer parametertag: * this goes at the beginning of the parameterName however
0 - this is only used if the function does not have a return or any parameters

Using Dependency Walker
1) Open Dependency Walker
2) Click the folder icon
3) Navigate to your dll and open it
4) The view will be split into multiple windows, the one you care about is the top rightish one. It should show a list of Functions.
5) Right click on this list and make sure the Undecorate C++ functions is checked. This is the list you'll use to find the UndecoratedDllName.
Olby
14
Years of Service
User Offline
Joined: 21st Aug 2003
Location:
Posted: 12th Apr 2012 22:53 Edited at: 12th Apr 2012 22:58
This is really useful! Original docs might be confusing for some but this practical example clearly tells what and how to do. I would suggest Mistrel (when he returns ) to add this to PGDK docs.

ACER Aspire 5920G: Core2Duo 2.2GHZ, 2GB, GeForce 8600M GT 1280MB, Windows Vista Ultimate SP1, PureBasic 4.60 + PureGDK 2.0

Login to post a reply

Server time is: 2017-11-22 10:55:34
Your offset time is: 2017-11-22 10:55:34