Updated: by Mike Potter (Zugg)

Related Articles:

• COM Programming in zMUD
• zMUD COM using zMUD
• Programming ADO in zMUD
• COM Plugins

zMUD can be controlled remotely using it's COM object interface.  Since most programming languages support COM, this means you can access and control zMUD from: Visual Basic, Visual C/C++, Delphi, C++Builder, etc.  You can even access COM objects from ASP web pages!

This document describes the zMUD COM interface.

NOTE: This document is for zMUD version 6.26 and later.  Earlier versions of zMUD did not have COM support, or did not support all of the interfaces described here.

Classe Index:

zMUDClass, zMUDSession, zMUDObject, zMUDClassRec, zMUDTrigger, zMUDTrigState, zMUDVar, zMUDMacro, zMUDButton, zMUDMenu, zMUDDir

The Name of the zMUD COM Server

The first thing you will need to call zMUD is it's COM class name.  The name of the zMUD application is "Zmud.Application".  So, to open a link to the zMUD Com Server, you'd do something like this:

Set zmud CreateOLEObject("Zmud.Application")

NOTE: Most examples in this document will be for Visual Basic.

Properties and Methods of zMudClass

The following properties and methods are defined for zMudClass:

function OpenSession(const SessionName, Password: WideString; Connect: WordBool): IzMUDSession; 

Opens a new zMUD session.  You must give the name of the session (corresponding to the Session name for the character in the zMUD character list), and the Password.  Use a "" for the Password if it is not set for this character.  The Connect flag determines whether zMUD will connect to the MUD (online) or not (offline mode).  A link to a zMUDSession COM Object is returned.  See the section below to find out what you can do with a zMUDSession object.

function OpenHost(const Hostname: WideString; Port: Integer): IzMUDSession;

Opens a new zMUD window.  You must give the Hostname and Port to connect to.  A link to a zMUDSession COM Object is returned.  See the section below to find out what you can do with a zMUDSession object.  This is similar to the zMUD #SESSION command.

property zMUDVersion: Integer;  READONLY

Returns the version number of zMUD.  The first digit is the major version number, and the last two digits are the minor version number.  So, for example, zMUD 6.03 returns 603.

property zMUDAppHandle: Integer;  READONLY

Returns the Windows handle to the main zMUD Application.

method zMUDFocus; 

Sets zMUD as the active application and returns the keyboard focus to the current MUD window.

property zMUDIsActive: WordBool;  READONLY

Returns true if zMUD is the currently active Windows application.

function zMUDWindow(const Name: WideString): Integer; 

Returns the Windows Handle of the named zMUD window.

method LoadPlugin(const Name: WideString; LoadFlag: WordBool); 

Loads (LoadFlag=true) or Unloads (LoadFlag=false) the named zMUD plugin.

method LoadPluginProc(const Name, ProcName: WideString; LoadFlag: WordBool);

Load or unload the specific method in the given plugin.

function OpenWindow(const WindowName: WideString): IzMUDSession; 

Opens a new zMUD window.  Simply give the Name of the Window to create and a link to a zMUDSession COM Object is returned.  See the section below to find out what you can do with a zMUDSession object.  This is similar to the zMUD #WINDOW command.

property NumWindows: Integer;  READONLY

Returns the number of MUD Windows currently open in zMUD.

function GetSessionNum(Index: Integer): IzMUDSession; 

Returns an existing zMUD window.  Index is the window number, starting from zero.  A link to a zMUDSession COM Object is returned.

property CurrentSession: IzMUDSession;  READONLY

Returns the current zMUD window.  A link to a zMUDSession COM Object is returned.

Properties and Methods of zMudSession

The zMUDSession is used to access a specific zMUD session.  You can create a zMudSession object using the class name "Zmud.ZmudSession", or you can get a session link using the methods of zMUDClass.  NOTE: If you create your own zMUDSession object, you MUST assign the Handle property to the Window's Handle of the MUD Window before the object will work.  There are still a few possible properties and methods missing, but this interface will be completed in the next few beta versions of zMUD.

A session is basically the same thing as a MUD window in zMUD.

The following properties and methods are defined for zMudSession:

property Handle: Integer; READ/WRITE

Retrieve or set the Window's Handle for this Session.  This is the key property for this object which is used to tie it to the internal zMUD objects.  You should normally not set this property.

method EchoStr(const S: WideString; Col: Integer);

Simply echo the string to the zMUD window.  Col is the color attribute to use.  This is the value returned by the %color zMUD function.

method SendStr(const S: WideString);

Send the given string to the MUD Session.  The string is not parsed but is sent directly to the MUD

method ProcessCommand(const S: WideString);

Process the string as a zMUD command.  Just as if the string had been typed into the zMUD command line.

function ExpandStr(const S: WideString): WideString;

Expand any zMUD variable references within the string and return the result

function EvaluateStr(const S: WideString): WideString;

Evaluate the string as a zMUD expression and return the result.

property IsActive: WordBool; READONLY

Indicates whether this session is the currently active zMUD session.  Use SetFocus to make this session the active one.

method SetFocus;

Make the session the currently active one and give it the keyboard focus.

function zMUDFunction(ComID: Integer; P: OleVariant): WideString;

Execute a zMUD Function and return the result.  ComID is the numeric ID of the function as listed in the ZMUD.INC file in the zMUD Developer's Kit.  P is the array of arguments for the function.  You must be able to create the standard Variant arrays in order to pass arguments to this method.  In Visual Basic, you create an array with the array(a,b,c) syntax.  In Delphi, you use VarArrayOf(a,b,c).  In zMUD, you use %array(a,b,c).

method zMUDCommand(ComID: Integer; P: OleVariant);

Execute a zMUD command for the current session.  ComID is the command ID as listed in the ZMUD.INC file in the zMUD Developer's Kit.  P is the array of arguments for the command.  You must be able to create the standard Variant arrays in order to pass arguments to this method.  In Visual Basic, you create an array with the array(a,b,c) syntax.  In Delphi, you use VarArrayOf(a,b,c).  In zMUD, you use %array(a,b,c).  P is optional if the command doesn't require arguments.

property WindowName: WideString; READ/WRITE

Retrieve or Set the name of the session window.

function SpecialChar(Ch: Byte): Byte;

Translate a special character.  Ch is the "standard" special character value, and the actual character being used by this session is returned.  For example, to retrieve the current command separator character, use a Ch of ';'.

function zMUDFileName(const FileName, Subfolder: WideString): WideString;

Given the name of a file, and the subfolder within the character folder (like "DB", or "Maps"), return the full path to the file.

property CharName: WideString; READ/WRITE

Retrieve or set the MUD Character name for this session.

property Hostname: WideString; READ/WRITE

Retrieve or set the MUD Hostname for this session.

property Port: Integer; READ/WRITE

Retrieve or set the MUD Port number for this session.

method Connect;

Connect to the MUD.  If already connected, then disconnect and reconnect.

method Disconnect;

Disconnect from the MUD.  Goes into Offline mode.

method UpdateButtons;

Recreate the buttons on the toolbar and the items in the status bar.

 

function MakeClass(const Name: WideString): IzMUDClassRec;

Create a New class for the session and return it as a zMUDClassRec COM Object.  Name is the class name.

function MakeAlias(const Name, Commands, ClassName: WideString): IzMUDObject;

Create a New alias for the session and return it as a zMUDObject COM Object.  Name is the alias name, Commands is the zMUD command(s) to execute, and ClassName is the name of the class ("" to use the current class).

function MakeVar(const Name, VarValue, DefValue, ClassName: WideString): IzMUDVar;

Create a New variable for the session and return it as a zMUDVar COM Object.  Name is the name of the variable, VarValue is it's current value, DefValue is its default value, and ClassName is the class folder. IzMUDVar is a descendant of IzMUDObject.

function MakeFunction(const Name, Definition, ClassName: WideString): IzMUDVar;

Create a New function for the session and return it as a zMUDObject COM Object.  Name is the function name, Definition is the zMUD script for the function, and ClassName is the class folder. IzMUDVar is a descendant of IzMUDObject.

function MakePath(const Name, PathName, ClassName: WideString): IzMUDObject;

Create a New path for the session and return it as a zMUDObject COM Object.  Name is the path name, and PathName is the path definition, ClassName is the class folder.

function MakeTrigger(const Pattern, Commands, ClassName: WideString; Flags: Integer): IzMUDTrigger;

Create a New trigger for the session and return is as a zMUDTrigger COM Object.  Pattern is the trigger pattern, Commands is the zMUD command(s) to execute, ClassName is the name of the trigger class ("" to use the current class), and Flags are optional flags.  Set Flags to zero for the default flag settings.  IzMUDTrigger is a descendant of IzMUDObject.

function MakeAlarm(const Pattern, Commands, ClassName: WideString; Flags: Integer): IzMUDTrigger;

Create a New alarm trigger for the session and return it as a zMUDTrigger COM Object.  Pattern is the alarm time pattern, Commands is the zMUD command(s) to execute, ClassName is the name of the trigger class ("" to use the current class), and Flags are optional flags.  Set Flags to zero for the default flag settings. IzMUDTrigger is a descendant of IzMUDObject.

function MakeKey(const KeyName, Commands, ClassName: WideString; Flags: Integer): IzMUDMacro;

Create a New macro key for the session and return it as a zMUDMacro COM Object.  KeyName is the name of the key (such as "F1" or "ALT-F1"), Commands is the zMUD command(s) to execute, ClassName is the class folder, and Flags are optional values.  Set Flags to zero for default flags. IzMUDMacro is a descendant of IzMUDObject.

function MakeButton(ButtonNum: Integer; const Captions, Commands, ClassName: WideString): IzMUDButton;

Create a New button for the session and return it as a zMUDButton COM Object.  ButtonNum is the button number to create.  Captions is the string list of captions for the button states.  Commands is the string list of commands for each button state.  ClassName is the name of the class ("" to use the current class). IzMUDButton is a descendant of IzMUDObject.

function MakeButtonFull(ButtonNum: Integer; const OffCaption, OnCommand, OnCaption, OffCommand, Expression, VarName, BitmapName: WideString; AutoSize: WordBool; Width, Height: Integer; AutoPos: WordBool; Top, Left, OffCol, OnCol: Integer; Seperator: WordBool; Margin: Integer; const ClassName: WideString; ExplorerStyle: WordBool; const ToopTip: WideString): IzMUDButton;

Create a New button for the session and return it as a zMUDButton COM Object.  All properties for the button can be specified using this method. IzMUDButton is a descendant of IzMUDObject.

function MakeMenu(const Caption, Commands, ClassName: WideString): IzMUDMenu;

Create a New speed menu item for the session and return it as a zMUDMenu COM Object.  Caption is the menu caption, Commands is the zMUD command(s) to execute, and ClassName is the class folder. IzMUDMenu is a descendant of IzMUDObject.

function MakeTab(const Name, ClassName: WideString): IzMUDObject;

Create a New tab word for the session and return it as a zMUDObject COM Object.  Name is the tab word, and ClassName is the class folder.

function MakeStatus(const S, ClassName: WideString): IzMUDObject;

Create a New status bar entry for the session and return it as a zMUDObject COM Object.  S is the text for the status bar and ClassName is the class folder.

function MakeDir(const DirChar, CommandList, MapDir, ClassName: WideString): IzMUDDir;

Create a New direction for the session and return it as a zMUDDir COM Object.  DirChar is the direction character.  If the direction has a reverse character, add it to the end of the DirChar.  CommandList is the string list of MUD commands corresponding to the direction, MapDir is the mapper direction name, and ClassName is the class folder. IzMUDDir is a descendant of IzMUDObject.

 

function GetClass(const Name): IzMUDClassRec;

Return the named Class as a zMUDClassRec COM Object.

function GetAlias(const Name, ClassName: WideString): IzMUDObject;

Return the named Alias in the given ClassName as a zMUDObject COM Object.

function GetVar(const Name, ClassName: WideString): IzMUDVar;

Return the named variable in the given ClassName as a zMUDVar COM Object.

function GetPath(const Name, ClassName: WideString): IzMUDObject;

Return the named Path in the given ClassName as a zMUDObject COM Object.

function GetTrigger(const Pattern, ClassName: WideString): IzMUDTrigger;

Return the named trigger Pattern in the given ClassName as a zMUDTrigger COM Object.

function GetKey(const KeyName, ClassName: WideString): IzMUDMacro;

Return the named key macro in the given ClassName as a zMUDMacro COM Object.

function GetMenu(const Caption, ClassName: WideString): IzMUDMenu;

Return the named speed menu item in the given ClassName as a zMUDMenu COM Object.

function GetTab(const Name, ClassName: WideString): IzMUDObject;

Return the given tab word in the given ClassName as a zMUDObject COM Object.

function GetStatus(const Caption, ClassName: WideString): IzMUDObject;

Return the named Status bar item in the given ClassName as a zMUDObject COM Object.

function GetDir(DirChar: Byte; const ClassName: WideString): IzMUDDir;

Return the given Direction in the given ClassName as a zMUDDir COM Object.

 

property NumClasses: Integer; READONLY

Return the total number of classes for the session.

property NumAliases: Integer; READONLY

Return the total number of aliases for the session.

property NumVars: Integer; READONLY

Return the total number of variables for the session.

property NumPaths: Integer; READONLY

Return the total number of paths for the session.

property NumTriggers: Integer; READONLY

Return the total number of triggers for the session.

property NumMacros: Integer; READONLY

Return the total number of macros for the session.

property NumMenus: Integer; READONLY

Return the total number of speed menu items for the session.

property NumTabs: Integer; READONLY

Return the total number of tab words for the session.

property NumStats: Integer; READONLY

Return the total number of status bar definitions for the session.

property NumDirs: Integer; READONLY

Return the total number of directions for the session.

 

function ClassNum(Index: Integer): IzMUDClassRec;

Index is the class number to retrieve (starting at zero, up to NumClasses-1).

function AliasNum(Index: Integer): IzMUDObject;

Index is the alias number to retrieve (starting at zero, up to NumAliases-1).

function VarNum(Index: Integer): IzMUDVar;

Index is the variable number to retrieve (starting at zero, up to NumVars-1).

function PathNum(Index: Integer): IzMUDObject;

Index is the path number to retrieve (starting at zero, up to NumPaths-1).

function TriggerNum(Index: Integer): IzMUDTrigger;

Index is the trigger number to retrieve (starting at zero, up to NumTriggers-1).

function MenuNum(Index: Integer): IzMUDMenu;

Index is the menu item number to retrieve (starting at zero, up to NumMenus-1).

function MacroNum(Index: Integer): IzMUDMacro;

Index is the macro number to retrieve (starting at zero, up to NumMacros-1).

function TabNum(Index: Integer): IzMUDObject;

Index is the tabword number to retrieve (starting at zero, up to NumTabs-1).

function StatNum(Index: Integer): IzMUDObject;

Index is the status item number to retrieve (starting at zero, up to NumStats-1).

function DirNum(Index: Integer): IzMUDDir;

Index is the direction number to retrieve (starting at zero, up to NumDirs-1).

Properties and Methods of zMudObject

The zMUDObject object is the base object used to access specific settings in a session, such as aliases, triggers, variables, etc.  You can access the common object properties with this.  If you wish to access properties specific to a setting, use the specific object for that setting type, described later.

The following properties and methods are defined for zMudObject:

property Name: WideString; DEFAULT

Retrieve or Set the name of an object.  This is the default property for zMUD objects.

property ClassName: WideString; 

Retrieve or Set the Class folder name of an object

property Value: WideString; 

Retrieve or Set the Value of an object

method DeleteObject; 

Delete the object from the session

method Change;

Marks the object as being changed and updates the zMUD user interface.

property ID: WideString;

The optional ID name for the setting

property Enabled: Boolean;

Determines if this setting is enabled or disabled.

property Comment: WideString;

A one-line comment for this setting

property ClassNum: Integer;

The class folder number that this setting resides in.

property Inherited: Boolean; READ ONLY

Returns true if this is an inherited setting.

property ObjType: zObjectType; 

Return the type of object.  zObjectType has the values: objBlank=0, objClass=1, objAlias=2, objVar=3, objPath=4, objTrigger=5, objMacro=6, objButton=7, objDir=8, objMenu=9, objTab=10, objStat=11

property ObjRef(Value: Integer); WRITE ONLY

Sets the object reference value for the object.  This is for INTERNAL use only and should not be used.

The zMUDClassRec Object

This object is used for zMUD Classes.  It has the following properties and methods in addition to those defined for zMUDObject:

property DisableInit: Boolean;

Determines if class is disabled when loaded

property EnableInit: Boolean;

Determines if class is enabled when loaded

property Hidden: Boolean;

Determines if class folder is hidden

property SetDefault: Boolean;

Determines if this class becomes the default creation class when triggers in the class create other settings.

property Submenu: Boolean;

Determines if this class is a collection of menu items for a button or submenu

The zMUDVar Object

This object is used for zMUD Variables.  It has the following properties and methods in addition to those defined for zMUDObject:

property UseDefault: Boolean;

Determine if default value should be used when initially loading this variable

property Default: WideString;

The default value of the variable

property OLEVal: OLEVariant;

The value of the variable when a COM object, or array is assigned to it.

The zMUDTrigger Object

This object is used for zMUD Triggers.  The Name and Value properties of the parent zMUDObject type always reference the current trigger state only.  zMUDTrigger has the following properties and methods in addition to those defined for zMUDObject:

property Current: IzMUDTriggerState; READ ONLY

Returns the current state record for the trigger

property StateNum: Integer;

Current state of the trigger, starting at zero.

function GetState( Index: Integer): IzMUDTriggerState;

Returns the specified trigger state

The zMUDTriggerState Object

This object is used for zMUD Trigger states.  It has the following properties and methods:

property Pattern: WideString;

The pattern for this trigger state

property Value: WideString;

The commands to execute for this trigger state

property CaseSens: Boolean;

Determines if the trigger state is case sensitive

property NewLine: Boolean;

Determines if trigger state waits until a new line to fire

property Prompt: Boolean;

Determines if trigger fires when the MUD pauses in sending text to zMUD

property TrigOnTrig: Boolean;

Determines if other triggers can fire while this trigger is running

property Fired: Boolean;

Determines if this state has fired or not.

property Kind: zTrigStateType;

Sets the type of trigger state.  It has the values: zTrigPattern=0, zTrigExp=1, zTrigAlarm=2, zTrigInput=3, zTrigSkip=4, zTrigWait=5, zTrigLoopPat=6, zTrigLoopLine=7, zTrigLoopExp=8, zTrigDur=9, zTrigManual=10, zTrigWithin=11, zTrigMXP=12, zTrigRegEx=13, zTrigReparse=14

property Param: Integer;

The parameter used for the specific state type

property ObjRef( Value: Integer); WRITE ONLY, INTERNAL ONLY

Used to set the internal trigger reference.  Do not use.

property ObjRefState( Value: Integer); WRITE ONLY, INTERNAL ONLY

Used to set the internal state reference.  Do not use.

The zMUDButton Object

This object is used for zMUD Buttons.  The Name and Value properties of the parent zMUDObject type always reference the "off" button state only.  zMUDButton has the following properties and methods in addition to those defined for zMUDObject:

property AlignRight: Boolean; 

Determines if the button is aligned to the right or bottom part of the panel

property AutoPos: Boolean; 

If set, the Left and Top values are ignored and the button is positioned automatically on the panel

property AutoSize: Boolean; 

If set, the Height and Width values are ignored and the button is given the default size

property BitmapName: WideString; 

Specifies the name of a BMP file or an internal bitmap name for the button

property ExplorerStyle: Boolean; 

Determine if button is "Explorer" style where it shows the border only when the mouse is over it.

property ExpressionStr: WideString; 

Gives the zMUD Expression used to auto-determine the state of the button

property GaugeBackColor: Integer; 

Set the color attribute of the gauge background

property GaugeLowColor: Integer; 

Set the color attribute of the gauge when the value of the gauge is less than the GaugeLowExpression.

property GaugeLowExpression: WideString; 

The zMUD Expression used to determine if the gauge value is low

property GaugeMaxExpression: WideString; 

The zMUD Expression used to set the maximum value of the gauge

property Height: Integer; 

The height of the button in pixels

property IconLeft: Boolean; 

Determines if the icon is to the left of the caption instead of above it

property Inset: Boolean; 

Determines if the button appears to be inset into the background

property Kind: zButtonType; 

Determines the type of button.  Values are: zButtonPush=0, zButtonToggle=1, zButtonMulti=2, zButtonGauge=3, zButtonSeperator=4, zButtonMenu=5

property Left: Integer; 

The left position of the button in pixels

property Margin: Integer; 

The number of pixels between the icon and the caption of the button

property MenuClassName: WideString; 

The name of the class containing menu items for Menu buttons

property MouseOverHint: WideString; 

The text displayed when the mouse is over the button

property NumStates: Integer;  READONLY

The number of states in the button.  To add more states, simply set the StateName, StateCom properties using an Index value larger than the current number of states.

property OffCaption: WideString; 

The Caption of the button when it is off (not depressed)

property OffColor: Integer; 

The color of the button when it is off

property OffCommand: WideString; 

The command executed when the button changes from the On to the Off state

property OnCaption: WideString; 

The caption of the button when it is on (depressed)

property OnColor: Integer; 

The color of the button when it is on

property OnCommand: WideString; 

The command executed when the button changes from the Off to the On state

property Panel: Integer; 

The panel number (1 to 4) containing the button

property Stacked: Boolean; 

Determines whether the button is stacked with the previous one

property StateColor(Index: Integer): Integer; 

The color of the button when in the specified state

property StateCommand(Index: Integer): WideString;

The command executed when the button reaches the specified state 

property StateName(Index: Integer): WideString; 

The name of the specified button state

property Top: Integer; 

The top of the button in pixels

property VarName: WideString; 

The name of the zMUD variable that controls the state of this variable

property Width: Integer; 

The width of the button in pixels.

The zMUDMacro Object

This object is used for zMUD Macros.  It has the following properties and methods in addition to those defined for zMUDObject:

property Key: Integer;

The windows virtual key and shift status for the macro (actually a WORD value)

property AllowChain: Boolean;

Determine if this key can daisy chain from a previous macro

property Send: Boolean;

Determine if macro value is sent to the MUD

property Append: Boolean;

Determine if the macro value is appended to the command line.

The zMUDMenu Object

This object is used for zMUD Menus.  It has the following properties and methods in addition to those defined for zMUDObject:

property SubClassName: Integer;

Specifies the name of the class containing submenu items for this menu

The zMUDDir Object

This object is used for zMUD Directions.  It has the following properties and methods in addition to those defined for zMUDObject:

property ReverseChar: WideString;

The letter used to reverse this direction in speedwalking

property MapDir: zMapDirType;

Determines the direction moved in the mapper: Values are zDirN=0, zDirNE=1, zDirE=2, zDirSE=3, zDirS=4, zDirSW=5, zDirW=6, zDirNW=7, zDirU=8, zDirD=9, zDirOther=10, zDirNone=11

Examples of using the zMUD COM Server

The ZMUD.EXE file contains the Type Library for all of the zMUD COM Objects.  In a Delphi or C++Builder project, simply use the Projects/Import Type Library menu command.  Choose to create a Unit for the type library.  Then you can program zMUD using real objects.  For example, here is how you can send the list of aliases for the current MUD session to a TList object in Delphi:

var
  cc: Variant;
  ss: Variant;
  o:  Variant;
  I, N: integer;
begin
  cc := CreateOLEObject( 'Zmud.Application');
  ss := cc.CurrentSession;
  N := ss.NumAliases;
  for I := 0 to N-1 do begin
    o := ss.AliasNum(I);
    if assigned(o) then AliasList.Items.Add( o.Name);
    end;
  cc := Unassigned;
end;

In Visual Basic, you would do something like this:

dim cc as Object
dim ss as Object
dim o as Object

Set cc = CreateObject( "Zmud.Application")
Set ss = cc.CurrentSession
N = ss.NumAliases
for I = 0 to N-1
  Set o = ss.AliasNum(I)
  Call lstAliases.AddItem(o.Name)
next

Set cc = Nothing

In zMUD, you would do something like this:

#VAR cc %comcreate("Zmud.Application")
#VAR ss @cc.CurrentSession
#VAR N @ss.NumAliases
#LOOP 0,@N-1 {#ECHO @ss.AliasNum(%i).Name}
#VAR cc ""