Magsbot Plug-In Examples
requires Magsbot version 6.0 or later to work
(If you have any questions, comments or suggestions, please post them on the Magsbot forum.)

Magsbot 6.0 supports plugins that let you add your own functions and commands to Magsbot by writing DLLs in Delphi.  To do this, you need the PlugIn support files, MBotCalls.pas, PublicMBTypes.pas and CFuncs.pas. You also need to download the  Recycler Memory Manager (it's free!) and include the RecyclerMM.pas file from that in your DLL, adding RecyclerMM as the first module in the project file (.DPR).  (Note: use version 1.0 or 1.3 of the RMM, version 1.2 doesn't seem to work so good with this.)

The progressively more detailed examples below show you how to write a Magsbot PlugIn. Note that the example zip files may not include the most recent copies of the support files, so if you are creating a new plugin of your own, you should download the latest support files (MBotCalls.pas and PublicMBTypes.pas) separately.

(Note in earlier versions of Magsbot it was possible to write DLLs and call the functions from those DLLs from Magsbot using the CALLDLL command; however this new functionality in version 6.0 provides the ability to add functions and commands to the Magsbot script language itself.)



The first example, MBPlugInExample.zip, shows how to use Delphi to create a plug-in for Magsbot in the form of a DLL for use with the new CALLDLLV command in Magsbot 6.0, which works similarly to the old CALLDLL command (which still exists as well), except that the third argument to CALLDLLV, instead of being a string that is passed to the DLL, is a vlist that is passed and which can contain whatever values you want. This example DLL shows how to get/put values from/to the vlist from within your DLL.  Also, if you put a string variable named $cmd in the vlist, Magsbot will execute it as a command when the function ends.

New in this version is the ability for your Delphi DLL to call upon functions in the Magsbot executable, MBot.exe. This allows your DLL to be a true "plug-in", tapping the internal functionality of the program, allowing you to add your own internal functions (not just macros as in .udf, or action buttons, but functions written in Delphi that will be merged with the built-in Magsbot functions) and even to add new commands! (The main problem here for me is going to be writing all the documentation to explain how to use the internal Magsbot functions...)

All this wonderful new functionality is due to the Recycler Memory Manager now incorporated into Magsbot, that allows memory to be easily shared between the program and the DLLs.

Therefore, you also need RecylerMM (a third-party memory manager for Delphi programs) in order to compile this, which I didn't include in this package since you should get it directly from Source Forge. Note: The 1.2 version of Recycler doesn't seem to work for this, so get the 1.0 version. Just put the RecyclerMM.pas file in the folder with the rest of the source code in this package and compile. (You also need to put RecyclerMM as the first module in the Uses clause of the .dpr, but I've already done that in this example.)

The PlugIns.btn file contains calls to the example functions, in the buttons Open Form, EvaluateExpression and Close Form.

MBotDLLs.lst should contain:

MBPlugIn OpenForm
MBPlugIn EvaluateExpression
MBPlugIn CloseForm


Note you don't have to call OpenForm to use the EvaluateExpression function. However, if you open the form, then you should REMEMBER TO CLOSE THE FORM BEFORE QUITTING MAGSBOT, or you'll get an error message.

Also--IMPORTANT!-- make sure that your magsbot.ini file has DLLListPath in the [DLLs] section set to MBotDLLs.lst, or the DLLs won't load when Magsbot starts.


The second example PlugInExample2, goes a step farther and shows how you can write your own functions in Delphi and add them to Magsbot's built-in functions.  (Documentation to come...but for now you can probably get an idea of how it works from the documentation in the program itself.) You also need Recycler Memory Manager to compile this example, as with the first.

This example adds the functions:

    @mynewfunc[$anystring,@any_integer,@any_float]
and
    $mynewfunc[$anystring,@any_integer,@any_float]

For the second example, MBotDLLs.lst should contain:

MBPlugIn OpenForm
MBPlugIn Install
MBPlugIn EvaluateExpression
MBPlugIn CloseForm


The third example PlugInExample3, goes another step and shows how you can write your own commands in Delphi and add them to Magsbot's built-in command set.  (Documentation to come...but for now you can probably get an idea of how it works from the documentation in the program itself.) You also need Recycler Memory Manager to compile this example, as with the others.

This example adds the commands:

    MYFIRSTCOMMAND  $anystring @any_integer
and
    MYSECONDCOMMAND { any_action_sequence }

For the second example uses the same MBotDLLs.lst as the second example.


The fourth example PlugInExample4, does something practical: it adds a command that creates a "radar" window showing the location of avatars around the bot.  This example also shows how to hook event handlers and some other good stuff.  The included MBotCalls.pas and PublicMBTypes.pas files in this example are more developed that the ones included in the previous examples.  Magsbot 6.0 exports other useful functions and is required for this DLL to run.

MBPlugIn Install        this is automatically called when Magsbot starts, before the behavior table & buttons are loaded
MBPlugIn Initialize     this is automatically called when Magsbot starts, after the behavior table & buttons are loaded
MBPlugIn EventHandler   this is called automatically whenever a non-SDK event occurs
MBPlugIn Terminate      this is called automatically when Magsbot ends

PlugInExample5  has the same functionality as example five, but it demonstrates a different method of hooking event handlers. This method allows the plug-in to use the Magsbot queueing system, instead of getting AW attributes directly from the SDK. It requires Magsbot 6.1.2.

MBPlugIn Install        this is automatically called when Magsbot starts, before the behavior table & buttons are loaded
MBPlugIn EventHandler   this is called automatically whenever a non-SDK event occurs
MBPlugIn Terminate      this is called automatically when Magsbot ends