Class Plugin

java.lang.Object
net.risingworld.api.Plugin
public abstract class Plugin extends Object
Base class of all plugins. Extend this class to create your own plugin.
Example: Very basic example plugin
1//Create a class extending the plugin class and implementing the Listener interface
2//(to listen to events)
3public class MyPlugin extends Plugin implements Listener {
4
5 @Override
6 public void onEnable() {
7 //This method is called when the plugin is initially loaded.
8
9 //We want our plugin to listen to events (it implements the "Listener" interface),
10 //so we register it as event listener
11 registerEventListener(this);
12 }
13
14 @Override
15 public void onDisable() {
16 //This is called when the plugin is unloaded/disabled
17 }
18
19 //To listen to events, you have to add "EventMethods" to this class.
20 //Every event method requires an "@EventMethod" annotation.
21 //Example: PlayerChatEvent (invoked when the player sends a text message in chat)
22
23 @EventMethod
24 public void onChatEvent(PlayerChatEvent event) {
25 //Cancel the event, so it will not show up in chat anymore (because we
26 //want to send a custom message instead)
27 event.setCancelled(true);
28
29 //Send a modified message to chat
30 Server.broadcastTextMessage("Player " + event.getPlayerChatName() + " send a text message: " + event.getChatMessage());
31 }
32}

  • Constructor Details

    • Plugin

      protected Plugin()

  • Method Details

    • onLoad

      public void onLoad()
      This method is called when the plugin will be loaded (before onEnable() is called). Other plugins may not be loaded at this stage. 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:
      1public 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 String getName()
      Gets the name of this plugin.
      Returns:
      the plugin name.

    • getDescription

      public String getDescription(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.

    • getLoadOrder

      public int getLoadOrder()
      Gets the load order for this plugin. The lower the value, the earlier the plugin gets loaded (when the API gets initialized). Default value is 0.
      Returns:
      the load order for this plugin.

    • getPath

      public String getPath()
      Gets the path to the plugin folder (for example: "C:/Server/plugins/MyPlugin"), without a slash at the end.
      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
      2File config = new File(getPath() + "/config.txt");
      3
      4//check if file exists
      5if(config.exists()){
      6 //read content from file
      7 String content = Utils.FileUtils.readStringFromFile(file);
      8}

    • getGameVersion

      public final 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)
      Finds a plugin by id. Please bear in mind that plugin ids are not persistent and they're only valid during the session!
      Parameters:
      pluginID - the id of the plugin you're looking for.
      Returns:
      the plugin instance, or null if no plugin with this id was found.

    • getPluginByName

      public final Plugin getPluginByName(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"
      1Plugin otherPlugin = getPluginByName("PluginB");
      2
      3//check if plugin really exists
      4if(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 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(WorldDatabase.Target db)
      Gets an interface providing access to the world database.
      Parameters:
      db - the world database type / target (i.e which world database you want to access).
      Returns:
      an interface which provides access to the desired world database.

    • getSQLiteConnection

      public final Database getSQLiteConnection(String database)
      Creates a new SQLite database connection (in thread-safe mode). If the provided database file does not exists, it will be created. Instead of providing a file path, you can also create a memory database (by providing null as parameter).

      Note: Calling this method always creates a new connection. It's recommendable to create a connection to a database only once and reuse that database object. If you no longer need the connection, call Database.close() to free the resources.
      Parameters:
      database - the path to the database (to get the relative plugin path, call getPath()). Set to null if you want to create a temporary memory database (which only exists while the game is running).
      Returns:
      a Database object which represents this database connection, or null if an error occurred.
      Example: 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()"
      3Database database = getSQLiteConnection(getPath() + "/" + "MyDatabase.db");
      4
      5//Execute CREATE sql statement
      6database.execute("CREATE TABLE IF NOT EXISTS `Players` (`ID` INTEGER PRIMARY KEY NOT NULL, `Name` VARCHAR(64), `Level` INTEGER)");
      7
      8//Close database connection only if it's no longer needed
      9database.close();

      Example: 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()"
      3Database database = getSQLiteConnection(getPath() + "/config/MyDatabase.db");
      4
      5//Do something
      6//...
      7
      8//Close connection once it's no longer needed
      9database.close();

      Example: Create temporary memory database
      1//Create connection with null parameter (memory db)
      2Database database = getSQLiteConnection(null);
      3
      4//Do something
      5//...
      6
      7//Close connection once it's no longer needed
      8database.close();

    • getMySQLConnection

      public final Database getMySQLConnection(String database, String ip, int port, String username, String password)
      Creates a new MySQL database connection.

      Note: Calling this method always creates a new connection. It's recommendable to create a connection to a database only once and reuse that database object. If you no longer need the connection, call Database.close() to free the resources.
      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 occurred (access denied, wrong ip etc.)
      Example: Create connection to "rwdb" database on local server
      1Database database = getMySQLConnection("rwdb", "127.0.0.1", 3306, "root", "1234");
      2if(database != null){
      3 //Connection was successful
      4}

    • sendHttpRequest

      public final String sendHttpRequest(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 String sendHttpRequest(String url, HashMap<String,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: An example class for an event listener
      1public class MyListener implements Listener{
      2
      3 //Reference to our plugin main class in order to access it from this listener
      4 private Plugin plugin;
      5
      6 //Constructor, in this case we pass a reference to our plugin main class
      7 public MyListener(Plugin plugin){
      8 this.plugin = plugin;
      9 }
      10
      11 @EventMethod
      12 public void onPlayerHit(PlayerHitEvent event){
      13 //this method will be called when a PlayerHitEvent is triggered
      14 }
      15
      16 @EventMethod
      17 public void onPlayerCommand(PlayerCommandEvent event){
      18 //this method will be called when a PlayerCommandEvent is triggered
      19 }
      20}

      Example: 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"
      5MyListener listener = new MyListener();
      6registerEventListener(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: Create a custom event and an according listener
      1//Custom event class
      2public 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
      15public class MyCustomEventListener implements Listener{
      16 @EventMethod
      17 public void customMethod(CustomEvent event){
      18 System.out.println(event.getMessage());
      19 }
      20}

      Example: Trigger the "CustomEvent"
      1CustomEvent evt = new CustomEvent("Hello World!");
      2triggerEvent(evt);

    • registerWebserverHandler

      public final void registerWebserverHandler(String path)
      Registers a webserver route handler for this plugin. Once registered, incoming HTTP requests targeting this route will trigger an HttpRequestEvent.

      The provided path is relative to the plugin (it must not be null). The resulting route is always located under the reserved prefix /plugins/<pluginname>/, for example registering the path "status" for a plugin called "MyPlugin" results in the route /plugins/myplugin/status. This prevents collisions with built-in webserver routes and with other plugins.

      Note: The Webserver is only active for the dedicated server! Calling this method in singleplayer or co-op (LAN, P2P) has no effect!
      Parameters:
      path - the route path (relative to the plugin), e.g. "status".
      Example: Register a webserver route and respond with JSON
      1//OnEnable():
      2registerWebserverHandler("status");
      3registerEventListener(this);
      4
      5//Event method (in a Listener):
      6@EventMethod
      7public void onHttpRequest(HttpRequestEvent event) {
      8 if(event.getPath().endsWith("/status")) {
      9 event.setContentType("application/json");
      10 event.setResponseBody("{\"online\": true}");
      11 }
      12}

    • registerWebserverHandler

      public final void registerWebserverHandler(String path, WebserverHandler handler)
      Registers a webserver route handler for this plugin, providing a callback which is invoked directly whenever a matching HTTP request is received (similar to registerWebserverHandler(String), but without the need to register a separate event listener and filter the request path manually).

      The provided path is relative to the plugin and follows the same rules as registerWebserverHandler(String) (resulting route under /plugins/<pluginname>/). The given WebserverHandler will only be called for requests targeting this particular route.

      Note: The handler is invoked on a webserver worker thread, NOT on the main thread. Use enqueue(Runnable) to safely access game state. The Webserver is also only active for the dedicated server!
      Parameters:
      path - the route path (relative to the plugin), e.g. "status".
      handler - the handler to call for incoming requests.
      Example: Register a webserver route with a callback, responding with JSON
      1//OnEnable():
      2registerWebserverHandler("status", event -> {
      3 event.setContentType("application/json");
      4 event.setResponseBody("{\"online\": true}");
      5});

    • unregisterWebserverHandler

      public final void unregisterWebserverHandler(String path)
      Unregisters a previously registered webserver route handler (see registerWebserverHandler(String) and registerWebserverHandler(String, WebserverHandler)).
      Parameters:
      path - the route path which was used to register the handler.

    • enqueue

      public final void enqueue(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: Enqueue a runnable, using lambda expression
      1enqueue(() -> {
      2 //do something
      3});

    • executeDelayed

      public final void executeDelayed(float delay, 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
      2executeDelayed(5.0f, () -> {
      3 //do something
      4});

    • isMainThread

      public final boolean isMainThread()
      Checks whether or not the currently executing thread is the main thread.
      Returns:
      true if this method was called from the main thread, false if not.

    • getRunningTime

      public final float getRunningTime()
      Gets the total running time of the game/server in seconds. Same as Server.getRunningTime().
      Returns:
      the total running time in seconds.