Plugin YAML/de

Wenn Bukkit ein Plugin lädt, dann braucht es einige grundlegende Infos über dieses. Es liest die Infos aus einer YAML-Datei aus, "plugin.yml". Diese Datei besteht aus eine Reihe von Attributen, jedes Einzelne wird in einer neuen Zeile und ohne Einrückung definiert.

Attribute

Attribut	Erforderlich	Beschreibung	Beispiel	Anmerkungen
name	ja	Der Name des Plugins.	name: MyPlugin	Darf nur aus alphanumerischen Zeichen und Unterzeichen bestehen (a-z,A-Z,0-9, _) Wird benutzt um den Namen des Plugin-Ordners festzulegen. Der Plugin-Ordner wird standardmäßig in ./plugins/* erstellt. Es ist von Vorteil wenn die .jar-Datei denselben Namen wie das Plugin selbst hat, z. B. "MyPlugin.jar"
version	ja	Die Version des Plugins.	version: 1.4.1	Die Version ist eine beliebige Zahlenfolge, allerdings ist das übliche Format ist "Hauptversion.Unterversion.Build" (z. B.: 1.4.1). Typischerweise erhöhst Du die Version jedes Mal, wenn Du eine neue Funktion oder eine Fehlerbehebung (Bug-Fix) vorgenommen hast. Wird angezeigt, wenn ein Benutzer schreibt /version PluginName
description	nein	Ein kurzer, aussagekräftiger Überblick, der die Funktionen des Plugins beschreibt.	description: This plugin is so 31337. You can set yourself on fire.	Die Beschreibung kann aus mehreren Zeilen bestehen. Wird angezeigt, wenn ein Benutzer schreibt /version PluginName
load	nein	Ausdrückliche Angabe, wann das Plugin geladen werden soll; wenn nichts angegeben, POSTWORLD (Standard).	load: STARTUP	Hat zwei mögliche Werte STARTUP POSTWORLD
author	nein	Gibt eindeutig an, wer dieses Plugin entwickelt hat.	author: CaptainInflamo	Anerkennen des Entwicklers. Wird in manchen Fehlermeldungen angezeigt, um Ansprechpartner im Falle eines Fehlers zu ermitteln. Es wird empfohlen, ein Link zum Plugin-Thread auf bukkit.org oder eine E-Mail-Adresse anzugeben. Wird angezeigt, wenn ein Benutzer schreibt /version PluginName
authors	nein	Wenn mehrere Entwickler mitgearbeitet haben, können diese hier gelistet werden.	authors: [Cogito, verrier, EvilSeph]	Es können sowohl author als auch authors definiert werden, jedoch werden diese in eine Liste zusammengefügt.
website	nein	Die Webseite des Plugin bzw. des Entwicklers.	website: http://forums.bukkit.org/threads/MyPlugin.31337/	Sollte keine Webseite vorhanden sein wird empfohlen, einen Link zum Bukkit-Forumbeitrag des Plugins einzutragen. Wird angezeigt, wenn ein Benutzer schreibt /version PluginName
main	ja	Referenziert die Java-Klasse, die JavaPlugin (oder Implementation dieser) erweitert (extends)	main: org.bukkit.plugin.MyPlugin	Muss den gesamten Namensraum (Namespace) inklussive Klasse-Datei selbst beinhalten Wenn der Namensraum org.bukkit.plugin ist und die Klassen-Datei MyPlugin ergibt sich daraus org.bukkit.plugin.MyPlugin
database	nein	true, wenn dieses Plugin eine Datenbank nutzt.	database: false	Die Verwendung einer Datenbank ist nicht einfach. Mehr hier: [wiki: Plugin_Databases]
depend	nein	Eine Liste von Plugins, die dein Plugin benötigt.	depend: [OnePlugin, AnotherPlugin]	Muss dem YAML-Listen-Format entsprechen (Siehe: http://en.wikipedia.org/wiki/YAML#Lists) Nutze das "name" Attribut des benötigten Plugins. um es zu spezifizieren. Falls ein gelistetes Plugin nicht gefunden wird, wird deins nicht geladen.
softdepend	nein	Eine Liste von Plugins die dein Plugins zur vollen Funktionalität erweitern.	softdepend: [OnePlugin, AnotherPlugin]	Muss dem YAML-Listen-Format entsprechen (Siehe: http://en.wikipedia.org/wiki/YAML#Lists) Nutze das "name" Attribut des benötigten Plugins um es zu spezifizieren Wenn die hier gelisteten Plugins gefunden werden, laden sie vor deinem Plugin. Wird eines nicht gefunden, wird dein Plugin als eines der letzten Plugins geladen.
loadbefore	nein	Eine Liste von Plugins, die dein Plugin zur vollen Funktionalität benötigen.	loadbefore: [ThirdPlugin, LastPlugin]	Ähnlich wie softdepend, nur aus umgedrehter Sicht. Muss dem YAML-Listen-Format entsprechen (Siehe: http://en.wikipedia.org/wiki/YAML#Lists) Nutze das "name" Attribut des abhängigen Plugins, um es zu spezifizieren Wenn die hier gelisteten Plugins gefunden werden, werden sie nach deinem Plugin geladen.
prefix	nein	Definiert den Präfix, der im Logging System des Plugins verwendet wird.	prefix: OwnPlugin	Bei Nicht-Angabe wird die Angabe aus name verwendet.
default-permission	nein	Standard Berechtigung für das Plugin	default-permission: admin	Wird von Bukkit direkt nicht ausgewertet. Kann von Plugins verwendet werden. Liste der möglichen Werte: true, false, op, isop, operator, isoperator, admin, isadmin, !op, notop, !operator, notoperator, !admin, notadmin
class-loader-of	nein	Wurde als veraltet markiert und wird von Bukkit direkt nicht mehr verwendet.
commands	nein	Der Name eines Kommandos, der vom Plugin registriert werden soll und eine optionelle Liste an Kommandoattributen.	commands: flagrate: [optional command attributes]	Der Kommandoname sollte aufgrund eines Fehlers nicht mit "/" starten. Du kannst den Kommandonamen deines Wunsches nehmen, jedoch sind 'übliche' Kommandos wie /kick oft schon registriert. Nutze das 'alias'-Attribut um alternative Namen anzugeben. @TODO: prüfen, ob wir damit zufrieden sind.
permissions	nein	Berechtigungen, die das Plugin registrieren will. Jeder node steht für eine Berechtigung. Jede Berechtigung kann weitere Attribute besitzen.	permissions: inferno.*: [optional permission attributes] inferno.flagate: [optional permission attributes] inferno.burningdeaths: [optional permission attributes]	Berechtigungsregistration ist optional, es lässt sich auch im Code machen. Mit der Berechtigungsregistration kannst Du Beschreibungen, Standardwerte, und Erbschaften festlegen. Berechtigungsnamen sollten im Stil von <Pluginname>.[Kategorie].[Kategorie].<Berechtigung> vergeben werden.

Eine Befehlsblock beginnt mit dem Namen des Befehls Namen und dann mit einer Liste von Attributen.

Befehls Attribut	Erforderlich	Beschreibung	Beispiel	Anmerkungen
description	nein	Eine kurze Beschreibung was der Command tut.	description: Set yourself on fire	Kann in Verbindung mit /help benutzt werden.
aliases	nein	Alternativer Command Alias, der benutzt wird wenn der Command-Name bereits vergeben ist.	aliases: combust_me OR aliases: [combust_me, combustMe]	Es kann keiner, einer oder mehrere Aliases definiert werden. Wenn mehr als ein Alias definiert wurde, muss das YAML Listen Format verwendet werden (Siehe: http://en.wikipedia.org/wiki/YAML#Lists)
permission	nein	The most basic permission node required to use the command	permission: inferno.flagrate	This permissions node can be used to determine if a user should be able to see this command Some plugins will use this node to construct a personalised /help
usage	nein	Eine kurze Beschreibung, wie dieser Command benutzt wird.	usage: Syntax error! Perhaps you meant /<command> PlayerName?	Displayed to whoever issued the command when the plugin's command handler (onCommand typically) does not return true. <command> is a macro that is replaced with the command issued wherever it occurs. To use the string "Usage:" (i.e. usage: Usage: /god [player], surround the text after the usage: label with double-quotes: usage: "Usage: /god [player]"

A permission block starts with the permission's name and is followed by nodes of attributes

Permission Attribut	Erforderlich	Beschreibung	Beispiel	Anmerkungen
description	nein	Eine kurze Beschreibung, was die Permission erlaubt	description: Allows you to set yourself on fire	Erlaubt programmatischen Zugriff und hilft Server-Ad
default	nein	Setze den Standardwert der Permission	default: true	If node does not exist the permission defaults to false Erlaube Werte sind: true, false, op, not op op default will be true if player is op no op default is the opposite behavior (of op)
children	nein	allows you to set children for the permission. Child nodes are permission names	children: inferno.flagrate: true inferno.burningdeaths: true	Each child node must be either set to true or false a child node of true inherits the parent permission a child node of false inherits the inverse parent permission Can also contain other permission nodes {1}

Beispiel:

 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
     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
 
 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