Minecraft Kotlinプラグイン開発 番外編 plugin.ymlの高度な編集

## 初めに
今回は番外編ということで、
何かを"**作る**"訳ではなく、プラグインを作るときに役立つ情報をまとめたいと思います。

一度この記事を通しで読むことで、
視野が広がり、自分の力で作るときに役立つと思うので一度通して読んでみてください！
また番外編はプラグインを自分で作るときに、一緒に読むのがオススメです。

今回の記事では初級編Part.4で軽く触った`plugin.yml`を編集していきます。

また、コマンド追加の部分も話しますが、その中でも権限の部分は使うことが多いので
忘れないようにしっかり覚えましょう！

**前** → [入門編 Part.4 簡易的なコマンドの作成](https://qiita.com/tooooowa/items/b02d0f06bdacb637c060)
**次** → [中級編 Part.1 コマンドの引数の設定](https://qiita.com/tooooowa/items/e823499575c6500f2ab5)

**目次** →  [目次と今後の展望](https://qiita.com/tooooowa/items/7809ec65dee757570250)

## お知らせ
本編へ入る前に少しお知らせです。
プラグイン開発用のDiscordサーバーを作成しました。
今までの工程で困った点があった際は、
そこで聞いてくれれば返信が可能なので
もし分からない部分があったらこちらで質問してください↓

https://discord.gg/3NEN5s5gnG

## plugin.yml
`plugin.yml`は一番上のフォルダから見て、`src`→`main`→`resources`の中に入っています。
ここに入ってる`plugin.yml`というファイルを今回は触っていきます。

## 目次(まとめ)
| 名前 | 説明 |
|:-|:-|
| [**必須項目**](#必須項目) | ↓ ここから下は必須項目です |
| [main](#main) | プラグインのクラスを指す (自動生成から変更不要) |
| [name](#name) | プラグインの名前 |
| [version](#version) | プラグインのバージョン |
| [**オプション**](#オプション) | ↓ ここから下は自由項目です |
| [description](#description) | プラグインの説明 |
| [api-version](#api-version) | APIのバージョン |
| [load](#load) | プラグインの読み込みタイミング |
| [author](#author) | プラグインの作者 |
| [authors](#authors) | プラグインの作者(複数人) |
| [website](#website) | プラグイン、作者のウェブサイト |
| [prefix](#prefix) | コンソールでのプラグインの名前 |
| [depend](#depend) | 依存プラグイン |
| [softdepend](#softdepend) | 軽依存プラグイン |
| [loadbefore](#loadbefore) | プラグインの後にロード必要なプラグインのリスト |
| [libraries](#libraries) | 外部ライブラリ |
| [command](#command) | コマンド |
| [permission](#permission) | 権限 (パーミッション) |
| [**コマンド属性**](#コマンド属性) | ↓ ここから下はコマンド属性です |
| [description](#descriptionコマンド) | コマンドの説明 |
| [usage](#usage) | コマンドの使用方法 |
| [aliases](#aliases) | コマンドの別名 |
| [permission](#permissionコマンド) | コマンドの権限 |
| [permission-message](#permission-message) | 権限がない際のエラー |
| [**権限**](#権限) | ↓ ここから下は権限です |
| [description](#description権限) | 権限の説明 |
| [default](#default) | デフォルトの権限の有無 |
| [children](#children) | 子権限の設定 |

## 必須項目
### main
プラグインのメインクラスを指します。
自動生成されるものから変更する必要はありません。
むしろ、変更すると動かなくなる可能性があるので注意してください。
### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin # ← ここ
```
---

### name
プラグインの名前です。
すべての英数字とアンダーバー (az, AZ, 0~9, _) のみ使用可能です。
### 例文
```plugin.yml
name: TutorialPlugin # ← ここ
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
```
---

### version
プラグインのバージョンです。
自動生成では`'${version}'`と書いており、
`build.gradle` の `version = '1.0-SNAPSHOT'` と書かれている場所から
ビルド時に自動で記述されます。
なのでバージョン変更時は`build.gradle`を変更するのがおすすめです。
### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}' # ← ここ
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
```
## オプション
### description
プラグインの機能についての説明文です。
`/version プラグイン名` で表示されます。
(あまり読まれることは無いです...)

複数行、カラーコードにも対応しています。
カラーコードは`§` + `英数字`で使えます。
改行は最初に`|`を入れて書きます。(例文参照)
↓ **カラーコード一覧サイト**

https://minecraft.fandom.com/ja/wiki/%E8%A3%85%E9%A3%BE%E3%82%B3%E3%83%BC%E3%83%89
### 例文① (1行)
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
description: "§eチュートリアル用のプラグインです。"
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3682428/9c8496b7-a027-a206-b741-71a040be9851.png)
### 例文② (2行)
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
description: |  # ← ここから下
  チュートリアルのプラグインです。
  §2aaaaa
  §6§ltest！
```
![description2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3682428/d00f4387-8562-3705-b54e-e5d9996f75ce.png)
---

### api-version
使用するAPIのバージョンです。
現在は `1.13` `1.14` `1.15` `1.16` `1.17` `1.18` `1.19` `1.20` が使用可能です
基本的には`1.20.2`だったら`1.20`のように小さい数を消したやつを選べばいいです。
`1.13`以下の場合は1.13を選びましょう。

また、`IntelliJ IDEA` ではこちらも自動入力されるので基本的には変更不要です。
### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
api-version: '1.20' # ← ここ
```
---

### load
プラグインの読み込みタイミングです。
指定しない場合は、デフォルトで `POSTWORLD` が使用されます。
Bukkit起動直後に読み込まれる`STARTUP` と
ワールド読み込み後に読み込まれる`POSTWORLD`が指定可能です。
(ほぼ使いません)
### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
load: POSTWORLD # ← ここ
```
---

### author
プラグインの作者です。
`description`と同じく`/version プラグイン名`で表示されます。
### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
author: abcde # ← ここ
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3682428/075395af-bef7-120d-f860-ee499a0e8588.png)
---

### authors
プラグインの作者です。(複数人用)
`description`と同じく`/version プラグイン名`で表示されます。
### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
authors: [abcde, 12345, ABCDE] # ← ここ
```
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3682428/45e855a0-e9b2-50a8-84b0-c71dff423584.png)
---

### website
プラグイン、もしくは作者のウェブサイトのURLを書きます。
`description`と同じく`/version プラグイン名`で表示されます。
### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
website: www.spigotmc.org # ← ここ
```
---

### prefix
プラグイン名の代わりでコンソールログの前に付く文字列。
### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
prefix: Tutorial # ← ここ
```
---

### depend
プラグインの読み込みに必要なプラグインのリストです。
ここに書かれてるプラグインが読み込まれていない場合、
プラグインは読み込まれません。

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
depend: [WorldEdit, Towny] # ← ここ
```
---

### softdepend
プラグインの完全な読み込みに必要なプラグインのリストです。
プラグインは、ここに書かれているプラ​​グインの後に読み込まれます。

`depend`とは違いここに書かれているプラグインが読み込まれていなくても読み込まれます。
### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
softdepend: [Essentials, AnotherPlugin] # ← ここ
```
---

### loadbefore
プラグインの後にロードする必要があるプラグインのリストです。
プラグインは、ここに書かれているプラ​​グインの前に読み込まれます。
### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
loadbefore: [OnePlugin, AnotherPlugin] # ← ここ
```
---

### libraries
プラグインに必要な、`Maven Central` からロードできるライブラリのリストです。
プラグインのサイズを軽減できます。
プラグインは、ここに書かれているプラ​​グインの前に読み込まれます。

:::note warn
`libraries` はまだテスト段階の機能です
:::


### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
libraries: # ← ここから下
  - com.squareup.okhttp3:okhttp:4.9.0
```
---

### command
プラグインが登録したいコマンドの名前と、コマンド属性のリスト。
コマンド属性に関しては[**コマンド属性**](#コマンド属性)をご覧ください。

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
commands: # ← ここから下
  hello:
    [コマンド属性]
```
---

### permission
プラグインが使用する権限です。
権限に関して詳しくは[**権限**](#権限)をご覧ください。

ここで権限を登録すると、説明、デフォルト、親子関係を設定できます。
権限名は、<プラグイン名>.[カテゴリ].[カテゴリ].<権限> の形で書きます。

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
permissions: # ← ここから下
  tutorialplugin.*: # ← 権限名
    [権限のオプション]
  tutorialplugin.command.debug:
    [権限のオプション]
```

## コマンド属性
### description(コマンド)
コマンドの短い説明です。
/help のコマンド説明に書かれます。

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
commands:
  debug:
    description: こんにちはとメッセージを返すコマンドです。 # ← ここ
```
---
### usage
コマンドの短い簡単な使い方です。
コマンドでは基本的に`return true`でコマンドのコードが終わりますが、
この `true` が `false` の際に表示されます。

例文の `<command>` は自動でコマンド名に置き換えられます。

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
commands:
  debug:
    usage: "使用方法: /<command> [hello|good]"
```
---
### aliases
コマンドの別名です。
`/teleport` が `/tp` でも使えるのと同じで、全く同じ動作をします。

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
commands:
  debug:
    aliases: [tutorialdebug, tdebug] # ← ここ
```
---
### permission(コマンド)
コマンドを使用するために必要な権限です。
ここにある権限をプレイヤーが持っていない場合、コマンドは実行できません。

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
commands:
  debug:
    permission: tutorialplugin.commands.debug # ← ここ
```
---
### permission-message
上の`permission`を持っていない人がコマンドを実行したときに出るエラーメッセージです。
ここにある権限をプレイヤーが持っていない場合、コマンドは実行できません。

また、ここを以下のように空欄にした場合、デフォルトのエラーメッセージになります。
`permission-message: ""`

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
commands:
  debug:
    permission-message: あなたはこのコマンドを使う権限がありません # ← ここ
```

## 権限
### description(権限)
この権限の説明を簡単にここに書きます。
(どこからこれを見ることが出来るのか分かりません。)

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
permissions:
  tutorialplugin.commands.debug:
    description: /debugコマンドを使うために必要な権限です。 # ← ここ
```
---
### default
権限のデフォルト値を設定します。
使用できるのは以下の4つです。
- `true` 全員デフォルトで権限が有効
- `false` 全員デフォルトで権限が無効
- `op` OP所持者のみ有効
- `not op` OP所持してない人全員が有効

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
permissions:
  tutorialplugin.commands.debug:
    default: true # ← ここ
```
---
### children
この権限が有効なとき一緒に有効、無効になる権限を設定します。

例では `tutorialplugin.admin` が有効の時、`tutorialplugin.commands.debug` が有効になり
`tutorialplugin.citizen` は無効になります。

### 例文
```plugin.yml
name: TutorialPlugin
version: '${version}'
main: com.github.tooooowa.tutorialplugin.TutorialPlugin
permissions:
  tutorialplugin.admin:
    children: # ← ここから下
      tutorialplugin.commands.debug: true
      tutorialplugin.citizen: false
```

## 終わりに
これで、`plugin.yml` の設定解説は終わりです。

前回、初級編が終わったので
次回から、中級編としてプラグイン開発でより詳しいところまでいじっていきます。
中級編Part.1では、初級編のプラグインを色々カスタマイズしていきます。
それではまた次回。お疲れ様でした！

**前** → [入門編 Part.4 簡易的なコマンドの作成](https://qiita.com/tooooowa/items/b02d0f06bdacb637c060)  
**次** → [中級編 Part.1 コマンドの引数の設定](https://qiita.com/tooooowa/items/e823499575c6500f2ab5)

**目次** →  [目次と今後の展望](https://qiita.com/tooooowa/items/7809ec65dee757570250)


## 参考
[https://www.spigotmc.org/wiki/plugin-yml/](https://www.spigotmc.org/wiki/plugin-yml/)
[https://mcmodding.jp/modding/index.php/Plugin.yml%E3%81%AE%E8%A8%AD%E5%AE%9A%E4%B8%80%E8%A6%A7](https://mcmodding.jp/modding/index.php/Plugin.yml%E3%81%AE%E8%A8%AD%E5%AE%9A%E4%B8%80%E8%A6%A7)
[https://zenn.dev/gekal/articles/yaml-multi-lines-string](https://zenn.dev/gekal/articles/yaml-multi-lines-string)