「Plugin Tutorial」を編集中

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

== 始めに ==
このチュートリアルは、[http://forums.bukkit.org/threads/plugin-development-a-huge-tutorial-status-under-development.15167/ こちらのスレッド]からの転載です。当ページの原著者は、'''Adamki11s'''氏ですが、多くの編集を受けて今に至ります。

[http://forums.bukkit.org/members/adamki11s.42417/ Adamki11s Bukkit Profile Page] 

このチュートリアルを読み終えた後は、'''Adamki11s''''氏の"Extras" からより深い情報を得る事が出来ます。[http://forums.bukkit.org/threads/dev-extras-v1-1-additional-useful-and-advanced-methods-for-plugin-developers-953.26207/ Extras library forums thread.]


:'''Note''': 当ページには、原文の翻訳ではない、日本語読者向けの独自の記述を行っている箇所が少量あります。そのような内容を含む節ではNoteにて通知しています。
:'''Note''': 当ページの内容は、[[Bukkit用MODの作成方法]]の内容とは異なるアプローチによるBukkitプラグイン開発手法の解説です。
:'''Note''': 当ページでは、技術的な解説やたとえ話の原意を理解し易くするために、一部意訳を行っています。

== Javaの習得 ==
:'''Note''': 当記事の一部は原文の訳ではありません、日本語読者向けに独自の内容を記述しています。 

このチュートリアルの読者には、Java言語プログラミングの基礎がわかる方を対象としています。<br/>
Javaの基礎知識が少ない方は、下記の情報に触れてください。

=== Javaコーディング方法 ===

*[http://docs.oracle.com/cd/E26537_01/tutorial/index.html Oracleの記事] (現在のJavaの公式サイト) 
*[http://www.tohoho-web.com/java/index.htm とほほのJava入門] - 基礎をみっちり解説している
*[http://www.kab-studio.biz/Programing/OOPinJava/ Javaのオブジェクト指向入門] - 継承や実装等のオブジェクト指向用語が分からない人向け

Javaがどうしても理解できない場合は、この他にも様々な資料があるので探して触れてください。

== Javaの開発環境 ==
:'''Note''': 当記事の一部は原文の訳ではありません、日本語読者向けに独自の内容を記述しています。

プラグインを開発する（またはJavaを学ぶ）前に、開発環境(IDE (Integrated Development Environment))をインストールして下さい。<br/>
開発環境は、プラグインのコンパイルとデバッグを行うために使います。<br/>
Javaの主要なIDEには、[http://www.eclipse.org/ Eclipse], [http://netbeans.org/ Netbeans], [http://www.jetbrains.com/idea/ IntelliJ IDEA] の３つがあります。<br/>
EclipseはBukkit開発者の中では最も人気があり、IntelliJの方は業界内で広く利用されています。

あなたがJavaの初心者なら、当チュートリアルが解説に利用しているEclipseを利用する事をお勧めします。<br/>
Eclipseのお勧めのバージョンの配布元は、[http://mergedoc.sourceforge.jp/pleiades_distros3.7.html 日本語 Eclipse / Pleiades All in One 日本語ディストリビューション]です。<br/>
これはMergedocProjectが配布する拡張されたパッケージであり、Eclipseの一次配布元が提供するパッケージではありません。

どのIDEも気に入らなければ、BlueJも利用できます。<br/>
プラグイン開発が初めてであるなら、とにかく一度Eclipseを使ってみて、<br/>
良ければNetBeansを試してみると良いでしょう。

[http://www.okapiproject.com/java/java_tools/eclipse/index.html 優良なEclipseの解説]。お勧めのものより古いバージョンの解説ですが、ほぼ同様です。

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

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

[[Image:NewJavaProject.png]]

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

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

最新のBukkit APIはここからダウンロードが可能です。 {{BDownload}}

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

[[Image:BuildPathPic.png|800px]]

=== BukkitのJavadocの利用方法 ===

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

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

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

:次ような画面になります：<br/>
:[[Image:Bukkitjavadocs.png]]

=== Plugin開発の開始 ===

[[Image:MakePackage.png]]

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

=== onEnable()とonDisable()の基本 ===
前のセクションで作成したメインクラスに、onEnable()とonDisable()のメソッドを作成します。<br />
<blockquote><source lang="java">
public void onEnable(){ 
 
}
 
public void onDisable(){ 
 
}
</source></blockquote>


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

これを・・・
<blockquote><source lang="java">Class <classname> {}</source></blockquote>

このように変更する。
<blockquote><source lang="java">Class <classname> extends JavaPlugin {}</source></blockquote>

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

<blockquote>[[ファイル:to_need_import_package.png]]</blockquote>

もしくは、
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;</source></blockquote>
をコード上部の定義部に記述する事でも同様の事が行えます。

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

始めに、プラグインが実際に動作するかどうかを確認するため、シンプルなメッセージをサーバコンソールに表示させてみましょう。この処理として、ログ出力機能(Logger)をメインクラスに定義して初期化します。
<blockquote><source lang="java">Logger log = this.getLogger();</source></blockquote>
その後、onEnable()メソッドに、プラグインが動作している事を通知するメッセージを出力する処理を記述します。
<blockquote><source lang="java">log.info("Your plugin has been enabled.");</source></blockquote>

onDisable()メソッドについても同等の記述を行います。ここまでのコーディングによって、メインクラスは下記の様な内容になっているはずです。
<blockquote><source lang="java">
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.");
	}
}
</source></blockquote>

== イベントとリスナ ==

:: ''[[新しいEventSystemの使い方]]を参照して下さい''

== コマンド ==
=== 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となる）

=== コマンドの設定 ===
<blockquote><source lang="java">public boolean onCommand(CommandSender sender, Command cmd, String commandLabel, String[] args){
        // プレイヤーが「/basic」コマンドを投入した際の処理...
	if(cmd.getName().equalsIgnoreCase("basic")){ 
		// 何かの処理
		return true;
                // コマンドが実行された場合は、trueを返して当メソッドを抜ける。
	}
	return false; 
        // コマンドが実行されなかった場合は、falseを返して当メソッドを抜ける。
}</source></blockquote>
onCommand()をコーディングする際は、上記の例のように、メソッドの最終ステップにfalseをreturnする行を記述するのが良い方法です。<BR/>
falseが返る事で、plugin.yml（下記参照）内に記述されたメッセージが表示され、<BR/>
onCommand()処理が正しく動作しなかった事をメッセージから検知できるため、動作確認の助けになるからです。<BR/>
逆に、メソッドの最後でtrueを返す処理構造にしてしまった場合は、onCommand()内の各処理に対して、<BR/>
処理結果チェック処理と結果が不正である場合にfalseを返すような、同じ処理を何度も記述する必要が出てきますので、大変な無駄となります。<BR/>
<BR/>
なお、コード「.equalsIgnoreCase("basic")」のパラメタ「basic」は、大文字小文字の区別はありません。

=== plugin.ymlへのコマンドの追加 ===

コマンドを用意する際は、plugin.ymlファイルにも定義を追加する必要があります。plugin.ymlの最後に次の行を追加します。
<blockquote><source lang="yaml">
commands:
   basic:
      description: This is a demo command.
      usage: /<command> [player]
      permission: <plugin name>.basic
      permission-message: You don't have <permission>
</source>
* basic - コマンド名 
* description - コマンドの説明文
* usage - onCommand()がfalseを返した際に、コマンド実行ユーザに向けて表示されるメッセージの内容。コマンドの使い方を明解に書いてください。
* permission - 当コマンドの動作に必要なプラグインの設定を、コマンド実行ユーザに知らせるメッセージ。（主に、コマンド実行に必要なpermissionを書きます）
* permission-message - コマンド実行権限を持たないユーザがコマンドを実行した場合に、その旨を同ユーザに知らせるメッセージ。
</blockquote>

:'''Note''': ymlファイルには、1個タブを2個のスペースで記述する必要があります。タブ文字は構文エラーとなるため利用できません。

=== コンソールコマンドとプレイヤーコマンド ===

察しの良い人は、<code>'''CommandSender sender'''</code> パラメタに着目しているかもしれません。 <code>'''CommandSender'''</code>クラスは、プラグイン開発者に2つの点で有用な、Bukkitが提供するインタフェースです。

CommandSenderインタフェースの実装: <code>'''Player'''</code> と <code>'''ConsoleCommandSender'''</code> (正確には <code>'''Player'''</code>もインタフェース)です。
プラグインを作る際は、次の2点に注意しながら作る事が非常に良い方法です。
* プラグインが動作している事をサーバコンソールで確認しながら作る事
* ログインプレイヤー向けのコマンドが、実際にログインしているプレイヤーのみ実行できる事
プラグインは、senderがプレイヤーではない場合（例えばコンソールからプラグインのコマンドが投入された場合）であっても、サーバコンソールには明解でシンプルな動作結果を返します。（例えば天気を変えるコマンドの実行結果は、ゲーム内では無くサーバコンソール上のメッセージから確認すれば間違いありません）

記述例: 
<blockquote><source lang="java">
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
	Player player = null;
	if (sender instanceof Player) {
		player = (Player) sender;
	}

	if (cmd.getName().equalsIgnoreCase("basic")){ // If the player typed /basic then do the following...
		// do something...
		return true;
	} else if (cmd.getName().equalsIgnoreCase("basic2")) {
		if (player == null) {
			sender.sendMessage("this command can only be run by a player");
		} else {
			// do something else...
		}
		return true;
	}
	return false;
}
</source> </blockquote> 

この例では、'''basic''' コマンドはログインプレイヤーとサーバコンソールのどちらからでも実行できます。しかし、'''basic2''' コマンドは、ログインプレイヤーしか実行できません。
一般的に、コマンドはプレイヤーとサーバコンソールの両者に実行を許可しますが、投入されたコマンドの実行可否をチェックする必要があるコマンドについては、ログインプレイヤー向けのコマンドとして実装されるべきでしょう。

つまり、プレイヤーに依存する処理（テレポートコマンドやアイテムを与えるコマンド等は、対象となるプレイヤーが必要です）を行うコマンドが、プレイヤーコマンドとして実装されるべきものと言えます。

凝ったコマンドを作りたい場合、コマンドのパラメタ（上記例では <code>'''args'''</code>パラメタ）を利用して独自の処理実装を行うことができます。例えば、プレイヤー名を指定したテレポートコマンドのみが、サーバコンソールから実行できる実装にする等が考えられます。

:'''訳者補記''': コマンド実装方法には、プレイヤー向け・サーバコンソール向けの2種類があり、それぞれの区別はどのような考え方で行うべきかについて説明しています。

=== CommandExecutorのクラス分割 ===

上記の例では、onCommand()メソッドをプラグインのメインクラスに記述していました。小さなプラグインでは良い方法ですが、大きなプラグインに拡張していくのであれば、適切なクラスを作成してそちらに配置するべきです。幸い、難しい事ではありません：

* プラグインのpackage内に、'''MyPluginCommandExecutor''' のような名前で新規のコマンド実行クラスを作成する(当然、MyPluginはあなたのプラグイン名に合わせて変えましょう)。
* MyPluginCommandExecutorに、BukkitのCommandExecutorインタフェースを実装(implements)させる。
* プラグインのonEnable()メソッドの処理で、MyPluginCommandExecutorクラスのインスタンスを生成する。
* MyPluginCommandExecutorインスタンスをパラメタとして、処理<code>'''getCommand("basic").setExecutor(myExecutor);'''</code>を実行させる。

:'''Note''': <code>'''"basic"'''</code>は実行されたコマンドであり、<code>'''myExecutor'''</code>はMyPluginCommandExecutorインスタンスです。

とっても良い具体例:
<blockquote><source lang="java">MyPlugin.java (the main plugin class):

private MyPluginCommandExecutor myExecutor;
@Override
public void onEnable() {
	// ....
 
	myExecutor = new MyPluginCommandExecutor(this);
	getCommand("basic").setExecutor(myExecutor);
 
	// ...
}</source></blockquote>

<blockquote><source lang="java">
MyPluginCommandExecutor.java:

public class MyPluginCommandExecutor implements CommandExecutor {
 
	private MyPlugin plugin;
 
	public MyPluginCommandExecutor(MyPlugin plugin) {
		this.plugin = plugin;
	}
 
	@Override
	public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
		// ... implementation exactly as before ...
	}
}
</source></blockquote>
どのように、メインプラグインのインスタンスが'''MyPluginCommandExecutor'''のコンストラクタを実行するかに注目しましょう。

この節で紹介した方法により、メインのonCommand()メソッドが巨大で複雑になったとしても簡単に整理する事ができ、結果として、プラグインのメインクラスを複雑化させずに、処理分割する事ができます。

:'''Note''': プラグインが複数のコマンドを持つ場合、個々のコマンドに対応する'''CommandExecutor'''をコーディングする必要があります。

:'''訳者補記''': 積極的に、大きな処理は小さく分割していきましょう。そのための仕組みをBukkitが用意しています。という事を教示しています。

== 堅牢なonCommandの記述 ==
onCommand()メソッドを記述する際、パラメタの利用に関して、<br/>
決め付けて掛かってはいけない事がありますので念頭において下さい。<br/>
これらに留意した処理を記述する事で、堅牢なonCommand()をコーディングする事ができます。

=== senderの内部データ型をチェックする ===
senderの内部データがPlayer型であるとは限らない事を念頭において、チェックを行って下さい。<br/>
処理例:
<blockquote><source lang="java">public boolean onCommand(CommandSender sender, Command cmd, String commandLabel, String[] args){
	if ((sender instanceof Player)) {
           // doSomething
        } else {
           sender.sendMessage(ChatColor.RED + "You must be a player!");
           return false;
        }
        Player player = (Player) sender;
        return false;
}</source> </blockquote>

=== コマンドのパラメタ長をチェックする ===
senderインスタンスは、妥当なパラメタを持っているとは限りません。パラメタ長をチェックして下さい。<br/>
処理例:
<blockquote><source lang="java">public boolean onCommand(CommandSender sender, Command cmd, String commandLabel, String[] args){
	if (args.length > 4) {
           sender.sendMessage(ChatColor.RED + "Too many arguments!");
           return false;
        } 
        if (args.length < 2) {
           sender.sendMessage(ChatColor.RED + "Not enough arguments!");
           return false;
        }
}</source> </blockquote>

=== プレイヤーがオンラインである事を確認する ===
特定のプレイヤーのPlayerインスタンスを利用したい場合、<br/>
必ずそのプレイヤーがオンラインである必要があります。<br/>
オンラインであるかどうかをチェックして下さい。<br/>
処理例:
<blockquote><source lang="java">public boolean onCommand(CommandSender sender, Command cmd, String commandLabel, String[] args){
	Player other = (Bukkit.getServer().getPlayer(args[0]));
        if (other == null) {
           sender.sendMessage(ChatColor.RED + args[0] + " is not online!");
           return false;
        }
        return false;
}</source> </blockquote> 

オンラインではないプレイヤーのインスタンスに操作を加えたい場合は、一般的には<code>'''OfflinePlayer'''</code>クラスを利用して行う事ができます。

== プラグインのConfiguration/Settings ==
:: ''[[新しいConfigurationの使い方]]を参照して下さい ''

== 権限 ==
Bukkitのパーミッション（権限）APIの利用は、簡単ではありません。

プレイヤーが特定の権限を持っているかどうかを調べる処理は次のようになります：
<blockquote><source lang="java">if(player.hasPermission("some.pointless.permission")) {
   //Do something
}else{
   //Do something else
}</source></blockquote> 

権限がセットされているか、いない(Javaの'''null'''と同等)かを調べる処理は次のようになります：
<blockquote><source lang="java">boolean isPermissionSet(String name)</source></blockquote> 

なぜグループの概念が存在しないかと思った方もいるでしょうが、
そもそも、権限にはグルーピングの概念は不要なのです。

元々、グループの主な用途はチャットメッセージをフォーマッティングする事にありました。<br/>
これは権限の機能を利用してもっと簡単に行えます。<br/>
例えば、チャットプラグインの設定において、権限とプレフィクスの関連を定義する事が該当します。<br/>
具体的には、権限'''"someChat.prefix.admin"'''をプレフィクス'''[Admin]'''に対応させる定義を行い、<br/>
プレイヤーがチャットで発言する度に、プレイヤー名の先頭に'''[Admin]'''が付くようになる機能が挙げられます。

他にも、グループに所属する複数のユーザに、<br/>
メッセージを送信するような機能を実現するために利用する事が考えられます。<br/>
この例を、権限を利用した処理で記述すると以下のようになります: 
<blockquote><source lang="java">for(Player player: getServer().getOnlinePlayers()) {

    if(player.hasPermission("send.recieve.message")) {
        player.sendMessage("You were sent a message");
    }

}</source> </blockquote> 

さて、依然として<br/>
「グループを利用せずに、複数のプレイヤーに権限をセットする良い方法は何なのか？」が疑問かと思いますが・・・<br/>
BukkitのAPI自体は、グループの概念を提供していません。<br/>
グループの概念を利用するためには、permissionsBukkitのような<br/>
グループ権限の機能を提供するプラグインを利用する事になります。<br/>
とどのつまり、'''このAPIはインタフェース(Interface)であり、実装(Implementation)ではない'''のです。

=== 権限の設定 ===

権限を利用して細かな制御を行いたい場合は、<br/>
デフォルト権限と、子権限の設定を''plugin.yml''に追記する事を検討して下さい。<br/>
この2種類の設定は、オプション（必須ではなく完全に任意で利用される）項目ではありますが、お勧めします。<br/>

下記は、''plugin.yml''の最後に追加する形で設定する権限です：
<blockquote><code><source lang="yaml">permissions:
    doorman.*:
        description: Gives access to all doorman commands
        children:
            doorman.kick: true
            doorman.ban: true
            doorman.knock: true
            doorman.denied: false
    doorman.kick:
        description: Allows you to kick a user
        default: op
    doorman.ban:
        description: Allows you to ban a user
        default: op
    doorman.knock:
        description: Knocks on the door!
        default: true
    doorman.denied:
        description: Prevents this user from entering the door</source>
</code></blockquote>


まず、プラグインが利用する各権限を、''permissions''ノードの子ノードとして定義します。<br/>
それぞれの権限はオプションとして、概要（description）、デフォルト値、子ノードを持ちます。

==== デフォルト権限 ====

プレイヤーが権限を持たない場合、&nbsp;''hasPermission''&nbsp;はデフォルトではfalseを返します。<br/>
''plugin.yml''中のデフォルトのノードに対して、下記の4つのどれか1つを設定する事で、<br/>
この挙動を変更する事ができます：
*'''true''' - デフォルトで、権限を持つ（=hasPermissionがtrueを返す）。
*'''false''' - デフォルトで、権限を持たない（=hasPermissionがfalseを返す）。
*'''op''' - プレイヤーがOPであれば、権限を持つ（=hasPermissionがtrueを返す）。
*'''not op''' - プレイヤーがOPでなければ、権限を持つ（=hasPermissionがtrueを返す）。

==== 子権限 ====

恐らく今までに、''* 権限''を利用してサブ権限を割り当てた事があると思います。<br/>
これは、変更されたBukkit APIと、子権限の定義によって実現した機能であり、<br/>
高い柔軟性を提供しています。<br/>
下記はその実装例です：
<blockquote><source lang="yaml">permissions:
    doorman.*:
        description: Gives access to all doorman commands
        children:
            doorman.kick: true
            doorman.ban: true
            doorman.knock: true
            doorman.denied: false</source>

''doorman.*''権限は、いくつかの子権限を含んでいます。
''doorman.*''権限がtrueである場合に、
その子権限は''plugin.yml''に定義された値(trueかfalse)をデフォルト権限として機能します。
''doorman.*''権限がfalseである場合は、
その子権限のデフォルト権限は、全て反転（trueが定義値ならfalseになる）された状態で機能します。
</blockquote> 

=== 独自の権限設定 ===

独自に権限の仕組みを提供するプラグインを開発したい場合、&nbsp;[[権限プラグインの開発方法]]を参考にして下さい。

== スケジューリングタスクとバックグラウンドタスク ==

現在、Minecraftサーバはゲームロジックのほとんどがシングルスレッドで稼動しています。<br/>
このため、発生する個々の処理はごく小さいものにする必要があります。<br/>
プラグイン中に複雑なコードが存在して、それが適切に処理されないような場合は、<br/>
ゲームロジックに多大なラグや処理遅延を発生させる原因となります。<br/>

幸運なことに、Bukkitはプラグインに対してスケジューリングのためのコーディング方法を提供しています。<br/>
どこかのタイミングで一度だけRunnableタスクを実行したり、<br/>
小さなタスクに分けた定期的な繰り返しであったり、<br/>
新規に独立したスレッドを派生させたり・・・<br/>
といった複数の方法で、長大なタスクをゲームロジックと並行で処理させる事ができます。

詳しくは、[[スケジューラのプログラミング方法]]中の、同期タスクと非同期タスクのスケジューリング方法に関する解説を参考にして下さい。

== ブロックの操作 ==
ブロックを生成する簡単な方法は、既存のブロックを取得して変更する事です。<br/>
例えば、あなたの5ブロック上方にあるブロックを変更したい場合、<br/>
まずはそのブロックを取得した上で、変更を加えることになります。<br/>
PlayerMoveイベントの処理中でこれを行う例を示します：
<blockquote><source lang="java">public void onPlayerMove(PlayerMoveEvent evt) {
	Location loc = evt.getPlayer().getLocation(); // プレイヤーからその位置を得る
	World w = loc.getWorld(); // 位置からワールドを得る
	loc.setY(loc.getY() + 5); // 位置のY座標を+5する
	Block b = w.getBlockAt(loc); // ワールド上の指定位置のブロックを得る
	b.setTypeId(1); // ブロックのタイプIDに1をセットする
}</source></blockquote> 

このコードの処理は、プレイヤーが移動する（=PlayerMoveイベントが発生する）度に、<br/>
プレイヤーの5ブロック上方のブロックがStone（TypeIdが1のブロック）に変化する動作として見えるでしょう。<br/>
ブロック取得までの流れは・・・
# 取得したプレイヤーの位置から、ワールドを取得する
# 位置のY座標を+5する
# <code>'''w.getBlockAt(loc);'''</code>で、ワールドにおける位置に存在するブロックを得る
となります。<br/>

位置（''loc''）中のブロックインスタンス（''b''）に対して、<br/>
IDを変えたり、ブロックデータ自体を変更する事もできます。

また、ブロックの種類を表すデータはbyte型であるため、<br/>
byte型にキャストしたデータを与えた指定ができます。<br/>
例えば、<code>'''b.setData((byte)3); '''</code>です。


建物の生成や、一定のアルゴリズムに従ったブロック生成処理などを行う事ができます。<br/>
例えば、固体ブロックによる立方体を生成する処理は、<br/>
3階層にネストしたforループ処理によって記述できます。
<blockquote><source lang="java">public void generateCube(Location point, int length){  // public visible method generateCube() with 2 parameters point and location
	World world = point.getWorld();

	int x_start = point.getBlockX();     // Set the startpoints to the coordinates of the given location
	int y_start = point.getBlockY();     // I use getBlockX() instead of getX() because it gives you a int value and so you dont have to cast it with (int)point.getX()
	int z_start = point.getBlockZ();

	int x_lenght = x_start + length;    // now i set the lenghts for each dimension... should be clear.
	int y_lenght = y_start + length;
	int z_lenght = z_start + length;

	for(int x_operate = x_start; x_operate <= x_length; x_operate++){ 
		// Loop 1 for the X-Dimension "for x_operate (which is set to x_start) 
		//do whats inside the loop while x_operate is 
		//<= x_length and after each loop increase 
		//x_operate by 1 (x_operate++ is the same as x_operate=x_operate+1;)
		for(int y_operate = y_start; y_operate <= y_length; y_operate++){// Loop 2 for the Y-Dimension
			for(int z_operate = z_start; z_operate <= z_length; z_operate++){// Loop 3 for the Z-Dimension

				Block blockToChange = world.getBlockAt(x_operate,y_operate,z_operate); // get the block with the current coordinates
				blockToChange.setTypeId(34);    // set the block to Type 34
			}
		}
	}
}</source></blockquote> 

このメソッドは、辺の長さと開始点の指定を受けて、任意のサイズと位置を持つ直方体を生成する処理です。<br/>
ブロックの削除処理の場合も、このロジックを真似て同様のアルゴリズムで実装する事ができます。<br/>
ただし、セットするブロックのIDはゼロ（=air）になりますね。

== プレイヤーインベントリの操作 ==

この節では、プレイヤーのインベントリ操作を特に扱っていますが、<br/>
チェストのインベントリの操作にも適用できますので、必要なら応用して下さい(ﾟ∀ﾟ)<br/>
インベントリ操作のシンプルな例：
<blockquote><source lang="java">public void onPlayerJoin(PlayerJoinEvent event) {
    Player player = event.getPlayer(); // Joinしたプレイヤー
    PlayerInventory inventory = player.getInventory(); // プレイヤーのインベントリ
    ItemStack diamondstack = new ItemStack(Material.DIAMOND, 64); // 山積みのダイヤモンド！

    if (inventory.contains(diamondstack)) {
        inventory.addItem(diamondstack); // プレイヤーインベントリに山積みのダイヤモンドを加える
        player.sendMessage(ChatColor.GOLD + "よく来たな!もっとダイヤモンドをくれてやろう、このとんでもない成金め!!");
    }
}</source> </blockquote> 

さて、onPlayerJoin()メソッドの先頭で<br/>
'''player''', '''inventory'''、'''diamondstack'''変数を用意して下さい。<br/>
'''inventory'''はプレイヤーのインベントリで、'''diamondstack'''は（アイテムとしての）64個のダイヤモンドです。

次に、プレイヤーのインベントリがダイヤモンドを含んでいるかをチェックします。<br/>
プレイヤーがダイヤモンドをインベントリに所持している場合、<br/>
<code>'''inventory.addItem(diamondstack)'''</code>処理にて<br/>
同プレイヤーのインベントリに別のスタックを与え、黄金色のメッセージを送信します。<br/>
インベントリ操作は全然難しくありません。

ダイヤモンドのスタックを削除したい場合でも単純に、<br/>
<code>'''inventory.addItem(diamondstack)'''</code>を<br/><code>'''inventory.remove(diamondstack)'''</code>に置き換えるだけです。<br/>
（メッセージにも少しイタズラしておきましょう）

== アイテムの操作 ==
アイテムはスタックという単位で操作します。<br/>
スタックデータに対する全ての操作は、[http://jd.bukkit.org/apidocs/org/bukkit/inventory/ItemStack.html ItemStackクラスの仕様]を参照して下さい。

=== エンチャント ===

アイテムに対するエンチャントに触れる前に、[http://ja.minecraftwiki.net/wiki/Data_values Item Code] と [http://ja.minecraftwiki.net/wiki/Enchanting EID]を見てから以下の解説を読んでください。

エンチャントは、Enchantmentクラスが受け持っている機能ですが、<br/>
Enchantmentクラス自体は抽象クラスであるため、インスタンス化('''new Enchantment()''')出来ません。
エンチャントはEnchantmentWrapperクラスから利用する必要があるからです。

元々エンチャントが出来ないアイテムに対して、独自にエンチャントを付与する処理は書けません。<br/>
Bukkitサーバ自体が、エンチャント不可能なアイテムに対して、エンチャント情報を付与する仕組みを備えていないからです。<br/>
つまり、Fire AspectedなStick（火のエンチャントが付いた木の棒）はあり得ません。
<blockquote><source lang="java">
int itemCode = 280;  // StickのItemID
int effectId = 20;  // 効果Fire AspectのEID
int enchantmentLevel = 100; // エンチャントのレベル

ItemStack myItem = new ItemStack(itemCode);  // 木の棒のインスタンスを生成する
Enchantment myEnchantment = new EnchantmentWrapper(effectId);  // エンチャント効果のインスタンスを生成する
myItem.addEnchantment(myEnchantment, enchantmentLevel);  // 木の棒にFireAspectを付与する（ただし付与は成功しない）
</source></blockquote>

== HashMapの応用 ==

:'''Note''': このセクションは原文が独特な書き回しだったため意訳を行っています。

複数のプレイヤーが発するアクションやイベントを処理するためには、<br/>
イベントの発生や状態を保持するための領域として単一の変数を利用していたのでは不十分です。

例を挙げると、<br/>
私が作った古いプラグインのZones（今はRegionsに改名して処理も改善しています）では、<br/>
プラグインがサーバ上で実際にどのように振舞うかに関して考慮し切れていなかったために、<br/>
多くのエラーに直面しました。<br/>
具体的には、プレイヤーが特定の領域内に居たかどうかをチェックする処理で<br/>
チェック結果の格納先として単一のboolean値を利用したため、<br/>
複数のプレイヤーそれぞれに対するチェックを個別に保持する事が出来ずに膨大なエラーを引き起こしたのです。

HashMapはこのような問題を解決する素晴らしい方法です。<br/>
HashMapは、データを「'''キー'''と'''値'''のペア」の集まりとして保管できるデータ保持機能です。<br/>
これを利用するメリットは、HashMapが下記の仕様を備えている事です。<br/>
* １つのキーに対して、必ず１つの値が対応する
* 同じ内容のキーが、同一のインスタンス内に重複して存在できない
つまり、キーがプレイヤー、値がプレイヤーに紐付く情報の保管先になるようにHashMapを利用する事で、<br/>
プレイヤーとプレイヤーに紐付く値が強制的にペア（対）で管理できますし、<br/>
プレイヤーがインスタンス内で重複し得ない（ゲーム内で同一のプレイヤーは重複し得ない）事を保証できるのです。

具体的には、"TaroYamada"がキーとなり、"False"が値となります。<br/>
また、後からキー"TaroYamada"に対応する値を"True"に変更する事もできます：
<blockquote><source lang="java">
import java.util.HashMap;
public class Sample{
  public Sample(){
    HashMap<String, Boolean> playerFlags = new HashMap<String, Boolean>();
    playerFlags.put("TaroYamada", false);
    playerFlags.put("TaroYamada", true);
    playerFlags.put("GorillaMatsui", true);
  }
}
</source></blockquote>
:'''Note''': 理解のために独自に追加したコードです。

=== HashMapの定義 ===
<blockquote><source lang="java">public Map<Key, DataType> HashMapName = new HashMap<Key, Datatype>(); //Example syntax

//Example Declaration

public Map<Player, Boolean> pluginEnabled = new HashMap<Player, Boolean>();
public Map<Player, Boolean> isGodMode = new HashMap<Player, Boolean>();
</source> </blockquote> 

このコードは、以降のHashMapsの説明で使うので覚えてください。
さて、例としてプラグインが有効・無効化する時に、天候を切り替える簡単な処理を作りましょう。
まずはonCommand()の中に、前述の説明と同様にプレイヤーの状態に応じて、プレイヤー名を送信する処理を記述します。

onCommand()には下記を記述します。
内部で呼んでいるメソッドの名前は変えても良いですが、意味が通じるシンプルなものにして下さい。
<blockquote><source lang="java">Player player = (Player) sender;
togglePluginState(player);</source> </blockquote> 
上記のコードは、senderをPlayer型にキャストしたものをパラメタとして'''togglePluginState()'''に与えています。
では、'''togglePluginState()'''を実装しましょう。
<blockquote><source lang="java">public void togglePluginState(Player player){
    
    if(pluginEnabled.containsKey(player)){
        if(pluginEnabled.get(player)){
            pluginEnabled.put(player, false);
            player.sendMessage("Plugin disabled");
        } else {
            pluginEnabled.put(player, true);
            player.sendMessage("Plugin enabled");
        }
    } else {
        pluginEnabled.put(player, true); //If you want plugin enabled by default change this value to false.
        player.sendMessage("Plugin enabled");
    }

}</source> </blockquote> 

このコードが何をやっているかというと、
まず、HashMapの'''pluginEnabled'''が'''player'''をキーとして持っているかと、
次に、値が'''true'''と'''false'''のどちらなのかを調べています。

playerがキーに含まれており、かつ
値がtrueであれば、falseにリセットしてプレイヤーへメッセージを送信します。
falseであれば、trueにリセットして同様にメッセージを送信します。

playerがキーに含まれていない場合、
今処理を'''player'''が初めて行った当処理の実行とみなして、
HashMapへプレイヤーと値のペアを追加し、メッセージを送信します。

=== まだあるHashMapsの用途 ===

HashMap(よく似たMapも)は、データの集合体です。
集合の中から、一意な'''キー'''を使って対応する'''値'''を参照する処理を、高速・効率的に行います。

これに類する処理は付き物ですが、Mapはこれらを解決します。
Mapの理想的な用途の例はいくつもあります。
下記を見れば分かる通り、
用途は個々のプレイヤーに対応したデータである事にこだわる必要もありません。
必要に応じて、対象を置き換えて他の用途にも活用して下さい。

==== 値の参照 ====

<blockquote><source lang="java">
public Map<String, Integer> wool_colors = new HashMap<String, Integer>();

// Run this on plugin startup (ideally reading from a file instead of copied out row by row):
wool_colors("orange", 1);
wool_colors("magenta", 2);
wool_colors("light blue", 3);
   ...
wool_colors("black", 15);

// Run this in response to user commands - turn "green" into 13
int datavalue = 0;
if (wool_colors.containsKey(argument)
    datavalue = wool_colors.get(argument);
else {
    try { datavalue = Integer.parseInt(argument); }
    catch (Exception e) { ; }
}
</source> </blockquote>

=== HashMapデータのセーブ/ロード ===
HashMapがどのように動作するかを学びましたが、
次は恐らく、HashMapのデータを読み書きする方法を知りたくなるかと思います。
もし次のような要求があれば、HashMapが適しています。
* 管理者に手作業でデータ編集をさせたくない
* バイナリ形式でデータを保管したい(YAMLで扱うには複雑すぎるデータ)
* ブロック等のオブジェクトの引き当てに、任意の文字列を使いたい

これらは、HasMapの定義（HashMap&lt;Player,Boolean&gt;）を、任意のデータ型に変更することでシンプルに行えます。
引き続き、前節で出てきた"pluginEnabled"インスタンスの例を使って説明をします。
このコードは、与えられたパスに存在するファイルに対して、HashMapの値を保存します。
<blockquote><source lang="java">public void save(HashMap<Player,Boolean> pluginEnabled, String path)
{
	try{
		ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));
		oos.writeObject(pluginEnabled);
		oos.flush();
		oos.close();
		//Handle I/O exceptions
	}catch(Exception e){
		e.printStackTrace();
	}
}</source> </blockquote> 

これも非常に簡単で、ロード処理も他の例とそっくりな記述をします。
ObjectOutputStreamの代わりにObjectInputStream、
FileOutputStreamの代わりにFileInputStream、
writeObject()の代わりにreadObject()を使っています。
そして、最後にHashMapをreturnしています。
<blockquote><source lang="java">public HashMap<Player,Boolean> load(String path) {
	try{
		ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));
		Object result = ois.readObject();
		//you can feel free to cast result to HashMap<Player,Boolean> if you know there's that HashMap in the file
		return (HashMap<Player,Boolean>)result;
	}catch(Exception e){
		e.printStackTrace();
	}
}</source> </blockquote> 

このAPIを、HashMap, ArrayLists, Blocks, Players...その他全てのオブジェクトの、セーブ/ロードに利用できます。もし利用する場合は、私(Tomsik68)の著作である事を明記して下さい。
<blockquote><source lang="java">/** SLAPI = Saving/Loading API
 * API for Saving and Loading Objects.
 * @author Tomsik68
 */
public class SLAPI
{
	public static void save(Object obj,String path) throws Exception
	{
		ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));
		oos.writeObject(obj);
		oos.flush();
		oos.close();
	}
	public static Object load(String path) throws Exception
	{
		ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));
		Object result = ois.readObject();
		ois.close();
		return result;
	}
}</source> </blockquote> 
APIを使った実装方法: '''一部だけ抜粋''' 
<blockquote><source lang="java">public class Example extends JavaPlugin {
	private ArrayList<Object> list = new ArrayList<Object>();
	public void onEnable()
	{
		list = (ArrayList<Object>)SLAPI.load("example.bin");
	}
	public void onDisable()
	{
		SLAPI.save(list,"example.bin");
	}
}</source> </blockquote> 

:'''SLAPIとJavaのObjectOutputStreamに関する補足'''：Integer, String, HashMapといったJavaのデータ型について理解しているのであれば、この処理は未編集で動作します。Bukkitが提供するデータ型に対しても同様です。しかし、独自のデータクラスを自作してこのテクニックを適用したい場合は、JavaのSerializableインタフェースについて読んで下さい。それにより、簡単に少量の変更で動かす事ができます。コードを丁寧に解析する必要はありません。

== Map・Set・Listの応用 ==
HashMapクラスのもうひとつの機能は、Javaの持つ多くのデータ構造を提供する事にあります。<br/>
しかし、クラスの種類によってMapは時に適切ではないケースも存在します。<br/>
こちらに、そのようなケースについて詳しく記述するためのページとして、[[Javaのデータ構造クラス]]を用意しています。

== データベース ==
時にフラットファイルは、データベースとして利用するには不足があるでしょう。
Linux/Mac/Windowsのマシンにおいて、もっとも汎用的なデータベースはSQL(Structured Query Language)です。

ソフトウェアとしてのSQLは、個々のデータを格納するセルと、それらを識別するための列およびヘッダから成るデータベースを生成します。
会計用ソフトウェア（たとえばエクセルのような）の表が、より便利になったモノを思い浮かべてください。
SQLは、この表形態のデータに、データ同士の整合性の確保を目的とした独自のルール付けが行え、
かつ、フラットなファイルよりも高速で高機能なデータ利用のための方法も提供します。

Bukkitは、SQLの標準的な機能を利用するための仕組みを提供しています。
残念なことに、SQLには複数の種類が存在し、それぞれの設定方法と利用方法が少しずつ異なっています。
各自のニーズに応じて、好きな種類のSQLを選んで利用してください。（プラグインについても、利用するデータベースの種類に応じて複数の接続・利用方法が利用できます）

=== SQLite  ===

Alta189は、ダウンロード・インポートによって導入や移動が容易に可能なSQLiteを、Bukkitのプラグインで利用するためのライブラリを使う方法のチュートリアル、[http://forums.bukkit.org/threads/lib-tut-mysql-sqlite-bukkit-drivers.33849/ fantastic SQLite tutorial]を書きました。

SQLの構文については、次に紹介する動画を一度見てみる事をお勧めします。簡単な内容なので短時間で済みます。[http://www.w3schools.com/sql/default.asp SQL Tutorials @W3Schools] 

SQLiteは、その稼動のためにサーバを構築する必要がないため、シンプルさにおいて非常に優れています。
新規にデータベースとその中のテーブルを作成する手順は少量です。また、データのバックアップも、1個のデータベースファイルをバックアップするだけです。ただし、データ間の整合性の確保や柔軟性、データ件数が100万を超えるような膨大なデータの扱いにおいては、多少弱い面もあります。

とはいえSQLiteは、SQLデータベースを利用する新規プラグインの開発作業を、迅速で簡単にしてくれるメリットがあります。また、サーバ上で稼動する規模のSQLの予習のためにも有用です。

=== MySQL  ===
もうひとつ、人気があるSQLにMySQLというものがあります。
SQLiteよりもサーバ寄りの用途をもった種類のSQLで、多くの有名な企業の業務システムや、一日に100万アクセスを捌くようなウェブサイトが、この機能に依存しています。ただし、チューニング可能な範囲や機能が多岐に渡るため、セキュリティ上のリスクがMySQLへの習熟度に大きく左右されます。

プラグインからMySQLを利用する処理のコーディング方法は、小規模なSQLiteからMByte単位のOracleのデータベースに対するものと、大差ありません。しかし、データベースの管理作業は増えていく余地があります。使い続ける内に、データベース利用者のアカウントや権限の設定作業を行う事になっていくでしょう。また、データのバックアップやバックアップからの復旧（Rollbackと呼ぶ）作業のために、SQL文のスクリプトを書く事にもなるはずです。

== プラグインの配布 ==

== ヒントとノウハウ ==