パルワールドの REST API：キック・BAN・告知・強制保存の使い方

専用サーバーが立ち上がると、ホストはいずれ次のことをしたくなります。荒らしをキックする、再起動前にサーバー全体へ告知する、止めずに強制保存する。パルワールドがこれらのために用意している公式の窓口が REST API です。古い解説が案内している RCON は非推奨で、開発元は将来動作しなくなると告知しています。RCON を前提にした手順は読み飛ばして構いません。

この記事では、API の有効化、呼び出し方、できること、そして絶対に破ってはいけない安全上の一線を扱います。サーバーの構築自体は構築ガイドにあります。

なぜ RCON ではなくなったのか

パルワールドの RCON には実害のある問題が三つあり、非推奨化は気まぐれではありません。

• マルチバイト文字が切れる。 日本語、中国語、韓国語のプレイヤー名があると、RCON のコマンドが失敗したりログが化けたりします。日本のサーバーではほぼ確実に踏みます。
• 認証が弱い。 パスワードが平文でネットワークを流れ、ポートが露出していれば AdminPassword がインターネットに転がっている状態です。
• 返ってくるのは文字列。 プレイヤー数やフレームレートを監視に使いたければ、テキストを自力で解析することになります。

REST は HTTP と JSON で、三つとも解決します。

有効化の手順

PalWorldSettings.ini のあの一行に三項目を足し（編集時の落とし穴は設定の全項目解説へ）、サーバーを再起動します。

RESTAPIEnabled=True
RESTAPIPort=8212
AdminPassword="十分に長いパスワード"

AdminPassword は API のパスワードであるだけでなく、ゲーム内の管理者コマンドのパスワードでもあります。長いものにして、ServerPassword と同じにはしないでください。サーバーパスワードは友達に渡すもの、管理者パスワードは渡さないものです。

認証は HTTP Basic で、ユーザー名は常に admin、パスワードは上のものです。

破ってはいけない一線

8212 番ポートをインターネットに開けないでください。 公式の REST API リファレンスにある開発元自身の言葉で、この API は「インターネットに直接公開する設計ではなく」、公開すると「サーバーが不正に操作される可能性がある」とされています。サーバーの停止、プレイヤーのキック、その他多くのことができるのに、防御はただ一つの Basic 認証パスワードだけです。

正しい姿勢は、API はローカルホストだけで待ち受け、スクリプトは同じマシンから呼ぶこと。本当に遠隔管理が必要なら SSH トンネルを通すか、HTTPS と接続元 IP の許可リストを備えたリバースプロキシを前に置きます。セキュリティグループで 8212 が 0.0.0.0/0 に開いていたら、それは設定ミスです。

エンドポイント

すべて http://127.0.0.1:8212/v1/api/ 配下で、書き込み系は JSON ボディ付きの POST です。

よく使うものは curl でそのまま試せます。

PW='十分に長いパスワード'
API='http://127.0.0.1:8212/v1/api'

# 誰がオンラインか
curl -s -u "admin:$PW" "$API/players"

# 全員に告知
curl -s -u "admin:$PW" -X POST "$API/announce" \
     -H 'Content-Type: application/json' \
     -d '{"message":"Server restarts in 5 minutes"}'

# 強制保存
curl -s -u "admin:$PW" -X POST "$API/save"

# 60 秒後に正常終了。告知は自動
curl -s -u "admin:$PW" -X POST "$API/shutdown" \
     -H 'Content-Type: application/json' \
     -d '{"waittime":60,"message":"Server is going down in 60 seconds"}'

キックと BAN は名前ではなく userId

キックと BAN の対象はプレイヤーの userId で、ゲーム内の表示名ではありません。名前はいつでも変えられますが userId は変わりません。手順は二段階で、GET /players で相手の userId を調べ、それを /kick か /ban に渡します。

# まず調べる
curl -s -u "admin:$PW" "$API/players"
# それから BAN
curl -s -u "admin:$PW" -X POST "$API/ban" \
     -H 'Content-Type: application/json' \
     -d '{"userid":"steam_7656119xxxxxxxxxx","message":"Banned for griefing"}'

クロスプレイサーバーではこの点がいっそう重要です。Xbox と PS5 のプレイヤーには Steam ID が無く、古い KickPlayer <SteamID> コマンドは届きませんが、userId は全プラットフォーム共通の識別子です。

キックと BAN の違いは、キックがその接続を切るだけですぐ戻ってこられるのに対し、BAN は /unban するまで締め出す点です。

何に組み込むか

API の真価は curl を手で打つことではなく、スクリプトに組み込むことにあります。

• セーブを失わない定時再起動：告知、保存、終了、起動を一つの cron ジョブに繋ぎます。手順一式はメモリリークと定時再起動にあります。
• バックアップ前の書き込み：セーブディレクトリをコピーする前に POST /save を打てば、コピーするものが完全な状態になります（バックアップと復元）。
• フレームレート監視：/metrics を定期的に取得し、サーバー FPS が長時間 20 を下回ったら再起動の合図です。

よくある質問

パルワールドの専用サーバーでキックや BAN はどうやりますか？

REST API を有効にして AdminPassword を設定し、/players で相手の userId を調べ、それを /kick か /ban に渡します。対象は必ず userId です。表示名は変えられるので当てになりません。

パルワールドの RCON はまだ使えますか？

公式に非推奨で、将来のビルドで動作しなくなる予定です。加えて日本語などのプレイヤー名を切ってしまいます。新しく立てるサーバーは最初から REST API を使い、RCON に時間を使わないでください。

友達に管理を手伝ってもらうために REST API のポートを開けてもいいですか？

インターネットには開けないでください。守っているのはパスワード一つなのに、サーバーの停止、キック、ワールドの変更ができます。遠隔アクセスは SSH トンネルか、IP 許可リスト付きのリバースプロキシで行ってください。

サーバーを止めずに強制保存するには？

POST /save です。メモリ上のワールドを即座にディスクへ書き込ませ、そのあとセーブディレクトリをコピーします。書き込みの最中に当たる確率を下げるだけで無くすわけではないので、いちばん安全なバックアップは今でもサーバーを止めて取るものです。

ホスティングなら API に触れずに済む

上のすべての手順は、ホスティングされたサーバーではコンソールのボタンになります。KeepWorlds のパルワールド専用サーバーでは、マイサーバーのオンラインのプレイヤーパネルに今いる人が並び、荒らしはそのままキックか BAN で、userId を調べる必要はありません。BAN した相手は BAN 済みからいつでも解除できます。自動バックアップの前には API 経由の強制保存が入り、管理者パスワードはこちらで管理され、API 自体はインターネットから到達できません。