RealPlugin basics
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
- [Example] version [0.01] (Author name) 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.
Comments