BLOG

server-net / server-admin入門:Discord通知とログイン制御

2026年11月5日 ・ 約10分

はじめに

⚠️ ご注意(必ずお読みください)

  • 紹介する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なので、アップデートのたびに仕様を確認してください。

参考

※この文章はClaude AIによって作成されました。

← ブログ一覧へ