Updated:
by Mike Potter (Zugg)
Related Articles:
Creating a COM-based plugin for zMUD is fairly easy. With a bit
of practice and some basic understanding of COM and OLE-automation, you'll soon
be creating zMUD plugins that add all sorts of functionality to zMUD. You
can create COM-based plugins for zMUD in many different programming languages,
including Visual Basic, Delphi, C, C++, etc. This tutorial contains
examples for both Delphi and Visual Basic.
Terminology
zMUD Plugins can be written using two different methods: COM-based, and
API-based. API-based are traditional DLL files that export certain
procedures required by zMUD. This is the traditional method for creating
zMUD plugins and is described in more detail in the zMUD Developer's Kit.
This article covers COM-based plugins for zMUD. However, this
terminology is a bit misleading, since zMUD plugins are actually OLE Automation
Servers, which themselves are COM objects. Think of COM as a very general
framework, with OLE Automation Servers as a subset of that framework.
Specifically, all OLE Servers implement the IDispatch interface, rather than
the bare-bones IUnknown interface of regular COM objects. Any programming
language that you will create plugins with will handle the details of the
IDispatch interface, so you don't need to understand the details. However,
one important consequence of using OLE Automation Servers is that your plugin
will require a Type Library.
A Type Library is a set of information that describes your plugin and allows
it to be registered within Windows. The Type Library is typically linked
in with your DLL or EXE plugin file. Most programming languages allow you
to import and view type libraries, either installed on the system, or residing
in a DLL or EXE file.
zMUD itself has a Type Library called the "Zmud Library".
Simply load ZMUD.EXE into a Type Library viewer, or look for the Zmud Library in
the system registry.
To help with your plugin debugging, I've compiled a simple Type Library
viewer called TIViewer.exe.
This utility was written by Eric Harmon as part of his book "Delphi COM
Programming". Click on the filename above to download the
utility. It allows you to open a DLL or EXE file and view it's associated
type library.
The Basics
To create a zMUD Plugin, you need to create an OLE Automation Server that
implements the IzMUDPlugin interface. The IzMUDPlugin interface is defined
in the Zmud Type Library contained in ZMUD.EXE. I'll document all of the
methods and properties of this interface at the end of this document. The
IzMUDPlugin is simply an interface that describes the methods and properties
that you can implement in your plugin. Any OLE Automation Server that
implements this interface can be loaded into zMUD as a plugin. Some of the
methods and properties are required, many are optional.
So, pick whatever programming language you want to use, and learn how to
create an OLE Automation Server. I'm going to show a detailed example
using Delphi, and then in Visual Basic, but you should be able to create OLE Automation Servers in most
any language. It might take some practice to master the detailed steps
involved in creating an automation server.
Creating an OLE Automation Object in Delphi
Delphi 5 contains several wizards that make COM and OLE Automation very
easy. There are two types of automation servers that you can create:
in-process, and out-of-process. In-process servers are DLL library files
that end up getting loaded into the same memory space as zMUD when they are
running as plugins. These plugins run the fastest. Out-of-process
automation servers are EXE application programs that run alongside zMUD in a
separate memory space. Because data must be transferred back and forth
between the applications, these types of plugins run a bit slower than the
in-process DLL servers. However, since they are self-contained application
programs, you can do a bit more with them. For example, consider the zChat
plugin for zMUD. In addition to being a plugin, it is also a standalone
chat program. This is a good example of a zMUD plugin that should probably
be an out-of-process EXE plugin.
In the following detailed example, I'm going to create an in-process DLL
plugin. From the File menu, select New...and in the ActiveX tab page,
select the "Active X Library" to create a new library project.
Delphi will create a small DLL Library for you. Next, from the File menu,
select New...and in the ActiveX tag page, select the "Automation
Object".
Delphi will prompt you to name your OLE Automation Server object. Enter
a shortname for your object, without any spaces, in the CoClass Name
field. Leave the other fields at their default values, and click OK.
In this example, we will enter a name of "TestPlug"
Because you have created an Automation Object, Delphi will automatically
create a Type Library for you and load the Type Library Editor. In order
to implement the IzMUDPlugin interface, we need to edit this type library a bit
before it's ready.
By default, you'll see this in your Type Library editor:
Project1 is your DLL Library, ITestPlug is the default Interface for your OLE
Automation Object, and TestPlug is the object that implements the
interface. Now we just have to tell Delphi that we want to implement the
IzMUDPlugin interface in our object.
First, we need to load the zMUD Type Library into our project so that Delphi
can find the IzMUDPlugin interface. From the Project Menu, select Import
Type Library. Scroll to the bottom of the list, and if you have run zMUD
v6.05 on your system at least once, you'll see the zMUD Library entry.
Select it, then click the Create Unit button at the bottom of the window.
Accept the defaults and click OK. The unit ZMUD_TLB will be added to your
project. When you are bored someday, you might look through this
file. It contains all of the interface information for all of the OLE
Automation objects used by zMUD.
Now we've added the zMUD Type Library to our project, but we still need to
add it to the Type Library editor. Select the "Project1" line in
the Type Library editor. Then, on the right-side of the screen, click the
Uses tab. You'll notice that two type libraries are already being used,
but nothing else is shown. The trick here is to right-click on the
list of libraries, and select "Show All Type Libraries". Now
everything will be listed. Scroll down to the bottom, and click on the
checkbox next to the zMUD Library entry. What can I say...the user
interface of the Delphi Type Library is horrible (ok, I want to use even
stronger language than that, but I won't). Right-click on the list of
libraries and select "Show Selected" again. Now, your type
library list should look like this (your paths and folders will be different):
Good. Now that the Type Library Editor knows about zMUD, it's time to
fix the TestPlug object so that it implements the correct interface. Click
on the TestPlug object in the list on the left. Go to the Implements tab
on the right. Once again, right-click on the
interface list (aarggg) and select "Insert Interface" from the popup
menu. Select the IzMUDPlugin interface from the list.
Now, a very important step: click the "Refresh
Implementation" button in the toolbar of the Type Library editor.
It's the icon with the two green arrows on it. Clicking this button just
added a bunch of code to your object that will save you lots of typing. It
added all of the methods and properties for the IzMUDPlugin class, and builds
sample code for each one!! This is a huge time saver.
The final step involves a small bit of editing. Delphi never added the
ZMUD_TLB unit to the Uses clause of our object unit, so add this yourself.
The top of your code page should now read something like this:
unit Unit1;
interface
uses
ComObj, ActiveX, Project1_TLB, StdVcl, ZMUD_TLB;
type
TTestPlug = class(TAutoObject, ITestPlug, IzMUDPlugin)
protected
function Get_CanCapture: WordBool; safecall;
.
.
.
Now, SAVE YOUR WORK!!! Select "Save Project As" from the File
menu. You will first be prompted for the name of your Automation Object
Unit (the Unit1 in the above diagram). Give your plugin file a good
name. I have chosen "TestCom.Pas" (ok, so it's a horrible
name). Next, you will be prompted for the name of your Project. This
is very important: The name of your project will also be the name
of your plugin DLL file. So, choose a really good name here.
I have chosen "TestPlugin" for my project name.
That's it...you have now created an IzMUDPlugin OLE Automation object in
Delphi. Now, you just need to add the detailed implementation of your
Plugin.
Implementing your Plugin
When you created your OLE Automation object, Delphi filled in a lot of
skeleton code for you. This included empty implementations of each method
and property used by the IzMUDPlugin interface. Most of these routines are
optional. Also, you will notice a striking similarity between the names of
the plugin methods and the names of the API routines from the zMUD Developer's
Kit. This makes converting an old API plugin into a new COM plugin very
easy.
The most important required method that you must implement is the
Register method. The skeleton code for this method looks like this:
procedure TTestPlug.Register(var Name, Company, Regcode, Description,
Version, HelpFile: WideString; var LoadDef: WordBool);
begin
end;
Just like the RegisterPlugin routine in the zMUD Developer's Kit
documentation, the Register method requires that you fill in the Name of the
plugin, the Company (author) creating the plugin, your Developer's Kit
registration code, a short description of your plugin, the version string, the
name of the helpfile, and whether the plugin should be loaded by default.
Note that in v6.05 and later, plugins do not have to be registered
anymore. The license agreement for the zMUD Developer's Kit is being
rewritten. Plugins can now be created for personal use for free.
It's only when you want to distribute your plugin to other zMUD users that you
must pay the Developer's Kit registration fee. In either case, your plugin
will load into zMUD. If the plugin is not registered, the user will
get a message in the zMUD Plugin Manager stating that the plugin is not
registered.
So, an example implementation might look like this:
procedure TTestPlug.Register(var Name, Company, Regcode, Description,
Version, HelpFile: WideString; var LoadDef: WordBool);
begin
Name := 'Test Plugin';
Company := 'Zugg Software';
Regcode := '123456789012';
Description := 'This is a test plugin that does not do anything';
HelpFile := '';
LoadDef := true;
end;
Compile your plugin using the "Compile" command in the Project
menu. You shouldn't get any errors if you have followed this tutorial
exactly.
Installing your Plugin
Now you must tell zMUD about your new plugin. There are two ways to do
this. A program called "zRegPlugin.exe" is included in the zMUD
Developer's Kit. Simply run this program and give your plugin filename as
the parameter. Your plugin will then be installed for zMUD. This
method is intended for professional plugin developers who can include a call to
zRegPlugin in their installer script.
For regular users, it is easier to install the plugin from within zMUD
itself. Run zMUD. At the character selection screen, press
<ESC> to get a blank, default MUD window. From the Plugins menu,
select the Install command.
A list of currently installed plugins will be displayed:
When you select a plugin in the top list, information about the plugin
(obtained from the plugin's Register routine) is shown in the area below.
To install a new plugin, click the Install button. Locate your plugin file
(Testplugin.dll in the example case) and click Open. The new plugin will
be loaded into zMUD:
Notice that all the information that we entered into the Register method of
our OLE Automation object is shown here. To uninstall a plugin, click the
Remove button. The checkbox next to the plugin name indicated whether the
plugin is active and loaded. zMUD only calls the methods for active
plugins. You can Load and Unload plugins using the buttons on this form,
or just click the checkbox next to the plugin. Loading a plugin causes the
Init method of the plugin to be called. Unloading a plugin causes the
Close method of the plugin to be called. For example, if we check the box
next to the zChat plugin, zChat will be loaded into memory and will appear as a
blue-Z in our system tray. If we then uncheck the box, zChat will be
unloaded from memory. So, for some plugins, loading and unloading can take
a few seconds.
This Plugin Manager can handle both the new COM-based plugins, as well as the
older API-based plugins (such as the Prompt and zChat plugins shown here).
In case you need to mess with the low level details, information about what
plugins are installed is stored in the System Registry under the key:
HKEY_CURRENT_USER\Software\Zuggsoft\zMUD\Plugins
Detailed Description of Methods and Properties
Well, I promised a detailed look at all the methods and properties of the
IzMUDPlugin interface. But I'll save this information for the next public
version of the zMUD Developer's Kit. For now, go to the zMUD Developer's
Kit page (click on it from the main www.zuggsoft.com
page) and read about the API routines. The COM-based routines are very
similar to the API routines. This, plus the skeleton code that Delphi
generates should be enough to get you going for now.
Creating an OLE Automation Object in Visual Basic
Thanks to Zor for this section!
Creating a COM and OLE Automation object in Visual Basic is pretty easy since
Visual Basic does most of the work for you. Visual Basic can create both
in-process (DLL) and out-of-process (EXE) servers.
When you start Visual Basic you should be presented with the New Project
dialog shown below. If you have shut this option off you can select New
Project from the File menu.
If you want to create an in-process server you should select the
"ActiveX DLL" option - select the "ActiveX EXE" option if
you want to create an out-of-process server. In this example we will
create an in-process server using the ActiveX DLL project. It doesn't
matter which kind of server you want to write - Visual Basic handles them in
almost exactly the same way.
When you click on the Open button Visual Basic will create a blank project
with a single empty class - the project will be called Project1 and the class
will be called Class1. Since the program ID of your project in based on
the name of the project and the object you references is the name of the class
you will want to give them both descriptive names.
Click on Project1 and go to the properties window (press F4 as a handy
shortcut) and change the name to whatever you want - in this case I will call
the project TestPlugin.
Now do the same thing with Class1 - click on it in the Project window and
then change the name in the Properties window - in this example we will call the
class TestObject.
Now that we have the project created we need to hook it up to the zMUD
interface by adding a reference to the zMUD type library which is contained in
the zMUD executable. Select "References..." from the Project
menu and scroll the list all the way to the bottom. As long as zMUD is
installed on your computer you will see "Zmud Library" near the
bottom. Click the checkbox next to the library to select it and click on
the OK button.
At this point Visual Basic knows about the zMUD type library and the
interfaces that it contains and we can start to hook up the code - double click
on TestObject in the Project window and the code window for that class will
open. At this point the class should be empty (except for a possible
"Option Explicit" line depending on how you have the Visual Basic
options set) and you can start to add code.
First we need to tell Visual Basic that this class is going to implement the
IzMUDPlugin interface by adding the following line:
Implements IzMUDPlugin
At this point the Object list at the top of the TestObject code window should
have IzMUDPlugin in the list and the Procedure list should have all of the
procedures in that interface. This would be a good point to save your work
before we start to add code to the project so that it will compile and
run. Click on the Save button on the toolbar and fill in the names of the
files as Visual Basic asks for them - I called my class and project
TestObject.cls and TestPlugin.vbp respectively.
Note that if you try to compile at this point Visual Basic will complain -
this is because you've told it that the TestObject implements an Interface but
you have not written any code for that Interface - we'll do that in the next
section.
Implementing your Plugin
Now that we have the project setup it is easy to add code into it. The
first thing you need to do is provide a declaration of each method in the
IzMUDPlugin interface - these declarations do not need to do anything, but
Visual Basic will not compile the project until you have done this.
Select IzMUDPlugin from the Object list in the TestObject code window and
select each method from the Procedure list - Visual Basic will create empty
procedures each time you select a procedure that does not have a
definition. The most important definition that we need to write code for
is the Register method so that zMUD has basic information about your
plugin. The skeleton code for this procedure looks like:
Private Sub IzMUDPlugin_Register(Name As String, Company As String, Regcode As String, Description As String, Version As String, HelpFile As String, LoadDef As Boolean)
End Sub
A sample implementation might look like:
Private Sub IzMUDPlugin_Register(Name As String, Company As String, Regcode As String, Description As String, Version As String, HelpFile As String, LoadDef As Boolean)
Name = "Test Plugin"
Company = "Zor Software"
RegCode = "123456789012"
Description = "This is a test plugin that does not do anything"
HelpFile = ""
LoadDef = True
End Function
Compile your plugin using the "Make TestPlugin.dll" command in the
File menu. If you followed this tutorial correctly the code should compile
with no errors. You can now follow the instructions in the
"Installing Your Plugin" section of the Zuggsoft document to load your
plugin into zMUD.
That's it! Now you know how to create a zMUD Plugin using Visual Basic.
Conclusion
Right now, COM-based plugins have a similar interface to the older API-based
plugins. So, why should you bother with the new COM stuff? Well, the
answer is simple: the API is frozen...the COM interface is under active
development. Eventually, you'll be able to do a lot more to customize zMUD
using a COM-based plugin. In addition, as mentioned before, you can create
a COM-based plugin in both a DLL file, and a normal EXE file, which allows more
flexibility. Also, more development languages (such as Visual Basic) allow
you to create OLE Automation servers in an EXE file, while they do not create
DLL files.
The COM-based plugin framework for zMUD is still under active
development. Ideas and suggestions are always welcome. Please post
your ideas to the Developer's Forum on www.zuggsoft.com
and the plugin framework will get better and better due to your feedback.
Home
Forums
Downloads
Documentation
Zugg's Blog