【マイクラ】scriptコマンドの使い方・構文・スクリプトデバッグを解説【統合版】

この記事はマイクラ統合版（Bedrock Edition）のスクリプト開発者向けです
Java版では使えないコマンドなので注意してください
/script はJavaScriptをその場で実行するコマンドではなく、デバッグ・診断・プロファイル取得用のコマンドです
チート有効化と管理者権限が必要です

こんにちは。ゆずかきです。

マイクラ統合版でアドオン制作やビヘイビアーパック制作をしていると、たまに見かけるのが /script コマンドです。

ただ、このコマンドは普通のサバイバル攻略で使うコマンドではありません。
/give や /tp みたいにゲーム内へ直接影響を出すというより、スクリプトのデバッグ・負荷確認・診断情報の取得に使う、かなり開発者寄りのコマンドです。

筆者も最初に見た時、

「/script って、チャット欄からJavaScriptを書いて実行できるコマンドなのかな？」

と思ったのですが、これは違います。

統合版のスクリプトは、基本的にビヘイビアーパック内のJavaScriptファイルとして読み込ませます。
そのうえで、/script コマンドは、VS Codeのデバッガへ接続したり、処理が重い箇所を調べたり、診断情報を取ったりするために使うものです。

この記事では、マイクラ統合版の scriptコマンドの使い方・構文・スクリプトデバッグの流れを、実際に作業する順番で整理していきますね。

この記事を読めば、次のことが分かります。

/script コマンドで何ができるのか分かります👍

debugger、profiler、diagnostics、watchdog の違いが分かります👌

VS Codeでスクリプトデバッグする時の流れが分かります

/scriptevent や /reload との違いも整理できます(^^♪

それでは、やっていきましょう！

※統合版のScript APIはバージョン更新で仕様が変わることがあるため、制作中のワールドやアドオンでは、必ず自分の利用バージョンでも確認してください。
※本記事では「統合版」「Bedrock Edition」は同じ意味で扱います。

1. scriptコマンドとは
2. scriptコマンドを使う前の前提条件
3. scriptコマンドの構文一覧
4. debugger系コマンドの使い方
5. profiler系コマンドの使い方
6. diagnostics系コマンドの使い方
7. watchdog exportstatsの使い方
8. VS Codeでスクリプトデバッグする流れ
9. Bedrock Dedicated Serverで使う時の注意点
10. scriptevent・reloadとの違い
11. よくあるエラーとチェックポイント
12. まとめ
13. 参考文献

この記事で分かること
・マイクラ統合版の /script コマンドの基本
・デバッガ接続、プロファイラ、診断、Watchdog統計の使い分け
・スクリプト開発で詰まりやすいポイントと対策

1. scriptコマンドとは

/script コマンドは、マイクラ統合版のスクリプト開発を補助するためのデバッグ系コマンドです。

通常のプレイで使うというより、ビヘイビアーパックに入れたJavaScriptが、

正しく読み込まれているか
エラーが出ていないか
処理が重くなっていないか
VS Codeのデバッガと接続できるか
スクリプト実行環境の統計を取れるか

こういうことを確認するために使います。

つまり、/script は、

アドオン制作者・配布ワールド制作者・統合版サーバー管理者向けのコマンド

という理解で大丈夫です。

サバイバルで便利装置を作る時に直接使うコマンドではないので、普通に遊ぶだけなら知らなくても困りません。
ただ、統合版でScript APIを使ったアドオン制作をするなら、知っておくとデバッグがかなり楽になります。

`/script` でできること

/script コマンドで扱う内容は、大きく分けて4つです。

種類	主な用途	使う場面
debugger	VS Codeなどのデバッガ接続	ブレークポイントで止めて中身を見る時
profiler	スクリプトの処理負荷を記録	重い処理を探す時
diagnostics	診断情報の取得	不具合調査・実行状態確認
watchdog	Watchdog関連の統計出力	メモリ使用量や実行環境の統計確認

ここで一番大事なのは、/script はスクリプト本文を書く場所ではないということです。

例えば、チャット欄に、

/script console.log("test")

みたいに書いても、JavaScriptを直接実行できるわけではありません。

スクリプト本体は、ビヘイビアーパックの中に、たとえば scripts/main.js のような形で用意します。
/script コマンドは、その読み込まれたスクリプトを調査・接続・計測するための道具と考えてくださいね。

2. scriptコマンドを使う前の前提条件

/script コマンドを使う前に、まず前提条件を確認しておきましょう。
ここを飛ばすと、コマンドを入力しても「権限がない」「認識されない」「接続できない」などで詰まりやすいです。

1. マイクラ統合版であること

/script は統合版向けのコマンドです。
Java版のコマンドではありません。

Java版でコマンドを打っても、同じようには使えないので注意してください。

本記事で扱う対象は、主に下記です。

Windows版のMinecraft Bedrock Edition
Minecraft Preview
Bedrock Dedicated Server
統合版のアドオン開発環境

Switch・スマホ・コンソール版でも統合版ではありますが、スクリプトデバッグを本格的に行うなら、基本的にはWindows版＋VS Codeの環境が扱いやすいです。

2. チートを有効にする

/script コマンドは、チート有効化が必要です。

ワールド作成時、またはワールド設定から、チートの実行をオンにしておきましょう。

コマンド入力自体はチャット欄やサーバーコンソールから行いますが、チートが無効だと使えない場合があります。

3. 管理者権限が必要

/script は、統合版のコマンド権限としてはAdmin（管理者）権限が必要です。

マルチプレイやサーバーで使う場合は、プレイヤーがOP相当の権限を持っているか確認してください。

「コマンドは合っているのに動かない」場合、構文ミスよりも権限不足が原因のことも多いです。

4. スクリプト入りのビヘイビアーパックを用意する

/script コマンドは、スクリプトのデバッグや診断を行うためのものです。
そのため、実際に確認したいスクリプトが入ったビヘイビアーパックが必要です。

統合版のScript APIでは、基本的にビヘイビアーパックの manifest.json に、script モジュールとエントリーファイルを指定します。

例としては、こんな形です。

{
  "format_version": 2,
  "header": {
    "name": "Script Test Pack",
    "description": "script command test",
    "uuid": "00000000-0000-0000-0000-000000000001",
    "version": [1, 0, 0],
    "min_engine_version": [1, 21, 100]
  },
  "modules": [
    {
      "type": "script",
      "language": "javascript",
      "entry": "scripts/main.js",
      "uuid": "00000000-0000-0000-0000-000000000002",
      "version": [1, 0, 0]
    }
  ],
  "dependencies": [
    {
      "module_name": "@minecraft/server",
      "version": "2.1.0"
    }
  ]
}

※UUIDは必ず自分で生成したものに置き換えてください。
※バージョン番号は、使うMinecraft本体とScript APIの対応状況に合わせて調整してください。

5. スクリプトはJavaScriptとして読み込む

統合版のスクリプトは、ビヘイビアーパック内でJavaScriptとして読み込ませます。

たとえば、上記の manifest.json なら、次のファイルを用意します。

behavior_packs
└─ Script Test Pack
   ├─ manifest.json
   └─ scripts
      └─ main.js

main.js の中身は、たとえば簡単に書くならこのような形です。

import { world } from "@minecraft/server";

world.afterEvents.playerSpawn.subscribe((event) => {
  const player = event.player;
  player.sendMessage("スクリプトが読み込まれました！");
});

このように、スクリプト本体はファイルとして用意します。
そして、その実行状態を確認するために /script コマンドを使う、という順番です。

3. scriptコマンドの構文一覧

まず、/script コマンドの主な構文を一覧で整理します。

環境やバージョンによって補完表示が少し変わる可能性はありますが、現在確認できる主な構文は下記です。

コマンド	内容	主な用途
`/script debugger connect [host] [port]`	デバッガへ接続	マイクラ側からVS Codeへ接続する
`/script debugger listen <port>`	デバッグ接続を待ち受け	BDS側でポートを開いて待つ
`/script debugger close`	デバッガ接続を閉じる	デバッグ接続を終了する
`/script profiler start`	プロファイル計測開始	重いスクリプト処理の調査
`/script profiler stop`	プロファイル計測終了	計測結果の出力
`/script diagnostics startcapture`	診断キャプチャ開始	実行状態の調査
`/script diagnostics stopcapture`	診断キャプチャ終了	診断データの取得完了
`/script watchdog exportstats`	Watchdog統計を出力	スクリプト実行環境やメモリ関連の調査

コマンドだけ見ると難しく見えますが、実際に使う時は目的別に分けると分かりやすいです。

VS Codeで止めながら確認したい → debugger
どこが重いか調べたい → profiler
実行状態をまとめて調べたい → diagnostics
Watchdogまわりの統計を見たい → watchdog exportstats

まずはこの整理で十分です。

引数の見方

構文に出てくる [host] と [port] は、デバッガ接続先を指定するための値です。

host：接続先のホスト名、またはIPアドレス
port：接続に使うポート番号

角括弧 [ ] で書かれているものは、省略できる場合があります。
一方で、<port> のように山括弧で書かれるものは、基本的に必要な引数です。

VS CodeのMinecraft Bedrock Debuggerでは、デフォルトのデバッグ用ポートとして 19144 がよく使われます。
初心者の方は、まず 19144 を基準に覚えると良いです。

4. debugger系コマンドの使い方

ここからは、各コマンドを順番に見ていきます。
まずは、debugger 系です。

debugger 系は、VS Codeなどのデバッガとマイクラ統合版のスクリプト実行環境を接続するために使います。

`/script debugger connect`

/script debugger connect

これは、マイクラ側からデバッガへ接続するためのコマンドです。

Windows版のMinecraft Bedrockを開き、同じPC上のVS CodeでMinecraft Bedrock Debuggerを待機させている場合、まず試すのはこれです。

VS Code側が待機状態になっていれば、マイクラ側でこのコマンドを実行した時にデバッガへ接続されます。
成功すると、デバッガ接続に成功した旨のメッセージが出ます。

hostとportを指定する場合

/script debugger connect 127.0.0.1 19144

接続先を明示したい場合は、ホストとポートを指定します。

同じPC上で動かしているなら、127.0.0.1 や localhost を使う場面があります。
別PCやサーバーに接続する場合は、その環境に合わせてIPアドレスを指定します。

ただし、別端末へ接続する場合は、ファイアウォールやネットワーク設定の影響を受けます。
「コマンドは成功しそうなのに接続できない」時は、まずポート開放や同一ネットワークかどうかを確認しましょう。

`/script debugger listen <port>`

/script debugger listen 19144

これは、マイクラ側・サーバー側がデバッグ接続を待ち受けるためのコマンドです。

特にBedrock Dedicated Serverでは、この形でサーバー側を待機状態にして、VS Codeから接続する流れになります。

クライアント版のマイクラをVS Codeへ接続する場合と、BDSをVS Codeから覗きに行く場合で、向きが少し変わるイメージです。

ここは混乱しやすいので、下のように覚えておくと楽です。

環境	よく使う流れ	覚え方
Windows版の統合版クライアント	VS Codeを待機 → マイクラで `/script debugger connect`	マイクラからVS Codeへ接続
Bedrock Dedicated Server	サーバーで `/script debugger listen 19144` → VS Codeから接続	サーバーが待つ

`/script debugger close`

/script debugger close

これは、デバッガ接続を閉じるコマンドです。

デバッグ作業を終える時や、接続が変な状態になった時に使います。
再接続したい時は、一度 close してから、VS Code側とマイクラ側の状態を整えて接続し直すと安定しやすいです。

debugger系を使う時の注意点

debugger 系は便利ですが、接続設定で詰まりやすいです。
特にWindows版で同じPC上のVS Codeへ接続する場合、環境によってはループバック通信の許可が必要になることがあります。

また、複数のスクリプト入りビヘイビアーパックを同時に読み込んでいると、どのスクリプトモジュールをデバッグするのか分かりにくくなります。
その場合は、VS Codeの launch.json 側で targetModuleUuid を指定すると、対象を絞りやすいです。

体験ベースの注意点
デバッガ接続まわりは、コマンド構文よりも「VS Code側が待機しているか」「ポート番号が合っているか」「対象のビヘイビアーパックを開いているか」で詰まりやすいです。
コマンドだけ何度も打つより、まず接続の向きとポート番号を確認しましょう。

5. profiler系コマンドの使い方

次は、profiler 系コマンドです。

profiler は、スクリプトの処理負荷を調べるために使います。
簡単に言うと、どの処理に時間がかかっているのかを調べるための計測機能です。

スクリプト制作では、最初は正常に動いていても、

毎tickで重い処理を回している
たくさんのエンティティを毎回検索している
配列やオブジェクトを大量に作り続けている
イベント登録を想定以上に増やしている

こういう書き方をすると、ワールドが重くなったり、Watchdogに止められたりすることがあります。
その時に使うのが profiler です。

`/script profiler start`

/script profiler start

これは、スクリプトのプロファイル計測を開始するコマンドです。

「今から重さを測るよ」という開始ボタンのようなものですね。

負荷を調べたい場合は、まずこのコマンドを実行します。
その後、実際にワールド内で重くなる操作を再現します。

たとえば、

スクリプトで大量のエンティティを処理する
カスタムUIを開く
カスタムコマンドを実行する
プレイヤーが特定エリアに入る
毎tick処理が走る場面を再現する

このような操作を行います。

`/script profiler stop`

/script profiler stop

これは、プロファイル計測を終了するコマンドです。

start で計測を開始し、問題の動作を再現したら、stop で終了します。
計測結果として、Minecraftのログフォルダにタイムスタンプ付きの .cpuprofile ファイルが生成されます。
GDK版のMinecraftでは、たとえば下記のような場所を確認します。

%APPDATA%\Minecraft Bedrock\logs\

このファイルを確認することで、どの処理に時間がかかっているかを調べられます。

profilerの使い方の流れ

実際の流れとしては、下記のように使います。

/script profiler start

👇重い動作を再現する

/script profiler stop

この順番です。

profilerを見る時の考え方

プロファイラを使う時は、いきなり全部を完璧に読もうとしなくて大丈夫です。
まず見るべきなのは、明らかに時間を使っている処理です。

特に、下記のような処理は重くなりやすいです。

system.runInterval で毎tick実行している処理
dimension.getEntities() を広範囲で頻繁に呼ぶ処理
プレイヤー人数やエンティティ数に比例して増える処理
毎回大量のブロックを取得する処理
イベント内でさらに重いループを回す処理

プロファイラで重い場所が見えたら、まずは処理頻度を下げるのがおすすめです。

たとえば、毎tick実行している処理を、5tickに1回、20tickに1回へ減らすだけでもかなり変わることがあります。

筆者メモ
スクリプトの重さ対策は、「1回の処理を軽くする」より先に「毎tickやらなくていい処理を減らす」ほうが効果を感じやすいです。
常時監視したくなる気持ちは分かりますが、全部を毎tick見る必要はないことが多いです。

6. diagnostics系コマンドの使い方

次は、diagnostics 系です。

diagnostics は、スクリプトや実行環境の診断情報を取るためのコマンドです。
プロファイラが「処理の重さを見る」目的なら、diagnosticsはもう少し広く、実行状態の情報を集める目的で使います。

`/script diagnostics startcapture`

/script diagnostics startcapture

これは、診断情報のキャプチャを開始するコマンドです。

不具合が起きる直前、または再現手順を始める前に実行します。

`/script diagnostics stopcapture`

/script diagnostics stopcapture

これは、診断情報のキャプチャを終了するコマンドです。

開始後に問題の動作を再現し、必要な情報を取り終えたら実行します。

diagnosticsを使う場面

diagnostics は、以下のような時に使います。

スクリプトの不具合が再現する場面を調べたい
実行環境の状態をまとめて確認したい
サーバーや配布ワールドの問題調査をしたい
エラーの前後で何が起きているか確認したい

コマンドの使い方自体はシンプルです。

/script diagnostics startcapture

👇問題の動作を再現する

/script diagnostics stopcapture

この流れです。

diagnosticsとprofilerの違い

初心者さんが混乱しやすいので、違いを整理しておきます。

項目	profiler	diagnostics
主な目的	処理負荷の調査	実行状態の診断
見るもの	どの処理が重いか	スクリプト環境の状態
使うタイミング	重い処理を探す時	不具合の再現調査
初心者向けの覚え方	重さを見る	状態を見る

迷ったら、

動作が重い → profiler
原因不明の不具合 → diagnostics

この使い分けで大丈夫です。

7. watchdog exportstatsの使い方

watchdog は、スクリプトの暴走や過負荷からゲームやサーバーを守るための仕組みです。

スクリプトが重すぎる、無限ループしている、メモリを使いすぎている、こういった状態になると、Watchdogがスクリプト実行環境を止めることがあります。

`/script watchdog exportstats`

/script watchdog exportstats

このコマンドは、スクリプト実行環境に関する統計情報を出力するために使います。

主に、下記のような情報を調べたい時に使います。

スクリプト実行環境の状態
メモリ使用量まわりの情報
スクリプトランタイムの挙動やメモリ消費に関する情報
Watchdogによる停止原因を調べる手がかり

Watchdogエラーが出る時の考え方

スクリプト制作中に怖いのが、Watchdog系のエラーです。

たとえば、無限ループを書いてしまったり、大量の処理を毎tick走らせたりすると、ワールドが固まる前にスクリプトが止められることがあります。

これは一見すると邪魔に見えますが、実際にはワールドやサーバーを守るための安全装置です。

Watchdogで止まりやすい書き方

特に注意したいのは、下記のような書き方です。

while (true) {
  // 終わらない処理
}

これは分かりやすい無限ループなので避けやすいです。
ただ、実際にやりがちなのは、下記のような「意図せず重くなる処理」です。

import { system, world } from "@minecraft/server";

system.runInterval(() => {
  for (const player of world.getPlayers()) {
    const entities = player.dimension.getEntities({
      location: player.location,
      maxDistance: 100
    });

    for (const entity of entities) {
      // 全エンティティに対して重い処理
    }
  }
}, 1);

この例では、毎tick、全プレイヤー周辺のエンティティを大量に取得しています。
小規模なら動いても、プレイヤーやエンティティが増えると一気に重くなります。

軽くするなら処理頻度を下げる

まずは、毎tick実行をやめるのが分かりやすいです。

import { system, world } from "@minecraft/server";

system.runInterval(() => {
  for (const player of world.getPlayers()) {
    const entities = player.dimension.getEntities({
      location: player.location,
      maxDistance: 30
    });

    for (const entity of entities) {
      // 必要な処理だけ行う
    }
  }
}, 20);

この例では、1tickごとではなく20tickごと、つまり約1秒ごとの処理にしています。
これだけでも、負荷がかなり変わることがあります。

注意
Watchdog関連は、ゲーム本体・サーバー設定・読み込んでいるアドオンの構成によって挙動が変わります。
配布ワールドやサーバー運用で使う場合は、実際の環境で必ず確認してくださいね。

8. VS Codeでスクリプトデバッグする流れ

ここからは、実際にVS Codeでマイクラ統合版のスクリプトデバッグを行う流れをまとめます。

細かい環境差はありますが、Windows版のMinecraft Bedrockで開発するなら、この流れが基本になります。

1. Minecraft Bedrock Debuggerを入れる

まず、VS Codeに Minecraft Bedrock Debugger 拡張機能を入れます。

これは、Mojang Studiosが公開しているVS Code拡張機能です。
スクリプトのブレークポイント、ステップ実行、ローカル変数の確認、パフォーマンス診断などに使えます。

2. ビヘイビアーパックのフォルダをVS Codeで開く

次に、スクリプト入りのビヘイビアーパックフォルダをVS Codeで開きます。

Windows版の場合、GDK版では、開発用ビヘイビアーパックは下記のような場所にあります。

%APPDATA%\Minecraft Bedrock\users\shared\games\com.mojang\development_behavior_packs

Minecraft Previewや従来のUWP版では、下記のような場所を使うことがあります。

%LOCALAPPDATA%\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs

この中に自分のビヘイビアーパックを置くか、自分で管理しているプロジェクトフォルダをVS Codeで開いて作業します。

3. `.vscode/launch.json` を用意する

ビヘイビアーパックのルートに .vscode フォルダを作り、その中に launch.json を用意します。

JavaScriptをそのまま使う場合の例です。

{
  "version": "0.3.0",
  "configurations": [
    {
      "type": "minecraft-js",
      "request": "attach",
      "name": "Debug with Minecraft",
      "mode": "listen",
      "localRoot": "${workspaceFolder}/",
      "port": 19144
    }
  ]
}

TypeScriptからJavaScriptへビルドしている場合は、sourceMapRoot や generatedSourceRoot を設定する流れになります。
最初はJavaScript直書きで動作確認してから、慣れてきたらTypeScript構成にするのも良いと思います。

4. VS Code側でデバッグ待機する

VS Codeの実行メニューから、Debug with Minecraft を開始します。

この時、VS Code側が接続待機状態になります。

5. マイクラでワールドを開く

スクリプト入りのビヘイビアーパックを適用したワールドを開きます。

ワールド側で、

チート有効
対象ビヘイビアーパックを適用済み
必要な実験設定をオン
スクリプトが読み込まれている

このあたりを確認しましょう。

6. マイクラ側で接続コマンドを打つ

VS Code側を待機状態にしたら、マイクラ内で下記を実行します。

/script debugger connect

接続に成功すると、VS Code側でデバッグできるようになります。

7. ブレークポイントを置いて動作確認する

VS Codeで main.js などのスクリプトファイルを開き、止めたい行の左側をクリックしてブレークポイントを置きます。

その後、マイクラ側で対象の処理を実行します。

たとえば、プレイヤーがスポーンした時の処理を見たいなら、ワールドに入り直す。
チャット送信イベントを見たいなら、チャットを送る。
カスタムコマンドを見たいなら、そのコマンドを実行する。

処理が通れば、VS Code側で止まって、変数の中身を見られます。

8. デバッグ後は接続を閉じる

作業が終わったら、必要に応じて接続を閉じます。

/script debugger close

デバッガ接続が不安定になった時も、一度閉じてから接続し直すと直ることがあります。

VS Codeデバッグでよく詰まるところ

筆者が初心者さんに説明するなら、ここはかなり大事です。
構文より、環境設定で詰まることが多いです。

VS Codeでビヘイビアーパックのルートを開いていない
launch.json の localRoot が違う
ポート番号が合っていない
Minecraft側がループバック通信できない
ワールドに古いビヘイビアーパックが適用されたまま
manifest.json のUUIDやバージョン指定が間違っている
スクリプトファイルのパスと entry が一致していない

/script debugger connect だけを何回打っても直らない時は、だいたいこのあたりに原因があります。

おすすめの確認順
1. ワールドに対象ビヘイビアーパックが入っているか
2. main.js が本当に読み込まれているか
3. VS Codeがデバッグ待機状態か
4. ポート番号が 19144 で揃っているか
5. ループバック許可やファイアウォールで止まっていないか

9. Bedrock Dedicated Serverで使う時の注意点

Bedrock Dedicated Server、いわゆるBDSでスクリプトデバッグをする場合、通常のWindows版クライアントとは少し考え方が変わります。

BDSでは、サーバー側でデバッグ接続を許可する設定が必要です。

server.propertiesの設定を確認する

BDSでは、server.properties にデバッグ接続関連の設定があります。

代表的なのは下記です。

allow-outbound-script-debugging=true
allow-inbound-script-debugging=true
force-inbound-debug-port=19144

設定名の意味は、簡単に言うとこうです。

設定	意味	確認ポイント
`allow-outbound-script-debugging`	サーバーから外へデバッグ接続する許可	`/script debugger connect`を使う場合に関係
`allow-inbound-script-debugging`	外部からサーバーへデバッグ接続する許可	`/script debugger listen`を使う場合に関係
`force-inbound-debug-port`	待ち受けポートの固定	ポートを固定して運用したい時に便利

デバッグを許可していない状態だと、コマンドを打っても接続できないことがあります。
BDSで使う場合は、まず server.properties を確認しましょう。

BDSでの基本的な流れ

BDSでデバッグする時の流れは、下記のようになります。

BDSの server.properties でデバッグ接続を許可する
スクリプト入りのビヘイビアーパックをワールドに適用する
サーバーを起動する
サーバーコンソールで下記を実行する

script debugger listen 19144

VS Code側からポート 19144 へ接続する

チャット欄で実行する時は先頭に / を付けますが、サーバーコンソールでは環境によって / なしで入力することがあります。
ここは自分の起動環境に合わせてください。

公開サーバーでの注意

デバッグ用ポートを開けるということは、外部から接続できる入口を作るということです。

身内検証やローカル環境ならまだ良いですが、公開サーバーで何も考えずに開けっぱなしにするのはおすすめしません。

必要な時だけ有効にする
ポート開放範囲を確認する
ファイアウォールで接続元を制限する
デバッグ終了後は設定を戻す

このあたりは必ず意識してくださいね。

10. scriptevent・reloadとの違い

/script と混同しやすいコマンドに、/scriptevent と /reload があります。
ここはかなり間違えやすいので、分けて整理しておきます。

`/script` はデバッグ・診断用

/script は、この記事で解説している通り、スクリプトのデバッグ・プロファイル・診断・Watchdog統計に使うコマンドです。

/script profiler start
/script profiler stop
/script debugger connect

こういう開発補助が目的です。

`/scriptevent` はスクリプトへイベントを送るコマンド

/scriptevent は、スクリプトへイベントIDとメッセージを送るためのコマンドです。

たとえば、コマンド側からスクリプトへ合図を送って、特定の処理を動かしたい時に使います。

イメージとしては、

/scriptevent yuzukaki:test hello

このように実行し、スクリプト側で受け取ります。

import { system } from "@minecraft/server";

system.afterEvents.scriptEventReceive.subscribe((event) => {
  if (event.id === "yuzukaki:test") {
    event.sourceEntity?.sendMessage(`受け取ったメッセージ: ${event.message}`);
  }
});

/scriptevent は、コマンドブロックや関数ファイルからスクリプトへ処理を渡したい時に便利です。

`/reload` は関数・スクリプトファイルの再読み込み

/reload は、ビヘイビアーパック内の関数ファイルやスクリプトファイルを再読み込みするコマンドです。

/reload

スクリプトを書き換えた後に、ワールドを開き直さず反映を試したい時に使う場面があります。

ただし、すべての変更が期待通りに反映されるとは限りません。
manifest.json の変更や依存関係の変更などは、ワールド再起動やパックの付け直しが必要になることもあります。

違いを表で整理

コマンド	役割	使う場面
`/script`	デバッグ・診断・計測	VS Code接続、負荷確認、不具合調査
`/scriptevent`	スクリプトへイベント送信	コマンドからScript APIへ合図を送る
`/reload`	関数・スクリプトファイル再読み込み	ファイル変更後の反映確認

特に、/script と /scriptevent は名前が似ています。
でも役割は全然違います。

/script：開発者が調査するためのコマンド
/scriptevent：ゲーム内コマンドからスクリプトへ合図を送るコマンド

この違いを覚えておくと、かなり理解しやすくなります。

11. よくあるエラーとチェックポイント

ここでは、/script コマンドやスクリプトデバッグで詰まりやすいポイントをまとめます。

「コマンドが動かない」「デバッガ接続できない」「スクリプトが読み込まれない」という時は、ここを順番に見てください。

コマンドが認識されない

まず確認することは、統合版で実行しているかどうかです。

[ ] Java版で実行していないか？
[ ] 統合版の対象バージョンか？
[ ] チートが有効か？
[ ] 管理者権限があるか？

Java版では使えないので、そこは最初に確認しましょう。

権限不足で実行できない

/script は管理者権限が必要です。

マルチプレイやBDSで使う場合は、プレイヤー権限を確認してください。

[ ] 自分がOP権限を持っているか？
[ ] サーバー設定でコマンド実行が許可されているか？
[ ] BDSのコンソールから実行する必要がないか？

権限不足の時は、構文が正しくても動きません。

スクリプトが読み込まれていない

デバッガ接続以前に、スクリプト自体が読み込まれていないケースもあります。

[ ] ワールドにビヘイビアーパックを適用しているか？
[ ] manifest.json の type が script になっているか？
[ ] entry のパスが実ファイルと一致しているか？
[ ] scripts/main.js などのファイル名を間違えていないか？
[ ] UUIDが重複していないか？
[ ] 依存関係の @minecraft/server バージョンが適切か？

特に、entry のパス違いは本当によくあります。

"entry": "scripts/main.js"

と書いているのに、実際のフォルダ名が script/main.js になっていると読み込まれません。
scripts と script の違いだけでも詰まるので注意です。

VS Codeへ接続できない

/script debugger connect で接続できない時は、下記を確認します。

[ ] VS Code側でデバッグ開始しているか？
[ ] launch.json の port が合っているか？
[ ] マイクラ側の接続先ポートも同じか？
[ ] 同じPC上ならループバック通信が許可されているか？
[ ] ファイアウォールでブロックされていないか？
[ ] VS Codeでビヘイビアーパックのルートを開いているか？

デバッグ接続は、コマンドよりも周辺設定が大事です。
ここは焦らず、1つずつ潰しましょう。

BDSでlistenできない

BDSで /script debugger listen を使う場合は、サーバー側設定を確認します。

[ ] allow-inbound-script-debugging が有効か？
[ ] force-inbound-debug-port と実際のポートが合っているか？
[ ] サーバーのファイアウォールでポートが開いているか？
[ ] 公開サーバーなら接続元制限をしているか？

BDSはローカルのクライアント版よりも、ネットワーク設定の影響を受けます。

Watchdogで止まる

Watchdogでスクリプトが止まる場合は、重い処理や無限ループを疑います。

[ ] while(true) のような終了しない処理がないか？
[ ] 毎tickで重い処理を実行していないか？
[ ] エンティティ検索範囲が広すぎないか？
[ ] 大量のブロック取得を頻繁に行っていないか？
[ ] イベント登録を重複させていないか？
[ ] 配列やオブジェクトを溜め込み続けていないか？

対策としては、まず処理頻度を下げるのが分かりやすいです。

// 重くなりやすい例：毎tick
system.runInterval(() => {
  // 処理
}, 1);

// 改善例：20tickごと
system.runInterval(() => {
  // 処理
}, 20);

バージョン差で動かない

統合版のScript APIは、バージョン更新の影響を受けます。

特に、@minecraft/server のバージョン、Beta APIか安定版APIか、ワールドの実験設定の有無で挙動が変わります。

1.21.100では、カスタムコマンド関連やプレイヤーのコマンド権限関連が安定版APIへ移行しています。
ただし、これは /script コマンドそのものというより、Script API側の機能更新です。

そのため、古い記事や古いサンプルコードを使う時は、下記を必ず確認しましょう。

[ ] サンプルコードのMinecraftバージョン
[ ] @minecraft/server のバージョン
[ ] Beta API前提か、安定版API前提か
[ ] 今の自分の環境で同じAPIが使えるか

古いコードをそのまま貼ると、メソッド名が変わっていたり、安定版で使えないAPIが混ざっていたりすることがあります。

最後のチェックリスト

どうしても動かない時は、下記を順番に確認してください。

[ ] 統合版で実行している
[ ] チートが有効
[ ] 管理者権限がある
[ ] ビヘイビアーパックがワールドに適用されている
[ ] manifest.json の entry が正しい
[ ] スクリプトファイル名とフォルダ名が一致している
[ ] VS Codeで対象フォルダを開いている
[ ] launch.json のポート番号が正しい
[ ] ループバック通信やファイアウォールで止まっていない
[ ] BDSなら server.properties でデバッグ接続を許可している

ここまで見れば、かなり原因を絞れると思います。

12. まとめ

以上、マイクラ統合版の /script コマンドの使い方・構文・スクリプトデバッグについて解説しました。

最後に要点を整理します。

/script は統合版のスクリプト開発者向けコマンド
JavaScriptをチャット欄から直接実行するコマンドではない
主な用途はデバッグ接続・プロファイル取得・診断・Watchdog統計
チート有効化と管理者権限が必要
VS Codeで使うならMinecraft Bedrock Debugger拡張機能を使う
通常の統合版クライアントでは /script debugger connect を使う場面が多い
BDSでは /script debugger listen 19144 とサーバー設定が重要
/scriptevent はスクリプトへイベントを送る別コマンド
/reload は関数・スクリプトファイルの再読み込み用

/script コマンドは、普通に遊ぶだけならあまり出番はありません。
でも、統合版アドオン制作を始めると、デバッグや負荷調査でかなり重要になります。

特に、Script APIを使ったアドオンは、最初のうちは「動かない理由」が見えづらいです。
構文ミスなのか、パック設定なのか、APIバージョンなのか、接続設定なのか、原因が分からず迷うことがあります。

そういう時に、/script debugger や /script profiler を使えると、原因をかなり追いやすくなります。

まずは、簡単な main.js を作って、VS Codeと接続するところから試してみてください。
一度つながると、スクリプト開発の見通しがかなり良くなるはずです。

では、本日はここまでで終わります。
最後までご覧いただき、ありがとうございました。
柚子クラでは他にもマイクラ統合版・Java版の攻略や便利装置を紹介しているので、ぜひご覧くださいね(^^♪

13. 参考文献

この記事を書くにあたり、以下の公式ドキュメント・コミュニティWiki・開発者向け情報を参考にしています。

目次