
この記事ではプラグインを作るための開発環境の整え方を解説します。

PCの初期状態には開発するためのソフトが入っていないので、そのままでは開発に入ることはできません。
まずは開発に必要なソフトをインストールし、使えるように設定しましょう。

何をインストールするのかは、対象となるMinecraftのバージョンによって、少し変わってきます。
ここでは混乱を避けるため、<mark>OSはWindowsで、Minecraftは最新バージョンに限定</mark>して話を進めていきます。現在Macユーザー向けには書かれていません。

プラグイン開発に必要なソフトは次の通りです。

* Minecraft Java Edition
* VS Code
* JDK
* Maven

これらを、ひとつずつ解説してきます。

## Minecraft Java Editionをインストールする

いわゆるJava版のMinecraftのことで、こちらの[マインクラフト公式サイト](https://www.minecraft.net/ja-jp/store/minecraft-java-edition)から購入できるエディションです。

<mark>内容は同じMinecraftですが、Bedrock版とはまったく別のソフトになります。</mark>
今回開発を進めていくプラグインは、このJava版でしか動かせないので、持っていない場合はこちらを購入してインストールしてください。

このMinecraft本体以外はすべて無料で使うことができます。

## Visual Studio Codeをインストールする

プログラミングをするためには、開発を助けてくれるプログラミング用のエディターが必要です。

エディターには様々な種類がありますが、このサイトでは、近年最も人気のある<strong>「<R t="ヴィジュアル">Visual</R> <R t="スタジオ">Studio</R> <R t="コード">Code</R> (<R t="ヴィエスコード">VS Code</R>)」</strong>のインストールとその設定について解説します。

<Note color="blue">
  VS Codeをインストール済みの方は、
  <a href="#すでにvs-codeが入っている場合">「すでにVS Codeが入っている場合」</a>
  に進んでください。
</Note>

VS Codeは初期状態では基本機能しか使うことができず、拡張機能によって使えるプログラミング言語を増やしていく形式になっています。
すでに公式から、今回必要な拡張機能を含んだインストーラーが公開されているので、こちらを使うことにしましょう。
これを使うことで、必要なソフトのインストールと設定の一部を省略できます。

<mark>次のページからインストーラーをダウンロードして、指示にしたがってインストールしてください。</mark>

<ExButton href="https://code.visualstudio.com/learn/educators/installers#_coding-pack-for-java">VS Code - Cording pack for java</ExButton>

標準のインストーラーを使った方は再インストールするか、次の<a href="#すでにvscodeが入っている場合">「すでにVS Codeが入っている場合」</a>の設定を併せて行ってください。

### 表示を日本語に設定する

VS Codeは初期状態では英語表示です。
日本語設定は拡張機能として公式に用意されているのでこれをインストールします。

OSが日本語環境なら、VS Codeを最初に開いたとき、この日本語化の拡張機能をインストールするか聞かれるので、そのまま入れておきましょう。

邪魔になったら削除して英語に戻すこともできます。

<Fig file="vscode-japanese.png" width={1105} height={594} />

この拡張機能は手動で入れることもできます。

1. `Ctrl + Shift + X`で拡張機能枠を開きます
2. 検索欄に「`japasese`」と入れて検索します。
3. 「Japanese Language Pack for Visual Studio Code」という拡張機能をインストールします。
4. これをインストールしたあとVS Codeを開き直すと日本語になっています。

<Note color="blue">
  この「Cording pack for java」を使ってインストールした場合、次の設定は不要なので、
  <a href="#maven">「Maven」</a>に進んでください。
</Note>

### すでにVS Codeが入っている場合

#### Java開発用の設定をする

通常のVS CodeにはJava開発用の機能が入っていないので、拡張機能をインストールします。

<mark>`Ctrl + Shift + X`で拡張機能を開き、「Extension Pack for Java」をインストールしてください。</mark>

<Fig file="extension_java.png" width={948} height={511} />

この拡張機能ひとつで、Java開発に必要な複数の拡張機能が同時にインストールされます。

#### JDK(Java Development Kit)

Javaというプログラミング言語の開発機能をインストールします。
(Java版のJavaというのは、このプログラミング言語のことです。)
Javaを動かす機能自体は標準で入っていますが、開発用の機能は含まれていません。
これをダウンロードしてインストールしましょう。

<ExButton href="https://www.oracle.com/java/technologies/downloads/#jdk17-windows">JKD17のダウンロードページへ</ExButton>

<mark>「Windows x64 MSI Installer」をダウンロードしてください。</mark>
末尾の細かいバージョンはダウンロード時期によって異なります。

<Fig file="download_jdk17.png" width={962} height={298} />

次に<mark>ダウンロードしたファイルをダブルクリックで開き、表示された指示に従ってインストールしてください。</mark>

## Maven

<R t="メイヴェン">Maven</R>とはJavaの開発で使うプロジェクト管理ソフトのことです。
これは開発中に行う様々な手順を自動化してくれます。
これも併せてインストールしましょう。

<ExButton href="https://maven.apache.org/download.cgi">Mavenのダウンロードページへ</ExButton>

<mark>「Binary zip archive」をダウンロードしてください。</mark>

<Fig file="maven_download.png" width={886} height={194} />

このファイルはインストーラーではないので、自分でインストールする必要があります。

<mark>ダウンロードしたファイルを展開</mark>
すると「apache-maven-3.8.3」という名前のフォルダーが現れます。

<mark>今回はこのフォルダーを「ドキュメント」の位置に置いて進めます。</mark>

<Note color="amber">置く場所によって動かない場合もあるので、Mavenが動かなかったら他のフォルダーに移動させて、もう一度設定しなおしてください。</Note>

次に、このファイルを使えるようにするための設定をします。（「パスを通す」と言います）

<mark>Windowsの検索欄から「環境変数」と入力して、「環境変数を編集」を選んでください。</mark>

<Fig file="environment_variables.png" width={784} height={640} />

<Note color="amber">以降の編集操作は他の記述を消してしまう可能性があるので、編集前にスクリーンショットを撮って残しておくと安心です。</Note>

次に、<mark>ユーザー環境変数から「Path」を選択して「編集」を選びます。</mark>

<Fig file="environment_variables2.png" width={614} height={331} />

<mark>「新規」を押したあと、そのまま「参照」を押してフォルダー選択画面を開きます。</mark>

<Fig file="environment_variables3.png" width={527} height={205} />

<mark>さきほど設置したフォルダーの中の「binフォルダー」を選んでください。</mark>

<Fig file="environment_variables4.png" width={373} height={382} />

これでMavenのインストールは完了です。

<Note color="blue">このファイルを消してしまったり、別の場所に移動させたい場合は、同じ手順でやりなおしてください。</Note>

以上で、プラグイン開発に必要なソフトのインストールは終わりです。

## 参考

* [Creating a blank Spigot plugin in VS Code](https://www.spigotmc.org/wiki/creating-a-blank-spigot-plugin-in-vs-code/?__cf_chl_jschl_tk__=pmd_bSbJ.XRzHgiZqo3bJcoWwc60ZFWroh07XGsOnKUD66I-1634702648-0-gqNtZGzNAjujcnBszQil)
* [BuildTools | SpigotMC - High Performance Minecraft](https://www.spigotmc.org/wiki/buildtools/#running-buildtools)
* [Java in Visual Studio Code](https://code.visualstudio.com/docs/languages/java)
* [Getting Started with Java in VS Code](https://code.visualstudio.com/docs/java/java-tutorial)


開発環境を整える

プラグインの開発環境を整える


プラグインはサーバーで動くプログラムなので、普通のJava版Minecraftだけでは動かせません。

いきなりサーバーと言われても難しく感じるかも知れませんが、実は自分のPCでとても簡単に動かすことができます。

ここでは<R t="ペーパーエムシー">PaperMC</R>というサーバーの使い方を学びましょう。

## PaperMCファイルをダウンロードする

PaperMCの本体ファイルを、次の公式サイトからダウンロードしてください。

<ExButton href="https://papermc.io/downloads">PaperMCをダウンロードする</ExButton>

特に理由がない限りは最新版をダウンロードしてください。

## PaperMCサーバーを起動する

PaperMCはコマンドラインを使って起動します。
Minecraftでコマンドが使えるように、WindowsやMacでも専用のコマンドが使えます。

しかし、コマンドを打つのは難しく、面倒なので、ファイルをクリックするだけで起動するようにしましょう。
起動ファイルの作り方はとても簡単です。

### 起動用のファイルを作る

1. サーバー関係のファイルを置くためのフォルダーを作る（場所はどこでもよい。あとで移動可能）
2. ダウンロードしたファイル(`paper-1.18.1-xxx.jar`)を、そのフォルダーに置く
3. `start.bat`という名前で空のファイルを作る(作り方の[補足1](#s1), [補足2](#s2))
4. そのファイルに次の内容をコピーして貼り付けて保存する

```bash:start.bat
@echo off
java -Xms2G -Xmx2G -jar paper-1.18.1-xxx.jar --nogui
pause
```

2行目の`paper-1.18.1-xxx.jar`の部分は、自分でダウンロードしてきたファイル名と同じものに変更してください。

<Note color="blue">
バージョン名などの数字部分は残しておいて方が良いですが、新しいサーバーファイルをダウンロードする度に、このファイル名部分も変更するのは面倒です。
その場合はバージョン名やビルド番号などを削除して、使いやすいように調整してください。
</Note>

<Suppliment color="blue" title="補足1: 拡張子が表示されない場合" id="s1">

ファイル表示の設定を変更していない場合、拡張子(.jpg, .txtなど)は表示されません。
まずは、これを表示するように変更しましょう。

1. エクスプローラーを開く
2. 「表示」タブをクリックする
3. 「ファイル名拡張子」にチェックを入れる

<Fig file="extension.png" width={1057} height={192} />

これで、ファイルに拡張子が表示されます。

</Suppliment>

<Note color="blue">
拡張子を表示すると、変なファイルに気づきやすくなるため、セキュリティ面から見ても重要です。
表示する設定のままにしておくことをお勧めします。
</Note>

<Suppliment color="blue" title="補足2: 特殊な拡張子を持つファイルを作る" id="s2">

1. エクスプローラー内で右クリック
2. 「新規作成 / テキスト ドキュメント」を選んで新しいファイルを作成する
3. <mark>名前を拡張子ごと変更します。</mark>(今回は`start.bat`です)

<Fig file="newfile.png" width={1053} height={664} />

</Suppliment>

### 起動用ファイルを実行する

このファイルをダブルクリックするだけで、記入したコマンドが自動で実行され、サーバーを起動させることができます。
毎回自分で打つよりも簡単ですね。

起動時にはコンソール画面が開くので、サーバーがどのような状態になっているかは、このコンソール画面を注意深く読んでください。
（英語がよくわからない場合は自動翻訳サイトにコピペしましょう）

基本的にサーバーは動き続けますが、<mark>最初だけは必ず停止します。</mark>
次に進んでください。

### EULAに同意する

<mark>最初の起動時には、次の表記が出て必ず止まります。</mark>

```txt
[INFO]: You need to agree to the EULA in order to run the server. Go to eula.txt for more info.
```

翻訳すると、<mark>「サーバーを動かすためには、EULAに同意していただく必要があります。詳細はeula.txtをご覧ください。」</mark>となります。

<Note color="blue">
<strong>EULA</strong>とは「End-User License Agreement」の略で、日本語では「使用許諾契約」という意味です。
要するにPaperMCを使うにあたり、Mojang（マインクラフトを作っている企業）との約束を守ります、という契約です。
</Note>

この表記が出た後は、<mark>新しく`eula.txt`が作成されている</mark>ので開きましょう。

このファイルの中には次のように書かれています。

> By changing the setting below to TRUE you are indicating your agreement to our EULA.

これは<mark>「以下の設定をTRUEに変更することにより、EULAへ同意したことになります。」</mark>という意味です。

urlは日本語環境なら日本語訳のページに移動します。
そこまで長くなく、わかりやすい文章になっているので、目を通しておいてください。
特にサーバーを公開する前には、必ず全文を理解するようにしてください。

<Suppliment color="blue" title="タコスは好きですか？" id="s1">

PaperMCの場合はもう1つ<span className="line-through">余計な</span>文章があります。

> You also agree that tacos are tasty, and the best food in the world.

日本語訳は「タコスは美味しくて、世界で一番の食べ物だということにも同意しますね。」となります。<br />
これはPaperMCの製作者の冗談なので気にしないでください。

</Suppliment>

EULAに同意するにはテキストファイル内の次の文章を変更します。

```bash:eula.txt
# 元の記述
eula=false
```

<mark>ここの`false`を`true`に変えることでEULAに同意したこととなります。</mark>
（タコスに関しては同意しなくても構いません）

```bash:eula.txt
# 同意する
eula=true
```

変更して保存したら、もう一度`start.bat`をダブルクリックして起動しましょう。

今回はEULAに同意しているので、サーバーがきちんと起動されます。

`Done`と表示されたら起動完了です。

```bash
[INFO]: Done (7.251s)! For help, type "help"
```

## PaperMCサーバー内のワールドに入る

それではサーバーが動いたので、このサーバー内のワールドに入ってみましょう。

1. 裏でサーバーを動かしたままにする
2. Minecraft Java Editionを同じバージョンで起動する
3. シングルプレイの下にある「マルチプレイ」を選ぶ
4. 「ダイレクト接続」から、サーバーアドレスを`localhost`と入力して接続する

<Fig file="localhost.png" width={852} height={508} />

これで、通常のMinecraftを同じようにワールドに入ることができます。
今回は何も設定を変更してないのでバニラと同じ状態です。

<Note color="blue">
  サーバーアドレスが<code>localhost</code>
  であればよいので、「サーバーを追加」から、開発用のサーバーとして登録しておくのもよいでしょう。
</Note>

## PaperMCサーバーを停止する

ワールドを抜けても、PaperMCは止まらず動き続けます。
最後にサーバーの停止の仕方を学びましょう。

停止には専用のbatファイルを作成する必要はありません。
`start.bat`を起動したときに開いたコンソール上で`stop`と入力するだけです。

```bash
stop
```

これを入力しないと裏でサーバーが動き続けたままになるので注意してください。

## 最後に

今回はプログインを実行するためのサーバーの動かし方を学びました。

これで最初の設定は終わったので、次回からは下のように操作するだけです。とても簡単ですね。

1. 起動: `start.bat`をダブルクリック
2. 停止: `stop`と入力

## 参考

* [PaperDocs Getting Started](https://paper.readthedocs.io/en/latest/server/getting-started.html)


自分のPCでサーバーを動かす(PaperMC)

【PaperMC】自分のPCでサーバーを動かす

このページではPaperMCサーバーで動くプラグインを作り方を説明していきます。

とはいえ、最初に細かい設定を説明しても、まったくわからないと思います。
まずは<mark>「よくわからないけれど、動いた」というところまでを目標</mark>にして、それから少しずつ理解していきましょう。

## 開発環境を整える

すでに開発環境が整っていることとして、話を進めていきます。

開発環境の準備がまだの方は、次のページから各種アプリの設定をしておいてください。

<LinkCard slug="plug-in-development-environment" />

## サンプルファイルのダウンロード

サンプルファイルを用意してあります。

最終的にはこのようなファイル構成になればよいだけので、まずはダウンロードしたものを使ってプラグインを適用してみましょう。

<ExButton href="https://github.com/akihamitsuki/paper-blank-plugin">サンプルファイルをダウンロードする</ExButton>

<Fig file="download.png" width={778} height={416} />

ダウンロードしたファイルを展開すると、次のファイル構成になっています。

```txt
paper-blank-plugin-main
 ┣ src
 ┃ ┗ main
 ┃   ┣ java
 ┃   ┃ ┗ com
 ┃   ┃   ┗ example
 ┃   ┃     ┗ blank_plugin
 ┃   ┃       ┗ Main.java
 ┃   ┗ resources
 ┃     ┗ plugin.yml
 ┗ pom.xml
```

<mark>最低限必要なのはこの3つのファイルだけです。これが適切なフォルダー位置に含まれているかを確認してください。</mark>

1. `src/main/java/com/example/blank_plugin/Main.java`<small>: プラグインのコードが書かれているファイル</small>
2. `src/main/resources/plugin.yml`<small>: プラグインの構成について書かれているファイル</small>
3. `pom.xml`<small>: Mavenプロジェクトに関するファイル</small>

<Note color="blue">
<code>readme.md</code>と<code>.gitignore</code>はプラグインとは関係ありませんが、そのまま含まれていても問題ありません。（消してもよい）
</Note>

## プラグインをコンパイルする

Javaファイル(`.java`)はそのまま使えないので、`.jar`ファイルにコンパイルしましょう。

コンパイルは<R t="メイヴェン">Maven</R>というビルドツールが自動でやってくれます。

ダウンロードしたファイルをフォルダーごとVS Codeで開いてください。

<Fig file="maven_install.gif" width={949} height={531} />

`pom.xml`が含まれていると、これらがJavaプロジェクトであると自動で認識してくれます。
このとき、VS Codeのエクスプローラー欄の下の方に`MAVEN`という項目が現れます。

これをクリックして開き、`blank-plugin/Lifecycle/install`にある矢印ボタンを押します。

設定やプログラムに不備がなければ`BUILD SUCCESS`と表示され、`target`フォルダーに`blank-plugin-0.0.1.jar`が作成されます。

このファイルをPaperMC(SpigotMC)サーバーの`plugins`フォルダーに配置(jarファイルをそのままコピペ)してから、サーバーを起動してください。

<LinkCard slug="start-up-papermc" />

次のようにコンソール画面に次のログが表示されれば、サーバー側がプラグインファイルを認識できたということになります。

<Fig file="plugin_enable.png" width={613} height={177} />

## 各構成の解説

ひとまずプラグインが動くことを確認したので、次は各ファイル説明に入ります。

<mark>これより下の説明は最初にすべて覚える必要はありません。</mark>

つまらくなったら次に進んでしまい、わからなくなったときに戻ってきてください。

### プロジェクトフォルダー

一番上の`paper-blank-plugin-main`がプロジェクトフォルダーです。
これは直接プラグインとは関係ないので好きな名前に変えても構いません。

### pom.xmlについて

`pom.xml`(Project Object Model)とはビルドツールであるMavenを管理するファイルです。

ビルドツールとは面倒なことを自動化してくれる機能のことで、それを使うためには決まった構成にしておく必要があります。

この中からプロジェクトに合わせて変更するべき箇所の説明をします。

ファイル内には様々な記述がありますが、自分で記入する箇所は次の3か所だけです。

```html

<groupId>com.example.blank_plugin</groupId>

<artifactId>blank-plugin</artifactId>

<version>0.0.1</version>
```

#### groupId (Group ID)

これは他の人が作ったプログラムと干渉しないようにするためのものです。

##### 公開しない場合

<mark>公開をしないのであれば、どのような値でもかまいません。</mark>

今回は練習として、`com.example`とし、パッケージ名として`.blank_plugin`を追加します。

##### 公開する場合

<mark>公開する予定があれば、独自の値を入力する必要があります。</mark>

GroupIDの決め方は、自分の持っているウェブサイトのドメイン名を逆にし、パッケージ名を加えることが推奨されています。

このサイトのURLの場合は`https://mc.akihamitsuki.net`なので`net.akihamitsuki.mc`となります。
ここにパッケージ名を加えた`net.akihamitsuki.mc.blank_plugin`をグループIDとして使います。

ウェブサイトを持っていない場合はメールアドレスなどを使ってください。
`myname@example.com`なら`com.example.myname.project`などと入力してください。

#### artifactId (Artifact ID)

バージョンを除いた配布ファイルの名前になります。

好きな名前を付けても構いませんが、いくつかの命名規則があります。

* アルファベットの小文字で書く
* 記号は使わない
* 単語はハイフンで繋ぐ

「Blank Plugin」場合は`blank-plugin`となります。

#### version

配布ファイルのバージョン名です。

##### 配布しない場合

配布しないのであれば、自由な値にしたり、変更しなくても問題ありません。

ずっと`1.0`のままでも問題ありません。

##### 配布する場合

配布する場合は、原則として数字とドットを使った典型的なバージョン名にしてください。
日付やそれ以外の文字は推奨されません。

* OK: `1.0`, `2.1`, `0.0.1`, `1.10.100`
* NG: `2021-12-11`, `v1`

#### repositoriesとdependencies

ここにはPaperMCを使うための記述をします。
これにより、このプロジェクト内でPaperMCにあるクラスなどを利用できます。

この個所には公式ページで記載されている値をそのまま入れてください。

repositoriesの方はおそらく変わりませんが、dependenciesの方はバージョンごとに変わります。
あたらしいサーバーファイルをダウンロードしたら、こちらの値も変更してください。

<ExButton href="https://papermc.io/using-the-api">公式ページへ</ExButton>

```html
<repositories>
  
  <repository>
    <id>papermc</id>
    <url>https://papermc.io/repo/repository/maven-public/</url>
  </repository>
  
</repositories>

<dependencies>
  
  <dependency>
    <groupId>io.papermc.paper</groupId>
    <artifactId>paper-api</artifactId>
    <version>1.18.1-R0.1-SNAPSHOT</version>
    <scope>provided</scope>
  </dependency>
  
</dependencies>
```

### Mavenのフォルダー構成

次の構成がMavenを使うためのフォルダー構成です。
一番上のプロジェクトフォルダー以外は名前と位置を揃える必要があり、変更してはいけません。

```bash
paper-blank-plugin-main
 ┣ src
 ┃ ┗ main
 ┃   ┣ java
 ┃   ┗ resources
 ┗ pom.xml
```

### plugin.ymlについて

どのようなプラグインなのかを記述するファイルです。

```yaml
# 最初に実行するファイルのパス
main: com.example.blank_plugin.Main
# プラグインの名前
name: BlankPlugin
# プラグインのバージョン
version: 0.0.1
# 使用するAPIのバージョン
api-version: 1.18
```

<Note color="blue">
<code>yml</code>はヤムルと読み、<code>.yaml</code>と書く場合もあります。
</Note>

#### main

最初に実行するファイルのパスです。
`src/main/java/`に続くパスとそろえる必要があります。

上の例の場合は、次のフォルダー構成になります。

```yaml
main: com.example.blank_plugin.Main
```

```bash
# src/main/java/com/example/blank_plugin/Main.java
[project]
 ┗ src
   ┗ main
     ┗ java
       ┗ com
         ┗ example
           ┗ blank_plugin
             ┗ Main.java
```

別の例も挙げておきます。最初に動かすファイル名は`Main.java`ではなく、好きな名前を指定できます。
次の例は`App.java`です。

```yaml
# ここまで短いのは推奨されない
main: myplugin.App
```

```bash
# src/main/java/myplugin/App.java
[project]
 ┗ src
   ┗ main
     ┗ java
       ┗ myplugin
         ┗ App.java
```

#### name

プラグインの名前です。
自由に決めてください。

この名前は使用中のプラグインの一覧などで表示されます。

#### version

プラグインのバージョンです。
`pom.xml`で決めたバージョンとは違っていても構いません。

* `pom.xml`: プロジェクトのバージョン
* `plugin.yml`: プラグインのバージョン

#### api-version

使用するAPIのバージョンです。
通常はMinecraftのバージョンと合わせてください。

この場合は3つ目の数字は記入しません。
`1.18.1`ではなく`1.18`が正しい値となります。

### Main.javaについて

最初に実行されるファイルです。

ファイル名自体はなんでもよいので`Main`以外でも構いません。

```java
// 自分のパッケージ
package com.example.blank_plugin;
// JavaPluginクラスを読み込む
import org.bukkit.plugin.java.JavaPlugin;
// Mainクラスを定義し、JavaPluginクラスを継承する
public class Main extends JavaPlugin {
  // メソッドを上書きする
  @Override
  // プラグインが有効になったときに動くメソッド
  public void onEnable() {
    // プラグインが有効になるとこの文字がコンソールに表示される
    getLogger().info("プラグインを有効にしました。");
  }
}
```

この最初に実行されるクラスには`JavaPlugin`を継承(`extends`)してください。

`onEnable()`とは、プラグインが有効(enable)になったとき(on)という意味です。

このとき、`getLogger().info()`を使って`プラグインを有効にしました。`とコンソールに表示しています。

## 最後に

今回はプラグインの適用の仕方を説明しました。

しかし、Javaに慣れている人以外は、まったくわからなかったはずです。（書いている本人も正確に理解していません）

次からサンプルを使って少しずつ解説していくので、少しずつ慣れていってください。

プラグインの作り方

【PaperMC】最初のプラグインの作り方


この章ではプラグインの基本的な処理を解説します。


プラグインの基本

プラグイン


プラグインとはサーバー上で動くJava版に追加の機能を与えるプログラムのことです。

一般的にMODとは区別されますが、サーバー上で動くMODと考えてもらって構いません。

ここでは代表的なサーバーMODであるSpigotMC/PaperMCで使えるプラグインの作り方を学びます。

## 公開サーバーにアップロードしなくても使える

プラグインは個人のPCで動かすことができます。
必ずしも、サーバーとして一般公開しないと使えないわけではありません。
公開予定がなく、開発を試してみたい方でも気軽に動かすことができます。



`manifest.json`は、Minecraft本体に対して、そのアドオンパックがどういうものかを伝えるためのファイルです。

このファイルの記述を間違えてしまうと、Minecraftが各アドオンパックを正しく認識できず、ワールドに適用できないので注意して書く必要あります。

manifestとは「宣言する・明白にする」という意味の英単語ですが、うまい日本語訳が定着していないので、このページではマニフェストファイルと呼ぶことにします。

## 例文

例としてビヘイビアーパックにある初期状態の`manifest.json`ファイルを確認してみます。

それぞれの簡単な説明については、コメント欄(`//`の行)を見てください。

<Note color="blue">
通常の`.json`形式では次のようなコメントは使えませんが、マインクラフトなど一部の環境では特別に許可されています。
一般的な利用方法では`.json`形式のファイルにコメントを書くとエラーになるので注意してください。
</Note>

```json:manifest.json
{
  // このファイルの記述方法のバージョン
  "format_version": 2,
  // このアドオンの基本情報
  "header": {
    // アドオンの説明
    "description": "Example vanilla resource pack",
    // アドオンの名前
    "name": "Vanilla Resource Pack",
    // アドオンのUUID
    "uuid": "ee649bcf-256c-4013-9068-6a802b89d756",
    // アドオンのバージョン（任意の値）
    "version": [0, 0, 1],
    // マインクラフトのバージョン
    "min_engine_version": [1, 19, 20]
  },
  // このアドオンに含まれる内容
  "modules": [
    {
      "description": "Example vanilla behavior pack",
      "type": "data",
      "uuid": "fa6e90c8-c925-460f-8155-c8a60b753caa",
      "version": [0, 0, 1]
    }
  ],
  // その他ファイルとの依存関係
  "dependencies": [
    {
      "uuid": "66c6e9a8-3093-462a-9c36-dbb052165822",
      "version": [0, 0, 1]
    }
  ]
}
```

## format_version

このマニフェストファイルの構文形式を表します。
下の表の通り、アドオンパックの種類によって異なります。

<Table>
  <tbody>
    <tr>
      <th>`"format_version": 1`</th>
      <td>スキンパック</td>
    </tr>
    <tr>
      <th>`"format_version": 2`</th>
      <td>リソースパック・ビヘイビアパック・ワールドパック</td>
    </tr>
  </tbody>
</Table>

## header

このアドオンパック自体についての情報が書かれています。

### description

このアドオンパックの説明欄です。
アドオン一覧に表示されます。

必須ではなく、省略できます。

```json
// アドオンの説明
"description": "Example vanilla resource pack",
```

### name

このアドオンパックの名称です。
アドオン一覧に表示されます。

これは必須項目です。

```json
// アドオンの名前
"name": "Vanilla Resource Pack",
```

### uuid

[UUID](https://ja.wikipedia.org/wiki/UUID)とは識別子のことで、
<mark>Minecraftはこの値をもとにして、それぞれのアドオンパックを認識します。</mark>
名前(`name`)で判断しているわけでも、入れたアドオンパックすべてを認識するわけでもありません。

そのため、UUIDが同じだと、それらはすべて同じアドオンパックとして扱われます。
ここを変更せず同じUUIDを持つアドオンパックが複数あると、その中の1つだけが認識され、それ以外のアドオンパックは一覧に表示されなくなります。

<mark>新しいアドオンを作るたびに、必ずここを独自の値に置き換えてください。</mark>

またUUIDは形式が決まっており、適当に入力するのではなく、型に沿って生成したものを使うようにしてください。
このUUIDの生成には、[UUIDを生成してくれるサイト](https://www.uuidtools.com/generate/v4)やVS Codeの拡張機能などを活用してください。

```json
// アドオンのUUID
// この値をそのまま使ってはいけない
"uuid": "ee649bcf-256c-4013-9068-6a802b89d756",
```

### version

このアドオンパックのバージョンです。
同じUUIDのアドオンパックを読み込んだ場合、このバージョンの高い方が有効になります。

そのため、開発開始時点では気にする必要はありません。
配布段階になったら確認して、適切なバージョンを入力するようにしてください。

```json
// アドオンのバージョン（任意の値）
"version": [ 0, 0, 1 ],
```

### min_engine_version

このパックが作成されたゲームの最小バージョンです。
リソースパックとビヘイビアーパックには必須の項目です。

基本的に<mark>開発時点でのMinecraftのバージョンに一致</mark>させてください。

```json
// 現在のマインクラフトのバージョンに一致させておく
"min_engine_version": [ 1, 19, 20 ]
```

## module

このアドオンパックに含まれる内容について書く場所です。

### description

モジュールの説明欄です。
アドオン一覧には表示されず、開発者向けのメモとして扱ってください。

### uuid

ここの`uuid`は`header`で入力したものとは別の値を入力してください。

### type

モジュールのタイプで、アドオンパック内で扱う内容に応じて、適切な値を選ぶ必要があります。

この辺りは公式ドキュメントの更新が追いついておらず、筆者もよくわかっていません。

<Table>
  <tbody>
    <tr>
      <th>`resources`</th>
      <td>リソースパック</td>
    </tr>
    <tr>
      <th>`data`</th>
      <td>ビヘイビアパック</td>
    </tr>
    <tr>
      <th>`script`</th>
      <td>ゲームテストフレームワーク</td>
    </tr>
  </tbody>
</Table>

リソースパックの場合は`resources`、ビヘイビアーパックの場合は`data`のモジュールが必要になります。

ゲームテストフレームワークを利用する場合には`script`になりますが、この場合には追加の設定も含める必要があります。

```json
// ゲームテストフレームワークを使う場合のモジュール例
{
  "description": "Use Game Test Framework",
  "type": "script",
  "uuid": "eb32839f-aa4e-41f3-ad15-49e9d76518c0",
  "version": [0, 0, 1],
  // 使用するプログラミング言語設定? 将来的に他の言語も使えるようになりそう
  "language": "javascript",
  // ワールド開始時に最初に読み込まれるスクリプトファイル
  "entry": "scripts/main.js"
}
```

### version

個別モジュールのバージョンです。

モジュール内のさらに細かい変更点を特定するために用いられるそうです。

## dependencies

このマニフェストファイルが動作するために必要な他のパックの定義を含みます。

この例では、バニラのリソースパックと依存関係にあることを示しています。

この中の`uuid`および`version`は、依存先のアドオンパックの`manifest.json`の値と一致させてください。
他のとは異なり、ランダムで固有な値に変更してはいけません。

```json
"dependencies": [
  {
    // このuuidがバニラのリソースパックのmanifest.jsonのuuidと同じ
    "uuid": "66c6e9a8-3093-462a-9c36-dbb052165822",
    "version": [0, 0, 1]
  }
]
```


manifest.jsonについて

entityファイルに何が書かれているのか、クリーパーを例に見ていきます。

entityファイルの読み方


アドオンとはBedrock版が公式で用意している拡張機能のことです。
Java版のMODとは区別され、完全に別物です。

基本的にはMinecraftを改造する機能という認識で問題ありません。
しかし、その本質は<mark>Minecraftのシステムを使った、あなた独自のゲームを作れる</mark>ことにあります。

コマンドがMinecraftの世界を拡張するだけなのに対して、アドオンでは根本的なゲームルールから改変し、まったく別のゲームにしてしまうこともできます。

このように、非常に大きな拡張性をもつため、その内容を理解するのは非常に難解です。
コードビルダーが誰もができたほうが良い教養レベルなら、アドオンは完全に専門技術の世界となります。

その専門技術を習得するためには、基本的なプログラミング能力は当然として、明確な論理性をともなう国語、図形や確率といった高等数学、英文サイトを読解できるだけの英語力が求められます。

これらを学んでからアドオンに入るのではなく、アドオンを学びながら、最終的にはこれらを習得していくという心構えが必要です。


マインクラフトのシステムで<br />自由に世界を作る

アドオン


アドオンの開発には専用エディターが不可欠です。
「メモ帳」での開発も不可能ではありませんが、あまりにも効率が悪いので、プログラミング用のエディターをインストールしましょう。

エディターには様々な種類がありますが、この記事では近年最も人気のある「<R t="ヴィエスコード">VS Code</R>」のインストールとその設定について解説します。

以降、このサイトでは、エディターとして「VS Code」を使用することを前提にします。

## VS Codeとは何か

<Fig file="vscode.png" width={1011} height={603} />

正式名称は「<R t="ヴィジュアル">Visual</R> <R t="スタジオ">Studio</R> <R t="コード">Code</R>」で、<mark>世界中のプロの開発者が使っている無料で使えるプログラミング用のエディターです。</mark>

YouTubeでプログラミング関係の動画を見ると、ほとんどの人がVS Codeを使っていることがわかります。
もちろん筆者もプログラミングの仕事で使っています。

高機能でありながら、とても軽く操作性が良く、Microsoftが開発しているため、何かとMinecraftと相性が良いことも特徴です。
(Minecraftの開発元のMojangはMicrosoftの子会社)

主にプログラミング用途で使われていますが、純粋にテキストエディターとしても優れているので、これで小説を執筆している方もいるほどです。
（この記事もVS Codeを使って執筆されています）

このエディター1つを使いこなせるようになっておけば、アドオン以外の他のプログラミング開発にも使いまわせるので、初心者の方はこのエディターを使えるようになっておきましょう。

## Visual Studio Code(VS Code)のインストール

インストール自体は、次の公式サイトからインストーラーをダウンロードし、手順に沿って実行するだけです。

<ExButton href="https://code.visualstudio.com">Visual Studio Code</ExButton>

## 表示を日本語に設定する

`Japanese Language Pack for Visual Studio Code`

VS Codeは初期状態では英語表示です。
日本語設定は拡張機能として公式に用意されているのでこれをインストールします。

システムが日本語環境なら、VS Codeを最初に開いたとき、この日本語化の拡張機能をインストールするか聞かれるので、そのまま入れておきましょう。

邪魔になったら削除して英語に戻すこともできます。

<Fig file="vscode-japanese.png" width={1105} height={594} />

自動でインストールされなかったら、手動で設定しましょう。

1. `Ctrl + Shift + X`で拡張機能枠を開きます（または一番左の四角が4つあるアイコンをクリック）
2. 検索欄に「`japasese`」と入れて検索します
3. 「Japanese Language Pack for Visual Studio Code」という拡張機能をインストールします
4. これをインストールし、VS Codeを開き直すと日本語になっています

## エディターの設定

設定しておくと便利な箇所をまとめておきます。
<mark>以降の設定は、必須ではありません。わからなくなったら、設定をとばして先に進んでください。</mark>

### 設定ファイルの開き方

`Ctrl + ,`で設定欄を開くと、フォームから設定を変更できます。
しかし、この場合は細かい設定の仕方が面倒なので（説明も面倒なので）、次の通り、設定ファイルを直接開いて編集します。

`Ctrl + Shift + P`でコマンドパレットを開きます。
入力欄に`settings`と入力すると、「基本設定：ユーザー設定を開く(JSON)」と表示されます。
これを選択し、設定ファイル(`settings.json`)を開いてください。

こちらの方がコピペするだけで設定できるので簡単です。(JSON構造の理解が怪しい場合は無理に使わないでください)

### プログラミング用のフォントを追加する

WindowsにしてもMacにしても、OSが標準で用意しているフォントはプログラミング用途に最適化されていないので、専用のフォントを使うようにしましょう。

例えば「ゼロとオー(0O)」や「アイ・エル・いち(Il1)」など似た形の文字の場合、一般的なフォントでは一瞬で見分けがつきませんが、プログラミング用のフォントではとてもわかりやすくなっています。
そのため、間違いに気づきやすくなり、作業効率が向上します。

<mark>「プログラミング用　フォント」などで検索するといくつも出てくるので、好みのものを選びインストールしましょう。</mark>
その際には日本語フォントが含まれているかだけ確認してください。
一般的な開発では日本語の文章を書く機会も多いので、良い日本語フォントが入っているかも重要です。

#### 「源ノ角ゴシック」の場合

筆者の場合は「源ノ角ゴシックCode(Source Han Code JP)」を使っています。
よくわからない場合は、とりあえずこのフォントを使ってみてください。

<ExButton href="https://github.com/adobe-fonts/source-han-code-jp">源ノ角ゴシック</ExButton>

<mark>リンク先の右側の「Release」から最新版を選択。</mark>

<Fig file="gennokaku1.png" width={1024} height={711} />

<mark>「SourceHanCodeJP.ttc」をクリックしてダウンロード。</mark>

<Fig file="gennokaku2.png" width={1024} height={711} />

ダウンロードしたファイル(`SourceHanCodeJP.ttc`)をダブルクリックして、開いたウィンドウの指示に従ってフォントをインストールします。

インストールしたら、VS Codeの設定ファイルを更新しましょう。

```json
{
  // ...
  // 自分でインストールしたフォント名を入力する
  // この場合は'Source Han Code JP'
  "editor.fontFamily": "'Source Han Code JP', Menlo, Monaco, 'Courier New', monospace",
  // ...
}
```

フォントを複数設定すると、左から優先的に使います。
もしそのフォントに含まれていない場合は、その次のフォントから探すという意味ですが、特殊な文字を使わない限りは気にする必要はないでしょう。

### ルーラー（定規）を設定する

エディター上に、その行の何文字目かの位置に縦線を引きます。
これは、改行位置の目安として設定します。

一般的な文章とは異なり、プログラミングのコードは改行されると、途端に全体像が把握しづらくなります。
そのため、適切な文字数以内で改行させることが推奨されています。

筆者の場合は、`[80, 100, 120]`の3つを指定しています。

```json
{
  // ...
  "editor.rulers": [80, 100, 120],
  // ...
}
```

#### 80文字以内:目標

かつてコマンドライン上で80文字制限があった時の名残が基準となっています。
「Prettier」の初期値が80文字になっていることからもわかる通り、<mark>現在でも理想的な改行位置とされる場合が多いです。</mark>
80文字以内で改行できるほど、綺麗で簡潔なコードを目指してみましょう。

#### 100文字以内:推奨

現在では80文字にこだわる必要は何もないので、<mark>短すぎると感じたら100文字以内などに伸ばしてください。</mark>
実際に、上級者の書いたコードでも80文字以内で改行していない例がいくらでもあり、無理に短くする必要はありません。

#### 120文字以内:上限

<mark>120文字を超える場合は、次のようにコードに何かしらの問題があると考えられます。</mark>

* 変数名が長すぎる
* 条件式が長すぎる
* 入れ子構造が何重にもなっている
* ...など

絶対に改行しないといけないわけではありませんが、コードを見直して調整することが推奨されます。

### ファイルの末尾に改行を追加する

ファイルの最後を改行で終わらせるための設定です。
また改行が複数ある場合は1つだけにします。

* [No Newline at End of Fileって何？どう対策するの？](https://qiita.com/kazuhito_nakayama/items/14c16f1b624ffd2f383c)

```json
{
  // ...
  "files.trimFinalNewlines": true,
  "files.insertFinalNewline": true,
  // ...
}
```

### 余分な余白を削除する

その行の最後に空白が入っていると自動で削除する設定です。

マークダウン(`.md`)の場合など、末尾の余白に意味がある場合は、拡張子別の設定で解除します。

```json
{
  // ...
  "files.trimTrailingWhitespace": true,
  "[markdown]": {
    "files.trimTrailingWhitespace": false
  },
  // ...
}
```

### 対になるカッコを強調する

選択中の開きカッコがどの閉じカッコと対になっているかをわかりやすくしてくれます。
初心者の方は、対になるカッコを見失いやすいので、特にオススメの設定です。

```json
{
  // ...
  "editor.guides.bracketPairs": true,
  // ...
}
```

### 半角スペースをわかりやすくする

半角スペースを見やすくします。
これがあることで何文字分の空白かを認識しやすくなります。

```json
{
  // ...
  "editor.renderWhitespace": "all",
  // ...
}
```

## 拡張機能を追加する

VS Codeは「拡張機能」によって便利な機能を追加していくことができます。（最初に設定した日本語化も拡張機能です）

アドオン開発は基本機能だけで行うことができるので、拡張機能の追加は必須でありません。
もし、下の説明で導入方法がわからなかったらとばしても構いません。

### UUID Generator: UUIDをクリックだけで追加する

`UUID Generator`で検索してインストールしてください。

アドオン開発ではUUIDを何度も追加・する必要が出てきますが、その度に専用の生成サイトを開くのは面倒です。

この拡張機能をインストールすると、右クリックで開いたメニューに`Generate UUID at cursor`が追加されます。

これを使うと、カーソルが合わさっている箇所にUUIDを生成して追加してくれます。


開発用エディタをインストールする

アドオン開発のためにエディタ「VS Code」をインストールする


ここでは自作アドオンを動かすまでの、最小限の手順で解説します。
詳しい解説はあとで行うので、まずは自分のアドオンをワールドに適用するところまでをやってみましょう。

## 事前準備

### com.mojangフォルダーを探す

一般的な配布アドオンは、ダブルクリックするだけで自動で適用してくれますが、今回は自作アドオンなので、アドオンの配置フォルダーを自分で開く必要があります。

その配置場所である`com.mojang`フォルダーは次の位置にありますが、
<mark>最初は「隠しフォルダー」になっているので、まずは表示するように設定しましょう。</mark>

```txt
C:\Users\[ユーザー名]\AppData\Local\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang
```

### 隠しファイルを表示する

1. 「エクスプローラー」（ファイルを探すアプリ）を開く
2. 上の方にある「表示」タブをクリックする
3. 「ファイル名拡張子」と「隠しファイル」にチェックを入れる

<Fig file="folder_settings.png" width={1110} height={224} />

「隠しファイル」にチェックを入れると、普段表示されていない隠しフォルダー・隠しファイルが表示されるようになります。

「ファイル名拡張子」にチェックを入れると、ファイル名の後に拡張子（`.jpg`や`.txt`など）が表示されます。
拡張子の表示は開発に必須なので、ここで一緒に表示しておいてください。

### フォルダーを表示する

隠しファイルを表示するようにしたので、上のパスの通りに移動すればフォルダーにたどり着くことができます。

しかし、途中のファイルを変更してしまったりすると危ないのでフォルダーを検索して移動しましょう。

ショートカットキー`Windows + R`で開いた検索ウィンドウに、次の値を入力して`OK`を押してください。

```txt
%localappdata%\Packages\Microsoft.MinecraftUWP_8wekyb3d8bbwe\LocalState\games\com.mojang
```

<Fig file="search_folder.png" width={399} height={206} />

これで目的のフォルダーが表示されます。

<Note color="blue">
`com.mojang`フォルダは、アドオン開発で頻繁に行き来することになるのでショートカットを作っておくと良いでしょう。
</Note>

### com.mojangフォルダーについて

`com.mojang`フォルダーの中には、Minecraftに関するファイルが入っています。
ゲームのプログラム本体は別のフォルダーにありますが、ワールドデータや設定ファイルなどがあるので、うっかり消したりしないように注意してください。

アドオンに関するフォルダーは、それぞれ**正式版**と**開発版**で分かれるので置く場所に注意してください。

<Table>
  <thead>
    <tr>
      <th></th>
      <th>正式版</th>
      <th>開発版</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>リソースパック</th>
      <td><code>resource_packs</code></td>
      <td><code>development_resource_packs</code></td>
    </tr>
    <tr>
      <th>ビヘイビアーパック</th>
      <td><code>behavior_packs</code></td>
      <td><code>development_behavior_packs</code></td>
    </tr>
    <tr>
      <th>スキンパック</th>
      <td><code>skin_packs</code></td>
      <td><code>development_skin_packs</code></td>
    </tr>
  </tbody>
</Table>

自分で作るアドオンファイルは開発版フォルダーに、他のユーザーが作ったアドオンは正式版フォルダーに入れます。

<Note title="正式版と開発版フォルダの違い" color="blue">
正式版の方はワールドにアドオンを適用した際に、そのアドオンデータがワールドデータにコピーされます。よってファイル内容を変更しても、ワールドが読み込むのはコピー済みのファイルなので影響を受けません。これによりアドオンを削除や編集しても元のワールドは影響を受けずに安定して遊ぶことができます。

一方、開発版の方はワールド内にコピーされず、このフォルダーにあるデータが毎回読み込まれます。このフォルダー内の内容を変更しても、ワールドを開き直すたびに更新内容が適用されるので、同じワールドのまま最新の内容を適用し続けることができます。
</Note>

## ファイルをアドオンとして適用するまで

### テンプレートファイルのダウンロード

まずはテンプレートとして使う、バニラの設定ファイルを公式サイトからダウンロードします。

アドオンには<R t="resource pack">リソースパック</R>と<R t="behavior pack">ビヘイビアーパック</R>の2種類がありますが、
今回は自分で変更しやすい**ビヘイビアーパック**の方を使ってみます。

<mark>次の公式Wiki(英語)のリンクから、最新のテンプレートファイルをダウンロードしてください。</mark>

<Note color="amber">
日本語版は最新の情報になっていない可能性があるので、必ず英語版のページからダウンロードしてください。
</Note>

<ExButton href="https://minecraft.gamepedia.com/Add-on">Add-on - Minecraft Wiki</ExButton>

ページやや下にある「Templates」欄から目的のファイルをダウンロードします。
<mark>今回はビヘイビアーパックの方を変更したいので、「Vanilla Behavior Pack files」の方です。</mark>
バージョン名は常に最新版に対応しています。

<Fig file="templates.png" width={1056} height={488} />

<Note color="amber">
そのすぐ下にある、ベータ版の方をダウンロードしないように注意してください。
ベータ版は基本的には同じですが、バージョンによって構成が異なる可能性があり、以降の説明と食い違う可能性があります。
</Note>

<mark>Zipファイルをダウンロードできたら展開(解凍)しておきましょう。</mark>
アドオン自体は`.zip`のままでも動きますが、今回は自分で変更を加えたいので展開しておきます。

### 解凍して指定のフォルダーへコピー

ファイルのコピー先である`com.mojang`フォルダーを開いてください。

今回は自分で作るビヘイビアーパックなので、<mark>「開発版」のフォルダー`development_behavior_packs`の中にZipから展開したフォルダーをまるごとコピーします。</mark>

### ファイルが認識されているかを確認する

<mark>ここでMinecraft本体を開き、ワールドを新規作成する画面で追加したアドオンが適用可能か確認してみましょう。</mark>

ワールド作成画面の左下の「ビヘイビアーパック」をクリックし、表示された画面から「マイパック」の方を開きます。

正しい箇所に配置できていれば、「Vanilla Behavior Pack」の名前でアドオンとして存在しているはずです。

<Fig file="vanilla.png" width={1380} height={936} />

この段階でのアドオンはバニラの設定なので、ワールドに適用しても何も変化はありません。

## 自分で変更を加えてみよう

今回はみんな大好きクリーパー師匠の爆発力をあげてみましょう。

### 不要なファイルを削除する

<mark>まずは変更したいファイルだけ残して他は削除してしまいましょう。</mark>
アドオン内から他の設定ファイルが消えても、Minecraft内の初期設定が適用されるだけなので、何も問題はありません。

<mark>今回残すファイルは次の3つだけです。</mark>

<Table>
  <thead>
    <tr>
      <th>ファイル名</th>
      <th>説明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>entities/creeper.json</code></td>
      <td>クリーパーの設定ファイル</td>
    </tr>
    <tr>
      <td><code>manifest.json</code></td>
      <td>アドオンの宣言ファイル</td>
    </tr>
    <tr>
      <td><code>pack_icon.png</code></td>
      <td>アドオンのアイコン(無くても動く)</td>
    </tr>
  </tbody>
</Table>

不要なファイルが残っていても問題なく動きますが、同じファイルを二重に読み込んでしまうだけになるなので、変更していないファイルは消しておきましょう。

最初にフォルダーごとコピーしたのはフォルダー名やファイルの階層を間違えないためです。
今回の例の場合、`creeper.json`は`entities`フォルダーの中にあるか、`manifest.json`が正しい名前で存在しているかが大切です。

慣れてきたら最初からすべて自分で作ってしまっても問題ありません。

### マニフェストファイルを編集する

次にアドオンのマニフェストファイルを更新しましょう。
このマニフェストファイルは、Minecraftフト本体に対して、このアドオンがどのような内容かを伝えるものです。
すべてのアドオンで必ず必要なファイルになります。

今回はマニフェストファイルについての詳しい説明は省きます。
詳しく知りたい方は次の記事を参照してください。

<LinkCard slug="add-on-manifest" />

<mark>`manifest.json`ファイルを開いて、次の内容を丸ごとコピーして書き換えてください。</mark>

```json:manifest.json
{
  "format_version": 2,
  "header": {
    "description": "クリーパーの爆発力が上がる",
    "name": "超クリーパー",
    "uuid": "daa20896-1ba7-49e9-a0a4-92673ae76627",
    "version": [0, 0, 1],
    "min_engine_version": [1, 19, 20]
  },
  "modules": [
    {
      "description": "エンティティファイルを改造",
      "type": "data",
      "uuid": "b21d5c21-9033-4b52-8da9-36ca4548ce5d",
      "version": [0, 0, 1]
    }
  ]
}
```

再びワールド設定からアドオン欄を見て、説明欄が変わっているかを確認してみましょう。
上で書き換えた通りのアドオン名になっていれば成功です。

<Fig file="creeper.png" width={1380} height={936} />

### クリーパーの設定を変える

最後にクリーパーの設定を書き換えましょう。

`entities/creeper.json`を開いてください。

今回は爆発力を大きくしたいので、39行目にある「<R t="forced_exploding">強制爆発</R>の<R t="power">威力</R>」を変更しましょう。
<mark>この行にある数字を`3`から`9`に変更してください。</mark>

```json:entities/creeper.json
{
  // ...略
  "minecraft:forced_exploding": {
    "minecraft:target_nearby_sensor": {
    },
    "minecraft:explode": {
      "fuseLength": 1.5,
      "fuseLit": true,
      "power": 9,  // ここを変更 3 -> 9
      "causesFire": false,
      "destroyAffectedByGriefing": true
    },
    "minecraft:on_target_escape": {
    }
  },
  // ...略
}
```

ここの設定は、近くに寄られて爆発した時ではなく、アイテム「**火打ち石と打ち金**」で強制的に爆発させた時の威力です。
同じように見えて内部では区別されているんですね。

### アドオンを適用して爆発させてみよう

<mark>ワールドを新規作成し、先ほど確認したアドオン設定からビヘイビアーパックを適用しましょう。</mark>

すぐにクリーパーを出したいので、ゲームモードはクリエイティブに設定しておいてください。

ワールドに入ったら、次のコマンドを使い準備をしてください。

```bash
# 「火打ち石と打ち金」を手に入れる
/give @s flint_and_steel
# クリーパーを呼び出す
/summon creeper
```

準備ができたら「火打ち石と打ち金」を使い、クリーパーを強制爆発させてみましょう。

<Fig file="explosion.jpg" width={1161} height={794} />

<mark>明らかに威力が高ければアドオンの適用が成功した証拠です。</mark>
これで自分のアドオンを適用することに成功しました。


アドオンの始め方


<mark>コードビルダーはプログラミング初心者向けの機能です。</mark>
大人はもちろんのこと、子供用のプログラミングの学習に使うこともできます。

ただし、誰でもすぐに使い始められるわけではありません。
ここではコードビルダーを始める前に必要なことを解説します。

Minecraftの基礎知識だけでなく、国語・算数の基礎学力、そしてタッチタイピングをはじめとする初歩的なPCを操作する能力が必要です。
英語は必要ありませんが、アルファベットは読める必要があります。

## Minecraftの基本を理解していること

まず、<mark>Minecraftというゲームをきちんと理解していること</mark>が大切です。

Minecraftでプログラミングをするということは、Minecraftの世界を自由に操作するということです。
「普通はこうだけれど、これをちょっと変えてみたら面白んじゃないか」というところから、プログラミングが始まります。
Minecraftのことを何もしらなければ、そのようなことはできません。

<Note color="red">
「マインクラフトはよくわからないけど、コードビルダーでプログラミングだけやりたい」というのは不可能です。
</Note>

基本を理解しているというのは、「<mark>サバイバルモードでエリトラを手に入れられる</mark>」あたりを目安にしてください。
これができれば、Minecraftの基本的な仕様は把握できているはずです。
細かいところまで、すべてを理解している必要はありません。

クリエイティブモードだけでは、基本的なルールの理解はとても難しいです。
まずはサバイバルモードでしっかりと遊ぶところから始めましょう。

<Note color="green">まずはサバイバルモードで、エリトラを手に入れられるくらい遊んでおこう。</Note>

## タッチタイピングの基本ができること

プログラミングでは文字の入力をします。
コードビルダーでは主にブロックを組み合わせるだけですが、少し文字・数字の入力があります。

このときに文字の入力ができないと、学習を進めることができません。
まずは、<mark>早くなくてもいいので、**ローマ字入力ができるように**なっておいてください</mark>。

タイピングの練習用のアプリはいろんなものがあるので、好みのものを探して練習しておいてください。

* [Typing Land (タイピング ランド)](https://typingland.higopage.com/jp.html) (おすすめ)
* [無料タイピング教材|マナビジョン](https://manabi.benesse.ne.jp/gakushu/typing/)

<Note color="green">タイピングの練習をしよう。</Note>

## 小学3年生レベルの基礎学力

<mark>最低でも小学3年生修了レベルの基礎学力が必要です。</mark>
より高度なプログラムを扱う場合には中学・高校レベルの数学が必要になってきますが、初歩レベルはこの年代から始めることができます。

具体的には次のことができないと、プログラミング以前のところでつまづいてしまいます。

* アルファベットの読み書きができること
* 「たし算・ひき算・かけ算・わり算」ができること
* わからない言葉を辞書で調べられること

<Note color="green">プログラミングには国語・算数・英語の基礎学力が大切。</Note>


始めるために必要なこと

コードビルダーを始めるために必要なこと


コードビルダーとはMinecraftで実行できる、教育向けのビジュアルプログラミング機能です。

## ビジュアルプログラミングとは

ビジュアルプログラミングとは次の画像のように、<mark>ブロックを組み合わせてプログラムを作る</mark>、主に学習向けに使われるプログラミング形式のことです。

<Fig file="code_connection.png" width={1280} height={925} />

現在では**ノーコード**と呼ばれる、文字のコードを書かない形式のプログラミングが、一般向け（専門のプログラマではない人）にも広がり始めています。

## コマンドよりも簡単に使える

Minecraft内でゲームを作ったりするときは[コマンド](/command/)を使うのが一般的です。
しかし、コマンドはプログラミング経験者でも難しいので、初心者が簡単に手をだせません。
一方、コードビルダーはプログラミングの学習用として作られているので、<mark>初心者や小学生からでも始めやすい</mark>のが特徴です。

## コードビルダーは練習用機能

残念ながらコードビルダーはコマンドよりも処理能力が低く、基本的に自分一人用の簡単なものしか作れません。
コードビルダーでプログラムの基本を学べば、コマンドの理解も深まります。
もっと複雑なものを作りたくなったらコマンドや[アドオン](/add-on/)に進みましょう。


マインクラフトで始めるプログラミング

コードビルダー


コードビルダーはMinecraft本体のみで動きません。
専用の別アプリと連携し、使い始めるまでを解説します。

## 必要なもの

* Windows10/11のPC
* Bedrock版Minecraft (統合版)

<Note color="red">Windows10/11でもJava版のMinecraftでは使えません。</Note>

**コードビルダー**を動かすためには、<mark>Minecraft本体とは別の公式アプリである「**コードコネクション**」が必要です。</mark>

また、このコードコネクションを動かすためには、<mark>Windows10のBedrock版</mark>または**教育版**のMinecraftである必要があります。

基本的にコードビルダーは教育版向けの機能ですが、例外的にWindows10/11のBedrock版でも使えます。同じBedrock版でも、SwitchやXBoxのMinecraftでは使えません。

<Note color="amber">教育版は教育機関向けにしか提供されておらず、一般ユーザーが使うことはできません</Note>

以降はWindows10/11のBedrock版を使っていることを前提に進めていきます。

## 1. コードコネクションのインストール

このコードコネクションは「**Microsoft Store**」から無料でインストールできます。

カタカナで「コードコネクション」と入力しても、検索に引っかかりません。
検索欄には英語で「`code connection`」と入力しましょう。
「`code`」と入力した段階で候補に現れます。

<Fig file="microsoftstore.png" width={984} height={584} />

上の画像と同じアプリのページを表示できたらインストールしてください。（画像はインストール後の状態です）

## 2. コードコネクションの起動

起動すると次のような画面が現れます。

<Fig file="cc1.png" width={905} height={532} />

「Education Edition(教育版)」と表示されていますが、先ほど説明したとおり<mark>Windows10でも動かすことができます</mark>。

「以下のコマンドを入力してください」とは、<mark>`/connect ...`というコマンドを、Minecraftのワールドで実行する</mark>という意味になります。

## 3. ワールドの作成

Minecraft本体を起動して（すでに起動していても構いません）、<mark>コードビルダーを動かすワールドを作成</mark>しましょう。

今後はコードコネクションと何度も行き来するので、<mark>Minecraftが全画面になっている場合は**ウィンドウ化してください**</mark>。

コードビルダーを使うために**必要な設定は「チートの実行」を有効にする**ことだけです。
それ以外は、変更する必要はありませんが、クリエイティブモードにしておくと便利でしょう。

<mark>クリエイティブモードにすると「チートの実行」も同時に有効になります。</mark>

<Note color="green">「チートの実行」を有効にして、ワールドを作成する。</Note>

<Fig file="cheat.jpg" width={1280} height={720} />

## 4. 2つのアプリを接続する

ワールドを作ったら、<mark>コードコネクションの方に戻ります</mark>。

通常画面ではいくらマウスを操作してもカーソルを外に出せませんが、**チャット画面**や**インベントリ画面**、もしくは<strong>`ESC`キーを押した画面</strong>にすると、マウスカーソルを画面の外に移動させることができます。

### コマンドをコピー

コードコネクションに戻ってきたら、<mark>表示されているコマンドをコピー</mark>します。
右側のアイコンをクリックすることで、クリップボードにコピーされます。
（見た目の変化はありませんが、きちんとコピーされています）

<Fig file="cc2.png" width={905} height={532} />

このコマンド内の数字は使用する環境によって異なります。
**必ず自分で開いたコードコネクションのコマンドを使ってください**。

### コマンドを貼り付け

コピーしたら、再びMinecraft本体に戻りチャット画面を開いてください。

<mark>チャット入力欄に先ほどのコマンドを貼り付けます</mark>。

ここではマウス操作で貼り付けができないので**ショートカットキー**(`Ctrl` + `v`)を使いましょう。

<LinkCard slug="keyboard-input"></LinkCard>

<Fig file="connect.png" width={1492} height={191} />

コマンドをチャット入力欄に貼り付けられたら、そのまま`Enter`キーを押して実行してください。

<mark>エージェントが現れれば、接続は完了です。</mark>

<Fig file="agent.jpg" width={1280} height={914} />

**エージェント**とはプログラミングで動かせる**ロボット**のことです。
指示を与えない限り何もせず、また何をされても影響を受けることがない無敵状態です。

<mark>今回は使わないので、そのまま放置</mark>してください。

## 5. コードコネクションの設定をする

再びコードコネクションに戻ります。
すると、次のようにエディター（プログラミング言語）を選ぶ画面に変わっています。

<Fig file="cc3a.png" width={905} height={532} />

有名なのは<R t="スクラッチ">Scratch</R>ですが、ここでは<mark>マイクロソフト公式の<R t="メイクコード">MakeCode</R>を選びます</mark>。以降このサイトではMakeCodeのみを解説します。

<Note color="blue" title="ScratchとMakeCodeのどちらが良い？">
  <strong>どちらを使っても構いません。</strong>
  どちらもプログラミング初学者向けのものなので、基本を学習した後は使わなくなります。
  そのため、どちらを選んでも、それ以降のプログラミング学習に影響がでることはありません。
</Note>

<Note color="blue" title="用語の確認">
  <dl className="m-0">
    <div className="flex my-1">
      <dt className="font-bold">コードビルダー</dt>
      <div style={{ margin: '0 0.75rem' }}>
        <Icon iconName="fa-arrow-right" />
      </div>
      <dd>マインクラフトのプログラミング学習機能</dd>
    </div>
    <div className="flex my-1">
      <dt className="font-bold">コードコネクション</dt>
      <div style={{ margin: '0 0.75rem' }}>
        <Icon iconName="fa-arrow-right" />
      </div>
      <dd>コードビルダーを使うためのアプリの名前</dd>
    </div>
    <div className="flex my-1">
      <dt className="font-bold">メイクコード</dt>
      <div style={{ margin: '0 0.75rem' }}>
        <Icon iconName="fa-arrow-right" />
      </div>
      <dd>コードコネクションで使うプログラミングの種類</dd>
    </div>
  </dl>
</Note>

## 6. プロジェクトの作成

MakeCodeを選択すると次のような画面になります。

<Fig file="project.jpg" width={1154} height={851} />

プログラムを書くための場所である「**プロジェクト**」を作成しましょう。

### プロジェクトの名前を決める

いきなり名前をつけろと言われても困ると思いますが、名前をつけないと同じプロジェクト名のファイルが増え続け、それぞれのプロジェクトの区別ができなくなってしまいます。

<Fig file="name.jpg" width={1154} height={851} />

ここでは<mark>正しい名前というよりも区別しやすい名前をつけてください</mark>。
今回は「接続テスト」にしておきます。

プロジェクト名はあとで変えることもできます。

## 7. プログラムが実行できるか確認する

すでに2つのプログラミングブロックがあります。
これを利用して最初のプログラムを作ってみましょう。

<Fig file="draganddrop.gif" width={800} height={500} />

左の「**プレイヤー**」カテゴリを開いてください。

<Fig file="project2.jpg" width={1154} height={851} />

その中にある`メッセージ ":)" を 送信する`を**ドラッグアンドドロップ**で持ってきます。

<Fig file="project3.png" width={1154} height={851} />

持ってきたブロックを`チャットコマンド "run" を入力した時`の間にはめ込みます。

それができたら、**右下にある緑色の開始ボタンを押して**ください。
赤い停止ボタンになったら成功です。

<Fig file="project4.png" width={1154} height={851} />

最後にMinecraft本体へ戻り、チャット欄に`run`と入力しましょう。

```bash
run
```

コマンドではないので、先頭にスラッシュは要りません。
そのまま`run`とだけ入力してください。

<Fig file="chat.png" width={678} height={278} />

チャット欄に「:)」と表示されたら成功です。プログラムが正常に動いています。

## プロジェクトを保存する

### 常に保存され続けている

プロジェクトの状態は常に保存され続けています。
そのままコードコネクションを閉じてしまっても、起動しなおせばプロジェクトを続きから始められます。
不安なら**一度ホームに戻っておく**と安心です。

### ファイルとして保存

プロジェクトはファイルとしても保存できます。

プロジェクト右上の歯車アイコンから「プロジェクトの保存」を押して保存してください。

<Fig file="cc11.png" width={960} height={528} />

<Note color="amber" title="大切なプロジェクトはファイルで保存する">
  Windows版のコードビルダーはとても不安定です。
  マインクラフトのバージョンアップに合わせて動かなくなったりすることがよく起きます。
  その場合は再インストールで直りますが、そのときにコードコネクション内のプロジェクトも消えてしまいます。
  大切なプロジェクトはファイルで残しておくようにしましょう。
</Note>

## プロジェクトを削除する

ファイル保存と同じ歯車アイコンで開いたメニューから削除できます。

プロジェクトが不要になった場合は削除しましょう。

## プロジェクトを読み込む

右上の読み込みボタンを押します。

<Fig file="cc12.png" width={888} height={478} />

ファイル、またはurlからプロジェクトを読み込むことができます。

<Fig file="cc13.png" width={930} height={547} />

## プロジェクトを複製する

「すべて表示する」を選択します。

<Fig file="cc14.png" width={888} height={478} />

複製したいプロジェクトの右上の丸にチェックを入れて、右上の複製ボタンを押します。

<Fig file="cc15.png" width={946} height={658} />

新しい名前をつけて保存してください。

<Fig file="cc16.png" width={946} height={658} />

<Note color="blue">
  前の状態を残しておきたい場合は、ファイルとして保存する方がおすすめです。無駄にプロジェクトが増えると管理しづらくなり、再インストール時に一緒に消えてしまう恐れがあります。
</Note>

## プロジェクトの名前を変える

プロジェクトを複製して、保存する際に名前を変えてください。

以前は直接変えることができましたが、バージョンがあがったときにできなくなってしまいました。
もしかしたら、どこかに名前を変更する機能があるかもしれないので、見つけたら教えてください。


始め方と簡単な操作方法

コードビルダーの始め方と簡単な操作方法


<R t="ざひょう">座標</R>とは世界の位置を3つの数字で表したものです。

コマンドでテレポートしたいときには、行き先を決める必要があります。
しかし「そこ」とか「あの辺」ではプログラムにはうまく伝わりません。
もっとはっきりとした言葉で伝えてあげる必要があります。

ここでは「あなたが言っている場所は、どこのことなのか」を正しく伝えるための方法である「座標」について学びます。

## 座標の指定方法

コマンドでの座標の指定の仕方には次の3種類あります。

1. 世界の中心から数える「<strong><R t="ぜったい">絶対</R>座標</strong>」
2. 自分を中心にして数える「<strong><R t="そうたい">相対</R>座標</strong>」
3. 自分の向きを基準に数える「<strong>ローカル座標</strong>」

### 絶対座標（ワールド座標）

絶対座標はそのワールドの中心から数え、同じ座標は必ず同じ場所を指し示します。

座標はそのまま数字で指定します。

```bash
# 世界の中心に移動（yはブロックに埋まらない程度の値）
/tp @s 0 80 0
```

<Table>
  <thead>
    <tr>
      <th>用語</th>
      <th>説明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th><code>/tp</code></th>
      <td>移動するコマンド</td>
    </tr>
    <tr>
      <th><code>@s</code></th>
      <td>誰を移動させるのか。この場合は自分</td>
    </tr>
    <tr>
      <th><code>0 80 0</code></th>
      <td>どこに移動させるのか。この場合は座標</td>
    </tr>
  </tbody>
</Table>

このコマンドはどこで使っても、必ず同じ場所にテレポートします。
`@s`については次で詳しく学びます。今は自分のことだと思ってください。

### 相対座標(チルダ記法)

相対座標は自分を中心に決定する座標です。
つまり自分のいる場所によって移動先が異なります。

座標は数字の前に<code><R t="チルダ">~</R></code>を付けて指定します。

<LinkCard slug="keyboard-input" />

```bash
# 今の位置から東に5ブロック、南に5ブロック進んだ場所に移動
/tp @s ~5 ~0 ~5
```

記号が付くと0は省略できます。

```bash
# 上のコマンドと同じ
/tp @s ~5 ~ ~5
```

また、半角スペースを開けずにくっつけて書くことができます。

```bash
# 上のコマンドと同じ
/tp @s ~5~~5
```

### ローカル座標(キャレット記法)

<Note color="blue">
  ローカル座標は難しい使い方なので、最初は跳ばして次に進んでもかまいません。
</Note>

ローカル座標は対象者の**顔の向き**を基準にして決定する座標です。
自分のいる場所と顔の向きによって移動先が異なります。

座標は数字の前に<code><R t="キャレット">^</R></code>を付けて指定します。

ローカル座標は単純な`(x, y, z)`ではなく、`(左, 上, 前)`方向に移動します。
真南を向いている場合は相対座標と同じになります。

```bash
# 今の位置から左に3ブロック、上に2ブロック、前に5ブロック進んだ場所に移動
/tp @s ~3 ~2 ~5
```

向きは平面方向だけでなく上下方向にも影響を与えます。
真上を向いていた場合には前方向に10ブロックを指定すると上に10ブロックの位置になります。
次のコマンドを同じ位置からいろんな方向を見ながら使ってみましょう。

```bash
# 向いている方向の10ブロック先に金ブロックを置く
/setblock ^ ^ ^10 gold_block
```

### 混合記法

絶対座標と相対座標はそれぞれを組み合わせて指定できます。

```bash
# x方向に5ブロック、y座標は80、z方向に10ブロック移動
/tp @s ~5 80 ~10
```

ローカル座標は組み合わせることができないので、必ずすべてに`^`をつける必要があります。

```bash
# 前方向に5ブロック分移動
/tp @s ^ ^ ^5
```

## マイナス方向

数字に<code><R t="マイナス">-</R></code>がつくと座標の場合は反対方向を表します。

* 「東」の反対は「西」
* 「上」の反対は「下」
* 「南」の反対は「北」

```bash
# 世界の中心から北西にそれぞれ5ブロック進んだ場所に移動（高さは80）
/tp @s -5 80 -5
```

相対座標の場合は、チルダをマイナスよりも先に付けます。
似たような記号なので紛らわしいですが、間違えないように注意してください。

```bash
# 今の位置から北西にそれぞれ5ブロック進んだ場所に移動（高さは同じ）
/tp @s ~-5 ~0 ~-5
```

「0」と「-0」は同じ数を表します。

<small>（0の読みは「レイ」または「ゼロ」です。どちらでも構いません）</small>

東に0ブロック進むのと、西に0ブロック進むのでは同じですね。

```bash
# これらは同じ座標
/tp @s 0 80 0
/tp @s -0 80 -0
```


座標とその指定の仕方


コマンドとは文字の入力によって、Minecraftを操作する機能のことです。

<Note color="green">
コードビルダーを十分に扱えるようになっておくと、コマンドが理解しやすくなります。
必須ではありませんが、事前に学んでおくのがおすすめです。
</Note>


command?

マインクラフト世界を操作して<br />新たにルールを追加する

コマンド


最初にコマンドを使うための設定を確認しておきましょう。
必要な設定はひとつだけで「チートの実行」を有効にすることだけです。

## 必ず設定すること

### 「チートの実行」を有効にする

「チートの実行」が有効になっていないと、会話用などのごく一部のコマンドしか使えません。
それ以外のコマンドを使うためには、**設定画面から「チートの実行」を有効に**してください。

<Note color="amber" title="チートを有効にすると実績解除ができなくなる">
チートを一度でも有効にすると、それ以降は実績解除ができなくなります。
普段使っているサバイバルワールドの設定を変えずに、コマンド用の新しいワールドを作ってください。
</Note>

<Fig file="cheat.jpg" width={1280} height={720} />

<Note color="blue" title="クリエイティブモードでは自動でチートが有効になる">
  クリエイティブモードに設定すると、この「チートの実行」も自動的に有効になります。実際には、このクリエイティブモードの設定をするだけの方が簡単です。
</Note>

以降のページではクリエイティブモードであるとして進めていきます。

コマンドを使うために必要な設定はこれだけです。

## 他のおすすめ設定

あとは、必須ではありませんが、変更しておくと便利な設定があります。
これは後からいつでも設定できるので、ワールド制作時でなくても構いません。
また、コマンドで設定を切り替えることもできます。

### 「座標を表示」を有効する

コマンドを扱う上で、自分の位置を正確に把握することは大切です。
座標表示欄が邪魔にならない限りは表示しておくとよいでしょう。

ちなみに、この座標の表示チート扱いではないので、はサバイバルモードで有効にしても実績は解除できます。
普段から座標を表示しておき座標に慣れておいてください。

<Fig file="coordinate.jpg" width={1280} height={720} />

### 「常に昼間」を有効にする

通常は常に昼の方が見やすいので便利です。
夜にしたい場合はコマンドで自由に時間を操作できるので、時間が経過しなくても問題ありません。

<Fig file="alwaysday.jpg" width={1280} height={720} />

### 「天気を変化」を無効にする

晴れの方が見やすく静かなので、最初の晴れの状態で固定します。

雨を降らせたい場合にもその雨が続いて欲しいので、固定されている方がつごうが良いです。
天気はコマンドで自由に操作できるので、天気が変わるのを待つ必要はありません。

<Fig file="weather.jpg" width={1280} height={720} />


コマンドを使うための設定


ターゲットセレクタとは使用するコマンドを目的の対象に絞り込むための方法です。

## 変数(へんすう)

<Table>
  <tbody>
    <tr>
      <th>
        <code>@s</code>
      </th>
      <td>self</td>
      <td>コマンド実行者自身</td>
    </tr>
    <tr>
      <th>
        <code>@p</code>
      </th>
      <td>player</td>
      <td>最も近いプレイヤー1人</td>
    </tr>
    <tr>
      <th>
        <code>@r</code>
      </th>
      <td>random</td>
      <td>ランダムに選ばれたプレイヤー1人</td>
    </tr>
    <tr>
      <th>
        <code>@a</code>
      </th>
      <td>all players</td>
      <td>すべてのプレイヤー</td>
    </tr>
    <tr>
      <th>
        <code>@e</code>
      </th>
      <td>entities</td>
      <td>すべてのエンティティ</td>
    </tr>
  </tbody>
</Table>

### @s: コマンドを使った人

コマンドを実行した**エンティティ自身**を対象にします。

```bash
# 自分にダイヤモンドを渡す
/give @s diamond

# 自分を10ブロック上に移動させる
/tp @s ~ ~10 ~
```

<Note color="amber" title="コマンドブロックでは無効">
  <code>@s</code>
  をコマンドブロックで使用した場合、そのコマンドは無効になります。コマンドブロックはエンティティではないためです。コマンドブロックで
  <code>@s</code>を使用するのはよくある間違いです。
</Note>

`/execute`を用いればプレイヤー以外のエンティティでも`@s`を使うことができます。

### @p: 最も近いプレイヤー

コマンド実行者から最も近いプレイヤーが対象です。
主にコマンドブロックや`/execute`と合わせて使用します。

プレイヤー自身が使用した場合は自分自身になり`@s`と同じになります。
これは自分に最も近いプレイヤーは自分であると判断されるためです。

```bash
# コマンドブロックから使うと、そのコマンドブロックから最も近いプレイヤー
/give @p diamond

# 最も近いクリーパーのところへ、そのクリーパーから最も近いプレイヤーを移動させる
/execute @e[type=creepr, c=1] ~ ~ ~ tp @p @s
```

`@p` = `@a[c=1]` = `@e[type=player, c=1]`

### @a: すべてのプレイヤー

すべてのプレイヤーを対象にします。

```bash
# すべてのプレイヤーにダイヤモンドを与える
/give @a diamond

# すべてのプレイヤーのゲームモードをサバイバルに変更する
/gamemode @a s
```

`@a` = `@e[type=player]`

### @r: ランダムに選ばれたエンティティ

そのまま使うとランダムに選ばれたプレイヤー1人を対象にします。
次で説明する**引数**を使うことでプレイヤー以外を対象にし、複数選ぶこともできます。

```bash
# ランダムに選らばれたプレイヤー1人にダイヤモンドを与える
/give @r diamond

# ランダムに選んだゾンビ2体を自分のところに呼び寄せる
/tp @r[type=zombie, c=2] @s
```

### @e: すべてのエンティティ

読み込み範囲内のすべてのエンティティを対象にします。
対象となるエンティティがとても多くなるので、通常は引数を加え絞り込んで使用します。
遠く離れすぎたモブは対象に入りません。

```bash
# すべてのエンティティを自分のところに呼び寄せる
/tp @e @s

# 落ちているアイテムを消す
/kill @e[type=item]
```

## 引数(ひきすう)

変数に加えることで対象をさらに細かく絞り込むことができます。

<Table>
  <tbody>
    <tr>
      <th>
        <code>name</code>
      </th>
      <td></td>
      <td>名前</td>
    </tr>
    <tr>
      <th>
        <code>type</code>
      </th>
      <td></td>
      <td>タイプ(エンティティの識別名)</td>
    </tr>
    <tr>
      <th>
        <code>family</code>
      </th>
      <td></td>
      <td>ファミリー(エンティティの分類)</td>
    </tr>
    <tr>
      <th>
        <code>tag</code>
      </th>
      <td></td>
      <td>
        <code>/tag</code>で付けられた値
      </td>
    </tr>
    <tr>
      <th>
        <code>scores</code>
      </th>
      <td></td>
      <td>
        <code>/scoreboard</code>で付けられた値
      </td>
    </tr>
    <tr>
      <th>
        <code>l</code>, <code>lm</code>
      </th>
      <td>level</td>
      <td>レベル(経験値で上昇する)</td>
    </tr>
    <tr>
      <th>
        <code>c</code>
      </th>
      <td>count</td>
      <td>上限数。近い順から。マイナスで遠い順から。</td>
    </tr>
    <tr>
      <th>
        <code>m</code>
      </th>
      <td>mode</td>
      <td>ゲームモード</td>
    </tr>
    <tr>
      <th>
        <code>r</code>, <code>rm</code>
      </th>
      <td>range</td>
      <td>中心からの距離での範囲</td>
    </tr>
    <tr>
      <th>
        <code>x</code>, <code>y</code>, <code>z</code>,<code>dx</code>, <code>dy</code>, <code>dz</code>
      </th>
      <td>dimension</td>
      <td>座標で指定する立方体の範囲</td>
    </tr>
    <tr>
      <th>
        <code>rx</code>, <code>rxm</code>
      </th>
      <td>roration x</td>
      <td>エンティティの顔の向いている方向。<br />南を正面と考えた時の顔の上下の向き(x軸回転)。</td>
    </tr>
    <tr>
      <th>
        <code>ry</code>, <code>rym</code>
      </th>
      <td>roration y</td>
      <td>エンティティの体の向いている方向(y軸回転)</td>
    </tr>
  </tbody>
</Table>

<Note color="blue">
  数が多く、とても複雑なものもありますが、初学者は<code>type</code>だけ理解すれば十分です。
</Note>

### name: 名前

名前を元にエンティティを絞り込みます。

* `@e[name=Steve]`: Steveという名前を持っている。
* `@e[name=!Steve]`: Steveという名前を持って**いない**。

プレイヤー以外のエンティティは、名札で名前をつけることができます。(エンダードラゴンなど例外あり)

コマンドでは`/summon`で呼び出す際に名前をつけることができます。

### type: 種類名

エンティティの種類で絞り込みます。
指定する名前は`/summon`で使うエンティティ名と同じです。

ビヘイビアーパックの`identifier`で定義されている値なので、自分のアドオンで追加したエンティティも指定できます。

* `@e[type=player]`: プレイヤーだけ。`@a`と同じ。
* `@e[type=!player]`: プレイヤー以外。

同じゾンビ族でもそれぞれで種類が違うのですべて別物として扱われます。
特に通常ゾンビと村人ゾンビが異なることに注意してください。

* `@e[type=zombie]`: ゾンビのみ。
* `@e[type=husk]`: ハスク(砂漠ゾンビ)のみ。
* `@e[type=drowned]`: ドラウンド(溺死ゾンビ)のみ。
* `@e[type=zombie_villager_v2]`: 村人ゾンビのみ。

落ちているアイテムといった特殊なエンティティも選ぶことができます。

* `@e[type=item]`: 落ちているアイテム
* `@e[type=armor_stand]`: 防具立て

### family: 分類名

分類名で絞り込みます。

* `@e[family=zombie]`: ゾンビ族で絞り込む。

`family`では`type`で別扱いになるゾンビ・ハスク・ドラウンドなどを一緒に扱うことができます。

ほとんどのエンティティは複数の属性を持っています。
例えばゾンビの場合は`zombie, undead, monster, mob`と4つ持っています。

`undead`にするとスケルトンなども含めることができます。
`monster`は敵対モブ全体です。
`mob`は友好的な動物までを含みます。

各エンティティがどのようなfamily属性を持っているかは、[エンティティ一覧](/data-entities/)を参考にしてください。

### tag: タグ

`/tag`で付けらた情報を元にエンティティを絞り込みます。

* `@e[tag=tagName]`: "tagName"タグを持っている
* `@e[tag=!tagName]`: "tagName"タグを持って**いない**

何も指定しないと特殊な操作になります。

* `@e[tag=]`: タグを**一切持っていない**
* `@e[tag=!]`: 少なくとも**1つ以上**のタグを持っている

タグの絞り込みは複数設定できます。

* `@e[tag=a, tag=b]`: タグ"a"と"b"を両方(すべて)持っている。(aかつb)
* `@e[tag=a, tag=!c]`: タグ"a"を持っていて、"c"を持って**いない**。

### scores: スコアボードの値

`/scoreboard`で付けられた値を元にエンティティを絞り込みます。
これだけ範囲の記法がJava版と同じです。

* `@e[scores={myscore=10}]`: "myscore"の値が10。
* `@e[scores={myscore=10..12}]`: "myscore"の値が10以上、12以下。
* `@e[scores={myscore=5..}]`: "myscore"の値が5以上
* `@e[scores={myscore=..15}]`: "mysocre"の値が15以下
* `@e[scores={foo=10,bar=1..5}]`: "foo"が10で"bar"が1以上5以下。

### l, lm: レベル

プレイヤーのレベルの状態で絞り込みます。

* `@e[l=3]`: レベル3以下。
* `@e[lm=3]`: レベル3以上。
* `@e[lm=3, l=3]`: レベル3のみ。

#### 使用例: レベルを使ってアイテム交換

```bash
# コマンドブロックから実行した場合
# 最も近いプレイヤーを交換対象として、レベルが3以上ならアイテムを与える
/give @p[lm=3] diamond
# レベルが3以上なら3レベル減らす（代金の支払い）
/xp -3L @p[lm=3]
```

### c: 上限数

選択する数を指定します。

普通に(<R t="プラス">正の数</R>で)使うと**近い方**から選ぶ。

* `@e[c=3]`: 近い方からエンティティ3体。
* `@a[c=1]`: 最も近いプレイヤー。`@p`と同じ。

<R t="マイナス">負の数</R>で指定すると**遠い方**から選ぶ。

* `@a[c=-1]`: 最も遠いプレイヤーを1人。
* `@e[c=-2, type=zombie]` ゾンビを遠い方から2体。

`@r`で使用すると距離に関係なく人数分選ぶ。

* `@r[c=2]`: 無作為(ランダム)にプレイヤーを2人選ぶ。

#### 使用例: 3番目に近いプレイヤーだけを選ぶ

```bash
# 近い方から3人選び対象タグをつける
/tag @a[c=3] add target
# 近い方から2人選び対象タグを取り除く
/tag @a[c=2] remove target
# 対象タグを持っている人(3人目)だけを選んでコマンドを実行する
/give @a[tag=target] diamond
# 対象タグを消す
/tag @a remove target
```

### m: ゲームモード

プレイヤーのゲームモードで絞り込みます。

* `@a[m=survival]`: サバイバルモードのプレイヤー
* `@a[m=!adventure]`: アドベンチャーモードではないプレイヤー

`/gamemode`と同じように`@a[m=s]`や`@a[m=0]`としても表記できます。

### x, y, z, dx, dy, dz: 座標

基準となる座標からの範囲で絞り込む。

* `x`, `dx`: x軸の座標範囲
* `y`, `dy`: y軸の座標範囲
* `z`, `dz`: z軸の座標範囲

少なくともどれか1組の設定が必要。

<div className="sm:grid grid-cols-2 gap-6">
  <div className="my-3">
    <div id="js-canvas-xyz0"></div>

* `@e[x=0, dx=4]`

実行者を基準にして(~0, ~0)からx軸方向に4ブロックが範囲。
高さは実行者と同じ1ブロック。

  </div>
  <div className="my-3">
    <div id="js-canvas-xyz1"></div>

* `@e[x=-2, y=0, z=-2, dx=1, dy=255, dz=1]`

実行者から(~-2, ~-2)の1ブロックが範囲。高さは0~255すべて。

  </div>
  <div className="my-3">
    <div id="js-canvas-xyz2"></div>

* `@e[x=-2, z=-2, dx=4, dz=6]`

(~-2, ~-2)からx軸に+4ブロック、z軸に+6ブロック分が範囲。
yを省略しているので、高さは実行者と同じ1ブロック分。

  </div>
  <div className="my-3">
    <div id="js-canvas-xyz3"></div>

* `@e[x=-3, z=-3, dx=6, dz=1]`
* `@e[x=-3, z=2, dx=6, dz=1]`
* `@e[x=-3, z=-2, dx=1, dz=4]`
* `@e[x=2, z=-2, dx=1, dz=4]`

内側を含めたくない場合は、分けて実行する。

  </div>
</div>

#### 使用例: 範囲外のプレイヤーにウィザー状態にする

「範囲内」のエンティティにタグを付け、そのタグを**持っていない**ことを条件とすることで、「範囲外」のエンティティを対象にできます。

```bash
# isInArea(範囲内にいる)タグを初期化する(*1)
/tag @a remove isInArea
# 範囲内のプレイヤーにisInAreaタグを与える
/tag @a[x=-10, y=0, z=-10, dx=20, dy=255, dz=20] add isInArea
# isInAreaタグを持っていないプレイヤーにウィザーをかける
/effect @a[tag=!isInArea] wither 999 0 true
```

<small>*1. 毎回消さないと、一度でも範囲内にいた場合は常に有効になってしまう。つまり、後から範囲外に出た場合や、後から範囲内に入ってきた人を判定できない。</small>

### r, rm: 距離

実行者からの<R t="range">距離</R>で絞り込む。

* `r`: 半径の内側
* `rm`: 半径の外側

下のグラフは2次元平面ですが、実際には3次元空間なので、円形ではなく球形になります。(円柱ではない)

<div className="sm:grid grid-cols-2 gap-6">
  <div className="my-3">
    <div id="js-canvas-r1"></div>

* `@e[r=4]`

半径4ブロックより内側。

  </div>
  <div className="my-3">
    <div id="js-canvas-r2"></div>

* `@e[rm=2]`

半径2ブロックより外側。

  </div>
  <div className="my-3">
    <div id="js-canvas-r4"></div>

* `@e[rm=2, m=4]`

「半径2ブロックより外側」<R t="and">かつ</R>「半径4ブロックより内側」。
つまり色が重なっている場所だけが対象。

  </div>
  <div className="my-3">
    <div id="js-canvas-r3"></div>

* `@e[rm=2, m=4]`

最終的にこの範囲だけが対象になる。

  </div>
  <div className="my-3">
    <div id="js-canvas-r6"></div>

* `@e[r=2]`
* `@e[rm=4]`

「半径2ブロックより内側」<R t="or">または</R>「半径4ブロックより外側」。2回に分けて実行する。
`@e[r=2, rm=4]`の場合は、どこも重ならないので誰も対象になりません。

  </div>
</div>

### ry, rym: 体の向き

対象エンティティがどの方向を向いているかで絞り込みます。
y軸を基準にした<ruby>回転<rt>rotation</rt></ruby>。

* `ry`: 最大値
* `rym`: 最小値

z方向(南)を0とした時計回りの角度で指定します。
東方向はマイナスの角度で指定するので、北を-180として時計回りで再び北に戻る180までが範囲です。
~-181,180~は範囲外としてエラーになります。0~360では指定できません。

<div className="sm:grid grid-cols-2 gap-6">
  <div className="my-3">
    <div id="js-canvas-rt1"></div>

* `@e[rym=0, ry=45]`

真南から時計回りに45度まで。

  </div>
  <div className="my-3">
    <div id="js-canvas-rt2"></div>

* `@e[rym=-45, ry=0]`

真南から反時計回りに45度まで。東側の指定にはマイナスを使う。

  </div>
  <div className="my-3">
    <div id="js-canvas-rt3"></div>

* `@e[rym=-45, ry=45]`

南を向いているエンティティ。

  </div>
  <div className="my-3">
    <div id="js-canvas-rt4"></div>

* `@e[rym=90, ry=180]`
* `@e[rym=-180, ry=-90]`

少しでも北を向いているエンティティ。
180度をまたぐ場合は2回に分けて実行する。

  </div>
  <div className="my-3">
    <div id="js-canvas-rt5"></div>

* `@e[rym=0, ry=0]`

真南を向いているエンティティのみ。

  </div>
  <div className="my-3">
    <div id="js-canvas-rt6"></div>

* `@e[rym=-180, ry=-180]`

真北は-180で指定する。180では動かない。

  </div>
</div>

### rx, rxm: 顔の向き

対象エンティティの顔がどの角度を向いているかで絞り込みます。
x軸(上下)を基準にした回転(rotation)。

* `rx`: 最大値
* `rxm`: 最小値

水平線を0とした角度となり、真上が-90度、真下が+90度です。
後ろはありません。

<div className="sm:grid grid-cols-2 gap-6">
  <div className="my-3">
    <div id="js-canvas-rx1"></div>

* `@e[rx=0]`

水平線から上を向いてるエンティティ。

  </div>
  <div className="my-3">
    <div id="js-canvas-rx2"></div>

* `@e[rxm=-30, rx=60]`

正面から少し下までを向いているエンティティ。

  </div>
  <div className="my-3">
    <div id="js-canvas-rx3"></div>

* `@e[rxm=30]`

下を向いているエンティティ。

  </div>
  <div className="my-3">
    <div id="js-canvas-rx4"></div>

* `@e[rxm=0, rx=0]`

完全に水平線を向いているエンティティ。

  </div>
</div>


ターゲットセレクタ


<strong><R t="ジェイソン">JSON</R>形式</strong>とは、データの表記法の一種です。
一部のコマンドでこの形式を扱うことがある他、アドオンのデータのほとんどはこの形式で書かれています。

<strong>JSON(JavaScript Object Notation)</strong>
は文字通り**JavaScriptのオブジェクト**を元に作られました。

JavaScriptにとってJSONとは何か特別なものではなくただのオブジェクトである、という認識ができれば正しい記述ができるようになります。
（実際には完全に同じではありませんが）

よって、正確な理解のためには、JavaScript(または他のプログラミング言語)の基礎を学ぶ必要があります。

## JSON形式の書き方

例文を通してJSON形式について簡単な解説をします。
ここでは深く考えずに、だいたいこんな感じで書く、くらいの理解から始めてください。

### コマンドでは1行になっている

それでは`/give`や`/replaceitem`でつかうアイテムコンポーネントの記述の仕方を見ていきましょう。

```bash
# 「石・丸石」だけ壊せる「鉄のツルハシ」を与える
/give @s iron_pickaxe 1 0 {"minecraft:can_destroy":{"blocks":["stone","cobblestone"]}}
```

後半のこの部分がJSON形式で書かれた部分です。

```bash
{"minecraft:can_destroy":{"blocks":["stone","cobblestone"]}}
```

これは次のような記述が1行になっています。

```json
{
  "minecraft:can_destroy": {
    "blocks": ["stone", "cobblestone"]
  }
}
```

JSON形式とは本来は1行で書くものではなく、通常は上のように改行されたり、字下げ（インデント）をしてわかりやすいように書かれています。

しかしコマンドではチャット欄で入力できるように**無理矢理1行になっています**。
いきなり1行で書くのは難しいので、まずはこのように複数行に分けて書いてから、最後に1行へと直しましょう。

### 配列

ブロック名の部分は**配列**と呼ばれる形式です。

`,`<small>(コンマ)</small>で区切って複数書くことができます。
ブロック名は文字なので「`"`<small>(ダブルクォーテーション)</small>」で囲ってください。
これらが配列を意味する`[]`で囲まれているという構造です。

```javascript
// アイテム名が2つ入っている
["stone", "cobblestone"]

// 中身が1つでもちゃんとした配列（コンマなし）
["A"]

// これは[]が無いので、ただの文字
"stone"

// いくつでも続けることができる
["A", "B"]
["A", "B", "C", "D", "E"]
```

### オブジェクト

このような配列`[]`がオブジェクト`{}`の中に入っています。

```json
{
  "blocks": ["stone", "cobblestone"]
}
```

オブジェクト`{}`とは次のように、内容に名前を付けてまとめた構造のことです。
上の場合は1組しかありませんが、複数入れることもできます。

```json
{
  "名前1": "「名前1」の内容",
  "名前2": "「名前2」の内容",
  "名前3": "「名前3」の内容"
}
```

今回の場合は`blocks`という名前の箱の中にブロック名の配列`[]`が入っている、と考えてください。

さらにこのまとまりが`minecraft:can_destroy`という名前の箱に入っています。

```json
{
  "minecraft:can_destroy": "(blocksが入っているオブジェクト)"
}
```

これらをまとめると次の構造になります。最初に開いたものと同じです。

```json
{
  "minecraft:can_destroy": {
    "blocks": ["stone", "cobblestone"]
  }
}
```

「`minecraft:can_destroy`という名前の箱の中に`blocks`という名前の箱があり、さらにその中にブロック名のまとまり(配列)が入っている」という構造が見えましたか。

よって、このJSONで設定する内容は次のようになります。

1. 壊せるブロック(`can_destroy`)という設定をします
2. その対象ブロック(`blocks`)は`[]`の中のものにします

そしてこれを1行で書くと最初のコマンドの中での記述になります。

```json
{ "minecraft:can_destroy": { "blocks": ["stone", "cobblestone"] } }
```

1行にしたことでかなり読みづらくはなりましたが、意味を読み取れるでしょうか。

さらに色分けを抜いてみましょう。内容を理解していれば読めますが、どうでしょうか。

```txt
{"minecraft:can_destroy":{"blocks":["stone","cobblestone"]}}
```

しかし、書く場合には、慣れていてもいきなり1行で書くことはかなり難しいです。
普段はここでやったように、複数行に分けて書いてから1行に直して入力するようにしましょう。

### 複数組み合わせる

アイテムコンポーネントの要素は同時に使うことができます。
アイテムをインベントリに固定する次の要素を一緒に使ってみましょう。

```json
{
  "minecraft:item_lock": {
    "mode": "lock_in_inventory"
  }
}
```

オブジェクトは1つだけではなく複数の値を持つことができるのでした。
これを一緒に書くと次のようになります。
配列と同じように繋げる場合はコンマを入れてください。
ただし最後には付けてはいけません。

```json
{
  "minecraft:can_destroy": {
    "blocks": ["stone", "cobblestone"]
  }, // <- コンマを付けてつなげる
  "minecraft:item_lock": {
    "mode": "lock_in_inventory"
  } // <- 最後はコンマ無し
}
```

<Note color="amber">
  「最後にコンマをつけてしまう」「途中をコンマで繋げない」は
  <span className="font-bold">非常に起こりやすい失敗</span>
  です。動かなかったら、最初にここを確認しましょう。
</Note>

これらを1行にしてコマンドとして使うと次のようになります。

```txt
/give @s iron_pickaxe 1 0 {"minecraft:can_destroy":{"blocks":["stone","cobblestone"]},"minecraft:item_lock":{"mode":"lock_in_inventory"}}
```

複雑なだけでなくとても長いですね。
それでもここまでやってきたように、きちんと手順を踏めば理解して進めることができます。

* いきなり1行で書かず、複数行に分けて書いてから1行に直す
* コマンド上の1行でわからなければ複数行に改行してわかりやすくする


JSON形式とは


Bedrock版のブロック名とIDの一覧です。

<SearchBlocks />

<Note color="blue">
IDの先頭にある`minecraft:`は名前空間です。<br />
ほとんどの場合で省略できます。(付けても付けなくても良い)
</Note>

<Note color="amber">
上の内容はBedrock版リソースパックの翻訳ファイルから取得したものです。<br />
Java版とは名前やIDが異なる場合があります。<br />
一覧に載っていないブロックもあると思います。
</Note>


ブロック名の一覧と検索


Bedrock版のエンティティのデータです。

<SearchEntities />

<Note color="blue">
IDの先頭にある`minecraft:`は名前空間です。ほとんどの場合で省略できます。(付けても良い)
</Note>

<Note color="blue">
ファミリー名は、そのエンティティの初期値です。イベントによって付与されるファミリー属性は記載されていません。
</Note>

<Note color="amber">
上の内容はBedrock版リソースパックの翻訳ファイルから取得したものです。<br />
Java版とは名前やIDが異なる場合があります。
</Note>

## 公式Wiki

正確な値は公式Wikiから確認してください。

* [Java版 - データ値](https://minecraft.fandom.com/ja/wiki/%E3%83%87%E3%83%BC%E3%82%BF%E5%80%A4/Java_Edition)
* [Bedrock版 - データ値/エンティティID](https://minecraft.fandom.com/ja/wiki/%E3%83%87%E3%83%BC%E3%82%BF%E5%80%A4/Bedrock_Edition#.E3.82.A8.E3.83.B3.E3.83.86.E3.82.A3.E3.83.86.E3.82.A3_ID)


エンティティの一覧と検索

アイテム名一覧


教材用にまとめた各種データを載せています。

より正確なデータは[公式Wiki(特に英語版)](https://minecraft.fandom.com/wiki/Minecraft_Wiki)を読んでください。


データ


この記事では、アドオン開発用に必要な開発環境の設定をします。

ここで設定するアプリ・ソフトはプロが実際の現場で使っているものと、まったく同じです。
これらの使い方を覚えておくと、実際の開発現場でも役立ちます。

## PCの初回設定

### プログラミング用エディターのインストール

プログラミングを始めるには専用のエディターが必要です。
インストールがまだの方は、次の記事を参考にエディターをインストールしてください。

<LinkCard slug="install-vscode" />

### Node.jsのインストール

アドオン制作を簡単に行うためのツール(npm)の導入をするためにNode.jsをインストールします。

<ExButton href="https://nodejs.org">Node.js</ExButton>

特別な理由がない限りは、LTSバージョンの方をダウンロード・インストールしておきましょう。

LTSとはLong-Term Supportの略で、長期サポート版のことです。
今回の目的では、バグがあるかもしれない最新版よりも、少し古くても安定してるバージョンの方が最適です。
（最新版でもまず問題は起こりませんが）

### gulpCLIをインストール

「gulp」とは一連の操作を自動で実行するためのツールです。

コマンドラインを開き、次のコマンドを実行してgulpコマンドを実行できるようにします。

```powershell
npm install gulp-cli --global
```

## プロジェクトの初回設定

### 1. テンプレートをダウンロードして展開する

次のリンクからテンプレートをダウンロードしてください。（公式ドキュメントを参考にして、筆者が独自に作成したテンプレートです。）

画面上方の緑色の「Code」ボタンから、「Download ZIP」を選択することで、ダウンロードできます。

<ExButton href="https://github.com/akihamitsuki/addon-development-template">アドオン開発テンプレート</ExButton>

ダウンロードしたZipファイルを展開してください。

展開したプロジェクトフォルダーはどこに置いても構いません。
あとで移動させることもできます。

### 2. プロジェクトフォルダーをVS Codeで開く

プロジェクトを開いたとき、推奨拡張機能が表示されるので、同時にインストールしておくと便利です。
必須ではありません。

### 3. npmパッケージをインストールする

展開したフォルダーをVS Codeで開きます。
この時`README.md`がプロジェクトの最上位にあるか確認してください。
階層が重要なので、余計なフォルダーが間に挟まっていたりする場合は開きなおしましょう。

正しい階層であれば、その状態でVS Codeのターミナル（コマンドラインを実行する場所）を開きます。(`Ctrl + Shift + @`)

次のコマンドでnpmパッケージをプロジェクトにインストールします。
（プロジェクトフォルダーに必要なファイルをダウンロードするだけで、PC上のソフトウェアとしてインストールされるわけではありません）

```powershell
npm install
```

`package.json`で指定されているファイルをインストールするという意味です。

`npm`コマンドは「Node.js」をインストールと同時に一緒にインストールされています。
このコマンドが認識されなければ、Node.jsのインストール状況を確認してください。

### 4. プロジェクト名を設定する

`gulpfile.js`を開き`projectName`を自分のプロジェクト名に変更します。

```javascript:gulpfile.js
// TODO: 自分のプロジェクト名に変更する
const projectName = 'my_project';
```

この値がアドオンのフォルダー名になります。

### 4. manifest.jsonを変更する

`behavior_pack/manifest.json`を開いて、自分のプロジェクト用に変更してください。

その際、`header.uuid`だけは必ず変更してください。

`dependencies`の値はスクリプトを動かすためのAPIをMinecraftに読み込む設定です。
削除しないでください。

## プロジェクトを開きなおす度に実行すること

### コマンドの実行ポリシーを変更する

このコマンド実行ポリシーを変更せずに、後述のgulpコマンドを実行しようとすると、次のような警告文が出て止まります。

> gulp : このシステムではスクリプトの実行が無効になっているため...(以下略)

gulpではファイルを操作するので、初期設定ではセキュリティ上の制限がかかっています。  
この制限を解除するためには次のコマンドを実行します。

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```

コマンドが具体的に何をしているかは、次の記事を参考にしてください。

[about_Execution_Policies](https://docs.microsoft.com/ja-jp/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.2)

### gulpを使ってデプロイ

デプロイとは「使えるようにする」というような意味です。
上で作成した内容は、そのままでは使えません。
これを使える形にする一連の操作を自動化してあるので、あとはそれを使うコマンドを実行します。

コマンドは次の方法A、方法Bの2通りがあります。

実行したら、Minecraftのワールドにアドオンを適用し、使えるかを確認してください。

#### A. コマンド実行時にデプロイ

次のコマンドを実行すると、使用した段階の内容がアドオンとして使えるようになります。

```powershell
gulp
```

実行後は`/AppData/.../com.mojang/development_behavior_packs/[project name]`に、使用できる形でファイルがコピーされています。

再びコマンドを入力することで、ファイルを上書きして更新します。

#### B. ファイル更新毎にデプロイ（推奨）

ファイルを更新する度に、Aと同じ処理を自動で実行します。

```powershell
gulp watch
```

ファイルの監視を停止する場合は`Ctrl + c`を押してください。

## 参考

* [https://docs.microsoft.com/ja-jp/minecraft/creator/documents/scriptinggettingstarted](https://docs.microsoft.com/ja-jp/minecraft/creator/documents/scriptinggettingstarted)
* [https://github.com/microsoft/minecraft-scripting-samples/](https://github.com/microsoft/minecraft-scripting-samples/)


開発テンプレートの使い方

アドオン開発テンプレートの使い方


ゲームテストフレームワークで基本的なプログラムを組む手順を解説します。

<Note color="amber">
この記事ではJavaScriptとTypeScriptの基礎を理解していることを前提に進めていきます。

当サイトではこれらの解説記事は**まだ**ありませんが、YouTubeなどにたくさんの解説動画がアップロードされているので、ひとまずそちらを参考にしてください。
</Note>

## 開発環境を整える

まずは次の記事から開発環境とテンプレートを使えるようにしておいてください。

<LinkCard slug="add-on-development-template" />

### manifest.jsonの設定

まずは`manifest.json`を、今回のチュートリアルように書き換えましょう。

`//`で始まる行はコメントなので、実行時に無視されます。
通常のJSON形式はコメントを書くとエラーになりますが、マインクラフトのアドオンではエラーにならないので、書いても構いません。(書かなくても良い)

```json:manifest.json
{
  "format_version": 2,
  "header": {
    // アドオンの名前です。わかりやすい名前をつけましょう
    "name": "ゲームテストフレームワークのチュートリアル",
    // アドオンの説明です。
    "description": "チュートリアル用に作成したアドオン",
    // 固有のUUIDです。必ず変更してください。
    "uuid": "59d5861d-0abd-4d52-8e56-a41d981a8a01",
    // このアドオンのバージョン名です。公開しない場合は気にしなくて構いません。
    "version": [0, 0, 1],
    // マインクラフト本体の必須バージョンです。とりあえず現行のバージョン名を付けておけば問題ありません。
    "min_engine_version": [1, 19, 0]
  },
  "modules": [
    // ゲームテストフレームワークを使用する設定です
    {
      // 説明欄
      "description": "Use Game Test Framework",
      // 1.18と1.19で設定が異なります。これらは1.19以降の設定です。
      "language": "javascript",
      "type": "script",
      // UUIDです。ここも独自の値に変更してください。
      "uuid": "0a4bbea0-a6fa-44b8-a207-d41bf9e872d6",
      // モジュールのバージョン名です。上と同様に公開しないのであれば変更しなくて構いません。
      "version": [0, 0, 1],
      // 最初に実行されるファイル名です。
      "entry": "scripts/main.js"
    }
  ],
  // 依存する他のアドオン・パッケージです
  // これらはゲームテストフレームワークで使用するパッケージのことです。
  // この設定をしないとゲームテストフレームワークは使えないので、削除しないでください。
  // バージョン名は頻繁に変わるので注意してください
  "dependencies": [
    {
      "uuid": "6f4b6893-1bb6-42fd-b458-7fa3d0c89616",
      "version": "1.0.0-beta"
    },
    {
      "uuid": "2bd50a27-ab5f-4f40-a596-3641627c635e",
      "version": "1.0.0-beta"
    }
  ]
}
```

### main.tsの内容を削除

次に`scripts/main.ts`を開いてください。
内部にはサンプルのコードが書かれていますが、今回は最初から記述するので、中の記述はすべて削除してください。

`scripts/`の中には他のファイルもありますが、一旦無視してください。

## 例文を作る

プログラムは、「X」をしたときに「A」をする。というのが基本形です。

最初の例文として、「`hi`と入力したとき」に「`hello`とメッセージを返す」だけの簡単な所から作ってみましょう。

これをプログラミングしやすい流れに分解すると、次のようになります。

1. チャット欄からメッセージが送信されたとき
2. そのメッセージの内容が`hi`ならば
3. `hello`の内容で、`/say`コマンドを実行する

### 1. アドオン用のパッケージをインポートする

Minecraft本体と連携する部分は、Minecraft側が用意してくれている要素を使います。
まずは、この要素を別パッケージからインポートします。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';
```

これは、`mojang-minecraft`パッケージから、すべて(`*`)の要素を`mc`という名前でインポートするという意味です。

<Note color="amber">
このようにすべて取得するのは、あまり推奨されない少し特殊な方法です。
開発が進むと、このパッケージからは数多くの要素をインポートすることになるので、記述の簡略化を優先して、まとめてインポートすることにしています。
</Note>

この`mojang-minecraft`パッケージの内容は、どこからきているのかというと、`manifest.json`での次の記載によって、Minecraft本体が内部のパッケージを読み込んでいます。

```json
{
  "uuid": "6f4b6893-1bb6-42fd-b458-7fa3d0c89616",
  "version": "1.0.0-beta"
},
```

開発環境上では、npmからインストールしたTypeScriptの定義ファイルによって、どのような要素がインポートされてくるかの型情報だけを見ることができます。（直接Minecraft本体から情報を取得しているわけではありません）

### 2. イベント関数を作成する

次は、そのプログラムで何をするかの関数を作成していきましょう。

今回の関数名は`hello`にしておきます。引数名は`event`です。
ここの名前は自由に設定できます。
どのような名前にしても良いですが、必ずわかりやすい名前にしてください。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

// 関数の枠組みを作成
function hello(event) {
}
```

### 3. 引数の型をインポートして設定する

イベント内容によって、引数`event`にわたってくる値は変わります。
どんな値かを指定するために、TypeScriptの記法で型を設定しましょう。
イベントの方は`mc`の中にあるので、ドットで繋げて取得します。

今回はチャット送信時なので`ChatEvent`に設定します。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

// 引数に型を付ける(TypeScirptの機能)
function hello(event: mc.ChatEvent) {
}
```

この型を設定することにより、`event`引数にどのような値が渡ってくるかをエディター上で確認できるようになります。
また、間違った値を取得しようとするとエラーとして検出してくれます。

このようにTypeScriptを使って型を指定しなかった場合は、Minecraftで動かしてみるまでエラーが出ません。
(エラーで動かない上に、どこのエラーかもわかりません)

`ChatEvent`の他に、どのようなイベントがあるかは[公式ドキュメント](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/mojang-minecraft)から探す必要があります。
ただ基本的に英語であり、プログラミングに慣れている人でないと、ドキュメントの使い方がわからないと思いますので、当サイトの記事も併せて参考にしてください。

<LinkCard slug="mojang-minecraft-events" />

### 4. 引数からメッセージを取得して判定

送信したメッセージは`event.message`で取得でき、これを`if`文で判定します。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

function hello(event: mc.ChatEvent) {
  // イベントからメッセージを取得し、if文で判定
  if (event.message === 'hi') {
  }
}
```

エディターが正しく設定されていれば、`event.`と入力した段階で`message`の候補が現れます。

### 5. 引数の情報からコマンドを実行する

今回の追加メッセージは`/say`コマンドを使うことにします。
コマンドはどの次元(`dimension`/オーバーワールド、ネザー、ジ・エンド)で使われているかの判定が必要ですが、今回は送信者から取得できる次元情報を使うことにします。（つまり送信者と同じ次元にする）

1. `event`オブジェクトからメッセージの送信者である`sender`オブジェクトを取得
2. `sender`オブジェクトからその次元情報である`dimension`オブジェクトを取得
3. さらに、その`dimension`オブジェクトにある`runCommand()`メソッドを実行
4. 引数としてコマンドの文字列を渡す

これらを1行で書くと次のようになります。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

function hello(event: ChatEvent) {
  if (event.message === 'hi') {
    // イベントの情報を元に、スラッシュコマンドを実行
    event.sender.dimension.runCommand('say hello');
  }
}
```

ゲームテストフレームワークでは、他にコマンドよりも効率の良い処理方法がありますが、ひとまずは使い慣れたコマンドを積極的に使っていってください。
慣れてきたら、ひとつずつ専用の処理方法を覚えていきましょう。

<Note color="blue" title="コマンド文の先頭にスラッシュは付けない">
基本的にチャット欄で使う場合に、通常のチャットと区別するためにスラッシュが用いられますが、それ以外ではスラッシュは使いません。
どちらかというと、チャット欄でスラッシュを付ける記法の方が特殊な使い方です。
</Note>

### 6. この関数をイベントに登録する

最後に、この関数をMinecraftが認識できるようにイベントに登録します。

`mc`の中から`world`情報を取得し、その中の`event`情報を取得、さらにその中の`beforeChat`イベントを取得します。

このイベントの`subscribe()`メソッドに`hello`関数を渡して、イベントを登録します。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

function hello(event: ChatEvent) {
  if (event.message === 'hi') {
    event.sender.dimension.runCommand('say hello');
  }
}

// hello関数を「BeforeChat」イベントに登録(subscribe)する
mc.world.events.beforeChat.subscribe(hello)
```

<Note color="amber">
最終行の`hello`関数にカッコをつけてはいけません。

* `hello()`は関数の実行を表します。
* `hello`だけだと関数自体を表します。

ここでは登録用の関数を渡したいので、カッコは付けません。
</Note>

## デプロイして実行

完成したら、使用している開発テンプレートの操作に従って、デプロイしましょう。

`Ctrl + Shift + @`でVS Code上のターミナルを開き次のコマンドを実行しましょう。

```bash
gulp
```

アドオンを適用したワールドのチャット画面で`hi`と送信したときに、`hello`と返ってくれば成功です。


スクリプト作成チュートリアル

ゲームテストフレームワークの作成チュートリアル


現在(`BE:1.19`)の仕様では、アドオンの機能として、**JavaScript**というプログラミング言語で書かれたプログラムを実行できます。

このアドオンの機能は「ゲームテストフレームワーク」と呼ばれています。
ゲームテストとあるように、名前としてはゲーム内の振る舞いをテスト（試験・確認）するために使用するものですが、それだけではなく独自ゲームの開発が可能です。

ここではテスト機能部分は後回しにして、これまでのコマンドを置き換える機能を学んでいきましょう。


アドオンの機能を使った<br />JavaScriptによるプログラミング

スクリプト


ゲームテストフレームワークのスクリプトからもスラッシュコマンドを実行できます。

スラッシュコマンドに慣れている方は、細かいスクリプトの処理を覚える前に、スクリプト上でスラッシュコマンドを使えるようになっておくと便利です。

## エンティティまたは次元のどちらかから実行する

スラッシュコマンドの使用は、エンティティ(`Entity`)、または次元(`Dimension`)が持っている`runCommand()`メソッドを使って実行できます。

どちらを使うかで、結果が少し異なるので、適切な方を選ぶ必要があります。

とは言っても、初めのうちはあまり気にする必要はありません。
何かおかしいと思ったら、2種類の使い方があることを思い出し、あとで修正すればそれで十分です。

例文では`BeforeChatEvent`を使っているので、事前にイベントの使い方を確認しておいてください。

<LinkCard slug="mojang-minecraft-events-chat" />

### エンティティから実行した場合

そのエンティティ自身がコマンドを使ったことになります。
つまり、`@s`が有効になります。

下の例の場合は、メッセージの送信者がコマンドを使用したことになります。

```typescript
import * as mc from 'mojang-minecraft';

export function runCommandByEntity(event: mc.BeforeChatEvent) {
  if (event.message === 'byentity') {
    // 使用するエンティティはメッセージの送信者
    const entity = event.sender;

    // 送信者自信がコマンドを使用したという扱いになるので
    // 雷はこのコマンドを実行したプレイヤーに落ちる
    entity.runCommand('summon lightning_bolt');
    // メッセージを送信すると送信者はプレイヤーの名前になる
    entity.runCommand(`say success`);

    event.cancel = true;
  }
}

mc.world.events.beforeChat.subscribe(runCommandByEntity);
```

### 次元から実行した場合とエラー処理

次元のメソッドからコマンドを実行した場合、`@s`を使うとエラーになります。

エラーが起こりうる場面では[try...catch文](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Statements/try...catch)を使います。

`try{}`の中でエラーが起きた場合、そこでプログラム全体を停止させず、`catch{}`に移動してプログラムの処理を続けるという記法です。

```typescript
import * as mc from 'mojang-minecraft';

export function runCommandByDimension(event: mc.BeforeChatEvent) {
  if (event.message === 'bydimension') {
    // 使用者はメッセージ送信者のいる次元(オーバーワールドやネザーのこと)
    const dimension = event.sender.dimension
    try {
      // 次元から@sを使うとエラー
      dimension.runCommand(`give @s apple`);
      // 上のコマンドが成功したら次のメッセージが表示されるはず
      // 実際は実行されずにcatch文に移動する
      dimension.runCommand(`say success`);
    } catch (error) {
      // エラーが起きたらこちらが表示される
      // 送信者は「システムメッセージ」になる
      dimension.runCommand(`say error: ${error}`);
      // -> {"statuCode": -2147352576, "statusMessage": "セレクターに合う対象がありません"}
    }

    event.cancel = true;
  }
}

mc.world.events.beforeChat.subscribe(runCommandByDimension);
```

エラーの内容は次のようになります。

次元自体はエンティティではないため、`@s`の対象が存在しないという単純なエラーです。

```json
{
  "statuCode": -2147352576,
  "statusMessage": "セレクターに合う対象がありません"
}
```

エラー表示が必要なければ、`catch`部分は空にしてください。
この場合、エラーが起きても全体を停止させず、エラー表示も出さず、そのまま処理を続けます。

```typescript
try {
  // プレイヤーのインベントリを空にする。ただし元から空だとエラー
  player.runCommand(`clear`);
} catch {
  // エラーの場合でも処理を止めずに続ける。エラー表示もしない。
}
```

<Note color="blue">
コマンド部分で停止してしまう場合は、このようなエラーが原因です。
エラー箇所を補足したり、処理を中断しないためにも、すべての`runCommand()`メソッドは、`try...catch文`の中に入れることをお勧めします。
</Note>

## コマンド結果を受け取る

コマンドを実行した後は、その実行結果をJSON構造のオブジェクトで受け取れます。

実行結果を受けて、さらに何かを行いたい場合に活用できそうです。

```typescript
import * as mc from 'mojang-minecraft';

export function runCommandResult(event: mc.BeforeChatEvent) {
  if (event.message === 'commandresult') {
    try {
      // コマンドの結果をJSON構造のオブジェクトで受け取れる
      const result = event.sender.runCommand('effect @s levitation 3 1 true');
      // 内容をすべて表示。中に何が入っているかはコマンドにより異なる
      event.sender.runCommand(`say ${JSON.stringify(result)}`);
      // JSON構造なので、オブジェクトとして内容を取り出して使うことができる
      event.sender.runCommand(`say ${result.statusMessage}`);
      event.sender.runCommand(`say 強さ:${result.amplifier}, 秒数:${result.seconds}`);
    } catch (error) {
      event.sender.runCommand(`say error ${error}`);
    }

    event.cancel = true;
  }
}

mc.world.events.beforeChat.subscribe(runCommandResult);
```

取得内容は使用したコマンドによって変わります。

上の例の場合は`/effect`なので、強さ・効果時間・対象プレイヤーなどが入っています。

```json
{
  "amplifier": 1,
  "effect": "levitation",
  "player": ["Steve"],
  "seconds": 3,
  "statusCode": 0,
  "statusMessage": "Steveに浮遊*1を3秒間与えました"
}
```

## コマンド文にはテンプレートリテラル記法を使おう

文章の中に変数を埋め込みたい場合は「テンプレートリテラル」という記法を使うのがお勧めです。

次のどちらを使っても最終結果は同じですが、コードの見やすさが異なります。
状況に合わせて便利な方を使ってください。

### 文字列の結合

まず最初に旧来の記法を見てみましょう。
これは単純に文字列同士を`+`で結合しているだけです。

```javascript
const target = 'Steve';
const item = 'apple';
const command = 'give ' + target + ' ' + item;
// -> give Steve apple
```

コマンドの場合は途中に半角スペースを入れる必要があるので、短文ですが結構ややこしいことになってしまっています。

こちらの方法では、正しくスペースを入れられずエラーになってしまいそうです。

### テンプレートリテラル

次にテンプレートリテラルです。
この記法を使うには全体をバッククォート`@ + Shift`で囲み、その中に`${変数名}`という記号を用いて変数を加えます。

<Note color="amber">
テンプレートリテラルで囲む記号は、通常の文字列で使用する記号と異なることに注意してください。
</Note>

```javascript
const target = 'Steve';
const item = 'apple';
const command = `give ${target} ${item}`;
// -> give Steve apple
```

全体的に見やすくなり、コードも短くなりました。
どこにどれだけ半角スペースが入っているのかも分かりやすくなっています。

## 非同期で実行する

<Note color="amber">
この項目は難しいので、初心者の方は気にせず読みとばしてください。
</Note>

コマンドは`runCommandAsync()`を使うと**非同期**に実行できます。
非同期とはものすごく簡単にいうと、すぐに実行せずに、他の処理が終わった後に余った時間で実行することです。

上で書いたような同期的な処理では、コマンドの実行が終わるまでMinecraft上の処理が停止します。
たまに処理落ちするのはこれが原因です。

一方、非同期処理では、ゲームのメイン処理の手が空いた時に実行するので、処理落ち的なことは起こりません。

基本的には同期処理である`runCommand()`を使えば問題ありませんが、何千・何万回もコマンドを実行するような使い方だとゲーム自体が停止し強制終了してしまいます。
筆者の環境では`/setblock`を1万5千回くらい連続で実行すると、Minecraft自体が強制終了しました。
このような場合には非同期処理で、メインの処理の合間に実行してやれば途中で停止させずにコマンドを実行できます。

```typescript
import * as mc from 'mojang-minecraft';

export function runCommandAsync(event: mc.BeforeChatEvent) {
  if (event.message === 'async') {
    const player = event.sender;

    for (let i = 0; i < 3; i += 1) {
      // 非同期処理を登録する、この時点では実行されない
      player
        // この戻り値はPromise型
        .runCommandAsync(`say *** async: ${i + 1}`)
        // Promiseなので、.then()で繋げることができる
        // 結果は成功数だけ取得できる
        .then((result) => player.runCommandAsync(`say --- success(1): ${i + 1} / ${result.successCount}`))
        .then((result) => player.runCommandAsync(`say --- success(2): ${i + 1} / ${result.successCount}`))
        .then((result) => player.runCommandAsync(`say --- success(3): ${i + 1} / ${result.successCount}`))
        // エラー内容は取得できない
        .catch(() => player.runCommandAsync(`say error`));
    }

    // 最後に同期処理のコマンドを実行する
    for (let i = 0; i < 3; i += 1) {
      try {
        player.runCommand(`say +++ sync: ${i + 1}`);
      } catch {
      }
    }
  }
}

mc.world.events.beforeChat.subscribe(runCommandResult);
```

上の場合、次のように順番に実行・表示されます。

```bash
# メイン処理の中の同期処理が順番に実行される
+++ sync: 1
+++ sync: 2
+++ sync: 3
# BeforeChatイベントが終わったので送信したメッセージが表示される
async
# メイン処理が終わったので、非同期処理が実行される
*** async: 1
*** async: 2
*** async: 3
# 非同期処理が成功したので.then()で繋げた内容が実行される
--- success(1): 1
--- success(1): 2
--- success(1): 3
# 繋げた非同期処理が成功したので、さらに繋げた内容が実行される
--- success(2): 1
--- success(2): 2
--- success(2): 3
# 繋げた非同期処理が成功したので、さらに繋げた内容が実行される
--- success(3): 1
--- success(3): 2
--- success(3): 3
```

## 参考

* [テキストを扱う — JavaScript での文字列](https://developer.mozilla.org/ja/docs/Learn/JavaScript/First_steps/Strings)
* [try...catch](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Statements/try...catch)
* [Entity Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/entity)
* [Dimension Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/dimension)


スラッシュコマンドを実行する


ゲームテストフレームワークはアドオンのビヘイビアーパックから実行するので、まずはビヘイビアーパックのプロジェクトを作成します。

ここではごく単純な動かし方だけ解説して、そのあとで一気に効率的な開発環境の構築に進みましょう。

まず、最小限の構成でゲームテストフレームワークからプログラムを実行してみます。

## ビヘイビアーパックを作る

次の構成でファイルを作成してください。
この2つのファイルが最小構成です。

```txt
com.mojang
 ┗ behavior_pack_development
   ┗ [ビヘイビアパック名]
     ┣ manifest.json
     ┗ scripts
       ┗ main.js
```

### 「manifest.json」ファイルを作る

`manifest.json`

今回のプロジェクトは使い捨てなので、丸ごとのコピペで構いません。

また、今回は動かしてみることだけが目的なので、細かい解説は省きます。
詳しく知りたい方は次回以降の解説記事に進んでください。

```json:manifest.json
{
  "format_version": 2,
  "header": {
    "name": "Add-on Development Template",
    "description": "Add-on development template.",
    "uuid": "59d5861d-0abd-4d52-8e56-a41d981a8a01",
    "version": [0, 0, 1],
    "min_engine_version": [1, 19, 2]
  },
  "modules": [
    {
      "description": "Use Game Test Framework",
      "language": "javascript",
      "type": "script",
      "uuid": "0a4bbea0-a6fa-44b8-a207-d41bf9e872d6",
      "version": [0, 0, 1],
      "entry": "scripts/main.js"
    }
  ],
  "dependencies": [
    {
      "uuid": "6f4b6893-1bb6-42fd-b458-7fa3d0c89616",
      "version": "1.0.0-beta"
    }
  ]
}
```

### 「main.js」ファイルを作成する

`scripts/main.js`

これが今回記述するJavaScriptのプログラムです。

チャット画面で`hi`と入力すると、`Hello, (プレイヤーの名前).`と返してくれるだけの、単純なプログラムです。

```javascript:scripts/main.js
import * as mc from 'mojang-minecraft';

// チャットが送信され、表示される直前に発生するイベント
mc.world.events.beforeChat.subscribe((event) => {
  // 送信メッセージが「hi」ならば
  if (event.message === 'hi') {
    // /sayコマンドを実行する
    event.sender.dimension.runCommand(`say Hello, '${event.sender.nameTag}'.`);
  }
});
```

### ワールドの作成とプログラムの実行

新しくワールドを作成してアドオンを適用しましょう。

1. 「ゲームテストフレームワークの使用」を有効にする
2. 「チートの実行」を有効にする（上を有効にした時点で自動的にチートが有効になります）
3. アドオン欄のビヘイビアーパックから、上で作成したアドオンを適用する
4. ゲームを開始
5. チャット画面で`hi`と入力（コマンドではないので先頭にスラッシュは付けない）

これで、`Hello, (プレイヤーの名前).`と表示されたら、上のプログラムが動いていることが確認できます。

ここまでの設定からもわかるように、実行するだけならとても単純です。

## 実行は単純でも開発は簡単ではない

実際のところ、この状態での開発はとても効率が悪く不便です。

そこで、開発の効率化を進めるために、開発環境を整えることにしましょう。

次の記事で、開発環境の設定を行なってください。
基本的にはテンプレートをダウンロードして、手順通りに設定するだけです。


アドオンでプログラムを実行する方法


この章ではMinecraftでプログラミングの学習を始めるために、押さえておきたいことを解説します。


はじめに


よく使うキーボードの入力方法です。

<R t="シフト">
  <code>Shift</code>
</R>
<R t="コントロール">
  <code>CTRL</code>
</R>
<R t="オルト">
  <code>Alt</code>
</R>
と組み合わせの場合は、先にこのキーを指で押さえてから、他のキーを押します。

## 記号

<div className="grid sm:grid-cols-2 gap-4">
<div>

### @ (アット)

`@`

<Fig file="atsign.png" width={1280} height={506} />

</div>
<div>

### + (プラス)

`Shift` + `;`

<Fig file="plus.png" width={1280} height={506} />

</div>
<div>

### - (マイナス)

`-`

<Fig file="minus.png" width={1280} height={506} />

</div>
<div>

### ^ (キャレット)

`^`

<Fig file="caret.png" width={1280} height={506} />

</div>
<div>

### ~ (チルダ)

`Shift` + `^`

<Fig file="tilde.png" width={1280} height={506} />

</div>
</div>

## ショートカットキー

ショートカットキーは使っているアプリによって異なりますが、下のはほとんどのアプリで共通なので覚えておくと便利です。

<div className="grid sm:grid-cols-2 gap-4">
<div>

### コピー/複製(copy)

`CTRL` + `c`

<Fig file="copy.png" width={1280} height={506} />

</div>
<div>

### ペースト/貼り付け(paste)

`CTRL` + `v`

<Fig file="paste.png" width={1280} height={506} />

</div>
<div>

### ひとつ前に戻る(undo)

`CTRL` + `z`

<Fig file="undo.png" width={1280} height={506} />

</div>
<div>

### セーブ/保存(save)

`CTRL` + `s`

<Fig file="save.png" width={1280} height={506} />

</div>
</div>


よく使うキーボード入力


プログラミングにおいて、英語能力はとても重要です。

しかし、初めのレッドストーンやコードビルダーまでならば、特に英語が必要になることはないので、まずは気軽にプログラミングの世界に入ってください。（なので小学生でも始めることができます）

ただ、そこから先のコマンドやアドオン・プラグインなど、より高度な内容へと進むに連れて、より高い英語能力が必要になっていきます。

このページでは、どの段階でどの程度の英語力が必要なのか、またどのように英語を学んでいくかを解説します。

## 英語ができる方が圧倒的に有利

プログラムは原則として英語を使って書きます。
そのため、当たり前の結論として、<mark>プログラミングにおいて、英語能力はあればあるだけ有利</mark>になります。

<mark>
  逆に言うと英語学習をおそろかにした場合、プログラミング学習の進みは遅くなります。
</mark>

可能な限り、プログラミングと並行して、英語も学んでいきましょう。

## 各分野別で必要な英語力

### 1. レッドストーン

専門用語として英単語が出てくることもありますが、<mark>基本的に英語能力は必要ありません。</mark>

### 2. コードビルダー

コードビルダーはほぼすべての内容を日本語環境で学ぶことができます。（一部に翻訳の不備により、英語のままの箇所があります）

ただし、文字入力・タイピングが必須なので、<mark>アルファベットの理解だけは必要</mark>です。
アルファベット学習前の小学校の低学年以前の子供を指導する場合には、事前にアルファベットの学習を行なってください。

このコードビルダーまでで、プログラミングの基本知識を十分に学ぶことができます。
特にプログラミングを専門的に学ぶ予定がない方は、ここまでできれば十分です。
よって、プログラミングのために、すぐに英語を学ぶ必要はありません。

<LinkCard slug="code-builder" />

### 3. コマンド

コマンドは英単語を入力するので、<mark>英単語を辞書で調べて理解する能力が必要です。</mark>

日本語での情報量も多く、英文が読める必要はありません。

<LinkCard slug="command" />

### 4. アドオン(JSON)

アドオン以降は日本語での情報は少なく、英語サイトから情報を集めなくてはいけなくなってきます。

そのため、<mark>自動翻訳機能の助けを借りて英文を読める</mark>必要が出てきます。

基本的な英語能力に加えて、翻訳ツールを使えるようになりましょう。

<LinkCard slug="add-on" />

### 5. アドオン(JavaScript)・プラグイン

ここで本格的なプログラミング言語を扱うことになります。

プログラミングは基本的に英文のように書くものなので、<mark>ごく簡単な英文を書けるのが理想</mark>です。

<LinkCard slug="plugin" />

## 各段階での英語の学習の仕方

### 英単語を辞書で調べる

コマンドまでは、英語の文章を読み書きできる必要はありません。
しかし、多くの英単語の知識が必要になります。

事前に出てくる英単語すべてを覚えておく必要はありませんが、わからない英単語が出てきた時には自分で調べられるようになりましょう。

これは単純に次のようなサイトで、検索にかけて調べるだけです。

* [英辞郎](https://eow.alc.co.jp/)
* [weblio](https://ejje.weblio.jp/)

### 機械翻訳の助けを借りて英語ページを読む

アドオン以降になると日本語での情報量が少なく、英語ページを読む必要が出てきます。

英語のページと言っても、ブラウザにページ丸ごと翻訳してくれる機能があるので、まずはこれを使いましょう。

GoogleChromeならば標準でページ翻訳機能が入っています。
それ以外のブラウザの場合は拡張機能で導入しましょう。

おすすめのブラウザは、ほぼすべての広告(YouTube含む)をブロックしてくれる[Brave](https://brave.com/ja/)です。

<ExButton href="https://brave.com/ja/">プライバシーを守るブラウザ「Brave」</ExButton>

Braveブラウザの基本部分はChromeと同じなので、BraveでもChromeと同じ拡張機能が使えます。

* [Google翻訳](https://chrome.google.com/webstore/detail/google-translate/aapbdbdomjkkjkaonfhkkikfgjllcleb)

部分的な文章の翻訳は、より精度の高いDeepLを使いましょう。

* [DeepL翻訳](https://chrome.google.com/webstore/detail/deepl-translate-beta-vers/cofdbpoegempjloogbagkncekinflcnj)

ただし、必ずしも正確に翻訳される訳ではないので、意味のわからない部分は自分で読み解く努力をしてください。

### 変数や関数の名前を英語でつける

プログラミングにおいて重要なのは、変数や関数などの名前の付け方です。
プログラミング言語によっては、漢字や絵文字を使ったりできるのもありますが、原則として英語で名前をつけなくてはいけません。

この時に間違った英語名をつけたり、日本語のローマ字で書いたりすると、コードが非常に読みづらくなります。
このように、適切な英語名をつけられるということが、プログラミング能力おいてとても大切です。

とはいえ、こちらも便利な翻訳ツールがあるのでこれを活用しましょう。

* [Codic](https://codic.jp/)
* [DeepL](https://www.deepl.com/translator)

本当に適切であるかを最終的に判断するのは自分なので、最低限の英語力は必要です。

適切な英語になっているかを見分けるコツは、英語の文脈も併せて調べることです。
自分で選んだ英単語を[英辞郎](https://eow.alc.co.jp/)や[weblio](https://ejje.weblio.jp/)で再検索して、適切な文脈で使われているかを調べ直しましょう。

### 基本的な英語力を上げる

ここまで見てきた通り、<mark>英語自体はプログラミングで絶対に必要な能力です。</mark>
しかしその一方で、英語力が足りなくても、道具を上手く使うことで対処できる環境が急速に整ってきています。

おそらく今後もこの傾向は続き、言語の壁は便利な道具によって取り除かれていくと予想されます。
しかし、これが完全にプログラミングにまで及ぶかどうかはわかりません。

普通に話す分には、うまく翻訳してくれるかもしれませんが、厳密なコードの作成には自分自身の英語能力が必要なままになるかもしれません。

そのため、英語をいっさい学ばないという選択は、現段階ではとても危険です。

<mark>
  高度なプログラミング力を持ちたい場合は、原則として英語の学習を同時に進めてください。
</mark>

おすすめの英語学習アプリは[Duolingo](https://ja.duolingo.com/)です。
これだけでもいいので、毎日10分続けましょう。

<ExButton href="https://ja.duolingo.com/">英語学習アプリ「Duolingo」</ExButton>

## 一番大事なのは日本語(母国語)

英語は重要な技術ではありますが、<mark>最も大切な技術は日本語</mark>です。

私達日本人は、母国語である日本語で物事を考えています。
英語を学習するにおいても日本語を使って学習することになります。
そのため、日本語力が足りなければ英語どころかプログラミングの学習もままなりません。

プログラミングや英語の教材を上手く使いこなすためにも、日本語を鍛えることも忘れないようにしましょう。

日々の学習方法としては、次のとおり単純なことから始めてください。

1. いろんな種類の本・少し難しい本を読む
2. わからない単語・漢字をきちんと辞書で調べる

基本はこの繰り返しです。

ある程度できるようになると、文法をきちんと抑えることが大切になってきます。
しかし、文法から入ると非常につまらないので、読書に慣れてからで構いません。


プログラミングに必要な英語

プログラミング学習で必要な英語能力と学び方


あなたがMinecraftをプレイしているとき、次のような行動をとることがあるでしょう。

満腹度が減っていたら、食べ物を食べる。
夜になったら、ベッドで寝る。
クリーパーを見つけたら、弓矢で攻撃する。

論理ブロックは、このように、「～なら、～をする」というような処理をプログラムで作ることができます。

## サンプルプロジェクトの読み込み

この記事で使ったプログラムを公開しています。
コードビルダーの読み込み機能から、次のURLを使って、プロジェクトをダウンロードしてください。

```txt
https://makecode.com/_YE1X59VEkJUR
```

まずは完成品のプログラムを使ってみて、次に自分で組んでみてください。

もし同じように動かなかった場合は、どこが違うのかをよく観察してください。

## もし～ならば (if)

<Fig file="logic1.png" width={772} height={232} />

例文は<mark>「スニークしたときに、『もし足元の座標に草ブロックがあるならば』、メッセージを送信する」</mark>という処理になります。

この`もし～なら`というブロックは、ある条件を確認して、それが正しいときにだけ実行します。
順番に見ていきましょう。

まず、座標部分ですが、自分を基準にして`y`が`-1`の位置ということですね。
つまり、自分の足元である、自分が立っているブロックのことを指します。

なので、<mark>今回の条件として、「足元のブロックは草ブロックですか」という質問がされています。</mark>

この質問の答えによって次のようになります。

* 「はい」ならば<R t="しん">真</R>・<R t="トゥルー">true</R>
* 「いいえ」ならば<R t="ぎ">偽</R>・<R t="フォルス">false</R>

この質問が**真**の場合だけ、ブロックの内側の処理が実行されてメッセージが流れます。
つまり、足元が草ブロックのときだけ、メッセージが流れて、それ以外のブロックだとメッセージが流れません。

**偽**の場合には、その部分は無視されて次に進みます。エラーになって止まるわけではありません。

「はい」か「いいえ」で答えられない質問の場合にはエラーがでます。

## ～でなければ (else)

<Fig file="logic2.png" width={682} height={440} />

次は、「正しくなかった場合」の処理の書き方をみていきましょう。

<mark>
  今回の条件は「草ブロックを壊した回数を2で割ったあまりが1ならば」です。
</mark>

`草ブロックを壊した回数`という[変数](/code-builder-variables/)を作って、この内容に合わせて処理を変えます。

壊した回数は1回ずつ増えていくので、具体的にみていきましょう。

* 1のとき、`1 ÷ 2 = 0 あまり 1`となり、正しいので**真**
* 2のとき、`2 ÷ 2 = 1 あまり 0`となり、正しくないので**偽**
* 3のとき、`3 ÷ 2 = 1 あまり 1`となり、正しいので**真**
* 4のとき、`4 ÷ 2 = 2 あまり 0`となり、正しくないので**偽**

この条件では、真のとき（あまりが1）は<R t="きすう">奇数</R>、偽のとき（余りは0）は<R t="ぐうすう">偶数</R>になります。

<Note color="blue">
  壊した回数は整数なので、必ず奇数か偶数かのどちらかになります。
  そのため、「奇数ではない」というのは「偶数である」と同じ意味になります。
  もし小数など、整数以外も含めて考える場合は、この処理は適切ではありません。
</Note>

## ～でないけれど、～ならば (else if)

<Fig file="logic3.png" width={621} height={571} />

条件はいくつも設定できます。
この書き方の場合は、上から順番に判定し、正しかったらそこの処理だけ行われ、残りは無視されます。

例えば`土ブロックを壊した数`が`1`の時は次のようになります。

* 1番目の条件は`数`が`1`のときなので、正しいです
* 2番目の条件は`数`が`4以下`なので、これも正しいです

しかし、<mark>この場合は1番目の処理だけが行われます。</mark>
1番目で条件を満たしたので、2番目以降は無視されます。

1回目のときは、メッセージだけが表示され、ニワトリが出現しないことに注目してください。

* 壊した数が`1`のとき、1番目の条件を満たすので、メッセージが出る
* 壊した数が`2`のとき、2番目の条件を満たすので、ニワトリが出る
* 壊した数が`3`のとき、2番目の条件を満たすので、ニワトリが出る
* 壊した数が`4`のとき、条件を満たさないのでゾンビが出る

<Note color="blue">
以上(≧)・以下(≦)は、その数字を含みます。
より大きい(&gt;)、より小さい・未満(&lt;)は、その数字を含みません。
</Note>

## フラグを立てる

<Fig file="logic4.png" width={959} height={922} />

変数の中にはそのまま「真」と「偽」を入れることもできます。

この例では、「羽根を使ったとき」を条件にして、変数`死亡フラグ`を切り替えています。
この`死亡フラグ`が**真**になっているときに、プレイヤーが走ると死にます。
このように、変数を通して離れたブロックの条件を操作できます。

よくいわれる死亡フラグとは、このようなプログラミング処理が語源です。

まず、あるキャラクターが物語の途中で、ある行動をとったときに、そのキャラクターの死亡フラグを真にします(フラグを立てる)。
そして、ある場面で条件が判定されたときに、条件は真になっているので、そのまま死亡イベントが発生します。

「フラグを折る」という表現は、死亡フラグが偽になったという表現です。
この場合は、判定されても条件を満たさないので死亡イベントは発生しません。

## 条件を組み合わせる

今回の例として、2と3の倍数を判定してみましょう。
長くなるので、先に全体のブロックを表示しておきます。

<Fig file="logic5.png" width={900} height={424} />

チャットコマンドのブロックの右上にある「+」ボタンを押して<R t="ひきすう">引数</R>を受け取れるように設定してください。

この場合の使い方は、指定したチャットコマンドに続けて、半角スペースを空けて数字を入力します。

```bash
baisuu 2
baisuu 3
baisuu 5
baisuu 6
```

### 判定した結果を変数に入れる

2の倍数とは、「2で割った余りが0になる数字」のことです。
具体的には`0, 2, 4, 6, 8, 10, 12...`です。

3の倍数とは、「3で割った余りが0になる数字」のことです。
具体的には`0, 3, 6, 9, 12, 15...`です。

これの判定結果を変数に入れておきます。

<Fig file="logic4_1.png" width={752} height={461} />

この変数の中には「入力した数を2で割った余りは、0ですか」という質問に対する答えが、「はい(真)」か「いいえ(偽)」で入っています。
つまり、この変数自体を条件ブロックの中に入れることができます。

<Note color="amber">
  「はい」か「いいえ」で答えられない場合はエラーになります。
</Note>

今回は倍数であるかどうかを判定をしたいのでした。
この場合は、2の倍数の処理と繋げて、3の倍数の判定を`～でなければもし`の形で、書かないようにしましょう。

例えば6のときは、2の倍数でも3の倍数でもあるので、両方を表示するべきです。
もし繋げて書いてしまうと、2の倍数と表示する処理だけで終わってしまい、3の倍数とは表示されません。

---

### かつ(and) - AとBの両方を満たす

<Fig file="logic4_2.png" width={959} height={165} />

<mark>「2の倍数」かつ「3の倍数」</mark>とは、この
<mark>2つの条件を「共に」満たしたときに正しくなります。</mark>

<mark>どちらか1つだけが正しい場合は条件を満たしません。</mark>
「2の倍数」だけでも、「3の倍数」だけでもいけません。
「2の倍数」でありながら、また「3の倍数」でもある場合だけ条件を満たします。

つまり`0, 6, 12, 18, 24, 30...`のときです。
それぞれの数字は2でも、3でも割り切れますね。

<Note color="blue">
「かつ」は英語で「<R t="アンド">and</R>」です。
レッドストーン回路の<strong>and回路</strong>と同じ働きをします。
</Note>

### または(or) - AかBの少なくともどちらか一方を満たす

<Fig file="logic4_3.png" width={959} height={165} />

<mark>「2の倍数」または「3の倍数」</mark>とは、
この<mark>2つの条件の「少なくともどちらか一方」を満たしたときに正しくなります。</mark>

「2の倍数」だけでも、「3の倍数」だけでも構いません。
勘違いしやすいところです、<mark>両方を満たしていても構いません。</mark>

つまり`0, 2, 3, 4, 6, 8, 9, 10...`のときです。
それぞれの数字は2か3のどちらかで割り切れますね。
6の場合は、2でも、3でも割り切れますが、これも含みます。

<Note color="blue">
「または」は英語で「<R t="オア">or</R>」です。
レッドストーン回路の<strong>or回路</strong>と同じ働きをします。
</Note>

### ではない(not)

<Fig file="logic4_4.png" width={959} height={165} />

<mark>「～ではない」を組み込むと条件が反対になります。</mark>
つまり、この中の値が偽であったときに、真と判定されるようになります。

「(『2の倍数』または『3の倍数』)ではない」となるので、この場合は上の「または」の条件を、「～でなければ(else)」として使った場合と同じです。

<Note color="blue">
「ではない」は英語で「<R t="ノット">not</R>」です。
レッドストーン回路の<strong>not回路</strong>と同じ働きをします。
</Note>


論理 - もし～ならば

論理ブロックの使い方 - 条件によって処理を変える


変数の内容は増やすだけでなく、減らしたり、かけたりして計算できます。
まずは簡単に足し算・引き算・掛け算・割り算の計算してみましょう。

## 計算用の変数を作る

今回の計算に使う変数の名前は、単純に`x`にしておきましょう。

変数の作り方がわからない方は次の記事を読んでください。

<LinkCard slug="code-builder-variables" />

## 足し算をする

**足し算**は変数の回で学んだのと同じですね。
`～だけ増やす`ブロックを使うだけです。

<Fig file="example1.png" width={556} height={353} style={{ maxWidth: '278px' }} />

1以外の数を足したいのであれば、中の数字を変更してください。

## 引き算をする

次は**引き算**をしてみましょう。

しかし、変数のメニューには`～だけ増やす`はありますが「減らす」ブロックがありません。

<Fig file="example2.png" width={557} height={354} style={{ maxWidth: '278px' }} />

ここでは「マイナス1増やす」と考え、数字を`-1`にすると、数字を減らすことができます。

<Note color="blue">「1減らす」ことは、「マイナス1増やす」ことと同じです。</Note>

## 掛け算をする

<R t="かけざん">掛け算</R>は変数ブロックだけでは計算できません。
計算ブロックと組み合わせます。

<Fig file="example3.png" width={745} height={414} style={{ maxWidth: '372px' }} />

「変数」メニューの「`～にする`」ブロックに、「計算」メニューにある計算ブロックを組み込んでください。

今回は、足し算・引き算で使った`～だけ増やす`ブロックではないので注意してください。

1行の中に変数`x`が2回出てくるのが紛らわしいですが、次のような意味になります。

1. 変数`x`から内容を取り出す
2. 取り出した内容に`2`を**掛ける**
3. 計算結果を変数`x`に入れる

<Note color="blue">
同じような形で、足し算と引き算の計算もすることができます。
計算結果は同じなので、足し算・引き算の場合はどちらを使っても構いません。
</Note>

## 割り算をする

<R t="わりざん">割り算</R>
も掛け算と同じように、計算ブロックと組み合わせてください。

<Fig file="example4.png" width={735} height={414} style={{ maxWidth: '368px' }} />

これも掛け算と同じ手順で計算されます。

1. 変数`x`から内容を取り出す
2. 取り出した内容に`2`で**割る**
3. 計算結果を変数`x`に入れる

## 四捨五入する

割り算の結果、数字が割り切れない場合は小数になります。
例えば、`1`を`2`で割った場合は`0.5`になります。
`1 ÷ 2 = 0.5`ですね。

ここで問題になるのが、場合によっては整数として使わなければならない場合もあります。
例えば、アイテムをいくつ渡すのかを、変数で決めたい場合です。

このときに、渡す個数は整数でなくてはいけません。
5.5個を渡すということはできません。
このような場合には、四捨五入ブロックを使って整数に直しましょう。

<Fig file="example5.png" width={769} height={729} style={{ maxWidth: '385px' }} />

もし、小数で個数を決めた場合は、次のようにエラーが置きてしまいます。

<Fig file="error.png" width={1202} height={152} />

これら以外にも計算ブロックはありますが、他の記事で具体的な処理とともに説明します。


数字の計算

変数の数字を計算する


<R t="へんすう">変数</R>とは、「数字や文字を入れておく、箱のようなものだ」と、よく表現されます。
この箱の中に数字や文字を入れて残しておくと、色んな場所で使いまわせるようになります。

難しく感じたかもしれませんが、これさえ理解できれば一気にプログラミングの世界が広がります。

詳しい説明を始める前に、まずは使ってみましょう。

説明がわからなくなったら、文章はとばしてください。
まずは画像の通りにブロックを組んで動かしてみましょう。

## 変数を作る

変数はたったひとつだけではなく、いくつも作ることができます。
他の変数と区別をつけられるように、まずは<mark>変数に名前を付けましょう。</mark>

<Fig file="make_variable.gif" width={787} height={526} />

左メニューから変数を選んで「変数を追加する」を選び名前をつけます。
今回は`回数`にします。

<Note color="blue">
変数の名前はひらがなでもアルファベットでも構いません。
ただし、記号や数字を使う場合にはいくつかの決まり事があります。
</Note>

## 歩いたときに1ずつ増やす

<Fig file="variables2.png" width={400} height={231} />

次はどのようなときに、プログラムを動かすかを決めましょう。
今回は何度も動いてほしいので、`プレイヤーが[歩いた]時`にしましょう。
左メニューの「プレイヤー」から取り出してください。

その中に、さっき作った変数から、`変数[回数]を(1)だけ増やす`ブロックを入れます。

次に、`回数`の中に何が入っているかも表示しましょう。
`メッセージ( )を送信する`ブロックを入れて、その内容に`回数`を入れます。

設定できたら、プログラムを起動して、Minecraftのワールド内を歩き回ってみましょう。

歩くたびに数字が1ずつ増えてチャット欄に表示されると思います。

<mark>「回数」という名前のついた変数(箱)の中身が、1ずつ増えていっているのがわかるでしょうか。</mark>

## プログラムを止めると、変数の内容は元に戻る

ゲームを終了させたり、コードを変更したりするとプログラムは止まります。
このときに変数の内容も消えてしまいます。
次にプログラムを実行したときには`回数`は再び`0`から始まります。

コードビルダーに、変数の内容を残しておく機能はありません。
実は、変数の内容を残しておくことは、難しい機能です。
コマンドやアドオンなど、より難しいプログラムへ進んだときに少しずつ使えるようになっていきます。

## 初めの数字を変える

上のプログラムでは`回数`の数字は`0`から始まりました。
これを別の数字に変えたい場合を作ってみましょう。

<Fig file="variables1.png" width={800} height={231} />

この場合には`最初だけ`ブロックを使います。
これはプログラムを動かしたときに一度だけ実行されるブロックです。

この中に`変数[回数]を(0)にする`を入れます。
そして、数字部分を`100`に変えましょう。

これで、最初(プログラムが始まったとき)に、`回数`の内容を`100`にするというプログラムができました。

そのあとに、「プレイヤーが歩いた時」のプログラムが実行されるので、表示する数字も`100`から始まります。

## 変数には数字以外も入れられる

<Fig file="box.jpg" width={1280} height={720} />

変数は数字以外の内容も入れることができます。
他には「文字」「真偽値」「座標」などいろんな種類があります。

他の種類の使い方については、別の記事で説明します。


変数(へんすう)

変数(へんすう)ブロックの使い方


ここではMakeCodeでの基本文法を学びます。


基本的な使い方

コードビルダーの基本的な使い方


コマンドを個別に解説します。
より正確な情報は公式Wikiを見てください。


コマンド詳細


イベントとは「～が起こった時」にスクリプトが起動させる条件のことです。

## イベントの種類

### ブロックに関するイベント

* `BlockBreakEvent`: ブロックが壊れたとき
* `BlockExplodeEvent`: ブロックが爆発で壊れたとき
* `BlockPlaceEvent`: ブロックが置かれたとき

<LinkCard slug="mojang-minecraft-events-block" />

### チャージに関するイベント

弓やクロスボウなどの、チャージできるアイテムを使用したとき。

* `ItemStartChargeEvent`: チャージを開始したとき
* `ItemStopChargeEvent`: チャージを停止したとき
* `ItemCompleteChargeEvent`: チャージを完了したとき
* `ItemReleaseChargeEvent`: チャージを解放したとき

<LinkCard slug="mojang-minecraft-events-charge" />

### チャットに関するイベント

* `ChatEvent`: チャットメッセージを送ったとき（送信された後）
* `BeforeChatEvent`: チャットメッセージを送ったとき（送信される直前）

<LinkCard slug="mojang-minecraft-events-chat" />

### 装置に関するイベント

* `ButtonPushEvent`: ボタンを押したとき
* `LeverActionEvent`: レバーを操作したとき
* `PistonActivateEvent`: ピストンが動いたとき(動いた後)
* `BeforePistonActivateEvent`: ピストンが動くとき(動く直前)

<LinkCard slug="mojang-minecraft-events-device" />

### エフェクトに関するイベント

* `EffectAddEvent`: ステータス効果が追加されたとき

<LinkCard slug="mojang-minecraft-events-effect" />

### エンティティに関するイベント

* `EntityCreateEvent`: エンティティが作成されたとき
* `EntityHitEvent`: エンティティが近接攻撃を受けたとき(遠距離 -> `ProjectileHitEvent`)
* `EntityHurtEvent`: エンティティがダメージを受けたとき
* `DataDrivenEntityTriggerEvent`: エンティティのコンポーネントが変更されたとき(直後)
* `BeforeDataDrivenEntityTriggerEvent`: エンティティのコンポーネントが変更されるとき(直前)

<LinkCard slug="mojang-minecraft-events-entity" />

### 爆発に関するイベント

* `ExplosionEvent`: 爆発したとき(爆発した直後)
* `BeforeExplosionEvent`: 爆発するとき(爆発する直前)

<LinkCard slug="mojang-minecraft-events-explosion" />

### アイテムに関するイベント

`Use`がアイテムを普通に使用したとき。  
`UseOn`がブロックに向けてアイテムを使用したとき。

* `ItemUseEvent`: アイテムを使用したとき(直後)
* `BeforeItemUseEvent`: アイテムを使用するとき(直前)
* `ItemStartUseOnEvent`: ブロックに向けてアイテムの使用を開始したとき
* `ItemStopUseOnEvent`: ブロックに向けてアイテムの使用を停止したとき
* `ItemUseOnEvent`: ブロックに向けてアイテムの使用を開始したとき
* `BeforeItemUseOnEvent`: ブロックに向けてアイテムの使用を開始するとき
* `ItemDefinitionTriggeredEvent`: アイテムのコンポーネントが変更されたとき
* `BeforeItemDefinitionTriggeredEvent`: アイテムのコンポーネントが変更されるとき

<LinkCard slug="mojang-minecraft-events-item" />

### プレイヤーに関するイベント

* `PlayerJoinEvent`: プレイヤーがワールドに入ったとき
* `PlayerLeaveEvent`: プレイやがーワールドから出たとき

<LinkCard slug="mojang-minecraft-events-player" />

### 発射物に関するイベント

* `ProjectileHitEvent`: 発射物が何かに当たったとき

<LinkCard slug="mojang-minecraft-events-projectile" />

### ワールドに関するイベント

* `TickEvent`: 1ティック毎（1秒に20回）に、定期的に実行される
* `WeatherChangeEvent`: 天候が変わったとき
* `WorldInitializeEvent`: ワールドが初期化したとき

<LinkCard slug="mojang-minecraft-events-world" />

## イベントの登録と解除

ワールドからイベントシグナルを呼び出して、そこに対応するイベント関数を `subscribe()` で登録します。
イベント関数とイベントシグナルは対応している必要があります。

解除する場合は、同じ関数を `unsbscribe()` で指定します。

```typescript
import * as mc from 'mojang-minecraft';

// イベント関数を作る
function onBlockBreak(event: mc.BlockBreakEvent) {
  // ...
}

// イベント関数を対応するイベントシグナルに登録する
mc.world.events.blockBreak.subscribe(onBlockBreak);

// イベント関数の登録を解除する
mc.world.events.blockBreak.unsubscribe(onBlockBreak);
```

### 直接記述する

匿名関数（下の例は[アロー関数](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Functions/Arrow_functions)）を使い、直接`subscribe()`の中に処理を記述できます。

```typescript
// この場合eventの型宣言は不要
mc.world.events.blockBreak.subscribe((event) => {
  // ...
});
```

ただし、この場合は登録したイベントを解除することは（おそらく）できません。


トリガーイベント一覧

ゲームテストフレームワークのイベント一覧


ブロックに関する操作をしたときに発生するイベントです。

## BlockBreakEvent

ブロックがプレイヤーによって破壊されたときに発生します。

```typescript
import * as mc from 'mojang-minecraft';

export function onBlockBreak(event: mc.BlockBreakEvent) {
  // イベントが発生したブロック
  // 壊したあとの情報なので破壊したブロックは取得しない。多くの場合で空気ブロック
  const block: mc.Block = event.block;
  // 壊したブロックの種類や状態などについての組み合わせ(permutation)情報
  const permutation: mc.BlockPermutation = event.brokenBlockPermutation;
  // イベントが発生した次元
  const dimension: mc.Dimension = event.dimension;
  // イベントを発生させたプレイヤー
  const player: mc.Player = event.player;

  // イベントが発生したブロックの位置を文字列で取得
  const location = `${dimension.id}(${block.x}, ${block.y}, ${block.z})`;
  // 内容を表示
  dimension.runCommand(`say ${player.nameTag} が ${location} の ${permutation.type.id} を破壊しました。`);
}

mc.world.events.blockBreak.subscribe(onBlockBreak);
```

## BlockExplodeEvent

ブロックが爆発で破壊されたときに発生します。

```typescript
import * as mc from 'mojang-minecraft';

function onBlockExplode(event: mc.BlockExplodeEvent) {
  // イベントが発生したブロック
  // 破壊後の情報なので、おそらく空気ブロックになる。
  // 破壊前のブロック情報はBeforeExplosionEventで取得する
  const block: mc.Block = event.block;
  // イベントが発生した次元
  const dimension: mc.Dimension = event.dimension;
  // 爆発を起こしたエンティティ
  const entity: mc.Entity = event.source;

  // イベントが発生したブロックの位置を文字列で取得
  const location = `${dimension.id}(${block.x}, ${block.y}, ${block.z})`;
  // 内容を表示
  dimension.runCommand(`say ${entity.id} が ${location} のブロックを爆破しました。破壊後は ${block.id} です。`);
}

mc.world.events.blockExplode.subscribe(onBlockExplode);
```

## BlockPlaceEvent

プレイヤーがブロックを置いたときに発生します。

```typescript
import * as mc from 'mojang-minecraft';

function onBlockPlace(event: mc.BlockPlaceEvent) {
  // イベントが発生したブロック
  const block: mc.Block = event.block;
  // イベントが発生した次元
  const dimension: mc.Dimension = event.dimension;
  // イベントを発生させたプレイヤー
  const player: mc.Player = event.player;

  // イベントが発生したブロックの位置を文字列で取得
  const location = `${dimension.id}(${block.x}, ${block.y}, ${block.z})`;
  // 内容を表示
  dimension.runCommand(`say ${player.nameTag} が ${location} に ${block.id} を置きました。`);
}

mc.world.events.blockPlace.subscribe(onBlockPlace);
```

## 参考

* [BlockBreakEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/blockbreakevent)
* [BlockExplodeEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/blockexplodeevent)
* [BlockPlaceEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/blockplaceevent)


ブロックに何かをしたとき

ブロックに関するイベント


チャージに関する操作をしたときに発生するイベントです。

チャージとは「弓」や「クロスボウ」など、マウスをクリックした後も押し続ける動作のことです。
他にもトライデントや釣竿などでもチャージイベントが発生します。
スケルトンやピレジャーなどの弓攻撃では発生しません。

## アイテム別の発生するイベント

主に弓系の操作とクロスボウの操作で分かれます。
すべてのアイテムで確認していませんが、ほとんどは弓系の操作になりそうです。

<Table>
  <thead>
    <tr>
      <th></th>
      <th><code>Start</code></th>
      <th><code>Stop</code></th>
      <th><code>Release</code></th>
      <th><code>Complete</code></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th style={{whiteSpace: "nowrap"}}>弓・トライデント(投)</th>
      <td>クリックしたとき</td>
      <td>--</td>
      <td>アイテムを放ったとき</td>
      <td>--</td>
    </tr>
    <tr>
      <th style={{whiteSpace: "nowrap"}}>クロスボウ</th>
      <td>クリックしたとき</td>
      <td>--</td>
      <td>完了前にボタンを離したとき</td>
      <td>完了したとき</td>
    </tr>
  </tbody>
</Table>

`ItemStopChargeEvent`はどのアイテムで発生するか未確認です。

## ItemStartChargeEvent

チャージできるアイテムのチャージを開始したとき。

```typescript
import * as mc from 'mojang-minecraft';

function onItemStartCharge(event: mc.ItemStartChargeEvent) {
  // チャージに使用したアイテム
  const item: mc.ItemStack = event.itemStack;
  // 使用者
  const user: mc.Entity = event.source;
  // このアイテムのチャージが完了するまでのティック
  const duration: number = event.useDuration;

  // 内容を表示
  user.dimension.runCommand(`say ${user.nameTag} が ${item.id} のチャージを開始。完了まで ${duration}ティック。`);
  // 特定のアイテムを使ったら
  if (item.id === mc.MinecraftItemTypes.bow.id) {
    user.runCommand(`effect @s levitation 9999 5 true`);
  } else if (item.id === mc.MinecraftItemTypes.crossbow.id) {
    user.runCommand(`effect @s blindness 9999 0 true`);
  }
}

mc.world.events.itemStartCharge.subscribe(onItemStartCharge);
```

## ItemStopChargeEvent

チャージできるアイテムのチャージを停止したとき。

どのアイテムで発生するか未確認。

```typescript
function onItemStopCharge(event: mc.ItemStopChargeEvent) {
  // チャージに使用したアイテム
  const item: mc.ItemStack = event.itemStack;
  // 使用者
  const user: mc.Entity = event.source;
  // このアイテムのチャージが完了するまでのティック
  const duration: number = event.useDuration;

  // 内容を表示
  user.dimension.runCommand(`${user.nameTag} が ${item.id} のチャージを停止`);
  // 特定のアイテムを使ったら
  if (item.id === mc.MinecraftItemTypes.bow.id) {
    user.runCommand(`effect @s levitation 0`);
  } else if (item.id === mc.MinecraftItemTypes.crossbow.id) {
    user.runCommand(`effect @s blindness 0`);
  }
}

mc.world.events.itemStopCharge.subscribe(onItemStopCharge);
```

## ItemReleaseChargeEvent

チャージできるアイテムをチャージから解放したとき。

```typescript
function onItemReleaseCharge(event: mc.ItemReleaseChargeEvent) {
  // チャージに使用したアイテム
  const item: mc.ItemStack = event.itemStack;
  // 使用者
  const user: mc.Entity = event.source;
  // このアイテムのチャージが完了するまでのティック
  const duration: number = event.useDuration;

  // 内容を表示
  user.dimension.runCommand(`say ${user.nameTag} が ${item.id} のチャージを解放。`);
  // 特定のアイテムを使ったら
  if (item.id === mc.MinecraftItemTypes.bow.id) {
    user.runCommand(`effect @s levitation 0`);
  } else if (item.id === mc.MinecraftItemTypes.crossbow.id) {
    user.runCommand(`effect @s blindness 0`);
  }
}

mc.world.events.itemReleaseCharge.subscribe(onItemReleaseCharge);
```

## ItemCompleteChargeEvent

チャージできるアイテムのチャージを完了したとき。

```typescript
function onItemCompleteCharge(event: mc.ItemCompleteChargeEvent) {
  // チャージに使用したアイテム
  const item: mc.ItemStack = event.itemStack;
  // 使用者
  const user: mc.Entity = event.source;
  // このアイテムのチャージが完了するまでのティック
  const duration: number = event.useDuration;

  // 内容を表示
  user.dimension.runCommand(`say ${user.nameTag} が ${item.id} のチャージを完了。`);
  // 特定のアイテムを使ったら
  if (item.id === mc.MinecraftItemTypes.bow.id) {
    user.runCommand(`effect @s levitation 0`);
  } else if (item.id === mc.MinecraftItemTypes.crossbow.id) {
    user.runCommand(`effect @s blindness 0`);
  }
}

mc.world.events.itemCompleteCharge.subscribe(onItemCompleteCharge);
```

## 「useDuration」について

使用したアイテムがチャージを完了するまでのティック数です。

クロスボウの初期値は`25`ティック(1.25秒)ですが、弓は`72000`ティック(1時間)です。

弓は最大まで引き絞っても、完了扱い(`ItemCompleteChargeEvent`)になりません。
この大きな数は「完了しない」を意味していると考えられます。
0やundefinedではないので注意してください。

## 参考

* [ItemStartChargeEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/itemstartchargeevent)
* [ItemStopChargeEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/itemstopchargeevent)
* [ItemReleaseChargeEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/itemreleasechargeevent)
* [ItemCompleteChargeEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/itemcompletechargeevent)


アイテムをチャージしたとき

チャージに関するイベント


チャットに関する操作をしたときに発生するイベントです。

新しいスラッシュコマンドの作成はできませんが、似たようなことができます。

## 実行される順番

1. チャット欄からメッセージを送信
2. `BeforeChatEvent`を実行
3. `ChatEvent`を実行
4. メッセージをチャット欄に表示

## ChatEvent

メッセージを送ったとき。

```typescript
import * as mc from 'mojang-minecraft';

function onChat(event: mc.ChatEvent) {
  // 送信されたメッセージ
  const message: string = event.message;
  // メッセージが特定のプレイヤーにだけ送られたか(/msg, /t)
  const sendToTargets: boolean = event.sendToTargets;
  // 送信者
  const sender: mc.Entity = event.sender;
  // 送信対象(送信者は含まれない)
  const targets: mc.Player[] = event.targets;

  sender.runCommand('say *** メッセージ送信イベントが発生');
}
```

## BeforeChatEvent

メッセージを送信したとき。
送信内容が確定する前に実行される。

送信する前に実行されるので、メッセージの送信を停止できます。

```typescript
import * as mc from 'mojang-minecraft';

function onBeforeChat(event: mc.BeforeChatEvent) {
  // イベントを停止させるか
  event.cancel;
  // これから送信されるメッセージ
  event.message;
  // メッセージが特定のプレイヤーにだけ送られるか(/msg, /t)
  const sendToTargets: boolean = event.sendToTargets;
  // 送信者
  const sender: mc.Player = event.sender;
  // 送信対象(送信者は含まれない)
  const targets: mc.Player[] = event.targets;

  // メッセージが特定を含んでいれば
  if (event.message.includes('tnt')) {
    // TNTを呼び出す
    sender.runCommand(`summon tnt`);
    // メッセージを送信しない
    event.cancel = true;
  }

  // 特定のプレイヤーだけに送信されていれば（ひとりではテストできない）
  if (sendToTargets) {
    // メッセージが届くプレイヤーで繰り返し
    targets.forEach(function (target) {
      // メッセージ内容を変更する
      event.message = `${sender.nameTag} -> ${target.nameTag}: ${event.message}`;
    });
  }
}
```

## 参考

* [ChatEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/chatevent)
* [BeforeChatEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/beforechatevent)


チャットをしたとき

チャットに関するイベント


一部の入力装置に関する操作をしたときに発生するイベントです。

バージョン`1.19.21`時点では、次の装置にだけ対応しています。

* ボタン（種類は問わない）
* レバー
* ピストン・粘着ピストン

## ButtonPushEvent

プレイヤーがボタンを押したとき。

```typescript
import * as mc from 'mojang-minecraft';

function onButtonPush(event: mc.ButtonPushEvent) {
  // ボタンのブロック情報
  const button: mc.Block = event.block;
  // イベントが発生した次元
  const dimension: mc.Dimension = event.dimension;
  // ボタンを押したエンティティ
  const user: mc.Entity = event.source;

  // 押したボタンの種類がアカシアなら
  if (button.id === mc.MinecraftBlockTypes.acaciaButton.id) {
    // 設置先のブロックを取得する
    // 設置したボタン情報は取得できるが、設置先のブロックは間接的に取得するしかない
    // getButtonInstalledLocation() は後述の関数を参照
    const installedBlock: mc.Block = dimension.getBlock(getButtonInstalledLocation(button));
    // 設置先のブロックをTNTに変える
    installedBlock.setType(mc.MinecraftBlockTypes.tnt);
    // そのままボタンの信号が伝わり着火する
  } else {
    // それ以外なら、押したプレイヤーに雷を落とす
    user.runCommand(`summon lightning_bolt`);
  }
}

mc.world.events.buttonPush.subscribe(onButtonPush);
```

### ボタンを設定したブロックの情報を取得する

`ButtonPushEvent`では、ボタンを設置したブロックは取得できますが、設置先のブロックは直接取得できません。
設置したボタンの情報を使い、間接的に取得します。

```typescript
import * as mc from 'mojang-minecraft';

export function getButtonInstalledLocation(button: mc.Block): mc.BlockLocation {
  // ブロックの種類や状態などについての組み合わせ(permutation)情報
  const permutation: mc.BlockPermutation = button.permutation;
  // ブロックの状態名を取得する（getProperty内に直接書いてもよい）
  const propertyName: string = mc.BlockProperties.facingDirection;
  // 向きを取得する（整数のプロパティ型に型変換をしている）
  const face: mc.IntBlockProperty = <mc.IntBlockProperty>permutation.getProperty(propertyName);

  // ボタンの位置と向きから設置しているブロックを取得する
  const blockLocation: mc.BlockLocation = button.location;
  if (face.value === 0) {
    blockLocation.y += 1; // ボタンが下向き -> 上のブロックに設置している -> 高さ+1
  } else if (face.value === 1) {
    blockLocation.y -= 1; // 上向き -> 下のブロックに設置
  } else if (face.value === 2) {
    blockLocation.z += 1; // 北向き -> 南面に
  } else if (face.value === 3) {
    blockLocation.z -= 1; // 南
  } else if (face.value === 4) {
    blockLocation.x += 1; // 西
  } else if (face.value === 5) {
    blockLocation.x -= 1; // 東
  }

  return blockLocation;
}
```

## LeverActionEvent

レバーが動作したとき。

```typescript
import * as mc from 'mojang-minecraft';

function onLeverActivate(event: mc.LeverActionEvent) {
  // レバーのブロック情報
  const lever: mc.Block = event.block;
  // イベントが発生した次元
  const dimension: mc.Dimension = event.dimension;
  // レバーが有効になっているか
  const isPowered: boolean = event.isPowered;
  // イベントを発生させたプレイヤー
  const player: mc.Player = event.player;

  // 設置先のブロックをレッドストーンランプにする
  // 設置したレバー情報は取得できるが、設置先のブロックは間接的に取得するしかない
  // getLeverInstalledLocation() は後述の関数を参照
  const installedBlock: mc.Block = dimension.getBlock(getLeverInstalledLocation(lever));
  installedBlock.setType(mc.MinecraftBlockTypes.redstoneLamp);

  // 有効なら夜に、無効なら昼にする
  if (isPowered) {
    dimension.runCommand('time set midnight');
  } else {
    dimension.runCommand('time set noon');
  }
}

mc.world.events.leverActivate.subscribe(onLeverActivate);
```

### レバーを設定したブロックの情報を取得する

`LeverActionEvent`も、設置先のブロックは直接取得できません。
ボタンイベントと同様に、設置したレバーの情報を使い、間接的に取得します。

ただし、ボタンとレバーで取得できる向き情報が異なるので、細部の処理方法が異なります。

```typescript
import * as mc from 'mojang-minecraft';

export function getLeverInstalledLocation(lever: mc.Block): mc.BlockLocation {
  // ブロックの種類や状態などについての組み合わせ(permutation)情報
  const permutation: mc.BlockPermutation = lever.permutation;
  // ブロックの状態名を取得する（getProperty内に直接書いてもよい）
  const propertyName: string = mc.BlockProperties.leverDirection;
  // 向きを取得する（文字列のプロパティ型に型変換している）
  const face: mc.StringBlockProperty = <mc.StringBlockProperty>permutation.getProperty(propertyName);

  // レバーの位置と向きから設置しているブロックを取得する
  const blockLocation: mc.BlockLocation = lever.location;
  if (face.value === 'down_east_west' || face.value === 'down_north_south') {
    blockLocation.y += 1; // レバーが下向き -> 上のブロックに設置している
  } else if (face.value === 'up_north_south' || face.value === 'up_east_west') {
    blockLocation.y -= 1; // 上
  } else if (face.value === 'north') {
    blockLocation.z += 1; // 北
  } else if (face.value === 'south') {
    blockLocation.z -= 1; // 南
  } else if (face.value === 'west') {
    blockLocation.x += 1; // 西
  } else if (face.value === 'east') {
    blockLocation.x -= 1; // 東
  }

  return blockLocation;
}
```

## PistonActivateEvent

ピストンが動作したとき（動作内容が確定した後）

```typescript
function onPistonActivate(event: mc.PistonActivateEvent) {
  // ピストンのブロック情報
  const block: mc.Block = event.block;
  // イベントが発生した次元
  const dimension: mc.Dimension = event.dimension;
  // ピストンが伸びているか
  const isExpanding: boolean = event.isExpanding;
  // イベントが発生したピストン
  const piston: mc.BlockPistonComponent = event.piston;

  // 粘着ピストン以外なら処理を終了
  if (block.type !== mc.MinecraftBlockTypes.stickyPiston) {
    return;
  }

  // ピストンが影響を与えたブロック位置の一覧
  const attachedBlocks: mc.BlockLocation[] = piston.attachedBlocks;
  if (isExpanding) {
    // 押し出すときは金ブロックに帰る
    for (const blockLocation of attachedBlocks) {
      dimension.getBlock(blockLocation).setType(mc.MinecraftBlockTypes.goldBlock);
    }
  } else {
    // 引き戻すときはダイヤモンドブロックに変える
    for (const blockLocation of attachedBlocks) {
      dimension.getBlock(blockLocation).setType(mc.MinecraftBlockTypes.diamondBlock);
    }
  }
}

mc.world.events.pistonActivate.subscribe(onPistonActivate);
```

## BeforePistonActivateEvent

ピストンを動かそうとし、動作内容が確定する前。

```typescript
function onBeforePistonActivate(event: mc.BeforePistonActivateEvent) {
  // イベントを停止させるか
  event.cancel;
  // ピストンのブロック情報
  const block: mc.Block = event.block;
  // イベントが発生した次元
  const dimension: mc.Dimension = event.dimension;
  // 動作の後にピストンが伸びているか
  const isExpanding: boolean = event.isExpanding;
  // イベントが発生したピストン
  const piston: mc.BlockPistonComponent = event.piston;

  // 通常ピストン以外なら処理を終了
  if (block.type !== mc.MinecraftBlockTypes.piston) {
    return;
  }

  if (isExpanding) {
    // ピストンが影響を与えるブロック位置の一覧
    const attachedBlocks: mc.BlockLocation[] = piston.attachedBlocks;
    for (const blockLocation of attachedBlocks) {
      const block: mc.Block = dimension.getBlock(blockLocation);
      if (block.type === mc.MinecraftBlockTypes.obsidian) {
        // 黒曜石が含まれていると動かない
        event.cancel = true;
      } else {
        // それ以外のブロックはTNTに変える
        block.setType(mc.MinecraftBlockTypes.tnt);
      }
    }
  }
}

mc.world.events.beforePistonActivate.subscribe(onBeforePistonActivate);
```

## 参考

* [ButtonPushEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/buttonpushevent)
* [LeverActionEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/leveractionevent)
* [PistonActivateEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/pistonactivateevent)
* [BeforePistonActivateEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/beforepistonactivateevent)


装置を操作したとき

装置に関するイベント


ステータス効果を受けたときに発生するイベントです。

## EffectAddEvent

エンティティにエフェクトが**追加**されたときに発生するイベントです。

追加なので、すでに同じ効果を持っている場合には発生しません。

* `/effect`で効果を受けたとき
* ポーションを飲んだ時
* ハスクの攻撃により空腹効果をうけたとき
* ...など

```typescript
import * as mc from 'mojang-minecraft';

function onEffectAdd(event: mc.EffectAddEvent) {
  // 追加されたエフェクト
  const effect: mc.Effect = event.effect;
  // エフェクト番号
  const effectState: number = event.effectState;
  // 効果を受けたエンティティ
  const entity: mc.Entity = event.entity;

  entity.dimension.runCommand(
    `say ${entity.id} が ${effect.displayName}(${effectState}) の効果を` +
      `強さ${effect.amplifier} で ${effect.duration}ティック間 受けました。`
  );
}

mc.world.events.effectAdd.subscribe(onEffectAdd);
```

## 参考

* [EffectAddEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/effectaddevent)


エフェクトにかかったとき

エフェクトに関するイベント


エンティティに関する操作をしたときに発生するイベントです。

## EntityCreateEvent

新しいエンティティが作成されたとき。（自然スポーンを含む）

```typescript
import * as mc from 'mojang-minecraft';

function onEntityCreate(event: mc.EntityCreateEvent) {
  // イベントを起こしたエンティティ
  const entity: mc.Entity = event.entity;

  // すべてを表示すると多すぎるので羊に限定
  if (entity.id === mc.MinecraftEntityTypes.sheep.id) {
    const loc = `${entity.location.x} ${entity.location.y} ${entity.location.z}`;
    entity.dimension.runCommand(`say ${entity.id} が 座標(${loc}) に出現しました。`);
  }
}

mc.world.events.entityCreate.subscribe(onEntityCreate);
```

## EntityHitEvent

エンティティが近接攻撃、他のエンティティやブロックに影響を与える可能性があるとき。

遠距離攻撃は`ProjectileHitEvent`の方を使う。

```typescript
import * as mc from 'mojang-minecraft';

function onEntityHit(event: mc.EntityHitEvent) {
  // イベントを起こしたエンティティ
  const attacker: mc.Entity = event.entity;
  // 攻撃が当たったブロック
  const block: mc.Block = event.hitBlock;
  // 攻撃が当たったエンティティ
  const victim: mc.Entity = event.hitEntity;

  // 攻撃の当たったブロック情報があれば
  if (block !== undefined) {
    attacker.dimension.runCommand(`say ${attacker.id} が ${block.id} を破壊しだしました。`);
  }

  // 攻撃の当たったエンティティ情報があれば
  if (victim !== undefined) {
    attacker.dimension.runCommand(`say ${attacker.id} が ${victim.id} に近接攻撃しました。`);
  }
}

mc.world.events.entityHit.subscribe(onEntityHit);
```

## EntityHurtEvent

エンティティがダメージを受けたとき。

```typescript
import * as mc from 'mojang-minecraft';

function onEntityHurt(event: mc.EntityHurtEvent) {
  // ダメージの理由
  const cause: string = event.cause;
  // ダメージ量
  const damage: number = event.damage;
  // ダメージを与えたエンティティ
  const attacker: mc.Entity = event.damagingEntity;
  // ダメージを受けたエンティティ
  const victim: mc.Entity = event.hurtEntity;
  // ダメージを与えた発射物
  const projectile: mc.Entity = event.projectile;

  // 発射物による影響かどうかで処理を分ける
  if (projectile === undefined) {
    attacker.dimension.runCommand(
      `say ${attacker.id} が ${victim.id} に ${cause} で ${damage} のダメージを与えました。`
    );
  } else {
    attacker.dimension.runCommand(
      `say ${attacker.id} が ${victim.id} に ${cause}(${projectile.id}) で ${damage} のダメージを与えました。`
    );
  }
}

mc.world.events.entityHurt.subscribe(onEntityHurt);
```

## DataDrivenEntityTriggerEvent

コンポーネントの変更イベントが発生したとき。

* クリーパーが帯電クリーパーになるとき
* 羊から羊毛を刈ったとき
* ...など

```typescript
import * as mc from 'mojang-minecraft';

function onDataDrivenEntityTriggerEvent(event: mc.DataDrivenEntityTriggerEvent) {
  // イベントを起こしたエンティティ
  const entity: mc.Entity = event.entity;
  // イベントを起こしたエンティティのidentifier
  const identifier: string = event.id;
  // 変更されたコンポーネント
  const modiffiers: mc.DefinitionModifier[] = event.modifiers;

  // 変更されたコンポーネントで繰り返し(同時複数変更される可能性がある)
  modiffiers.forEach(function (moddifer) {
    // 追加されるコンポーネントごとに繰り返し
    moddifer.componentGroupsToAdd.forEach(function (component) {
      // そのコンポーネント名を表示
      entity.dimension.runCommand(`say ${identifier} イベントで ${component}コンポーネント が追加されました。`);
    });
    // 削除されるコンポーネントごとに繰り返し
    moddifer.componentGroupsToRemove.forEach(function (component) {
      // そのコンポーネント名を表示
      entity.dimension.runCommand(`say ${identifier} イベントで ${component}コンポーネント が削除されました。`);
    });
  });
}

mc.world.events.dataDrivenEntityTriggerEvent.subscribe(onDataDrivenEntityTriggerEvent);
```

## BeforeDataDrivenEntityTriggerEvent

コンポーネントの変更イベントが発生するとき。

```typescript
import * as mc from 'mojang-minecraft';

function onDeforeDataDrivenEntityTriggerEvent(event: mc.BeforeDataDrivenEntityTriggerEvent) {
  // イベントを停止させるか
  event.cancel;
  // イベントを起こしたエンティティ
  const entity: mc.Entity = event.entity;
  // イベントを起こしたエンティティのidentifier
  const identifier: string = event.id;
  // これから変更されるコンポーネント
  const modiffiers: mc.DefinitionModifier[] = event.modifiers;

  modiffiers.forEach(function (moddifer) {
    moddifer.componentGroupsToAdd.forEach(function (component) {
      entity.dimension.runCommand(
        `say ${identifier} イベントで ${component}コンポーネント が追加されようとしています。`
      );
    });
    moddifer.componentGroupsToRemove.forEach(function (component) {
      entity.dimension.runCommand(
        `say ${identifier} イベントで ${component}コンポーネント が削除されようとしています。`
      );
    });
  });
}

mc.world.events.beforeDataDrivenEntityTriggerEvent.subscribe(onDeforeDataDrivenEntityTriggerEvent);
```

## 参考

* [EntityCreate Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/entitycreateevent)
* [EntityHit Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/entityhitevent)
* [EntityHurt Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/entityhurtevent)
* [DataDrivenEntityTriggerEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/datadrivenentitytriggerevent)
* [BeforeDataDrivenEntityTriggerEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/beforedatadrivenentitytriggerevent)


エンティティに変化があったとき

エンティティに関するイベント


エンティティが爆発したときに発生するイベントです。

## ExplosionEvent

爆発が起こり、爆発結果が確定した後に発生するイベントです。

```typescript
import * as mc from 'mojang-minecraft';

function onExplosion(event: mc.ExplosionEvent) {
  // イベントが発生した次元
  const dimension: mc.Dimension = event.dimension;
  // 爆発の影響を受けるブロック位置の配列
  const blockLocations: mc.BlockLocation[] = event.impactedBlocks;
  // 爆発した(する)エンティティ
  const explodeEntity: mc.Entity = event.source;

  // 爆発したエンティティがクリーパーなら
  if (explodeEntity.id === mc.MinecraftEntityTypes.creeper.id) {
    // 影響を受けるブロックでループ
    blockLocations.forEach(function (blockLocation) {
      // 対象ブロックを変更
      // 壊れることが確定したブロックなので、変更後のブロックが壊れることになる
      // 例え岩盤でもアイテム化する
      dimension.getBlock(blockLocation).setType(mc.MinecraftBlockTypes.bedrock);
    });
    // 爆発後なのでcancelはできない
  }
}

mc.world.events.explosion.subscribe(onExplosion);
```

## BeforeExplosionEvent

爆発が起こり、爆発結果が確定する前に発生するイベントです。

```typescript
import * as mc from 'mojang-minecraft';

function onBeforeExplosion(event: mc.BeforeExplosionEvent) {
  // イベントを停止させるか
  event.cancel;
  // イベントが発生した次元
  const dimension: mc.Dimension = event.dimension;
  // 爆発の影響を受けるブロック位置の配列
  const blockLocations: mc.BlockLocation[] = event.impactedBlocks;
  // 爆発した(する)エンティティ
  const explodeEntity: mc.Entity = event.source;

  // 爆発したエンティティがTNTなら
  if (explodeEntity.id === mc.MinecraftEntityTypes.tnt.id) {
    // 影響を受けるブロックでループ
    blockLocations.forEach(function (blockLocation) {
      // 対象ブロックを変更
      dimension.getBlock(blockLocation).setType(mc.MinecraftBlockTypes.goldBlock);
    });
    // 真にすると爆発させない -> ブロックの変更だけをして終わる
    event.cancel = true;
  }
}

mc.world.events.beforeExplosion.subscribe(onBeforeExplosion);
```

## 参考

* [ExplosionEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/explosionevent)
* [BeforeExplosionEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/beforeexplosionevent)


爆発したとき

爆発に関するイベント


アイテムを使用するときに発生するイベントです。

## "Use"と"UseOn"の違い

`Use`はアイテムを右クリックで使用したときに発生します。

`UseOn`はアイテムをブロックに向けて使用したときに発生します。
ブロックに影響を与えないアイテムでも発生します。

## イベントが発生する順番

似たようなイベント名が並びますが、発生順としては(おそらく)次の通りになります。
このように一度の行動で、複数のイベントが発生し、それぞれで取得できる内容が異なります。

1. `ItemStartUseOnEvent`
2. `BeforeItemUseOnEvent`
3. `ItemUseOnEvent`
4. `BeforeItemUseEvent`
5. `ItemUseEvent`
6. `ItemStopUseOnEvent`

`UseOn`が先で`Use`が後。
そしてそれぞれの前に`Before`が発生し、それらを`Start`と`Stop`で挟みます。

## ItemUseEvent

アイテムの使用を始めたとき。(アイテムを持って右クリックした時点で発生)

アイテムが消費されたときではありません。

```typescript
import * as mc from 'mojang-minecraft';

function onItemUse(event: mc.ItemUseEvent) {
  const item: mc.ItemStack = event.item;
  const user: mc.Entity = event.source;

  user.dimension.runCommand(`say itemUse: ${user.nameTag} が ${item.id} を使用しました。`);
}

mc.world.events.itemUse.subscribe(onItemUse);
```

## BeforeItemUseEvent

```typescript
import * as mc from 'mojang-minecraft';

function onBeforeItemUse(event: mc.BeforeItemUseEvent) {
  // イベントを停止させるか
  event.cancel;
  // 影響を受けるアイテム
  const item: mc.ItemStack = event.item;
  // イベントを起こしたエンティティ
  const user: mc.Entity = event.source;

  user.dimension.runCommand(`say beforeItemUse: ${user.nameTag} が ${item.id} を使用します。`);
}

mc.world.events.beforeItemUse.subscribe(onBeforeItemUse);
```

## ItemStartUseOnEvent

アイテムをブロックに向けて使用した始めたとき。

* ターゲットにしたブロック位置
* アイテム使用後にブロックが置かれる位置

これら両方の位置が取得できます。

```typescript
import * as mc from 'mojang-minecraft';

function onItemStartUseOn(event: mc.ItemStartUseOnEvent) {
  // ブロックを置くときにターゲットにした面
  const blockFace: mc.Direction = event.blockFace;
  // ブロックを置くときにターゲットにした位置
  const blockLocation: mc.BlockLocation = event.blockLocation;
  // ブロックが置かれる位置
  const buildBlockLocation: mc.BlockLocation = event.buildBlockLocation;
  // 使用するアイテム
  const item: mc.ItemStack = event.item;
  // 使用したエンティティ
  const user: mc.Entity = event.source;

  const blockLoc = `${blockLocation.x} ${blockLocation.y} ${blockLocation.z}`;
  const buildLoc = `${buildBlockLocation.x} ${buildBlockLocation.y} ${buildBlockLocation.z}`;
  user.dimension.runCommand(
    `say itemStartUseOn: ${user.nameTag} が ${item.id} を ${blockLoc}(${buildLoc}) に使用します。`
  );
}

mc.world.events.itemStartUseOn.subscribe(onItemStartUseOn);
```

## ItemStopUseOnEvent

```typescript
function onItemStopUseOn(event: mc.ItemStopUseOnEvent) {
  // ブロックを置くときにターゲットにした位置
  const blockLocation: mc.BlockLocation = event.blockLocation;
  // 使用するアイテム
  const item: mc.ItemStack = event.item;
  // 使用したエンティティ
  const user: mc.Entity = event.source;

  const location = `${blockLocation.x} ${blockLocation.y} ${blockLocation.z}`;
  user.dimension.runCommand(`say itemStopUseOn: ${user.nameTag} が ${item.id} を ${location} に使用します。`);
}

mc.world.events.itemStopUseOn.subscribe(onItemStopUseOn);
```

## ItemUseOnEvent

アイテムをブロックに向けて使用したとき。

* ターゲットにしたブロック面(上下東西南北)
* その面の中の(x, y)座標

これらが取得できます。

```typescript
function onItemUseOn(event: mc.ItemUseOnEvent) {
  // ブロックを置くときにターゲットにした面
  const blockFace: mc.Direction = event.blockFace;
  const faceLocX: number = event.faceLocationX;
  const faceLocY: number = event.faceLocationY;
  // ブロックを置くときにターゲットにした位置
  const blockLocation: mc.BlockLocation = event.blockLocation;
  // 使用するアイテム
  const item: mc.ItemStack = event.item;
  // 使用したエンティティ
  const user: mc.Entity = event.source;

  const location = `${blockLocation.x} ${blockLocation.y} ${blockLocation.z}`;
  user.dimension.runCommand(`say itemUseOn: ${user.nameTag} が ${item.id} を ${location} に使用しました。`);
}

mc.world.events.itemUseOn.subscribe(onItemUseOn);
```

## BeforeItemUseOnEvent

アイテムをブロックに向けて使用する直前。

```typescript
function onBeforeItemUseOn(event: mc.BeforeItemUseOnEvent) {
  // ブロックを置くときにターゲットにした面
  const blockFace: mc.Direction = event.blockFace;
  const faceLocX: number = event.faceLocationX;
  const faceLocY: number = event.faceLocationY;
  // ブロックを置くときにターゲットにした位置
  const blockLocation: mc.BlockLocation = event.blockLocation;
  // 使用するアイテム
  const item: mc.ItemStack = event.item;
  // 使用したエンティティ
  const user: mc.Entity = event.source;

  // 砂はブロックの上にしか置けない
  if (item.id === mc.MinecraftBlockTypes.sand.id && blockFace !== mc.Direction.up) {
    event.cancel = true;
  } else {
    const location = `${blockLocation.x} ${blockLocation.y} ${blockLocation.z}`;
    user.dimension.runCommand(`say beforeItemUseOn: ${user.nameTag} が ${item.id} を ${location} に使用します。`);
  }
}

mc.world.events.beforeItemUseOn.subscribe(onBeforeItemUseOn);
```

## ItemDefinitionTriggeredEvent

アイテムのコンポーネントを変更したときに発生するイベント。

未確認。

```typescript
function onItemDefinitionEvent(event: mc.ItemDefinitionTriggeredEvent) {
  event.eventName;
  event.item;
  event.source;

  event.source.dimension.runCommand(`say itemDefinitionEvent`);
}

mc.world.events.itemDefinitionEvent.subscribe(onItemDefinitionEvent);
```

## BeforeItemDefinitionTriggeredEvent

アイテムのコンポーネントを変更する前に発生するイベント。

未確認。

```typescript
function onBeforeItemDefinitionEvent(event: mc.BeforeItemDefinitionTriggeredEvent) {
  // イベントを停止させるか
  event.cancel;
  // イベント名
  event.eventName;
  // 影響を受けるアイテム
  event.item;
  // イベントを起こしたエンティティ
  event.source;

  event.source.dimension.runCommand(`say beforeItemDefinitionEvent`);
}

mc.world.events.beforeItemDefinitionEvent.subscribe(onBeforeItemDefinitionEvent);
```

## 参考

* [ItemUseEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/itemuseevent)
* [BeforeItemUseEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/beforeitemuseevent)
* [ItemStartUseOnEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/Itemstartuseonevent)
* [ItemStopUseOnEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/Itemstopuseonevent)
* [ItemUseOnEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/itemuseonevent)
* [BeforeItemUseOnEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/beforeitemuseonevent)
* [ItemDefinitionTriggeredEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/itemdefinitiontriggeredevent)
* [BeforeItemDefinitionTriggeredEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/beforeItemdefinitiontriggeredevent)


アイテムを使ったとき

アイテムに関するイベント


プレイヤーに(だけ)関係するイベントです。

現在は、ログインとログアウトのイベントがあります。
それ以外のイベントについては[他のエンティティと共通のイベント](/mojang-minecraft-events-entity/)を使用してください。

## PlayerJoinEvent

プレイヤーがワールドへ参加したときに発生するイベントです。

このときにコマンドの実行はできないようです。

```typescript
import * as mc from 'mojang-minecraft';

export function onPlayerJoin(event: mc.PlayerJoinEvent) {
  // 参加したプレイヤー
  const player: mc.Player = event.player;

  // この時点でのコマンドは無効
  // event.player.runCommand('give @s apple');

  // 専用のメソッドでアイテムを渡す
  const itemStack = new mc.ItemStack(mc.MinecraftItemTypes.apple, 1);
  itemStack.nameTag = 'ログインボーナス';
  const inventory = player.getComponent('minecraft:inventory') as mc.EntityInventoryComponent;
  inventory.container.addItem(itemStack);
}

mc.world.events.playerJoin.subscribe(onPlayerJoin);
```

## PlayerLeaveEvent

プレイヤーがワールドを退出したときのイベントです。

退出した後のイベントなので、名前しか取得できません。

```typescript
function onPlayerLeave(event: mc.PlayerLeaveEvent) {
  // 退出したプレイヤーの名前だけ取得可能
  const playerName: string = event.playerName;

  const dimension = mc.world.getDimension(mc.MinecraftDimensionTypes.overworld);
  dimension.runCommand(`say PlayerLeaveEvent: ${playerName} がワールドから退出しました。`);
}

mc.world.events.playerLeave.subscribe(onPlayerLeave);
```

## 参考

* [PlayerJoinEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/playerjoinevent)
* [PlayerLeaveEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/playerleaveevent)


ログイン・ログアウトしたとき

プレイヤーに関するイベント


発射物に関するイベントです。

## ProjectileHitEvent

発射物が何かに当たったときに発生するイベントです。

当たったブロックやエンティティの情報を詳しく取得できます。

```typescript
import * as mc from 'mojang-minecraft';

function projectileHit(event: mc.ProjectileHitEvent) {
  // イベントが発生した次元
  const dimension: mc.Dimension = event.dimension;
  // 発射したエンティティ
  const shooter: mc.Entity = event.source;

  // 当たったブロック情報
  // 通常のブロック情報だけではなく、どこに当たったかの情報も入っている
  const hitBlock: mc.BlockHitInformation = event.blockHit;
  // 当たったエンティティ情報
  const hitEntity: mc.EntityHitInformation = event.entityHit;

  // 当たった発射物
  const projectile: mc.Entity = event.projectile;
  // 当たったときの発射物の位置（当たった相手の位置ではない）
  const projectileLocation: mc.Location = event.location;
  // 当たったときの投射物の方向ベクトル
  const vector: mc.Vector = event.hitVector;

  // ブロックに当たったとき
  if (hitBlock !== undefined) {
    // 当たったブロックの情報
    const block: mc.Block = hitBlock.block;
    // 当たった面
    const face: mc.Direction = hitBlock.face;
    // 当たった位置
    const faceLocX: number = hitBlock.faceLocationX;
    const faceLocY: number = hitBlock.faceLocationY;

    // ターゲットブロックに当たったとき
    if (block.id === mc.MinecraftBlockTypes.target.id) {
      // getDistanceFromBlockCenter() は後述
      const distance: number = getDistanceFromBlockCenter(faceLocX, faceLocY);
      dimension.runCommand(`say ブロック面の中心から ${trunc(distance, 2)} 離れた場所に当たりました。`);

      // 距離に応じて処理を分ける（中心に近いほど高得点）
      let point: number | string = 0;
      if (distance < 0.1) {
        point = 10;
        dimension.runCommand(`say 大当たり! 経験値 +${point}`);
      } else if (distance < 0.3) {
        point = 3;
        dimension.runCommand(`say 当たり! 経験値 +${point}`);
      } else {
        point = '-1L';
        dimension.runCommand(`say はずれ! レベル -1`);
      }
      dimension.runCommand(`xp ${point} ${shooter.nameTag}`);
    }
  }

  // エンティティに当たったとき
  if (hitEntity !== undefined) {
    // 現在EntityHitInformationにはentity情報しか入っていない
    const entity: mc.Entity = hitEntity.entity;
    // 当たったエンティティの頭の中心位置を取得する
    const headLocation: mc.Location = entity.headLocation;
    // 頭の位置と発射物の位置が、特定の距離以内であるかを判定（距離単位はブロック）
    // これは2点間の距離だけを判定しているので、必ずしも頭に当たっているわけではない
    const isHeadShot: boolean = headLocation.isNear(projectileLocation, 0.7);
    if (isHeadShot) {
      dimension.runCommand(`say Head Shot! ${shooter.nameTag} -> ${entity.id}`);
      // エンティティを倒す（残りHPを無視して）
      entity.kill();
    } else {
      // getDistance() は後述
      const distance = getDistance(headLocation, projectileLocation)
      dimension.runCommand(`say 頭との距離: ${trunc(distance, 2)}ブロック`);
    }
  }
}

mc.world.events.projectileHit.subscribe(projectileHit);
```

### ブロック面の中心からの距離を求める

平面座標AとBの距離を求める関数です。

* 座標Aは１ブロック内の位置なので`(x, y)`のそれぞれの範囲は`0.0`以上`1.0`未満です。
* 座標Bはブロックの中心なので、`(0.5, 0.5)`で固定です。

```typescript
export function getDistanceFromBlockCenter(faceLocX: number, faceLocY: number) {
  // 当った位置と中心の差の2乗
  const x = (faceLocX - 0.5) ** 2;
  const y = (faceLocY - 0.5) ** 2;
  // それらを足したものの平方根が2点間の距離
  return Math.sqrt(x + y);
}
```

#### 数学的な解説

2点AB間の距離"d"は[三平方の定理](https://ja.wikipedia.org/wiki/%E3%83%94%E3%82%BF%E3%82%B4%E3%83%A9%E3%82%B9%E3%81%AE%E5%AE%9A%E7%90%86)と[平方根](https://ja.wikipedia.org/wiki/%E5%B9%B3%E6%96%B9%E6%A0%B9)を使って、次の計算で求めます。

<Math>

$$d = \sqrt{(x_a - x_b)^2 + (y_a - y_b)^2}$$

</Math>

上の関数はこの計算をJavaScriptのプログラムとして記述した形になります。

<R t="square root">平方根</R>はJavaScriptでは`Math.sqrt()`と書き、「<R t="べきじょう">冪乗</R>」は`**`とアスタリスクを2つ繋げて書きます。

具体的な解説は、次のような動画を参考にしてください。

* [YouTube:【中３　数学】　三平方の定理４　２点間の距離　（１２分）](https://www.youtube.com/watch?v=vPN9UvGLKyg)

<Note color="blue">
この2点間の距離を求める計算は、図形計算の基本であり、空間を操作するマインクラフトでは、今後あらゆる場面で登場します。
数学的な意味がわからなくても、この関数を使えば距離の計算はできますが、出来るだけ自分で理解できるようにしておきましょう。
</Note>

### 2点間の空間の距離を求める

空間座標AとBの距離を求める関数です。

上のコード例の場合は、当った時点での「A:エンティティの頭の位置」と「B:発射物の位置」の距離を算出しています。

```typescript
export function getDistance(locationA: mc.Location, locationB: mc.Location) {
  // A地点とB地点の差の2乗
  const x = (locationA.x - locationB.x) ** 2;
  const y = (locationA.y - locationB.y) ** 2;
  const z = (locationA.z - locationB.z) ** 2;
  // それらを足したものの平方根が2点間の距離
  return Math.sqrt(x + y + z);
}
```

#### 数学的な解説

空間座標の距離も平面と同じように三平方の定理から計算し、2点ABの空間座標の距離"d"は次のようになります。

<Math>

$d = \sqrt{(x_a - x_b)^2 + (y_a - y_b)^2 + (z_a - z_b)^2}$

</Math>

* [YouTube:【高校　数学B】　空間ベクトル４　２点間の距離　(１２分)](https://www.youtube.com/watch?v=8CLpyWmibSc)

### 小数点以下の値を特定の桁で切り捨てる

表示用に小数をある桁数で切り捨てます。
表示しない場合、この処理を挟む必要はありません。

JavaScriptには特定の位置の小数を切り捨てる関数が標準で用意されていないので、自分で用意する必要があります。

ここでは `value = 3.141592, digit = 2` の場合 `3.14` が返ります。

```typescript
function trunc(value: number, digit: number = 0) {
  // 桁数を決める digit=2 の場合は base=100
  const base = 10 ** digit;
  // baseで桁を上げた上で小数点切り捨て、その後baseで割って小数に戻す
  return Math.trunc(value * base) / base;
}
```

## 参考

* [ProjectileHitEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/projectilehitevent)


発射物が当たったとき

発射物に関するイベント


ワールドに関するイベントです。

## TickEvent

このイベントはティック毎（1秒間に20回）に発生します。

```typescript
import * as mc from 'mojang-minecraft';

const overworld = mc.world.getDimension(mc.MinecraftDimensionTypes.overworld);

function tick(event: mc.TickEvent) {
  // このイベントが起きてからのティック数
  // と、公式ドキュメントにあるが、ワールドが作成されてからのティック数になっている(1.19.21)
  const tick: number = event.currentTick;
  // 前回のティックからの時間
  // ティックは1秒間に20回起こることになっているが、毎回厳密に0.05秒になるわけではない
  // 細かい補正するために用いられる
  const delta: number = event.deltaTime;

  // (200ティック = 10秒)に1回実行(毎ティック表示すると多すぎるので)
  if (tick % 200 === 0) {
    overworld.runCommand(`say TickEvent: ${tick} tick`);
  }
}

mc.world.events.tick.subscribe(tick);
```

## WeatherChangeEvent

天候が変化したときに発生するイベント。

変化したときなので、コマンドで同じ天候を指定した場合にはこのイベントは発生しません。

```typescript
import * as mc from 'mojang-minecraft';

const overworld = mc.world.getDimension(mc.MinecraftDimensionTypes.overworld);

function onWeatherChage(event: mc.WeatherChangeEvent) {
  // イベントが発生した次元名（ここは文字列であることに注意）
  const dimensionName: string = event.dimension;
  // 変更後の天候が雨かどうか
  const isRaining: boolean = event.raining;
  // 変更後の天候が雷かどうか
  const isLightning: boolean = event.lightning;

  // {(雨でない) かつ (雷でない)} ならば 晴れ
  if (!isRaining && !isLightning) {
    // /weather clear
    overworld.runCommand(`say ${dimensionName} の天候は「晴れ」です。`);
  }
  // 雨だが雷ではない
  else if (isRaining && !isLightning) {
    // /weather rain
    overworld.runCommand(`say ${dimensionName} の天候は「雨」です。`);
  }
  // 雨ではないが雷
  else if (!isRaining && isLightning) {
    // コマンドではこの状態は起こせない
    // 自然に発生する状況があるかは未確認
    overworld.runCommand(`say ${dimensionName} の天候は「雷」です。`);
  }
  // 雨かつ雷
  else if (isRaining && isLightning) {
    // /weather thunder
    overworld.runCommand(`say ${dimensionName} の天候は「雷雨」です。`);
  }
}

mc.world.events.weatherChange.subscribe(onWeatherChage);
```

## WorldInitializeEvent

ワールドが初期化される時に実行される。

現在(`BE:1.19.21`)はダイナミックプロパティの登録機能しかありません。
詳しい使い方はダイナミックプロパティの項目で解説します。

```typescript
function onWorldInitialize(event: mc.WorldInitializeEvent) {
  // ダイナミックプロパティの登録
  event.propertyRegistry;
}

mc.world.events.weatherChange.subscribe(onWorldInitialize);
```

## 参考

* [TickEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/tickevent)
* [WeatherChangeEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/weatherchangeevent)
* [WorldInitializeEvent Class](https://docs.microsoft.com/ja-jp/minecraft/creator/scriptapi/mojang-minecraft/worldinitializeevent)


ワールドに関するイベント


このコースはMinecraft Bedrock版のアドオンで使用できる、スクリプト機能（ゲームテストフレームワーク）を用いた、ゲーム作成チュートリアルです。

ここでは、ごく簡単なミニゲームの制作を通して、アドオンのスクリプト機能でできることを確認していきます。


## このコースの対象者

* コマンドでは作れない複雑な処理を作ってみたい
* 本格的なプログラミングを身につけたい
* JavaScriptの基礎知識はあるが、アドオンでのスクリプトの書き方がわからない


### 前提条件

このコースを進めるための事前知識は次のとおりです。

* [スラッシュコマンド](/command/)の基本を理解している
  * プログラムを簡単にするため、細かい処理はスラッシュコマンドで代用する
* JavaScript/TypeScriptの基本を理解している
  * 変数・配列・オブジェクト・関数など初歩的な文法だけでよい
* [アドオン開発テンプレート](add-on-development-template)を準備できている


## このコースでの学習目標

* ごく簡単なゲーム制作を通して、アドオンのスクリプトの概要を理解する


### このコースで対応していないこと

* スクリプト内で用いられたコード・文法の完全な解説


## 完成コード

各段階のコードはGitHubにアップロードしてあります。

<ExButton href="https://github.com/akihamitsuki/fight-on-height">GitHubでコードを確認</ExButton>


はじめてのゲーム制作チュートリアル

スクリプトによる、はじめてのゲーム制作チュートリアル


それではミニゲームの開発を始めていきましょう。

今回作るのゲームの内容は、<mark>「一定時間内にプレイヤーが移動した高低差を得点とする」</mark>とします。
また、開発方法として、最初に完璧な設計図を作らずに、必要そうな機能を小さく追加していく方法にします。

1回目となる今回の記事では、重要そうなプレイヤーの高さを取得して表示してみます。


## 開発テンプレートの準備をする

こちらの記事を参考にして開発テンプレートの準備をしてください。

<LinkCard slug="add-on-development-template" />

以降のコードは、この開発テンプレートの`scripts/main.ts`ファイルに書き込んでいってください。

<Note color="amber">
このチュートリアルでは、TypeScriptを使っていきます。
そのため、そのままコードをアドオン内のJavaScriptファイルに書き込んでも動かないので注意してください。
TypeScriptを動かすには、上のテンプレートのようにJavaScriptに変換する処理が必要です。
</Note>


## プログラムを実行する条件を決める

最初は「きちんとプログラムが動くか」を確認するところから始めましょう。

<mark>プログラムの形は「○○をしたときに、××を実行する」が基本です(入力と出力)。</mark>
そのため、プログラムを書くときには、<mark>最初にどういう条件のときに動いてほしいのかを決めます。</mark>
この実行する条件をアドオンでは「[イベント](/mojang-minecraft-events/)」といい、様々な条件があります。

<LinkCard slug="mojang-minecraft-events" />

今回は動いているかを確認するのが目的なので、確認しやすいものなら、どんなイベントでも構いません。
<mark>まずは使いやすい「チャット欄からメッセージを送信したとき(`BeforeChatEvent`)」を条件にして、プログラムが動くかを確認してみましょう。</mark>

<mark>最初に作成した開発テンプレート内の`scripts/main.ts`ファイルを開いて、次の内容で上書きしてください。</mark>
`//`で始まる行はコメント(プログラムには関係ないメモ)なので書かなくても構いません。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

// BeforeChatEvent: チャット欄からメッセージを送信したとき
mc.world.events.beforeChat.subscribe((event) => {
  // この中のプログラムが動く
  // 送信されたメッセージを「before chat event」に変更
  event.message = 'before chat event';
});
```

<mark>書き終えたら、デプロイ(アドオンとして使えるようにすること)して、アドオンを適用したワールドを開いてください。</mark>
デプロイ方法がわからない場合は、[開発テンプレートの設定記事](/add-on-development-template/)を読み直してください。

今回のイベントは「チャット欄からメッセージを送信したとき」なので、チャット欄をひらいて何かメッセージを送信してください。（1文字だけでも構いません）
送信したら、次の文章が表示されるか確認しましょう。

```txt:Minecraftのチャット欄
before chat event
```

きちんと表示されたら、イベントが正常に設定できています。
プログラムの作成は、一度に大きな処理を作らずに、このような小さな更新を積み重ねていきます。

## 上のコードの解説

上のコードが何をしているかを個別に見てきましょう。


### モジュールの読み込み

次の文は[import文](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Statements/import)です。
今回のアドオンに関するモジュール（別ファイルにあるプログラム）を読み込んでいます。
このモジュールをアドオンで読み込めるようにするには、`manifest.json`で設定しています。

```typescript
import * as mc from 'mojang-minecraft';
```

これは次の意味のプログラムです。

* `import *`: すべて読み込む
* `as mc`:「mc」という名前で
* `from 'mojang-minecraft'`:「mojang-minecraft」モジュールから

最初にこの文の構造を完璧に理解する必要はありません、
「Minecraftに関するプログラムを他のところから持ってくる」という処理をしているんだな、という緩い理解で十分です。


### イベント登録メソッド

```typescript
mc.world.events.beforeChat.subscribe();
```

上で読み込んだ

* `mc`モジュールの中の
* `world`オブジェクトの中の
* `events`オブジェクトの中の
* `beforeChat`オブジェクトの中の
* `subscribe()`メソッド

を使用しています。

この部分はオブジェクトの使い方に慣れてくれば、後から意味が分かるようになります。
はじめのうちは、意味が分からなくても、とりあえずこのように書いておいてください。


### イベント関数

上の登録メソッドに引数として、次のような[アロー関数](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Functions/Arrow_functions)を渡して、イベントを登録しています。

```typescript
(event) => {
  event.message = 'event';
};
```

引数である`event`は、イベントが実行されたときの、イベントの内容が渡されてきます。
今回はチャットに関するイベントなので、この中にメッセージが入っています。
上の処理では、このメッセージ内容を書き換えています。

いったんアロー関数を変数に入れると次の書き方になります。
別けて書く場合は引数の型が必要になるので注意してください。
(`(event: mc.BeforeChatEvent)`の部分)

```typescript
// アロー関数を別に書いた場合
const onBeforeChat = (event: mc.BeforeChatEvent) => {
  event.message = 'event';
};

mc.world.events.beforeChat.subscribe(onBeforeChat);
```

従来の関数表記でも同じことができます。

```typescript
// 従来の関数の場合
function onBeforeChat(event: mc.BeforeChatEvent) {
  event.message = 'event';
}

mc.world.events.beforeChat.subscribe(onBeforeChat);
```

今回の使い方では変数に入れる処理を省略して、直接メソッドの中にアロー関数を書いています。

<Note color="blue" title="用語の確認">
* __アロー関数__: 独立した新しい形式の関数。アロー関数で書くと、なにかと便利な場面が多い。
* __関数__: 独立した従来の関数。古いわけではなく、こちらも現役で使う。
* __メソッド__: オブジェクトの中の関数。基本的には区別されるので、できるだけ使い分けること。
</Note>

アロー関数と従来の関数は機能が少し異なりますが、はじめのうちは「書き方が違うだけ」という理解で問題ありません。


## sayコマンドを実行する

次は好きな処理を実行できるように、スラッシュコマンドを使えるようになっておきましょう。

基本的にはスラッシュコマンドを使わず、JavaScriptで処理を書いた方が早くなります。
しかし、それではそれぞれの処理方法を覚えないといけないので、最初はコマンドを実行する形で進めていきます。

スラッシュコマンドは`runCommand()`メソッドを使い、引数としてコマンド文を入れます。
今回の場合は`/say`コマンドでメッセージを表示しています。

前回書いたコードはすべて消して、次のコードに書き換えてください。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

mc.world.events.beforeChat.subscribe((event) => {
  const text = `チャット内容「${event.message}」`
  const sayCommand = `say ${text}`
  try {
    event.sender.runCommand(sayCommand);
  } catch (error) {
    event.sender.runCommand(`say ${error}`);
  }
}
```

`runCommand()`メソッドや`try...catch文`については次の記事で詳しく解説しています。
わからなくなったらこちらの記事を読んでください。

<LinkCard slug="mojang-minecraft-runcommand" />

書き終えたら、前回と同じようにデプロイして、ワールド上でチャットを入力して動作を確認してください。

今回は送信内容を書き換えていないので、もとの送信メッセージと、`/say`で実行したメッセージの2つが表示されて入れば成功です。


## 高さを取得する

チャットコマンドを実行できたので、次はプレイヤーの高さを取得して表示してみましょう。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

mc.world.events.beforeChat.subscribe((event) => {
  // チャット欄から送信した内容が「height」のとき
  if (event.message === 'height') {
    // プレイヤーの高さを取得する
    const height = Math.floor(event.sender.location.y);
    try {
      // /sayコマンドで高さを表示する
      event.sender.runCommand(`say 現在の高さは ${height} です。`);
    } catch (error) {
      event.sender.runCommand(`say ${error}`);
    }
    // 送信したメッセージは表示しない
    event.cancel = true;
  }
});
```

### if文で特定のメッセージのときだけ処理を実行させる

`event.message`には送信したメッセージ内容が入っているのでした。
この内容をif文で判定すれば、特定の内容の時だけ、専用の処理を行えます。

```typescript
if (event.message === 'height')
```

<Note color="amber" title="条件式のイコールは2つか3つか">
「等しい」を判定する条件式は基本的に`===`と等号を3つ繋げて書きます。
3つの場合は[厳密等価](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Operators/Strict_equality)といい、2つの場合は[等価](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Operators/Equality)で、これらは別物です。
今回の例ではどちらを使っても同じ結果になりますが、<strong>もし2つか3つか迷ったら、3つの方を使う</strong>と覚えておいてください。
特別な場合にだけ2つの方を使います。
</Note>


### オブジェクトの中のオブジェクトの中のオブジェクトを取得する

チャットイベントから送信者を取得できます。
これがチャットを使用したプレイヤーのことです。

そしてこのプレイヤーの中に座標情報があるので、それを取得して表示します。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

mc.world.events.beforeChat.subscribe((event) => {
  // イベントの送信者(プレイヤー)を取得する
  const sender = event.sender;
  // 送信者(プレイヤー)から位置情報を取得する
  const location = sender.location;
  // 位置情報から高さ(y座標)を取得する(この時点では少数)
  const y = location.y;

  try {
    // /sayコマンドで高さを表示する
    event.sender.runCommand(`say 現在の高さは ${y} です。`);
  } catch (error) {
    event.sender.runCommand(`say ${error}`);
  }
}
```

この取得処理は次のように1行で書けます。
今回の場合は1行にしたほうが見やすいので、こちらの方が良いでしょう。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

mc.world.events.beforeChat.subscribe((event) => {
  const y = event.sender.location.y;
  event.sender.runCommand(`say 現在の高さは ${y} です。`);
}
```

### 整数に直す

このときの高さ(`y`)の値は少数になっているので、表示しやすいように整数に直します。

整数に直すメソッドは`Math.floor()`メソッドを使います。
`Math`はJavaScriptが最初から読み込んでいるので、個別にインポートせずに使うことができます。

`floor()`は小数を切り捨てて整数に直すメソッドです。
ほかに切り上げや四捨五入をするメソッドもあります。

`Math`はその名前の通り、<R t="mathematics">数学</R>的な処理を行うクラスです。
この`Math`クラスは今後もたくさん使っていくことになるので、簡単な使い方をここで押さえておきましょう。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

mc.world.events.beforeChat.subscribe((event) => {
  const height = Math.floor(event.sender.location.y);
  try {
    event.sender.runCommand(`say 現在の高さは ${height} です。`);
  } catch (error) {
    event.sender.runCommand(`say ${error}`);
  }
}
```

## 特定のメッセージのときだけ実行する

このままでは、チャットをするたびに反応してしまうので、特定のメッセージを送信したときだけ動くように設定しましょう。

チャットイベントからメッセージ内容を取得できるので、その内容をif文を使って囲みます。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

mc.world.events.beforeChat.subscribe((event) => {
  // チャット欄から送信した内容が「height」のとき
  if (event.message === 'height') {
    const height = Math.floor(event.sender.location.y);
    try {
      event.sender.runCommand(`say 現在の高さは ${height} です。`);
    } catch (error) {
      event.sender.runCommand(`say ${error}`);
    }
  }
});
```

この場合は、高さ情報を表示したいだけなので、入力した`height`はチャット欄に表示する必要はありません。

引数から渡ってくる`event`の中の`cancel`の値を`true`にすると、メッセージの送信を停止できます。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

mc.world.events.beforeChat.subscribe((event) => {
  if (event.message === 'height') {
    const height = Math.floor(event.sender.location.y);
    try {
      event.sender.runCommand(`say 現在の高さは ${height} です。`);
    } catch (error) {
      event.sender.runCommand(`say ${error}`);
    }
    // 送信したメッセージは表示しない
    event.cancel = true;
  }
});
```

長く解説してきましたが、上が今回の最終的なコードです。

一気に完璧なコードを書くのではなく、何度も書き直して少しずつ良いコードへ修正しつづけていくのが正しいプログラミングの書き方だと思ってください。

## おまけ

ちなみに、今回の場合は内容の表示だけなので、メッセージ自体を書き換える方法でも代替可能です。
表示が最終目的ではないので、今回はこの方法を使いません。

```typescript
mc.world.events.beforeChat.subscribe((event) => {
  if (event.message === 'height') {
    const height = Math.floor(event.sender.location.y);
    event.message = `現在の高さは ${height} です。`
  }
});
```


01.高さの取得と表示

STEP01.プレイヤーのいる高さ(y座標)を取得して表示しよう


ミニゲーム作成チュートリアルの2回目です。

[前回](/script-takasa-geme-1/)は高さを取得して表示まで行いました。
毎回チャットコマンドを入力するのは面倒なので、この表示を自動化しましょう。


## Tickイベントを使って、表示コマンドをティックごとに自動で実行する

`TickEvent`はティックごとに自動で実行されるイベントです。
1ティック、つまり1秒間に20回、目的のプログラムを実行します。
この機能を使い、目的のコマンドを定期的に実行することで、表示を自動化します。

コマンドを使うには、<mark>どの<R t="dimension">次元</R>で使っているのか、あるいはどの<R t="player">プレイヤー</R>が使ってるのか</mark>をはっきりさせる必要があります。

例えば`/tp`を使うときに、オーバーワールドで使った場合と、ネザーで使った場合では移動する場所が違いますね。
移動先の座標の数字は同じでも、オーバーワールドとネザーでは別のワールドだからです。

また、誰が使うのかをはっきりさせれば、そのプレイヤーがどの次元にいるのかを判断できます。
そのため、コマンドを使うには「次元」か「プレイヤー」の情報が必要になります。

<Note color="green">
**次元**が分かれば、そこにいる**プレイヤー**もわかる。<br />
**プレイヤー**が分かれば、どの**次元**にいるかもわかる。
</Note>

今回使用する`TickEvent`で取得できる内容だけではコマンドを実行できないので、オーバーワールドの次元情報を事前に取得しておきます。
この情報から`runCommand()`を実行することにします。

前回書いたコードは削除して、次の内容で上書きしてください。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

// 最初にオーバーワールドの次元情報を取得しておく
// 今回の使い方では毎回取得する必要がないので、グローバル変数に入れる
const overworld = mc.world.getDimension('overworld');

mc.world.events.tick.subscribe((event) => {
  // 次元情報からコマンドを実行
  overworld.runCommand(`say ${event.currentTick}`)
});
```

## ワールドにいる全プレイヤーを取得する

次にプレイヤー情報を取得する処理を加えます。

開発時には自分ひとりしかいませんが、マルチプレイのことも考えて、プレイヤー全員に対して処理を行うようにしておきます。

プレイヤーの情報は、次元情報から取得できます。
上で取得したオーバーワールドの次元情報を今回も使用します。

まずはプレイヤー情報を取得できていることを確かめるために、名前だけを表示してみましょう。
すべての処理を一気に描くのではなく、ひとつずつ進めていきます。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

const overworld = mc.world.getDimension('overworld');

mc.world.events.tick.subscribe((event) => {
  // オーバーワールドにいるプレイヤーを取得する
  const players = overworld.getPlayers();
  // プレイヤーごとに繰り返し
  for (const player of players) {
    // そのプレイヤーの名前を表示
    overworld.runCommand(`say ${player.nameTag}`)
  }
});
```

プレイヤーの取得は変数に入れずに、直接for文の中に書くこともできます。
上では、途中の処理をわかりやすくするため、分けて書きましたが、この場合は直接for文の中に書いても良いでしょう。

```typescript
for (const player of overworld.getPlayers()) {
  // ...
}
```

## 高さをアクションバーに表示する

オーバーワールドにいるプレイヤー全員分の名前が表示されたら成功です。
しかし、本当に表示したいのは、それぞれのプレイヤーのいる「高さ」でした。
次はこれを表示するようにしましょう。

高さを取得する処理は前回と同じです。
今回は各プレイヤーが自分の情報だけを知れれば良いので、共通のチャット画面ではなく、そのプレイヤーのアクションバーに表示させます。
アクションバーに表示させるのは`/title`コマンドです。

<LinkCard slug="slash-command-title" />

また、今回の`runCommand()`メソッドはプレイヤーから使用します。
この場合、コマンド文の`@s`は、このメソッドを実行したプレイヤーのことになります。
次元情報から`runCommand()`を使用した場合、`@s`は無効になるので注意してください。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

const overworld = mc.world.getDimension('overworld');

mc.world.events.tick.subscribe((event) => {
  for (const player of overworld.getPlayers()) {
    const height = Math.floor(player.location.y);
    const text = `現在の高さは ${height} です。`;
    // titleコマンドでアクションバーに表示する
    player.runCommand(`title @s actionbar ${text}`);
  }
});
```


## 実行回数を制限する

上の方法では1秒間に20回、表示コマンドが実行されます。
今回の目的では、ここまで何度も書き換える必要はないので、回数を制限しましょう。

`event.currentTick`で現在の総ティック数を取得できるので、これを使用します。

また、`%`演算子を使うと、割った余りを求めることができます。
この場合の記号に元の百分率(パーセント)の意味はありません。

下の例の場合はティック数を`10`で割った余りが`0`のときにだけ実行できます。
つまり、ティック数が10の倍数のときだけ、条件式の判定が真になり、目的のコマンドを実行します。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

const overworld = mc.world.getDimension('overworld');

mc.world.events.tick.subscribe((event) => {
  // 10ティック(0.5秒)ごとに1回実行する
  if (event.currentTick % 10 === 0) {
    for (const player of overworld.getPlayers()) {
      const height = Math.floor(player.location.y);
      const text = `現在の高さは ${height} です。`;
      // titleコマンドでアクションバーに表示する
      player.runCommand(`title @s actionbar ${text}`);
    }
  }
});
```

この例では10ティックごとに目的のコマンドを実行しています。
つまり、それぞれのプレイヤーの高さ情報を0.5秒ごとに更新しています。

もし更新が遅いと感じたら、数字を調整してみましょう。
更新が多すぎると、ゲームが重くなってしまうので、処理内容に合わせてうまく制限してください。
(毎ティック実行した方が良い場合もあります)


## コードを整理する

最後にコードの整理を行います。

ここまでのコード自体は間違っていません。
しかし、このままひとつの関数に処理を加え続けると、コードが読みづらくなっていきます。
これを避けるために、処理のまとまりを関数に置き換えて分離します。

理想的な関数の書き方はありますが、まずは<mark>意味のまとまりで切り出す</mark>、というところから始めてください。

次の場合は、アクションバーに表示する処理を切り出しています。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

const overworld = mc.world.getDimension('overworld');

mc.world.events.tick.subscribe((event) => {
  if (event.currentTick % 10 === 0) {
    for (const player of overworld.getPlayers()) {
      // 関数を呼び出し
      showActionBar(player);
    }
  }
});

// 自分の高さ(y座標)をアクションバーに表示する
function showActionBar(player: mc.Player) {
  const height = Math.floor(player.location.y);
  const text = `現在の高さは ${height} です。`;
  player.runCommand(`title @s actionbar ${text}`);
}
```

このように関数に切り出すことで、コードが読みやすくなります。
この場合は「プレイヤーごとにアクションバーを表示させる」という意図がはっきりします。


02.表示を自動化する

STEP02.高さの表示を自動化しよう


前回は現在の高さを自動で取得するところまでを行いました。
今回はこれを変数に保存して、「最高到達点」と「最低到達点」を保存してみましょう。

今回の記事で作る内容はまだ1人用として使えません。
マルチプレイ用に個別に保存する場合は次回に行います。


## 高さを取得して得点を計算する

### 全体のコード

先に、変更後のコードを表示しておきます。
次のように、変数の追加と関数の修正を行なってください。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

const overworld = mc.world.getDimension('overworld');
// 到達した高さを記録する
let maxHeight = 0;
let minHeight = 0;

mc.world.events.tick.subscribe((event) => {
  if (event.currentTick % 10 === 0) {
    for (const player of overworld.getPlayers()) {
      showActionBar(player);
    }
  }
});

function showActionBar(player: mc.Player) {
  // 得点を計算する
  const score = maxHeight - minHeight;
  // 表示用の文字列を作る
  const text = `${score}pt (${minHeight} ~ ${maxHeight})`;
  player.runCommandAsync(`title @s actionbar ${text}`);
}
```


### 高さを入れる変数を作る

まずは記録を残すための変数を作成します。

* 最高到達点: `maxHeight`
* 最低到達点: `minHeight`

この変数の内容は変更されるので`let`で定義してください。

<Note color="blue">
変数の定義は基本的に`const`を使い、後で変更される**特殊な場合にだけ**`let`を使います。
</Note>

```typescript
// 最高到達点
let maxHeight = 0;
// 最低到達点
let minHeight = 0;
```


### 得点を計算する

得点(`score`)は到達点の差で決定します。
今回作成した変数を使って計算します。
同時に前回作成した、アクションバーの表示用変数を変更して、新しく得点を表示するようにします。

```typescript
// 得点を計算する
const score = maxHeight - minHeight;
// 表示用の文字列を作る
const text = `${score}pt (${minHeight} ~ ${maxHeight})`;
```

今の段階では、この変数を変更する処理は加えていないので、まだ初期値の`0`から変わりません。
`0pt (0 ~ 0)`と表示されていれば、ここまでの処理は正しく動いています。


## 今の高さから最高到達点と最低到達点を決定する

次にこの変数を、現在位置で変更する処理を加えます。

この変更処理は、ひとつのまとまりなので、新しい関数を作成します。
関数名は<R t="height">高さ</R>を<R t="set">設定</R>するので`setHeight()`としておきましょう。

そして、この関数は定期的に実行したいので、`TickEvent`の中から一定時間ごとに呼び出します。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

const overworld = mc.world.getDimension('overworld');
let maxHeight = 0;
let minHeight = 0;

mc.world.events.tick.subscribe((event) => {
  if (event.currentTick % 10 === 0) {
    for (const player of overworld.getPlayers()) {
      // 高さを設定する関数を呼び出す
      setHeight(player);
      showActionBar(player);
    }
  }
});

// 到達点を記録する処理を関数で作成する。
function setHeight(player: mc.Player) {
  // そのプレイヤーの現在位置を整数で取得する
  const currentHeight = Math.floor(player.location.y);
  // 現在位置が最高到達点よりも大きい場合
  if (currentHeight > maxHeight) {
    // 最高到達点を変更
    maxHeight = currentHeight
  }
  // 現在位置が最低到達点よりも小さい場合
  if (currentHeight < minHeight) {
    // 最低到達点を変更
    minHeight = currentHeight
  }
}

function showActionBar(player: mc.Player) {
  const score = maxHeight - minHeight;
  const text = `${score}pt (${minHeight} ~ ${maxHeight})`;
  player.runCommandAsync(`title @s actionbar ${text}`);
}
```

### 適切な値を代入する

最高・最低到達点を保存したいので、今の高さ(`currentHeight`)と保存されている位置(`maxHeight`, `minHeight`)を比較して、適切な方を変数に代入します。

例えば、次のような状況だとします。

<table>
  <tbody>
    <tr>
      <th>現在の高さ</th>
      <td>`currentHeight`</td>
      <td>`80`</td>
    </tr>
    <tr>
      <th>最高到達点</th>
      <td>`maxHeight`</td>
      <td>`70`</td>
    </tr>
    <tr>
      <th>最低到達点</th>
      <td>`minHeight`</td>
      <td>`60`</td>
    </tr>
  </tbody>
</table>

このとき、**最高**到達点は`80`に更新したいですが、**最低**到達点の方は`60`のまま残す必要があります。
最低到達点まで`80`にしてしまうのはもちろん間違いです。

この処理は数字の比較なので、if文を使って分岐させます。

```typescript
function setHeight(player: mc.Player) {
  const currentHeight = Math.floor(player.location.y);
  // 現在位置が最高到達点よりも大きい場合
  if (currentHeight > maxHeight) {
    // 最高到達点に代入
    maxHeight = currentHeight
  }
  // 現在位置が最低到達点よりも小さい場合
  if (currentHeight < minHeight) {
    // 最低到達点に代入
    minHeight = currentHeight
  }
}
```

これで正しい数字を取得して代入できます。


### 便利な計算メソッドを使う

上で追加したコードはこれで問題ありませんが、JavaScriptにはもっと便利なメソッドが`Math`クラスに用意されています。
せっかくなので、これを使ってみましょう。

今回の最高点を取得する処理は[`Math.max()`](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/max)を使います。
引数として値を渡すと、渡した値の中から<R t="maximum">最も大きい数字</R>の方を選んでくれます。
例えば、`Math.max(5, 7)`の場合は`7`になります。

同じように低いほうは[`Math.min()`](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Math/min)を使用します。
こちらは引数で渡した値の中から<R t="minimum">最も小さい数字</R>を選んでくれます。

```typescript
function setHeight(player: mc.Player) {
  const currentHeight = Math.floor(player.location.y);
  // 最高到達点は、現在の値と過去の値を比べて高い方を採用する -> Math.max()
  maxHeight = Math.max(currentHeight, maxHeight);
  // 最低到達点は、現在の値と過去の値を比べて低い方を採用する -> Math.min()
  minHeight = Math.min(currentHeight, minHeight);
}
```

処理としては、最初に作ったif文の方でも問題ないので、どちらを使っても構いません。
ただ、この`Math`クラスを使った処理の方が、短く、わかりやすくなっているので、こちらの書き方をする方がおすすめです。


### この時点での問題点

ただ、この方法ではまだ不十分で、最初に設定した初期値が`0`のため、問題が起こります。

テストをしているy座標位置が……。

* 0より高い場合 -> 最低点がいきなり`0`
* 0より低い場合 -> 最高点がいきなり`0`

こうなってしまうので、最初の高さが`y=64`の場合、最高点が`64`、最低点が`0`となります。
`64 - 0`で、いきなり64点になります。
これは点数として間違いですね。

初期値として正しいのは、`0`ではなく、最高点と最低点がともに「ゲーム開始時のプレイヤーの位置」です。
`y=64`にいる場合は、最高点と最低点がともに`64`になるので、`64 - 64`なので0点となり、正しい点数になります。
次で、この初期値を設定する処理を追加しましょう。


## 高さの初期値を今の位置に設定する

自分の高さの位置を取得する方法は、`Math.floor(player.location.y)`ですね。
単純にこの方法を使って、今回作った変数に自分の位置を入れるだけです。

コードの上の方で、`let`で定義したときに、一緒に自分の位置を取得してしまいたいところです。
しかし、この部分のコードが実行されるときは、まだプレイヤーがワールドに入る前なので、うまくいきません。
それに、ゲーム開始時の位置であることが重要なので、きちんとゲームを開始した時に初期値を取得することにしましょう。

最終的には自動化しますが、まずはチャットコマンドから手動で初期化することにします。
次の例は`reset`とチャットで入力した際に実行します。

```typescript:scripts/main.ts
// 上書きではなく次のコードを追加

// チャットからリセットする処理を追加
mc.world.events.beforeChat.subscribe((event) => {
  if (event.message === 'reset') {
    resetHeight(event.sender);
  }
});

// 高さ変数を初期化する
function resetHeight(player: mc.Player) {
  // 現在の高さを取得する
  const currentHeight = Math.floor(player.location.y);
  // それぞれの高さをプレイヤーの位置に設定する
  maxHeight = currentHeight;
  minHeight = currentHeight;
}
```

チャット欄に`reset`と入力して、アクションバーに表示される数字が今の高さに変わったら成功です。


## コードを整理する

最後にコードを整理しましょう。

今回は高さを取得する同じ処理(`Math.floor(player.location.y)`)が2箇所にあるので、これらを共通化します。
共通化するには、専用の関数を作成して、その関数を2箇所から呼び出します。

最終的には次のコードになります。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

const overworld = mc.world.getDimension('overworld');
let maxHeight = 0;
let minHeight = 0;

mc.world.events.tick.subscribe((event) => {
  if (event.currentTick % 10 === 0) {
    for (const player of overworld.getPlayers()) {
      setHeight(player);
      showActionBar(player);
    }
  }
});

mc.world.events.beforeChat.subscribe((event) => {
  if (event.message === 'reset') {
    resetHeight(event.sender);
  }
});

// 現在の高さを取得する
function getCurrentHeight(player: mc.Player) {
  // 1行だけでも、処理が共通なら必ず1つの関数にまとめる
  return Math.floor(player.location.y);
}

function resetHeight(player: mc.Player) {
  // 高さの取得を共通化する
  const currentHeight = getCurrentHeight(player);
  maxHeight = currentHeight;
  minHeight = currentHeight;
}

function setHeight(player: mc.Player) {
  // 高さの取得を共通化する
  const currentHeight = getCurrentHeight(player);
  maxHeight = Math.max(currentHeight, maxHeight);
  minHeight = Math.min(currentHeight, minHeight);
}

function showActionBar(player: mc.Player) {
  const score = maxHeight - minHeight;
  const text = `${score}pt (${minHeight} ~ ${maxHeight})`;
  player.runCommandAsync(`title @s actionbar ${text}`);
}
```


03.変数に保存する

STEP03. 高さを変数に保存しよう


前回は高さを変数に保存しました。
しかし、高さを情報を共通のグローバル変数に保存しているため、マルチプレイ用にはなっていませんでした。

今回は、この高さ情報をグローバル変数ではなく、それぞれのプレイヤー自身に持たせる設定を行います。
これにより、マルチプレイ用にプレイヤー別の得点を計算できるようになります。


## ダイナミックプロパティとは

ダイナミックプロパティとは、ワールドまたはエンティティ自身に対して変数を持たせる機能だと思ってください。

少し難しく感じるとは思いますが、よく使う機能になるので慣れていってください。

今回は全体の変更後のコードを示したうえで、後で個別に解説します。

```typescript:scripts/main.ts
import * as mc from 'mojang-minecraft';

const overworld = mc.world.getDimension('overworld');

// ワールド作成時に実行されるイベント
mc.world.events.worldInitialize.subscribe((event) => {
  // ダイナミックプロパティの定義を作成
  const playerDef = new mc.DynamicPropertiesDefinition();
  // 数字型のダイナミックプロパティを作成する
  playerDef.defineNumber('tks:maxHeight');
  playerDef.defineNumber('tks:minHeight');
  // 定義を登録する
  event.propertyRegistry.registerEntityTypeDynamicProperties(
    playerDef,
    mc.MinecraftEntityTypes.player
  );
});

mc.world.events.tick.subscribe((event) => {
  if (event.currentTick % 10 === 0) {
    for (const player of overworld.getPlayers()) {
      setHeightProperty(player);
      showActionBar(player);
    }
  }
});

mc.world.events.beforeChat.subscribe((event) => {
  if (event.message === 'reset') {
    // プレイヤーごとに処理するように変更
    for (const player of overworld.getPlayers()) {
      resetHeightProperty(player);
    }
  }
});

function getHeight(player: mc.Player) {
  return Math.floor(player.location.y);
}

function resetHeightProperty(player: mc.Player) {
  const current = getHeight(player);
  // 変数ではなくダイナミックプロパティに設定する
  player.setDynamicProperty('tks:maxHeight', current);
  player.setDynamicProperty('tks:minHeight', current);
}

function setHeightProperty(player: mc.Player) {
  const current = getHeight(player);
  const height = getHeightProperty(player);
  // 変数ではなくダイナミックプロパティに設定する
  player.setDynamicProperty('tks:maxHeight', Math.max(current, height.max));
  player.setDynamicProperty('tks:minHeight', Math.min(current, height.min));
}

// ダイナミックプロパティから取得する処理を追加する
function getHeightProperty(player: mc.Player) {
  // ダイナミックプロパティから、それぞれの到達点を(数字として)取得する
  const max = player.getDynamicProperty('tks:maxHeight') as number;
  const min = player.getDynamicProperty('tks:minHeight') as number;
  // 戻り値が2つあるので、オブジェクトにしてまとめて返す(配列でもいい)
  return { max, min };
}

function showActionBar(player: mc.Player) {
  // 高さの取得関数
  const height = getHeightProperty(player);
  // 取得した値を使うように置き換える
  const score = height.max - height.min
  const text = `${score}pt (${height.min} ~ ${height.max})`;
  player.runCommandAsync(`title @s actionbar ${text}`);
}
```

## ダイナミックプロパティで独自の変数を追加する

ダイナミックプロパティはアドオン適用時(ワールドを開いたとき)にしか追加できません。
ゲームの途中で勝手に追加できないので、アドオンを読み込んだ時にすべて決定しておく必要があります。

このダイナミックプロパティは`WorldInitializeEvent`の中で定義します。

次の例は、プレイヤーに数字型のダイナミックプロパティを設定します。

```typescript
mc.world.events.worldInitialize.subscribe((event) => {
  // ダイナミックプロパティの定義を作成
  const playerDef = new mc.DynamicPropertiesDefinition();
  // 数字型のダイナミックプロパティを作成する
  playerDef.defineNumber('tks:maxHeight');
  playerDef.defineNumber('tks:minHeight');
  // 定義を登録する
  event.propertyRegistry.registerEntityTypeDynamicProperties(
    playerDef,
    mc.MinecraftEntityTypes.player
  );
});
```

### 定義を作成する

```typescript
const playerDef = new mc.DynamicPropertiesDefinition();
```

この部分では、`DynamicPropertiesDefinition`クラスを`new`でインスタンス化しています。

ここは難しい箇所なので、初心者の方は完全に理解する必要はありません。
ひとまず、ダイナミックプロパティの設定テンプレートを取得しているという理解で十分です。


### プロパティを作成する

```typescript
playerDef.defineNumber('tks:maxHeight');
playerDef.defineNumber('tks:minHeight');
```

`defineNumber()`は数字型のダイナミックプロパティを作成するメソッドです。
JavaScriptでいうところのnumber型のみ入れることができます。
他には文字列型と真偽値型がありますが、今回は数字型だけ使います。

引数には追加するプロパティのID名を入力します。
これは追加する変数名のことだと考えてください。
ここでは`tks:maxHeight`としています。


### 定義を登録する

```typescript
event.propertyRegistry.registerEntityTypeDynamicProperties(
  playerDef,  // この定義を
  mc.MinecraftEntityTypes.player  // このエンティティに
);
```

上で作成したのは、ただの設定内容なので、またワールドに対して登録されていません。

`registerEntityTypeDynamicProperties()`から登録します。

* 第1引数: どの定義を登録するのか
* 第2引数: どのエンティティに対して登録するのか

今回の場合はプレイヤー全体に対して、2つの数字型のダイナミックプロパティを追加します。
この場合、ゾンビやニワトリなど、別のエンティティには追加されません。
また、単体のエンティティにだけ追加することもできません。


## ダイナミックプロパティを設定する

高さの初期化関数をダイナミックプロパティを使うように変更します。

今回のダイナミックプロパティはプレイヤー向けに作成したので、設定したいプレイヤーから`setDynamicProperty()`メソッドを使って、値を設定します。

```typescript
function resetHeightProperty(player: mc.Player) {
  const current = getHeight(player);
  // 変数ではなくダイナミックプロパティに設定する
  player.setDynamicProperty('tks:maxHeight', current);
  player.setDynamicProperty('tks:minHeight', current);
}
```

* 第1引数: 設定するID名
* 第2引数: 設定する内容


## ダイナミックプロパティを取得する

取得間数の方も、グローバル変数ではなく、ダイナミックプロパティから取得するように変更します。

ダイナミックプロパティの取得は、設定と同じように、プレイヤーから`getDynamicProperty()`メソッド使って取得します。

```typescript
function getHeightProperty(player: mc.Player) {
  // ダイナミックプロパティから、それぞれの到達点を(数字として)取得する
  const max = player.getDynamicProperty('tks:maxHeight') as number;
  const min = player.getDynamicProperty('tks:minHeight') as number;
  // 戻り値が2つあるので、オブジェクトにしてまとめて返す(配列でもいい)
  return { max, min };
}
```

末尾についている`as number`は、このプロパティが数字型であることを明示しています。
ダイナミックプロパティは、数字以外も入れることができるので、このメソッドの引数は型が何になるのか確定しません。
そのため、何も設定しないとTypeScriptが型の種類を判別できないので、このように型を明示し、TypeScriptに型情報を教えてあげます。


## 既存の関数を修正

高さの取得方法がグローバル変数から、個別のダイナミックプロパティに変わったので、アクションバーに表示する処理も修正しましょう。

```typescript
function showActionBar(player: mc.Player) {
  const height = getHeightProperty(player);
  const score = height.max - height.min;
  const text = `${score}pt (${height.min} ~ ${height.max})`;
  player.runCommand(`title @s actionbar ${text}`);
}
```

初期化関数も修正します。
今回は関数名も変更しているので注意してください。

```typescript
function resetHeightProperty(player: mc.Player) {
  // そのプレイヤーの現在の高さを取得し、整数に直す
  const current = getHeight(player);
  // それぞれのプロパティを設定する
  player.setDynamicProperty('tks:maxHeight', current);
  player.setDynamicProperty('tks:minHeight', current);
}
```

ここまでの変更で前回と同じように動いたら、ダイナミックプロパティがうまく動いています。
開発段階では1人しかいないので、見た目上の変化はありません。
2人以上で遊んだ場合には、うまく動いてくれると思います。


04.マルチプレイ化

STEP04.ダイナミックプロパティに高さを保存しよう


次はゲームの開始と終了を操作できるようにしましょう。

全体のコード量が長くなってきたので、以降は記事の中ですべてのコードを表示しません。
今回の記事で作成する最終的なコードは次のリンクから確認してください。

<ExButton href="https://github.com/akihamitsuki/fight-on-height/blob/main/scripts/step05/main.ts">GitHubで今回のコードを確認</ExButton>


## ゲーム中であるかどうかを切り替える

まずはゲーム中の場合のみ、アクションバーに高さを表示するように変更してみましょう。

「ゲーム中であるかどうか」は、「はい」か「いいえ」の2択なので、真偽値を使えばよさそうです。

ゲーム中フラグを入れる変数として`isPlaying`を作成しましょう。
これは変数の値が変わるので`let`で定義してください。

この変数をif文で判定して処理を分岐させれば、ゲーム中かどうかで処理を分岐できます。

```typescript:scripts/main.ts(部分)
// ゲーム中フラグ
let isPlaying = false;

mc.world.events.tick.subscribe((event) => {
  // ゲーム中フラグ判定のif文で囲む
  if (isPlaying) {
    if (event.currentTick % 10 === 0) {
      for (const player of overworld.getPlayers()) {
        setHeightProperty(player);
        showActionBar(player);
      }
    }
  }
});
```

初期値を`false`にしておけば、ワールドに入った直後にゲーム処理が始まることはありません。


## チャットイベントを設定する

次はこのフラグを操作して、切り替えられるようにしましょう。
いつものように、まずはチャットイベントで操作するところから始めます。

フラグの切り替えは、操作に合わせて適切な真偽値を入れるだけです。
値が変わったことがわかりやすいように、`/title`を使って画面に文章を表示しておきます。

```typescript:scripts/main.ts(部分)
mc.world.events.beforeChat.subscribe((event) => {
  if (event.message === 'start') {
    // フラグを真に切り替える
    isPlaying = true;
    // titleを表示
    overworld.runCommand(`title @a title Game Start!`);
    event.cancel = true;
  }
  if (event.message === 'end') {
    // フラグを偽に切り替える
    isPlaying = false;
    // titleを表示
    overworld.runCommand(`title @a title Game Over!`);
    event.cancel = true;
  }

  // あとで使うのでコメントアウト
  // if (event.message === 'reset') {
  //   for (const player of overworld.getPlayers()) {
  //     resetHeightProperty(player);
  //   }
  // }
});
```

もともとあった`reset`は一旦コメントアウトしておきます。
(この中の処理は次ですぐに使います)


## プレイヤーの状態を初期化する

`reset`で行なっていた、高さの初期値の設定は、ゲーム開始時に行うべきものなので、`start`の中に移動します。

```typescript:scripts/main.ts(部分)
mc.world.events.beforeChat.subscribe((event) => {
  if (event.message === 'start') {
    isPlaying = true;
    overworld.runCommand(`title @a title Game Start!`);

    // ここに処理を移動
    for (const player of overworld.getPlayers()) {
      resetHeightProperty(player);
    }

    event.cancel = true;
  }
  if (event.message === 'end') {
    isPlaying = false;
    overworld.runCommand(`title @a title Game Over!`);
    event.cancel = true;
  }
});
```


## 初期化処理を共通化する

高さの初期値以外にも、プレイヤーの<R t="initialize">初期化</R>として様々な処理を行いたいので、専用の関数を作成します。

作成した`resetHeightProperty()`はこちらに移動し、それ以外の処理をスラッシュコマンドで追加します。

```typescript:scripts/main.ts(部分)
// 初期化処理を関数にまとめる
function initializePlayer(player: mc.Player) {
  // 移動してきた関数
  resetHeightProperty(player);

  // 追加のスラッシュコマンド
  player.runCommand('gamemode survival');
  try {
    player.runCommand('clear');
  } catch (error) {
    // アイテムを持っていない場合はエラーになる
    // エラーを表示しない
  }
  player.runCommand('effect @s instant_health 1 255 true');
  player.runCommand('effect @s saturation 1 255 true');
}
```

ここで追加したスラッシュコマンド部分は、今回のゲーム作成に直接関係ないので、必要そうなものを任意で追加してください。

よくわからなければ、次のようにスラッシュコマンド部分は省略しても構いません。
あとで必要なものだけ追加していってください。

```typescript:scripts/main.ts(部分)
function initializePlayer(player: mc.Player) {
  resetHeightProperty(player);
}
```

初期化関数は、開始時だけでなく、終了時にも実行しておきます。

```typescript:scripts/main.ts(部分)
mc.world.events.beforeChat.subscribe((event) => {
  if (event.message === 'start') {
    isPlaying = true;
    overworld.runCommand(`title @a title Game Start!`);

    for (const player of overworld.getPlayers()) {
      // 初期化関数に変更
      initializePlayer(player);
    }

    event.cancel = true;
  }
  if (event.message === 'end') {
    isPlaying = false;
    overworld.runCommand(`title @a title Game Over!`);

    // こちらにも追加
    for (const player of overworld.getPlayers()) {
      initializePlayer(player);
    }

    event.cancel = true;
  }
});
```

## さらに関数に分離する

ここまでのコードでも問題はありませんが、もう一歩踏み込んでコードを整理しておきましょう。

関数の使い方には、共通部分をまとめる他に、<mark>意味のまとまりで切り出す</mark>方法もあります。
共通要素として複数箇所にあるものだけでなく、1箇所にしかない場合でも、適切なまとまりで関数にしておくとコードが見やすくなります。

ここでは開始処理と終了処理を関数に切り出してみましょう。

```typescript:scripts/main.ts(部分)
mc.world.events.beforeChat.subscribe((event) => {
  if (event.message === 'start') {
    // ここでは、どの関数を呼び出すのかだけを決めたい
    startGame();
    event.cancel = true;
  }
  if (event.message === 'end') {
    exitGame();
    event.cancel = true;
  }
});

// 開始処理を関数で切り出す
function startGame() {
  isPlaying = true;
  overworld.runCommand(`title @a title Game Start!`);
  for (const player of overworld.getPlayers()) {
    initializePlayer(player);
  }
}

// 終了処理を関数で切り出す
function exitGame() {
  isPlaying = false;
  overworld.runCommand(`title @a title Game Over!`);
  for (const player of overworld.getPlayers()) {
    initializePlayer(player);
  }
}
```

このように関数に分けることで、全体的な見通しが良くなります。
特にチャットイベントの中で何をしているのかが明確になったのではないかと思います。


05.開始と終了

STEP05.ゲームの開始と終了を操作する


前回はゲームの開始と終了の処理を作りました。
今回は終了処理を行うときに、ゲームの結果を表示するようにしましょう。

今回の記事で作成する最終的なコードは次のリンクから確認してください。

<ExButton href="https://github.com/akihamitsuki/fight-on-height/blob/main/scripts/step06/main.ts">GitHubで今回のコードを確認</ExButton>


## 結果表示用の関数を作る

最初に結果表示用の関数の枠組みだけを作成しておきます。

呼び出す場所は、修了処理の中からです。
プレイヤーの状態を初期化すると結果を計算できないので、タイトル表示と初期化の間に追加します。

```typescript:scripts/main.ts(部分)
function exitGame() {
  isPlaying = false;
  overworld.runCommand(`title @a title Game Over!`);
  // 結果を表示する(記述する場所に注意)
  showResult();
  for (const player of overworld.getPlayers()) {
    initializePlayer(player);
  }
}

function showResult() {
  // ここに結果表示の処理を書いていく
}
```


## 全員の得点を表示する

最終結果の表示方法は色々と工夫できそうですが、まずは簡単に全プレイヤーの結果だけを表示してみましょう。
各プレイヤーのアクションバーに表示していた内容を、名前を加えて`/say`コマンドでチャット画面に表示します。

```typescript:scripts/main.ts(部分)
function showResult() {
  overworld.runCommand(`say --- 結果表示 ---`);
  // プレイヤーごとに繰り返し
  for (const player of overworld.getPlayers()) {
    const height = getHeightProperty(player);
    const score = height.max - height.min;
    const text = `${score}pt (${height.min} ~ ${height.max})`;
    // /sayでチャット画面に表示
    overworld.runCommand(`say ${player.nameTag}: ${text}`);
  }
  overworld.runCommand(`say --------------`);
}
```


## 順位をつけて表示したい

得点を表示をするだけなら、上の処理だけでも構いません。
しかしゲームである以上、勝者や順位を適切に表示してあげるべきでしょう。

ここからの処理は少し難しくなります。
わからなくなったら、最終結果をコピペして次に進んでください。


## 最初に全員の得点を計算する

今回は単純に得点順にプレイヤーを並べ替えて、その並び順を、そのまま順位とします。

順位は厳密に判定しようとすると、同じ点数などを考えないといけません。
この処理はずっと複雑な処理になってしまうので、今回は簡単な処理で済ませます。

先に全体の処理を載せておきます。

```typescript:scripts/main.ts(部分)
function getScore(max: number, min: number) {
  return max - min;
}

function getScoreText(max: number, min: number) {
  const score = getScore(max, min);
  return `${score}pt (${min} ~ ${max})`;
}

function getResult(playerIterator: mc.PlayerIterator) {
  // イテレーターをスプレッド構文を使って配列化する(次のように.map()と.sort()を使いたい)
  const players = [...playerIterator];
  // 結果をJSON構造で返す
  const result = players.map((player) => {
    const name = player.nameTag;
    const height = getHeightProperty(player);
    const score = getScore(height.max, height.min);
    const text = getScoreText(height.max, height.min);
    return { name, score, text };
  });

  // テスト用に結果情報を追加
  result.push({
    name: 'Steve',
    score: getScore(60, 57),
    text: getScoreText(60, 57),
  });
  result.push({
    name: 'Alex',
    score: getScore(80, 62),
    text: getScoreText(80, 62),
  });

  return result
    .sort((a, b) => {
      // スコアで並び替えて順位を決める
      return b.score - a.score;
    })
    .map((obj, index) => {
      // スコアが高い順に並び変えているので、indexを+1した値がそのまま順位になる(indexは0から)
      const ranking = index + 1;
      return { ranking, ...obj };
    });
}

function showResult() {
  const players = overworld.getPlayers();
  const result = getResult(players);
  try {
    overworld.runCommand(`say --- 結果表示 ---`);
    result.forEach((obj) => {
      overworld.runCommand(`say ${obj.ranking}. ${obj.name} ${obj.text}`);
    });
    overworld.runCommand(`say --------------`);
  } catch (error) {
    overworld.runCommand(`say ${error}`);
  }
}
```

最終的に、`showResult()`は次のように、大きく3つに分かれます。

1. 計算対象のプレイヤーを決定する
2. そのプレイヤーの結果を取得する
3. 取得した結果を順番に表示する

```typescript:scripts/main.ts(部分)
function showResult() {
  // 1. 計算対象のプレイヤーを決定する
  const players = overworld.getPlayers();
  // 2. そのプレイヤーの結果を取得する
  const result = getResult(players);
  // 3. 取得した結果を順番に表示する
  try {
    overworld.runCommand(`say --- 結果表示 ---`);
    result.forEach((obj) => {
      overworld.runCommand(`say ${obj.ranking}. ${obj.name} ${obj.text}`);
    });
    overworld.runCommand(`say --------------`);
  } catch (error) {
    overworld.runCommand(`say ${error}`);
  }
}
```

## 計算対象のプレイヤーを決定する

今回の計算対象はプレイヤー全員です。

今後開発が進むと、ゲームに参加している人だけに絞り込んだりする必要があります。
そのため、計算対象は次の結果計算関数から分離しておきます。

```typescript
const players = overworld.getPlayers();
```

## そのプレイヤーの結果を取得する

結果計算は`getResult()`として専用の関数にまとめます。

```typescript:scripts/main.ts(部分)
function getResult(playerIterator: mc.PlayerIterator) {
  // イテレーターをスプレッド構文を使って配列化する(次のように.map()と.sort()を使いたい)
  const players = [...playerIterator];
  // 結果をJSON構造で返す
  const result = players.map((player) => {
    const name = player.nameTag;
    const height = getHeightProperty(player);
    const score = getScore(height.max, height.min);
    const text = getScoreText(height.max, height.min);
    return { name, score, text };
  });

  return result
    .sort((a, b) => {
      // スコアで並び替えて順位を決める
      return b.score - a.score;
    })
    .map((obj, index) => {
      // スコアが高い順に並び変えているので、indexを+1した値がそのまま順位になる(indexは0から)
      const ranking = index + 1;
      return { ranking, ...obj };
    });
}
```

`overworld.getPlayers()`で取得されるデータは[イテレーター](https://developer.mozilla.org/ja/docs/Web/JavaScript/Guide/Iterators_and_Generators)という少し特殊な形式になっているので注意してください。

イテレーターは次のように[スプレッド構文](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Operators/Spread_syntax)を使って、簡単に配列に変換できるので、今の段階では正確に理解する必要はありません。

```typescript
const players = [...playerIterator];
```

配列に変換したら[`map()`](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Map)を使って、順番に処理します。

`map()`は配列の内容ごとに繰り返し、それぞれの戻り値で新しい配列を作ります。
新しい配列には、後の結果表示処理するときの内容を格納しておきます。

```typescript
const result = players.map((player) => {
  const name = player.nameTag;
  const height = getHeightProperty(player);
  const score = getScore(height.max, height.min);
  const text = getScoreText(height.max, height.min);
  return { name, score, text };
});
```

処理内容は、次のコードとまったく同じですが、この場合は`map()`を使った方が少し綺麗に書けます。

```typescript
// map()をfor文で書き直した場合
const result = [];
for (const player of players) {
  const name = player.nameTag;
  const height = getHeightProperty(player);
  const score = getScore(height.max, height.min);
  const text = getScoreText(height.max, height.min);
  result.push({ name, score, text });
};
```

`map()`は頻繁に出現する処理方法なので、少しずつ慣れていってください。

細かい違いを言うと`map()`は「式」で、for文は「文」という違いがあります。
そのため、すべての場合で、相互に置き換えられるわけではありません。

また、最後の戻り値のオブジェクトは省略表記になっています。

```typescript
// 本来のオブジェクトの記入の仕方
{
  name: name,
  score: score,
  text: text,
}

// キーと変数が同じ場合には、記述を省略できる
{
  name,
  score,
  text,
}

// 1行に直した場合
{ name, score, text }
```

## テスト用のデータを追加する

開発環境では基本的に自分1人だけなので、順位として並べ替える対象が存在しません。
これではテストができないので、結果配列にデータを[push()](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/push)で追加しておきます。

```typescript
// テスト用に結果情報を追加
result.push({
  name: 'Steve',
  score: getScore(60, 57),
  text: getScoreText(60, 57),
});
result.push({
  name: 'Alex',
  score: getScore(80, 62),
  text: getScoreText(80, 62),
});
```

## データを並べ替える

配列の並べ替えは、次に[`sort()`](https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/sort)を使います。

今回の配列内容はオブジェクトなので、どのように並べ替えるのかを明示するアロー関数を書きます。
この部分は少し難しいので、とりあえず次のように書いておいてください。
これで得点が高い方から順に並びます。(降順)

```typescript
result.sort((a, b) => {
  // スコアで並び替えて順位を決める
  return b.score - a.score;
})
```

続けて、再び`map()`を使い、並び替えた後の配列内オブジェクトに順位を追加します。

```typescript
result.map((obj, index) => {
  // スコアが高い順に並び変えているので、indexを+1した値がそのまま順位になる(indexは0から)
  const ranking = index + 1;
  return { ranking, ...obj };
});
```

上の二つのメソッドを連続で実行し、`return`で返すまでの処理を一気に書くと、次のようになります。

```typescript
return result
  .sort((a, b) => {
    return b.score - a.score;
  })
  .map((obj, index) => {
    const ranking = index + 1;
    return { ranking, ...obj };
  });
```

ここは改行で少し伝わりづらいですが、`result.sort().map()`という形で、メソッドが繋がっています。
このようにメソッドを繋げる方法を<R t="method chaining">メソッドチェーン</R>と呼びます。
このメソッドチェーンを使う場合は`map()`部分をfor文におきかえられません。


## 結果を表示する

`showResult()`に戻って、結果を表示する処理を行います。

表示する内容は、結果計算関数内で終えているので、ここでは単純な繰り返しから、その内容を呼び出すだけです。
予期しない値でエラーになった場合に備えて、`try...catch`文で囲んでおきます。

```typescript
try {
  overworld.runCommand(`say --- 結果表示 ---`);
  result.forEach((obj) => {
    overworld.runCommand(`say ${obj.ranking}. ${obj.name} ${obj.text}`);
  });
  overworld.runCommand(`say --------------`);
} catch (error) {
  overworld.runCommand(`say ${error}`);
}
```

ここの処理はとても簡潔になっていますが、これを最初から書くことは難しいです。
実際は、どのように前処理を行なっておけば、ここでのコードが綺麗になるかを考えて、何度も修正を繰り返しています。


06.結果表示

STEP06.ゲーム結果を表示する


今回はゲームに制限時間を追加して、自動でゲームが終了するようにしましょう。
これで、このチュートリアルはいったんの完成とします。

今回の記事で作成する最終的なコードは次のリンクから確認してください。

<ExButton href="https://github.com/akihamitsuki/fight-on-height/blob/main/scripts/step07/main.ts">GitHubで今回のコードを確認</ExButton>


## 変数を追加する

まず定数として初期値と、ゲーム中の時間の変数を用意します。

```typescript:scripts/main.ts(部分)
// ゲーム時間の初期値(テスト用なので短い)
const defaultTimerSecond = 20;
// ゲーム中の残り時間(秒)
let timerSecond = 0;
```

変数名には単位をつけておきましょう。
特にマインクラフトの場合は<R t="second">秒</R>と<R t="tick">ティック</R>が混在しがちです。
その数字の単位は何なのかを明示するようにしてください。

今回は秒で管理しますが、ティックで管理しても構いません。

## ゲーム開始時に残り時間を初期化する

残り時間はゲームを始めるたびに元に戻さないといけないので、ゲーム開始関数の中に初期化処理を追加しましょう。

```typescript:scripts/main.ts(部分)
function startGame() {
  isPlaying = true;
  // 残り時間を設定する
  timerSecond = defaultTimerSecond;
  for (const player of overworld.getPlayers()) {
    initializePlayer(player);
  }
  overworld.runCommand(`title @a title Game Start!`);
}
```

この場合は、初期値用の変数`defaultTimerSecond`の値を、ゲーム中に変動する変数`timerSecond`に入れています。


## ゲーム中に残り時間を減らす

残り時間は`TickEvent`内で管理します。

今回のように秒で管理する場合は、20ティックごとに1減らせば良いわけですね。
この処理はゲーム中だけのものなので`if (isPlaying) {}`の中に入れます。

```typescript:scripts/main.ts(部分)
mc.world.events.tick.subscribe((event) => {
  if (isPlaying) {
    if (event.currentTick % 10 === 0) {
      for (const player of overworld.getPlayers()) {
        setHeightProperty(player);
        showActionBar(player);
      }
    }
    // 20ティックごとに残り時間(秒)から1減らす
    if (event.currentTick % 20 === 0) {
      timerSecond--;
    }
  }
});
```

## 残り時間がなくなったらゲーム終了

残り時間が0以下(`<= 0`)になったらゲーム終了関数を実行するようにします。

```typescript:scripts/main.ts(部分)
mc.world.events.tick.subscribe((event) => {
  if (isPlaying) {
    if (event.currentTick % 10 === 0) {
      for (const player of overworld.getPlayers()) {
        setHeightProperty(player);
        showActionBar(player);
      }
    }
    // 残り時間が0秒以下になったらゲーム終了
    if (timerSecond <= 0) {
      exitGame();
    }
    if (event.currentTick % 20 === 0) {
      timerSecond--;
    }
  }
});
```

終了処理を関数に切り出しておいたので、ここでの処理が簡単になりました。

チャットコマンドも残っているので、手動で終わらせることもできます。


## 残り時間を表示する

残り秒数(`timerSecond`)は、得点と一緒にアクションバーに表示するようにしておきましょう。

```typescript:scripts/main.ts(部分)
function showActionBar(player: mc.Player) {
  const height = getHeightProperty(player);
  // /titleコマンドで高さを表示する
  const text = `残り ${timerSecond}秒 / ${getScoreText(height.max, height.min)}`;
  try {
    player.runCommand(`title @s actionbar ${text}`);
  } catch (error) {
    player.runCommand(`say ${error}`);
  }
}
```

ゲーム部分はひとまずこれで完成です。
次回はコードの整理だけを行います。


07.制限時間を追加

STEP07.タイマーで終了処理を自動化しよう


今回のチュートリアルでのゲーム制作部分は、前回までで終わりです。
コード量が増えてきたので、今後の開発に備えて、ファイルを分割して管理する方法を覚えておきましょう。

<ExButton href="https://github.com/akihamitsuki/fight-on-height/tree/main/scripts/step08">GitHubで今回のコードを確認</ExButton>


## ファイル分割例

今回は次の3つのファイルに分けています。
これはただの一例なので、これが最適解というわけではありません。
最適な分割の仕方は、今後の開発方針によって変わります。

* `main.ts`: 最初に読み込まれるファイル
* `game.ts`: ゲーム全体の処理に関するファイル
* `player.ts`: プレイヤーに関するファイル


## import と export

別ファイルから要素を読み込むには`import`を使います。
このimportの仕方はいくつかの書き方がありますが、ここでは1種類だけ解説します。

`import`文とは、一番最初に記述した、次の行のことです。

```typescript
import * as mc from 'mojang-minecraft';
```

これはマインクラフトが最初から用意しているファイルから、すべての要素(`*`)を`mc`という名前で読み込んでいます。
同じように、自分で分割したファイルからも読み込めます。

`game.ts`ファイルと同じ階層の`player.ts`ファイルから`initializePlayer()`を呼び出したい場合は、次のように記述します。

```typescript:scripts/game.ts
import { initializePlayer } from './player';
```

`./player`の`./`部分は、同じ階層であることを意味します。
これを付けずに`player`とすると、別の箇所のファイルから探そうとします。

ただし、単純に要素名を書いただけでは呼び出すことはできません。
呼び出せるようにするには、その要素の先頭に`export`と記述する(宣言する)必要があります。

```typescript:scripts/player.ts
export function initializePlayer(player: mc.Player) {
  // ...
}
```

### exportは必要な要素にだけ宣言する

`export`は関数だけでなく、変数やクラスにも付けられるので、関数以外も呼び出せます。

すべての要素に`export`宣言をしてもエラーにはなりませんが、他から呼び出す必要があるものにだけ、`export`を付けるようにしましょう。

`export`が宣言されていない場合は、逆に他から呼び出されていないことを意味します。
このとき、宣言されていない要素はそのファイル内だけで使用されているので、変更する際に注意する範囲が限定されるので、修正しやすくなります。


## 次の開発へ

これでさらにゲーム開発を進める準備が整いました。

このチュートリアルはここで終了となりますが、自分で追加できそうな機能があれば、自由に追加していってください。


08.ファイル分割

STEP08.ファイルを分割してコードを整理する


ここではプレイヤーやモブが何かをしたときに関わらず、一定時間ごとに何かをしたいときの処理を学びます。

このような処理は、
「5分たったらがたったらゲームを終了させる。」
「30秒ごとにアイテムを出現させる。」
など、さまざまなことに使えます。

今回は単純に1秒ごとに数字を減らしていき、0になったら終了するだけの、タイマーを作ってみます。

## サンプルファイル

サンプルファイルを用意してあるので、全体の構成はこちらから確認してください。

<ExButton href="https://github.com/akihamitsuki/spigotmc-examples/tree/main/countdown">サンプルファイルを見る/ダウンロードする</ExButton>

## タイマークラスを作る

最初に目的のカウントダウンを制御するクラスを作りましょう。

`BukkitRunnable`を継承させて新しいクラスを作ってください。(クラス名とファイル名は常に同じです。)
この中へ一定時間ごとに処理したい内容を書いていきます。

```java
// CountDownTime.java
import org.bukkit.scheduler.BukkitRunnable;

public class CountDownTimer extends BukkitRunnable {

  /** 秒数 */
  private int seconds;

  public CountDownTimer() {
    // 秒数を設定
    this.seconds = 20;
  }

  /**
   * カウントダウンを開始
   */
  public void start() {
    // runTaskTimer()を実行した時点で起動
    // Main.getInstance(): JavaPluginを指定
    // 0: 0ティック後から開始
    // 20: 20ティック(1秒)ごとにrun()を実行
    this.runTaskTimer(Main.getInstance(), 0, 20);
    Bukkit.broadcastMessage("カウントダウンを開始します。");
  }

  /**
   * カウントダウンを停止
   */
  public void stop() {
    Bukkit.broadcastMessage("カウントダウンを停止しました。");
    this.cancel();
  }

  /**
   * 指定間隔ごとに、このメソッドを実行（今回は20ティック=1秒ごと）
   */
  @Override
  public void run() {
    // 0以下になったとき
    if (seconds <= 0) {
      Bukkit.broadcastMessage("終了!");
      // cancel()を実行すると停止
      this.cancel();
      return;
    }

    // 5秒ごと(5で割った余りが0のとき)
    // または5秒未満のときに残り時間を表示
    if (seconds % 5 == 0 || seconds < 5) {
      Bukkit.broadcastMessage("残り" + seconds + "秒。");
    }

    // 1ずつ減らす
    seconds--;
  }

}
```

### タイマーを起動する

```java
this.runTaskTimer(Main.getInstance(), 0, 20);
```

この`this.runTaskTimer()`を実行した時にタイマーが動き出します。
引数は順番に、次のようになります。

1. `JavaPlugin`のインスタンス
2. 最初に動くまでのティック数
3. 次に動くまでのティック数

上の例文の場合は、開始0ティック後に動き出して、20ティック(1秒)ごとに処理を行います。

`JavaPlugin`のインスタンスを渡す必要があるので、取得しやすいようにする処理を追加しましょう。

```java
// Main.java
public class Main extends JavaPlugin {

  private static Main instance;

  @Override
  public void onEnable() {
    // プラグインを有効にしたときに作られたインスタンス(this)をstaticで残す
    Main.instance = this;
  }

  /** 他クラスからJavaPluginのインスタンスを取得できるようにするメソッド */
  public static Main getInstance() {
    return instance;
  }

}
```

これにより`Main.instance()`を使えば、どこでも`JavaPlugin`のインスタンスを取得できます。

<Note color="blue">
  このような書き方を「シングルトン(singleton)」と言います。
  より詳しい解説が知りたい方は検索してみましょう。
</Note>

### 一定時間ごとに処理を行う

上で設定した周期ごとに`run()`が実行されます。
必ずしもタイマーとして秒数を数えなくてはいけないわけではありません。
目的に合わせて自由に作ってください。

```java
// CountDownTime.java
@Override
public void run() {
  // ここに処理したい内容を書く
}
```

### タイマーを停止する

`this.cancel()`を使うとタイマーが停止します。

これは`BukkitRunnable`から継承(extend)されてきたメソッドなので、上で書いた範囲にはありません。

これを実行しないと裏で動き続けるので、停止条件を満たしたら必ず実行するようにしてください。

## タイマーを操作するクラスを作る

次は、このタイマークラスを操作するコマンドを作ります。

<LinkCard slug="plug-in-create-slash-command"></LinkCard>

使いたい操作は次の通りです。

* `/countdown start`のときに、タイマーを開始
* `/countdown stop`のときに、タイマーを停止

```java
public class CommandCountdown implements CommandExecutor {

  private CountDownTimer countDownTimer = null;

  public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {

    // CommandCountdown.java
    if (args[0].equals("start")) {
      // インスタンスを作成していれば停止処理を入れて重複を避ける
      if (countDownTimer != null) {
        countDownTimer.cancel();
      }
      // インスタンスを作成
      countDownTimer = new CountDownTimer();
      // カウントダウンを開始
      countDownTimer.start();

      return true;
    } else if (args[0].equals("stop")) {
      // インスタンスを作成していなければ停止処理をしないように
      if (countDownTimer != null) {
        countDownTimer.stop();
      }

      return true;
    }

    return false;
  }
}
```

今回のタイマーの場合、単純に`start()`と`stop()`を実行するだけでなく、現在のタイマーの状態によって処理を調整しなくてはならない点に注意してください。

`start`で新しくタイマーを作成する前に、前のタイマーを終了させておく。

```java
// インスタンスを作成していれば停止処理を入れて重複を避ける
if (countDownTimer != null) {
  countDownTimer.cancel();
}
```

まだタイマーが作成されていない場合、`stop`で止めるタイマーがないので、`stop()`を実行しないように例外処理をする。

```java
// インスタンスを作成していなければ停止処理をしないように
if (countDownTimer != null) {
  countDownTimer.stop();
}
```

### タイマーを操作するコマンドを登録する

クラスを作ったら登録するのを忘れないようにしてください。

```java
// Main.java
@Override
public void onEnable() {
  Main.instance = this;
  this.getCommand("countdown").setExecutor(new CommandCountdown());
}
```

```yaml
# plugin.yml
# 追加する
commands:
  countdown:
```

コード部分は以上になります。
プラグインをコンパイルして、サーバーに適用させてください。

## 実行する

操作するためのコマンドは次の2つでした。
これらを使ってタイマーを操作してみてください。

```bash
/countdown start
```

```bash
/countdown stop
```


周期的に処理を実行する


Spigotではスラッシュコマンドを独自に追加できます。
今回は説明を簡単にするため、挨拶を返すだけの簡単なコマンドを作成してみます。

サンプルファイルを用意してあるので、全体の構成はこちらから確認してください。

<ExButton href="https://github.com/akihamitsuki/spigotmc-examples/tree/main/create-slash-command">サンプルファイルを見る/ダウンロードする</ExButton>

## 最小構成のファイルを追加する

`/greet`というコマンドを使ったときの処理を追加してみます。
まずは、最小構成でファイルを作成してみましょう。

### コマンド内容のクラスを作成する

`/greet`を使った時のコマンド内容なので、クラス名は`CommandGreet`としましょう。
この`CommandGreet.java`をメインクラス(`pom.xml`の`main`で設定したファイル)と同じ位置に作成して、次の内容を入れてください。

```java
// CommandGreet.java
public class CommandGreet implements CommandExecutor {
  @Override
  public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
    // コマンド実行者に「Hi!」というメッセージを送る
    sender.sendMessage("Hi!");
    // コマンド成功判定
    return true;
  }
}
```

コマンド実行時のクラスとして扱うために`CommandExecutor`を実装(`implements`)します。

そして、コマンドが実行されたときのメソッドである`onCommand()`を`@Override`を付けて書き加えます。

内容はコマンド実行者に対して`Hi!`というメッセージを返すだけです。

### コマンドを登録する

次にこのクラスを、コマンドに対応させます。

`plugin.yml`に登録するコマンド名を追記します。
今回は`greet`なので、`commands`の後に記述します。
`greet`の前にスペースが2個(また4個)入ることに注意してください。

```yaml
# plugin.yml
commands:
  greet:
```

<Note color="amber">
  他にも設定しておくべき値はありますが、今回は省略します。
</Note>

追記後は下のようになっていると思います。

```yaml
# plugin.yml
main: com.example.greeting.Main
name: create-slash-command
version: 0.1
commands:
  greet:
```

最後に、`Main.java`に上で設定したコマンドを有効にするための記述を追加します。

```java
// Main.java
public class Main extends JavaPlugin {
  @Override
  public void onEnable() {
    // greetコマンドを使った時に実行するクラスを設定する
    // "greet"はplugin.ymlで設定した値
    this.getCommand("greet").setExecutor(new CommandGreet());
  }
}
```

### 実行する

これだけで新しいコマンドを追加できました。
ビルドしたプラグインを適用したSpigotサーバーを起動して、コマンドを実行してみてください。

```bash
/greet
```

`Hi`とメッセージが表示されれば成功です。

<Note color="amber">
  コンソールから使う場合は先頭に<code>/</code>は付けません。
</Note>

## コマンド内容に合わせて処理を行う

次にコマンドの内容に合わせて、具体的な処理を記述していきましょう。

### 引数が1つのとき

例えば次のようなコマンドを使ったとします。

```bash
/greet hello
```

この`/greet`以降の部分を<R t="ひきすう">引数</R>といいます。
この場合は`hello`が引数です。

この引数は`onCommand()`の中の`args`という配列に入れられて渡されます。

```java
// 引数が1つならば
if (args.length == 1) {
  // 最初の引数が"hello"であれば(`/greet hello`のとき)
  if (args[0].equalsIgnoreCase("hello")) {
    // コマンドを使った人にメッセージを送る
    sender.sendMessage("こんにちは、" + sender.getName() + "さん。");
    // 正しく処理されたので true を返す
    return true;
  }
}
```

### 引数が無いとき

最初にやったように引数がない場合もコマンドとして機能します。

```bash
/greet
```

この場合の処理も調整しておきましょう。

```java
// 引数が無かったとき(`/greet`のとき)
if (args.length == 0) {
  sender.sendMessage("どうしましたか？");
  // 処理が正常に終了したらtrueを返す
  return true;
}
```

### それ以外の引数の場合

それ以外の場合は正しくない処理として、最後に`false`を返しておきます。

```java
public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
  // ...中略

  // それ以外の場合は正しくないので false を返す
  return false;
}
```

### 最終的な内容

今回は最終的に次のようになりました。

あとは、引数の数や内容によって、自由に分岐させて処理を追加してください。

```java
public class CommandGreet implements CommandExecutor {

  @Override
  public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
    // 引数が1つのとき
    if (args.length == 1) {
      // 最初の引数が"hello"であれば(`/greet hello`のとき)
      if (args[0].equalsIgnoreCase("hello")) {
        sender.sendMessage("こんにちは、" + sender.getName() + "さん。");
        return true;
      }
    }

    // 引数が無かったとき(`/greet`のとき)
    if (args.length == 0) {
      sender.sendMessage("どうしましたか？");
      // 処理が正常に終了したらtrueを返す
      return true;
    }

    // それ以外なら、失敗判定としてfalseを返す
    return false;
  }

}
```


独自コマンドを追加する


エンティティの名前欄を使って、ワールド内に文字を表示させることができます。
チャット欄やスコアボード欄以外にも、文字を表示できるので表現の幅が広がります。

## サンプルファイル

サンプルファイルを用意してあるので、全体の構成はこちらから確認してください。

<ExButton href="https://github.com/akihamitsuki/spigotmc-examples/tree/main/display-text">サンプルファイルを見る/ダウンロードする</ExButton>

## 文字を表示するクラスを作る

Minecraftには、ワールド内に文字だけを表示させる機能はないので、
エンティティの名前欄を使って文字を表示させるクラスを作ります。

名前を付けるエンティティは動かない「防具立て」が最適です。
これを呼び出した後に、その設定を変更し、文字だけを表示しているように見せかけましょう。

```java
public class Text {

  /**
   * 文字を表示する防具立てをスポーンさせる
   */
  public static ArmorStand spawnArmorStand(World world, Location location, String name) {
    // 防具立てをスポーンさせる
    ArmorStand stand = (ArmorStand) world.spawnEntity(location, EntityType.ARMOR_STAND);
    // 呼び出した後に設定を変更する
    // 表示(visible)するか
    stand.setVisible(false);
    // 重力(gravity)の影響を受けるか
    stand.setGravity(false);
    // 不死身であるか。invulnerable: 傷つくことのない、不死身の、難攻不落の
    stand.setInvulnerable(true);
    // カスタムネームを表示するか
    stand.setCustomNameVisible(true);
    // カスタムネームの設定
    stand.setCustomName(name);

    return stand;
  }

}
```

## コマンドを設定する

上のメソッドをコマンドから使えるようにしましょう。

コマンドを使ったときの位置に、第一引数の値を表示する名前として、上で設定した防具立てをスポーンさせます。

```java
public class TextCommand implements CommandExecutor {

  @Override
  public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {

    if (sender instanceof Player) {
      Player player = (Player) sender;

      if (args.length == 1) {
        // 名前の付いた防具立てを表示
        Text.spawnArmorStand(player.getWorld(), player.getLocation(), args[0]);

        return true;
      }
    }

    return false;
  }
}
```

コマンドの登録も忘れずに。

## 表示する

上のコマンドは次のように使います。
第一引数に表示したい文を入れてください。

```bash
/text なまえ
# 「なまえ」と空中に表示

/text my name
# 引数が2つあるので無効
```

今回は例文なので、スペースが入る場合などは考慮していません。

## 表示を消す

防具立てはゾンビやクリーパーと同じエンティティなので、`/kill`を使えば消すことができます。

```bash
/kill @e[type=armor_stand]
```

呼び出したときに、無敵状態に設定していますが、コマンドの`/kill`は有効です。


ワールド上に文字を表示する


「プレイヤーが歩いたとき」「モンスターがスポーンしたとき」「ブロックが壊れたとき」などのイベントを検知してプログラムを実行できます。

今回は「プレイヤーが歩いたとき」に、足元のブロックを「赤い羊毛」に変更するというプログラムを書いてみましょう。

## サンプルファイル

サンプルファイルを用意してあるので、全体の構成はこちらから確認してください。

<ExButton href="https://github.com/akihamitsuki/spigotmc-examples/tree/main/event-handling">サンプルファイルを見る/ダウンロードする</ExButton>

## イベントリスナークラスを作成

まず、イベント検知用の新しいクラスを作成します。

プレイヤーのイベントを検知するクラスなので、ファイル名は`PlayerListener.java`としておきます。

イベントを検知するには、このクラスに`Listener`を実装してください。

```java
// PlayerListener.java
import org.bukkit.event.Listener;

public class PlayerListener implements Listener {
}
```

その中にメソッドとして、「プレイヤーが歩いた時」の処理を加えます。

`@EventHandler`をメソッドの前に加えて、引数の型を`PlayerMoveEvent`にします。

この場合、メソッド名はどんな名前でも構いません。
引数の型で検知する条件が決まります。

```java
// PlayerListener.java
@EventHandler
// メソッド名はなんでも良い。引数の型でいつ検知されるのかが変わる
public void onPlayerMove(PlayerMoveEvent event) {
}
```

さらにこの中に、具体的な処理を書いていきます。

この場合は、event変数の中に、移動したプレイヤーの情報が入っているので、この情報を元に処理を加えていきます。

```java
// PlayerListener.java
@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
  // event変数からプレイヤーを取得
  Player player = event.getPlayer();
  // プレイヤーの位置を取得
  Location location = player.getLocation();
  // 足元のブロックを取得(その位置からy座標をマイナス1)
  Block block = location.add(0, -1, 0).getBlock();
  // そのブロックが空気ブロックでなければ
  if (block.getType() != Material.AIR) {
    // 赤の羊毛に変える
    block.setType(Material.RED_WOOL);
  }
}
```

## イベント検知クラスをJavaPluginに登録する

イベント検知のクラスを作っただけでは動かないので、これを`JavaPlugin`に登録します。

```java
// Main.java
public class Main extends JavaPlugin {
  @Override
  public void onEnable() {
    // イベント検知のクラスを登録する
    this.getServer().getPluginManager().registerEvents(new PlayerListener(), this);

    // 細かく分割した場合。上はこれを1行で書いている
    // Server server = this.getServer();
    // PluginManager pluginManager = server.getPluginManager();
    // pluginManager.registerEvents(new PlayerListener(), this);
  }
}
```

`JavaPlugin`(`this`)からサーバー情報を取得し、そこからさらにプラグインマネージャーを取得します。
このプラグインマネージャーのメソッドである`registerEvents()`を使って、イベント検知クラスを登録します。

1. 第一引数が登録するクラスのインスタンス(上で作ったもの)
2. 第二引数が`JavaPlugin`(`Main`)のインスタンス、ここでは`this`

これで、プレイヤーが動くたびに、作成したメソッドが動きます。

## 検知できるイベントは大量にある

今回は「プレイヤーが歩いたとき」を検知しましたが、他にもたくさんのイベントがあります。

詳しくは[公式ドキュメント](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/class-use/Event.html)を見てください。
すべて英語ですが、ページごと翻訳をかければおおよそ何ができるのかわかると思います。


イベントを検知する

ブロックを操作する

ブロックを操作するコマンド


指定した範囲内をブロックで<R t="fill">満たす</R>コマンドです。

## 文法と例文

### 基本形

`/fill <この座標から> <この座標まで> <ブロック名>`

範囲を決めるために「ここから」「ここまで」と座標を二組入力します。
細かい数字が6つ続くことになるので、注意して入力しましょう。

```bash
/fill ~10 ~-1 ~10 ~-10 ~-1 ~-10 diamond_block
```

最初の3つ`(~10, ~-1, ~10)`と最後の3つ`(~-10, ~-1, ~-10)`で2つの座標です。

<Note color="blue" title="1回で置けるのは3万ブロックまで">
  1度のコマンドで指定できる最大範囲は<b>「約3万ブロック」</b>です。
  これを超えるとエラーになります。
  これ以上の範囲を指定したい場合は複数回に分けて実行しましょう。
  正確な数は32,768ブロックで、これは2を15回掛けた数のことです。
  計算してみてください。
</Note>

### ブロックのデータ値を決める

`/fill <この座標から> <この座標まで> <ブロック名> [データ値]`

データ値を指定する場合はブロック名に続けて入力します。
変更する必要がない場合は0にします。

```bash
/fill ~10 ~-1 ~10 ~-10 ~-1 ~-10 stained_glass 1
```

### 敷き詰め方法

`/fill <この座標から> <この座標まで> <ブロック名> [データ値] [方法名]`

敷き詰め方法を指定することで、別の方法で置くことができます。

* `destroy`: 置き換え前のブロックをアイテム化する
* `hollow`: 枠のみに置き、内側は消す
* `outline`: 枠のみに置き、内側は残す
* `keep`: ブロックがあれば置き換えない
* `replace`: 特定のブロックだけ置き換える

#### 置き換えブロックをアイテム化する

<code>
  <R t="デストロイ">destroy</R>
</code>

置き換えたブロックを<R t="destroy">壊し</R>てアイテム化します。

<Note color="amber">
  最大で3万ブロックがアイテム化するので、このモードでは特に処理が重くなります。
  小さな範囲から試して自分のPCスペックに合わせて使いましょう。
</Note>

```bash
# 周囲5ブロックを空気ブロックで埋め、置き変わったブロックをアイテム化する
/fill ~5 ~-5 ~5 ~-5 ~5 ~-5 air 0 destory
```

#### 枠のみに置き、内側は消す

<code>
  <R t="ホロウ">hollow</R>
</code>

範囲内を<R t="hollow">空洞</R>にするようにブロックを敷き詰めます。
指定ブロックは外側1ブロック分にのみ置かれ、その内側は空気ブロックで取り除かれます。

```bash
/fill ~5 ~-5 ~5 ~-5 ~5 ~-5 glowstone 0 hollow
```

#### 枠のみに置き、内側は残す

<code>
  <R t="アウトライン">outline</R>
</code>

範囲内の<R t="outline">輪郭</R>にのみ指定ブロックを置きます。
その内側は何も影響を受けずにそのまま残ります。

```bash
/fill ~5 ~-5 ~5 ~-5 ~5 ~-5 glowstone 0 outline
```

#### ブロックがあれば置き換えない

<code>
  <R t="キープ">keep</R>
</code>

範囲内のブロックの状態を<R t="keep">保ち</R>、何もない場所にだけブロックを敷き詰めます。

```bash
/fill ~5 ~-5 ~5 ~10 ~5 ~10 stained_glass 1 keep
```

#### 特定のブロックだけ置き換える

<code>
  <R t="リプレイス">replace</R>
</code>

範囲内にある特定のブロックだけを<R t="replace">置き換え</R>ます。
このモードだけさらに置き換えるブロック名を続けて入力します。

```bash
# 周囲の草ブロックだけ消す
/fill ~10 ~-5 ~10 ~-10 ~5 ~-10 air 0 replace grass
# 葉ブロックをピンクの羊毛に置き換える
/fill ~5 ~0 ~5 ~-5 ~20 ~-5 wool 6 replace leaves
```


/fill

/fill - ブロックで満たす


指定した座標に<R t="block">ブロック</R>を<R t="set">置く</R>コマンドです。

## 基本の使い方

`/setblock <座標> <ブロック名>`

コマンドに続いて、**座標**と**ブロック名**を入力します。

```bash
# 1ブロック先にTNTブロックを置く
/setblock ~1 ~ ~ tnt
# 足元に空気ブロックを置く（ブロックを消す）
/setblock ~ ~-1 ~ air
# (0, 64, 0)に溶岩源ブロックを置く
/setblock 0 64 0 lava
# 10ブロック前にダイヤモンドブロックを置く
/setblock ^ ^ ^10 diamond_block
```

通常はアイテムとして持てないネザーやエンドへのポータルなども置くことができます。

```bash
# 足元にエンドポータルを置く（すぐにエンドへ移動する）
/setblock ~ ~ ~ end_portal
# 足元に(ネザー)ポータルを置く（ネザーへ移動する）
/setblock ~ ~ ~ portal
```

## ブロックを細かく指定する

### データ値でブロックを指定する

`/setblock <座標> <ブロック名> [データ値]`

ブロック名の後に数字を加えることで、ブロックの種類を変えることができます。
すべてのブロックがデータ値を持っているわけではありません。

```bash
# 何も入力しないと通常の白色の羊毛
/setblcok ~ ~-1 ~ wool
# 0は何も入力しない場合と同じ
/setblcok ~ ~-1 ~ wool 0
# 1にすると橙色
/setblcok ~ ~-1 ~ wool 1
# 最大で15まである（途中までしかないものもある）
/setblcok ~ ~-1 ~ wool 15
```

### ブロック状態で指定する

`/setblock <座標> <ブロック名> [ブロック状態]`

データ値の代わりに<R t="block state">ブロック状態</R>でも指定できます。
できることはデータ値とほとんど同じなので、無理して使う必要はありません。

```bash
# 「激しく損傷している」金床
/setblock ~ ~ ~ anvil ["damage": "very_damage"]
# 「開いている」アカシアのドア
/setblock ~ ~ ~ acacia_door ["open_bit": true]
# 「橙色」の羊毛
/setblock ~ ~ ~ wool ["color": "orange"]
```

JSON形式に似ていますが別の書き方です。

データ値と違い、記述を見ただけでどのようなブロックを指定しているのかがわかりやすいのが特徴です。
しかし、その分だけ書き方を覚えなくてはならないので、上級者向けの機能になります。

どのような値が使えるかは公式Wikiを読んでください。

<ExButton href="https://minecraft.fandom.com/ja/wiki/%E3%83%96%E3%83%AD%E3%83%83%E3%82%AF%E7%8A%B6%E6%85%8B">ブロック状態(公式Wiki)</ExButton>

また、この方法はアドオンでブロックを操作するのにも使います。
もしアドオンまで進むつもりなら積極的に使ってみてください。

## 破壊モード

`/setblock <座標> <ブロック名> [データ値] [破壊モード]`<br />
`/setblock <座標> <ブロック名> [ブロック状態] [破壊モード]`

最後に破壊モードを指定することで、配置先のブロックの扱いを決めることができます。

破壊モードは3種類あり、次のいずれかを入力します。

* `replace`: そのまま置き換える(初期値。何も指定しない場合と同じ)
* `destroy`: 置き換え前のブロックをアイテム化する
* `keep`: ブロックがあれば置き換えない

破壊モードを指定するためには**データ値**または**ブロック状態**の指定が必要です。
ブロックをそのまま使いたい場合はデータ値の0で入力しておくのがよいでしょう。

### 置き換えブロックをアイテム化する

<code>
  <R t="デストロイ">destroy</R>
</code>

置き換えたブロックを<R t="destroy">壊し</R>てアイテム化します。

```bash
# 対象のブロックを壊して置き換える
/setblock ~ ~-1 ~ air 0 destroy
```

### ブロックがあれば置き換えない

<code>
  <R t="キープ">keep</R>
</code>

対象ブロックの状態を<R t="keep">保ち</R>、何もない場合にだけブロックを置きます。

```bash
# 対象にブロックがあれば置き換えない、なければ置き換える
/setblock ~ ~-1 ~ gold_block 0 keep
/setblock ~ ~ ~ gold_block 0 keep
```

### 特定のブロックだけ置き換える

<code>
  <R t="リプレイス">replace</R>
</code>

対象のブロックを<R t="replace">置き換え</R>ます。
これは何も指定しない場合と同じです。

```bash
# 対象のブロックを置き換える
/setblock ~ ~-1 ~ tnt 0 replace
```


/setblock

/setblock - ブロックを置く


<Note color="amber">
ここでは他のコマンドと組み合わせて使う特に難しいコマンドを扱います。
コマンドに慣れていないうちは、他のコマンドを使ってコマンド自体に慣れましょう。
</Note>


条件を付け加える

条件を付け加えるコマンド


自分以外を基準にしてコマンドを実行し、複雑な処理を行うことができます。

`/execute`は**通常モード**と**detectモード**の2つがあります。
detectモードでは通常モードの機能に加え特別な条件を加えた操作を行えます。

まずは通常モードから例文を通して学んでいきましょう。

## 通常モード

### ニワトリをそのニワトリ自身の上空に移動させる

事前準備としてニワトリを呼び出しておきます。

```bash
# ニワトリを5匹呼び出す
/summon chicken
/summon chicken
/summon chicken
/summon chicken
/summon chicken
```

次に`/tp`の使い方のおさらいです。次の場合は自分を20ブロック上に移動させます。

```bash
/tp @s ~ ~20 ~
```

次は`type`を使って<R t="chiken">ニワトリ</R>に絞り込んで実行してみましょう。

```bash
/tp @e[type=chiken] ~ ~20 ~
```

この場合ニワトリ達は**プレイヤーの上**に移動します。移動先の`~ ~20 ~`は**実行者であるプレイヤー**を基準にしているからです。

目的の操作はニワトリを、そのニワトリ自身の上空に移動させることでした。プレイヤーの上ではありません。`/tp`の動作を考えると、`/tp`をニワトリ達自身に実行させればうまくいきそうです。

ここで出てくるのが`/execute`です。`/execute`はコマンドの実行者を自分以外にするコマンドです。

```bash
/execute @e[type=chicken] ~ ~ ~ tp ~ ~20 ~
```

ニワトリ達がプレイヤーの上ではなく、ニワトリそれぞれの上に移動すれば成功です。`@e[type=chicken]`で選ばれたそれぞれの対象自身が、`/tp ~ ~20 ~`を実行した形になります。

このコマンドは次の2つに分けることができます。

* `@e[type=chicken] ~ ~ ~`: コマンドを実行させる対象
* `tp ~ ~20 ~`: 使用させるコマンド(最初のスラッシュは不要)

このように、自分以外のエンティティをコマンドの実行者にしないとできないような操作するのが`/execute`です。

### クリーパーに雷を落とす

この場合は次の通りになります。

```bash
/execute @e[type=creeper] ~ ~ ~ summon lightning_bolt
```

雷はエンティティ扱いなので`/summon`で呼び出せます。

自分で`/summon`を使った場合は呼び出す場所を座標しか指定できません。雷を動いているクリーパーに当てるのは難しいですが、`/execute`を使って対象から自分自身に落とさせれば必ず命中させることができます。

## detectモード

`/execute`にはもう1つdetect(検知)モードという使い方があります。指定の場所に特定のブロックが存在するかを判定して、コマンドを実行するかを決める使い方です。

### クリーパーの"足元が草ブロックなら"雷を落とす

```bash
# 対象の足元が草ブロックなら雷を落とす
/execute @e[type=creeper] ~ ~ ~ detect ~ ~-1 ~ grass 0 summon lightning_bolt
# 参考: detectモードを使わない場合(ブロックの状態に関係なく実行)
/execute @e[type=creeper] ~ ~ ~                        summon lightning_bolt
```

このコマンドの中で次の部分がdetectモードで使用する箇所です。

`detect ~ ~-1 ~ grass 0`

この部分を通常モードの間に追加することでdetectモードになります。

* `detect`: detectモードを使用する
* `~ ~-1 ~`: その対象からの座標
* `grass 0`: 検知するブロック名とデータ値

この条件が満たされた場合(対象の足元が草ブロック)にのみ、以降のコマンドが実行されます。

### "足元が砂ブロックなら"移動速度を遅くする

この場合は、ずっと判定し続けて欲しいのでコマンドブロックの反復モードで使用します。

```bash
# コマンドブロックの反復モードで使用
# 対象の足元が砂ブロックなら移動速度を遅くする
/execute @e ~ ~ ~ detect ~ ~-1 ~ sand -1 effect @s slowness 1 0 true
# 参考: detectモードを使わない場合
/execute @e ~ ~ ~                        effect @s slowness 1 0 true
```


/execute

/execute - 自分以外を基準にしてコマンドを実行する


各エンティティに独自の数字を持たせ、管理するコマンドです。

* `objectives`は、各エンティティが**どのような入れ物を持つのか**を操作します。
* `players`は、そのエンティティが持っている**入れ物に、何を・どう入れるのか**を操作します。
* 箱の中に入れられるのは**数字(整数)だけ**です(-21億から+21億の間)。文字は入りません。
* 箱の中に何も入っていない場合は`undefined`(未定義)になります。0ではありません。

## objectives - 全体のオブジェクトの枠組みを操作する

`objective` は日本語に訳すのが難しいので、そのまま「オブジェクト」とします。
数字を入れておく箱のようなものだと思ってください。

<Table>
  <tbody>
    <tr>
      <th rowspan="6"><code>/socreboard objectives</code></th>
      <td colspan="2">
        <div><code>add</code></div>
        <div><small>オブジェクトを作成する</small></div>
      </td>
      <td rowspan="2">
        <div><code>&lt;objective&gt;</code></div>
        <div><small>オブジェクト名</small></div>
      </td>
      <td><code>dummy</code></td>
      <td>
        <div><code>[displayName]</code></div>
        <div><small>表示名</small></div>
      </td>
    </tr>
    <tr>
      <td colspan="2">
        <div><code>remove</code></div>
        <div><small>オブジェクトを削除</small>する</div>
      </td>
    </tr>
    <tr>
      <td colspan="2">
        <div><code>list</code></div>
        <div><small>オブジェクトの一</small>覧を見る</div>
      </td>
    </tr>
    <tr>
      <td rowspan="3">
        <div><code>setdisplay</code></div>
        <div><small>オブジェクトの値を表示</small></div>
      </td>
      <td>
        <div><code>list</code></div>
        <div><small>ポーズ画面</small></div>
      </td>
      <td rowspan="3">
        <div><code>[objective]</code></div>
        <div><small>オブジェクト名</small></div>
      </td>
      <td rowspan="2" colspan="2">
        <div><code>[ascending|descending]</code></div>
        <div><small>並び順</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>sidebar</code></div>
        <div><small>画面右側</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>belowname</code></div>
        <div><small>名前の下</small></div>
      </td>
    </tr>
  </tbody>
</Table>

### オブジェクトを追加する

`/scoreboard objectives add <オブジェクト名> dummy [表示名]`

```bash
# オブジェクト「score」を追加、表示名は「スコア」
/scoreboard objectives add score dummy スコア
```

<Note color="amber">
  現在、BEには<code>dummy</code>しかありません。
  JEにある他の機能はアドオンを併用して対応してください。
</Note>

### オブジェクトを削除する

`/scoreboard objectives remove <オブジェクト名>`

```bash
# オブジェクト「score」を削除
/scoreboard objectives remove score
```

### オブジェクトの一覧を表示する

`/scoreboard objectives list`

```bash
# 現在登録されているオブジェクトの一覧を表示
/scoreboard objectives list
```

### オブジェクトを画面に表示する

`/scoreboard objectives setdisplay <list|sidebar> [オブジェクト名] [並び順]]`

```bash
# オブジェクト「score」をlistに降順（大きい数から）で表示
/scoreboard objectives setdisplay list score descending

# オブジェクト「score」をsidebaに昇順（小さい数から）で表示
/scoreboard objectives setdisplay sidebar score ascending
```

### オブジェクトを名前の下に表示する

`/scoreboard objectives setdisplay belowname [オブジェクト名]`

```bash
# オブジェクト「score」を各エンティティの名前の下に表示
/scoreboard objectives setdisplay belowname score
```

## players - 個別のオブジェクトの値を操作する

名称はプレイヤーとなっていますが、すべてのエンティティが対象です。
例えば、「防具立て」や「トロッコ」にもオブジェクトを持たせることができます。

<Table>
  <tbody>
    <tr>
      <th rowspan="7">
        <code>/scoreboard players</code>
      </th>
      <td>
        <div><code>list</code></div>
        <div><small>そのエンティティの持つオブジェクト名一覧を見る</small></div>
      </td>
      <td colspan="3">
        <div><code>[playername]</code></div>
        <div><small>対象者</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>reset</code></div>
        <div><small>オブジェクトの値を初期化する</small></div>
        <div><small>(<code>x = undefined</code>)</small></div>
      </td>
      <td rowspan="6">
        <div><code>&lt;player&gt;</code></div>
        <div><small>対象者</small></div>
      </td>
      <td colspan="2">
        <div><code>[objective]</code></div>
        <div><small>オブジェクト名</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>test</code></div>
        <div><small>オブジェクトを値を評価する</small></div>
        <div><small>(<code style={{"white-space": "no-wrap"}}>{'if(min <= x && x <= max)'}</code>)</small></div>
        <div><small>コマンドブロックで実行した際に、真ならコンパレーターを通して信号が出力される。</small></div>
      </td>
      <td rowspan="5">
        <div><code>&lt;objective&gt;</code></div>
        <div><small>オブジェクト名</small></div>
      </td>
      <td>
        <div><code>&lt;min&gt; [max]</code></div>
        <div><small>範囲(ワイルドカードあり)</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>random</code></div>
        <div><small>オブジェクトに無作為な値を代入する</small></div>
        <div><small>(<code>{'x = Math.random(min, max)'}</code>)</small></div>
      </td>
      <td>
        <div><code>&lt;min&gt; [max]</code></div>
        <div><small>範囲</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>set</code></div>
        <div><small>オブジェクトを指定の値にする</small></div>
        <div><small>(<code>x = count</code>)</small></div>
      </td>
      <td rowspan="3">
        <div><code>&lt;count&gt;</code></div>
        <div><small>数字</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>add</code></div>
        <div><small>オブジェクトに指定の値を加える</small></div>
        <div><small>(<code>x += count</code>)</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>remove</code></div>
        <div><small>オブジェクトを指定の値で減らす</small></div>
        <div><small>(<code>x -= count</code>)</small></div>
      </td>
    </tr>
  </tbody>
</Table>

### オブジェクト名を表示する

`/scoreboard players list [誰の]`

そのエンティティが持っているオブジェクトの一覧を表示する。

```bash
/scoreboard players list @s
```

### オブジェクトを初期化する

`/scoreboard players reset <誰の> [オブジェクト名]`

```bash
# 「score」オブジェクトの値を初期化する
/scoreboard players reset @s score

# オブジェクト名を指定しないとすべてのオブジェクトが初期化される
/scoreboard players reset @s
```

### オブジェクトの値が特定の範囲内にあるかどうかを検査する

`/scoreboard players test <誰の> <オブジェクト名> <最小値> [最大値]`

```bash
# オブジェクトの値が1以上100以下かどうか
/scoreboard players test @s score 1 100
# オブジェクトの値が100ちょうどかどうか
/scoreboard players test @s score 100 100

# オブジェクトの値が50以下かどうか
/scoreboard players test @s score * 50
# オブジェクトの値が50以上かどうか
/scoreboard players test @s score 50 *
# 最大値の方は指定しない場合と同じ
/scoreboard players test @s score 50

# オブジェクトの値になにかの数字が入っているか
# undefinedではないことを調べられる
/scoreboard players test @s score * *
# これと同じ意味
/scoreboard players test @s score -2147483648 2147483647
```

これ自体は何も影響を与えません。
`testfor`や`testforblock`などと同じように、判定に使用します。
判定が成功したら、成功判定としてコンパレーターから信号を出します、またコマンドブロックの条件も有効になります。

<Note color="blue" title="ワイルドカード(*)とは">
  <code>*</code>(アスタリスク)で指定します。
  最小値の方で使うと最小値(約-21億)、最大値の方で使うと最大値(約+21億)と同じ意味になります。
</Note>

### オブジェクトにランダムな値を入れる

`/scoreboard players random <誰の> <オブジェクト名> <最小値> <最大値>`

```bash
# 1から100までの数字をランダムに入れる
/scoreboard players random @s score 1 100
```

### オブジェクトに指定した値をそのまま入れる

`set`を使うと、そのオブジェクトの値を指定した数にします。
元の値に関係なく、その数で上書きしてしまいます。

`/scoreboard players set <誰の> <オブジェクト名> <整数>`

```bash
/scoreboard players set @s score 50
```

### オブジェクトを指定した値で増やす

`add`を使うと、そのオブジェクトの値を増やすことができます。
元の値が`undefined`であった場合は0として扱われ、0から足した数になります。

`/scoreboard players add <誰の> <オブジェクト名> <整数>`

```bash
/scoreboard players add @s score 50
```

### オブジェクトを指定した値で減らす

`/scoreboard players remove <誰の> <オブジェクト名> <整数>`

元の値が`undefined`であった場合は0として扱われ、0から引いた数になります。

```bash
/scoreboard players remove @s score 50
```

## players operation - オブジェクト同士を計算する

演算子(+や-などの記号)を使って、オブジェクト同士を計算できます。

`/scoreboard players operation <変更される方> <オブジェクト名> <演算子> <計算に使う方> <オブジェクト名>`

```bash
/scoreboard players operation @a[tag=achieved] score += @e[tag=admin] reward
```

長いので次のまとまりを`x`,`y`と表します。

* `x`: `<変更される方> <オブジェクト名>`
* `y`: `<計算に使う方> <オブジェクト名>`

<Table>
  <tbody>
    <tr>
      <th rowspan="9"><code>/scoreboard players</code></th>
      <td rowspan="9">
        <div><code>operation</code></div>
        <div><small>オブジェクト同士で計算</small></div>
      </td>
      <td rowspan="9">
        <div><code>x</code></div>
        <div><small>変更される方</small></div>
      </td>
      <td>
        <div><code>+=</code></div>
        <div><small>足す（加算）(<code>x = x + y</code>)</small></div>
      </td>
      <td rowspan="9">
        <div><code>y</code></div>
        <div><small>計算に使う方</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>-=</code></div>
        <div><small>引く（減算）(<code>x = x - y</code>)</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>*=</code></div>
        <div><small>掛ける（乗算）(<code>x = x * y</code>)</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>/=</code></div>
        <div><small>割る（除算。余りは切り捨て）</small></div>
        <div><small>(<code>x = Math.floor(x / y)</code>)</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>%=</code></div>
        <div><small>余り（剰余）: 割った後の余りを入れる</small></div>
        <div><small>(<code>x = x % y</code>)</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>=</code></div>
        <div><small>代入: 同じ値を入れる(<code>x = y</code>)</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>{'<'}</code></div>
        <div><small>小さい方: 2つのうち小さい方を入れる</small></div>
        <div><small>(<code>{'x = Math.min(x, y)'}</code>)</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>></code></div>
        <div><small>大きい方: 2つのうち大きい方を入れる</small></div>
        <div><small>(<code>{'x = Math.max(x, y)'}</code>)</small></div>
      </td>
    </tr>
    <tr>
      <td>
        <div><code>{'><'}</code></div>
        <div><small>入れ替え: 値を入れ替える</small></div>
        <div><small>(<code>[x, y] = [y, x]</code>)</small></div>
      </td>
    </tr>
  </tbody>
</Table>

{/*prettier-ignore*/}
<Note color="amber" title="=は「代入」。「等しい」ではない">
この場合の<code>=</code>はプログラミングで言う<strong>代入</strong>です。<br />
代入とは「この記号の右の計算結果を左の箱に入れる」という意味になります。
算数・数学で言う「等しい・イコール」ではありません。
ちなみに等しいを表す場合は<code>==</code>と2つ繋げます。
これはほとんどのプログラミング言語で共通です。
Minecraft独自のものではありません。
</Note>

計算に使う方のオブジェクトが`undefined`だとエラーです。

### 例文のための準備

```bash
# 防具立てを「Global」という名前で呼び出す
/summon armor_stand Global

# 全員にscoreオブジェクトを作成
/scoreboard objectives add score
# Globalのscoreを30にする
/scoreboard players set Global score 30
# scoreを名前の下に表示
/scoreboard objectives setdisplay sidebar score
```

### 別のオブジェクトの値で足す

```bash
# 自分のscoreを初期化
/scoreboard players set @s score 100
# 自分のscore(100)を、Globalのscore(30)で足す(100 + 30)
/scoreboard players operation @s score += Global score
# -> 130
```

### 別のオブジェクトの値で引く

```bash
# 自分のscoreを初期化
/scoreboard players set @s score 100
# 自分のscore(100)を、Globalのscore(30)で引く(100 - 30)
/scoreboard players operation @s score -= Global score
# -> 70
```

### 別のオブジェクトの値で掛ける

```bash
# 自分のscoreを初期化
/scoreboard players set @s score 100
# 自分のscore(100)を、Globalのscore(30)で掛ける(100 * 30)
/scoreboard players operation @s score *= Global score
# -> 3000
```

### 別のオブジェクトの値で割る

```bash
# 自分のscoreを初期化
/scoreboard players set @s score 100
# 自分のscore(100)を、Globalのscore(30)で割る(100 / 30)
/scoreboard players operation @s score /= Global score
# -> 3(余りは無視される)
```

相手のオブジェクトが`0`の場合は計算されず、元の値がそのまま入ります。
(0で割る計算はできません。)

### 別のオブジェクトの値で割った余りにする

```bash
# 自分のscoreを初期化
/scoreboard players set @s score 100
# 自分のscore(100)を、Globalのscore(30)で割った余りにする(100 % 30)
/scoreboard players operation @s score %= Global score
# -> 10
```

相手のオブジェクトが`0`の場合は計算されず、元の値がそのまま入ります。

### 別のオブジェクトの値にする

```bash
# 自分のscoreを初期化
/scoreboard players set @s score 100
# 自分のscore(100)に関係なく、Globalのscore(30)にする
/scoreboard players operation @s score = Global score
# -> 30
```

### 別のオブジェクトの値と比較して小さいほうにする

```bash
# 自分のscoreを初期化
/scoreboard players set @s score 100
# 自分のscore(100)とGlobalのscore(30)で小さい方にする
/scoreboard players operation @s score < Global score
# -> 30
```

### 別のオブジェクトの値と比較して大きいほうにする

```bash
# 自分のscoreを初期化
/scoreboard players set @s score 100
# 自分のscore(100)とGlobalのscore(30)で大きい方にする
/scoreboard players operation @s score > Global score
# -> 100
```

### 別のオブジェクトの値と入れ替える

```bash
# 自分のscoreを初期化
/scoreboard players set @s score 100
# 自分のscore(100)とGlobalのscore(30)を入れ替える
/scoreboard players operation @s score >< Global score
# -> 30(自分)
# -> 100(Global)
```


/scoreboard

/scoreboard - スコアボードを操作する


<R t="tag">タグ</R>を管理するコマンドです。
タグを付けることでエンティティをターゲットセレクタで絞り込めるようになります。
そのため他のコマンドと組み合わせなくては意味がありません。

## タグを追加する

`/tag <誰に> add <タグ名>`

指定したエンティティにタグを<R t="add">追加</R>します。

```bash
# モンスターをランダムに5体選んで"enemy"タグをつける
/tag @r[family=monster, c=5] add enemy
```

タグを付けたあとはこのタグを条件にして、同じエンティティを選び続けることができます。

```bash
/tp @e[tag=enemy] ~20 ~ ~
/effect @e[tag=enemy] speed 60 5 true
```

## タグを削除する

`/tag <誰に> remove <タグ名>`

指定したエンティティが持っているタグを<R t="remove">取り除き</R>ます。

```bash
# すべてのエンティティに"target"タグを付ける
/tag @e add target
# 自分だけ"target"タグを外す
/tag @s remove target
# "target"タグを持っているエンティティを倒す
/kill @e[tag=target]
```

## 持っているタグを表示する

`/tag <誰の> list`

指定したエンティティが持っているタグの<R t="list">一覧</R>を表示します。

```bash
/tag @s list
```

## 使用例

### 各プレイヤーを2つのチームに分ける

次の2つのコマンドを交互に繰り返して、プレイヤー全員にタグを付けてチームを振り分けます。(コマンドブロックの反復・チェーンを利用する)

```bash
# team1でもteam2でもないランダムなプレイヤーに「team1」タグを付ける
/tag @r[tag=!team1, tag=!team2] add team1
# team1でもteam2でもないランダムなプレイヤーに「team2」タグを付ける
/tag @r[tag=!team1, tag=!team2] add team2
```

以降はタグで絞り込むことにより、チーム別で処理が実行できます。

```bash
# team1の設定
/replaceittem entity @a[tag=team1] slot.armor.head lether_helmet 1 1
/tp @a[tag=team1] 20 64 0
# team2の設定
/replaceittem entity @a[tag=team2] slot.armor.head lether_helmet 1 2
/tp @a[tag=team2] -20 64 0
```


/tag

/testforblock

/testforblock - ブロックを検知する


<R t="ticking area">ティック領域</R>を追加、削除または一覧を表示するコマンドです。

Minecraftでは、プレイヤーから遠く離れた場所は時間が止まります。
しかし、コマンドブロックなど動作が止まってしまうと困るものもあります。
このコマンドではどれだけ離れようとも、動作を停止させずに動かし続ける範囲を設定できます。

## ティック領域とは

Minecraftの世界はとても広いので、もし世界のすべてを動かそうとすると、とても大きな処理能力が必要になってしまいます。
これを避けるために、ゲーム中はプレイヤーの周りだけが動くようにできています。
行くことのない遠くの場所にいる、動物の動きや植物の成長を管理し続けても意味がありませんからね。

しかし、コマンドによる自作ゲームでは、とても広い範囲を移動したりする場合があります。
自作ゲームを動かしているときに、遠くのコマンドブロックが止まってしまうと困ります。
このような場合などに、止まってほしくない範囲を決めて、その場所からプレイヤーが離れても動かし続けるためのコマンドが`/tickingarea`です。

## 範囲を追加する

追加した領域は離れていてもランダムティックが進行するようになります。
プレイヤーが近くにいる時と同じようにコマンドブロックが動き、植物が成長します。

範囲はブロック単位で指定しますが、**実際にはその範囲を含むチャンク**で設定されます。

### 立方体で範囲を指定

`/tickingarea add <ここから> <ここまで> [範囲名]`

`/fill`のように始点と終点を決めて立方体の形で範囲を決めます。

`[範囲名]`は自分で付ける範囲の名前です。
あとで削除するときや、一覧で確認するときに使います。
わかりやすい名前を付けておきましょう。

```bash
# 立方体範囲: 始点から終点までを含むチャンクを「commandBlocks」という名前を付けて追加
/tickingarea add 0 64 0 20 84 20 commandBlocks
```

実際にはこの範囲を含むチャンク単位で動き続けます。
よって、高さは関係ありません。

### 円で範囲を指定

`/tickingarea add circle <中心座標> <半径> [範囲名]`

中心の座標とそこからの半径を決めて円の形で範囲を決めます。

```bash
# 円柱範囲: 中心からの半径を含むチャンクを「commandBlocks2」という名前を付けて追加
/tickingarea add circle 0 64 0 10 commandBlocks2
```

こちらも同様に、この範囲を含むチャンク単位で動き続けます。

## 範囲を削除する

設定した範囲を削除します。

### 名前で削除

`/tickingarea remove <範囲名>`

範囲名を指定して、その範囲を丸ごと削除します。

```bash
# 「commandBlocks」という名前の範囲を削除
/tickingarea remove commandBlocks
```

### 位置で削除

`/tickingarea remove <position: x y z>`

指定した位置を含む登録済み範囲を削除します。

```bash
# 削除: 指定した位置を含む登録済み範囲を削除
/tickingarea remove 0 74 0 0 84 0
```

### すべて削除

`/tickingarea remove_all`

設定済みの範囲をすべて削除します。

```bash
# 削除: すべて
/tickingarea remove_all
```

## 一覧を表示

`/tickingarea list [all-dimensions: AllDimensions]`

設定した範囲を表示します。

```bash
# 一覧
/tickingarea list
```


/tickingarea

/tickingarea - ティック領域を管理する


ゲームを演出するコマンドです。


ゲームを演出する

ゲームを演出するコマンド


画面に表示する<R t="title">字幕</R>を管理するコマンドです。

## 大きい字幕を表示

`/title <誰に> title <表示する文章>`

```bash
# 画面中央に「Minecraft」と表示する
/title @a title Minecraft

# 空白を入れて書くこともできます
/title @a title M i n e c r a f t
```

## 小さい字幕を合わせて表示する

`/title <誰に> subtitle <表示する文章>`

`subtitle`は上で説明した`title`と一緒に使います。
`subtitle`は小さい字幕の設定だけを行うだけで、これを実行した段階では表示されません。
次に`title`を使った時に`subtitle`も一緒に表示されます。

```bash
# 小さい字幕を設定（まだ表示されない）
/title @a subtitle Game Start!

# 大きい字幕を設定して表示（小さい字幕と一緒に表示）
/title @a title Minecraft
```

`title`が表示中だった場合は、その場で追加されて表示されます。

## アクションバーに表示する

`/title <誰に> actionbar <表示する文章>`

アクションバーとはホットバーの上の部分のことです。
通常の字幕と同時に表示できます。

```bash
# アクションバーに表示する
/title @a actionbar ここがアクションバーです

# 上が表示中に使っても一緒に表示される
/title @a title Minecraft
```

この箇所は表示時間の設定ができないので、表示し続けたい場合は、繰り返し何度も実行してください。

## 表示する時間を変更する

`/title <誰に> times <フェードイン> <表示される時間> <フェードアウト>`

字幕を表示する時間を変更できます。
アクションバー欄には効果はありません。
左から順番に次のようになります。

1. フェードイン: 不透明度が0%から始まり100%になるまでの時間
2. 待機時間: 不透明度が100%のままの時間
3. フェードイン: 不透明度が100%から始まり0%になるまでの時間

ここでの数字の**単位は<R t="tick">ティック</R>**です。秒ではありません。
20ティックで1秒になるので注意してください。秒だと思って1に設定すると一瞬(0.05秒)で終わってしまいます。

<Note color="blue">時間の単位はティック。20ティックで１秒。</Note>

秒数から考える場合は20を掛ければティック数になり、ティック数から考える場合は20で割れば秒数に直すことができます。

```bash
# 「2秒でフェードイン・6秒間表示・1秒でフェードアウト」と設定
/title @a times 40 120 20

# 表示時間が変わったか確認する
/title @a title Minecraft
```

一度設定すると何度でも有効です。

## 表示中の字幕を削除する

`/title <誰の> clear`

表示中の内容を取り除くことができます。

```bash
# 長い時間(10分)表示する
/title @a times 20 12000 20

# 表示する
/title @a title Minecraft

# 表示中の内容を取り除く
/title @a clear
```

## 設定を初期化する

`/title <誰の> reset`

副題・表示時間を最初の状態に戻します。

```bash
# 長い時間(10分)表示する
/title @a times 20 12000 20

# 時間の設定を初期化する
/title @a reset

# 字幕を表示（すぐに消える）
/title @a title Minecraft
```


/title

/title - 画面に文字を表示する


エンティティとは「プレイヤー・動物・モンスター・着火したTNT・雷・落ちているアイテム」などのことです。

初めのうちは「Minecraft世界でブロックではないもの」という考え方で問題ありません。(他にはパーティクルもあります)


エンティティを操作する

エンティティを操作するコマンド


エンティティのステータス効果を操作するコマンドです。
各種ステータス効果を与えたり取り消します。

## 使い方

<code>/<R t="エフェクト">effect</R></code>は効果を「与える」と「消す」の2種類の使い方があります。

### 効果を与える

`< >`で囲んであるところまでが必須です。`[ ]`は省略できます。

`/effect <誰に> <エフェクト名> [秒数] [強さ] [パーティクルを消すか]`

```bash
# 自分に跳躍力上昇（ジャンプ力を上げる）を10秒の間、強さ255（最大値）で与える。
# 効果の強さは最大で255です。どこまでジャンプするか試してみましょう。
/effect @s jump_boost 10 255

# 自分に透明化を60秒与える。透明に強さは関係ないので0でも255でも同じ。
# パーティクルは表示されて欲しくないので、最後にtrueを加える。
/effect @s invisibility 600 0 true

# 秒数以降は省略することができます。
# 次の2つは同じです。何も書かないと決まった値が適用されます。
/effect @s speed
/effect @s speed 30 0 false
```

### 効果を消す

`/effect <誰のを> clear`

この方法では、その人の**すべての**ステータス効果を消します。
一部だけは消すことはできません。

```bash
# 自分のステータス効果をすべて消す。
/effect @s clear
```

一部だけ消したい場合は**0秒間与える**と考えて次のように使います。

```bash
# 0秒間効果を与える -> 効果がすぐに切れる -> 効果を消す
/effect @s invisibility 0
```

### 引数（細かい書き方）

<Table>
  <thead>
    <tr>
      <th>用語</th>
      <th>初期値</th>
      <th>説明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th><code>&lt;player: target&gt;</code></th>
      <td>必須</td>
      <td><strong>誰に</strong>エンチャントをかけるか。</td>
    </tr>
    <tr>
      <th><code>&lt;effect: string&gt;</code></th>
      <td>必須</td>
      <td><strong>どのステータス効果</strong>を与えるのか。<br />下の一覧から選ぶ。</td>
    </tr>
    <tr>
      <th><code>[seconds: int]</code></th>
      <td><code>30</code></td>
      <td>効果を与える<strong>秒数</strong>。<br />`0`にすると効果を消すことができる。<br />`60`で1分、`3600`で1時間、`86400`で1日。<br />最大で`1000000`（約11日間）まで。</td>
    </tr>
    <tr>
      <th><code>[amplifier: int]</code></th>
      <td><code>0</code></td>
      <td>効果の<strong>強さ</strong>。`0`から`255`までの整数を入れる。<br />`0`から効果が出るので、`0`にしても効果は消えない。<br />普通は`0`から`4`くらいを選ぶ。<br />`255`にすると非常に強くなるので注意。<br />強すぎると種類によっては効果が出なくなる。</td>
    </tr>
    <tr>
      <th><code>[hideParticles: bool]</code></th>
      <td><code>false</code></td>
      <td>パーティクルを<strong>隠す</strong><br />「隠す」なので`true`で表示が消える。<br />間違えやすいので注意。</td>
    </tr>
  </tbody>
</Table>

エフェクト名の代わりにIDを使った数字でも扱うことができる。

## ステータス効果一覧

<small>表の「強さ上限」は効果が上限に達する、または見かけ上の変化が無くなる値。一部例外を除いて255まで入力できるがこの値を超えても無意味。</small>

<StatusEffectTable />

## ステータス詳細

コマンドで入力する強さ(amplirier)は0から有効で、この0の時をレベル1とみなす。
計算には1から数えた方がわかりやすいので以降はレベルで考える。

`level = amplifier + 1`

### スピード (移動速度上昇)

<StatusEffect code="speed" />

移動速度が`level * 20`%上がる。

最大レベルでは制御不能状態に落ちいる。

### 鈍化 (移動速度低下)

<StatusEffect code="slowness" />

移動速度が`(amplifier + 1) * 15`%下がる。

強さ6で移動速度の低下率が100%を超え移動速度が0になる。
ただしジャンプによりわずかに移動できる。

<LineChart effect="slowness" />

### 勤勉 (採掘速度上昇)

<StatusEffect code="haste" />

採掘速度を`level * 20`％上げる。
攻撃速度も上がったように見えるが実質的な変化はなし。

### 疲労 (採掘速度低下)

<StatusEffect code="mining_fatigue" />

採掘速度が`0.3**level`倍になる。

乗算ではなく**累乗**であることに注意。1未満の累乗なので強さごとに値が小さくなる。
わずか強さ3で元の採掘速度の0.81%(100倍以上時間がかかる)になり、ほぼ採掘ができない状態になる。

<LineChart effect="miningFatigue" />

### 力 (攻撃力上昇)

<StatusEffect code="strength" />

近接攻撃にダメージが追加されます。
弓矢での攻撃は間接攻撃なのでこの効果は受けません。
トライデントの場合、直接攻撃すると効果を受け、投げた場合は効果を受けません。

#### 計算式

「攻撃力上昇」によるダメージ量は次のような関数によって**再帰的**に計算されます。
`damage(x) = floor(damage(x - 1) * 1.3 + 1)`

```javascript
function damage(amplifier) {
  // x = amplifier(強さ)が-1の場合は基本攻撃力を入れる
  if (amplifier == -1) {
    // 素手の場合は2。武器を持っていると異なる
    return 2;
  }
  // この部分のように内部に自分自身の関数を持つ関数を再帰関数と呼ぶ
  return Math.floor(damage(amplifier - 1) * 1.3 + 1);
}
```

```javascript
// xは効果の強さ(amplifier)
// damege(-1)の場合は初期攻撃力2(素手の場合)を入れる
damage(0) = floor(damage(0 - 1) * 1.3 + 1)
          = floor(damage(-1) * 1.3 + 1)
          = floor(2 * 1.3 + 1)
          = floor(2.6 + 1)
          = floor(3.6) // floorは小数点以下切り捨て
          = 3

// 上の計算からdamage(0) = 3 なので
damage(1) = floor(damage(0) * 1.3 + 1)
          = floor(3 * 1.3 + 1)
          = 4

// 以降同じようにして計算していく
damage(2) = floor(damage(1) * 1.3 + 1)
          = 6
```

計算式の一部に掛け算(`* 1.3`)が混じっているので、強さが大きくなるほどに、その上昇率も大きくなっていきます。

最初のダメージ量は小さく、強さ6の時点でようやくゾンビのHP20を超えます。しかし、その約3倍の強さ19になればウィザーのHP600を超えてしまうほど強くなります。

<LineChart effect="strength" />

#### 処理上限

ダメージには処理上限があります。
ダメージがおおよそ300万を超えるとダメージ処理がされなくなり、逆にダメージを与えられなくなってしまいます。

素手の場合だと強さ52でこの処理上限を超えるようで、ダメージが無くなってしまいます。(51までは有効)
上の計算式から強い武器を持っているほど、この上限を超える強さが小さくなります。

このため、`/effect`の中でも「力(`strength`)」だけは強さ(`amplifier`)に事実上の上限があります。これ以外は255まで入力してもエラー・不具合は起きません。

いずれにしても、最強ボスのウィザーが600ダメージで倒せる世界では、何万ダメージも出す必要はありません。通常は上の表の範囲である20以下で扱いましょう。

ちなみに計算上は強さ100でダメージが1兆を超え、255で50穣<small>(万・億・兆・京・垓・𥝱・穣)</small>に達します。もし処理上限を無しにしてしまうと、このように意味もなく膨大な数字を計算することになってしまうので、300万程度で処理を意図的に止めていると考えられます。<small className="text-muted">(上限があるのはいいけどエラーの表示くらいは出して欲しい)</small>

<LineChart effect="strength2" />

### 回復 (即時回復)

<StatusEffect code="instant_health" />

体力を瞬時に回復させる。

アンデッドはダメージを受ける。

### ダメージ (即時ダメージ)

<StatusEffect code="instant_damage" />

瞬時にダメージを与える。

アンデッドは回復する。

即時回復の逆。

### 跳躍 (跳躍力上昇)

<StatusEffect code="jump_boost" />

強さに合わせて落下ダメージを減らします。落下ダメージが減る量よりも落下ダメージが増える割合の方が大きいので、強すぎると落下ダメージを受けるようになります。対策無しなら強さ15でダメージを受け始め、強さ33で即死(ダメージ20)します。

JEとBEで計算方法が違うらしく、公式Wikiの計算式と実測値が一致しない。
詳しい計算式がわからないので、実測値をそのままグラフにしておく。

<small className="text-muted">形がいびつなのは、小数点以下の値を考慮していないため。</small>

<LineChart effect="jumpBoost" />
<LineChart effect="jumpBoost2" />

以下は、上のデータから等差数列を作り増加量を調べたもの。
弱いほど増加率が高く、強くなるほど鈍ることがわかる。

<LineChart effect="jumpBoost3" />

### 目まい (吐き気)

<StatusEffect code="nausea" />

画面が歪む。
最初の2秒で次第に歪みが大きくなり、最後の2秒で次第に歪みが小さくなる。
強さによって歪みは大きくならなず、0~255で同じです。

### 再生 (再生能力)

<StatusEffect code="regeneration" />

`50 / 2**amplifier`ティック毎に1回復。
強さでは回復速度が早くなるだけで回復量は増えない。
強さ5で最小の1ティックごとの回復になり、上限に達する。

<LineChart effect="regeneration" />

### 耐性

<StatusEffect code="resistance" />

受けるダメージを減らします。
強さ5で一切のダメージを受けない無敵状態になります。

### 耐火 (火炎耐性)

<StatusEffect code="fire_resistance" />

火によるダメージを**無効化**します。

強さによる差はなく、強さ0から完全に無効化します。

### 水中呼吸

<StatusEffect code="water_breathing" />

正確にはエンティティが窒息しなくなる効果です。
プレイヤー・陸上モブが水中で呼吸できるようになるだけでなく、魚などの**水中モブが陸上で呼吸できる**ようになります。

### 不可視 (透明化)

<StatusEffect code="invisibility" />

見た目上は全く見えなくなります。ただし装備やパーティクルは見えます。強さによる変化はありません。

プレイヤー同士で見えなくなるだけでなく、敵モブからも発見されにくくなります。
プレイヤーは防具を1つ装備するごとに、敵モブにから見つかる可能性が上がります。また攻撃すると気付かれます。
このようにモブから完全に探知されなくなるわけではないので注意してください。

コマンドで使う場合は、`[hideParticle]`を`true`にして使うとパーティクルを隠せるのでより効果的になります。

### 目つぶし (盲目)

<StatusEffect code="blindness" />

プレイヤーを黒い霧でつつみ視界が悪くなります。またダッシュとクリティカル攻撃ができなくなります。

### 暗視

<StatusEffect code="night_vision" />

暗い場所や水中でもよく見えるようになります。強さによる変化はありません。

### 空腹

<StatusEffect code="hunger" />

1tickごとに`level * 0.005`満腹度が減る。
プレイヤー以外にも付与自体はされるが満腹度がないので無意味。

### 弱体化

<StatusEffect code="weakness" />

攻撃力が減少します。

攻撃力が0になると攻撃が当たらずノックバックも発生しません。

### 毒

<StatusEffect code="poison" />

時間と共にダメージを受けます。ただし死ぬことはありません。

レベルごとにダメージを受ける間隔が小さくなり強さ4で上限に達します。
無敵時間があるので正確な計算は難しい。

ボス・アンデッド・クモは無効。

### 致死毒

<StatusEffect code="fatal_poison" />

毒と同じで時間と共にダメージを受けますが、こちらはHP0になると死にます。死ぬ以外は毒とまったく同じです。

オウムにクッキーを与えた場合にのみ発生する特殊なステータス異常です。<small className="text-muted">(Minecraftのクッキーはカカオを材料に作るチョコクッキーです。チョコレートの主原料であるカカオに実際のオウムにとって毒となる成分が含まれています。)</small>

ボス・クモは無効。
毒と異なりアンデッドには有効。

### ウィザー (衰弱)

<StatusEffect code="wither" />

基本は致死毒と同じで、時間と共にダメージを受け、HP0になり死ぬ可能性があります。
こちらはHPゲージの色が変わり見づらくなりますが、毒よりもダメージ間隔が少し長いのでダメージ量は少なくなっています。

ウィザー・ウィザースケルトン・エンダードラゴンは無効。

<LineChart effect="poison" />

### HPブースト (体力増強)

<StatusEffect code="health_boost" />

最大HPを`level * 4`増加させます。
サバイバルでは発生しないコマンド専用のスタータス効果です。

特に上限は無いので強さ上限の255\*4の1020HP増やすことができます。
ただし増えた分だけ画面がHPバーで埋め尽くされるので非常に見づらくなります。

<LineChart effect="healthBoost" />

### 吸収 (衝撃吸収)

<StatusEffect code="absorption" />

`level * 4`分のHPを追加します。ただし追加分は回復しません。
つまり一定ダメージを無効化する効果となります。

強さ3の+16が上限です。

<LineChart effect="absorption" />

### 飽和 (満腹度回復)

<StatusEffect code="saturation" />

満腹度を即座に回復します。

### 浮遊

<StatusEffect code="levitation" />

エンティティを強制的に浮遊させます。
1秒間に`level * 0.9`ブロック上昇する。

ほとんどの場合で落下ダメージを受けるため基本的には悪い効果とみなされますが使い方次第です。

ボスとシュルカーは無効。

### 低速落下 (落下速度低下)

<StatusEffect code="slow_falling" />

ゆっくりと落ちることで落下ダメージを無効化します。
強さによる変化はありません。

### コンジットパワー

<StatusEffect code="conduit_power" />

強さを上げると採掘速度が上がります。
暗視・水中呼吸は強さによる変化は元々ありません。

### 凶兆

<StatusEffect code="bad_omen" />

村で襲撃イベントが発生するようになる。

モブにも付けることもできますが、プレイヤー以外は発動できないので無意味です。

### 村の英雄

<StatusEffect code="village_hero" />

村での取引で割引を受けることができます。
レベルが上がるほど割引率が高くなります。


/effect

/effect - ステータス効果を与える


プレイヤーの<R t="experience">経験値</R>・レベルを操作するコマンドです。

`/experience`は短縮形として`/xp`が用意されています。
特別な理由がない限りはこちらの短縮形で構いません。

## 経験値を操作する

`/xp <経験値量> [誰に]`

指定できる経験値の範囲は0~2147483647(2^15-1)です。
負(マイナス)の経験値を与えることはできません。

```bash
# 経験値を10与える
/xp 10 @s
# エラー: 負(マイナス)の経験値は与えられない
/xp -10 @s
```

## レベルを操作する

レベルの場合は数字の後に`L`を付けるだけです。
また、マイナス記号をつけることでレベルを減らすことができます。

指定できるレベルの範囲は、経験値と同じで0~2147483647(2^15-1)です。
ただし、レベルとして残る範囲は0~24791です。

`/xp <レベル数>L [誰に]`

```bash
# レベルを10増やす
/xp 10L @s
# レベルを10減らす
/xp -10L @s
```

## レベル判定

各プレイヤーのレベル状況はターゲットセレクタで判定できます。

```bash
# レベル10以上のプレイヤーを表示
/testfor @a[lm=10]
# レベル5のプレイヤーだけにダイヤモンドの剣を与える。
/give @a[lm=5,l=5] diamond_sword
```

## レベル別総経験値量

以下の表は、そのレベルで持っている経験値量を示しています。
{/* textlint-disable */}
<BarChart
  data={{
    labels: [...Array(40).keys()].map((_, n) => n + 1),
    datasets: [
      {
        label: '合計経験値量',
        data: [
          7, 16, 27, 40, 55, 72, 91, 112, 135, 160, 187, 216, 247, 280, 315,
          352, 394, 441, 493, 550, 612, 679, 751, 828, 910, 997, 1089, 1186,
          1288, 1395, 1507, 1628, 1758, 1897, 2045, 2202, 2368, 2543, 2727, 2920,
        ],
        backgroundColor: 'rgba(0, 125, 125, 0.5)',
      },
    ],
  }}
  options={{ scales: { y: { min: 0 } } }}
/>
{/* textlint-enable */}


/experience(/xp)

/experience - 経験値・レベルを操作する


動物やモンスターなどのエンティティを倒す(<R t="kill">殺す</R>)コマンドです。

## 対象を選んで使う

```bash
# 自分だけを倒す
/kill @s
# すべてのエンティティを倒す
/kill @e
# すべてのプレイヤーを倒す
/kill @a
# プレイヤー以外のエンティティを倒す
/kill @e[type=!player]
# Steve以外を倒す
/kill @e[name=!Steve]
```

コマンドに続けて[ターゲットセレクタ](/target-selector/)で対象を選んで使用します。

<LinkCard slug="target-selector" />

<Note color="amber">
すべてのエンティティ(<code>@e</code>)は「トロッコ」や「防具立て」など生き物では無いものも含むことに注意してください。生き物でないエンティティを含めた場合、そのエンティティは消滅します。
</Note>

## 引数無しで使うと自分になる

```bash
# コマンド実行者を倒す
/kill
# これと同じ
/kill @s
```

引数無しで使うとコマンド実行者が対象になります。普通に使うと自分のことになります。

<Note color="amber">
  コマンドブロックで使うと無効です。（コマンドブロックはエンティティではありません）
</Note>

## 消すコマンドではなく、倒すコマンド

`/kill`はエンティティを消すコマンドではなく、倒すコマンドです。
そのためエンティティを倒した後にアイテムや経験値を落とします。
また、スライム系なら分裂することに注意してください。

落ちているアイテムもエンティティなので`/kill`の影響を受けます。
アイテムの場合、倒すことはできないので、この場合は消えることになります。

```bash
# 落ちているアイテムを消す
/kill @e[type=item]
```

## クリエイティブモードのプレイヤーは倒せない

Bedrock版の場合、クリエイティブモードのプレイヤーを`/kill`で倒すことはできません。(Java版では倒せます)

クリエイティブモードのプレイヤーも対象に含めたい場合はゲームモードを変更しましょう。

```bash
# プレイヤー全員をサバイバルモードにする
/gamemode s @a
# プレイヤー全員を倒す
/kill @a
```


公開サーバーにアップロードしなくても使える

この章の記事

プラグインの開発環境を整える

【PaperMC】自分のPCでサーバーを動かす

【PaperMC】最初のプラグインの作り方

プラグインの基本