• PluginAPI

PluginAPI refrance

To see example of how the API is used please read the Example Plugin page.

The formating and functionality of plugin function has changed dramaticly since 1.6.3 so I am creating this API page to help plugin developers learn how to use the new format to it's fullest potential. The first change is all plugin functions have moved to a class, this helps encapsulate the plugin code and make it slightly more readable. The second major change is the way new slash commands are added for plugins. Other changes include increased functionality and incorperation into the core code.

Plugin Functions

• def init(self, openrpg, plugindb, parent): - This is the internal init function and no code should be added here with the exception of variable declarations.

Required functions

plugin_enabled

This is where you should set set your predefined variables value, add new slash commands, create message handlers, and add any setting you want stored in the settings.xml file.

Adding new slash commands

• There are two ways to acomplish this
  • self.plugin_addcommand(cmd, function, helptext)

    • cmd is the actual slash command. (eg. '/test'

    • function is a function you create to execute when this command is called. (eg. self.on_test)

      • The function is passed a variable called cmdargs so must be defined like def on_test(self, cmdargs):

    • helptext is the string you wish to be shown when someone types the /help command

    • eg. self.plugin_addcommand('/test', self.on_test, '- This is an example plugin command') This creates a new command /test that calls a function on_test that is defined in the Plugin class. and will display the help string - This is an example plugin command' when a users types /help

  • self.plugin_commandalias(alias, cmd)

    • alias is a shorter version of a command (eg. /h insted of /help)

    • cmd is the command that alias is short for

      • eg. self.plugin_commandalias('/example', '/me is giving you an example') this creates a new command /example that when you type it in actualy executes /me is giving you an example. So an alias is a nice way to shorten long or comples commands.

Creating Message Handlers

This is a way you can have plugins talk to eachother over the network. So if two people are running the same plugin, the plugins can talk to eachother. Currently noone has made use of this feature yet, but I am working on a Card dealer plugin that will make use of this.

• self.plugin_add_msg_handler(msgname, recivefunction)

  • msgname is the XML tag name of the message. I recomend using the file name of your plugin (eg. xxblank) If you require multiple message handlers for your plugin you can use (xxblank_typeone, xxblank_typetwo, etc) this will ensure that you do not have cross handling between plugins.

  • recivefunction is the function name you want called whenever you recive a message of type msgname (eg. on_msg_recive)

• eg. self.plugin_add_msg_handler('xxblank', self.on_xml_recive) This creates a message handler of type xxblank and will call the function on_xml_recive when your client recives the proper message type.

• The recive function must be defined like def on_xml_recive(self,id,data,xml_dom):

  • id is the player ID that sent the message

  • data is the actual xml message

  • xml_dom is a dom object of the data

• To send a message to the message handler you make a call to self.plugin_send_msg(id, msg)

  • id is the player ID that you want to send the message to, OR the string all to send to every one in the room

  • msg is the actual XML message you want to send

    • eg. <xxblank_typeone attrib1="somevalue">Some text here</xxblank> or <xxblank_typetwo attrib1="somevalue" />

Adding Settings to the Settings.xml file

This is used for setting that you want the user to beable to change via the settings window, NOT to store data or long strings of stuff.

• self.plugin_add_setting('Setting', 'Value', 'Options', 'Help message')

  • Setting is the name of the setting, this name must not contain spaces

  • Value This is the initial value of your setting

  • Options lets the user know what type of information is expacted for this setting

  • Help message is the text of the help window when the user clicks on your setting name from the Settings window.

• This will add a subtab to the Plugins tab of the Settings window so that your settings will not conflict with other plugins setting
• If the value is already in the settings.xml file it will not overwite the setting so there is no worry about your plugin overwiting setting values that a user has changed if the user disables and reenables the plugin.

plugin_disabled

This is where you remove slash commands, message handlers, and do other clean up calls for you plugin

Removing Slash Commands

• This is a very important thing to do, forgetting to remove the commands when the plugin is disabled can cause OpenRPG to crash if you try to use the command.
• Removing shalsh commands is as simple as calling self.plugin_removecmd(cmd)

  • cmd is the sting you used when adding the slash command in the first place (eg. '/test')

Removing Message Handlers

• This is another very important thing to do, if you forget to do this OpenRPG can crash if you recive a message after you have disabled your plugin
• Removing a message handler is as simple as calling self.plugin_delete_msg_handler(msgname)

  • msgname is the string you used for msgname in your call to plugin_add_msg_handler

Optional Functions

pre_parse

This grabs messages that you are trying to send before they get parsed by OpenRPG's ParsePost function. You should use this function if you wish to do some formating of messages you are about to send before the system gets ahold of them. To see an example of how it can be used look at the Hidden Dice Plugin

send_msg

This grabs a message right before it is sent to the server, but after it has been parsed for dice rolls, and other parse functions, but before it's general format has been changed

plugin_incoming_msg

This grabs all chat messages you recive, here you can change the format of the recived message. To see an example of how this can be used check out the URL to link conversion plugin.

post_msg

This grabs messages right before they are to be displaied to your chat window after they have been though the full processing of the core system. Any changes you make to a message here are only shown to you.

refresh_counter

This is called once every second by the core system and is usefull if you want your plugin to preform operations every x amount of time. To see an example of this check out the Idle Time or the Name Sound plugins

---

CategoryPlugins