RealPlugin Basics

Base plugin code

Create your plugin as any Bukkit plugin. The only difference is : extend your plugin class from RealPlugin instead of JavaPlugin.

Example : file fr/crafter/tickleman/example/ExamplePlugin.java :

package fr.crafter.tickleman.example;

import fr.crafter.tickleman.realplugin.RealPlugin;

public class ExamplePlugin extends RealPlugin
{
 
}

File plugin.yml :

name: Example
version: 0.01

author: Author name
website: http://plugins.crafter.fr/tickleman/Example/

main: fr.crafter.tickleman.example.ExamplePlugin
depend: [RealPlugin]

What this base plugin does

• Creates the plugins/PluginName folder (ie plugins/Example).
• Creates the plugins/PluginName/config.txt base configuration file, containing :
  • debug=false : debug mode. When set to true, more debugging informations can be send to the server.log file
  • language=en : language. The used language file will be plugins/PluginName/en.lang.txt.
  • permissionPlugin=none : permission plugin used : when none, default op / user rules will be used. Can be either bukkit for bukkit permissions plugin or permissions if you use the old Permissions 2.x/3.x plugin.
  • pluginLog=false : when set to true, a plugins/PluginName/pluginname.log file containing all logs of the plugin will be created. The logs information is always written into the server.log file. Only the debug informations will be written into the plugin log file only when this is true, or into the server.log if false, but never on both.
• when the plugin is loaded by bukkit, a loaded log goes into console output and server.log, looking like this for this example :
  
  • [Example] version [0.01] (Author name) loaded
    On unload (plugin disabled) :
    
  • [Example] version [0.01] (Author name) un-loaded

Configuration file

Create your own PluginNameConfig class :

package fr.crafter.tickleman.example;

import fr.crafter.tickleman.realplugin.RealConfig;

public class ExampleConfig extends RealConfig
{

	public boolean mayDisplaySomething = true;
	public double  numberToBeDisplayed = 500.0;
	public String stringToBeDisplayed = "test string";

	public ExampleConfig(final ExamplePlugin plugin)
	{
		super(plugin);
	}

	@Override
	protected ExamplePlugin getPlugin()
	{
		return (ExamplePlugin)super.getPlugin();
	}

}

You will only have to add properties to your config class to get new configurations properties.

Add this to your plugin class code (ie ExamplePlugin.java) :

	@Override
	public ExampleConfig getRealConfig()
	{
		return (ExampleConfig)super.getRealConfig();
	}

	@Override
	protected void loadConfig()
	{
		config = new ExampleConfig(this).load();
	}

Example of use of configuration options :

	@Override
	public void onEnable()
	{
		super.onEnable();
		if (getRealConfig().mayDisplaySomething) {
			getLog().info("Configuration value of " + getRealConfig().stringToBeDisplayed);
		}
	}

This will display on console output :

Configuration value of test string

Log generator basics

You can call the plugin class getLog() method to get the log generator instance.

This generate différent logs levels :

• getLog().debug("debug text") : debug text will be output only if debug mode is true into config.txt
• getLog().info("information text") : display [INFO] text : tell information to the server admin
• getLog().warning("warning text") : display [WARNING] text : for warnings you want to send to the server admin
• getLog().error("error text") : display [ERROR] text : for errors that will not crash the plugin / bukkit
• getLog().severe("severe text") : display [SEVERE] text : for severe errors that could really crash everything

Logs errors text will always be output like this into the server.log or plugin log file :

[INFOS] [DEBUG] [PluginName] debug text
[INFOS] [PluginName] information text
[AVERTISSEMENT] [PluginName] warning text
[INFOS] [ERROR] [PluginName] error text
[SEVERE] [ERROR] [PluginName] severe text

Using language files

Want to translate your plugin's text in French ? Change your config.txt language to fr and create this file into your sources folder : default/fr.lang.txt with following content (notice : this file will be automatically copied into plugins/Exemple/fr.lang.txt as the server admin will like to modify its content at wish) :

Simple text example=Texte d'exemple simple
This example text show you +variable=Ce texte d'exemple affiche +variable
An example of +what with +count variables=Un +what d'exemple avec +count variables
example variable=variable exemple

In your plugin code, translate all your texts like this :

	@Override
	public void onEnable()
	{
		super.onEnable();
		String variable = "example variable";
		getLog().info(tr("Simple text example"));
		getLog().info(
			tr("This example text show you +variable")
			.replace("+variable", tr(variable))
		);
		getLog().info(
			tr("An example of +what with +count variables")
			.replace("+count", "2")
			.replace("+what", tr(variable))
		);
	}

If your config.txt language setting is en, this will display when your plugin enables :

Simple text example
This example text show you example variable
An example of example variable with 2 variables

If you choose fr :

Texte d'exemple simple
Ce texte d'exemple affiche variable exemple
Un variable exemple d'exemple avec 2 variables

Permissions basics

The built-in permissions Gate can use bukkit permissions plugin, or the deprecated Permissions v2 / v3 system. If server admins don't want any of them, they can choose default op / user assigned permissions for the plugin for the simpliest use.

Into your plugin, check permissions like this :

		if (plugin.hasPermission(player, "pluginname.subperm") { }

Server admins can configure their config.txt like this :

• permissionsPlugin=none : default permissions for op / user will be used
• permissionsPlugin=bukkit : any available bukkit permissions plugin will be used
• permissionsPlugin=permissions : old Permissions 2.x/3.x plugin will be used

Think about overriding the opHasPermission() and playerHasPermission() methods like this, into your plugin class, to give default permissions to users when the server admin choose permissionsPlugin as none (default if you don't override is : ops has all permissions on your plugin, and players have no permission at all). Example :

	public boolean opHasPermission(String permissionString)
	{
		// op will have all permission but "example.protected"
		return !permissionString.equals("example.protected");
	}

	public boolean playerHasPermission(String permissionString)
	{
		// players will have access to this list of permissions
		String[] playerPermissions = {"example.display", "example.otherperm", "example.subperm.what"};
		for (String playerPermission : playerPermissions) if (playerPermission.equals(permissionString)) return true;
		return false;
	}

Other API objects and advanced use

The RealPlugin project is released on GitHub. The simplest way to know what else you can do is to have a look to classes and methods names in its source.

https://github.com/tickleman/RealPlugin