はじめに
⚠️ ご注意(必ずお読みください)
- 紹介するAPIはすべて Beta API で、Minecraftの更新で仕様の変更・削除が起こりえます。公式も「changes or even removal」の可能性を示しています。
- 実機確認は BDS 1.26.61.1 のみです。お使いの版では動作が異なることがあるので、導入前に必ず公式の変更履歴と型定義を確認し、ワールドをバックアップしてください。
統合版(Bedrock Edition)の専用サーバー(BDS)では、Script APIの @minecraft/server-net と @minecraft/server-admin で、外部サービスとの通信やサーバー管理ができます。どちらも専用サーバー専用で、クライアントやRealmsでは使えません。
@minecraft/server-net:HTTP通信、WebSocket、パケットイベント@minecraft/server-admin:キック、OP、プレイヤー転送、変数・秘密情報、参加前の制御
準備:manifestとNetの許可
manifest.jsonの例
依存関係(dependencies)は次のように書きます。版名は、npmの長い版名(2.12.0-beta.1.26.61-stable など)だと実機で拒否されました。サーバーが示す短い版名にしてください。
{
"format_version": 2,
"header": {
"name": "T6 Admin Sample",
"description": "server-net / server-admin sample",
"uuid": "(任意のUUID)",
"version": [1, 0, 0],
"min_engine_version": [1, 21, 0]
},
"modules": [
{
"type": "script",
"language": "javascript",
"uuid": "(別のUUID)",
"version": [1, 0, 0],
"entry": "scripts/main.js"
}
],
"dependencies": [
{ "module_name": "@minecraft/server", "version": "2.12.0-beta" },
{ "module_name": "@minecraft/server-net", "version": "1.0.0-beta" },
{ "module_name": "@minecraft/server-admin", "version": "1.0.0-beta" }
]
}
min_engine_version や UUID は自分の環境に合わせてください。server-net は server-admin を依存先にしています。また、ワールドでBeta APIsを有効にする必要があります。
【必須】permissions.json に @minecraft/server-net を追記する
server-net は初期状態では許可されていません。許可しないまま import すると、実機では次のエラーで読み込みに失敗しました。
requesting dependency on module [@minecraft/server-net] but it is not configured to use it.
そのため、専用サーバーの permissions.json に追記します。なお、ファイル名は permission.json ではなく、permissions.json(sが付く) です。
ファイルの場所(BDSを置いているフォルダーが基準です)
bedrock_server/
└─ config/ ← 初回起動で作成されるフォルダー
└─ default/
└─ permissions.json ← これを編集する
config フォルダーが無い場合は、一度サーバーを起動すると作られます(Microsoft Learn の説明)。
もともと書かれている内容(公式ドキュメントに載っている既定値。版によって違う可能性があります)
{
"allowed_modules": [
"@minecraft/server-gametest",
"@minecraft/server",
"@minecraft/server-ui",
"@minecraft/server-admin",
"@minecraft/server-editor"
]
}
書き足した後("@minecraft/server-editor" の行の末尾にカンマを足し、その次の行に追加します)
{
"allowed_modules": [
"@minecraft/server-gametest",
"@minecraft/server",
"@minecraft/server-ui",
"@minecraft/server-admin",
"@minecraft/server-editor",
"@minecraft/server-net"
]
}
追記する部分は "@minecraft/server-net" の1行と、直前の行のカンマだけです。最後の要素の後ろにカンマを付けないよう注意してください(JSONエラーになります)。編集後はサーバーを再起動します。
補足:全アドオンではなく、このアドオンだけに許可する方法
config/default に書くと、サーバー上のすべてのスクリプトが外部通信できるようになります。Microsoft Learn は、default は最小限にして、必要なモジュールだけ個別に許可することを強く推奨しています。その場合は、config の下にスクリプトモジュールのUUID(manifestの modules にある uuid。header のものではありません)と同名のフォルダーを作り、そこに permissions.json を置きます。
bedrock_server/
└─ config/
├─ default/
│ └─ permissions.json
└─ (modulesのuuid)/
└─ permissions.json ← 新規作成して中身を下記にする
{
"allowed_modules": [
"@minecraft/server",
"@minecraft/server-admin",
"@minecraft/server-net"
]
}
server-net:HTTP通信
HttpRequest を作り、http.request() で送ります。setMethod()(HttpRequestMethod)、setBody()(文字列)、addHeader(key, value)(値は文字列か SecretString)、setHeaders()(丸ごと置換)、setTimeout()(秒)が使えます。
Discord Webhook通知の例
プレイヤー参加時にDiscordへ知らせる例です。Webhook URLは秘密情報なので、公開するソースに直書きしないでください。
import { world } from "@minecraft/server";
import { http, HttpRequest, HttpRequestMethod } from "@minecraft/server-net";
async function notify(text) {
try {
const req = new HttpRequest("https://discord.com/api/webhooks/xxxx/yyyy");
req.setMethod(HttpRequestMethod.Post);
req.addHeader("Content-Type", "application/json");
req.setBody(JSON.stringify({ content: text }));
req.setTimeout(10);
const res = await http.request(req);
if (res.status < 200 || res.status >= 300) {
console.warn(`Discord error: ${res.status} ${res.body}`);
}
} catch (e) {
console.warn(`通信失敗: ${e.name} ${e.message}`);
}
}
world.afterEvents.playerJoin.subscribe((ev) => {
notify(`${ev.playerName} が参加しました`);
});
実機で確認: 存在しないWebhookへ送ると、例外は出ず status=404 と本文(Unknown Webhook)が返りました。4xxでもthrowされないので status の確認が必須で、通信失敗に備えて try/catch も併用します。
URIの制約とエラー(実機結果)
- 不正なURIは
new HttpRequest()の時点でMalformedUriErrorが同期的に投げられます(ftp://、file://、ホスト名なしのhttps://など)。 http://(TLSなし)も通り、http://httpbin.org/getは200でした。TLSOnlyErrorは出ませんでした。https://localhost/とhttps://127.0.0.1/はInternalHttpRequestErrorでした。一方http://127.0.0.1:19132/はブロックされず応答が返りました。宛先URLを外部入力で決める作りは避けてください。https://192.168.0.1/は1分以上待っても結果が出ず、挙動は確認できていません。
websocket とパケットイベントは未検証のため、詳細は公式の型一覧をご覧ください。
server-admin:変数・秘密情報
variables(設定値)と secrets(秘密情報)は、専用サーバーのJSON設定で定義します。
設定ファイルの置き場所
variables.json と secrets.json は、上の permissions.json と同じく config/default/(全モジュール共通)か、config/(modulesのuuid)/(個別)に置きます(Microsoft Learn の説明)。
bedrock_server/
└─ config/
├─ default/
│ ├─ permissions.json
│ ├─ variables.json
│ └─ secrets.json
└─ (modulesのuuid)/
├─ permissions.json
├─ variables.json
└─ secrets.json
- community docs には
config/<pack_id>/という表記もあり、表記ゆれがあります。 variables.jsonは{ "mobSpawnRate": 22 }のような任意のJSON、secrets.jsonは値がすべて文字列の{ "secretToken": "..." }形式です。permissions.jsonの書き方は前節のとおりです。@minecraft/server-adminは既定で許可されていますが、@minecraft/server-netは含まれていません。
確認できていないこと: 私の実験では、config にダミー値を置いても variables.names は空、secrets.get は undefined でした。置き場所や形式のどこが原因か、切り分けられていません。上の配置は公式ドキュメントの記述であり、実機では読み込みを確認できていません。
コード例
import { variables, secrets } from "@minecraft/server-admin";
console.warn(variables.names);
const rate = variables.get("mobSpawnRate");
const token = secrets.get("secretToken"); // SecretString か undefined
SecretString は中身をスクリプトに見せず、addHeader に渡すと実行時に値へ解決されます。undefined のまま渡すと TypeError になるので、先に存在確認をしてください。
server-admin:参加前の制御(asyncPlayerJoin)
beforeEvents.asyncPlayerJoin は、プレイヤーが入る前の参加待ちの間に呼ばれ、非同期で許可・拒否を決められます。
import { world } from "@minecraft/server";
import { beforeEvents } from "@minecraft/server-admin";
world.afterEvents.worldLoad.subscribe(() => {
beforeEvents.asyncPlayerJoin.subscribe(async (ev) => {
const ok = true; // 外部APIで照会するなど
if (ok) ev.allowJoin();
else ev.disallowJoin("参加できません");
});
});
実機で確認した点です。
world.beforeEventsではなく server-admin 側にあります。- スクリプト読み込み直後の
subscribeはReferenceError(early execution)。worldLoadの中なら登録できました。 - イベントは
allowJoin、disallowJoin、disconnect、isValid、persistentId、name、splitScreenSlotを持ちます。 - 3秒後の
allowJoin()で参加でき、40秒待っても参加できました(上限は未確認)。 disallowJoin("理由")の理由文字列はクライアントに届きました。disconnectは公式上、disallowJoinへの置き換えが推奨されています。
server-admin:キック・OP・転送
以下は公式の型定義の内容で、実機検証はしていません。いずれも restricted-execution モードと early-execution モードでは呼べません(worldLoad 後に使います)。
| 関数 | 内容 |
|---|---|
kickPlayer(player, reason?) |
プレイヤーをキック。CannotKickPlayerError などを投げうる |
opPlayer(player) |
OP権限を付与。すでにOPなら PlayerAlreadyOpError |
deopPlayer(player) |
OP権限を剥奪。CannotDeopPlayerError というエラー型が存在(引数の詳細は未確認) |
transferPlayer(player, options) |
別サーバーへ転送 |
transferPlayer の options は2種類です。
TransferPlayerIpPortOptions:hostname(string)とport(number)TransferPlayerNetherNetOptions:netherNetId(string)
import { kickPlayer, transferPlayer } from "@minecraft/server-admin";
// 例:ルール違反でキック(呼び出し元は自分のイベントに合わせる)
function punish(player) {
try { kickPlayer(player, "ルール違反です"); }
catch (e) { console.warn(`${e.name}: ${e.message}`); }
}
// 例:ロビーサーバーへ転送
function toLobby(player) {
transferPlayer(player, { hostname: "lobby.example.com", port: 19132 });
}
kickPlayer は権限者などで CannotKickPlayerError になりうるため、try/catch を推奨します。
まとめ
- server-net を使うには、
config/default/permissions.json(またはconfig/(modulesのuuid)/permissions.json)のallowed_modulesに"@minecraft/server-net"を追記する必要があります。追記しないと読み込みエラーになります。 - server-net は 非2xxが例外にならないので、
statusとtry/catchの両方が必要です。 - 宛先URLを外部入力で決めないでください。
- 変数・秘密情報の配置は公式の説明どおりですが、実機での読み込みは未確認です。
- 参加制御は
asyncPlayerJoin(worldLoad後に登録)。キック・転送はworldLoad後に呼びます。 - Beta APIなので、アップデートのたびに仕様を確認してください。
参考
- Scripting Bedrock Dedicated Server(Microsoft Learn)
- Bedrock Wiki:script-net
- Secrets and Variables(Script API docs)
- @minecraft/server-net
- @minecraft/server-admin
- kickPlayer
- transferPlayer
- opPlayer
※この文章はClaude AIによって作成されました。