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:

import net.risingworld.api.Plugin;
import net.risingworld.api.events.EventMethod;
import net.risingworld.api.events.Listener;
import net.risingworld.api.events.player.PlayerCommandEvent;

public class MyPlugin extends Plugin implements Listener {

    @Override
    public void onEnable() {
        //Register event listener
        registerEventListener(this);
    }

    @Override
    public void onDisable() {
        //...
    }

    @EventMethod
    public void onPlayerCommand(PlayerCommandEvent event) {
        //this method will be called when the "PlayerCommandEvent" 
        //triggers, i.e. when a player enters a command into chat.
    }

}

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

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. Both Server and World are static class, providing various static methods.
Here is an simple example which outputs the server name, seed and world name once the server is started:

import net.risingworld.api.Plugin;
import net.risingworld.api.Server;
import net.risingworld.api.World;

public class MyPlugin extends Plugin {

    @Override
    public void onEnable() {
        //Show server name
        System.out.println("Server name: " + Server.getName());

        //Show world name and seed
        System.out.println("World name: " + World.getName() + "  seed: " + World.getSeed());
    }

    @Override
    public void onDisable() {
        //...
    }

}

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):

import net.risingworld.api.Plugin;
import net.risingworld.api.events.EventMethod;
import net.risingworld.api.events.Listener;
import net.risingworld.api.events.player.PlayerChatEvent;
import net.risingworld.api.events.player.PlayerCommandEvent;
import net.risingworld.api.objects.Player;

public class MyPlugin extends Plugin implements Listener {

    @Override
    public void onEnable() {
        //Register event listener
        registerEventListener(this);
    }

    @Override
    public void onDisable() {
        //...
    }

    @EventMethod
    public void onCommand(PlayerCommandEvent event) {
        Player player = event.getPlayer();
        String command = event.getCommand();

        //split the command
        String[] cmd = command.split(" ");

        //check the command, example: teleport command
        if (cmd[0].equals("/teleport")) {
            //check if player provided coordinates
            if (cmd.length == 4) {
                float x = Float.parseFloat(cmd[1]);
                float y = Float.parseFloat(cmd[2]);
                float z = Float.parseFloat(cmd[3]);
                //teleport player
                player.setPosition(x, y, z);
                //send message to player
                player.sendTextMessage("[FFFF00]Teleported to " + x + ", " + y + ", " + z);
            }
            else {
                //inform player that he has to enter coordinates
                player.sendTextMessage("[#FF0000]You have to provide coordinates!");
                player.sendTextMessage("[#FF0000]USAGE: /tp x y z");
            }
        }
        //Exampe: send admin message command
        else if (cmd[0].equals("/adminmessage")) {
            if (cmd.length > 1) {
                //get the rest of the message
                String message = command.substring(14);  //remove the first 14 characters

                //send to all admins, check all players if they are admins
                for (Player p : Server.getAllPlayers()) {
                    if (p.isAdmin()) {
                        p.sendTextMessage("[#FF0000]" + player.getName() + ": " + message);
                    }
                }
            }
            else {
                //inform player that he has to provide a message
                player.sendTextMessage("[#FF0000]You have to provide a message");
                player.sendTextMessage("[#FF0000]USAGE /adminmessage message");
            }
        }


    }


    @EventMethod
    public void onChat(PlayerChatEvent event) {
        Player player = event.getPlayer();
        String message = event.getChatMessage();

        //cancel the event, so the chat message does not show up
        event.setCancelled(true);

        //send your own custom chat message
        Server.broadcastTextMessage("[#4110DD]" + player.getName() + " said: [#FFFFFF]" + message);
    }


}

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:

name: MyPlugin
main: net.mypackage.myplugin.MyPlugin
version: 1.0.0
author: <your name>
team: <your team, optional>
description: "Put your description here"
loadorder: 0
license: MIT
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).

One special setting is the loadorder: It can be used to determine the load order for your plugin. By default, the load order is 0. If all plugins have a load order of 0, they will be loaded alphabetically (so a plugin called "Library" will be loaded before a plugin called "Worldplugin"). If a plugin has a negative load order, it will be loaded earlier (so if "Worldplugin" has a load order of -100, and "Library" has a load order of 0, the game will first load the "Worldplugin"). If a plugin has a positive load order, it will be loaded later. This can be useful if your plugin depends on other plugins and you want to make sure the other plugin is loaded first before. If your plugin acts as a library or framework, it's usually recommendable to set a very low negative load order.

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.