library SamplePlugin; {This is a sample zMUD Plugin. Use this as a template for other plugins} {zMUDAPI VERSION 2} {Note that SysUtils is optional and is only used by the call to IntToStr in the ParseMUDLine sample procedure} uses SysUtils, zMUDAPI; {includes all the functions we can call} {$I zmud.inc} {include zMUD command IDs if you need to reference them} type PCharArray = Array[1..99] of PChar; {array used to pass parameter lists} procedure RegisterPlugin( Name, Company, Regcode, Description, Version, HelpFile: PChar; var LoadDef: Boolean); stdcall; {REQUIRED} {this routine is called to install your plugin. You must return the Name of the plugin, the name of your Company (or author name), and the Registration code that you are issued when you purchase the zMUD Developer's Kit. Without all of this information, the plugin will not install. Also note that only the registered version of zMUD (v5.30 and greater) will install your plugin. The Description of the plugin is optional information shown in the About box for the plugin. The Version number is shown in the About box for the plugin} {Plugins autoload the first time they are used. To disable this and force the user to manually load the plugin from the zMUD Plugins menu, set LoadDef to false. After the first time, plugin loading is determined by whether the plugin was last loaded or unloaded by the user in the Plugins menu} {HelpFile is the name of the *.HLP file for the plugin. If left blank, the name of the DLL file with HLP instead of DLL is used} begin {Note that this routine can also check whatever you wish to see if the user has purchased the plugin from you as well, so you are free to sell your plugins if you wish, or you can just distribute them freely. There are no license requirements other than being a registered zMUD user and registered user of the Developer's Kit} {This information is displayed within the About box for the plugin within zMUD} StrCopy( Name, PChar('Name of Plugin')); {this is the name of the plugin} StrCopy( Company, PChar('Registration Name')); {replace this with your actual registration name} StrCopy( Regcode, PChar('XXXXXXXXXXXX')); {replace XXXXXXXXXXXX with your actual reg code} {Note that you probably do not want to pass the Regcode in clear text like this in case someone snoops your DLL. Perform some sort of encoding so that the proper value is returned without it appearing as clear text} StrCopy( Description, PChar('Description of plugin')); {limited to 2046 characters} StrCopy( Version, PChar('1.0')); StrCopy( HelpFile, PChar('')); {use DLL file name as HLP file name} LoadDef := false; {do this to prevent autoloading the plugin the first time} InitAPI(0); {THIS LINE IS REQUIRED} {initializes the zMUDAPI.DLL} end; function PluginAPIVersion: Integer; stdcall; {REQUIRED} {Return the version of the zMUDAPI that is being used for this plugin. Your plugin will only be loaded by versions of zMUD that support this API version} {If this routine is omitted, your Plugin is assumed to be version 1} begin Result := 2; end; procedure InitPlugin; stdcall; {OPTIONAL} {This routine is called after the plugin is successfully registered. Do whatever initialization code you need here} begin end; procedure ClosePlugin; stdcall; {OPTIONAL} {This routine is called before zMUD exits. Do whatever cleanup code is needed here} begin end; {$I Sample.INC} {reference any .INC file created by CMDEDIT.EXE} procedure AddCommands( Filename: PChar; var ComVersion: Integer); stdcall; {OPTIONAL} {allows you to add commands to zMUD. Create a command file using the supplied CMDEDIT program. Include the resulting filename.INC file above to include your command symbols, and distribute the filename.DAT command file with your plugin.DLL file (you do not distribute the .INC file, it is just for the Delphi compiler)} begin StrCopy( Filename, PChar('SAMPLE.DAT')); {name of .DAT file created by CMDEDIT} ComVersion := PluginVers; {points to the current version stored in the .INC file} end; procedure PluginCommand( H: THandle; ComID, NumParam: Integer; ComStr: PChar; P, AllP: PCharArray); stdcall; {OPTIONAL} {Execute one of your plugin commands. ComID contains the ID number of the command to execute. ComStr contains the entire parameter list in case you need to parse it yourself. NumParam is the number of parameters passed in the P array. AllP contains the parameters %-1, %-2, %-3, etc which are the full command parameter list starting at the specified argument number} {H is the handle of the MUD window making the call} begin end; function PluginFunction( H: THandle; ComID, NumParam: Integer; ComStr: PChar; P: PCharArray; var L: Integer): PChar; stdcall; {OPTIONAL} {Execute a plugin function and return the result. ComID contains the ID number of the function. ComStr contains the entire parameter list in case you need to parse it yourself. NumParam is the number of parameters passed in the P array} {Set L to the length of the result that you return} {DisposeStr will be called to allow you to dispose of the result you return} {H is the handle of the MUD window making the call} begin Result := nil; end; procedure AddMenu( MenuIndex: Integer; Caption, HelpStr: PChar; var ComID: Integer; M: HMENU); stdcall; {OPTIONAL} {used to add menu items to the Tools menu for your Plugin. All your menu items are on the submenu for your plugin in the zMUD Tools menu. This routine is called multiple times, with MenuIndex starting at one and then incrementing. Each time, you should return the Caption of a menu item and the corresponding command ID you want to execute when the user selects the menu item. If you are done adding menu items, return a blank Caption name} {M is the Handle to the MenuItem being created} {You can also return ComID of -1 with blank Caption to prevent any menu from being added for this plugin.} begin StrCopy( Caption, PChar('')); end; procedure MenuCommand( H: THandle; ComID: Integer); stdcall; {OPTIONAL} {executes a menu command previously defined with the AddMenu call. Note that menu command IDs are seperate than Command and Function IDs} {H is the handle of the MUD window making the call, or zero if no mud window is open} begin end; const idPluginFunction = 1; idUserInput = 2; idSaveSettings = 3; idParseMUDLine = 4; idMUDInput = 5; procedure DisposeStr( H: THandle; id: Word; P: PChar; L: Integer); stdcall; {SEMI-OPTIONAL} {Called whenever you send a PChar result back to PluginFunction, UserInput, SaveSettings, ParseMUDLine, or MUDInput. id indicated the procedure that allocated the memory} {The PChar that you returned to these functions is given in P so that you can dispose of the memory used by the string as needed. L is the size of the data to be disposed.} {H is the handle of the MUD window making the call} begin end; function UserInput( H: THandle; P: PChar; var L: Integer; var SendToMUD: Boolean): PChar; stdcall; {OPTIONAL} {called when the user sends output to the MUD. The line to be sent to the MUD is passed in P. L is the length of the line. Set SendToMUD to false to prevent the command from being sent. To modify the command, return a PChar with the new command and set L to the length of the new command. zMUD will call DisposeStr to allow you to dispose the PChar if you need to} {H is the handle of the MUD window making the call} begin SendToMUD := true; Result := nil; end; function ParseMUDLine( H: THandle; P: PChar; var L: Integer; IsPrompt: Boolean; var DoGag: Integer; var DoUpdate: Boolean); stdcall; {OPTIONAL} {Called when a line of text is received from the MUD. You get this line BEFORE triggers have been processed. You can return different text as the result of this function (and set L to its length) and the triggers will process your modified text. However, if you want the updated text also changed on the screen, you need to set the DoUpdate flag to true. To delete the line from the screen and prevent the zMUD triggers from seeing it, set the DoGag parameter to 1. If you want to prevent the line from being gagged by anyone else, including zMUD, set the DoGag paremeter to -1. The IsPrompt variable indicates whether this is a full line (false) or whether it is a partial line without a newline that might be a MUD prompt (true). Note that it might not actually be a MUD prompt, but could just be the end of a network data buffer. L is the length of the line} {If you return new text to be processed, DisposeStr will be called to dispose of the string when it it no longer needed by zMUD} {H is the handle of the MUD window making the call} begin Result := nil; end; procedure CaptureOutput( H: THandle; AsciiText, RawText: PChar); stdcall; {OPTIONAL} {This routine is called whenever a line of text has been displayed on the screen. It is called AFTER triggers have been processed and reflects the actual output on the screen (which may have been modified with #SUB or #CW triggers). The text cannot be changed here (use ParseMUDLine to change it). This routine is used to snoop the actual text displayed on the user's screen} {The AsciiText variable contains only the ascii text of the line, with any control codes stripped out. The RawText includes any ANSI color codes used in the line. Not that zMUD regenerates the ANSI color codes so this text may not exactly match the raw input received from the MUD (use MUDInput for that)} {H is the handle of the MUD window making the call} begin end; function MUDInput( H: THandle; P: PChar; var L: Integer): PChar; stdcall; {OPTIONAL} {VERY LOW LEVEL! This routine is called whenever a buffer of data is received from the MUD server. You can change the text by returning a new text buffer and setting L to its length. zMUD will discard the original text and use your returned text as if it was received from the MUD instead. DisposeStr will be called to allow you to dispose of your string buffer if necessary} {H is the handle of the MUD window making the call} begin end; procedure UpdatePlugin( H: THandle); stdcall; {OPTIONAL} {this procedure is called whenever a change is made to a zMUD variable in case the plugin needs to be updated or recomputed when this occurs} {H is the handle of the MUD window making the call} begin end; procedure LoadSettings( P: PChar; L: Integer); stdcall; {OPTIONAL} {settings for the plugin have been loaded from the user's .MUD settings file and placed into the P buffer. L is the length of data in the buffer} begin end; function SaveSettings( var L: Integer): PChar; stdcall; {OPTIONAL} {in order to store settings for the plugin into the user's .MUD settings file, place the data into a PChar buffer and return it. L is the length of data stored in the buffer} {DisposeStr is called to dispose of the result} begin Result := nil; end; const zMUDSTAT_ACTIVATE = 1; {zMUD application is now the active app on the system} zMUDSTAT_DEACTIVATE = 2; {zMUD application no longer the active app} procedure zMUDStatus( Stat: Integer); stdcall; {OPTIONAL} {called when the zMUD application status changes values. Possible values are shown above} begin end; procedure OpenThread( H: THandle; Name, Host: PChar; Port: Word); stdcall; {OPTIONAL} {Called when a MUD character using this plugin is first opened in zMUD. Name is the name of the MUD character and H is the handle of the MUD character window, Host is the MUD Hostname, and Port is the port number being connected to} begin end; procedure CloseThread( H: THandle); stdcall; {OPTIONAL} {Called when a MUD character window is closed. H is the handle of the window} begin end; procedure OnConnect( H: THandle); stdcall; {OPTIONAL} {Called when the MUD socket connection of a character window is connected to the MUD. You can use SendStr at this point to send data to the MUD} begin end; procedure OnDisconnect( H: THandle); stdcall; {OPTIONAL} {Called when the socket to the MUD window is closed by the MUD server} begin end; {EXPORTS LINE IS REQUIRED} {be sure and only list the routines that you have actually implemented} exports RegisterPlugin, InitPlugin, ClosePlugin, AddCommands, PluginCommand, PluginFunction, AddMenu, MenuCommand, UserInput, ParseMUDLine, MUDInput, UpdatePlugin, LoadSettings, SaveSettings, PluginAPIVersion, CaptureOutput, zMUDStatus, OpenThread, CloseThread, OnConnect, OnDisConnect; begin end.