Announcement Create a Plugin

We've posted an important announcement regarding the current situation and the future of the game: Announcement

  • Create a Plugin

    Base class: Plugin

    All plugins you are going to create for Rising World have one thing in common: They contain a class which extends the base Plugin class. Usually this is the first step in order to create a plugin.

    When extending the Plugin class, you have to override the onEnable() and onDisable() methods. These methods will be called once the plugin has been enabled or disabled. It doesn't matter what code you put into these methods, depending on the structure of your plugin, you can initialize some variables there. It also makes sense to register all events in the onEnable() method (note: it is not necessary to unregister any events in the onDisable(), in general you don't have to care about any kind of "clean up").



    Register events

    If you want to listen to an event, you have to register it. It's recommendable to register all events you are going to need in the onEnable() method. The Plugin class has a registerEventListener(Listener) method, which expects a Listener. Every event listener has to implement this interface. It is up to you if you want to create separate event listener classes, or simply implement the Listener interface in your main plugin class.

    The particular event methods in your listener are determined by its parameter. It is important that your event methods only have a single parameter, and this parameter must be any event object. The name of your method does not matter. Your event methods also need an "@EventMethod" annotation. Like any other annotations you have to put it above your method.

    Example:

    Java Source Code

    1. import net.risingworld.api.Plugin;
    2. import net.risingworld.api.events.EventMethod;
    3. import net.risingworld.api.events.Listener;
    4. import net.risingworld.api.events.player.PlayerCommandEvent;
    5. public class MyPlugin extends Plugin implements Listener{
    6. @Override
    7. public void onEnable(){
    8. //Register event listener
    9. registerEventListener(this);
    10. }
    11. @Override
    12. public void onDisable(){
    13. //...
    14. }
    15. @EventMethod
    16. public void onPlayerCommand(PlayerCommandEvent event){
    17. //this method will be called when the "PlayerCommandEvent"
    18. //triggers, i.e. when a player enters a command into chat.
    19. }
    20. }
    Display All



    The "@EventMethod" annotation can take a threading parameter, which determines how the event method will be called:

    Threading.AsyncEvent methods will be called "directly", i.e. a server thread simply calls the event method without doing any synchronization.
    This is the fastest way to trigger events, but it is not thread-safe (default mode).
    Threading.SyncEvent methods will be called from the same server thread, but they will be synchronized. This way you can access shared variables


    from different events (all these events have to use the Sync threading model).
    Threading.ThreadedA new thread will be created to call the event. This only makes sense when you want to do some heavy computations or


    any time consuming tasks in your event methods. When using this mode, you can no longer cancel the event.



    Let the party begin

    You are able to listen for events now, but the real action takes place when accessing the various server, world or player functions. To do this, you need to get a reference to the server or world objects. The Plugin class offers getServer() and getWorld() methods (and a few more methods, check out the javadoc to get an overview).
    Here is an simple example which outputs the server name, seed and worldname once the server is started:

    Java Source Code

    1. import net.risingworld.api.Plugin;
    2. import net.risingworld.api.Server;
    3. import net.risingworld.api.World;
    4. public class MyPlugin extends Plugin{
    5. @Override
    6. public void onEnable(){
    7. //Get server and world objects
    8. Server server = getServer();
    9. World world = getWorld();
    10. //Show server name
    11. System.out.println("Server name: " + server.getName());
    12. //Show world name and seed
    13. System.out.println("World name: " + world.getName() + " seed: " + world.getSeed());
    14. }
    15. @Override
    16. public void onDisable(){
    17. //...
    18. }
    19. }
    Display All
    Here is a more complex Plugin-class which listens for the PlayerCommandEvent (when a player enters a command) as well as the PlayerChatEvent (when a player writes a chat message):

    Java Source Code

    1. import net.risingworld.api.Plugin;
    2. import net.risingworld.api.events.EventMethod;
    3. import net.risingworld.api.events.Listener;
    4. import net.risingworld.api.events.player.PlayerChatEvent;
    5. import net.risingworld.api.events.player.PlayerCommandEvent;
    6. import net.risingworld.api.objects.Player;
    7. public class MyPlugin extends Plugin implements Listener{
    8. @Override
    9. public void onEnable(){
    10. //Register event listener
    11. registerEventListener(this);
    12. }
    13. @Override
    14. public void onDisable(){
    15. //...
    16. }
    17. @EventMethod
    18. public void onCommand(PlayerCommandEvent event){
    19. Player player = event.getPlayer();
    20. String command = event.getCommand();
    21. //split the command
    22. String[] cmd = command.split(" ");
    23. //check the command, example: teleport command
    24. if(cmd[0].equals("/teleport")){
    25. //check if player provided coordinates
    26. if(cmd.length == 4){
    27. float x = Float.parseFloat(cmd[1]);
    28. float y = Float.parseFloat(cmd[2]);
    29. float z = Float.parseFloat(cmd[3]);
    30. //teleport player
    31. player.setPosition(x, y, z);
    32. //send message to player
    33. player.sendTextMessage("[FFFF00]Teleported to " + x + ", " + y + ", " + z);
    34. }
    35. else{
    36. //inform player that he has to enter coordinates
    37. player.sendTextMessage("[#FF0000]You have to provide coordinates!");
    38. player.sendTextMessage("[#FF0000]USAGE: /tp x y z");
    39. }
    40. }
    41. //Exampe: send admin message command
    42. else if(cmd[0].equals("/adminmessage")){
    43. if(cmd.length > 1){
    44. //get the rest of the message
    45. String message = command.substring(14); //remove the first 14 characters
    46. //send to all admins, check all players if they are admins
    47. for(Player p : getServer().getAllPlayers()){
    48. if(p.isAdmin()){
    49. p.sendTextMessage("[#FF0000]" + player.getName() + ": " + message);
    50. }
    51. }
    52. }
    53. else{
    54. //inform player that he has to provide a message
    55. player.sendTextMessage("[#FF0000]You have to provide a message");
    56. player.sendTextMessage("[#FF0000]USAGE /adminmessage message");
    57. }
    58. }
    59. }
    60. @EventMethod
    61. public void onChat(PlayerChatEvent event){
    62. Player player = event.getPlayer();
    63. String message = event.getChatMessage();
    64. //cancel the event, so the chat message does not show up
    65. event.setCancelled(true);
    66. //send your own custom chat message
    67. getServer().broadcastTextMessage("[#4110DD]" + player.getName() + " said: [#FFFFFF]" + message);
    68. }
    69. }
    Display All

    Final steps

    Every plugin needs a definition file. It has to be called "plugin.yml" and belongs into a "resources" folder in your source directory (once you build your plugin, the resource folder will be added to the resulting jar automatically.




    Here is an example "plugin.yml" definitions file:

    Source Code

    1. name: MyPlugin
    2. main: net.mypackage.myplugin.MyPlugin
    3. version: 1.0.0
    4. author: <your name>
    5. team: <your team, optional>
    6. description: "Put your description here"
    7. license: MIT
    8. website: http://www.myhomepage.com
    The most important values are basically the name (the name of your plugin), the main (the path to your main class, including the full package name), the version (it's up to you to choose a version number) and the author (your name or your nickname). All other values are optional.

    To release your plugin, you have to compile it (in Netbeans, for example, you can rightclick on your project and select "Clean and Build" to compile your plugin). The resulting jar file is basically your plugin (you can rename it if you want). Just put the jar file into a separate folder (e.g. you can call your jar file "MyPlugin.jar", and the folder "MyPlugin" accordingly), and move this folder into the "plugins" subfolder in your game or server directory (if there is no such folder yet, just create it). Now start your server or the game, and your plugin should be loaded.

    The post was edited 3 times, last by red51 ().