Plugin (Rising World Plugin API)

java.lang.Object
- net.risingworld.api.Plugin

```
public abstract class Plugin
extends java.lang.Object
```
Plugin is the base class for all plugins. Extend this class to create your own plugin.

Constructor Summary

Constructors
Constructor and Description

Plugin()

Constructors
Constructor and Description
`Plugin()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`enqueue(java.lang.Runnable runnable)` "Enqueues" a task (Runnable).
`void`	`executeDelayed(float delay, java.lang.Runnable runnable)` Executes a task after a given delay.
`java.util.Collection<Plugin>`	`getAllPlugins()` Returns a collection of all plugins which are currently loaded.
`java.lang.String`	`getDescription(java.lang.String name)` Gets the description for this plugin (which is defined in the plugin.yml file).
`java.lang.String`	`getGameVersion()` Gets the current version of the game/server.
`int`	`getID()` Gets the internal id of this plugin.
`Internals`	`getInternals()`
`Database`	`getMySQLConnection(java.lang.String database, java.lang.String ip, int port, java.lang.String username, java.lang.String password)` Gets a new MySQL database connection.
`java.lang.String`	`getName()`
`java.lang.String`	`getPath()` Gets the path to the plugin folder (for example: "C:/Server/plugins/MyPlugin").
`Plugin`	`getPluginByID(int pluginID)`
`Plugin`	`getPluginByName(java.lang.String pluginName)` Finds a plugin with the according name and returns the instance.
`Server`	`getServer()` Gets the server object.
`Database`	`getSQLiteConnection(java.lang.String database)` Gets a new SQLite database connection.
`World`	`getWorld()` Gets the world object.
`WorldDatabase`	`getWorldDatabase()` Gets an interface providing access to the world database.
`abstract void`	`onDisable()` This method is called when the plugin will be disabled and unloaded.
`abstract void`	`onEnable()` This method is called when the plugin will be enabled.
`void`	`onLoad()` This method is called when the plugin will be loaded.
`void`	`registerEventListener(Listener listener)` Registers an event `Listener`.
`java.lang.String`	`sendHttpRequest(java.lang.String url)` Sends a http request to the target url.
`java.lang.String`	`sendHttpRequest(java.lang.String url, java.util.HashMap<java.lang.String,java.lang.String> postData)` Sends a http request with POST data to the target url.
`void`	`triggerEvent(Event event)` Calls an event.
`void`	`unregisterEventListener(Listener listener)` Unregisters an event `Listener`, i.e. this listener will no longer be called when an event triggers.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail
- Plugin
```
public Plugin()
```

Method Detail

onLoad
```
public void onLoad()
```
This method is called when the plugin will be loaded. Override this method if necessary, otherwise just use the onEnable() method for initialization purposes.

onEnable

public abstract void onEnable()

This method is called when the plugin will be enabled. At this point all other plugins are already loaded. You have to override this method when extending this class.

Example:

1	public class MyPlugin extends Plugin{
2
3	`@`Override
4	public void onEnable(){
5	System.out.println("MyPlugin enabled!");
6	}
7
8	`@`Override
9	public void onDisable(){
10	System.out.println("MyPlugin disabled!");
11	}
12
13	}

onDisable
```
public abstract void onDisable()
```
This method is called when the plugin will be disabled and unloaded. You have to override this method when extending this class.

getID
```
public final int getID()
```
Gets the internal id of this plugin. Once the game / server is started, it assigns a unique id to every plugin, but this id is only valid during runtime (i.e. the plugin may get a different id after restart).

Returns:

the internal id of this plugin.

getName
```
public java.lang.String getName()
```

getDescription
```
public java.lang.String getDescription(java.lang.String name)
```
Gets the description for this plugin (which is defined in the plugin.yml file).

Parameters:

name - the actual property you want to get. Valid names: name, version, author, team, description, main, license, website, contact, git

Returns:

the property, or "N/A" when no such property was found.

getPath

public java.lang.String getPath()

Gets the path to the plugin folder (for example: "C:/Server/plugins/MyPlugin").

Returns:

the path to the plugin folder (the subfolder of this particular plugin).

Example: Access text file "config.txt" in plugin folder

1	//create new file object
2	File config = new File(getPath() + "/config.txt");
3
4	//check if file exists
5	if(config.exists()){
6	//read content from file
7	String content = Utils.FileUtils.readStringFromFile(file);
8	}

getServer
```
public Server getServer()
```
Gets the server object.

Returns:

the server object.

getWorld
```
public World getWorld()
```
Gets the world object.

Returns:

the world object.

getGameVersion
```
public final java.lang.String getGameVersion()
```
Gets the current version of the game/server.

Returns:

the current version of the game/server as a String.

getPluginByID

public final Plugin getPluginByID(int pluginID)

getPluginByName

public final Plugin getPluginByName(java.lang.String pluginName)

Finds a plugin with the according name and returns the instance.

Parameters:

pluginName - the name of the plugin you're looking for (which is specified in the plugin.yml file)

Returns:

the plugin instance, or null if no such plugin was found.

Example: Access another plugin called "PluginB"

1	Plugin otherPlugin = getPluginByName("PluginB");
2
3	//check if plugin really exists
4	if(otherPlugin != null){
5	//read file from other plugin folder
6	String path = otherPlugin.getPath() + "/database.db";
7	File file = new File(path);
8	if(file.exists(){
9	//...
10	}
11	}

getAllPlugins
```
public final java.util.Collection<Plugin> getAllPlugins()
```
Returns a collection of all plugins which are currently loaded. This method creates a new collection, so modifying it has no effect on the plugins or the server.

Returns:

a newly created collection containing all currently loaded plugins.

getWorldDatabase
```
public final WorldDatabase getWorldDatabase()
```
Gets an interface providing access to the world database.

Returns:

an interface which provides access to the world database.

getInternals
```
public final Internals getInternals()
```

getSQLiteConnection

public final Database getSQLiteConnection(java.lang.String database)

Gets a new SQLite database connection. If the provided file does not exists, it will be created.

Parameters:

database - the path to the database (to get the relative plugin path, call getPath()).

Returns:

a Database object which represents this database connection, or null if an error occurs.

Example #1: Create connection to "MyDatabase.db" in plugin folder and create new table if not exists

1	//create connection to database "MyDatabase.db" in pluginfolder
2	//to get the plugin folder, call "getPath()"
3	Database database = getSQLiteConnection(getPath() + "/" + "MyDatabase.db");
4
5	//execute CREATE sql statement
6	database.execute("CREATE TABLE IF NOT EXISTS `Players` (`ID` INTEGER PRIMARY KEY NOT NULL, `Name` VARCHAR(64), `Level` INTEGER)");
7	//close database connection only if it's no longer needed
8	database.close();

Example #2: Create connection to "MyDatabase.db" in subfolder "config"

1	//create connection to database in pluginfolder/config
2	//to get the plugin folder, you can call "getPath()"
3	Database database = getSQLiteConnection(getPath() + "/config/MyDatabase.db");
4
5	//do something
6	//...
7
8	//close connection once it's no longer needed
9	database.close();

getMySQLConnection
```
public final Database getMySQLConnection(java.lang.String database,
                                         java.lang.String ip,
                                         int port,
                                         java.lang.String username,
                                         java.lang.String password)
```
Gets a new MySQL database connection.

Parameters:

database - the database name.

ip - the ip of the MySQL server.

port - the port of the MySQL server (by default 3306)

username - the login username, e.g. "root"

password - the login password.

Returns:

a Database object which represents this database connection, or null if an error occurs (access denied, wrong ip etc.)

Example: Create connection to "rwdb" database on local server
1 Database database = getMySQLConnection("rwdb", "127.0.0.1", 3306, "root", "1234");
2 if(database != null){
3 //connect successful
4 }

sendHttpRequest
```
public final java.lang.String sendHttpRequest(java.lang.String url)
```
Sends a http request to the target url. Returns the content as a string.

Parameters:

url - the target url

Returns:

the content of the target page.

sendHttpRequest
```
public final java.lang.String sendHttpRequest(java.lang.String url,
                                              java.util.HashMap<java.lang.String,java.lang.String> postData)
```
Sends a http request with POST data to the target url. Returns the content as a string.

Parameters:

url - the target url

postData - the POST data as a hash map

Returns:

the content of the target page.

registerEventListener

public final void registerEventListener(Listener listener)

Registers an event Listener. The particular methods of this event will be called when an event was triggered (depending on the parameter of the method - an event method is supposed to have a single Event parameter). Also make sure to use the @EventMethod annotation for these methods.

Parameters:

listener - the event listener you want to register.

Example #1: An example class for an event listener

1	public class MyListener implements Listener{
2
3	//Reference to our plugin main class in order to access it from this
4	//listener (e.g. to call functions like "getServer()" or "getWorld()" etc)
5	private Plugin plugin;
6
7	//Constructor, in this case we pass a reference to our plugin main class
8	public MyListener(Plugin plugin){
9	this.plugin = plugin;
10	}
11
12	`@`EventMethod
13	public void onPlayerHit(PlayerHitEvent event){
14	//this method will be called when a PlayerHitEvent is triggered
15	}
16
17	`@`EventMethod
18	public void onPlayerCommand(PlayerCommandEvent event){
19	//this method will be called when a PlayerCommandEvent is triggered
20	}
21	}

Example #2: Register the "MyListener" event listener

1	//Since the "MyListener" class only has the "onPlayerHit()" and
2	//"onPlayerCommand()" methods (note: the name does not matter, only the
3	//parameter type is relevant), it will only listen for the "PlayerHitEvent"
4	//and "PlayerCommandEvent"
5	MyListener listener = new MyListener();
6	registerEventListener(listener);

unregisterEventListener
```
public final void unregisterEventListener(Listener listener)
```
Unregisters an event Listener, i.e. this listener will no longer be called when an event triggers.

Parameters:

listener - the event listener you want to unregister.

triggerEvent

public final void triggerEvent(Event event)

Calls an event. This is useful if you create your own custom events and want to call them through the event pipeline.

Parameters:

event - the event you want to trigger.

Example #1: Create a custom event and an according listener

1	//Custom event class
2	public class CustomEvent extends Event{
3	private String message;
4
5	public CustomEvent(String message){
6	this.message = message;
7	}
8
9	public String getMessage(){
10	return message;
11	}
12	}
13
14	//Event listener which listens for the custom event
15	public class MyCustomEventListener implements Listener{
16	`@`EventMethod(Threading.Threaded)
17	public void customMethod(CustomEvent event){
18	System.out.println(event.getMessage());
19	}
20	}

Example #2: Trigger the "CustomEvent"

1	CustomEvent evt = new CustomEvent("Hello World!");
2	triggerEvent(evt);

enqueue
```
public final void enqueue(java.lang.Runnable runnable)
```
"Enqueues" a task (Runnable). This runnable will be processed the next tick. All runnables that are "enqueued" will always be processed from the same thread, so this might be useful to achieve a thread-safety.

Parameters:

runnable - the Runnable that will be processed in the next tick.

Example #1: Enqueue a runnable, using lambda expression (Java 8 onwards)
1 enqueue(() -> {
2 //do something
3 });
Example #2: Same as example #1, but without lamda expressions, instead passing the anonymous class as parameter (old style)
1 enqueue(new Runnable(){
2 @Override
3 public void run(){
4 //do something
5 }
6 });

executeDelayed
```
public final void executeDelayed(float delay,
                                 java.lang.Runnable runnable)
```
Executes a task after a given delay. Task will be executed from the main server thread (this is always the same thread), similar to enqueue(java.lang.Runnable).

Parameters:

delay - the delay in seconds.

runnable - the task you want to execute delayed.

Example: Execute a task (runnable) after 5 seconds (using lambda expression)
1 //in your plugin class
2 executeDelayed(5.0f, () -> {
3 //do something
4 });

1	Database database = getMySQLConnection("rwdb", "127.0.0.1", 3306, "root", "1234");
2	if(database != null){
3	//connect successful
4	}

1	enqueue(new Runnable(){
2	`@`Override
3	public void run(){
4	//do something
5	}
6	});

1	//in your plugin class
2	executeDelayed(5.0f, () -> {
3	//do something
4	});

Class Plugin

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Plugin

Method Detail

onLoad

onEnable

onDisable

getID

getName

getDescription

getPath

getServer

getWorld

getGameVersion

getPluginByID

getPluginByName

getAllPlugins

getWorldDatabase

getInternals

getSQLiteConnection

getMySQLConnection

sendHttpRequest

sendHttpRequest

registerEventListener

unregisterEventListener

triggerEvent

enqueue

executeDelayed