Bukkit

Plugin API Tutorial

We are going to make PHPsend plugin. You must be familiar with Java and Bukkit API to understand this tutorial.

Project setup

The first thing we should do is to setup our project. I use Eclipse, It's probably most common environment. Start like with normal Bukkit plugin, add external Jar with bukkit, create new Project, package, and class extending JavaPlugin. One more thing you need to do is to add the PHPsend.jar to external jars. Now we can start doing the job! :)

NOTE!

If you use maven I (Ultimate) can let you add PHPSend as a dependency. Just add the follow to repositories and dependencies:

<repositories>
		<repository>
			<id>phpsend-repo</id>
			<url>http://ci.breezeyboy.com/plugin/repository/project/PHPSend/LastSuccessful/repository/</url>
		</repository>
	</repositories>
	<dependencies>
		<dependency>
			<groupId>org.shadowz.phpsend</groupId>
			<artifactId>PHPSend</artifactId>
			<version>1.2.2-dev</version>
		</dependency>
	</dependencies>

Writing main plugin

Create new class, extending PhpSendPlugin, name it as you wish. PhpSendPlugin is the main plugin class (rly?), it has several methods that we are going to use, and one method that must be overwritten. At first we should register our plugin for PHPsend, so it can pass events and execute functions from our class. Go to Bukkit Plugin class and add 2 lines to onEnable():

pl = new yourPluginClass();
MainPhpSend.registerPlugin(pl,"Your_Plugin_ID");

Simple? :D

Now let's do something more usefull, add following code to your plugin class:

@Override
public boolean onWebCommand(String cmd) 
{
	System.out.println("Cmd caught: "+cmd);
	return true;
}

@Override
public boolean onWebCommandAsPlayer(String player, String cmd) 
{
	return true;
}

When PHPsend receives anything it will pass it to all registered plugins through onWebCommand. :) Our method is quite simple. It prints passed message and returns true. Why true? onWebCommand should return true if the command should be passed further, and false if it was handled and shouldn't be executed by server. When having multiple plugins all must return true to let command be executed by server.

One more question, what is onWebCommandAsPlayer? Its used with player associated commands. Now just make it return true and leave it that way. We won't be changing it anymore. Lets just focus on the first method.

Now lets do something usefull. Change the code a bit:

@Override
public boolean onWebCommand(String cmd) 
{
	up.log.info("CMD: "+cmd);
	if (cmd.equals("PHPgetOnlinePlayers"))
	{
		/* We will check online players and send it here */
		return false;
	}
	return true;
}

Our plugin will react on "PHPgetOnlinePlayers". Otherwise we are going to pass cmd further. Now code for checking online players and getting their names into tab:

@Override
public boolean onWebCommand(String cmd) 
{
	up.log.info("CMD: "+cmd);
	if (cmd.equals("PHPgetOnlinePlayers"))
	{
		Player players[]=Bukkit.getServer().getOnlinePlayers();
		for (Player p : players)
		{
			/* Send his name here */
		}
		return false;
	}
	return true;
}

Sending data to opened socket is easy. Just use send(String msg). ;) Simple?

One more thing, PHP script needs to know how many players are online, to know when to stop getting data. We can also send MaxPlayers, just to make our page look better. Complete code:

@Override
public boolean onWebCommand(String cmd) 
{
	up.log.info("CMD: "+cmd);
	if (cmd.equals("PHPgetOnlinePlayers"))
	{
		Player players[]=Bukkit.getServer().getOnlinePlayers();
		send(""+players.length);
		send(""+Bukkit.getServer().getMaxPlayers());
		for (Player p : players)
			send(p.getName());
		return false;
	}
	return true;
}

We are done with our Java code, now lets make PHP script that will display online players.

PHP Script

First lets include PHPsend.php and connect to server.

<?php
include_once("PHPsend.php");

$c=new PHPsend();
if ($c->PHPconnect("adress","password")!=0)
{
	echo 'Can\'t connect :C';
	exit(0);
}
...

Now when we are connected, we ask for player list:

$c->PHPcommand("PHPgetOnlinePlayers");

Our plugin should catch the "PHPgetOnlinePlayers" message, and start sending data. We have to receieve it, and display. Firstly, as you remember we sent number of players, and then maximum number of players.

$numplayers=(int)($c->PHPrecvMsg());
$maxplayers=(int)($c->PHPrecvMsg());
	
echo("Players Online: ".$numplayers." / ".$maxplayers."<br>");

As you see reading data from plugin is just a quesion of one function :) We use PHPrecvMsg() to get the msg contents. It's also possible (and maybe more secure) to check the msg sender (sender is unique ID that we set while registering plugin). Then we should create PHPresponse object and receieve it with PHPrecv(), like $response = $c->PHPrecv(); To check if the msg came from "testPlugin", we should add $response->isFrom("testPlugin"); Getting the msg itself is just $response->msg; Simple enough, I think :D

Now we get the player names in loop from $i=0; to $i<$numplayers, and display names. It's also possible to store names in array, but we don't need to do that. Now the rest of the code.

for ($i=0; $i<$numplayers; $i++)
	echo($c->PHPrecvMsg()."<br>");

echo('END :)');

I echo end just to ensure that everything is finished :)

We could also send message to plugin that everything is ok, but its not needed ;)

That's all!

I hope its easy enough! :)