The plugin system is a part of the mod system, it allows you to define and override custom behaviours on almost every aspect of the game.

Plugins are bundled in .jar files, either with a mod or stand-alone to be placed in the plugins/ folder of the server.

name: Demo plugin
authors: Gobrosse
version: 1.0
main: io.xol.demo.DemoPlugin

command: demo

This is very similar to the plugin.yml found in bukkit plugins, only it uses a much cruder parser. All those lines are pretty obvious, I'll just explain main and command : the first tells the game what class it should instantiate, and the latter defines one command that this plugin will manage. Your plugin can manage multiple commands, just repeat that line with the commands you need.

The entry point to your plugin is a class extending the ChunkStoriesPlugin class, like this one

package io.xol.demo;

import io.xol.chunkstories.api.GameContext;
import io.xol.chunkstories.api.plugin.ChunkStoriesPlugin;
import io.xol.chunkstories.api.plugin.PluginInformation;
import io.xol.chunkstories.api.plugin.commands.Command;
import io.xol.chunkstories.api.plugin.commands.CommandEmitter;
import io.xol.chunkstories.api.plugin.commands.CommandHandler;

public class DemoPlugin extends ChunkStoriesPlugin implements CommandHandler {

	public DemoPlugin(PluginInformation pluginInformation, GameContext pluginExecutionContext) {
		super(pluginInformation, pluginExecutionContext);
	}

	DemoEventHandler handler;
	
	@Override
	public void onEnable() {
		handler = new DemoEventHandler(this);
		this.getPluginManager().registerCommandHandler("demo", this);
		
		this.getPluginManager().registerEventListener(handler, this);
		System.out.println("Enabling plugin ... ");
	}

	@Override
	public void onDisable() {
		System.out.println("Disabling plugin");
	}

	@Override
	public boolean handleCommand(CommandEmitter emitter, Command command, String[] arguments)
	{
		if(command.equals("demo"))
			emitter.sendMessage("Hi !"+arguments.length);
		return true;
	}

}

If you are any familiar with Bukkit/Spigot plugins, this code shouldn't feel too overwhelming, there is a constructor dependant on wether the plugin is only client, only server or both, onEnable/onDisable methods as well as command and event handlers.

this.getPluginsManager().registerEventListener(handler, this);, let's look at DemoEventHandler :

Let's look at this example :

package io.xol.demo;

import io.xol.chunkstories.api.events.EventHandler;
import io.xol.chunkstories.api.events.Listener;
import io.xol.chunkstories.api.events.core.PlayerLoginEvent;

public class DemoEventHandler implements Listener {

	public DemoEventHandler(DemoPlugin demoPlugin) {
		// You might want to reference your plugin for callbacks or whatever
	}
	
	@EventHandler
	public void handlePlayerLogin(PlayerLoginEvent event)
	{
		// Blah
		event.connectionMessage = event.getPlayer()+" tried to connect but was rejected :(";
		event.setEventAllowedToExecute(false);
	}
}

You can see an @EventHandler annotation before the handlePlayerLogin function. It's actually very important, it tells the plugins manager that this methods should care about a specific event and be called when that event occurs. The function name can be anything you like, the event name too, the only important thing is that a function annotated with @EventHandler has only one parameter of type a subclass of “Event”.

By default, Events are allowedToExecute() and the server/client will carry on doing whatever it was supposed to do. You can change this behaviour by either messing with the Event parameters and affected objects, or even by denying the event to happen altogether.