OpenRPG

What is a Plugin?

A plugin is a bit of software that plugs into the OpenRPG game table and modifies the functionality of the software. Plugins can change the way dice are parsed, improve on already established features, or in reality a whole list of things that I did not mention. In a short summary a plugin Plugs Into the software to add new stuff.

Lesson 1. Hello Plugin World!

In the first lesson of plugin writing we are going to write ourselves a bit of code that prints to chat, "Hello Plugin World!" The finished plugin can be found here: Hello_Plugin_World, and you can use this to guide yourself in the learning process.

In the first part we create some imports. The mandatory import is import orpg.pluginhandler. This import bring the details of the plugin handler so the plugin can be recognized. If you want to create a fancy menu for your plugin add import wx to the top also.

The next part of the code creates the Plugin class so the plugin can further be recognized and carries the correct objects over.

class Plugin(orpg.pluginhandler.PluginHandler):
    def __init__(self, plugindb, parent):
        orpg.pluginhandler.PluginHandler.__init__(self, plugindb, parent)

This also inititates (init) the plugin. This code is mandatory for all plugins. Afterwards we have the help info. Here we name the author, the plugin name, and then we create a small block of text that users will be able to read when they click the Plugin Info button. ` self.name = 'Hello Plugin World'

    self.author = 'Prof Sir Ebral'
    self.help = 'Hello World is a basic Plugin that shows off the ease\n'
    self.help += 'at which plugins can be created.  The source helps \n'
    self.help += 'explain which portions of a plugin are needed for\n'
    self.help += 'developers to learn to write their own.'

Now we can create a menu. To do this we define the plugin menu function and add a menu with wx.Menu. In this lesson we skipped menus so just put pass after the plugin menu function has been created.

    def plugin_menu(self): #Option Function, though it adds a nice GUI menu
        ##You can create a menu here.
        pass #We are passing this step

Whew!! Almost done!! Seriously!! Writing plugins for OpenRPG is not really that heard. It all depends on what you want your plugin to do. In fact, with this plugin we create a model plugin, but we also create a small bug. Thankfully, OpenRPG's code is so sound that we can fix that bug in the next lesson. Well, on with the lesson.

After we have created the menu we have three more functions we will create. plugin_enabled, plugin_disabled, and then the function that of the plugin. The plugin_enabled and plugin_disabled functions occur when the plugin is turned on or off at the control panel. In this plugin we will make a small command, and I want you to look at the command.

    def plugin_enabled(self): #Required Function
        ##You can create text commands here that will enable when the plugin is enabled. 
        ##Other features that are needed when the plugin enables can also be created here.
        self.plugin_addcommand('/helloworld', self.on_hello, '- Tell the world Hello Plugin World!')
        pass

    def plugin_disabled(self): #Required Function
        ##You will need to disable text commands here.
        self.plugin_removecmd('/helloworld')
        pass

Here we say, when the plugin starts, create this command and when the plugin stops, destory this command. But look at the command. 'self.plugin_addcommand('/helloworld', self.on_hello, '- Tell the world Hello Plugin World!')' See, self.on_hello ? That is actually our last function.

    def on_hello(self, cmdargs):
        ##We call cmdargs with text commands.  This allows us to add arguments to the command.
        ##cmdargs and how they are used will be covered later.
        self.chat.Post('Hello Plugin World!', True, True)

And all that does is print to chat "Hello Plugin World!"

I bet you did not notice this right away, but if you put a die roll in there, such as [2d6], the code does not pass through the dice parser. But .. that is the bug we will cover in the next lesson. For now you can add these last three functions and see what is different about that fake roll, and a real roll.

    def pre_parse(self, text):
        print text
        return text

    def plugin_incoming_msg(self, text, type, name, player):
        print text
        return text, type, name

    def post_msg(self, text, myself):
        print text
        return text

Have fun showing off your new plugin, and I hope you enjoyed this simple lesson.