PluginDependencies

Introduction

Plugins can depend on other plugins. These other plugins can be required dependencies or they can be optional. Required means just what you think it would; You cannot run this Purugin unless the other Purugin/Plugin exists and has been loaded. An optional plugin may or may not be neccesary for your plugin to work.

A common example of optional is the use of an Economy plugin. If no ecomony plugin exists then you don't care about limiting access to the features using money. The only difficulty in writing plugins which use optional plugins is you must conditionally check to see if the optional plugin has loaded or not and then act accordingly.

Syntax

The syntax for declaring your use of other plugins is done at the top of your Purugin:

    class MyPlugin
      include Purugin::Plugin
      description 'MyPlugin', 0.3
      required :Vault
      #...
    end

This example says you require the Vault plugin to be present by the time you enter on_enable (see LifeCycle for more info on on_enable). If we instead wanted vault to be optional then:

    class MyPlugin
      include Purugin::Plugin
      description 'MyPlugin', 0.3
      optional :Vault
      #...
    end

Simple right? So at this point you are probably wondering how you can use the other plugin now.

Accessing

Once you have a plugin declared you can reference the plugin in two ways:

   def on_enable
     Vault().some_vault_method
     #...
   end

optional and required will define a method with the same name as the plugin (if possible). If there is a name conflict or you find this mechanism distasteful you can also use:

   def on_enable
     plugin_manager['Vault'].some_vault_method
     #...
   end

Bukkit Services

Bukkit (layer underneath Purugin) provides a way of advertising services and an API for providing implementations for those services. We will use Vault as a real world example. Vault provides a common set of services for Economy, Chat, and Permissions. The rational for providing services is that many many implementations of these three types of services exist, but they all have slightly different APIs. By creating Vault, then all these various implementations can provide an implementation for the Vault service. Then server maintainers can pick the individual implementation they like best, but still write all their plugins based on the common Vault API.

Purugin provides a mechanism via either optional or required for hooking up to individual services:

    class MyPlugin
      include Purugin::Plugin
      description 'MyPlugin', 0.3
      required :Vault, :services => {:economy => "net.milkbowl.vault.economy.Economy"}
      #...
    end

In this example, we say we that we require the Vault plugin and that we want an implementation of the "net.milkbowl.vault.economy.Economy" provided for us under the method name economy. At this point from on_enable on we can:

   def on_enable
     event(:on_login) do |me|
       if economy.has_account? me.name
          me.msg "Wow! I have #{economy.balance} moneyz"
       end
     end
   end

Note: To try this example out you will have needed to download Vault and an economy-implementing plugin like iConomy.

Purugin module inclusion

A Purugin-only feature is the ability to include other Purugins modules into your Purugin. Here is a simple highly contrived example. First let's define a simple Purugin which provides a module:

   class MyPlugin1
     include Purugin::Plugin, Purugin::Colors
     description 'MyPlugin1', 0.3

     module Shouter
       def shout(message)
         message.upcase
       end
     end

     module Rage
       def rage(message)
         red(message)
       end
     end
   end

This purugin has two modules defined. The example has two to point out you can include one or more plugins to be included:

   class MyPlugin2
     include Purugin::Plugin
     description 'MyPlugin2', 0.3
     required :MyPlugin1, :include => [Shouter, Rage]

     def on_enable
       event(:on_login) do |me|
         me.msg rage(shout("I am Sparta!!!!"))
       end
     end  
   end

If you only use a single module in the include statement you do not need to wrap the include into a list:

        required :MyPlugin1, :include => Shouter