【Bukkit Plugin開発】 Configuration API を使って設定・データを保存できるようにする

これは Adventar: Bukkit Plugin開発 Advent Calendar 2015 参加記事です。
他の記事もぜひご覧ください。

さて、今回は Bukkit API で用意されている Configuration API を使ってデータを保存します。これを使うと設定を保存したりできるようになります。

例によって参考ページです。
Minecraft Modding Wiki: 新しいConfigurationの使い方

この Configuration API を使うと簡単にプラグインのデータを、コンフィグファイルへ保管する事が出来ます。

注意点は

Configuration APIは、org.bukkit.configurationとorg.bukkit.configuration.file パッケージの配下にあります。
Bukkit1.1-R5以前に作られたプラグインは、org.bukkit.util.configurationパッケージ配下に存在した、
古いライブラリを利用した実装を採用しているかもしれません。
新旧の実装方法には互換性がありませんので、古いパッケージを使う処理は除去して下さい。

とあります。当てはまる方はご注意ください。

それではいきます。

以降、JavaPluginをextendsした、メインクラスにコーディングします。

ディスク上に保存したファイルの読み出し (getConfigメソッド)

継承メソッドgetConfig()は、 org.bukkit.configuration.file.FileConfiguration型のオブジェクトをreturnします。このオブジェクトはデータフォルダ配下のconfig.ymlのデータをもちます。

FileConfiguration configuration = this.getConfig();

getConfig() の動作

初めて呼び出された時

ディスク上のデータフォルダ/config.ymlの内容と、プラグインのJarファイル中に定義されたデフォルト値が、メモリ上にロードされ、その内容が戻り値として返される。
config.ymlがデータフォルダ配下に存在しない場合は、空のconfig.ymlファイルを読み込んだ事と等しい結果となる。

2回目以降

メモリ上に存在するFileConfigurationオブジェクトが戻り値として返されます。

Configuration API の注意事項

明示的に保存しない限りディスクへ保持されません。同様に、config.ymlファイルに加えられた変更も、メモリ上にロード済みのオブジェクトには反映されません。
ファイルに加えられた変更を読み込むためにはリロードメソッドを実行する必要があります。

データの取得 (getXxxメソッド)

値の読み込み処理は、以下のようなのgetterメソッドの呼び出し処理から成ります。

  • getBoolean(String key)
  • getInt(String key)
  • getString(String key)
  • getList(String key)
  • getStringList(String key)

その他の getterはこちらから確認してください。(API version 1.8.8)

データを代入 (setメソッド)

値をセットするには、設定ファイルのインスタンスのset(String, Object)メソッドを利用します。getメソッドとは異なり、setメソッドは1種類しか存在しません。下記のデータ型のオブジェクトだけがセット可能です。

  • プリミティブ
  • String
  • List
  • VectorやItemStackのようなConfigurationSerializableインタフェースを実装した型

コンフィグ値を削除するにはnullをセットします。
セット処理は、メモリ上に対してのみ行われ、ファイルにセーブしなければ、プラグインがdisabledされたタイミング(例: サーバを再起動した時)で失われます。

ディスク上に保存する (saveConfigメソッド)

プラグインの無効化後も残したい設定値であればディスクに書き出す必要がある。書き出すことで無効化(disabled)後も残すことができ、次回起動時にも参照することができる。
ディスク上に保存するにはsaveConfigメソッドを呼び出す。すでにファイルがあるときはディスク上のconfig.ymlに上書き保存される。

this.saveConfig();

ディスク上からリロードする (reloadConfigメソッド)

データフォルダ上のconfig.ymlが直接変更された場合、この変更点はメモリ上の設定値に反映されていない。
反映させるためには、reloadConfig()メソッドを呼び出す必要がある。ただしメモリ上の設定値が、リロードした内容で上書きされる事にも注意する必要がある。

this.reloadConfig();

デフォルト値を定義する

設定ファイルが、プラグインのデータディレクトリ配下に存在しない, 空である, キーが無い・・・といった状態である場合には、プラグインのJarファイル内に定義された値が、デフォルト値としてロードされる。
デフォルトのconfig.ymlファイルは、ファイル名はconfig.ymlであり、plugin.ymlと同一の場所に配置されている必要がある。
動的な値をデフォルト値とする場合、addDefaults(Map)やaddDefault(String, Object)、getString(String key, String default)のようにコーディングする事で実現できる。

ディスク上に保存されている config.yml を デフォルト値で上書きしたいとき

プラグインのデータフォルダ配下のconfig.ymlをデフォルト値で上書きしたい場合は、JavaPluginクラスのsaveDefaultConfig()メソッドを呼び出す必要がある。

saveDefaultConfig();

新規のデフォルト値を既存のconfig.ymlに追加したい場合は、copyDefaultsにtrueをセットする。

getConfig().options().copyDefaults(true);

注意!

デフォルトのconfig.ymlには、日本語のようなマルチバイトを含めないようにする!
config.ymlに ShiftJISで日本語を含めたプラグインは、Windowsでしか正常に起動しなくなる。
逆に、UTF-8N(BOM無し) で日本語を含めたプラグインは、MacintoshとLinuxでしか正常に起動しなくなる。

HashMapの活用

HashMapをコンフィグ値としてセーブする場合は、ConfigurationSectionを使う。
なお、HashMapはキーがString型、値がConfigurationSerializableを実装したデータ型でなければならない。

createSection (String path, Map<String, Object> map)

使用例

import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;
 
public class SamplePlugin extends JavaPlugin {
     @Override
    public void onEnable() {
        // もしconfig.ymlが存在しないなら、既定のconfig.ymlをコピー
        this.saveDefaultConfig();
 
        // 新しいリスナーを登録
        getServer().getPluginManager().registerEvents(new Listener() {
 
            @EventHandler
            public playerJoin(PlayerJoinEvent event) {
                // プレイヤーがサーバーに参加したときに、config.ymlに書かれたメッセージを送る
                event.getPlayer().sendMessage(SimpleMOTD.this.getConfig().getString("message"));
            }
        }, this);
    }
}
message: Welcome!

まとめ・次回

この Configuration API のおかげでとても楽に実装することが出来ました。
次回は Bukkit API に含まれるライブラリの話をします。

コメント
トラックバック
ページトップへ