Plugin Tutorial

本ページの内容は、Bukkit WikiのPlugin Tutorialを和訳した物となります。（一部は省略しています）
最新ではない可能性があるため、より新しい情報を確認する場合は、本家を参照するようにして下さい。
本項目は、和訳の最中です。最後まで読むことは出来ません。

Plugin用プロジェクトを始めるために

プロジェクトの作成

始める前にEclipseのワークスペースとファイルの設定を行う必要があります。
Eclipseを起動し、ファイル＞新規＞Java プロジェクトと選択して下さい。

プロジェクト名を入力し、新規プロジェクトウィザード画面の指示に従って、プロジェクトを作成してください。

Bukkit APIの参照

開発を始める前にbukkit APIライブラリをプロジェクトに追加する必要があります。 使用したい他のAPIも同じように追加することが可能です。

最新のBukkit APIはここからダウンロードが可能です。 Bukkit API - Development Snapshot

画面の左手にあるパッケージエクスプローラの(先ほど名前を付けた)プロジェクトを右クリックし、プロパティーを選択します。
開いた画面のJavaビルド・パスを選択し、ライブラリータブの中から、外部 Jar 追加ボタンを押して、ダウンロードしたBukkit APIを指定します。

BukkitのJavadocの利用方法

Eclipseを用いたJavaプログラミングの経験がある方なら、
Eclipseのエディタ上でクラスやメソッドにマウスカーソルを重ねた時に、
クラスやメソッドに関するドキュメントがポップアップで表示される事をご存知でしょう。
これは、Oracleのウェブサイトから得る事ができるJavadocの内容が表示されています。

Bukkitもまた、BukkitのAPIが提供するクラスやメソッドの各々のコードに同種のドキュメントを含んでおり、ポップアップで表示させる事ができます。
Eclipse上で、Bukkitのクラスやメソッドにマウスを重ねたタイミングでポップアップを表示できるようにするためには、下記の手順を行います。

1. プロジェクトエクスプローラ上で、Bukkitのjarファイルを右クリックして、メニューを開く。
2. "プロパティ"を選択し、表示されるポップアップ左側の"Javadoc ロケーション"項目を選択する。
3. "Javadoc URL"の下部にあるテキストボックスに、"http://jd.bukkit.org/apidocs/" (ダブルクォートは除く)を貼り付ける。
4. "検証"ボタンを押下し、URLがJavadocとして正しく識別される事をチェックしてから、OKボタンを押す。

次ような画面になります：

Plugin開発の開始

onEnable() and onDisable()

このファンクションは、プラグインが有効/無効になったときに呼ばれます。
デフォルトでは、プラグインは自動的に読み込まれたときに、イベントを登録やデバッグ出力を行うことが出来ます。
onEnable()は、プラグインがBukkitから読み込まれるときに最初に呼ばれ、プラグインを実行するために必須です。

onEnable()とonDisable()の基本

前のセクションで作成したメインクラスに、onEnable()とonDisable()のメソッドを作成します。

public void onEnable(){ 
 
}
 
public void onDisable(){ 
 
}

現時点では、このメソッドは何も行いません。また、エラーが発生する事にも気付くでしょう。このエラーは、メインクラスが、プラグインの機能を継承する必要がある事を示しています。当クラスの定義文を、下記のように変更しましょう。

これを・・・

Class <classname> {}

このように変更する。

Class <classname> extends JavaPlugin {}

すると、前述の追加コードが赤の下線でハイライト表示され、何かが間違っていることを通知してくるはずです。このハイライト部にマウスを重ねると、下記のようなポップアップが表示されるので、「'JavaPlugin'をインポートします(org.bukkit.plugin.java)」を選択します。

もしくは、

import org.bukkit.plugin.java.JavaPlugin;

をコード上部の定義部に記述する事でも同様の事が行えます。

Loggerを利用したメッセージ出力

始めに、プラグインが実際に動作するかどうかを確認するため、シンプルなメッセージをサーバコンソールに表示させてみましょう。まずは、loggerをメインクラスに定義して初期化します。

Logger log = this.getLogger();

その後、onEnable()メソッドに、プラグインが動作している事を通知するメッセージを出力する処理を記述します。

log.info("Your plugin has been enabled.");

onDisable()メソッドについても同等の記述を行います。ここまでのコーディングによって、メインクラスは下記の様な内容になっているはずです。

package me.<yourname>.<pluginname>;
 
import java.util.logging.Logger;
import org.bukkit.plugin.java.JavaPlugin;
 
public class <classname> extends JavaPlugin {
 
	Logger log;
 
	public void onEnable(){
		log = this.getLogger();
		log.info("Your plugin has been enabled!");
	}
 
	public void onDisable(){
		log.info("Your plugin has been disabled.");
	}
}

イベントとリスナ

Minecraft1.1向けのBukkit API以降、新しいイベントの仕組みが提供されています。
この新しい仕組みは、シンプルでかつ、汎用性・高速性・可読性等に優れています。

チュートリアル

当項目の、翻訳元記事で紹介されている動画を参照して下さい。
http://wiki.bukkit.org/Introduction_to_the_New_Event_System#Video_Tutorial

基礎

PlayerLoginEventについて説明します。
このイベントは最低限動作するための処理のみを記述するよう心がけ、
極力シンプルに保ちつつ編集していきましょう。

イベントリスナ

まず、イベントを待ち受ける処理（Event Listenerと呼ばれます）が必要です：

public void onPlayerLogin(PlayerLoginEvent event) {
    // Your code here...
}

次に、発生するイベント（Event Handlerと呼ばれます）が必要になります。

イベントハンドラ

イベントハンドラはイベントリスナに対する注釈であり、次のような書き方をします：

@EventHandler // EventPriority.NORMAL がデフォルト値

この記述は、メソッドがイベント優先度がNORMALのイベントハンドラである事を指定します。

イベントハンドラには優先度を指定でき、次のような書き方をします：

@EventHandler(priority = EventPriority.HIGHEST) // 高優先度のイベントとする
@EventHandler(priority = EventPriority.LOW) // 低優先度のイベントとする

以上をまとめると、次のようになります：

@EventHandler
public void onPlayerLogin(PlayerLoginEvent event) {
    // Your code here...
}

リスナの追加

"PlayerListener"として拡張する場合は、"Listener"インタフェースを実装する必要があります。
この時点では、次のような形のメソッドになりそうです：

public class myPlayerListener implements Listener {
    @EventHandler
    public void onPlayerLogin(PlayerLoginEvent event) {
        // Your code here...
    }
}

リスナ内部のメソッドは任意の名前を付けて呼び出する事が可能であり、
"onPlayerLogin()"のような、メソッドの名称が重要ではない事に言及しておきましょう。
「Bukkitは、どのEventを識別可能でどうやってListenするのか？」と不思議に思うかもしれませんが・・・
Bukkitは、あなたが指定したイベントからそれら（識別可能なEventと、そのListenの方法）を読み込みます。
上記の例で言えば、PlayerLoginEventから読み込みます。

Note: 特定のイベントまたはBukkitが登録しないイベントに関しては、手動で指定しなければなりません。（訳が不適切か）

イベントハンドラの設定

イベントハンドラには、様々な内容を指定可能です。
現時点では次のような指定が行えます：

型	項目名	デフォルト値	概要	指定できる値
EventPriority	priority	EventPriority.NORMAL	リスナに指定する優先度。	EventPriority.MONITOR EventPriority.HIGHEST EventPriority.HIGH EventPriority.NORMAL EventPriority.LOW EventPriority.LOWEST
boolean	ignoreCancelled	false	この値にTrueを指定したメソッド場合は、イベントがキャンセルされた際にイベントを受け付けない。	true false

イベントの登録

イベントを記述するクラスは、
Listenerインタフェースを実装(implements)し、かつイベントハンドラを含んでいなければなりません。

import org.bukkit.event.Listener;

public class LoginListener implements Listener {
}

イベントの登録処理は、PluginManagerインスタンスのregisterEventsメソッドとして、プラグインとリスナに記述します。

getServer().getPluginManager().registerEvents(Listener, Plugin);

リスナの例

このリスナは、2つのイベントハンドラを含んでいます。
1つは高優先度のもの、もうひとつは通常の優先度のものです。

import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;
 
public class LoginListener implements Listener {
    @EventHandler
    public void normalLogin(PlayerLoginEvent event) {
        // 何かの処理
    }
 
    @EventHandler(priority = EventPriority.HIGH)
    public void highLogin(PlayerLoginEvent event) {
        // 何かの処理
    }
}

プラグインへのイベントの登録

イベントの登録処理は、リスナとプラグインが必要です。
丁度よい事に、既にLoginListenerを作成していますので、これを利用してLoginPluginを作りましょう！

import org.bukkit.plugin.java.JavaPlugin;

public class LoginPlugin extends JavaPlugin {
    public void onEnable() {
        getServer().getPluginManager().registerEvents(new LoginListener(), this);
    }
}

プラグインへのイベントのリスナとしての登録

メインとなるクラスもイベントを持つ事ができます。
例:

import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;
 
public class LoginPlugin extends JavaPlugin implements Listener {
    public void onEnable() {
        getServer().getPluginManager().registerEvents(this, this);
    }
 
    @EventHandler
    public void normalLogin(PlayerLoginEvent event) {
        // Some code here
    }
}

リスナへのイベントの登録

イベントの登録には複数の方法があります。リスナクラスでイベントを登録する例を記述します。

import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;
 
public class LoginListener implements Listener {
    public LoginListener(LoginPlugin plugin) {
        plugin.getServer().getPluginManager().registerEvents(this, plugin);
    }
 
    @EventHandler
    public void normalLogin(PlayerLoginEvent event) {
        // Some code here
    }
 
    @EventHandler(priority = EventPriority.HIGH)
    public void highLogin(PlayerLoginEvent event) {
        // Some code here
    }
}

LoginPluginは次のようになります：

import org.bukkit.plugin.java.JavaPlugin;
 
public class LoginPlugin extends JavaPlugin {
    public void onEnable() {
        new LoginListener(this);
    }
}

イベントの自作

Bukkit自体が利用しているイベント記述の仕組みと全く同一の仕組みを利用して、 イベントを自作する事ができます。 この方法は、従来のような、 自作イベントである事に起因する固有のチェックが不要な点、 Bukkitの処理方法をそのまま利用するためにパフォーマンスを犠牲にしないという点で、 従来のイベント自作の方法よりも優れています。

イベントを自作する際は、次の2点に留意して下さい。

• Eventクラスを継承する必要がある
• static(静的)なハンドラとして作成する必要がある

staticハンドラは、自作イベント中に次のように記述して下さい。

private static final HandlerList handlers = new HandlerList();
 
public HandlerList getHandlers() {
    return handlers;
}
 
public static HandlerList getHandlerList() {
    return handlers;
}

上記のコードを実際に自作のイベント処理の中に記述する事で、 処理は疎結合となり、実行速度が改善します。

自作イベントの例

import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
 
public class CustomEvent extends Event {
    private static final HandlerList handlers = new HandlerList();
    private String message;
 
    public CustomEvent(String example) {
        message = example;
    }
 
    public String getMessage() {
        return message;
    }
 
    public HandlerList getHandlers() {
        return handlers;
    }
 
    public static HandlerList getHandlerList() {
        return handlers;
    }
}

自作イベントの呼び出し

イベントの呼び出し方法は、従来の方法と同様です：

// Create the event here
CustomEvent event = new CustomEvent("Sample Message");
// Call the event
Bukkit.getServer().getPluginManager().callEvent(event);
// Now you do the event
Bukkit.getServer().broadcastMessage(event.getMessage());

自作イベントの待ち受け

イベントはどのようにListen（待受,受付などとも表記）すれば良いでしょう？ 簡単です。通常のイベントと同様に待ち受けして下さい。

import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
 
public class CustomListener implements Listener {
    @EventHandler
    public void normalLogin(CustomEvent event) {
        // Some code here
    }
}

コマンド

onCommand()メソッド

さて、どのようにイベントを登録しいつ発生するかについて理解しました。 しかし、コマンドを利用して何かを起こしたい場合はどのようなデータ型を利用すればよいのでしょうか？それには、onCommand()メソッドを利用します。 このメソッドは、プレイヤーが文字"/"を入力する度に実行されます。 具体的には、"/do something"とコマンドを実行した場合にonCommand()が呼び出されます。 今のところ、onCommand()はまだプログラムしていないので何も起こらないでしょう。

コマンド名は、Bukkitや他のプラグインが提供しているものや、 提供するであろうものとの重複を避け、 ユニークなものとなるように考慮して下さい。 具体的には、"give"コマンドは既にいくつかのプラグインで利用されています。 もし独自に"give"コマンドを実装した場合は、 "give"コマンドを実装している他のプラグインとの互換性は無くなります。

onCommand()は、常にboolean型の値としてtrue,falseのどちらかを戻り値として返さねばなりません。 trueを返した場合は、情報表示のためのイベントは発生しません。 falseを返した場合は、プラグインファイルを"usage: property"に戻し、コマンドを実行したプレイヤーに、コマンドの利用方法を通知するメッセージを表示します。

onCommand()を利用する際は、4つのパラメータを登録しなければなりません。

• CommandSender sender - コマンドの発行元
• Command cmd - 実行されたコマンドの内容
• String commandLabel - 利用されたコマンドエイリアス
• String[] args - コマンドの引数を格納した配列（例：/hello abc defコマンドが入力された場合の内容は、args[0]がabc、args[1]がdefとなる）

コマンドの設定

public boolean onCommand(CommandSender sender, Command cmd, String commandLabel, String[] args){
	if(cmd.getName().equalsIgnoreCase("basic")){ // If the player typed /basic then do the following...
		// doSomething
		return true;
	} //If this has happened the function will break and return true. if this hasn't happened the a value of false will be returned.
	return false; 
}

onCommandメソッドをコーディングする際は、最終ステップでfalseをreturnするように記述しておくのが良いでしょう。 falseが戻り値として返る事で、plugin.yml(詳細は後述)に記述されているコマンドの利用方法がディスプレイ表示されますので、 コマンドの実行に何かしら問題が発生した事を表示から知ることができます。

戻り値を返す際にメソッドは終了しますので、似たようなreturn文がif文の配下にネストして記述されていない限り、trueを返す処理の下部に、実行したくないコードを記述します。

.equalsIgnoreCase("basic")に与える内容には、大文字小文字の区別はありません。例えば、"BAsIc"と"BasiC"はどちらも"basic"を与えた事と同義と見なされます。