「Plugin.ymlの設定一覧」を編集中


{{warning}} 本ページの原文は http://wiki.bukkit.org/Plugin_YAML にあります。原文は、https://github.com/Bukkit/Bukkit/blob/master/src/main/java/org/bukkit/plugin/PluginDescriptionFile.java のJavadocをwikiに書き直したドキュメントです。本ページは、訳者独自の記述が含まれることをご了承ください。<br />
{{warning}} plugin.ymlにマルチバイトコード（日本語）を使用したい場合は、UTF8N (BOM無し) で保存してください。windows のメモ帳ではBOM無しで保存できないため、日本語を使いたい場合はメモ帳を使用しないでください。また、BukkitDevへの登録など、海外圏での利用を視野に入れている場合は、全て英語で書くようにしてください。<br />
{{warning}} 本項目は、"YAMLの表記方法" までは、深く言及しません。リストやハッシュ、複数行文字列の記載方法は、http://ja.wikipedia.org/wiki/YAML などをご参照ください。

Bukkitがプラグインをロードするとき、Bukkitはプラグインから、プラグインの情報を取得する必要があります。
情報は、YAMLファイル（plugin.yml）から取得されます。

=== plugin.ymlの基本設定一覧 === 
plugin.ymlは、下表に書かれている設定のセットから構成されます。

{| cellspacing="0" cellpadding="4" border="1" class="wikitable"
|+ plugin.ymlの基本設定一覧 
|-
! 設定名 
! 必須かどうか 
! 説明 
! 設定例 
! 備考
|- style="font-weight: bold;"
| name 
| 必須 
| プラグイン名。 
| <code>name: MyPlugin</code> 
| 
*英字、数字、アンダースコア が使用できます(a-z,A-Z,0-9, _)。
*プラグインのデータフォルダは、このname設定により決定されます。./plugins/(name) になります。
*プラグインのjarファイルのファイル名は、name設定と同一にすることが推奨されます。例：'MyPlugin.jar'

|- style="font-weight: bold;"
| version 
| 必須 
| プラグインのバージョン。 
| <code>version: 1.4.1</code> 
| 
*version設定には、任意の文字列が設定可能です。一般的なバージョン標記  MajorRelease.MinorRelease.Build (例：1.4.1) のように設定するといいでしょう。
*新機能を追加したり、バグを修正したら、バージョン番号を上げてください。 
*バージョン情報は、「<code>/version プラグイン名</code>」のコマンドを実行したときに表示されます。

|-
| description 
|  
| プラグインの説明。 
| <code>description: This plugin is so 31337. You can set yourself on fire.</code> 
| 
*プラグインが提供している機能の概要を書いてください。
*複数行文字列で記載することが可能です。 
*説明の情報は、「<code>/version プラグイン名</code>」のコマンドを実行したときに表示されます。

|-
| load
| 
| プラグインの起動タイミング設定。
| <code> load: STARTUP </code>
| 
*プラグインが起動されるタイミングを指定することが可能です。省略した場合は POSTWORLD になります。
*下記の2つが設定可能です。
** STARTUP(Bukkit起動直後)
** POSTWORLD(Bukkitが起動して、ワールドデータのロードが完了した後)
|-
| author 
|  
| 開発者名。 
| <code>author: CaptainInflamo</code> 
| 
*開発者名を書いてください。 
*エラーが発生したときのフィードバック先として表示されます。 フォーラムのハンドル名や、メールアドレスなど、連絡が付くような内容で記載することが望ましいです。 
*開発者名の情報は、「<code>/version プラグイン名</code>」のコマンドを実行したときに表示されます。

|-
| authors 
|  
| 開発者名（複数用）。 
| <code>authors: [Cogito, verrier, EvilSeph]</code> 
| 
*共同制作プロジェクトなどの場合に、複数の開発者名を記載することができます。
*この設定は、YAMLのリスト形式で記載してください。(参考：http://ja.wikipedia.org/wiki/YAML#.E3.83.AA.E3.82.B9.E3.83.88) 
*author設定とauthors設定は、両方指定することも可能です。マージされて、author設定として表示されます。また、この場合、author設定に指定された名前が必ず最初に表示されます。

|-
| website 
|  
| プラグイン開発者のウェブサイト。 
| <code>website: http://forums.bukkit.org/threads/MyPlugin.31337/</code> 
| 
*ウェブサイトを持っていない場合は、プラグインを公開した、フォーラムのスレッドのURLなどを記載すると良いでしょう。
*ウェブサイトの情報は、<code>/version プラグイン名</code> のコマンドを実行したときに表示されます。

|- style="font-weight: bold;"
| main 
| 必須 
| プラグインのメインクラス。 
| <code>main: org.bukkit.plugin.MyPlugin</code> 
| 
*JavaPluginクラスを拡張(extends)した、プラグインのメインクラスを記載してください。 
*パッケージ名を含めた、メインクラスのフルネームで記載してください。 
*例えば、パッケージ名が <code>org.bukkit.plugin</code>で、クラス名が <code>MyPlugin</code> なら、<code>org.bukkit.plugin.MyPlugin</code> と記載してください。

|-
| database 
|  
| データベースを使用するかどうか。 
| <code>database: false</code> 
| 
*プラグインがデータベースを使用する場合は、trueを指定してください。
*省略した場合は falseとみなされます。
*データベースの使用方法についての参考URL：[http://wiki.bukkit.org/Plugin_Databases]

|-
| prefix
| 
| ログの接頭辞
| <code>prefix: ex-why-zee</code>
|
*コンソールに表示されるログの接頭辞を指定します。
*省略した場合、name設定が使用されます。

|-
| depend 
|  
| 依存先プラグインの一覧。 
| <code>depend: [OnePlugin, AnotherPlugin]</code> 
| 
*自分のプラグインを起動するために必要となる、他のプラグインの一覧を記載します。
*この設定は、YAMLのリスト形式で記載してください。(参考：http://ja.wikipedia.org/wiki/YAML#.E3.83.AA.E3.82.B9.E3.83.88) 
*他プラグインの "name" 設定名で、記載してください。 
*ここに設定されたプラグインが見つからない場合は、プラグインの起動でエラーになり、プラグインがdisabledになります。 
*複数のプラグインが互いに依存している場合、双方のプラグインとも、起動に失敗します。
*(See: Wiki: Plugin_Dependencies)

|-
| softdepend 
|  
| 先に起動すべきプラグインの一覧。 
| <code>softdepend: [OnePlugin, AnotherPlugin]</code> 
| 
*自分のプラグインよりも先に起動すべき、他のプラグインの一覧を記載します。
*depend設定と異なるところは、ここに記載されたプラグインが見つからなくても、自分のプラグインは起動失敗にならないところです。
*この設定は、YAMLのリスト形式で記載してください。(参考：http://ja.wikipedia.org/wiki/YAML#.E3.83.AA.E3.82.B9.E3.83.88) 
*他プラグインの "name" 設定名で、記載してください。 
*ここに記載されているプラグインが、自分のプラグインよりも先にロードされるようになります。 
*複数のプラグインがsoftdepend設定で互いに依存していたとしても、プラグインを起動することができます。
*(See: Wiki: Plugin_Dependencies)

|-
| loadbefore 
|  
| 後に起動すべきプラグインの一覧。 
| <code>loadbefore: [OnePlugin, AnotherPlugin]</code> 
| 
*自分のプラグインの後に起動すべき、他のプラグインの一覧を記載します。
*この設定は、YAMLのリスト形式で記載してください。(参考：http://ja.wikipedia.org/wiki/YAML#.E3.83.AA.E3.82.B9.E3.83.88) 
*他プラグインの "name" 設定名で、記載してください。 
*指定したプラグインのsoftdepend設定に、自分のプラグイン名を加える事と、同等の効果を得ることができます。
*ここに記載されているプラグインが、自分のプラグインよりも後にロードされるようになります。 
*複数のプラグインがloadbefore設定で互いに依存していたとしても、プラグインを起動することができます。

|-
| commands 
|  
| プラグインのコマンド一覧。 
| 
<pre>
commands:
  flagrate:
    [optional command attributes]
</pre>

| 
*プラグインのコマンドとして使用したいコマンド名を指定してください。
*<code>[optional command attributes]</code>のところには、YAMLのハッシュ形式で、コマンドのオプション設定を指定できます。オプション設定の詳しい指定内容は、後述の表を参照してください。
*指定するコマンド名は、頭の'/'を抜いた状態で指定してください（例：'/flagrate' → 'commands: flagrate'）。 
*あなたはどのようなコマンドでも登録できますし、既に登録されている<code>/kick</code>のようなコマンドを指定することも可能です。コマンドが重複したときのために、'alias'設定で代わりのコマンド名も指定しておくことを推奨します。（訳者注：要検証、原文の方にも要検証と書かれたままである。）

|-
| permissions 
|  
| プラグインの権限設定一覧。 
| 
<pre>
permissions:
  inferno.*:
    [optional permission attributes]
  inferno.flagate:
    [optional permission attributes]
  inferno.burningdeaths:
    [optional permission attributes]
</pre> 

| 
*プラグインの権限設定として使用したいパーミッションノードを指定してください。
*plugin.ymlでのパーミッションノードの登録は必須ではありません。プラグインのコード上で、同様のことが実施できます。
*plugin.ymlでのパーミッションノードの登録では、権限不足時のメッセージやデフォルト権限設定、権限の親子関係などが設定できます。
*パーミッションノードは、次の形式で記載することをお勧めします。&lt;pluginname&gt;.[category].[category].&lt;permission&gt;

|-
| default-permission 
|  
| デフォルト権限設定。 
| <code>default-permission: NOT_OP</code> 
| 
*プラグインが登録する権限設定のデフォルト権限を指定します。
*省略した場合、defalt-permission: OP と同等です。
*ここに記載された内容は、permission設定ノード以下の権限設定で、"default"設定を省略した項目に適用されます。

|}

=== コマンドのオプション設定 === 
commands設定以下の（[optional command attributes]）部分に記載できる、コマンドのオプション設定一覧

{| cellspacing="0" cellpadding="4" border="1" class="wikitable"
|-
! 設定名 
! 必須かどうか 
! 説明 
! 設定例 
! 備考
|-
| description 
|  
| コマンドの説明文。 
| <code>description: Set yourself on fire</code> 
| 
*コマンドの説明文を記述します。
*<code>/help</code>コマンド実行時に表示されます。

|-
| aliases 
|  
| 代替コマンド名。
| 
 <code>aliases: combust_me</code>
または 
 <code>aliases: [combust_me, combustMe]</code>

| 
*登録しようとしたコマンド名が既に使用されている場合に、代わりのコマンド名として使用できるコマンド名を指定します。
*通常のYAML文字列形式でも、YAMLリスト形式でも、どちらでも指定可能です。

|-
| permission 
|  
| コマンドのパーミッションノード 
| <code>permission: inferno.flagrate</code>
| 
*コマンドを実行するために必要になるパーミッションノードを指定します。
*コマンドを実行した人が、指定のパーミッションノードの権限を持っていない場合、"permission-message"設定のメッセージを表示して、コマンドが実行されないようにすることができます。

|-
| permission-message
|  
| 権限不足時に表示されるメッセージ
| <code>permission-message: You do not have &lt;permission&gt;.</code>
| 
*コマンドを実行しようとした人が、"permission"設定の権限を持っていない場合に、表示されるメッセージです。
*"&lt;permission&gt;" はマクロで、実際にメッセージが表示されるときに、該当のパーミッションノードに置き換えされます。
*空文字列を指定する<pre>permission-message: ''</pre>ことで、本メッセージを非表示にすることが可能です。

|-
| usage 
|  
| コマンドの使用方法説明文。 
| <code>usage: Syntax error! Perhaps you meant /&lt;command&gt; PlayerName?</code> 
| 
*このコマンドのCommandExecutorのonCommandメソッドがfalseを返すときに、表示されるメッセージです。
*"&lt;command&gt;" は実際にメッセージが表示されるときに、指定されたコマンドのラベルで置き換えされます。
*コロンを含む文字列を使用したい場合<ref group="訳注">キーとみなされうまく解析されません。</ref>（例: <code>usage: Usage: /god [player]</code>）、クオートで文字列を囲うようにしてください。<code>usage: "Usage: /god [player]"</code>

|}

=== 権限のオプション設定 === 
permissions設定以下の [optional permission attributes] 部分に記載できる、権限のオプション設定一覧

{| cellspacing="0" cellpadding="4" border="1" class="wikitable"
|-
! 設定名 
! 必須かどうか 
! 説明 
! 設定例 
! 備考
|-
| description 
|  
| 権限の説明文。
| <pre>description: Allows you to set yourself on fire</pre> 
| 
*権限の説明文を記載します。
*サーバー管理者がヘルプコマンドで参照するための文章です。

|-
| default 
|  
| 権限のデフォルト設定。 
| <pre>default: true</pre> 
| 
*権限のデフォルト設定を指定します。
*省略した場合は、"op" が指定されたとみなされます。ただし、"default-permission"設定がある場合は、"default-permission"設定が適用されます。
*指定できる文字列は、true(全員が実行可能)、false(全員が実行不可能)、op(OPのみが使用可能)、not op(OPのみが使用不可能) の4種類です。

|-
| children 
|  
| 子権限の設定。 
| 
<pre>
children:
  inferno.flagrate: true
  inferno.burningdeaths: true
</pre> 
| 
*権限の子となる権限名を指定してください。
*指定できる値は、true、false の2種類です。
**trueを指定した場合、指定した権限を親の権限に含めることになります。
**falseを指定した場合、指定した権限を親の権限から除外することになります。
*訳者註：trueやfalseではなく、子権限の設定をそのまま記載することも、実は可能です。[https://github.com/Bukkit/Bukkit/blob/master/src/main/javadoc/org/bukkit/plugin/doc-files/permissions-example_plugin.yml] ただしこの方法は、インデントが深くなり、親子関係がわかりにくくなるため、あまりお勧めはしません。

|}


=== plugin.yml の記載例 ===

<blockquote><source lang="yaml" style="border: 1px #aaa solid;">
 name: Inferno
 version: 1.4.1
 description: This plugin is so 31337. You can set yourself on fire.
 # We could place every author in the authors list, but chose not to for illustrative purposes
 # Also, having an author distinguishes that person as the project lead, and ensures their 
 # name is displayed first
 author: CaptainInflamo
 authors: [Cogito, verrier, EvilSeph] 
 website: http://forums.bukkit.org/threads/MyPlugin.31337/
 
 main: com.captaininflamo.bukkit.inferno.Inferno
 database: false
 depend: [NewFire, FlameWire]
 
 commands:
   flagrate:
     description: Set yourself on fire.
     aliases: [combust_me, combustMe]
     permission: inferno.flagrate
     usage: Syntax error! Simply type /<command> to ignite yourself.
   burningdeaths:
     description: List how many times you have died by fire.
     aliases: [burning_deaths, burningDeaths]
     permission: inferno.burningdeaths
     permission-message: You do not have <permission>.
     usage: |
       /<command> [player]
       Example: /<command> - see how many times you have burned to death
       Example: /<command> CaptainIce - see how many times CaptainIce has burned to death
 # The next command has no description, aliases, etc. defined, but is still valid
 # Having an empty declaration is useful for defining the description, permission, and messages from a configuration dynamically
   apocalypse:
 
 permissions:
   inferno.*:
     description: Gives access to all Inferno commands
     children:
       inferno.flagrate: true
       inferno.burningdeaths: true
       inferno.burningdeaths.others: true
   inferno.flagrate:
     description: Allows you to ignite yourself
     default: true
   inferno.burningdeaths:
     description: Allows you to see how many times you have burned to death
     default: true
   inferno.burningdeaths.others:
     description: Allows you to see how many times others have burned to death
     default: op
     children:
       inferno.burningdeaths: true
</source></blockquote>