Build / API / Integration

既存の Markdown ガイドを wiki へ再配置したページです。ビルドターゲット、公開 API、WordPress 連携をまとめています。

Build Matrix

RankingPlugin build matrix

このプロジェクトは共通ソース + バージョン別オーバーレイで、以下の 2 系統を同時ビルドする構成です。

ビルド

./gradlew buildAll

出力先:

分割した互換処理

共通コードから参照する内部互換処理は、各ターゲットに応じて以下へ分割しています。

現在は次の差分を分離しています。

必要になれば、この方式で 26.1 専用の追加修正をさらに増やせます。

Plugin API Guide

RankingPlugin 連携ガイド

このプラグインは、外部プラグインから **ServicesManager API** と **Bukkit Event** の2本立てで連携できます。

1. plugin.yml

name: YourAddon
main: your.package.YourAddon
version: 1.0.0
api-version: 1.21
softdepend: [RankingPlugin]

`depend` でも動きますが、起動順の都合で止まりたくないなら `softdepend` が扱いやすいです。

2. まず持っておくと便利なクラス

外部連携プラグインでは、最低でも次の3クラス構成にしておくと拡張しやすいです。

この分け方にすると、将来 API が増えても差し替えが楽です。

3. APIの取得

import com.example.rankingplugin.api.RankingPluginApi;
import org.bukkit.Bukkit;

RankingPluginApi api = Bukkit.getServicesManager().load(RankingPluginApi.class);
if (api == null) {
    getLogger().warning("RankingPlugin API が見つかりませんでした");
    return;
}

long score = api.getScore("mizugorou_n");
long after = api.addScore("mizugorou_n", 1000);
long money = api.getCurrency("mizugorou_n");

主なAPI

4. 追加されたイベント通知

4-1. スコア変動通知

import com.example.rankingplugin.api.events.RankingScoreChangeEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class RankingEventListener implements Listener {
    @EventHandler
    public void onScore(RankingScoreChangeEvent e) {
        if (e.getDelta() <= 0) return;
        // 例: 一定値を超えたら独自UI更新
    }
}

取れる値:

4-2. ビンゴ達成通知

import com.example.rankingplugin.api.events.RankingBingoAchievedEvent;

@EventHandler
public void onBingo(RankingBingoAchievedEvent e) {
    // boardType は "3x3" or "5x5"
    // gainedLines は今回増えたライン数
}

取れる値:

4-3. ボス出現通知

import com.example.rankingplugin.api.events.RankingBossSpawnEvent;

@EventHandler
public void onBoss(RankingBossSpawnEvent e) {
    getLogger().info(e.getDisplayName() + " Lv" + e.getLevel() + " spawned at " + e.getWorldName());
}

取れる値:

現在は主に次のボスで通知します。

5. 自分のプラグイン側で用意すると楽な薄いラッパー例

public final class RankingBridge {
    private final JavaPlugin plugin;
    private RankingPluginApi api;

    public RankingBridge(JavaPlugin plugin) {
        this.plugin = plugin;
    }

    public void reload() {
        this.api = Bukkit.getServicesManager().load(RankingPluginApi.class);
    }

    public boolean isAvailable() {
        return api != null;
    }

    public long addScore(String playerName, long delta) {
        return api != null ? api.addScore(playerName, delta) : 0L;
    }
}

この形にしておくと、将来 RankingPlugin が無効でも自分のプラグインが落ちにくいです。

6. 連携時のおすすめ方針

7. 今後増やすとさらに便利なもの

今後このAPIを広げるなら、次のようなイベントも相性が良いです。

必要になったら、この方針のまま追加しやすい構造になっています。

WordPress Status Guide

WordPress 連携ガイド

1. Minecraft 側

`config.yml` の `external_status` を使います。

external_status:
  enabled: true
  endpoint_url: "https://YOUR_WORDPRESS_DOMAIN/wp-json/mc-status/v1/heartbeat"
  token: "YOUR_SHARED_SECRET"
  interval_seconds: 15
  immediate_on_joinquit: true
  include_player_list: true
  include_player_stats: true
  include_server_icon: true
  player_list_limit: 20

`server-id` と `server-name` も設定してください。

2. WordPress 側

1. `mc-status-bridge.php` を `wp-content/plugins/mc-status-bridge/` に置く

2. WordPress のプラグイン画面で **MC Status Bridge** を有効化

3. WordPress 管理画面 `設定 > MC Status Bridge` で token を設定

4. 固定ページにショートコードを置く

[mc_server_status]

特定のサーバーだけなら:

[mc_server_status server_id="Kure"]

3. 表示される内容

4. オフライン判定

Minecraft サーバーからの heartbeat が一定時間来なくなると、WordPress 側で自動的に OFFLINE 表示になります。

Wiki Coverage Update

この wiki では通常の src/main/java だけでなく、ビルド別の互換実装 paper-1_21_11 / paper-26_1 も掲載対象に拡張しています。

そのため、現在の掲載数は 273 logical classes / 73 packages です。物理的な Java ソースファイル数としては、ビルド別重複を含めてさらに多くなります。