Minecraft插件百科 - 用户贡献 [zh-cn]

Configuration API Reference

2017-08-01T11:46:44Z

Tdiant：/* 默认值 */

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个能够帮助开发者快速解析与编辑配置文件的工具，它让配置文件更简单、更容易读写。无论是什么，这个API可以帮助你更容易的存储你插件的配置信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而这个API被设计有广泛的拓展性，这意味着它允许你实现其他需要实现的东西。

Configuration API存在于 org.bukkit.configuration 和 org.bukkit.configuration.file 这两个包中。如果是创建在 1.1-R5 版本之前的插件，就只能用老版本并且与本文截然不同的API了，这些老版API在老版本的org.bukkit.util.configuration包中。这些内容彼此互不兼容，并且因为老的方法太过时了，所以在新版中已被删去。

本文假定你对面向对象思想、Java与Bukkit插件编写的核心思想有着相当深的了解与认识。本文并非JavaDoc[https://hub.spigotmc.org/javadocs/bukkit/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]的替代品。

（译者注：上方链接因过时，已经替换到了最新的新版链接当中，内容稍微与原文有所不符，但影响不大）

== 基本论述 ==

=== 配置文件对象 ===
当你的插件主类继承 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin] 类时也会继承父类 JavaPlugin 类的方法和属性。在被继承的方法中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 文件。

你的插件在第一次调用''getConfig()''方法时，会从你插件的jar文件中读取相应的''config.yml'' 文件，同时从jar中的''config.yml''文件里加载相应的默认数据。需要注意的是，在第一次使用之后若再次调用''getConfig()''方法，只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的，并且你对这个对象进行的修改并不会被保存，除非你手动保存。同理，在第一次调用''getConfig()''方法之后，对磁盘上的config.yml文件的修改不会被同步给这个对象。如果在 plugins 文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml''文件, 也会加载一个空的''FileConfiguration''对象。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 方法的返回值分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''方法，而不是将其分配给一个变量}}

=== 键 ===

一个配置文件由键值对构成，键是一个字符串。键对应的值可能是一个 ''ConfigurationSection'' 对象或是其他形式的数据. ''getKeys(boolean)'' 方法会返回一个存有当前''FileConfigurationSection''所有键的集合，布尔值决定着是否递归地返回集合，如果值为true，将返回指定部分的所有键与所有对应子键, 如果为false则只会返回指定部分的所有键（不含子键）。若要获取特定部分的所有键，需调用特定部分''ConfigurationSection''对象的 ''getKeys(boolean)'' 方法。你可使用''getConfigurationSection(String)''方法来获取这个部分。

{{warning| getKeys(boolean)方法返回的是一个字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 中使用路径（Path）来构成一个独立的键值对。一个路径是一层层的键的组合，被用来联系所对应的值。每一层都用路径分隔符区分开来，路径分隔符通常是 '.' (段落)。举个例子，下面的YMAL文件有着下面这些组路径。
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的插件jar中应该为用户准备一个默认的''config.yml''文件。当''config.yml''丢失或是不完整的情况发生时，要获取的值将会从jar内的 ''config.yml''文件来获取。被准备的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同目录下。你应该在jar里的''config.yml''里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

如果你想动态的把一对键值作为默认值，你可以利用''addDefault(String, Object)'' 方法和 ''addDefaults(Map<String,Object>)'' 方法。

有时如果你想添加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

你可以使用一堆 getter 方法来获取配置文件中的值。这些 getter 方法你可以在[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html 这里]找到。每个 getter 方法 takes a configuration path detailed above. 一般条件下你应该需要这些 getter 来获取值：

*getBoolean(String) 获取键对应的类型为boolean的值
*getInt(String) 获取键对应的类型为 int 的值
*getString(String) 获取键对应的类型为 String 的值
*getList(String) 获取键对应的类型为 List 的值
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

如果你对一个 ''FileConfiguration'' 对象进行了修改操作，或者改变了某些 ''Lists''，如果你想保存你的修改，让插件被卸载了这些数据也能得以保存的话，你可以把你修改的数据保存到硬盘里。保存文件到硬盘里，你可以借助 saveConfig 方法。这会重写硬盘里的那份配置文件。 <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

如果你怀疑用户在插件数据文件夹里修改了''config.yml''，并且那些数据并没有更新在内存里。你可以用 ''reloadConfig()'' 方法重新读取插件文件夹中最新的配置文件信息，来更新内存中的数据，但这会把你内存中保存的那份数据删除，这可能会让你丢失一部分数据。 <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件来存储其他的配置信息，或储存额外的游戏信息配置文件等，你可以自己写一个你自己的方法，来仿照 <big>JavaPlugin</big> 类里的 getConfig，reloadConfig，saveConfig 方法实现这一目的。下面是一个例子，可以告诉你如何编写一个方法，来读取和保存自定义配置文件。由于这些配置文件属于你的插件，你可以把这个方法放在你的主类，这样用起来跟原来一样。你必须为每个YAML文件写的一套方法。不过你可以使用以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== 序列化与反序列化对象 ===

在 Configuration API 中，上面提及的可以存储的对象均实现（implements）了 ''ConfigurationSerializable'' 接口。对象序列化可以有助我们保存和读取数据，来让插件开发者集中开发插件的其他部分。它真正的使一些任务变得简单明了了，就例如存储一个 ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' 对象到YAML文件当中，开发者可以序列化一个包装类，用以提供取用 ''Location'' 对象的方法。 

Classes, 除了implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

下面是一个使用了新版Configuration API的样例插件，它可以显示MOTD信息给进入服务器的玩家，并且可以让玩家使用指令获取规则（rule）。''此处为了让代码行数达到最佳，代码没有采用适当的风格和插件布局''。

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// 如果没有默认 config.yml 文件，保存一个默认配置副本
this.saveDefaultConfig();

// 注册新的监听器
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// 当玩家进入服务器时发送 config.yml 文件里的信息
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// 给获取规则指令（rules）设置命令执行器（Command Executor）
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// 当指令被执行，发送 config.yml 里的规则信息给输入指令的人
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> 插件jar文件中的默认 config.yml 文件
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Configuration API Reference

2017-08-01T11:42:21Z

Tdiant：/* 路径 */

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个能够帮助开发者快速解析与编辑配置文件的工具，它让配置文件更简单、更容易读写。无论是什么，这个API可以帮助你更容易的存储你插件的配置信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而这个API被设计有广泛的拓展性，这意味着它允许你实现其他需要实现的东西。

Configuration API存在于 org.bukkit.configuration 和 org.bukkit.configuration.file 这两个包中。如果是创建在 1.1-R5 版本之前的插件，就只能用老版本并且与本文截然不同的API了，这些老版API在老版本的org.bukkit.util.configuration包中。这些内容彼此互不兼容，并且因为老的方法太过时了，所以在新版中已被删去。

本文假定你对面向对象思想、Java与Bukkit插件编写的核心思想有着相当深的了解与认识。本文并非JavaDoc[https://hub.spigotmc.org/javadocs/bukkit/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]的替代品。

（译者注：上方链接因过时，已经替换到了最新的新版链接当中，内容稍微与原文有所不符，但影响不大）

== 基本论述 ==

=== 配置文件对象 ===
当你的插件主类继承 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin] 类时也会继承父类 JavaPlugin 类的方法和属性。在被继承的方法中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 文件。

你的插件在第一次调用''getConfig()''方法时，会从你插件的jar文件中读取相应的''config.yml'' 文件，同时从jar中的''config.yml''文件里加载相应的默认数据。需要注意的是，在第一次使用之后若再次调用''getConfig()''方法，只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的，并且你对这个对象进行的修改并不会被保存，除非你手动保存。同理，在第一次调用''getConfig()''方法之后，对磁盘上的config.yml文件的修改不会被同步给这个对象。如果在 plugins 文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml''文件, 也会加载一个空的''FileConfiguration''对象。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 方法的返回值分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''方法，而不是将其分配给一个变量}}

=== 键 ===

一个配置文件由键值对构成，键是一个字符串。键对应的值可能是一个 ''ConfigurationSection'' 对象或是其他形式的数据. ''getKeys(boolean)'' 方法会返回一个存有当前''FileConfigurationSection''所有键的集合，布尔值决定着是否递归地返回集合，如果值为true，将返回指定部分的所有键与所有对应子键, 如果为false则只会返回指定部分的所有键（不含子键）。若要获取特定部分的所有键，需调用特定部分''ConfigurationSection''对象的 ''getKeys(boolean)'' 方法。你可使用''getConfigurationSection(String)''方法来获取这个部分。

{{warning| getKeys(boolean)方法返回的是一个字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 中使用路径（Path）来构成一个独立的键值对。一个路径是一层层的键的组合，被用来联系所对应的值。每一层都用路径分隔符区分开来，路径分隔符通常是 '.' (段落)。举个例子，下面的YMAL文件有着下面这些组路径。
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的插件jar里应该为用户准备一个默认的''config.yml''。当config.yml丢失或是不完整的情况出现时，将会访问jar内的 ''config.yml''来获取默认值。准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录。你应该在jar里的''config.yml''里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

如果你想动态的把一对键值作为默认值，你可以利用''addDefault(String, Object)'' 方法和 ''addDefaults(Map<String,Object>)'' 方法。

在某些情况下，如果你想附加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

你可以使用一堆 getter 方法来获取配置文件中的值。这些 getter 方法你可以在[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html 这里]找到。每个 getter 方法 takes a configuration path detailed above. 一般条件下你应该需要这些 getter 来获取值：

*getBoolean(String) 获取键对应的类型为boolean的值
*getInt(String) 获取键对应的类型为 int 的值
*getString(String) 获取键对应的类型为 String 的值
*getList(String) 获取键对应的类型为 List 的值
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

如果你对一个 ''FileConfiguration'' 对象进行了修改操作，或者改变了某些 ''Lists''，如果你想保存你的修改，让插件被卸载了这些数据也能得以保存的话，你可以把你修改的数据保存到硬盘里。保存文件到硬盘里，你可以借助 saveConfig 方法。这会重写硬盘里的那份配置文件。 <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

如果你怀疑用户在插件数据文件夹里修改了''config.yml''，并且那些数据并没有更新在内存里。你可以用 ''reloadConfig()'' 方法重新读取插件文件夹中最新的配置文件信息，来更新内存中的数据，但这会把你内存中保存的那份数据删除，这可能会让你丢失一部分数据。 <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件来存储其他的配置信息，或储存额外的游戏信息配置文件等，你可以自己写一个你自己的方法，来仿照 <big>JavaPlugin</big> 类里的 getConfig，reloadConfig，saveConfig 方法实现这一目的。下面是一个例子，可以告诉你如何编写一个方法，来读取和保存自定义配置文件。由于这些配置文件属于你的插件，你可以把这个方法放在你的主类，这样用起来跟原来一样。你必须为每个YAML文件写的一套方法。不过你可以使用以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== 序列化与反序列化对象 ===

在 Configuration API 中，上面提及的可以存储的对象均实现（implements）了 ''ConfigurationSerializable'' 接口。对象序列化可以有助我们保存和读取数据，来让插件开发者集中开发插件的其他部分。它真正的使一些任务变得简单明了了，就例如存储一个 ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' 对象到YAML文件当中，开发者可以序列化一个包装类，用以提供取用 ''Location'' 对象的方法。 

Classes, 除了implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

下面是一个使用了新版Configuration API的样例插件，它可以显示MOTD信息给进入服务器的玩家，并且可以让玩家使用指令获取规则（rule）。''此处为了让代码行数达到最佳，代码没有采用适当的风格和插件布局''。

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// 如果没有默认 config.yml 文件，保存一个默认配置副本
this.saveDefaultConfig();

// 注册新的监听器
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// 当玩家进入服务器时发送 config.yml 文件里的信息
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// 给获取规则指令（rules）设置命令执行器（Command Executor）
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// 当指令被执行，发送 config.yml 里的规则信息给输入指令的人
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> 插件jar文件中的默认 config.yml 文件
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Configuration API Reference

2017-08-01T11:32:43Z

Tdiant：更正了“键”部分的译制内容

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个能够帮助开发者快速解析与编辑配置文件的工具，它让配置文件更简单、更容易读写。无论是什么，这个API可以帮助你更容易的存储你插件的配置信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而这个API被设计有广泛的拓展性，这意味着它允许你实现其他需要实现的东西。

Configuration API存在于 org.bukkit.configuration 和 org.bukkit.configuration.file 这两个包中。如果是创建在 1.1-R5 版本之前的插件，就只能用老版本并且与本文截然不同的API了，这些老版API在老版本的org.bukkit.util.configuration包中。这些内容彼此互不兼容，并且因为老的方法太过时了，所以在新版中已被删去。

本文假定你对面向对象思想、Java与Bukkit插件编写的核心思想有着相当深的了解与认识。本文并非JavaDoc[https://hub.spigotmc.org/javadocs/bukkit/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]的替代品。

（译者注：上方链接因过时，已经替换到了最新的新版链接当中，内容稍微与原文有所不符，但影响不大）

== 基本论述 ==

=== 配置文件对象 ===
当你的插件主类继承 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin] 类时也会继承父类 JavaPlugin 类的方法和属性。在被继承的方法中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 文件。

你的插件在第一次调用''getConfig()''方法时，会从你插件的jar文件中读取相应的''config.yml'' 文件，同时从jar中的''config.yml''文件里加载相应的默认数据。需要注意的是，在第一次使用之后若再次调用''getConfig()''方法，只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的，并且你对这个对象进行的修改并不会被保存，除非你手动保存。同理，在第一次调用''getConfig()''方法之后，对磁盘上的config.yml文件的修改不会被同步给这个对象。如果在 plugins 文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml''文件, 也会加载一个空的''FileConfiguration''对象。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 方法的返回值分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''方法，而不是将其分配给一个变量}}

=== 键 ===

一个配置文件由键值对构成，键是一个字符串。键对应的值可能是一个 ''ConfigurationSection'' 对象或是其他形式的数据. ''getKeys(boolean)'' 方法会返回一个存有当前''FileConfigurationSection''所有键的集合，布尔值决定着是否递归地返回集合，如果值为true，将返回指定部分的所有键与所有对应子键, 如果为false则只会返回指定部分的所有键（不含子键）。若要获取特定部分的所有键，需调用特定部分''ConfigurationSection''对象的 ''getKeys(boolean)'' 方法。你可使用''getConfigurationSection(String)''方法来获取这个部分。

{{warning| getKeys(boolean)方法返回的是一个字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的插件jar里应该为用户准备一个默认的''config.yml''。当config.yml丢失或是不完整的情况出现时，将会访问jar内的 ''config.yml''来获取默认值。准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录。你应该在jar里的''config.yml''里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

如果你想动态的把一对键值作为默认值，你可以利用''addDefault(String, Object)'' 方法和 ''addDefaults(Map<String,Object>)'' 方法。

在某些情况下，如果你想附加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

你可以使用一堆 getter 方法来获取配置文件中的值。这些 getter 方法你可以在[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html 这里]找到。每个 getter 方法 takes a configuration path detailed above. 一般条件下你应该需要这些 getter 来获取值：

*getBoolean(String) 获取键对应的类型为boolean的值
*getInt(String) 获取键对应的类型为 int 的值
*getString(String) 获取键对应的类型为 String 的值
*getList(String) 获取键对应的类型为 List 的值
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

如果你对一个 ''FileConfiguration'' 对象进行了修改操作，或者改变了某些 ''Lists''，如果你想保存你的修改，让插件被卸载了这些数据也能得以保存的话，你可以把你修改的数据保存到硬盘里。保存文件到硬盘里，你可以借助 saveConfig 方法。这会重写硬盘里的那份配置文件。 <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

如果你怀疑用户在插件数据文件夹里修改了''config.yml''，并且那些数据并没有更新在内存里。你可以用 ''reloadConfig()'' 方法重新读取插件文件夹中最新的配置文件信息，来更新内存中的数据，但这会把你内存中保存的那份数据删除，这可能会让你丢失一部分数据。 <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件来存储其他的配置信息，或储存额外的游戏信息配置文件等，你可以自己写一个你自己的方法，来仿照 <big>JavaPlugin</big> 类里的 getConfig，reloadConfig，saveConfig 方法实现这一目的。下面是一个例子，可以告诉你如何编写一个方法，来读取和保存自定义配置文件。由于这些配置文件属于你的插件，你可以把这个方法放在你的主类，这样用起来跟原来一样。你必须为每个YAML文件写的一套方法。不过你可以使用以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== 序列化与反序列化对象 ===

在 Configuration API 中，上面提及的可以存储的对象均实现（implements）了 ''ConfigurationSerializable'' 接口。对象序列化可以有助我们保存和读取数据，来让插件开发者集中开发插件的其他部分。它真正的使一些任务变得简单明了了，就例如存储一个 ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' 对象到YAML文件当中，开发者可以序列化一个包装类，用以提供取用 ''Location'' 对象的方法。 

Classes, 除了implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

下面是一个使用了新版Configuration API的样例插件，它可以显示MOTD信息给进入服务器的玩家，并且可以让玩家使用指令获取规则（rule）。''此处为了让代码行数达到最佳，代码没有采用适当的风格和插件布局''。

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// 如果没有默认 config.yml 文件，保存一个默认配置副本
this.saveDefaultConfig();

// 注册新的监听器
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// 当玩家进入服务器时发送 config.yml 文件里的信息
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// 给获取规则指令（rules）设置命令执行器（Command Executor）
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// 当指令被执行，发送 config.yml 里的规则信息给输入指令的人
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> 插件jar文件中的默认 config.yml 文件
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Configuration API Reference

2017-08-01T11:21:10Z

Tdiant：/* Serializing and Deserializing Objects */

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个能够帮助开发者快速解析与编辑配置文件的工具，它让配置文件更简单、更容易读写。无论是什么，这个API可以帮助你更容易的存储你插件的配置信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而这个API被设计有广泛的拓展性，这意味着它允许你实现其他需要实现的东西。

Configuration API存在于 org.bukkit.configuration 和 org.bukkit.configuration.file 这两个包中。如果是创建在 1.1-R5 版本之前的插件，就只能用老版本并且与本文截然不同的API了，这些老版API在老版本的org.bukkit.util.configuration包中。这些内容彼此互不兼容，并且因为老的方法太过时了，所以在新版中已被删去。

本文假定你对面向对象思想、Java与Bukkit插件编写的核心思想有着相当深的了解与认识。本文并非JavaDoc[https://hub.spigotmc.org/javadocs/bukkit/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]的替代品。

（译者注：上方链接因过时，已经替换到了最新的新版链接当中，内容稍微与原文有所不符，但影响不大）

== 基本论述 ==

=== 配置文件对象 ===
<ref>key 键 value 值</ref>
当你的插件主类继承 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin] 类时也会继承父类 JavaPlugin 类的方法和属性。在被继承的方法中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 文件。

你的插件在第一次调用''getConfig()''方法时，会从你插件的jar文件中读取相应的''config.yml'' 文件，同时从jar中的''config.yml''文件里加载相应的默认数据。需要注意的是，在第一次使用之后若再次调用''getConfig()''方法，只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的，并且你对这个对象进行的修改并不会被保存，除非你手动保存。同理，在第一次调用''getConfig()''方法之后，对磁盘上的config.yml文件的修改不会被同步给这个对象。如果在 plugins 文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml''文件, 也会加载一个空的''FileConfiguration''对象。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 方法的返回值分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''方法，而不是将其分配给一个变量}}

=== 键 ===

配置文件由键值组合构成，所有的键都是字符串。值对于其他键来说可能是一个''FileConfigurationSection''或是独立的数据. ''getKeys(boolean)'' 方法会返回现有''FileConfigurationSection''集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, ''getKeys(boolean)'' 方法必须加载在特定节点. 你可以通过''getConfigurationSection(String)''方法来获取这个部分.

{{warning| getKeys(boolean)方法返回的是这里的字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的插件jar里应该为用户准备一个默认的''config.yml''。当config.yml丢失或是不完整的情况出现时，将会访问jar内的 ''config.yml''来获取默认值。准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录。你应该在jar里的''config.yml''里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

如果你想动态的把一对键值作为默认值，你可以利用''addDefault(String, Object)'' 方法和 ''addDefaults(Map<String,Object>)'' 方法。

在某些情况下，如果你想附加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

你可以使用一堆 getter 方法来获取配置文件中的值。这些 getter 方法你可以在[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html 这里]找到。每个 getter 方法 takes a configuration path detailed above. 一般条件下你应该需要这些 getter 来获取值：

*getBoolean(String) 获取键对应的类型为boolean的值
*getInt(String) 获取键对应的类型为 int 的值
*getString(String) 获取键对应的类型为 String 的值
*getList(String) 获取键对应的类型为 List 的值
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

如果你对一个 ''FileConfiguration'' 对象进行了修改操作，或者改变了某些 ''Lists''，如果你想保存你的修改，让插件被卸载了这些数据也能得以保存的话，你可以把你修改的数据保存到硬盘里。保存文件到硬盘里，你可以借助 saveConfig 方法。这会重写硬盘里的那份配置文件。 <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

如果你怀疑用户在插件数据文件夹里修改了''config.yml''，并且那些数据并没有更新在内存里。你可以用 ''reloadConfig()'' 方法重新读取插件文件夹中最新的配置文件信息，来更新内存中的数据，但这会把你内存中保存的那份数据删除，这可能会让你丢失一部分数据。 <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件来存储其他的配置信息，或储存额外的游戏信息配置文件等，你可以自己写一个你自己的方法，来仿照 <big>JavaPlugin</big> 类里的 getConfig，reloadConfig，saveConfig 方法实现这一目的。下面是一个例子，可以告诉你如何编写一个方法，来读取和保存自定义配置文件。由于这些配置文件属于你的插件，你可以把这个方法放在你的主类，这样用起来跟原来一样。你必须为每个YAML文件写的一套方法。不过你可以使用以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== 序列化与反序列化对象 ===

在 Configuration API 中，上面提及的可以存储的对象均实现（implements）了 ''ConfigurationSerializable'' 接口。对象序列化可以有助我们保存和读取数据，来让插件开发者集中开发插件的其他部分。它真正的使一些任务变得简单明了了，就例如存储一个 ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' 对象到YAML文件当中，开发者可以序列化一个包装类，用以提供取用 ''Location'' 对象的方法。 

Classes, 除了implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

下面是一个使用了新版Configuration API的样例插件，它可以显示MOTD信息给进入服务器的玩家，并且可以让玩家使用指令获取规则（rule）。''此处为了让代码行数达到最佳，代码没有采用适当的风格和插件布局''。

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// 如果没有默认 config.yml 文件，保存一个默认配置副本
this.saveDefaultConfig();

// 注册新的监听器
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// 当玩家进入服务器时发送 config.yml 文件里的信息
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// 给获取规则指令（rules）设置命令执行器（Command Executor）
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// 当指令被执行，发送 config.yml 里的规则信息给输入指令的人
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> 插件jar文件中的默认 config.yml 文件
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Configuration API Reference

2017-08-01T11:10:09Z

Tdiant：更正了几处不当错误，做了简单的汉化工作

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个能够帮助开发者快速解析与编辑配置文件的工具，它让配置文件更简单、更容易读写。无论是什么，这个API可以帮助你更容易的存储你插件的配置信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而这个API被设计有广泛的拓展性，这意味着它允许你实现其他需要实现的东西。

Configuration API存在于 org.bukkit.configuration 和 org.bukkit.configuration.file 这两个包中。如果是创建在 1.1-R5 版本之前的插件，就只能用老版本并且与本文截然不同的API了，这些老版API在老版本的org.bukkit.util.configuration包中。这些内容彼此互不兼容，并且因为老的方法太过时了，所以在新版中已被删去。

本文假定你对面向对象思想、Java与Bukkit插件编写的核心思想有着相当深的了解与认识。本文并非JavaDoc[https://hub.spigotmc.org/javadocs/bukkit/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]的替代品。

（译者注：上方链接因过时，已经替换到了最新的新版链接当中，内容稍微与原文有所不符，但影响不大）

== 基本论述 ==

=== 配置文件对象 ===
<ref>key 键 value 值</ref>
当你的插件主类继承 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin] 类时也会继承父类 JavaPlugin 类的方法和属性。在被继承的方法中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 文件。

你的插件在第一次调用''getConfig()''方法时，会从你插件的jar文件中读取相应的''config.yml'' 文件，同时从jar中的''config.yml''文件里加载相应的默认数据。需要注意的是，在第一次使用之后若再次调用''getConfig()''方法，只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的，并且你对这个对象进行的修改并不会被保存，除非你手动保存。同理，在第一次调用''getConfig()''方法之后，对磁盘上的config.yml文件的修改不会被同步给这个对象。如果在 plugins 文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml''文件, 也会加载一个空的''FileConfiguration''对象。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 方法的返回值分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''方法，而不是将其分配给一个变量}}

=== 键 ===

配置文件由键值组合构成，所有的键都是字符串。值对于其他键来说可能是一个''FileConfigurationSection''或是独立的数据. ''getKeys(boolean)'' 方法会返回现有''FileConfigurationSection''集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, ''getKeys(boolean)'' 方法必须加载在特定节点. 你可以通过''getConfigurationSection(String)''方法来获取这个部分.

{{warning| getKeys(boolean)方法返回的是这里的字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的插件jar里应该为用户准备一个默认的''config.yml''。当config.yml丢失或是不完整的情况出现时，将会访问jar内的 ''config.yml''来获取默认值。准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录。你应该在jar里的''config.yml''里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

如果你想动态的把一对键值作为默认值，你可以利用''addDefault(String, Object)'' 方法和 ''addDefaults(Map<String,Object>)'' 方法。

在某些情况下，如果你想附加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

你可以使用一堆 getter 方法来获取配置文件中的值。这些 getter 方法你可以在[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html 这里]找到。每个 getter 方法 takes a configuration path detailed above. 一般条件下你应该需要这些 getter 来获取值：

*getBoolean(String) 获取键对应的类型为boolean的值
*getInt(String) 获取键对应的类型为 int 的值
*getString(String) 获取键对应的类型为 String 的值
*getList(String) 获取键对应的类型为 List 的值
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

如果你对一个 ''FileConfiguration'' 对象进行了修改操作，或者改变了某些 ''Lists''，如果你想保存你的修改，让插件被卸载了这些数据也能得以保存的话，你可以把你修改的数据保存到硬盘里。保存文件到硬盘里，你可以借助 saveConfig 方法。这会重写硬盘里的那份配置文件。 <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

如果你怀疑用户在插件数据文件夹里修改了''config.yml''，并且那些数据并没有更新在内存里。你可以用 ''reloadConfig()'' 方法重新读取插件文件夹中最新的配置文件信息，来更新内存中的数据，但这会把你内存中保存的那份数据删除，这可能会让你丢失一部分数据。 <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件来存储其他的配置信息，或储存额外的游戏信息配置文件等，你可以自己写一个你自己的方法，来仿照 <big>JavaPlugin</big> 类里的 getConfig，reloadConfig，saveConfig 方法实现这一目的。下面是一个例子，可以告诉你如何编写一个方法，来读取和保存自定义配置文件。由于这些配置文件属于你的插件，你可以把这个方法放在你的主类，这样用起来跟原来一样。你必须为每个YAML文件写的一套方法。不过你可以使用以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== Serializing and Deserializing Objects ===

The Configuration API, as mentioned above can store Java objects that implement the ''ConfigurationSerializable'' Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''. 

Classes, in addition to implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

下面是一个使用了新版Configuration API的样例插件，它可以显示MOTD信息给进入服务器的玩家，并且可以让玩家使用指令获取规则（rule）。''此处为了让代码行数达到最佳，代码没有采用适当的风格和插件布局''。

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// 如果没有默认 config.yml 文件，保存一个默认配置副本
this.saveDefaultConfig();

// 注册新的监听器
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// 当玩家进入服务器时发送 config.yml 文件里的信息
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// 给获取规则指令（rules）设置命令执行器（Command Executor）
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// 当指令被执行，发送 config.yml 里的规则信息给输入指令的人
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> 插件jar文件中的默认 config.yml 文件
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Event API Reference/en

2017-08-01T10:41:25Z

Tdiant：/* Video Tutorial */

{{条目原文}}
欢迎来到Bukkit提供的EventAPI相关教程页

== 简介 ==

'''事件''' 就是你在使用CraftBukkit,或者基于CraftBukkit服务端的其他服务端的时候，服务端会将服务器内发生的事告诉正在监听对应事件的插件。CraftBukkit服务端为插件定义了许多不同的事件，比如玩家登录服务器，玩家进入服务器，玩家点击方块，玩家重生。还有一些可以被取消的事件例如，玩家放置方块，玩家破坏方块，等等。更还有区块卸载区块装载，实体等相关事件。具体请查看API文档:
BukkitAPI:https://hub.spigotmc.org/javadocs/bukkit
SpigotAPI:https://hub.spigotmc.org/javadocs/spigot
这里请注意了,有些事件是Spigot独有事件如果你想兼容CraftBukkit服务端请勿调用,例如PlayerSpawnLocationEvent

== 开始使用EventAPI ==
为了让大家看得懂，这一部分先定个小目标,先只用PlayerLoginEvent做示范

=== 设置监听指定Event的方法 ===
为了监听事件，我们需要创建一个新的方法，并给它加上EventHandler的注解来告诉服务端，这是个监听事件的方法,服务端就会在事件发生的时候调用该方法
方法名可以自己写你自己喜欢的，但传入的参数必须是你想监听的事件类
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你在监听到玩家登录时执行的代码
}</source>

=== @EventHandler ===
"@EventHandler" 是一个注解，用来告诉服务端这是一个监听事件的方法,你只需要把它加在你监听指定事件方法的上面就好，就像下面这样
<source lang="java">@EventHandler // EventPriority.NORMAL 是默认的监听级别</source>
这样就告诉了服务端你这个监听事件的方法，优先级是普通的。

当然你也可以自己设置事件监听的优先级比如下面这样:
<source lang="java">@EventHandler(priority = EventPriority.HIGHEST) // 将该事件监听的优先级修改到HIGHEST级别
@EventHandler(priority = EventPriority.LOW) // 将该事件的优先级修改到LOW级别</source>

现在呢你的监听事件的方法的代码应该像这样:
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}</source>

=== 添加一个监听器 ===
为了监听事件，你必须让监听事件的类实现 ''Listener'' (包名是:org.bukkit.event.Listener) 这个接口, e.g.:
<source lang="java">public final class MyPlayerListener implements Listener {
@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}
} </source>

上面那个名字叫''onLogin'' 的监听玩家登录事件的方法现在什么都不能干

就像我说的，Bukkit通过EventHandler注解来知道你这个方法是用来监听事件的，通过方法需要传入的参数知道要监听的是哪个事件，比如: <code>PlayerLoginEvent</code>.

{{特别提醒:要想监听事件，你还必须得执行一个注册监听事件类的方法才能让插件正常监听事件}}

你必须在你的插件主类里(也就是那个继承JavaPlugin的类)的onEnable方法里加上如下代码:
其实吧也不是非得在onEnable里面加上，在你需要监听事件的时候保证这个监听事件的类被注册过就行
<source lang="java">
public class MyPlugin extends JavaPlugin implements Listener {
@Override
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void onLogin(PlayerLoginEvent event) {
System.out.println(event.getPlayer().getName()+"登入了服务器");
}
}
</source>
这里我提醒一下各位读者
玩家登录服务器分四个阶段
HandShake(和服务器握手
PreLogin(预登录阶段，就是正在登录
Login(登入阶段,一般盗版服会直接跳过该阶段,但是是可以监听到的
JoinGame(成功登录服务器

=== EventHandler注解的参数 ===
@EventHandler你可以使用注解来定义事件监听的相关设置

{| class="wikitable" cellspacing="0" cellpadding="5" border="1"
|-
! Name
! Type
! Default
! Description
! Values

|-
| priority
| EventPriority
| EventPriority.NORMAL
| 监听事件的优先级
|
* EventPriority.MONITOR
* EventPriority.HIGHEST
* EventPriority.HIGH
* EventPriority.NORMAL
* EventPriority.LOW
* EventPriority.LOWEST

|-
| ignoreCancelled
| boolean
| false
| 如果你把它设置成true，如果事件被取消这个监听的事件将不再会被监听到
|
* true
* false

|}

==== 事件优先级 ====
Bukkit会按照下面的顺序挨个在事件发生时通知监听该事件的插件
* EventPriority.LOWEST(最优先
* EventPriority.LOW
* EventPriority.NORMAL
* EventPriority.HIGH
* EventPriority.HIGHEST
* EventPriority.MONITOR(最后

服务端将会根据这些监听器内EventHandler注解里面的监听优先级按顺序通知监听器，从LOWEST到MONITOR挨个通知插件，你可以通过设置优先级来阻止其他的插件对同等事件进行操作，并在MONITOR优先级的监听器取消后面插件对该事件的监听达到覆盖操作。

== 注册监听事件的类 ==
要使你插件里包含监听器方法的类被注册，这个监听器才能起效，且包含监听方法的这个类必须实现Listener这个接口
<blockquote><source lang="java">import org.bukkit.event.Listener;

public final class LoginListener implements Listener {
}</source></blockquote>

你只需要这一行代码来注册监听事件的类
<blockquote><source lang="java">getServer().getPluginManager().registerEvents(Listener, Plugin);</source></blockquote>

=== 监听事件的例子 ===
这个监听事件的类包含两个监听器，且监听的是同一个事件，但是一个优先级是HIGH一个是默认的NORMAL
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

=== 将监听事件的类在你的插件内起效 ===
下面代码示范了如何注册你的监听类
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
getServer().getPluginManager().registerEvents(new LoginListener(), this);
}
}</source></blockquote>

==== 直接使用插件主类作为监听类 ====
下面的代码示范了如何偷懒直接使用插件主类作为监听类并注册它:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginPlugin extends JavaPlugin implements Listener {
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

=== 用监听类的构造器注册监听类 ===
有很多很多不同的方式来注册你的监听类，下面代码示范了如何使用监听类的构造器来注册监听类
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
public LoginListener(LoginPlugin plugin) {
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

现在插件的主类代码应该看起来像这样:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
new LoginListener(this);
}
}</source></blockquote>

== 注销你的监听器 ==
前面提到了如何去创建并且注册监听器使之生效，同样的服务端也提供了注销监听器的方法，你可以注销一个插件里所有的监听器，也可以注销一个插件里所有指定事件的监听器

==== 注销一个插件内指定事件的监听器 ====
无一例外，所有事件都有一个静态方法:getHandlerList()，你可以使用这个方法下面的unregister()方法来对一个插件内所有的这个事件的监听器进行注销
比如这样搞:
<blockquote><source lang="java">
PlayerInteractEvent.getHandlerList().unregister(plugin);
// 这样就代表会注销plugin这个插件内所有监听PlayerInteractEvent这个事件的监听器
// 当然了你也可以单独在plugin那个参数里面写入要注销指定监听器的类
</source></blockquote>
下面我们将会学习自定义事件

==== 注销一个插件所有的监听器 ====
你可以使用HandlerList类下面的unregisterAll()这个静态方法来对一个插件所监听的所有事件的监听器进行注销
比如下面这样:
<blockquote><source lang="java">
HandlerList.unregisterAll(plugin);
// 这将会注销这个插件监听这个事件的所有监听器
// 当然这里的参数也可以用一个指定的监听类来代替，可以单独注销一个监听器
</source></blockquote>

== 创建自定义事件 ==
要创建一个自定义的事件是很简单的，而且不会和Bukkit所自带的事件冲突

要创建你的自定义事件，有下面的几点是需要注意的
你的自定义事件的类必须继承Event类，并且必须要有
HandlerList这个静态常量和getHandlers这个方法
所以你的一个基础的自定义事件的类应该看起来像下面这样:

<blockquote><source lang="java">private static final HandlerList handlers = new HandlerList();

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}</source></blockquote>
因为为了不和别的事件起冲突，你必须要拥有自己的HandlerList才可以.

=== 自定义事件的一个小例子 ===
下面得到代码示范了如何快速简单的创建一个自定义的事件的类:
CustomEvent是类名，可以根据自己的事件类型进行更改
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

public final class CustomEvent extends Event {
private static final HandlerList handlers = new HandlerList();
private String message;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

==== 触发你的自定义事件 ====
你现在可以自如掌握如何创建与触发你的自定义事件了。下面是一个例子：
<blockquote><source lang="java">// 创建你的自定义事件对象
CustomEvent event = new CustomEvent("Sample Message");
// 触发事件
Bukkit.getServer().getPluginManager().callEvent(event);
// 现在来对你的事件做点什么
Bukkit.getServer().broadcastMessage(event.getMessage());</source></blockquote>

请您记住：你现在正在控制你的事件，如果你不去触发他，他就没有办法正常工作，什么都不会发生！

==== 监听自定义事件 ====
如何来监听一个自定义事件呢？通常情况下，监听自定义事件与其他普通的事件是一样的！
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public final class CustomListener implements Listener {
@EventHandler
public void normalLogin(CustomEvent event) {
// 你的代码
}
}</source></blockquote>

==== 让你的自定义事件可以被取消 ====
如果你希望你的自定义事件可以被取消，记住，要"implements Cancellable."（实现Cancelled类），就像你去实现Listener类一样，是非常简单的，下面是一个例子：
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.event.Cancellable;

public final class CustomEvent extends Event implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private String message;
private boolean cancelled;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public boolean isCancelled() {
return cancelled;
}

public void setCancelled(boolean cancel) {
cancelled = cancel;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

之后你需要留意，在做些什么之前，你需要在你的代码中检查是否有插件取消了这个事件。就像这样：
<blockquote><source lang="java">// 创建一个事件对象
CustomEvent event = new CustomEvent("Sample Message");
// 触发事件
Bukkit.getServer().getPluginManager().callEvent(event);
// 检查他是不是被取消了
if (!event.isCancelled()) {
// 现在你就可以做些什么了！
Bukkit.getServer().broadcastMessage(event.getMessage());
}</source></blockquote>

== 视频资料 ==
如果你更希望观看视频版的本教程，请点击 [http://www.youtube.com/watch?v=PWQNsqwD-AY 这里！].

[[Category: 条目原文]] [[分类:开发教程]]

Event API Reference/en

2017-08-01T10:40:22Z

Tdiant：/* Making your CustomEvent Cancellable */

{{条目原文}}
欢迎来到Bukkit提供的EventAPI相关教程页

== 简介 ==

'''事件''' 就是你在使用CraftBukkit,或者基于CraftBukkit服务端的其他服务端的时候，服务端会将服务器内发生的事告诉正在监听对应事件的插件。CraftBukkit服务端为插件定义了许多不同的事件，比如玩家登录服务器，玩家进入服务器，玩家点击方块，玩家重生。还有一些可以被取消的事件例如，玩家放置方块，玩家破坏方块，等等。更还有区块卸载区块装载，实体等相关事件。具体请查看API文档:
BukkitAPI:https://hub.spigotmc.org/javadocs/bukkit
SpigotAPI:https://hub.spigotmc.org/javadocs/spigot
这里请注意了,有些事件是Spigot独有事件如果你想兼容CraftBukkit服务端请勿调用,例如PlayerSpawnLocationEvent

== 开始使用EventAPI ==
为了让大家看得懂，这一部分先定个小目标,先只用PlayerLoginEvent做示范

=== 设置监听指定Event的方法 ===
为了监听事件，我们需要创建一个新的方法，并给它加上EventHandler的注解来告诉服务端，这是个监听事件的方法,服务端就会在事件发生的时候调用该方法
方法名可以自己写你自己喜欢的，但传入的参数必须是你想监听的事件类
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你在监听到玩家登录时执行的代码
}</source>

=== @EventHandler ===
"@EventHandler" 是一个注解，用来告诉服务端这是一个监听事件的方法,你只需要把它加在你监听指定事件方法的上面就好，就像下面这样
<source lang="java">@EventHandler // EventPriority.NORMAL 是默认的监听级别</source>
这样就告诉了服务端你这个监听事件的方法，优先级是普通的。

当然你也可以自己设置事件监听的优先级比如下面这样:
<source lang="java">@EventHandler(priority = EventPriority.HIGHEST) // 将该事件监听的优先级修改到HIGHEST级别
@EventHandler(priority = EventPriority.LOW) // 将该事件的优先级修改到LOW级别</source>

现在呢你的监听事件的方法的代码应该像这样:
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}</source>

=== 添加一个监听器 ===
为了监听事件，你必须让监听事件的类实现 ''Listener'' (包名是:org.bukkit.event.Listener) 这个接口, e.g.:
<source lang="java">public final class MyPlayerListener implements Listener {
@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}
} </source>

上面那个名字叫''onLogin'' 的监听玩家登录事件的方法现在什么都不能干

就像我说的，Bukkit通过EventHandler注解来知道你这个方法是用来监听事件的，通过方法需要传入的参数知道要监听的是哪个事件，比如: <code>PlayerLoginEvent</code>.

{{特别提醒:要想监听事件，你还必须得执行一个注册监听事件类的方法才能让插件正常监听事件}}

你必须在你的插件主类里(也就是那个继承JavaPlugin的类)的onEnable方法里加上如下代码:
其实吧也不是非得在onEnable里面加上，在你需要监听事件的时候保证这个监听事件的类被注册过就行
<source lang="java">
public class MyPlugin extends JavaPlugin implements Listener {
@Override
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void onLogin(PlayerLoginEvent event) {
System.out.println(event.getPlayer().getName()+"登入了服务器");
}
}
</source>
这里我提醒一下各位读者
玩家登录服务器分四个阶段
HandShake(和服务器握手
PreLogin(预登录阶段，就是正在登录
Login(登入阶段,一般盗版服会直接跳过该阶段,但是是可以监听到的
JoinGame(成功登录服务器

=== EventHandler注解的参数 ===
@EventHandler你可以使用注解来定义事件监听的相关设置

{| class="wikitable" cellspacing="0" cellpadding="5" border="1"
|-
! Name
! Type
! Default
! Description
! Values

|-
| priority
| EventPriority
| EventPriority.NORMAL
| 监听事件的优先级
|
* EventPriority.MONITOR
* EventPriority.HIGHEST
* EventPriority.HIGH
* EventPriority.NORMAL
* EventPriority.LOW
* EventPriority.LOWEST

|-
| ignoreCancelled
| boolean
| false
| 如果你把它设置成true，如果事件被取消这个监听的事件将不再会被监听到
|
* true
* false

|}

==== 事件优先级 ====
Bukkit会按照下面的顺序挨个在事件发生时通知监听该事件的插件
* EventPriority.LOWEST(最优先
* EventPriority.LOW
* EventPriority.NORMAL
* EventPriority.HIGH
* EventPriority.HIGHEST
* EventPriority.MONITOR(最后

服务端将会根据这些监听器内EventHandler注解里面的监听优先级按顺序通知监听器，从LOWEST到MONITOR挨个通知插件，你可以通过设置优先级来阻止其他的插件对同等事件进行操作，并在MONITOR优先级的监听器取消后面插件对该事件的监听达到覆盖操作。

== 注册监听事件的类 ==
要使你插件里包含监听器方法的类被注册，这个监听器才能起效，且包含监听方法的这个类必须实现Listener这个接口
<blockquote><source lang="java">import org.bukkit.event.Listener;

public final class LoginListener implements Listener {
}</source></blockquote>

你只需要这一行代码来注册监听事件的类
<blockquote><source lang="java">getServer().getPluginManager().registerEvents(Listener, Plugin);</source></blockquote>

=== 监听事件的例子 ===
这个监听事件的类包含两个监听器，且监听的是同一个事件，但是一个优先级是HIGH一个是默认的NORMAL
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

=== 将监听事件的类在你的插件内起效 ===
下面代码示范了如何注册你的监听类
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
getServer().getPluginManager().registerEvents(new LoginListener(), this);
}
}</source></blockquote>

==== 直接使用插件主类作为监听类 ====
下面的代码示范了如何偷懒直接使用插件主类作为监听类并注册它:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginPlugin extends JavaPlugin implements Listener {
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

=== 用监听类的构造器注册监听类 ===
有很多很多不同的方式来注册你的监听类，下面代码示范了如何使用监听类的构造器来注册监听类
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
public LoginListener(LoginPlugin plugin) {
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

现在插件的主类代码应该看起来像这样:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
new LoginListener(this);
}
}</source></blockquote>

== 注销你的监听器 ==
前面提到了如何去创建并且注册监听器使之生效，同样的服务端也提供了注销监听器的方法，你可以注销一个插件里所有的监听器，也可以注销一个插件里所有指定事件的监听器

==== 注销一个插件内指定事件的监听器 ====
无一例外，所有事件都有一个静态方法:getHandlerList()，你可以使用这个方法下面的unregister()方法来对一个插件内所有的这个事件的监听器进行注销
比如这样搞:
<blockquote><source lang="java">
PlayerInteractEvent.getHandlerList().unregister(plugin);
// 这样就代表会注销plugin这个插件内所有监听PlayerInteractEvent这个事件的监听器
// 当然了你也可以单独在plugin那个参数里面写入要注销指定监听器的类
</source></blockquote>
下面我们将会学习自定义事件

==== 注销一个插件所有的监听器 ====
你可以使用HandlerList类下面的unregisterAll()这个静态方法来对一个插件所监听的所有事件的监听器进行注销
比如下面这样:
<blockquote><source lang="java">
HandlerList.unregisterAll(plugin);
// 这将会注销这个插件监听这个事件的所有监听器
// 当然这里的参数也可以用一个指定的监听类来代替，可以单独注销一个监听器
</source></blockquote>

== 创建自定义事件 ==
要创建一个自定义的事件是很简单的，而且不会和Bukkit所自带的事件冲突

要创建你的自定义事件，有下面的几点是需要注意的
你的自定义事件的类必须继承Event类，并且必须要有
HandlerList这个静态常量和getHandlers这个方法
所以你的一个基础的自定义事件的类应该看起来像下面这样:

<blockquote><source lang="java">private static final HandlerList handlers = new HandlerList();

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}</source></blockquote>
因为为了不和别的事件起冲突，你必须要拥有自己的HandlerList才可以.

=== 自定义事件的一个小例子 ===
下面得到代码示范了如何快速简单的创建一个自定义的事件的类:
CustomEvent是类名，可以根据自己的事件类型进行更改
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

public final class CustomEvent extends Event {
private static final HandlerList handlers = new HandlerList();
private String message;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

==== 触发你的自定义事件 ====
你现在可以自如掌握如何创建与触发你的自定义事件了。下面是一个例子：
<blockquote><source lang="java">// 创建你的自定义事件对象
CustomEvent event = new CustomEvent("Sample Message");
// 触发事件
Bukkit.getServer().getPluginManager().callEvent(event);
// 现在来对你的事件做点什么
Bukkit.getServer().broadcastMessage(event.getMessage());</source></blockquote>

请您记住：你现在正在控制你的事件，如果你不去触发他，他就没有办法正常工作，什么都不会发生！

==== 监听自定义事件 ====
如何来监听一个自定义事件呢？通常情况下，监听自定义事件与其他普通的事件是一样的！
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public final class CustomListener implements Listener {
@EventHandler
public void normalLogin(CustomEvent event) {
// 你的代码
}
}</source></blockquote>

==== 让你的自定义事件可以被取消 ====
如果你希望你的自定义事件可以被取消，记住，要"implements Cancellable."（实现Cancelled类），就像你去实现Listener类一样，是非常简单的，下面是一个例子：
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.event.Cancellable;

public final class CustomEvent extends Event implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private String message;
private boolean cancelled;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public boolean isCancelled() {
return cancelled;
}

public void setCancelled(boolean cancel) {
cancelled = cancel;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

之后你需要留意，在做些什么之前，你需要在你的代码中检查是否有插件取消了这个事件。就像这样：
<blockquote><source lang="java">// 创建一个事件对象
CustomEvent event = new CustomEvent("Sample Message");
// 触发事件
Bukkit.getServer().getPluginManager().callEvent(event);
// 检查他是不是被取消了
if (!event.isCancelled()) {
// 现在你就可以做些什么了！
Bukkit.getServer().broadcastMessage(event.getMessage());
}</source></blockquote>

== Video Tutorial ==
If you would prefer to watch a video tutorial version of this, please click [http://www.youtube.com/watch?v=PWQNsqwD-AY here].

[[Category: 条目原文]] [[分类:开发教程]]

Event API Reference/en

2017-08-01T10:36:56Z

Tdiant：/* Listening to a Custom Event */

{{条目原文}}
欢迎来到Bukkit提供的EventAPI相关教程页

== 简介 ==

'''事件''' 就是你在使用CraftBukkit,或者基于CraftBukkit服务端的其他服务端的时候，服务端会将服务器内发生的事告诉正在监听对应事件的插件。CraftBukkit服务端为插件定义了许多不同的事件，比如玩家登录服务器，玩家进入服务器，玩家点击方块，玩家重生。还有一些可以被取消的事件例如，玩家放置方块，玩家破坏方块，等等。更还有区块卸载区块装载，实体等相关事件。具体请查看API文档:
BukkitAPI:https://hub.spigotmc.org/javadocs/bukkit
SpigotAPI:https://hub.spigotmc.org/javadocs/spigot
这里请注意了,有些事件是Spigot独有事件如果你想兼容CraftBukkit服务端请勿调用,例如PlayerSpawnLocationEvent

== 开始使用EventAPI ==
为了让大家看得懂，这一部分先定个小目标,先只用PlayerLoginEvent做示范

=== 设置监听指定Event的方法 ===
为了监听事件，我们需要创建一个新的方法，并给它加上EventHandler的注解来告诉服务端，这是个监听事件的方法,服务端就会在事件发生的时候调用该方法
方法名可以自己写你自己喜欢的，但传入的参数必须是你想监听的事件类
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你在监听到玩家登录时执行的代码
}</source>

=== @EventHandler ===
"@EventHandler" 是一个注解，用来告诉服务端这是一个监听事件的方法,你只需要把它加在你监听指定事件方法的上面就好，就像下面这样
<source lang="java">@EventHandler // EventPriority.NORMAL 是默认的监听级别</source>
这样就告诉了服务端你这个监听事件的方法，优先级是普通的。

当然你也可以自己设置事件监听的优先级比如下面这样:
<source lang="java">@EventHandler(priority = EventPriority.HIGHEST) // 将该事件监听的优先级修改到HIGHEST级别
@EventHandler(priority = EventPriority.LOW) // 将该事件的优先级修改到LOW级别</source>

现在呢你的监听事件的方法的代码应该像这样:
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}</source>

=== 添加一个监听器 ===
为了监听事件，你必须让监听事件的类实现 ''Listener'' (包名是:org.bukkit.event.Listener) 这个接口, e.g.:
<source lang="java">public final class MyPlayerListener implements Listener {
@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}
} </source>

上面那个名字叫''onLogin'' 的监听玩家登录事件的方法现在什么都不能干

就像我说的，Bukkit通过EventHandler注解来知道你这个方法是用来监听事件的，通过方法需要传入的参数知道要监听的是哪个事件，比如: <code>PlayerLoginEvent</code>.

{{特别提醒:要想监听事件，你还必须得执行一个注册监听事件类的方法才能让插件正常监听事件}}

你必须在你的插件主类里(也就是那个继承JavaPlugin的类)的onEnable方法里加上如下代码:
其实吧也不是非得在onEnable里面加上，在你需要监听事件的时候保证这个监听事件的类被注册过就行
<source lang="java">
public class MyPlugin extends JavaPlugin implements Listener {
@Override
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void onLogin(PlayerLoginEvent event) {
System.out.println(event.getPlayer().getName()+"登入了服务器");
}
}
</source>
这里我提醒一下各位读者
玩家登录服务器分四个阶段
HandShake(和服务器握手
PreLogin(预登录阶段，就是正在登录
Login(登入阶段,一般盗版服会直接跳过该阶段,但是是可以监听到的
JoinGame(成功登录服务器

=== EventHandler注解的参数 ===
@EventHandler你可以使用注解来定义事件监听的相关设置

{| class="wikitable" cellspacing="0" cellpadding="5" border="1"
|-
! Name
! Type
! Default
! Description
! Values

|-
| priority
| EventPriority
| EventPriority.NORMAL
| 监听事件的优先级
|
* EventPriority.MONITOR
* EventPriority.HIGHEST
* EventPriority.HIGH
* EventPriority.NORMAL
* EventPriority.LOW
* EventPriority.LOWEST

|-
| ignoreCancelled
| boolean
| false
| 如果你把它设置成true，如果事件被取消这个监听的事件将不再会被监听到
|
* true
* false

|}

==== 事件优先级 ====
Bukkit会按照下面的顺序挨个在事件发生时通知监听该事件的插件
* EventPriority.LOWEST(最优先
* EventPriority.LOW
* EventPriority.NORMAL
* EventPriority.HIGH
* EventPriority.HIGHEST
* EventPriority.MONITOR(最后

服务端将会根据这些监听器内EventHandler注解里面的监听优先级按顺序通知监听器，从LOWEST到MONITOR挨个通知插件，你可以通过设置优先级来阻止其他的插件对同等事件进行操作，并在MONITOR优先级的监听器取消后面插件对该事件的监听达到覆盖操作。

== 注册监听事件的类 ==
要使你插件里包含监听器方法的类被注册，这个监听器才能起效，且包含监听方法的这个类必须实现Listener这个接口
<blockquote><source lang="java">import org.bukkit.event.Listener;

public final class LoginListener implements Listener {
}</source></blockquote>

你只需要这一行代码来注册监听事件的类
<blockquote><source lang="java">getServer().getPluginManager().registerEvents(Listener, Plugin);</source></blockquote>

=== 监听事件的例子 ===
这个监听事件的类包含两个监听器，且监听的是同一个事件，但是一个优先级是HIGH一个是默认的NORMAL
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

=== 将监听事件的类在你的插件内起效 ===
下面代码示范了如何注册你的监听类
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
getServer().getPluginManager().registerEvents(new LoginListener(), this);
}
}</source></blockquote>

==== 直接使用插件主类作为监听类 ====
下面的代码示范了如何偷懒直接使用插件主类作为监听类并注册它:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginPlugin extends JavaPlugin implements Listener {
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

=== 用监听类的构造器注册监听类 ===
有很多很多不同的方式来注册你的监听类，下面代码示范了如何使用监听类的构造器来注册监听类
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
public LoginListener(LoginPlugin plugin) {
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

现在插件的主类代码应该看起来像这样:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
new LoginListener(this);
}
}</source></blockquote>

== 注销你的监听器 ==
前面提到了如何去创建并且注册监听器使之生效，同样的服务端也提供了注销监听器的方法，你可以注销一个插件里所有的监听器，也可以注销一个插件里所有指定事件的监听器

==== 注销一个插件内指定事件的监听器 ====
无一例外，所有事件都有一个静态方法:getHandlerList()，你可以使用这个方法下面的unregister()方法来对一个插件内所有的这个事件的监听器进行注销
比如这样搞:
<blockquote><source lang="java">
PlayerInteractEvent.getHandlerList().unregister(plugin);
// 这样就代表会注销plugin这个插件内所有监听PlayerInteractEvent这个事件的监听器
// 当然了你也可以单独在plugin那个参数里面写入要注销指定监听器的类
</source></blockquote>
下面我们将会学习自定义事件

==== 注销一个插件所有的监听器 ====
你可以使用HandlerList类下面的unregisterAll()这个静态方法来对一个插件所监听的所有事件的监听器进行注销
比如下面这样:
<blockquote><source lang="java">
HandlerList.unregisterAll(plugin);
// 这将会注销这个插件监听这个事件的所有监听器
// 当然这里的参数也可以用一个指定的监听类来代替，可以单独注销一个监听器
</source></blockquote>

== 创建自定义事件 ==
要创建一个自定义的事件是很简单的，而且不会和Bukkit所自带的事件冲突

要创建你的自定义事件，有下面的几点是需要注意的
你的自定义事件的类必须继承Event类，并且必须要有
HandlerList这个静态常量和getHandlers这个方法
所以你的一个基础的自定义事件的类应该看起来像下面这样:

<blockquote><source lang="java">private static final HandlerList handlers = new HandlerList();

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}</source></blockquote>
因为为了不和别的事件起冲突，你必须要拥有自己的HandlerList才可以.

=== 自定义事件的一个小例子 ===
下面得到代码示范了如何快速简单的创建一个自定义的事件的类:
CustomEvent是类名，可以根据自己的事件类型进行更改
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

public final class CustomEvent extends Event {
private static final HandlerList handlers = new HandlerList();
private String message;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

==== 触发你的自定义事件 ====
你现在可以自如掌握如何创建与触发你的自定义事件了。下面是一个例子：
<blockquote><source lang="java">// 创建你的自定义事件对象
CustomEvent event = new CustomEvent("Sample Message");
// 触发事件
Bukkit.getServer().getPluginManager().callEvent(event);
// 现在来对你的事件做点什么
Bukkit.getServer().broadcastMessage(event.getMessage());</source></blockquote>

请您记住：你现在正在控制你的事件，如果你不去触发他，他就没有办法正常工作，什么都不会发生！

==== 监听自定义事件 ====
如何来监听一个自定义事件呢？通常情况下，监听自定义事件与其他普通的事件是一样的！
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public final class CustomListener implements Listener {
@EventHandler
public void normalLogin(CustomEvent event) {
// 你的代码
}
}</source></blockquote>

==== Making your CustomEvent Cancellable ====
If you ever want to make your event cancellable, remember one thing: "implements Cancellable." Just like you would import Listener. It's really that simple, let me show you an example!
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.event.Cancellable;

public final class CustomEvent extends Event implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private String message;
private boolean cancelled;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public boolean isCancelled() {
return cancelled;
}

public void setCancelled(boolean cancel) {
cancelled = cancel;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

Afterwards, you would check if a plugin had cancelled the event in your code, before processing normally
<blockquote><source lang="java">// Create the event here
CustomEvent event = new CustomEvent("Sample Message");
// Call the event
Bukkit.getServer().getPluginManager().callEvent(event);
// Check if the event is not cancelled
if (!event.isCancelled()) {
// Now you do the event
Bukkit.getServer().broadcastMessage(event.getMessage());
}</source></blockquote>

== Video Tutorial ==
If you would prefer to watch a video tutorial version of this, please click [http://www.youtube.com/watch?v=PWQNsqwD-AY here].

[[Category: 条目原文]] [[分类:开发教程]]

Event API Reference/en

2017-08-01T10:35:47Z

Tdiant：/* 唤起你的自定义事件 */

{{条目原文}}
欢迎来到Bukkit提供的EventAPI相关教程页

== 简介 ==

'''事件''' 就是你在使用CraftBukkit,或者基于CraftBukkit服务端的其他服务端的时候，服务端会将服务器内发生的事告诉正在监听对应事件的插件。CraftBukkit服务端为插件定义了许多不同的事件，比如玩家登录服务器，玩家进入服务器，玩家点击方块，玩家重生。还有一些可以被取消的事件例如，玩家放置方块，玩家破坏方块，等等。更还有区块卸载区块装载，实体等相关事件。具体请查看API文档:
BukkitAPI:https://hub.spigotmc.org/javadocs/bukkit
SpigotAPI:https://hub.spigotmc.org/javadocs/spigot
这里请注意了,有些事件是Spigot独有事件如果你想兼容CraftBukkit服务端请勿调用,例如PlayerSpawnLocationEvent

== 开始使用EventAPI ==
为了让大家看得懂，这一部分先定个小目标,先只用PlayerLoginEvent做示范

=== 设置监听指定Event的方法 ===
为了监听事件，我们需要创建一个新的方法，并给它加上EventHandler的注解来告诉服务端，这是个监听事件的方法,服务端就会在事件发生的时候调用该方法
方法名可以自己写你自己喜欢的，但传入的参数必须是你想监听的事件类
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你在监听到玩家登录时执行的代码
}</source>

=== @EventHandler ===
"@EventHandler" 是一个注解，用来告诉服务端这是一个监听事件的方法,你只需要把它加在你监听指定事件方法的上面就好，就像下面这样
<source lang="java">@EventHandler // EventPriority.NORMAL 是默认的监听级别</source>
这样就告诉了服务端你这个监听事件的方法，优先级是普通的。

当然你也可以自己设置事件监听的优先级比如下面这样:
<source lang="java">@EventHandler(priority = EventPriority.HIGHEST) // 将该事件监听的优先级修改到HIGHEST级别
@EventHandler(priority = EventPriority.LOW) // 将该事件的优先级修改到LOW级别</source>

现在呢你的监听事件的方法的代码应该像这样:
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}</source>

=== 添加一个监听器 ===
为了监听事件，你必须让监听事件的类实现 ''Listener'' (包名是:org.bukkit.event.Listener) 这个接口, e.g.:
<source lang="java">public final class MyPlayerListener implements Listener {
@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}
} </source>

上面那个名字叫''onLogin'' 的监听玩家登录事件的方法现在什么都不能干

就像我说的，Bukkit通过EventHandler注解来知道你这个方法是用来监听事件的，通过方法需要传入的参数知道要监听的是哪个事件，比如: <code>PlayerLoginEvent</code>.

{{特别提醒:要想监听事件，你还必须得执行一个注册监听事件类的方法才能让插件正常监听事件}}

你必须在你的插件主类里(也就是那个继承JavaPlugin的类)的onEnable方法里加上如下代码:
其实吧也不是非得在onEnable里面加上，在你需要监听事件的时候保证这个监听事件的类被注册过就行
<source lang="java">
public class MyPlugin extends JavaPlugin implements Listener {
@Override
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void onLogin(PlayerLoginEvent event) {
System.out.println(event.getPlayer().getName()+"登入了服务器");
}
}
</source>
这里我提醒一下各位读者
玩家登录服务器分四个阶段
HandShake(和服务器握手
PreLogin(预登录阶段，就是正在登录
Login(登入阶段,一般盗版服会直接跳过该阶段,但是是可以监听到的
JoinGame(成功登录服务器

=== EventHandler注解的参数 ===
@EventHandler你可以使用注解来定义事件监听的相关设置

{| class="wikitable" cellspacing="0" cellpadding="5" border="1"
|-
! Name
! Type
! Default
! Description
! Values

|-
| priority
| EventPriority
| EventPriority.NORMAL
| 监听事件的优先级
|
* EventPriority.MONITOR
* EventPriority.HIGHEST
* EventPriority.HIGH
* EventPriority.NORMAL
* EventPriority.LOW
* EventPriority.LOWEST

|-
| ignoreCancelled
| boolean
| false
| 如果你把它设置成true，如果事件被取消这个监听的事件将不再会被监听到
|
* true
* false

|}

==== 事件优先级 ====
Bukkit会按照下面的顺序挨个在事件发生时通知监听该事件的插件
* EventPriority.LOWEST(最优先
* EventPriority.LOW
* EventPriority.NORMAL
* EventPriority.HIGH
* EventPriority.HIGHEST
* EventPriority.MONITOR(最后

服务端将会根据这些监听器内EventHandler注解里面的监听优先级按顺序通知监听器，从LOWEST到MONITOR挨个通知插件，你可以通过设置优先级来阻止其他的插件对同等事件进行操作，并在MONITOR优先级的监听器取消后面插件对该事件的监听达到覆盖操作。

== 注册监听事件的类 ==
要使你插件里包含监听器方法的类被注册，这个监听器才能起效，且包含监听方法的这个类必须实现Listener这个接口
<blockquote><source lang="java">import org.bukkit.event.Listener;

public final class LoginListener implements Listener {
}</source></blockquote>

你只需要这一行代码来注册监听事件的类
<blockquote><source lang="java">getServer().getPluginManager().registerEvents(Listener, Plugin);</source></blockquote>

=== 监听事件的例子 ===
这个监听事件的类包含两个监听器，且监听的是同一个事件，但是一个优先级是HIGH一个是默认的NORMAL
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

=== 将监听事件的类在你的插件内起效 ===
下面代码示范了如何注册你的监听类
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
getServer().getPluginManager().registerEvents(new LoginListener(), this);
}
}</source></blockquote>

==== 直接使用插件主类作为监听类 ====
下面的代码示范了如何偷懒直接使用插件主类作为监听类并注册它:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginPlugin extends JavaPlugin implements Listener {
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

=== 用监听类的构造器注册监听类 ===
有很多很多不同的方式来注册你的监听类，下面代码示范了如何使用监听类的构造器来注册监听类
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
public LoginListener(LoginPlugin plugin) {
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// 你的代码
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// 你的代码
}
}</source></blockquote>

现在插件的主类代码应该看起来像这样:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
new LoginListener(this);
}
}</source></blockquote>

== 注销你的监听器 ==
前面提到了如何去创建并且注册监听器使之生效，同样的服务端也提供了注销监听器的方法，你可以注销一个插件里所有的监听器，也可以注销一个插件里所有指定事件的监听器

==== 注销一个插件内指定事件的监听器 ====
无一例外，所有事件都有一个静态方法:getHandlerList()，你可以使用这个方法下面的unregister()方法来对一个插件内所有的这个事件的监听器进行注销
比如这样搞:
<blockquote><source lang="java">
PlayerInteractEvent.getHandlerList().unregister(plugin);
// 这样就代表会注销plugin这个插件内所有监听PlayerInteractEvent这个事件的监听器
// 当然了你也可以单独在plugin那个参数里面写入要注销指定监听器的类
</source></blockquote>
下面我们将会学习自定义事件

==== 注销一个插件所有的监听器 ====
你可以使用HandlerList类下面的unregisterAll()这个静态方法来对一个插件所监听的所有事件的监听器进行注销
比如下面这样:
<blockquote><source lang="java">
HandlerList.unregisterAll(plugin);
// 这将会注销这个插件监听这个事件的所有监听器
// 当然这里的参数也可以用一个指定的监听类来代替，可以单独注销一个监听器
</source></blockquote>

== 创建自定义事件 ==
要创建一个自定义的事件是很简单的，而且不会和Bukkit所自带的事件冲突

要创建你的自定义事件，有下面的几点是需要注意的
你的自定义事件的类必须继承Event类，并且必须要有
HandlerList这个静态常量和getHandlers这个方法
所以你的一个基础的自定义事件的类应该看起来像下面这样:

<blockquote><source lang="java">private static final HandlerList handlers = new HandlerList();

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}</source></blockquote>
因为为了不和别的事件起冲突，你必须要拥有自己的HandlerList才可以.

=== 自定义事件的一个小例子 ===
下面得到代码示范了如何快速简单的创建一个自定义的事件的类:
CustomEvent是类名，可以根据自己的事件类型进行更改
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

public final class CustomEvent extends Event {
private static final HandlerList handlers = new HandlerList();
private String message;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

==== 触发你的自定义事件 ====
你现在可以自如掌握如何创建与触发你的自定义事件了。下面是一个例子：
<blockquote><source lang="java">// 创建你的自定义事件对象
CustomEvent event = new CustomEvent("Sample Message");
// 触发事件
Bukkit.getServer().getPluginManager().callEvent(event);
// 现在来对你的事件做点什么
Bukkit.getServer().broadcastMessage(event.getMessage());</source></blockquote>

请您记住：你现在正在控制你的事件，如果你不去触发他，他就没有办法正常工作，什么都不会发生！

==== Listening to a Custom Event ====
How do you listen to a custom event you say? Simple, the same way as listening to a normal event!
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public final class CustomListener implements Listener {
@EventHandler
public void normalLogin(CustomEvent event) {
// Some code here
}
}</source></blockquote>

==== Making your CustomEvent Cancellable ====
If you ever want to make your event cancellable, remember one thing: "implements Cancellable." Just like you would import Listener. It's really that simple, let me show you an example!
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.event.Cancellable;

public final class CustomEvent extends Event implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private String message;
private boolean cancelled;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public boolean isCancelled() {
return cancelled;
}

public void setCancelled(boolean cancel) {
cancelled = cancel;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

Afterwards, you would check if a plugin had cancelled the event in your code, before processing normally
<blockquote><source lang="java">// Create the event here
CustomEvent event = new CustomEvent("Sample Message");
// Call the event
Bukkit.getServer().getPluginManager().callEvent(event);
// Check if the event is not cancelled
if (!event.isCancelled()) {
// Now you do the event
Bukkit.getServer().broadcastMessage(event.getMessage());
}</source></blockquote>

== Video Tutorial ==
If you would prefer to watch a video tutorial version of this, please click [http://www.youtube.com/watch?v=PWQNsqwD-AY here].

[[Category: 条目原文]] [[分类:开发教程]]

Developing a permissions plugin

2017-08-01T10:32:31Z

Tdiant：/* Permissible */

[[Developing a permissions plugin/en|点击此处查看原文]]

== 引言 ==

这篇教程将会带领你了解有关怎么基于新的BukkitPermissionsAPI给你插件创建权限。

=== 前提 ===

这篇教程需要你掌握很好的Java知识和一些插件开发知识。这篇教程只会涵盖有关Bukkit Permissions API的各种细节。

== Permissible类 ==

所有拥有权限集的类都必须继承自Permissible类。 
目前这些只包含Player和CommandSender类，然而理论上任何事物都应该拥有“权限”。 在接下来的教程里我们将更多的提到玩家而不是permissible对象。

== PermissionAttachments ==

=== PermissionAttachment是什么? ===
 什么是PermissionAttachment？
 “权限附属物”[PermissionAttachment]是插件管理玩家权限的一种手段，更胜一筹的是，它允许多插件管理玩家权限而不需要接口，除非它想要设置同样的权限。

=== 怎样创建和移除它们 ===
 如何创建和移除一个PermissionAttachment
 每一位玩家必须先被“附着”在插件上，这样才能使用他们。用如下代码来创建一个PermissionAttachment:
<source lang="java">PermissionAttachment attachment = player.addAttachment(plugin);</source>

 你甚至可以创建一个仅仅只维持很短时间的attachment

<source lang="java">PermissionAttachment attachment = player.addAttachment(plugin,ticks);</source>

 attachment需要被储存起来。最好的解决方案是用哈希表HashMap<UUID,PermissionAttachment> 来储存。用玩家的UniqueID作为键值。之后你就可以用玩家的UniqueID来管理指定玩家的权限了。并且在不需要的时候移除它。移除attachment的地方最好是onPlayerQuit event, onPlayerKick event。并且总是在插件的onDisable中移除所有的attachment。使用下面的代码移除attachment：

<source lang="java">player.removeAttachment(attachment);</source>

== 配置权限 ==

 这有两种主要的方法去配置玩家的权限：

#通过字符串。这大概是最简单的方法了，所以我最先解释它。
#通过permission对象。这就有点复杂了，然而他内部的工作方式与第一个完全一样。所以我并不打算重温它。

 

想要设置玩家的权限你必须先获取之前通过哈希表创建的PermissionAttachment。一旦你取得了PermissionAttachment，你就可以通过一种简单的方式来设置权限。代码如下：

<source lang="java">attachment.setPermission(permissionName,permissionValue);</source>

 permissionName是一个字符串，permissionValue则是布尔类型数据。之后你可以通过如下代码撤销一个玩家的权限(与将permissionValue设置成false不同)：

<source lang="java">attachment.unsetPermission(permissionName);</source>
 
你希望撤销玩家权限的原因是你希望别的权限插件来设置它。
== 总结 ==
以上就是所有想要写出自己的权限插件的你需要知道东西了。
一个真正的权限插件是什么样的完全取决于你。下面提供2个例子：
* 一个根据玩家经验值继续权限的RPG插件
* 一个从论坛链接权限组/权限的接口，例如从phpBB到bukkit权限

[[Category:开发教程]]

Event API Reference

2017-02-25T14:03:02Z

Tdiant：/* 创建自定义事件 */

[[Event API Reference/en|点击此处浏览原文]]
{{待翻译}}
== 介绍 ==

服务器里发生的事情，服务器会用'''事件''' 来告诉你。 '''Bukkit'''中有各种各样的事件，例如玩家的互动(玩家登录, 玩家点击了一个方块, 玩家死了,玩家重生...), 方块的动态(方块被放置, 方块被破坏, 方块附近的实体被改变...), 实体事件(一个怪物看上了你233, 一个苦力怕帮你收集土方块...), 世界事件 (一个世界被加载或卸载, 一个区块被加载或卸载)等等. 由于MC官方的一些原因，他们的JavaDocs都挂了= =

== 基础 ==
为了保持简单易懂，这一节只讨论一种事件——PlayerLoginEnvent。让我们从创建一个监听器开始吧。

=== 创建方法 ===
为了让你的插件能够监听并处理该事件的回调，你需要为它创建一个方法，这个方法就是事件'''监听器'''。
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你自己的代码...
}</source>
你需要向Bukkit注册你的监听器，这样服务器才会在"PlayerLoginEvent"触发时调用该监听器。我们需要给监听器打上 @EventHandler 批注。

=== @EventHandler ===
"@EventHandler" 是一个能打在某个方法上的批注，就像这样：
<source lang="java">@EventHandler // 优先级默认为NORMAL级</source>
这样一来，这所对应的方法就成为了一个优先级为NORMAL的监听器。

你可以设置EventHandler标签的EventPriority属性来自定义事件的优先级，例如：
<source lang="java">@EventHandler(priority = EventPriority.HIGHEST) // 将优先级设为HIGHEST级
@EventHandler(priority = EventPriority.LOW) // 优先级设为LOW级</source>

你的监听器应该看上去像是这样：
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你自己的代码...
}</source>

=== 添加监听器 ===
为了让Bukkit能够注册你的监听器，你需要给你的监听器所在的类实现Listener接口(org.bukkit.event.Listener)。例如这样：

<source lang="java">public final class MyPlayerListener implements Listener {
@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}
} </source>
监听器的方法名（例子中是“onlogin”的东西）并不重要；只要符合命名规则，起什么名字，你开心就好。
你可能想知道：“Bukkit怎么知道监听那个事件呢？”。Bukkit是通过上面例子中你定义的“PlayerLoginEvent”这个参数知道的。
{{warning|一个监听器只能监听一个事件，否则Bukkit是不会注册它的！}}
你的插件的主类 (就是继承JavaPlugin的那个类) 也可以成为一个事件监听器。在你的插件非常小的时候，这样就很方便了。比如:
<source lang="java">
public class MyPlugin extends JavaPlugin implements Listener {
@Override
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void onLogin(PlayerLoginEvent event) {
getLogger().log(Level.INFO, "Player " + event.getPlayer().getName() + " is logging in!");
}
}
</source>

=== EventHandler的参数 ===
@EventHandler 批注可以设置某些参数来改变监听器的某些作用等。在某些情况下，你可以设置这些参数:

{| class="wikitable" cellspacing="0" cellpadding="5" border="1"
|-
! 名称
! 类型
! 默认值
! 描述
! 值

|-
| priority
| EventPriority
| EventPriority.NORMAL
| 设置监听器优先级
|
* EventPriority.MONITOR
* EventPriority.HIGHEST
* EventPriority.HIGH
* EventPriority.NORMAL
* EventPriority.LOW
* EventPriority.LOWEST

|-
| ignoreCancelled
| boolean
| false
| 如果设为true，在事件被其他监听器关闭的时候，你的监听器将监听不到这个事件
|
* true
* false

|}

==== 事件优先级 ====
Bukkit中的监听器拥有六个优先级
* EventPriority.LOWEST
* EventPriority.LOW
* EventPriority.NORMAL
* EventPriority.HIGH
* EventPriority.HIGHEST
* EventPriority.MONITOR

每个插件可能会在一个事件触发时做出不同的相应，并且有的插件可能想更快的知道一个事件的发生。并且，有时候Bukkit传递事件给每个插件的时候，甚至这个事件已经被其他插件关闭了。某些情况下，其他插件刚把这个事件关掉，另外一个插件监听到了以后又把这个事件开开了。这样乱七八糟的冲突发生了以后，这就很尴尬了。

比如方块放置被触发了，LOWEST优先级的监听器将会最先对这个事件做出决定，比如关闭它什么的。然后LOW优先级的监听器将会被触发，这时候可以重写LOWEST级监听器刚刚做出的修改，以此类推。Eventually it hits monitor, and at this point nothing should change the outcome of the event. MONITOR级的监听器 should be used to see the outcome of an event, without changing any aspect of it.
If we have three plugins enabled; one is a basic area protection plugin, one is a fancy plugin using signs, and another is a logging plugin.
The protection plugin listens on Priority.LOWEST. It says they can't place blocks in this area, and cancels the event.
The fancy sign plugin listens on Priority.NORMAL. It says they can place signs here, and uncancels the event.
The log plugin listens on Priority.MONITOR. It sees that the event was actually allowed, and logs it.

If you want to change the outcome of an event, choose very carefully from LOWEST to HIGHEST. Suggested generalized protection plugins on lowest, more specific plugins on normal, and override plugins on high.
If you want to act when an event happens, but not change the outcome, use MONITOR. '''It's really really important that you use MONITOR, or an event might get cancelled after you've acted on it, and it's even more important that you don't change the outcome of the event on MONITOR or it'll break other plugins.'''

'''中文简单解释'''

优先级越高的方法越早调用

优先级再高(除了MONITOR) setCanceled() 方法也不能阻止其它插件监听到它

在MONITOR上搞 setCanceled(false) 其它插件会给你玩死~

== 注册事件(监听器) ==
要注册你的方法，包含EventHandler的类必须是implent了Listenr类的
<blockquote><source lang="java">import org.bukkit.event.Listener;

public final class LoginListener implements Listener {
}</source></blockquote>
你只需要提供一个插件和一个监听器来在PluginManager里注册它们
<blockquote><source lang="java">getServer().getPluginManager().registerEvents(Listener, Plugin);</source></blockquote>

=== 监听器示例 ===
这个监听器包含两个EventHandlers，一个监听级别是HIGH并且另一个是NORMAL。
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

=== 在插件中注册事件监听器 ===
The registerEvents method requires a listener and a plugin. Luckily, we already have our LoginListener. Now for the LoginPlugin!
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
getServer().getPluginManager().registerEvents(new LoginListener(), this);
}
}</source></blockquote>

==== 在实现监听器接口的插件中注册事件监听器 ====
<ref>准确来说是在实现了监听器接口的继承了JavaPlugin的类中注册事件（笑</ref>
You could even have the events in the main class, for example:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginPlugin extends JavaPlugin implements Listener {
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

=== 在监听器中注册事件监听器 ===
There are many ways to register your events. Here's an example where you register them in your listener class.
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
public LoginListener(LoginPlugin plugin) {
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

The LoginPlugin would look like this:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
new LoginListener(this);
}
}</source></blockquote>

== 在监听器中注销事件监听器 ==
You can un-register individual events, entire listener classes or all events registered by your plugin or even by other plugins!

==== 注销特定的事件监听器 ====
Each event class has the getHandlerList() static method, call that and then you can use .unregister() method.
Example:
<blockquote><source lang="java">
PlayerInteractEvent.getHandlerList().unregister(plugin);
// this will unregister all PlayerInteractEvent instances from the plugin
// you can also specify a listener class instead of plugin.
</source></blockquote>
Now you know why you'll need the getHandlerList() in your custom events.

==== 注销所有事件监听器 ====
Using the HandlerList class and its unregisterAll() static method you can easily unregister events from listener classes or plugins.
Example:
<blockquote><source lang="java">
HandlerList.unregisterAll(plugin);
// this will unregister all events from the specified plugin
// you can also specify a listener class instead of plugin.
</source></blockquote>

== 创建自定义事件 ==
创建一个自定义事件是非常简单的，你可以使用跟Bukkit用的一样的系统，而不需要担心服务器性能的问题。

在你创建一个自定义事件的时候，有两个东西你要记住——"继承 Event 类" 和 "静态的 handlers" 。你必须像下面这样写来做静态的handlers：

<blockquote><source lang="java">private static final HandlerList handlers = new HandlerList();

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}</source></blockquote>
这块代码可以让 EventHandlers 更方便的操作事件，使无关的事件完全的分开。

=== 自定义事件示例 ===
下面的这个例子向你展示如何简单地创建一个你自己的事件——“CustomEvent事件”。
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

public final class CustomEvent extends Event {
private static final HandlerList handlers = new HandlerList();
private String message;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

==== 调用你的自定义事件 ====
You are in control of creating and calling your events, where you call it is completely up to you. Here's an example
<blockquote><source lang="java">// 创建一个自定义事件对象
CustomEvent event = new CustomEvent("Sample Message");
// 触发事件（创建好自定义事件对象，要使用本语句触发事件，否则什么都不会发生）
Bukkit.getServer().getPluginManager().callEvent(event);
// 然后继续操作事件
Bukkit.getServer().broadcastMessage(event.getMessage());</source></blockquote>

请你记住！你正在控制你的自定义事件的对象。如果你不触发它，那就啥都不会发生。

==== 监听一个自定义事件 ====
如何监听一个自定义事件呢？简单！就像监听Bukkit其他普通的事件是一样的！
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public final class CustomListener implements Listener {
@EventHandler
public void normalLogin(CustomEvent event) {
// 你的代码
}
}</source></blockquote>

==== 使得你的自定义事件具有可撤销性 ====
如果你想让你的自定义事件可以被撤销，记得，要“继承Cancellable类”。就像你继承Listener那样。这十分简单，让我向你展示一个例子！
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.event.Cancellable;

public final class CustomEvent extends Event implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private String message;
private boolean cancelled;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public boolean isCancelled() {
return cancelled;
}

public void setCancelled(boolean cancel) {
cancelled = cancel;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

之后，你需要在你执行相应代码前，检查一下是否有插件把你的事件撤销掉了。
<blockquote><source lang="java">// 创建一个事件对象
CustomEvent event = new CustomEvent("Sample Message");
// 触发事件
Bukkit.getServer().getPluginManager().callEvent(event);
// 检查一下是否事件被撤销
if (!event.isCancelled()) {
// 现在在这里做些什么吧！
Bukkit.getServer().broadcastMessage(event.getMessage());
}</source></blockquote>

== 视频教程 ==
If you would prefer to watch a video tutorial version of this, please click [http://www.youtube.com/watch?v=PWQNsqwD-AY here].
<references />
[[Category: Tutorials]]

Event API Reference

2017-02-25T13:41:35Z

Tdiant：/* 使得你的自定义事件具有可撤销性 */

[[Event API Reference/en|点击此处浏览原文]]
{{待翻译}}
== 介绍 ==

服务器里发生的事情，服务器会用'''事件''' 来告诉你。 '''Bukkit'''中有各种各样的事件，例如玩家的互动(玩家登录, 玩家点击了一个方块, 玩家死了,玩家重生...), 方块的动态(方块被放置, 方块被破坏, 方块附近的实体被改变...), 实体事件(一个怪物看上了你233, 一个苦力怕帮你收集土方块...), 世界事件 (一个世界被加载或卸载, 一个区块被加载或卸载)等等. 由于MC官方的一些原因，他们的JavaDocs都挂了= =

== 基础 ==
为了保持简单易懂，这一节只讨论一种事件——PlayerLoginEnvent。让我们从创建一个监听器开始吧。

=== 创建方法 ===
为了让你的插件能够监听并处理该事件的回调，你需要为它创建一个方法，这个方法就是事件'''监听器'''。
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你自己的代码...
}</source>
你需要向Bukkit注册你的监听器，这样服务器才会在"PlayerLoginEvent"触发时调用该监听器。我们需要给监听器打上 @EventHandler 批注。

=== @EventHandler ===
"@EventHandler" 是一个能打在某个方法上的批注，就像这样：
<source lang="java">@EventHandler // 优先级默认为NORMAL级</source>
这样一来，这所对应的方法就成为了一个优先级为NORMAL的监听器。

你可以设置EventHandler标签的EventPriority属性来自定义事件的优先级，例如：
<source lang="java">@EventHandler(priority = EventPriority.HIGHEST) // 将优先级设为HIGHEST级
@EventHandler(priority = EventPriority.LOW) // 优先级设为LOW级</source>

你的监听器应该看上去像是这样：
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你自己的代码...
}</source>

=== 添加监听器 ===
为了让Bukkit能够注册你的监听器，你需要给你的监听器所在的类实现Listener接口(org.bukkit.event.Listener)。例如这样：

<source lang="java">public final class MyPlayerListener implements Listener {
@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}
} </source>
监听器的方法名（例子中是“onlogin”的东西）并不重要；只要符合命名规则，起什么名字，你开心就好。
你可能想知道：“Bukkit怎么知道监听那个事件呢？”。Bukkit是通过上面例子中你定义的“PlayerLoginEvent”这个参数知道的。
{{warning|一个监听器只能监听一个事件，否则Bukkit是不会注册它的！}}
你的插件的主类 (就是继承JavaPlugin的那个类) 也可以成为一个事件监听器。在你的插件非常小的时候，这样就很方便了。比如:
<source lang="java">
public class MyPlugin extends JavaPlugin implements Listener {
@Override
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void onLogin(PlayerLoginEvent event) {
getLogger().log(Level.INFO, "Player " + event.getPlayer().getName() + " is logging in!");
}
}
</source>

=== EventHandler的参数 ===
@EventHandler 批注可以设置某些参数来改变监听器的某些作用等。在某些情况下，你可以设置这些参数:

{| class="wikitable" cellspacing="0" cellpadding="5" border="1"
|-
! 名称
! 类型
! 默认值
! 描述
! 值

|-
| priority
| EventPriority
| EventPriority.NORMAL
| 设置监听器优先级
|
* EventPriority.MONITOR
* EventPriority.HIGHEST
* EventPriority.HIGH
* EventPriority.NORMAL
* EventPriority.LOW
* EventPriority.LOWEST

|-
| ignoreCancelled
| boolean
| false
| 如果设为true，在事件被其他监听器关闭的时候，你的监听器将监听不到这个事件
|
* true
* false

|}

==== 事件优先级 ====
Bukkit中的监听器拥有六个优先级
* EventPriority.LOWEST
* EventPriority.LOW
* EventPriority.NORMAL
* EventPriority.HIGH
* EventPriority.HIGHEST
* EventPriority.MONITOR

每个插件可能会在一个事件触发时做出不同的相应，并且有的插件可能想更快的知道一个事件的发生。并且，有时候Bukkit传递事件给每个插件的时候，甚至这个事件已经被其他插件关闭了。某些情况下，其他插件刚把这个事件关掉，另外一个插件监听到了以后又把这个事件开开了。这样乱七八糟的冲突发生了以后，这就很尴尬了。

比如方块放置被触发了，LOWEST优先级的监听器将会最先对这个事件做出决定，比如关闭它什么的。然后LOW优先级的监听器将会被触发，这时候可以重写LOWEST级监听器刚刚做出的修改，以此类推。Eventually it hits monitor, and at this point nothing should change the outcome of the event. MONITOR级的监听器 should be used to see the outcome of an event, without changing any aspect of it.
If we have three plugins enabled; one is a basic area protection plugin, one is a fancy plugin using signs, and another is a logging plugin.
The protection plugin listens on Priority.LOWEST. It says they can't place blocks in this area, and cancels the event.
The fancy sign plugin listens on Priority.NORMAL. It says they can place signs here, and uncancels the event.
The log plugin listens on Priority.MONITOR. It sees that the event was actually allowed, and logs it.

If you want to change the outcome of an event, choose very carefully from LOWEST to HIGHEST. Suggested generalized protection plugins on lowest, more specific plugins on normal, and override plugins on high.
If you want to act when an event happens, but not change the outcome, use MONITOR. '''It's really really important that you use MONITOR, or an event might get cancelled after you've acted on it, and it's even more important that you don't change the outcome of the event on MONITOR or it'll break other plugins.'''

'''中文简单解释'''

优先级越高的方法越早调用

优先级再高(除了MONITOR) setCanceled() 方法也不能阻止其它插件监听到它

在MONITOR上搞 setCanceled(false) 其它插件会给你玩死~

== 注册事件(监听器) ==
要注册你的方法，包含EventHandler的类必须是implent了Listenr类的
<blockquote><source lang="java">import org.bukkit.event.Listener;

public final class LoginListener implements Listener {
}</source></blockquote>
你只需要提供一个插件和一个监听器来在PluginManager里注册它们
<blockquote><source lang="java">getServer().getPluginManager().registerEvents(Listener, Plugin);</source></blockquote>

=== 监听器示例 ===
这个监听器包含两个EventHandlers，一个监听级别是HIGH并且另一个是NORMAL。
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

=== 在插件中注册事件监听器 ===
The registerEvents method requires a listener and a plugin. Luckily, we already have our LoginListener. Now for the LoginPlugin!
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
getServer().getPluginManager().registerEvents(new LoginListener(), this);
}
}</source></blockquote>

==== 在实现监听器接口的插件中注册事件监听器 ====
<ref>准确来说是在实现了监听器接口的继承了JavaPlugin的类中注册事件（笑</ref>
You could even have the events in the main class, for example:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginPlugin extends JavaPlugin implements Listener {
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

=== 在监听器中注册事件监听器 ===
There are many ways to register your events. Here's an example where you register them in your listener class.
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
public LoginListener(LoginPlugin plugin) {
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

The LoginPlugin would look like this:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
new LoginListener(this);
}
}</source></blockquote>

== 在监听器中注销事件监听器 ==
You can un-register individual events, entire listener classes or all events registered by your plugin or even by other plugins!

==== 注销特定的事件监听器 ====
Each event class has the getHandlerList() static method, call that and then you can use .unregister() method.
Example:
<blockquote><source lang="java">
PlayerInteractEvent.getHandlerList().unregister(plugin);
// this will unregister all PlayerInteractEvent instances from the plugin
// you can also specify a listener class instead of plugin.
</source></blockquote>
Now you know why you'll need the getHandlerList() in your custom events.

==== 注销所有事件监听器 ====
Using the HandlerList class and its unregisterAll() static method you can easily unregister events from listener classes or plugins.
Example:
<blockquote><source lang="java">
HandlerList.unregisterAll(plugin);
// this will unregister all events from the specified plugin
// you can also specify a listener class instead of plugin.
</source></blockquote>

== 创建自定义事件 ==
Creating custom events is very simple, you can use the same system that Bukkit uses without ruining performance.

There are two (2) things to keep in mind when you create a Custom Event. They are "extend Event" and "static handlers." With static handlers, you must input the following code into your custom event:

<blockquote><source lang="java">private static final HandlerList handlers = new HandlerList();

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}</source></blockquote>
This block of code makes the EventHandlers contained inside your own event, keeping any unrelated events completely separated.

=== 自定义事件示例 ===
The following example shows how easy it is to create your own "CustomEvent."
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

public final class CustomEvent extends Event {
private static final HandlerList handlers = new HandlerList();
private String message;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

==== 调用你的自定义事件 ====
You are in control of creating and calling your events, where you call it is completely up to you. Here's an example
<blockquote><source lang="java">// Create the event here
CustomEvent event = new CustomEvent("Sample Message");
// Call the event
Bukkit.getServer().getPluginManager().callEvent(event);
// Now you do the event
Bukkit.getServer().broadcastMessage(event.getMessage());</source></blockquote>

Remember: You are in control of your events. If you don't call it, and act upon it, it doesn't happen!

==== 监听一个自定义事件 ====
How do you listen to a custom event you say? Simple, the same way as listening to a normal event!
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public final class CustomListener implements Listener {
@EventHandler
public void normalLogin(CustomEvent event) {
// Some code here
}
}</source></blockquote>

==== 使得你的自定义事件具有可撤销性 ====
如果你想让你的自定义事件可以被撤销，记得，要“继承Cancellable类”。就像你继承Listener那样。这十分简单，让我向你展示一个例子！
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.event.Cancellable;

public final class CustomEvent extends Event implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private String message;
private boolean cancelled;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public boolean isCancelled() {
return cancelled;
}

public void setCancelled(boolean cancel) {
cancelled = cancel;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

之后，你需要在你执行相应代码前，检查一下是否有插件把你的事件撤销掉了。
<blockquote><source lang="java">// 创建一个事件对象
CustomEvent event = new CustomEvent("Sample Message");
// 触发事件
Bukkit.getServer().getPluginManager().callEvent(event);
// 检查一下是否事件被撤销
if (!event.isCancelled()) {
// 现在在这里做些什么吧！
Bukkit.getServer().broadcastMessage(event.getMessage());
}</source></blockquote>

== 视频教程 ==
If you would prefer to watch a video tutorial version of this, please click [http://www.youtube.com/watch?v=PWQNsqwD-AY here].
<references />
[[Category: Tutorials]]

Bukkit/插件开发教程

2016-08-19T08:04:39Z

Tdiant：

{{待完善}}
{{待更新|url=http://wiki.bukkit.org/Plugin_Tutorial}}
本页面英文原文内容来源 [http://wiki.bukkit.org/Plugin_Tutorial]

== 介绍 ==

这篇内容丰富的教程旨在帮助你学会如何开发Bukkit插件.这一篇教程不可能完全涉及到Bukkit中所有的可能性,而是最基本的一般概述. 前提是你懂得Java这门语言,并在IDE中设置好你的工作区,此教程介绍了大多数Bukkit插件所必需的语法结构.

== 学习Java ==

'''理解这些教程需要具备Java这门编程语言的基本知识.'''如果你刚开始学习Java或者需要重温一下相关知识，下面有一个并不完整的网站列表可供参考.

<big>[http://docs.oracle.com/javase/tutorial/ Oracle's Java Tutorials]</big> - 官方教程
*[http://www.java2s.com/Tutorial/Java/CatalogJava.htm Java2s.com] - 教程
*[http://www.javacoffeebreak.com/java101/java101.html Java 101] - 教程
*[http://math.hws.edu/javanotes/ JavaNotes] - 免费的在线教科书
*[http://thenewboston.org/list.php?cat=31 TheNewBoston] - 视频教程.
*[http://www.yiibai.com/java/java_quick_guide.html JavaQuickGuide] - 易百快速入门教程

https://docs.oracle.com/javase/8/docs/api/ JavaSE爪哇文挡

== 开发环境 ==

在编写一个插件前 (或学习Java前) 你需要配置一个开发者环境，这个包括但不限于安装IDE (Integrated Development Environment，集成开发环境)。接下来的教程中有关于Eclipse上IDE的操作指南。

:: ''更多信息，请参见 [[Bukkit/插件开发教程-建立工作区|建立工作区]]''

你'''必须'''下载'''Java'''开发者使用的Eclipse构建版本, '''不是''' '''Java EE'''开发者的版本。 Java EE 开发者的版本不包含此教程需要的Maven支持。

或者使用更加方便快捷的NetBeansIDE编写插件

[[文件:NetBeanIDE-FristSee.jpg]]

下载地址：

https://netbeans.org/downloads/index.html

下载指定的安装包

[[文件:NetBeanIDE-download.jpg]]

当然安装前需要JDK，下载网站：

http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

打开安装程序后点击
下一步 > 我接受许可证协议中的条款 > 下一步
要不要Juit你来定 > 下一步 > 安装

== 了解BukkitAPI和学看它的Javadocs ==

=== 结构与Java文档 ===
<big>工欲善其事，必先利其器</big> 我们做的是Bukkit插件，当然要了解它了

这是给菜鸟看的，高手自觉跳过

要扯到Javadocs上，关于这货的属性以后会详细解释

Javadocs 是一种关于程序的帮助文档，帮助开发者更了解程序的构造

BukkitAPI当然有Javadocs ，在 https://hub.spigotmc.org/javadocs/bukkit/ 上有

全景图

[[文件:BukkitAPI-Javadocs-1.jpg]]

[[文件:BukkitAPI-Javadocs-2.jpg]]

[[文件:BukkitAPI-Javadocs-3.jpg]]

---

解压一个服务端(Craftbukkit/Spigot)查看

[[文件:BukkitAPI-see-1.jpg]]

进入<big>org</big>文件夹 (在Java中这叫<big>包</big>)

[[文件:BukkitAPI-see-2.jpg]]

看，BukkitAPI就在这里，这是一个Spigotmc服务端，所以也可以看到spigotAPI

Spigotmc是依靠BukkitAPI的，所以spigotAPI分量很轻(自己动手去看就知道了)

[[文件:BukkitAPI-see-3.jpg]]

橙色框内的就是包，红框(及以下)是编译好的class文件

和全景图连起来看看，是不是一一对应。

额...那个...说好的<big>class</big>呢？

点击Javadocs的 org.bukkit 超链接

[[文件:BukkitAPI-Javadocs-4.jpg]]

就在这里

全景图拍摄的是<big>Overview</big> ，它显示的只是包和它的分支而已

拿 org.bukkit.block 和 org.bukkit.block.bander 举例

<big>block</big>

[[文件:BukkitAPI-Javadocs-5.jpg]]

[[文件:BukkitAPI-see-4.jpg]]

<big>block.bannder</big>

[[文件:BukkitAPI-Javadocs-6.jpg]]

[[文件:BukkitAPI-see-5.jpg]]

一般情况下，许多人说的 <big>去看API</big> 实际意思是看BukkitAPI的Javadocs

=== other ===

building …

== 新建插件开发项目 ==

=== 创建一个新的项目 ===

==== Eclipse ====

在开始工作之前，你需要先在Eclipse中配置好工作区和文件. 打开Eclipse,然后依次点击''File -> New -> Project:''来创建一个新的项目.

[[Image:Newproject.png]]

现在,打开''Maven''文件夹, 然后选择''Maven Project''.点击next,之后在下一个菜单中选择''Create a simple project'', 再次点击''Next'':
如果你看不到''Maven''文件夹, 那么你需要[http://eclipse.org/m2e/download/ 下载m2eclipse]

[[Image:Newproject2.png]]

现在，你需要给你的组用户命名，就像下面这样:
* 如果你拥有一个域名，package则填写逆转的域名地址.
** 例如: i-am-a-bukkit-developer.com 你的package地址即是com.i_am_a_bukkit_developer [http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html source]
** 避免使用一个不属于你自己的域名.
* 没有域名? 这里有几种方法可供选择。
*# 在资源管理站点创建一个用户，比如GitHub或是sourceforge
*#* 对于使用GitHub的用户, 请参照[http://pages.github.com/ 这里的说明] 之后你将获得一个子域名,所以你的package地址是io.github.<username> 
*# 使用你的邮箱. 例如: <username>@gmail.com格式的邮箱应输入com.gmail.<username> 
*# 最不济的方法.：使用独特的组名命名方式，这应当是你最后的解决方法。

以下几个地址不能作为package中的地址前缀:
* org.bukkit
* net.bukkit
* com.bukkit
* net.minecraft

完成基础的组名以后，你需要在最后加上插件的名称. 在这里用 GitHub页面作为讲解的实例. 如果你创建了一个名为 ''TestPlugin''的插件，那么完整的组名是''io.github.<username>'', 你的工程名也是 ''TestPlugin''. 至于版本，默认即可，稍后可以修改。
完成向导:

[[Image:Newproject3.png]]

如果这是你首次使用Eclipse, 点击右上角的"X" 来关闭Welcome提示页面. 现在，你的窗口视图看起来就像下面的图片这样:

[[Image:Eclipsemain.png]]

点击工程名称右边的箭头来进行下一步，现在我们正式开始。

==== Netbeans ====

先创建项目

[[文件:Nb1.jpg]]

[[文件:TNb2.jpg]]

接下来更改主类中的内容

[[文件:Nb3.jpg]]

当一个类继承Javaplugin后，它就是插件的主类

不允许其他类继承主类。

=== 添加Bukkit API ===

==== Eclipse ====

在开发插件之前，你需要添加 Bukkit API库文件到你的项目，作为一个dependency, 你也可以添加其他你想实用的API.

找到项目文件夹中部的''pom.xml''并双击进行编辑. 点击''pom.xml''中部的 tab,你将会看到下图所示内容:

[[Image:Pomeditor.png]]

如果你想使用Java 6以上版本的语言特性,你需要指定搭建项目的Java版本.复制并粘贴以下内容(设定项目只能使用Java 7及以下的版本)到 ''</project>''之前:

<code>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<nowiki><</nowiki>source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
</plugins>
</build>
</code>

你或许想使用其他版本,例如 <code>1.8</code> 使用Java 8. 请注意 [http://mcstats.org/global/ 根据MCStats数据统计], 大多数服主选择了Java 7, 所以使用Java 8会使许多服务器无法运行你的插件. 如果你使用Java 1.7的特性, Eclipse将会在报错代码"error"中建议你更改语言版本.同意即可.

在位于代码中段的''</project>''之前粘贴以下内容(这段代码告诉Eclipse关于Bukkit's repository的地址):

<code>
<repositories>
<repository>
<id>bukkit-repo</id>
<url>http://repo.bukkit.org/content/groups/public/</url>
</repository>
</repositories>
</code>

然后继续在 ''</project>''前粘贴以下内容 (这段代码告诉Eclipse搭建插件的Bukkit版本):

<code>
<dependencies>
<dependency>
<groupId>org.bukkit</groupId>
<artifactId>bukkit</artifactId>
<version>1.7.2-R0.3</version>
<type>jar</type>
<scope>provided</scope>
</dependency>
</dependencies>
</code>

你也可以修改这里的Bukkit版本.你可以在[http://repo.bukkit.org/content/groups/public/org/bukkit/bukkit/ here]这里通过查看 maven-metadata.xml文件下的版本列表来获取可用的服务端版本号.

当你完成上述步骤后,''pom.xml''中的内容应该是这样:

[[Image:Finishedpom.png]]

通过菜单 ''File -> Save''或者按住 <code>Ctrl + S</code> 来保存''pom.xml''文件 . 之后, 右键项目标题，然后依次选择 ''Maven -> Update Project''.

==== NetBeans ====

这个相对简单，先创建库

[[文件:NetBeansIDE-lib.jpg]]

[[文件:NetBeansIDE-lib-setin.jpg]]

然后添加<库类路径>，一般是服务端核心文件

[[文件:NetBeansIDE-lib-use.jpg]]

由此完成设置

=== Bukkit Java文档 ===

如果你曾经使用过Eclipse和Java，你会知道当你将鼠标准心移至class或者 method中的代码部分时，一个含有相关文档内容的黄色小框会弹出来. 这就是（Java的）Java文档。

你可以[http://download.oracle.com/javase/6/docs/api/ Oracle website 在线获取]它.。Bukkit同样拥有文档，这些文档内容包含了关于API中method和class的有用描述。

你可以在[http://jd.bukkit.org/ 这]找到它 (Beta版的Java文档在[http://jd.bukkit.org/ 这]找, 新开发出来的Java文档在

[http://jd.bukkit.org/ 这]) 。为了在Eclipse里使用Java文档,这样的话当你的鼠标停留在Bukkit的class和method上时，

（Bukkit的）Java文档就会冒出来。
JavaDoc in spigot [https://hub.spigotmc.org/javadocs/bukkit/ Click Here]

首先右键在侧边栏里的"Maven Dependencies"下面的Bukkit jar,选择"Properties".选中窗口左边的''Javadoc Location'', 并粘贴如下网址

'''http://jd.bukkit.org/''' (或者上面的测试版/最新版 Java文档链接也好) 到"Javadoc URL"下面的输入框内. 就像这样:

[[Image:Bukkitjavadocs.png]]

点击 "Validate",然后再点击"OK"就完成了.现在Bukkit Javadocs已经连接到Bukkit提供的资源,同时你也可以通过Eclipse来获得帮助类文档信息了.

=== 创建一个包 ===

现在你需要创建一个包，它将储存所有我们需要使用的Java类文件. 右键展开''src/main/java''折叠并选择 ''New > Package'':

[[Image:Newpackage.png]]

包名的话，先写上你的组名，然后加个点，再写上你的小写Artifact ID。举例, 如果你的组名是''io.github.name''，你的artifact名是 ''TestPlugin''。

你的包名就应该是''io.github.name.testplugin''.

=== 创建插件的类文件 ===

既然我们已经建立好了我们的项目，我们接下来可以开始添加类文件以及制作插件了. 插件的主类指的是拓展(extends)JavaPlugin的类文件. 在你的插件中只能有一个类文件拓展JavaPlugin，无论直接还是间接. 先创建你的主类文件并保持名称与插件名一致是个很好的习惯.右键你之前新建的包,并选择  ''New > Class''.你将会创建一个新的类文件，就像下面这样

package {$GroupName}.{$ArtifactName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$ArtifactName} extends JavaPlugin {

}

警告：插件绝对不应该调用自己的构造函数并实例化

=== 创建plugin.yml ===

你已经创建了项目和主类，如果你想要Bukkit能够加载你的插件，你还必须创建 '''[[Plugin YAML|plugin.yml]]''' 文件. 这个文件包含有基础的插件信息，如果缺失这个文件，你的插件也将会失效. 此时你需要右键''src/main/resources''. 选择''New > File''. 命名为"'''plugin.yml'''" 并右键完成新文件的创建.Eclipse会打开默认的文本编辑窗口来显示'''plugin.yml'''文件中空白的内容并提供编辑. ''(Hint: 如果你想要使得你的工作空间更加规整，关闭文本编辑器并将'''plugin.yml''' 文件拖到主工作空间(拖到文件目录的右边) 之后你就可以在eclipse中编辑文件了.)''

有三个基础的内容需要在plugin.yml写明.
: name: 插件名称.
: main: [http://docs.oracle.com/javase/specs/jls/se7/html/jls-6.html#jls-6.7 插件主类的完整，合法名称] .
: version: 插件当前版本号.

最简单的 '''plugin.yml''' 文件内就像这样 :

name: {插件名称}
main: {包名}.{主类}
version: {版本号}

PS:插件的包名经常会包括插件的名称，所以看到这个的时候不要感到惊讶。
你的主类是否是你的插件名取决于你之前的命名方式，时刻记住这一点很重要。

'''''更多例子''', 请看[[#Example_Files_and_Templates]]''

此时你的插件已经可以被Bukkit加载了,同时服务端日志也会开始记录你的插件. 不过它现在什么用都没有!

== onEnable()和onDisable()方法 ==

这些方法将在插件启用与卸载时生效. 默认情况下，你的插件在被加载时会调用这些方法，所以你可以在这里注册你需要用到的事件和提供一些调试信息. <code>onEnable()</code> 方法会在插件启用时被调用, 需要包含初始化插件的逻辑语句. <code>onDisable()</code> 方法会在插件卸载时被调用，需要包含清理(clean up)插件的逻辑语句和连接声明(associated state)。此外，插件可以重写 <code>onLoad()</code> 方法来在插件载入时执行附加的逻辑语句。

=== onEnable()和onDisable()方法介绍 ===

在前面的章节中，我们在主类创建了<code>onEnable()</code> 和 <code>onDisable()</code> 方法. 此时，这些代码看起来就像下面这样

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
// 插件载入时要执行的代码（略）
}

@Override
public void onDisable() {
// 插件卸载时要执行的代码（略）
}
}

这些方法已经创建，但目前它们还没有任何作用.
注意: 不需要添加代码来实现输出信息"{$PluginName} has been enabled!" ，因为bukkit会自动输出此类信息
有关更多事件的信息请查看 [[Event_API_Reference|这里]].

=== 发送提示信息 ===

插件能够输出信息至控制台与服务器日志。这是通过调用插件记录器里正确的方法来实现的。首先我们必须调用 <code>getLogger()</code> 方法来检索该插件的记录器，

然后我们就可以开始记录信息了。

我们通过调用<code>onEnable()</code>方法可以实现输出信息。我们需要在<code>onEnable()</code>方法下面插入如下代码：

getLogger().info("onEnable has been invoked!");

在 <code>'''onDisable()'''</code>方法里面，你也可以做类似的事情，不过要改改输出信息。

此时你的主类文件就像这样:

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
getLogger().info("onEnable has been invoked!");
}

@Override
public void onDisable() {
getLogger().info("onDisable has been invoked!");
}
}

=== 防止重载后插件失效 ===

你需要知道的是，插件并不只会伴随服务器关闭、启动而重载，你的插件也可能会被其他插件启用、关闭，或是在服务器运行时使用/reload命令.
假设服务器启动之后一会儿后，你的插件才被启用，这时便是危险的,因为服务器中可能已经有玩家在线、额外的世界被加载以及很多预想不到的不同之处(与"插件同服务器同时加载"的情况相比较).

举个例子来说:
* 你有一个用来储存HashMap中的玩家登入信息的插件
* 你希望该信息对所有玩家都可见
* 一名管理员使用/reload命令
* 你的插件被卸载，所有储存的数据都丢失了
* 你的插件被再次启用时，一些玩家已经在线
* 这些玩家在HashMap并没有储存的信息
* 你试图重新获得他们的信息，但是失败了!

为了插件重载以后能够正常工作, 你需要在插件启用时加载所有已经在线的玩家的信息并将之储存在HashMap中.

for (Player player : Bukkit.getServer().getOnlinePlayers()) {
playerList.put(player.getName(), playerData(player));
}

== 监听器 ==
监听器是一种方法被调用来对事件作出反应的类.所有的监听器使用 org.bukkit.event.Listener接口.更多有关监听器创建的细节,
:: '' 请查看: [[Event API Reference]]''

== 指令 ==

=== onCommand() 方法 ===

现在你已经知道如何注册一个事件并做出响应,但是如果你只是想要在命令输入之后做出响应呢? 你可以使用 <code>'''onCommand'''</code>方法.

这个代码的作用是当玩家输入“/”时，监听该操作并执行相关语句"/" . 举个例子来说.输入 "/do something" 将会执行 <code>'''onCommand'''</code>方法.

此种情况下，因为没有特定的行为被编程，所以并不会发生任何事情。

请避免使用和bukkit所提供的指令重名的指令, 然后深思你的指令名的唯一性。

例如.指令"give"已经被好几个插件使用了, 如果你执行了另外一个"give"指令, 你的插件将会和这些插件冲突。

你必须在插件的"plugins.yml"注册你的指令否则这个方法将不会被触发。

<code>'''onCommand'''</code>方法必须返回一个布尔值（true或false）。

如果返回值是true，你不会看到什么明显的事情发生。

但如果返回值是false，则会返回你的plugin.yml里的'usage:property'然后发送给命令使用者.

当使用 <code>'''onCommand'''</code>方法时, 你需要填写4个参数.

*<code>'''CommandSender sender'''</code> - 发送命令的对象

*<code>'''Command cmd'''</code> - 被执行的指令

*<code>'''String commandLabel'''</code> - 被执行指令的别名

*<code>'''String[] args'''</code> - 该指令的自变量数组。

例如.指令 ''/hello abc def'' 中， ''abc'' 会被存放进args[0]中, ''def'' 被存放进args[1]中。

==== 设置命令 ====
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { // 如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} //如果以上内容成功执行，则返回true
// 如果执行失败，则返回false.
return false;
}

每当使用<code>'''onCommand'''</code>方法时，在每个方法后面都加上一个 return false; 是一个惯例。

返回false会显示在plugin.yml里设置的usage信息 (看下面). 用这种方法的话，一旦执行出错便会显示usage信息。

每当方法return一个值的时候，这个方法就会退出，所以return true的时候，在它下面的代码就会被跳过,

除非return语句在一个if的嵌套中，或者类似的嵌套情况。

<code>'''.equalsIgnoreCase("basic")'''</code>代表忽略英文大小写. 在这种情况下,字符串"BAsIc" 和 "BasiC"和 basic相同，代码会被照常执行。

和以前一样，加两行import在你的java文件头

import org.bukkit.command.Command;

import org.bukkit.command.CommandSender;

=== 在Plugin.yml中添加你的指令 ===

你需要添加你的指令到 '''plugin.yml''' 文件里. 如下是指令/basic添加到 '''plugin.yml'''的例子（请在plugins.yml的末尾添加如下代码）:

commands:
basic:
description: This is a demo command.
usage: /<command> [player]
permission: <plugin name>.basic
permission-message: You don't have <permission></source> </code> </blockquote>

*<code>'''basic'''</code> - 指令名称

*<code>'''description'''</code> - 指令描述

*<code>'''usage'''</code> - 在oncommand方法return false后显示的用法提示。尽量简洁, 使别人能够理解指令是什么以及如何使用它。

*<code>'''permission'''</code> - 使用该命令所需的权限节点。

*<code>'''permission-message'''</code> - 当玩家使用了这个指令而没有权限时输出的信息。

PS:yml文件使用两个空格作为制表符,使用tab键输入制表符会导致错误。

===控制台指令vs玩家指令===

你可能注意到了上文的<code>'''CommandSender sender'''</code>参数. <code>'''CommandSender'''</code> 是个Bukkit接口，

它有两个（对插件编写者）有用的子类：<code>'''Player'''</code> 和 <code>'''ConsoleCommandSender'''</code>.

所以当你编写插件的时候, 确定这个指令从控制台发出后能完全正常工作是十分必要的,

那些只能由在线玩家执行的指令 ''只能'' 由一个在线玩家执行。

有的插件在判断命令执行对象不是玩家时仅仅用return进行处理 (比如当有人从控制台发出指令),

即便这些指令能够在控制台完美运行（比如改变天气的指令）。

一个判断sender的方法:
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { //如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} else if (cmd.getName().equalsIgnoreCase("basic2")) {
if (!(sender instanceof Player)) { //如果sender与Player类不匹配
sender.sendMessage("这个指令只能让玩家使用。");
} else {
Player player = (Player) sender;
// 所需要执行的事（此处略）
}
return true;
}
return false;
}

在这个例子里，指令'''basic'''能由任何人发出 - 一个在线的玩家, 或者服务器后台的op.

但是指令'''basic2'''只能由一个在线的玩家发出.

大体上说,你应该允许尽可能多的指令在控制台和玩家聊天框里都正常执行.

需要在线玩家执行的指令可以使用以上例子中的机制来检测<code>'''CommandSender'''</code>是一个玩家.

很多指令广泛依靠于一些玩家的属性（例如可以被tp或被给予物品等等）。

如果你想更进一步, 你可以对你的指令的自变量做一些额外的检测，例如传送指令在提供玩家ID的情况下（也只有在这种情况下）可以在控制台被执行。

=== 使用独立的 CommandExecutor class ===

以上的例子必须把 <code>'''onCommand()'''</code> 方法放在插件的主类里。

对于小插件来说，这是极好的,但如果你要写一个大点的插件,把你的 <code>'''onCommand()'''</code>方法放在独立的类里将会很有意义。

幸运的是，这并不难:

*在你的包里创建一个新类. 命名为'''MyPluginCommandExecutor'''之类的 (当然，要把'''MyPlugin'''替换成你制作的插件的名字)。这个类 '''必须''' 实现Bukkit 的'''CommandExecutor'''接口。

*在你的插件的<code>'''onEnable()'''</code>方法中,你需要实例化你创建的命令执行类(CommandExecutor class), 然后做一个像下面一样的调用：<code>getCommand("basic").setExecutor(myExecutor);</code>
其中"basic"是我们需要操控的指令, <code>myExecutor</code> 是我们创建的实例.

实例:

'''MyPlugin.java''' (插件的主类):
@Override
public void onEnable() {
// 如果你没有在plugins.yml注册过指令的话，此处会抛出空指针异常！
this.getCommand("basic").setExecutor(new MyPluginCommandExecutor(this));
}

'''MyPluginCommandExecutor.java'''（独立CommandExecutor类）:
public class MyPluginCommandExecutor implements CommandExecutor {
private final MyPlugin plugin;

public MyPluginCommandExecutor(MyPlugin plugin) {
this.plugin = plugin; // Store the plugin in situations where you need it.
}

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 和以前一样执行就好…
}
}

请注意我们是如何把主类里的对象指向'''MyPluginCommandExecutor'''的. 这允许我们轻易的使用主类对象的方法（如果我们需要的话）。

这么做的话, 我们便能更好的组织代码 - 如果 <code>'''onCommand()'''</code> 方法又大又复杂, 它就能被划分为子类，从而不使插件的主类显得凌乱。

PS：如果你的插件含有多个指令的话, 你需要为每一个指令单独设立一个commandexecutor.

=== 写一个安全的指令 ===
当写一个指令的时候,别进行任何假设（很重要）, 例如假设执行者一定是个玩家. 请牢记以下原则:

==== 在命令执行前确定发出者是玩家 ====

使用简单的例子来进行检测:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (sender instanceof Player) {
Player player = (Player) sender;
// do something
} else {
sender.sendMessage("You must be a player!");
return false;
}
// do something
return false;
}

==== 检测自变量个数 ====

别老是认为玩家都能打对正确数量的自变量.

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (args.length > 4) {
sender.sendMessage("Too many arguments!");
return false;
}
if (args.length < 2) {
sender.sendMessage("Not enough arguments!");
return false;
}
}

==== 在获取玩家之前先检测他们是否在线 ====

有时你想通过命令发出者打出的ID来获取其他玩家，请确保他们在线再说！

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
Player target = (Bukkit.getServer().getPlayer(args[0]));
if (target == null) {
sender.sendMessage(args[0] + " is not online!");
return false;
}
return false;
}

如果你想对离线玩家进行操作，<code>'''OfflinePlayer'''</code>类提供了基础操作的方法.

== 插件的配置/设置 ==
Bukkit API 为插件提供了一种简便的方法，用来管理用户自定义的设置。同时，通过这种方法也可以储存数据。
:: ''详情请查看: [[Configuration API Reference]]''

== 权限 ==

利用新的Bukkit API来设置权限是再容易不过的事情. 检测玩家是否拥有权限，可以使用以下代码:
<blockquote><source lang="java">if (player.hasPermission("some.pointless.permission")) {
//执行此段代码(有权限)
} else {
//执行此段代码(无权限)
}</source> </blockquote>
你也可以检测一个权限节点是否被定义过，(等效于 Java 语言中的'''null''')，使用下面的方法:
<blockquote><source lang="java">boolean isPermissionSet(String name)</source></blockquote>
你或许对此抱有疑惑:为什么这段代码中没有任何用户群的信息？因为它们并不是必需的. 之前这段代码想要实现的主要功能之一就是根据用户群格式化聊天信息. 但其实使用权限就可以很容易地完成这项工作.你可以在聊天插件的配置文件中定义权限与前缀的对应关系. 举例来说，"someChat.prefix.admin" 权限可以对应前缀[Admin].当拥有此权限的玩家发出聊天信息时，聊天前缀便是[Admin].

另一个想要实现的主要功能则是给所有拥有权限的在线用户发一条信息.你可以这样做:
<blockquote><source lang="java">for (Player player: Bukkit.getServer().getOnlinePlayers()) {
if (player.hasPermission("send.receive.message")) {
player.sendMessage("You were sent a message");
}
}</source> </blockquote>
看到这里你可能会问，若是没有权限组我该如何配置玩家的 [[权限]] ？既然 [[Bukkit]] API 本身并没有提供用户组的预设, 你必须通过安装一款权限组插件，像 [[permissionsBukkit]] 这样的插件来帮助你配置用户群. '''API 只是提供接口而不是提供已实现的类.'''

=== 配置权限 ===
{{Hide|标题=译者注 |内容= 其一，以下代码中部分内容将以''//文字''翻译，使用时请不要加入其中内容，仅做教程中的翻译参考；
其二，default:true在下面翻译为全员默认拥有该权限，default:false则翻译为全员默认没有该权限，请注意理解。 }}
如果你想要更多地控制你的权限，例如设置权限的默认值或是子权限节点，不如将权限节点加入你的 ''[[plugin.yml]]''文件.这并不是必须的，但我们推荐你这样做. 下面是一个实例，显示了当你将权限添加在''plugin.yml''文件末尾时的样子:
<blockquote><code><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //给予使用doorman所有命令的权限
children: //子权限节点
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false
doorman.kick:
description: Allows you to kick a user //允许你踢出一名用户
default: op //OP默认拥有该权限
doorman.ban:
description: Allows you to ban a user //允许你封禁一名用户
default: op //OP默认拥有该权限
doorman.knock:
description: Knocks on the door! //敲门
default: true //全员默认拥有该权限
doorman.denied:
description: Prevents this user from entering the door //禁止拥有该权限节点的用户进入门内</source> </code> </blockquote>
值得注意的是,你的插件使用的每个权限都被定义为 ''permissions'' 这个节点的子权限节点. 每个权限都能够拥有一个描述，默认值以及子权限节点。
==== 默认值 ====

当一个权限没有明确是否为玩家所拥有 ，''hasPermission''<ref>这是一个检测玩家是否拥有指定权限节点的方法</ref> 将返回false<ref>该方法返回的boolean值</ref>. 在你的[[plugin.yml]] you can change this by setting the default node to be one of four values:

*'''true''' - 全员默认拥有该权限.
*'''false''' - 全员默认没有该权限.
*'''op''' - 如果玩家是一名OP<ref>Operator，服务器管理员</ref>，那么他将拥有该权限.
*'''not op''' - 如果玩家不是一名OP，那么他将拥有该权限.

==== 子权限 ====

在这之前你可能已经习惯了通过权限节点自动分配所有的子权限<ref>原句:Before now you will probably be used to the * permission to automatically assign all sub permissions.此处的sub permissions应是同上文“你的插件使用的每个权限都被定义为 permissions 这个节点的子权限节点.”相照应</ref>. 现在这种方法已经随着bukkit API<ref>应用程序编程接口(Application Programming Interface)</ref>的更新而改变，现在你可以自己定义子权限了. 这将使得插件具有更多的灵活性. 下面是一个例子:
<blockquote><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //翻译见上
children:
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false</source> </blockquote>
在这里，''doorman.*'' 权限拥有几个子权限并分配在其下. 子权限工作的方式就是当''doorman.*'' 权限节点被设置为true时,子权限也会随之设置为 ''plugin.yml''中的默认值. 然而当''doorman.*'' 被设置为false时，所有子权限都会设置为与默认值相反的值（true->false,false->true）.
<references />

=== 设置你自己的权限 ===

如果你希望想知道更多有关开发你自己的权限插件的事情(即是设置权限的管理类插件) ，那么请前往查看教程 [[Developing a permissions plugin]].

== 计划任务与后台任务 ==

目前, Minecraft服务器都使用一个线程进行所有逻辑操作, 所以每个发生在游戏中的逻辑运算必须要很短. 如果处理不好的话, 复杂的代码可能会导致你的服务器逻辑运算有极大的延迟和滞后.

幸运的是, Bukkit正在帮助你安排你的插件源代码. 你可以提交一个在未来能够运行一次的可运行任务, 或者一个基础的循环, 或者你可以拆分出一个新的与游戏逻辑并行的线程, 用来执行过于冗长的任务.

这里 [[Scheduler Programming]] 单独写出了计划程序的教程, 并给出了更多你可以用来安排同步任务的信息, 还有启动Bukkit的异步进程.

== 方块操控 ==

这是一个很容易的方法创建、获取或修改一个方块, 例如当你想要修改往你头上数第五格的方块时, 首先你需要做的是获取你当前的坐标点, 然后往你当前的坐标点的Y轴加上五, 获取目标方块后我们便能够很容易地修改它了, 例子如下:
<blockquote><source lang="java">
@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
// 得到玩家当前的坐标.
Location loc = event.getPlayer().getLocation();
// 设置目标坐标为玩家头顶 5 格处.
loc.setY(loc.getY() + 5);
// 得到目标坐标的方块
Block b = loc.getBlock();
// 将目标坐标的方块更改为石头 (stone).
b.setType(Material.STONE);
}</source> </blockquote>
上面的代码获取了玩家的所在位置，获取头上的第五个方块，并且放上一个石头（stone）。 Note that once you have a <code>Block</code>, there are other things you can do besides set its type. 你可以查阅JavaDoc获取更多的东西。

你可以用这样相似的观念去生成一些建筑，并且还可以用编程的方式通过算法生成一些独特的方块（这里指由很多个方块拼在一起的四四方方的方块）。比如，去生成一个实心的方块建筑，你可能在生成建筑的时候还需要用到<code>for</code>循环，去一遍遍循环来生成这些建筑，填满这些建筑等。
下面，是一个在指定坐标生成一个实心的方块建筑的实例方法：
<blockquote><source lang="java">
public void generateCube(Location loc, int length) {
// 放置这个方块最中间的方块并且获取这个方块的坐标。
// Uses getBlockN() instead of getN() to avoid casting to an int later.
int x1 = loc.getBlockX();
int y1 = loc.getBlockY();
int z1 = loc.getBlockZ();

// Figure out the opposite corner of the cube by taking the corner and adding length to all coordinates.
int x2 = x1 + length;
int y2 = y1 + length;
int z2 = z1 + length;

World world = loc.getWorld();

// Loop over the cube in the x dimension.
for (int xPoint = x1; xPoint <= x2; xPoint++) {
// Loop over the cube in the y dimension.
for (int yPoint = y1; yPoint <= y2; yPoint++) {
// Loop over the cube in the z dimension.
for (int zPoint = z1; zPoint <= z2; zPoint++) {
// Get the block that we are currently looping over.
Block currentBlock = world.getBlockAt(xPoint, yPoint, zPoint);
// 设置方块ID为57号(钻石块!)
currentBlock.setType(Material.DIAMOND_BLOCK); //这里下面会提到
}
}
}
}</source></blockquote>
这个方法将会在程序给予这个方法高度和起始坐标（最中间的方块的坐标）时，构建一个3D的方块建筑。简单的删除方块也可以使用这个方法的思路实现，但是，但是设置方块的时候，记得把上面标注会提到的那行，设置为物品ID为0的方块(空气方块)。 
<blockquote></blockquote>

== (玩家)修改背包 ==

这个部分大部分讲的是修改玩家的背包。但是在某些情况下，修改箱子里的内容与此相同，当然得在你能找到获取箱子里内容的方法才可以。 :P. 这是一个修改玩家背包的一个例子:
<blockquote><source lang="java">public void onPlayerJoin(PlayerJoinEvent evt) {
Player player = evt.getPlayer(); // 当玩家加入游戏
PlayerInventory inventory = player.getInventory(); // 获取玩家背包列表
ItemStack itemstack = new ItemStack(Material.DIAMOND, 64); // 生成一组钻石

if (inventory.contains(itemstack)) {
inventory.addItem(itemstack); // 将一组钻石放到玩家的背包里
player.sendMessage("Wow！你看上去很土豪啊！"); //向玩家发送消息("Wow！你看上去很土豪啊！")
}
}</source> </blockquote>
所以，上面代码里面的 onPlayerJoin 方法中，我们首先构建了一些变量<ref>或许应该是实例化的对象？不过原文中是variables，故此处直译 </ref>，让我们的工作变得更容易一些。变量分别是： player, inventory and itemstack。 inventory 变量是玩家的背包内容，itemstack是那64个钻石的物品栈。然后我们判断了玩家是不是有一组钻石。如果有，我们就用inventory.addItem(itemstack)方法再给玩家一组钻石，并且给他发送一个消息“Wow！你看上去很土豪啊！”。所以修改背包并不像我们想象的那么难，如果我们想实现让玩家进入游戏，检测到一组钻石后删掉这组钻石，只需要把代码里的inventory.addItem(itemstack)替换成inventory.remove(itemstack)。或许你还需要把“Wow！你看上去很土豪啊！”改成“Wow！你看上去好穷啊！”2333333。

== 控制物品 ==

当你需要写一个对物品们做出行为的代码时，你要使用ItemStack类来查阅有关那个栈的所有设置信息。
当然，你也可以干脆搞出一个特别的背包~

=== 物品容器GUI ===
你可以搞出一个类似于箱子的容器，只不过不是实体化的，它叫Inventory 。

你可以到 https://hub.spigotmc.org/javadocs/bukkit/
查找org.bukkit.inventory包了解详情

构建方法：
Inventory 变量 = Bukkit.createInventory(InventoryHolder ,int ,String);
Inventory 变量 = Bukkit.createInventory(InventoryHolder,InventoryType ,String);

所有者可以是null

大小有两种，数字（int）或类型（InventoryType），需要注意的是，使用类型时，需要使用getDefaultSize()方法获取默认的大小。

数字是9的倍数，不超过54，出来的是像箱子界面，如果超过54则...呵呵呵呵。

类型是特殊的容器，如工作台界面，具体根据名称而定。

类型列表(图片)：

[[文件:InvType.jpg]]

后面的String是你箱子的名字（标题）

代码：

<source lang="java">
Inventory inv1 = Bukkit.createInventory(null,InventoryType.CHEST , "seesaw_233");
Inventory inv2 = Bukkit.createInventory(null,54 , "§2 !seesaw!");
</source>

inv1是普通小箱子界面，黑字体标题： seesaw_233

inv2是大箱子界面,绿字体标题： !seesaw!

颜色代码（§）列表（图）：

[[文件:MinecraftColorCode.png]]

让玩家关闭容器/背包的方法:

closeInventory()

让玩家打开指定容器的方法:

openInventory(容器变量)

容器变量是你指定的Inventory变量

代码范例:

<source lang="java">
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args )
{
if(cmd.getName().equalsIgnoreCase("cg") )
{
if(args.length ==0)
{
sender.sendMessage("§4 未知命令");
}
if(args.length ==1)
{
if (sender instanceof Player)
{
Player p = (Player)sender;
if(args[0].equalsIgnoreCase("open"))
{
p.closeInventory();
p.openInventory(inv1);

}
} else{ sender.sendMessage("§4 只有玩家才可使用该命令"); }
}
}
return true;
}
</source>

=== 物品添加 ===

有了容器，没有物品怎么行？
我们需要new出一个物品~

ItemStack 变量 = new ItemStack(类型 ,数量) ;

类型同样可以是数字ID（int）或原版类型（Material）

类型太多了，请到 https://hub.spigotmc.org/javadocs/bukkit/

查看org.bukkit.Material类的静态方法 2333333333333333333~

<source lang="java">
ItemStack myitem = new ItemStack(Material.DIAMOND_PICKAXE ,1) ;
</source>

lol~

=== 附魔属性 ===

你想给一个物品附魔，你首先需要了解[http://www.minecraftwiki.net/wiki/Data_values Item Code]和[http://www.minecraftwiki.net/wiki/Talk:Enchanting#Effect_IDs Effect ID]. Enchantments他们自己不能例示(new Enchantment() won't work) 因为他们是抽象的。所以你必须要用一个EnchantmentWrapper。如果你想去附魔物品，还不想在默认的SMP里附魔，可以使用addEnchantment()里面的addUnsafeEnchantment()

<source lang="java">
int itemCode = 280; //use the item code you want here
int effectId = 20; //use the enchantment code you want here
int enchantmentLevel = 100;

ItemStack myItem = new ItemStack(itemCode); //new item of item code
Enchantment myEnchantment = new EnchantmentWrapper(effectId); //new enchantment of effect id
myItem.addEnchantment(myEnchantment, enchantmentLevel); //给物品附魔
</source>

=== 物品数据 ===
您可以通过这样做来设置物品的显示名称。
<source lang="java">
String myDisplayName = "Awesome Sword"; //这里是保存了你想要显示的名字

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //你要更改的方块
ItemMeta im = myItem.getItemMeta(); //得到方块的元数据
im.setDisplayName(myDisplayName); //设置它显示的名字
myItem.setItemMeta(im); //保存更改
</source>
你也可以设置一个物品的lore。 lore是物品的小注释, 像 "+5 攻击伤害" 在一个石剑上.
<source lang="java">
List<String> lores = new ArrayList<String>();
lores.add("123"); //第一行lore
lores.add("abc") //这条lore在123之后
ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //你的物品
ItemMeta im = myItem.getItemMeta(); //get the itemmeta of the item again
im.setLore(lores); //add the lores of course
myItem.setItemMeta(im); //give the item the new itemmeta
</source>

更多关于lore的设置和它所依靠的ArrayList参见 [[ArrayList Reference]]

=== 容器控制 ===

容器不控制咋行呢，不能让人乱来。

这次要扯到监听器，先放前置代码：

<source lang="java">
public void onInventoryClick(InventoryClickEvent event)
</source>

<source lang="java">
Inventory inv = Bukkit.createInventory(null,InventoryType.CHEST , "hello");
</source>

<source lang="java">
Player p = (Player)event.getWhoClicked();
</source>

我们先要判断操作者是不是玩家（真的有非玩家操作物品的事）

<source lang="java">
if(event.getWhoClicked() instanceof Player == false) { return;} // 如果操作对象不是玩家则返回
</source>

然后看TA是不是在操作我们指定的容器（用容器标题判定）

<source lang="java">
if (event.getInventory().getTitle().equalsIgnoreCase("hello") )
</source>

我们可以使用 getRawSlot() 来判断TA打开的是什么位置。

<source lang="java">
if(event.getRawSlot() == 0 )
</source>

需要知道的是，数组是从0开始计数的，左上角第一个格子的位置为0

具体如图所示

[[文件:InvNumber.jpg]]

如果不想让TA拿走物品，使用:

<source lang="java">
event.setCancelled(true)
</source>

但是这会有延迟，并且如果在拿走的一瞬间关闭界面可能会刷走物品

所以可以先关闭界面再打开容器

<source lang="java">
p.closeInventory();
p.openInventory(inv);
</source>

代码范例:

<source lang="java">
public void onInventoryClick(InventoryClickEvent event)
{
{
if (event.getWhoClicked() instanceof Player == false) { return;}
Player p = (Player)event.getWhoClicked();
if (event.getInventory().getTitle().equalsIgnoreCase(" §2 !DC! ") )
{
event.setCancelled(true);
p.updateInventory();
if(event.getRawSlot() == 0 )
{
p.closeInventory();
p.openInventory(inv);
}
}
}
}
</source>

版权所有，违者不究~

== Maps, and Sets, and Lists 天呐！ <ref>标题中Map,Set,List均为Java类集中的接口，故不翻译</ref> ==

除了Map类和HashMap类，Java中还提供了其它的数据结构类集。

他们提供这些不同的类，是因为有些时候，使用Map类并不合适。<nowiki>[[Java data structure classes]]</nowiki>在这个条目中，有对Java数据框架类集更深入的讲述。

=== HashMaps概览以及如何使用此接口 ===

{{模板:待修正}}
记住永远不要在一个HashMap直接使用Player玩家！

应在HashMap中使用String字符串，使用 "p.getName()" 来添加，移除或是检查列表中是否含有某个玩家.

将玩家当作object储存在HashMap中会造成大量内存泄漏(就是费机器资源).

当做一个插件时，你会得到一个点，只使用单变量事件发生或条件已经满足不了由于多个玩家执行的动作/事件。

这是我的问题，我有一个旧的插件，Zones，现在被改进，重新命名为Regions 。我得到了这些错误的大部分，因为我没有考虑插件会如何在一个实际的服务器上的行为，在任何给定的时间超过一个。我过去使用一个独立的布尔值变量来检测玩家是否在选区中，显然当每个玩家的值需要被区分开来时这个方法将不能正常工作。所以如果一个玩家在选区内而另一个在选区外，那么这个变量将会一直保持改变，因此也会造成许多错误。

HashMap是这样做的一个好方法。HashMap是一种映射/分配的一个关键值。你可以设置HashMap，关键是玩家的值可以做你想做的事情，但与HashMap的有用的东西是一个key的只能包含一个值，不能有重复的key。比如说，我把“adam”作为key，并赋予它“a”的值。那工作的打算，但后来说，后来我想指定值“B”为重点的“adam”我能会没有错误，但价值”“分配到关键的“adam”在HashMap将覆盖因为与哈希图不包含重复的值。

==== Defining a HashMap ====

<source lang="java">
public Map<KeyType, DataType> HashMapName = new HashMap<>(); //Example syntax
// Example Declaration
public Map<String, Boolean> pluginEnabled = new HashMap<>();
public Map<String, Boolean> isGodMode = new HashMap<>();
</source>

记住代码因为我们会使用它的教程的其余部分在与哈希图。因此，例如，我们可以创建一个简单的函数，它将切换插件是否已启用或不启用。首先，在你的命令功能中，我解释了你需要创建一个函数，将玩家的名字发送到函数，并相应地调整玩家的状态。

所以在命令的内部，你需要这个，函数名可以是不同的，但为了简单，它是最好的，如果你保持不变。

public boolean onCommand(Commandsender sender, Command cmd, String label, String args[])

<source lang="java">
Player player = (Player) sender;
togglePluginState(player);
</source>

这上面的代码将发送到玩家的值传递给函数的参数togglepluginstate()

但现在我们需要建立我们的togglepluginstate()功能。

<source lang="java">
public void togglePluginState(Player player)
{
// 请注意我们如何使用这个玩家名为这里的 key
// 不是玩家对象
String playerName = player.getName();

if (pluginEnabled.containsKey(playerName))
{

if (pluginEnabled.get(playerName))
{
pluginEnabled.put(playerName, false);
player.sendMessage("Plugin disabled");
}
else
{
pluginEnabled.put(playerName, true);
player.sendMessage("Plugin enabled");
}
}
else
{
pluginEnabled.put(playerName, true);
//如果你想要的插件默认情况下为禁用更改此值为 false
player.sendMessage("Plugin enabled");

}

}
</source>

现在，这个代码是做个检查，如果HashMap首先包含的关键玩家，所以如果它被放入HashMap，如果那时候我们检查HashMap关键值获得（玩家）；如果这是真的然后设定值假送玩家一个消息，如果这个值是false，然后做相反，设定值为true，发送一个消息了。但如果HashMap不包含关键的玩家，那么我们可以认为这是他们的第一次运行/使用所以我们改变默认值，增加玩家的HashMap

==== More Ideas for HashMaps ====

一个HashMap（或是任何一种Map在Java）是一个关联系统。它可以快速、高效地查找某种值，赋予独特的key。在任何情况下，这会发生在您的代码，地图可能是您的解决方案。

这里有一些其他的想法非常适合使用map。正如你所看到的，它不必是你存储的数据或你的玩家，但可以是任何类型的数据，需要“翻译”从一个形式到另一个。

===== Data Value Lookups =====

<source lang="java">
public Map<String, Integer> wool_colors = new HashMap<>();
// Run this on plugin startup (ideally reading from a file instead of copied out row by row):
wool_colors.put("orange", 1);
wool_colors.put("magenta", 2);
wool_colors.put("light blue", 3);
wool_colors.put("black", 15);
// Run this in response to user commands - turn "green" into 13

int datavalue = 0;
public boolean onCommand(Commandsender sender, Command cmd, String label, String args[])
if (wool_colors.containsKey(argument))
{ datavalue = wool_colors.get(argument); }
else
{
try
{ datavalue = Integer.parseInt(argument); }
catch (Exception e) {}
}
</source>

==== Saving/Loading a HashMap ====

一旦你知道如何使用与哈希图，你可能想知道如何保存和加载的HashMap数据。

*您不希望管理员手动编辑数据

* 你需要以二进制格式保存数据

*你想避免解析块名称和/或其他物体从任意文本上

这是很简单的方法如何保存任何HashMap。你可以替换HashMap ,amp ,String, Integer；任何你想要的HashMap类型。让我们举个例子让HashMap代码保存它：

<source lang="java">
HashMap<String, Integer> mapToSave = new HashMap<String,Integer>();

public void save(HashMap<String, Integer> map, String path)
{
try
{
ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));
oos.writeObject(map);
oos.flush();
oos.close();
}
catch(Exception e) // Hand a IOexceptions
{ e.printStackTrace(); }
}
// ...
save(mapToSave, getDataFolder() + File.separator + "example.bin");
</source>

你可以看到它真的很容易。加载工作非常相似但我们使用对象输入流而不是对象，而是个FileInputStream，代替writeobject() 让我们返回HashMap。

<source lang="java">
public HashMap<String, Integer> load(String path)
{
try
{
ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));
Object result = ois.readObject();
// 如果你知道这文件中的HashMap ，你可以随意投结果HashMap <字符串，整数>
return (HashMap<String, Integer>)result;
}
catch(Exception e)
{ e.printStackTrace(); }
}

// ...

HashMap<Integer, String> loadedMap;

String path = getDataFolder() + File.separator + "example.bin";

File file = new File(path);

if (file.exists()) // 检查是否有文档
{ loadedMap = load(path); }
</source>

你可以使用这个“API”保存/加载与哈希图，数组列表，并执行序列化或外部接口的所有对象。

<source lang="java">
/** SLAPI = Saving/Loading API

* API for Saving and Loading Objects.

* Everyone has permission to include this code in their plugins as they wish :)

* @author Tomsik68<tomsik68@gmail.com>

*/
public class SLAPI
{
public static <T extends Object> void save(T obj,String path) throws Exception
{
ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));
oos.writeObject(obj);
oos.flush();
oos.close();
}

public static <T extends Object> T load(String path) throws Exception
{
ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));
T result = (T)ois.readObject();
ois.close();
return result;
}
}
</source>

Example implementation of this API: <nowiki>'''</nowiki>I'm skipping some part of code in this source<nowiki>'''</nowiki>

<source lang="java">
public class Example extends JavaPlugin
{
private ArrayList<Object> list = new ArrayList<>();

@Override
public void onEnable()
{
try
{ list = SLAPI.load("example.bin"); }
catch(Exception e) // handle the exception
{ e.printStackTrace(); }
}

@Override
public void onDisable()
{
try
{ SLAPI.save(list,"example.bin"); }
catch(Exception e)
{ e.printStackTrace(); }
}
}
</source>

Note #1: 这将未修改的几乎所有知名Java类型如整型，字符串，HashMap。它还将为一些Bukkit类型以及工作。如果你在写你自己的数据对象类，你可能想利用这一技术保存它们的状态，你应该阅读关于Java的序列化或外部接口。可外化和序列化的唯一区别是，自动将所有的，序列化的类的域和试图序列化，而外部的允许你定义的阅读和写作的对象的方法。它很容易添加到您的代码，它会使您的数据持久性非常小的工作需要。没有更多的解析！

Note #2: 该API不支持变化。一旦你改变了类中的东西，你的插件的旧版本保存的数据文件将无法正确加载。

===== Tips & Examples =====

1. 简化你的储蓄结构

让要被保存的数据越简单越好, 例如: 如果你要保存一个Player对象,你可以保存该对象的UUID/Name来代替; 如果你想要保存Localtion对象, 你可以保存它的x,y,z以及World对象UUID. '''不要直接保存Bukkit的原始类型'''

2. 保存版本号以及数据

You should always remember, that you don't know what you'll be saving in the same file tomorrow. Will you ever migrate this file because of newer version of your plugin, bukkit, or minecraft? You don't know!

3. 迁移旧文件

If your plugin finds older version of some file, it should update the file accordingly and change version number.

== 元数据 ==

Bukkit正在尝试尽可能的让制作插件变得更简单，所以带有一个键值例如Player, Entity, World，甚至是一个block的HashMaps都可以用元数据取缔掉。元数据是一些替代HashMap的方式。他可以允许你去自定义"fields"给Players, Entities, Worlds and Blocks.这些东西都是元数据类的一个成员(详见[http://jd.bukkit.org/doxygen/de/d59/interfaceorg_1_1bukkit_1_1metadata_1_1MetadataValue.html#ab49975fe013a0626dd29d3b85c63a82f])It works very simply. Everything that is Metadatable holds its own HashMap of Metadata which you have access to. That means, for example, if you're creating an economy plugin, you would need a HashMap of Player and Float or Double. 如果用了元数据，你不必去做! You just attach to player new metadata 值, and that's it! 

=== 为何要去使用元数据 ===

* Metadata is all handled by Bukkit, which makes it a very good alternative to HashMaps.
* 元数据可以用来跟其他插件分享信息与数据。

=== 为什么不去使用元数据 ===

* Slightly more difficult to get the value.
* It is not saved on shutdown (but then again, neither are any Maps that you create).

=== 获取 & 设置元数据 ===

<source lang="java">
public void setMetadata(Metadatable object, String key, Object value, Plugin plugin) {
object.setMetadata(key, new FixedMetadataValue(plugin,value));
}

public Object getMetadata(Metadatable object, String key, Plugin plugin) {
List<MetadataValue> values = object.getMetadata(key);
for (MetadataValue value : values) {
// Plugins are singleton objects, so using == is safe here
if (value.getOwningPlugin() == plugin) {
return value.value();
}
}
return null;
}</source>

Note: If you're manipulating with numbers, booleans or strings, use convenient method to get the result. For example, you can use asInt(), asString() or asBoolean() instead of value to find out the value.

== Databases ==

Sometimes flat files aren't enough for what your looking to do, this is where databases come in. The most common database engines available on Linux/Mac/Windows machines typically run on some flavor of SQL (Structured Query Language).

Software offering SQL allow you to create databases with columns and header to identify to contents of each cell. Think of it as a spreadsheet on steroids, where every column you set up in your database can enforce rules to ensure integrity. Apart from being more organised than a simple custom data file, SQL provides faster access and better searching than flat files.

The SQL standard helps applications like Bukkit implement database storage for their data in a consistent way. Unfortunately, there's more than one SQL-ready database engine, and each has minor differences in how to configure and use it. Which one you choose may depend on your particular needs. (Some plugins even offer configurable options to connect to multiple database engines!)

=== SQLite ===

Alta189 has written a [http://forums.bukkit.org/threads/lib-tut-mysql-sqlite-bukkit-drivers.33849/ fantastic SQLite tutorial] which I suggest you watch if you're interested in using SQL in your plugins, included with the tutorials is a handy library you can download and import to make using SQL easier. Once you have watched these video tutorials I would suggest you go and learn some SQL syntax, it's very straightforward and shouldn't take you long to pick up. SQL Tutorials [http://www.w3schools.com/sql/default.asp @W3Schools] and [http://www.1keydata.com/sql/sql.html @1Keydata].

SQLite is great for very simple databases, because there's no server concerns to set up. Just make a few calls to create a new database and table. It's easy to back up: just copy the whole database file in one go. SQLite is a little bit weaker at data integrity, flexibility in data types, and it may not be something you would want to trust for huge databases of millions of rows. But for a new plugin in development, it's often easiest and fastest to get the SQL basics squared away with SQLite, even if you "graduate" to a more server-class database engine later.

=== MySQL ===

Another popular SQL database engine is called MySQL. It is closer to server-grade than SQLite, where many popular companies or websites depend on it for millions of webpage hits every day. With that security comes a little bit steeper learning-curve, because MySQL has more tunable parameters and capabilities.

The coding for plugins accessing MySQL is mostly the same as tiny SQLite or mega-sized Oracle, with only small differences in syntax here or there. But the administration has room to grow. You may want to set up accounts and privileges inside your MySQL setup. You may want to set up SQL scripts that organize your backups and rollback to previous states.

== 简易定时器 ==

要定时当然是用 BukkitScheduler

要定时就和long脱不了干系

long是一种整数数据类型，数值后面要加 <big>L</big> 如:

<source lang="java">
public long a = 233L ;
</source>

Java的时间单位是1000L一秒

Bukkit的时间单位是20L一秒

还要扯到Bukkit的线程系统上

Bukkit服务器是使用一条线程运行的，所以在插件里随便搞java线程是非常危险的

说白了，当你在插件里用这条代码时:

Thread.sleep(5*1000L);
// 你认为是插件“睡”五秒

整个服务器会停止五秒...

所以要用Bukkit提供的东西

这里将会使用BukkitRunnable定时

<source lang="java">
new BukkitRunnable()
{

int time = 60; // 六十秒

@Override
public void run()
{
if(time == 0)
{
cancel(); // 终止线程
return;
}
// your code ...
}

}.runTaskTimer(this, 0L, 20L);
// 插件主类延时定时
</source>

== 随机器 ==

这玩意经常出现在娱乐性插件中，主要用它来抽某个玩家

Random实现的随机算法是伪随机，也就是有规则的随机。在进行随机时，随机算法的起源数字称为种子数(seed)，在种子数的基础上进行一定的变换，从而产生需要的随机数字。

但是相同种子数的Random对象，相同次数生成的随机数字是完全相同的。这点在生成多个随机数字时需要特别注意。

接下来是使用普通jar运行，所以会有大量 <big>static</big> 关键字，请注意

<source lang="java">

public static void say(Object the) //输出
{
System.out.print(the);
}

</source>

用Random有两种方法

public static Random rd = new Random();
rd.*

(new Random()).*

接下来用第二种来讲

Random在很多地方都能学到，这里只举插件常用的int作为例子

(new Random()).nextInt(整数);

整数就是上限，随机范围从 0 ~ 整数-1

每一个随机数的几率都是相等的，也就是说 0123456789他们的几率都是 10%

但如果要随机范围最低不是0呢

放个丧心病狂的代码:

<source lang="java">
public static void ran(int start ,int to)
{
say( (new Random()).nextInt(start)+to +" ");
say( (new Random()).nextInt(start)+to +" ");
say( (new Random()).nextInt(start)+to +" ");
say( (new Random()).nextInt(start)+to +" ");
say( (new Random()).nextInt(start)+to +" ");
say( (new Random()).nextInt(start)+to +" ");
say( (new Random()).nextInt(start)+to +" ");
say( (new Random()).nextInt(start)+to +" ");
say( (new Random()).nextInt(start)+to +" ");
say( (new Random()).nextInt(start)+to +" ");
}
</source>

<source lang="java">
public static void main(String[] args)
{ ran(5,2); }
</source>

取值范围是 2 ~ 2+(5-1)

弄一方程式(设 start=x ，to=y )
x ~ x+(y-1)

结果就是(一行一次结果):
6 5 6 6 3 3 6 6 5 6
4 3 2 4 5 2 2 3 6 2
6 3 3 5 4 2 5 2 2 2

那怎么随机玩家呢，这就要扯到ArrayList了

ArrayList可以直接储存Player 所以...

看看HotPotato（烫手山芋）是怎么挑中某个倒霉的玩家的吧

<source lang="java">
public void giveRandomPotato()
{
if (getAlivePlayers().size() <= 1) // 如果只剩一个玩家
return;
GamePlayer gp = (GamePlayer)getAlivePlayers().get((new Random()).nextInt(getAlivePlayers().size() - 1)); // 就是这里
gp.getPlayer().getInventory().setHelmet(new ItemStack(Material.TNT)); // 呵呵
gp.getPlayer().getInventory().addItem(new ItemStack[] {
ItemUtil.potato()
});
potatoPlayer = gp.getPlayer();
GamePlayer gamePlayer;
for (Iterator iterator = gamePlayers.iterator(); iterator.hasNext(); MessageUtil.sendTextMessage(gamePlayer.getPlayer(), "newPotato", gp.getPlayer().getName()))
gamePlayer = (GamePlayer)iterator.next();

new PotatoTimer(this); // 另一个定时器(Boom!)
}
</source>

<source lang="java">
public List getAlivePlayers()
{
List alive = new ArrayList();
for (Iterator iterator = gamePlayers.iterator(); iterator.hasNext();)
{ // 遍历列表中的玩家
GamePlayer gamePlayer = (GamePlayer)iterator.next();
if (gamePlayer.isAlive())
alive.add(gamePlayer);
}

return alive;
}
</source>

但如果要抽取多个玩家呢?

可用方法太多，时间成本太贵，举个不是例子的例子。

其实是懒 ~

<source lang="java">

public class Support
{
public List allplayer;
public List allplayerCopy; // 拷贝
public List hider;
public List seeker;
public Random rd; // 随机器
public Support()
{
allplayer = new ArrayList()
{{
add("player01");
add("player02");
add("player03");
add("player04");
add("player05");
add("player06");
add("player07");
add("player08");
add("player09");
add("player10");
}};
allplayerCopy = new ArrayList();
allplayerCopy.clear();
allplayerCopy.addAll(allplayer);
hider = new ArrayList();
seeker = new ArrayList();
rd = new Random();
ran(3);
System.out.print("hider: "+ hider + " ");
System.out.print("seeker: "+ seeker);
}

public void ran(int amount)
{
int ta; // 数量
Object player ; // 模拟玩家
if(allplayerCopy.size() <= 1)
{ return; }
for (ta = amount;ta > 0; ta--)
{
player = allplayerCopy.get(rd.nextInt(allplayerCopy.size() )); // 抽取一个玩家
seeker.add(player);
allplayerCopy.remove(player);
}
hider.clear();
hider.addAll(allplayerCopy);
allplayerCopy.clear();
}

}

</source>

结果:

hider: [player01, player02, player03, player05, player06, player08, player10]
seeker: [player09, player07, player04]

hider: [player02, player05, player06, player07, player08, player09, player10]
seeker: [player04, player03, player01]

hider: [player01, player03, player04, player06, player07, player09, player10]
seeker: [player08, player02, player05]

不要问我10号模拟玩家(String)怎么回事，他人品好~

如果要搞几率呢？

<source lang="java">

if((new Random().nextInt(100)+1) < 50){
//50%的几率
}else{
//另外50%
}

</source>

== 部署你的插件 ==

=== Eclipse 构建方法 ===

总之你写好的你的插件,如何把它变成一个可安装在服务端的jar文件呢?

首先我们需要建立一个水桶服务器。 [http://wiki.bukkit.org/Setting_up_a_server 在这里] 能找到开服相关信息.接下来你需要把插件导出为一个.jar文件，

这样你就能在你的服务器里运行它。在Eclipse里, 右键工程，点击''Run as > Maven install''即可:

[[Image:Maveninstall.png]]

将来呢, 当你对插件进行了改动后,在做上述操作之前，如果你想删除之前的.jar文件，你可以右键工程，点击 ''Run as > Maven clean'' 。

如果你在编译插件时遇到了问题, 请检查你的JDK是否正确安装，并浏览[[建立工作区]]条目。

如果你在Eclipse控制台看到了和JDK有关的错误，你可能需要手动调整JDK,因为Eclipse的检测可能发生了错误。

点击''Window -> Preferences'', 然后是''Java -> Installed JREs''。选中你最近安装的JDK作为Java运行环境（JRE）并添加, 并取消掉原来那个报错的JDK:

[[Image:Jrelocation.png]]

如果你的工程成功被编译,JAR文件会生产在 ''target'' 目录下，具体在Eclipse的工作空间里名字为工程名的文件夹中。

这个JAR文件就是一个能正常工作的Bukkit插件了。当然前提是你的plugin.yml里没出差错。

你可以把这个jar文件丢到服务器的plugins文件夹里,重载或重启服务器,就可以测试你的新插件啦。

为了连接上使用你自己的电脑开的服务器 ,在多人游戏的ip里填上你的本地ip即可。

如果出现了错误而你又不能解决的话, 试试这里[http://forums.bukkit.org/forums/plugin-development.5/ plugin development forum],

在这里提问[http://wiki.bukkit.org/IRC bukkitdev IRC channel],或者重新阅读wiki。

当你做完了一个实用的插件,可以考虑把它发表在这里[http://dev.bukkit.org/ dev.bukkit]（为了Bukkit社区的访问量）。

以上可知,JAR格式是默认压缩生成的(JAR文件基于ZIP文件的格式)。这么说来，在上传插件到Bukkit上时把JAR文件压缩成ZIP只会增加文件体积罢了。

而且呢, 放在JAR中的config文件可以在检测不到插件目录（插件自动生成的文件夹，名字与插件名相同，里面是该插件的配置）下的config文件时自动生成。

所以我们一般不把jar文件转换成其他格式。

=== NetBeanIDE 构建方法 ===

[[文件:NetBeansIDE-build.jpg]]

然后到项目文件所在地打开dist文件夹就能看到了

== 导入其它插件 ==
你可能会希望编辑其它那些有源代码的插件. 如果插件在它的目录下有''pom.xml''(大多数知名插件,例如WorldEdit和Essentials都有),你可以通过点击''File -> Import''来把它作为一个工程导入, 然后打开''Maven''项并选择''Existing Maven Projects'':

[[Image:Importmaven.png]]

然后选择''pom.xml''所在的目录,这个工程就应该出现在你的侧边栏里了。就像平常一样编辑并编译它吧。

== 小贴士 ==

=== 使玩家着火 ===

Bukkit API有很多碉堡的功能。以下是实现一些功能的代码片段。

下面的代码运行一个玩家使另一个玩家着火。通过类似于'''/ignite Notch'''这样的指令，这个指令会让 Notch 着火。

<source lang="java">

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 使用 equalsIgnoreCase() 来忽视大小写
if (cmd.getName().equalsIgnoreCase("ignite")) {
// 确保玩家只输入了一个自变量(要被点着的玩家名).
if (args.length != 1) {
// 当return false时，该指令的使用信息会显示出来。
return false;
}

// 确保命令发出者是个玩家.
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can set other players on fire.");
sender.sendMessage("This is an arbitrary requirement for demonstration purposes only.");
return true;
}

// 获取那个要被点着的玩家. 请注意下标起始是0，不是1.
Player target = Bukkit.getServer().getPlayer(args[0]);

// 确保这个玩家在线。
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}

// 让这个玩家着火1000 ticks (一秒钟大概有20ticks,所以总共是50秒).
target.setFireTicks(1000);
return true;
}
return false;
}

</source>

=== 干掉玩家 ===

和标题一样.这里是要干掉某个玩家。

在你的onCommand方法里使用这个:

<source lang="java">

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("KillPlayer")) {
Player target = sender.getServer().getPlayer(args[0]);
// 确保玩家在线.
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}
target.setHealth(0);
}
return false;
}

</source>

这里有个小扩展,会使用一个爆炸来杀死玩家:

<source lang="java">

float explosionPower = 4F; //爆炸等级 - TNT的爆炸等级默认是4F
Player target = sender.getWorld().getPlayer(args[0]);
target.getWorld().createExplosion(target.getLocation(), explosionPower);
target.setHealth(0);

</source>

=== 创造一个假爆炸 ===

这段代码会生产一个看起来和听起来与TNT/苦力怕产生的爆炸一样的效果。但是不会对实体和方块产生破坏。在保留爆炸的艺术的同时又削弱了爆炸的威力，真是太有用了
<source lang='java'>
@EventHandler
public void onExplosionPrime(ExplosionPrimeEvent event) {
Entity entity = event.getEntity();

// 如果事件和点燃的TNT有关,执行一些代码（又略）
if (entity instanceof TNTPrimed) {
entity.getWorld().createExplosion(entity.getLocation(), 0);
}
}
</source>

=== 使一个玩家对另外一个玩家隐形 ===

通过输入指令，能让指令执行者对特定的玩家隐形。然而其他人仍然能看到指令执行者。

<source lang="java">

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("HideMe") && args.length == 1) {
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can use this command!");
return true;
}
// 检测指令执行者是玩家后，我们便可以安全的进行强制转换类操作。
Player s = (Player) sender;

// 获取命令执行者指定的玩家
Player target = Bukkit.getServer().getPlayer(args[0]);
if (target == null) {
sender.sendMessage("Player " + args[0] + " is not online.");
return true;
}
// 将 s 从 target 的视野中隐藏起来.
target.hidePlayer(s);
return true;
}
return false;
}

</source>

=== 在玩家准星所指处生产闪电 ===

如下代码运行手持鱼竿的玩家通过点击来生成闪电 (当然要用准星瞄准)。真是个简单好玩的恶作剧（。

<source lang="java">
@EventHandler
public void onPlayerInteractBlock(PlayerInteractEvent event) {
Player player = event.getPlayer();
if (player.getItemInHand().getType() == Material.FISHING_ROD) {
// 在给定坐标中生成一道闪电. 在本例中, 这个坐标是玩家准星瞄准的地方.
// 只能指向200格以内的坐标.
player.getWorld().strikeLightning(player.getTargetBlock(null, 200).getLocation());
}
}

</source>

=== 玩家摔不死 ===

<source lang="java">
@EventHandler
public void onEntityDamage(EntityDamageEvent event)
{
Entity target = event.getEntity();
org.bukkit.event.entity.EntityDamageEvent.DamageCause cause = event.getCause();
if (target instanceof Player)
{
if (cause == org.bukkit.event.entity.EntityDamageEvent.DamageCause.FALL )
{
event.setCancelled(true);
}
}
</source>

=== 自动格式 ===

Eclipse提供了将你的代码自动转成Oracle规定的格式, 修正了不符合常规的缩进, 空格等等。在侧边栏选中你的项目,然后选择''Source -> Format''即可对其进行更改。

=== 代码集锦 ===

看现成的总好过绞尽脑汁~

如果你想在动手做一个实用插件时不想死一堆脑细胞，这里是你的好去处

警告: 其中黑科技出没!

点我点我 ---> [[插件代码集中营]]

为伸手党而生~

== 插件需求专区 ==

http://forums.bukkit.org/forums/plugin-requests.13/

== 范例文件和样板 ==

*[https://github.com/Bukkit/SamplePlugin/ Bukkit/SamplePlugin on GitHub]

*[http://pastebin.com/wpeTPx7N Example.Java]

*[http://pastebin.com/MTwaAVCT ExamplePlayerListener.Java]

*[http://pastebin.com/6FLixfH3 ExampleBlockListener.Java]

*[http://pastebin.com/8UZ6pkWC ExampleEntityListener.Java]

If you have any more questions on this matter, don't hesitate to visit the BukkitDev [[IRC]] channel and ask!

[[Category:开发教程]]

Event API Reference

2016-08-15T14:16:47Z

Tdiant：/* 基础 */

[[Event API Reference/en|点击此处浏览原文]]
{{待翻译}}
== 介绍 ==

服务器里发生的事情，服务器会用'''事件''' 来告诉你。 '''Bukkit'''中有各种各样的事件，例如玩家的互动(玩家登录, 玩家点击了一个方块, 玩家死了,玩家重生...), 方块的动态(方块被放置, 方块被破坏, 方块附近的实体被改变...), 实体事件(一个怪物看上了你233, 一个苦力怕帮你收集土方块...), 世界事件 (一个世界被加载或卸载, 一个区块被加载或卸载)等等. 由于MC官方的一些原因，他们的JavaDocs都挂了= =

== 基础 ==
为了保持简单易懂，这一节只讨论一种事件——PlayerLoginEnvent。让我们从创建一个监听器开始吧。

=== 创建方法 ===
为了让你的插件能够监听并处理该事件的回调，你需要为它创建一个方法，这个方法就是事件'''监听器'''。
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你自己的代码...
}</source>
你需要向Bukkit注册你的监听器，这样服务器才会在"PlayerLoginEvent"触发时调用该监听器。我们需要给监听器打上 @EventHandler 批注。

=== @EventHandler ===
"@EventHandler" 是一个能打在某个方法上的批注，就像这样：
<source lang="java">@EventHandler // 优先级默认为NORMAL级</source>
这样一来，这所对应的方法就成为了一个优先级为NORMAL的监听器。

你可以设置EventHandler标签的EventPriority属性来自定义事件的优先级，例如：
<source lang="java">@EventHandler(priority = EventPriority.HIGHEST) // 将优先级设为HIGHEST级
@EventHandler(priority = EventPriority.LOW) // 优先级设为LOW级</source>

你的监听器应该看上去像是这样：
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你自己的代码...
}</source>

=== 添加监听器 ===
为了让Bukkit能够注册你的监听器，你需要给你的监听器所在的类实现Listener接口(org.bukkit.event.Listener)。例如这样：

<source lang="java">public final class MyPlayerListener implements Listener {
@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}
} </source>
监听器的方法名（例子中是“onlogin”的东西）并不重要；只要符合命名规则，起什么名字，你开心就好。
你可能想知道：“Bukkit怎么知道监听那个事件呢？”。Bukkit是通过上面例子中你定义的“PlayerLoginEvent”这个参数知道的。
{{warning|一个监听器只能监听一个事件，否则Bukkit是不会注册它的！}}
你的插件的主类 (就是继承JavaPlugin的那个类) 也可以成为一个事件监听器。在你的插件非常小的时候，这样就很方便了。比如:
<source lang="java">
public class MyPlugin extends JavaPlugin implements Listener {
@Override
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void onLogin(PlayerLoginEvent event) {
getLogger().log(Level.INFO, "Player " + event.getPlayer().getName() + " is logging in!");
}
}
</source>

=== EventHandler的参数 ===
@EventHandler 批注可以设置某些参数来改变监听器的某些作用等。在某些情况下，你可以设置这些参数:

{| class="wikitable" cellspacing="0" cellpadding="5" border="1"
|-
! 名称
! 类型
! 默认值
! 描述
! 值

|-
| priority
| EventPriority
| EventPriority.NORMAL
| 设置监听器优先级
|
* EventPriority.MONITOR
* EventPriority.HIGHEST
* EventPriority.HIGH
* EventPriority.NORMAL
* EventPriority.LOW
* EventPriority.LOWEST

|-
| ignoreCancelled
| boolean
| false
| 如果设为true，在事件被其他监听器关闭的时候，你的监听器将监听不到这个事件
|
* true
* false

|}

==== 事件优先级 ====
Bukkit中的监听器拥有六个优先级
* EventPriority.LOWEST
* EventPriority.LOW
* EventPriority.NORMAL
* EventPriority.HIGH
* EventPriority.HIGHEST
* EventPriority.MONITOR

每个插件可能会在一个事件触发时做出不同的相应，并且有的插件可能想更快的知道一个事件的发生。并且，有时候Bukkit传递事件给每个插件的时候，甚至这个事件已经被其他插件关闭了。某些情况下，其他插件刚把这个事件关掉，另外一个插件监听到了以后又把这个事件开开了。这样乱七八糟的冲突发生了以后，这就很尴尬了。

比如方块放置被触发了，LOWEST优先级的监听器将会最先对这个事件做出决定，比如关闭它什么的。然后LOW优先级的监听器将会被触发，这时候可以重写LOWEST级监听器刚刚做出的修改，以此类推。Eventually it hits monitor, and at this point nothing should change the outcome of the event. MONITOR级的监听器 should be used to see the outcome of an event, without changing any aspect of it.
If we have three plugins enabled; one is a basic area protection plugin, one is a fancy plugin using signs, and another is a logging plugin.
The protection plugin listens on Priority.LOWEST. It says they can't place blocks in this area, and cancels the event.
The fancy sign plugin listens on Priority.NORMAL. It says they can place signs here, and uncancels the event.
The log plugin listens on Priority.MONITOR. It sees that the event was actually allowed, and logs it.

If you want to change the outcome of an event, choose very carefully from LOWEST to HIGHEST. Suggested generalized protection plugins on lowest, more specific plugins on normal, and override plugins on high.
If you want to act when an event happens, but not change the outcome, use MONITOR. '''It's really really important that you use MONITOR, or an event might get cancelled after you've acted on it, and it's even more important that you don't change the outcome of the event on MONITOR or it'll break other plugins.'''

'''中文简单解释'''

优先级越高的方法越早调用

优先级再高(除了MONITOR) setCanceled() 方法也不能阻止其它插件监听到它

在MONITOR上搞 setCanceled(false) 其它插件会给你玩死~

== 注册事件(监听器) ==
要注册你的方法，包含EventHandler的类必须是implent了Listenr类的
<blockquote><source lang="java">import org.bukkit.event.Listener;

public final class LoginListener implements Listener {
}</source></blockquote>
你只需要提供一个插件和一个监听器来在PluginManager里注册它们
<blockquote><source lang="java">getServer().getPluginManager().registerEvents(Listener, Plugin);</source></blockquote>

=== 监听器示例 ===
这个监听器包含两个EventHandlers，一个监听级别是HIGH并且另一个是NORMAL。
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

=== 在插件中注册事件监听器 ===
The registerEvents method requires a listener and a plugin. Luckily, we already have our LoginListener. Now for the LoginPlugin!
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
getServer().getPluginManager().registerEvents(new LoginListener(), this);
}
}</source></blockquote>

==== 在实现监听器接口的插件中注册事件监听器 ====
<ref>准确来说是在实现了监听器接口的继承了JavaPlugin的类中注册事件（笑</ref>
You could even have the events in the main class, for example:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginPlugin extends JavaPlugin implements Listener {
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

=== 在监听器中注册事件监听器 ===
There are many ways to register your events. Here's an example where you register them in your listener class.
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
public LoginListener(LoginPlugin plugin) {
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

The LoginPlugin would look like this:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
new LoginListener(this);
}
}</source></blockquote>

== 在监听器中注销事件监听器 ==
You can un-register individual events, entire listener classes or all events registered by your plugin or even by other plugins!

==== 注销特定的事件监听器 ====
Each event class has the getHandlerList() static method, call that and then you can use .unregister() method.
Example:
<blockquote><source lang="java">
PlayerInteractEvent.getHandlerList().unregister(plugin);
// this will unregister all PlayerInteractEvent instances from the plugin
// you can also specify a listener class instead of plugin.
</source></blockquote>
Now you know why you'll need the getHandlerList() in your custom events.

==== 注销所有事件监听器 ====
Using the HandlerList class and its unregisterAll() static method you can easily unregister events from listener classes or plugins.
Example:
<blockquote><source lang="java">
HandlerList.unregisterAll(plugin);
// this will unregister all events from the specified plugin
// you can also specify a listener class instead of plugin.
</source></blockquote>

== 创建自定义事件 ==
Creating custom events is very simple, you can use the same system that Bukkit uses without ruining performance.

There are two (2) things to keep in mind when you create a Custom Event. They are "extend Event" and "static handlers." With static handlers, you must input the following code into your custom event:

<blockquote><source lang="java">private static final HandlerList handlers = new HandlerList();

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}</source></blockquote>
This block of code makes the EventHandlers contained inside your own event, keeping any unrelated events completely separated.

=== 自定义事件示例 ===
The following example shows how easy it is to create your own "CustomEvent."
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

public final class CustomEvent extends Event {
private static final HandlerList handlers = new HandlerList();
private String message;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

==== 调用你的自定义事件 ====
You are in control of creating and calling your events, where you call it is completely up to you. Here's an example
<blockquote><source lang="java">// Create the event here
CustomEvent event = new CustomEvent("Sample Message");
// Call the event
Bukkit.getServer().getPluginManager().callEvent(event);
// Now you do the event
Bukkit.getServer().broadcastMessage(event.getMessage());</source></blockquote>

Remember: You are in control of your events. If you don't call it, and act upon it, it doesn't happen!

==== 监听一个自定义事件 ====
How do you listen to a custom event you say? Simple, the same way as listening to a normal event!
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public final class CustomListener implements Listener {
@EventHandler
public void normalLogin(CustomEvent event) {
// Some code here
}
}</source></blockquote>

==== 使得你的自定义事件具有可撤销性 ====
If you ever want to make your event cancellable, remember one thing: "implements Cancellable." Just like you would import Listener. It's really that simple, let me show you an example!
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.event.Cancellable;

public final class CustomEvent extends Event implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private String message;
private boolean cancelled;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public boolean isCancelled() {
return cancelled;
}

public void setCancelled(boolean cancel) {
cancelled = cancel;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

Afterwards, you would check if a plugin had cancelled the event in your code, before processing normally
<blockquote><source lang="java">// Create the event here
CustomEvent event = new CustomEvent("Sample Message");
// Call the event
Bukkit.getServer().getPluginManager().callEvent(event);
// Check if the event is not cancelled
if (!event.isCancelled()) {
// Now you do the event
Bukkit.getServer().broadcastMessage(event.getMessage());
}</source></blockquote>

== 视频教程 ==
If you would prefer to watch a video tutorial version of this, please click [http://www.youtube.com/watch?v=PWQNsqwD-AY here].
<references />
[[Category: Tutorials]]

Event API Reference

2016-08-15T13:55:56Z

Tdiant：/* 介绍 */

[[Event API Reference/en|点击此处浏览原文]]
{{待翻译}}
== 介绍 ==

服务器里发生的事情，服务器会用'''事件''' 来告诉你。 '''Bukkit'''中有各种各样的事件，例如玩家的互动(玩家登录, 玩家点击了一个方块, 玩家死了,玩家重生...), 方块的动态(方块被放置, 方块被破坏, 方块附近的实体被改变...), 实体事件(一个怪物看上了你233, 一个苦力怕帮你收集土方块...), 世界事件 (一个世界被加载或卸载, 一个区块被加载或卸载)等等. 由于MC官方的一些原因，他们的JavaDocs都挂了= =

== 基础 ==
To keep this section simple, we're going to only work with PlayerLoginEvent. Lets start with setting up the method
为了保持简单易懂，这一节只讨论一种事件——PlayerLoginEnvent。让我们从创建一个监听/处理该事件的方法开始吧。

=== 创建方法 ===
In order for your plugin to handle an event call, you need to create a method for it:
为了让你的插件能够监听并处理该事件的回调，你需要为它创建一个方法。
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你自己的代码...
}</source>
Before this method can be invoked by Bukkit when the "PlayerLoginEvent" is fired, we need to annotate it. We do this with EventHandlers.
你还需要向Bukkit声明一下，这样服务器才会在"PlayerLoginEvent"触发时调用该函数。我们需要用到EventHandlers来做到这一点。

=== @EventHandler ===
The "@EventHandler" class is an Annotation, which goes just above your method. It looks like this:
“@EventHandler”类是一个Annotation，一般就放在你的方法上面。就像这样：
<source lang="java">@EventHandler // EventPriority（事件优先级）默认为NORMAL</source>
This marks your method as an EventHandler with the EventPriority as NORMAL.
这样一来，这一方法就标记为了一个EventPriority（事件优先级）为NORMAL的EventHandler（事件监听/处理器）。

The EventHandler can take an EventPriority to specify the priority of the method, like so:
EventHandler可以通过EventPriority来自定义事件的优先级，例如：
<source lang="java">@EventHandler(priority = EventPriority.HIGHEST) // 方法优先级设为最高
@EventHandler(priority = EventPriority.LOW) // 方法优先级设为低</source>

Here's what it would look like in your class:
你的回调函数看起来应该和下面这个相类似：
<source lang="java">@EventHandler
public void onLogin(PlayerLoginEvent event) {
// 你自己的代码...
}</source>

=== 添加监听器 ===
为了bukkit能够注册你的时间处理器，包含你事件处理方法的类必须implement了Listener接口(org.bukkit.event.Listener),例如：

<source lang="java">public final class MyPlayerListener implements Listener {
@EventHandler
public void onLogin(PlayerLoginEvent event) {
// Your code here...
}
} </source>
这个方法的名字（在上面的例子中的“onlogin”）并不重要；你可以给你的监听器任何只要你开心就好的名字。
你可能想知道：“bukkit怎么知道监听那个事件呢？”bukkit通过上面例子中你定义的“PlayerLoginEvent”这个方法的事件参数知道的。
{{warning|你必须定义一个单个的事件否则Bukkit不会注册它的}}
你的插件的主类 (即extends JavaPlugin的那个类)也可以成为一个事件监听器, 并且这个可能在你的插件非常小的时候起作用，比如:
<source lang="java">
public class MyPlugin extends JavaPlugin implements Listener {
@Override
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void onLogin(PlayerLoginEvent event) {
getLogger().log(Level.INFO, "Player " + event.getPlayer().getName() + " is logging in!");
}
}
</source>

=== EventHandler参数 ===
The @EventHandler annotation can take parameters to further define how the event handler behaves. At the moment you can specify:

{| class="wikitable" cellspacing="0" cellpadding="5" border="1"
|-
! Name
! Type
! Default
! Description
! Values

|-
| priority
| EventPriority
| EventPriority.NORMAL
| Sets the priority of your method
|
* EventPriority.MONITOR
* EventPriority.HIGHEST
* EventPriority.HIGH
* EventPriority.NORMAL
* EventPriority.LOW
* EventPriority.LOWEST

|-
| ignoreCancelled
| boolean
| false
| If set to true, your method will not get the event if the event has been cancelled
|
* true
* false

|}

==== 事件优先级 ====
There are six priorities in Bukkit that are called in the following order
* EventPriority.LOWEST
* EventPriority.LOW
* EventPriority.NORMAL
* EventPriority.HIGH
* EventPriority.HIGHEST
* EventPriority.MONITOR

Every plugin gets a say in what happens, and every plugin must get a chance to know the outcome of an event. So, we pass events to plugins even after they've been cancelled. A plugin can actually uncancel an event after another plugin cancelled it. This is where priorities become really important.

Let's say a BLOCK_PLACE event is being handled. The lowest priority listener is called to get its say in whether it should be cancelled or not. Then the low priority listener is called to see if it wants to override the lowest, etc. Eventually it hits monitor, and at this point nothing should change the outcome of the event. Monitor should be used to see the outcome of an event, without changing any aspect of it.
If we have three plugins enabled; one is a basic area protection plugin, one is a fancy plugin using signs, and another is a logging plugin.
The protection plugin listens on Priority.LOWEST. It says they can't place blocks in this area, and cancels the event.
The fancy sign plugin listens on Priority.NORMAL. It says they can place signs here, and uncancels the event.
The log plugin listens on Priority.MONITOR. It sees that the event was actually allowed, and logs it.

If you want to change the outcome of an event, choose very carefully from LOWEST to HIGHEST. Suggested generalized protection plugins on lowest, more specific plugins on normal, and override plugins on high.
If you want to act when an event happens, but not change the outcome, use MONITOR. '''It's really really important that you use MONITOR, or an event might get cancelled after you've acted on it, and it's even more important that you don't change the outcome of the event on MONITOR or it'll break other plugins.'''

'''中文简单解释'''

优先级越高的方法越早调用

优先级再高(除了MONITOR) setCanceled() 方法也不能阻止其它插件监听到它

在MONITOR上搞 setCanceled(false) 其它插件会给你玩死~

== 注册事件(监听器) ==
要注册你的方法，包含EventHandler的类必须是implent了Listenr类的
<blockquote><source lang="java">import org.bukkit.event.Listener;

public final class LoginListener implements Listener {
}</source></blockquote>
你只需要提供一个插件和一个监听器来在PluginManager里注册它们
<blockquote><source lang="java">getServer().getPluginManager().registerEvents(Listener, Plugin);</source></blockquote>

=== 监听器示例 ===
这个监听器包含两个EventHandlers，一个监听级别是HIGH并且另一个是NORMAL。
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

=== 在插件中注册事件监听器 ===
The registerEvents method requires a listener and a plugin. Luckily, we already have our LoginListener. Now for the LoginPlugin!
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
getServer().getPluginManager().registerEvents(new LoginListener(), this);
}
}</source></blockquote>

==== 在实现监听器接口的插件中注册事件监听器 ====
<ref>准确来说是在实现了监听器接口的继承了JavaPlugin的类中注册事件（笑</ref>
You could even have the events in the main class, for example:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginPlugin extends JavaPlugin implements Listener {
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

=== 在监听器中注册事件监听器 ===
There are many ways to register your events. Here's an example where you register them in your listener class.
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.player.PlayerLoginEvent;

public final class LoginListener implements Listener {
public LoginListener(LoginPlugin plugin) {
plugin.getServer().getPluginManager().registerEvents(this, plugin);
}

@EventHandler
public void normalLogin(PlayerLoginEvent event) {
// Some code here
}

@EventHandler(priority = EventPriority.HIGH)
public void highLogin(PlayerLoginEvent event) {
// Some code here
}
}</source></blockquote>

The LoginPlugin would look like this:
<blockquote><source lang="java">import org.bukkit.plugin.java.JavaPlugin;

public final class LoginPlugin extends JavaPlugin {
public void onEnable() {
new LoginListener(this);
}
}</source></blockquote>

== 在监听器中注销事件监听器 ==
You can un-register individual events, entire listener classes or all events registered by your plugin or even by other plugins!

==== 注销特定的事件监听器 ====
Each event class has the getHandlerList() static method, call that and then you can use .unregister() method.
Example:
<blockquote><source lang="java">
PlayerInteractEvent.getHandlerList().unregister(plugin);
// this will unregister all PlayerInteractEvent instances from the plugin
// you can also specify a listener class instead of plugin.
</source></blockquote>
Now you know why you'll need the getHandlerList() in your custom events.

==== 注销所有事件监听器 ====
Using the HandlerList class and its unregisterAll() static method you can easily unregister events from listener classes or plugins.
Example:
<blockquote><source lang="java">
HandlerList.unregisterAll(plugin);
// this will unregister all events from the specified plugin
// you can also specify a listener class instead of plugin.
</source></blockquote>

== 创建自定义事件 ==
Creating custom events is very simple, you can use the same system that Bukkit uses without ruining performance.

There are two (2) things to keep in mind when you create a Custom Event. They are "extend Event" and "static handlers." With static handlers, you must input the following code into your custom event:

<blockquote><source lang="java">private static final HandlerList handlers = new HandlerList();

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}</source></blockquote>
This block of code makes the EventHandlers contained inside your own event, keeping any unrelated events completely separated.

=== 自定义事件示例 ===
The following example shows how easy it is to create your own "CustomEvent."
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;

public final class CustomEvent extends Event {
private static final HandlerList handlers = new HandlerList();
private String message;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

==== 调用你的自定义事件 ====
You are in control of creating and calling your events, where you call it is completely up to you. Here's an example
<blockquote><source lang="java">// Create the event here
CustomEvent event = new CustomEvent("Sample Message");
// Call the event
Bukkit.getServer().getPluginManager().callEvent(event);
// Now you do the event
Bukkit.getServer().broadcastMessage(event.getMessage());</source></blockquote>

Remember: You are in control of your events. If you don't call it, and act upon it, it doesn't happen!

==== 监听一个自定义事件 ====
How do you listen to a custom event you say? Simple, the same way as listening to a normal event!
<blockquote><source lang="java">import org.bukkit.event.Listener;
import org.bukkit.event.EventHandler;

public final class CustomListener implements Listener {
@EventHandler
public void normalLogin(CustomEvent event) {
// Some code here
}
}</source></blockquote>

==== 使得你的自定义事件具有可撤销性 ====
If you ever want to make your event cancellable, remember one thing: "implements Cancellable." Just like you would import Listener. It's really that simple, let me show you an example!
<blockquote><source lang="java">import org.bukkit.event.Event;
import org.bukkit.event.HandlerList;
import org.bukkit.event.Cancellable;

public final class CustomEvent extends Event implements Cancellable {
private static final HandlerList handlers = new HandlerList();
private String message;
private boolean cancelled;

public CustomEvent(String example) {
message = example;
}

public String getMessage() {
return message;
}

public boolean isCancelled() {
return cancelled;
}

public void setCancelled(boolean cancel) {
cancelled = cancel;
}

public HandlerList getHandlers() {
return handlers;
}

public static HandlerList getHandlerList() {
return handlers;
}
}</source></blockquote>

Afterwards, you would check if a plugin had cancelled the event in your code, before processing normally
<blockquote><source lang="java">// Create the event here
CustomEvent event = new CustomEvent("Sample Message");
// Call the event
Bukkit.getServer().getPluginManager().callEvent(event);
// Check if the event is not cancelled
if (!event.isCancelled()) {
// Now you do the event
Bukkit.getServer().broadcastMessage(event.getMessage());
}</source></blockquote>

== 视频教程 ==
If you would prefer to watch a video tutorial version of this, please click [http://www.youtube.com/watch?v=PWQNsqwD-AY here].
<references />
[[Category: Tutorials]]

Configuration API Reference

2016-08-15T13:51:13Z

Tdiant：/* 自定义配置文件 */

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个帮助程序员们更快地解析与编辑配置文件的设置工具，让人们觉得配置文件更简单更容易编辑。不管是什么，这个API可以帮助你更容易的存储你插件的信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而，有了这个API，设计的能有更多的扩展空间，还能允许你实现其他的东西。

Configuration API可以在 org.bukkit.configuration 和 org.bukkit.configuration.file 这俩包里找到。插件的版本如果创建在 1.1-R5之前，就只能用老的并且与此不同的方法了，这些东西在org.bukkit.util.configuration这个包里。这些实现方法彼此不兼容并且老的方法因为太过时了，在新版中被删去了。

This introduction assumes that you have some knowledge about proper object oriented design, Java, and the core design of Bukkit plugins. This page is not a substitute for the JavaDocs for the [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]

== 基本论述 ==

=== 配置文件对象 ===
<ref>key 键 value 值</ref>
当你的插件主类继承了 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin]的时候, 这个类也会继承JavaPlugin这个父类的的方法和属性。在被继承的方法其中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 。

你的插件在第一次使用''getConfig()''的时候，会从你插件的jar文件中读取相应的''config.yml'' ，同时从jar中的''config.yml''加载相应的默认值。需要注意的是，第一次使用之后再调用''getConfig()''只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的。除非你手动保存了，否则你对这个对象进行的修改并不会被保存。同理，在第一次调用''getConfig()''之后，对磁盘上的config.yml文件的修改不会被反映在这个对象里。如果在plugins文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml'', 也会加载一个空的''FileConfiguration''。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''，而不是将其分配给一个变量}}

=== 键值 ===

配置文件由键值组合构成，所有的键都是字符串.值对于其他键来说可能是一个''FileConfigurationSection''或是独立的数据. ''getKeys(boolean)'' 方法会返回现有''FileConfigurationSection''集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, ''getKeys(boolean)'' 方法必须加载在特定节点. 你可以通过''getConfigurationSection(String)''方法来获取这个部分.

{{warning| getKeys(boolean)方法返回的是这里的字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的插件jar里应该为用户准备一个默认的''config.yml''。当config.yml丢失或是不完整的情况出现时，将会访问jar内的 ''config.yml''来获取默认值。准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录。你应该在jar里的''config.yml''里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

如果你想动态的把一对键值作为默认值，你可以利用''addDefault(String, Object)'' 方法和 ''addDefaults(Map<String,Object>)'' 方法。

在某些情况下，如果你想附加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

你可以使用一堆 getter 方法来获取配置文件中的值。这些 getter 方法你可以在[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html 这里]找到。每个 getter 方法 takes a configuration path detailed above. 一般条件下你应该需要这些 getter 来获取值：

*getBoolean(String) 获取键对应的类型为boolean的值
*getInt(String) 获取键对应的类型为 int 的值
*getString(String) 获取键对应的类型为 String 的值
*getList(String) 获取键对应的类型为 List 的值
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

如果你对一个 ''FileConfiguration'' 对象进行了修改操作，或者改变了某些 ''Lists''，如果你想保存你的修改，让插件被卸载了这些数据也能得以保存的话，你可以把你修改的数据保存到硬盘里。保存文件到硬盘里，你可以借助 saveConfig 方法。这会重写硬盘里的那份配置文件。 <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

如果你怀疑用户在插件数据文件夹里修改了''config.yml''，并且那些数据并没有更新在内存里。你可以用 ''reloadConfig()'' 方法重新读取插件文件夹中最新的配置文件信息，来更新内存中的数据，但这会把你内存中保存的那份数据删除，这可能会让你丢失一部分数据。 <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件来存储其他的配置信息，或储存额外的游戏信息配置文件等，你可以自己写一个你自己的方法，来仿照 <big>JavaPlugin</big> 类里的 getConfig，reloadConfig，saveConfig 方法实现这一目的。下面是一个例子，可以告诉你如何编写一个方法，来读取和保存自定义配置文件。由于这些配置文件属于你的插件，你可以把这个方法放在你的主类，这样用起来跟原来一样。你必须为每个YAML文件写的一套方法。不过你可以使用以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== Serializing and Deserializing Objects ===

The Configuration API, as mentioned above can store Java objects that implement the ''ConfigurationSerializable'' Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''. 

Classes, in addition to implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

Below is the an example plugin that uses the new Configuration API to be display messages as an MOTD as players join, and for the player to retrieve the rules on command. It does not follow proper style and plugin layout to keep the number of lines to a minimum.

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// Save a copy of the default config.yml if one is not there
this.saveDefaultConfig();

// Register a new listener
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// On player join send them the message from config.yml
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// Set the command executor for the rules command
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// On command send the rules from config.yml to the sender of the command
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> The default config.yml that is in the plugin's jar
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Configuration API Reference

2016-08-15T13:46:48Z

Tdiant：/* 保存文件 */

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个帮助程序员们更快地解析与编辑配置文件的设置工具，让人们觉得配置文件更简单更容易编辑。不管是什么，这个API可以帮助你更容易的存储你插件的信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而，有了这个API，设计的能有更多的扩展空间，还能允许你实现其他的东西。

Configuration API可以在 org.bukkit.configuration 和 org.bukkit.configuration.file 这俩包里找到。插件的版本如果创建在 1.1-R5之前，就只能用老的并且与此不同的方法了，这些东西在org.bukkit.util.configuration这个包里。这些实现方法彼此不兼容并且老的方法因为太过时了，在新版中被删去了。

This introduction assumes that you have some knowledge about proper object oriented design, Java, and the core design of Bukkit plugins. This page is not a substitute for the JavaDocs for the [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]

== 基本论述 ==

=== 配置文件对象 ===
<ref>key 键 value 值</ref>
当你的插件主类继承了 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin]的时候, 这个类也会继承JavaPlugin这个父类的的方法和属性。在被继承的方法其中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 。

你的插件在第一次使用''getConfig()''的时候，会从你插件的jar文件中读取相应的''config.yml'' ，同时从jar中的''config.yml''加载相应的默认值。需要注意的是，第一次使用之后再调用''getConfig()''只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的。除非你手动保存了，否则你对这个对象进行的修改并不会被保存。同理，在第一次调用''getConfig()''之后，对磁盘上的config.yml文件的修改不会被反映在这个对象里。如果在plugins文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml'', 也会加载一个空的''FileConfiguration''。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''，而不是将其分配给一个变量}}

=== 键值 ===

配置文件由键值组合构成，所有的键都是字符串.值对于其他键来说可能是一个''FileConfigurationSection''或是独立的数据. ''getKeys(boolean)'' 方法会返回现有''FileConfigurationSection''集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, ''getKeys(boolean)'' 方法必须加载在特定节点. 你可以通过''getConfigurationSection(String)''方法来获取这个部分.

{{warning| getKeys(boolean)方法返回的是这里的字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的插件jar里应该为用户准备一个默认的''config.yml''。当config.yml丢失或是不完整的情况出现时，将会访问jar内的 ''config.yml''来获取默认值。准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录。你应该在jar里的''config.yml''里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

如果你想动态的把一对键值作为默认值，你可以利用''addDefault(String, Object)'' 方法和 ''addDefaults(Map<String,Object>)'' 方法。

在某些情况下，如果你想附加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

你可以使用一堆 getter 方法来获取配置文件中的值。这些 getter 方法你可以在[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html 这里]找到。每个 getter 方法 takes a configuration path detailed above. 一般条件下你应该需要这些 getter 来获取值：

*getBoolean(String) 获取键对应的类型为boolean的值
*getInt(String) 获取键对应的类型为 int 的值
*getString(String) 获取键对应的类型为 String 的值
*getList(String) 获取键对应的类型为 List 的值
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

如果你对一个 ''FileConfiguration'' 对象进行了修改操作，或者改变了某些 ''Lists''，如果你想保存你的修改，让插件被卸载了这些数据也能得以保存的话，你可以把你修改的数据保存到硬盘里。保存文件到硬盘里，你可以借助 saveConfig 方法。这会重写硬盘里的那份配置文件。 <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

如果你怀疑用户在插件数据文件夹里修改了''config.yml''，并且那些数据并没有更新在内存里。你可以用 ''reloadConfig()'' 方法重新读取插件文件夹中最新的配置文件信息，来更新内存中的数据，但这会把你内存中保存的那份数据删除，这可能会让你丢失一部分数据。 <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件，用于存储配置信息或坚持额外的游戏信息你需要访问额外的配置文件，写下你自己的方法。仿照 <big>JavaPlugin</big> 里的 getConfig，reloadConfig，saveConfig方法，下面是一个例子，如何编写你自己的方法来读取和保存自定义配置文件。由于这些配置文件，属于你的插件，你可以把这个方法在你的主类，这样你可以有相同的访问，你有config.yml 。你必须为每个YAML文件写的一套方法。这里的优势是，你可以使用都以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== Serializing and Deserializing Objects ===

The Configuration API, as mentioned above can store Java objects that implement the ''ConfigurationSerializable'' Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''. 

Classes, in addition to implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

Below is the an example plugin that uses the new Configuration API to be display messages as an MOTD as players join, and for the player to retrieve the rules on command. It does not follow proper style and plugin layout to keep the number of lines to a minimum.

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// Save a copy of the default config.yml if one is not there
this.saveDefaultConfig();

// Register a new listener
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// On player join send them the message from config.yml
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// Set the command executor for the rules command
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// On command send the rules from config.yml to the sender of the command
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> The default config.yml that is in the plugin's jar
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Configuration API Reference

2016-08-15T13:43:47Z

Tdiant：/* 从磁盘中重载配置文件 */

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个帮助程序员们更快地解析与编辑配置文件的设置工具，让人们觉得配置文件更简单更容易编辑。不管是什么，这个API可以帮助你更容易的存储你插件的信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而，有了这个API，设计的能有更多的扩展空间，还能允许你实现其他的东西。

Configuration API可以在 org.bukkit.configuration 和 org.bukkit.configuration.file 这俩包里找到。插件的版本如果创建在 1.1-R5之前，就只能用老的并且与此不同的方法了，这些东西在org.bukkit.util.configuration这个包里。这些实现方法彼此不兼容并且老的方法因为太过时了，在新版中被删去了。

This introduction assumes that you have some knowledge about proper object oriented design, Java, and the core design of Bukkit plugins. This page is not a substitute for the JavaDocs for the [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]

== 基本论述 ==

=== 配置文件对象 ===
<ref>key 键 value 值</ref>
当你的插件主类继承了 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin]的时候, 这个类也会继承JavaPlugin这个父类的的方法和属性。在被继承的方法其中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 。

你的插件在第一次使用''getConfig()''的时候，会从你插件的jar文件中读取相应的''config.yml'' ，同时从jar中的''config.yml''加载相应的默认值。需要注意的是，第一次使用之后再调用''getConfig()''只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的。除非你手动保存了，否则你对这个对象进行的修改并不会被保存。同理，在第一次调用''getConfig()''之后，对磁盘上的config.yml文件的修改不会被反映在这个对象里。如果在plugins文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml'', 也会加载一个空的''FileConfiguration''。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''，而不是将其分配给一个变量}}

=== 键值 ===

配置文件由键值组合构成，所有的键都是字符串.值对于其他键来说可能是一个''FileConfigurationSection''或是独立的数据. ''getKeys(boolean)'' 方法会返回现有''FileConfigurationSection''集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, ''getKeys(boolean)'' 方法必须加载在特定节点. 你可以通过''getConfigurationSection(String)''方法来获取这个部分.

{{warning| getKeys(boolean)方法返回的是这里的字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的插件jar里应该为用户准备一个默认的''config.yml''。当config.yml丢失或是不完整的情况出现时，将会访问jar内的 ''config.yml''来获取默认值。准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录。你应该在jar里的''config.yml''里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

如果你想动态的把一对键值作为默认值，你可以利用''addDefault(String, Object)'' 方法和 ''addDefaults(Map<String,Object>)'' 方法。

在某些情况下，如果你想附加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

你可以使用一堆 getter 方法来获取配置文件中的值。这些 getter 方法你可以在[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html 这里]找到。每个 getter 方法 takes a configuration path detailed above. 一般条件下你应该需要这些 getter 来获取值：

*getBoolean(String) 获取键对应的类型为boolean的值
*getInt(String) 获取键对应的类型为 int 的值
*getString(String) 获取键对应的类型为 String 的值
*getList(String) 获取键对应的类型为 List 的值
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

If make any changes to the''FileConfiguration'' with set methods, or mutate any ''Lists'', you will need to save the changes to disk if you wish to keep these changes after the plugin is disabled. To save the file to disk invoke the saveConfig method for your plugin, it will overwrite the file already there. <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

如果你怀疑用户在插件数据文件夹里修改了''config.yml''，并且那些数据并没有更新在内存里。你可以用 ''reloadConfig()'' 方法重新读取插件文件夹中最新的配置文件信息，来更新内存中的数据，但这会把你内存中保存的那份数据删除，这可能会让你丢失一部分数据。 <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件，用于存储配置信息或坚持额外的游戏信息你需要访问额外的配置文件，写下你自己的方法。仿照 <big>JavaPlugin</big> 里的 getConfig，reloadConfig，saveConfig方法，下面是一个例子，如何编写你自己的方法来读取和保存自定义配置文件。由于这些配置文件，属于你的插件，你可以把这个方法在你的主类，这样你可以有相同的访问，你有config.yml 。你必须为每个YAML文件写的一套方法。这里的优势是，你可以使用都以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== Serializing and Deserializing Objects ===

The Configuration API, as mentioned above can store Java objects that implement the ''ConfigurationSerializable'' Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''. 

Classes, in addition to implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

Below is the an example plugin that uses the new Configuration API to be display messages as an MOTD as players join, and for the player to retrieve the rules on command. It does not follow proper style and plugin layout to keep the number of lines to a minimum.

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// Save a copy of the default config.yml if one is not there
this.saveDefaultConfig();

// Register a new listener
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// On player join send them the message from config.yml
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// Set the command executor for the rules command
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// On command send the rules from config.yml to the sender of the command
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> The default config.yml that is in the plugin's jar
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Configuration API Reference

2016-08-15T13:41:22Z

Tdiant：/* 获得值 */

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个帮助程序员们更快地解析与编辑配置文件的设置工具，让人们觉得配置文件更简单更容易编辑。不管是什么，这个API可以帮助你更容易的存储你插件的信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而，有了这个API，设计的能有更多的扩展空间，还能允许你实现其他的东西。

Configuration API可以在 org.bukkit.configuration 和 org.bukkit.configuration.file 这俩包里找到。插件的版本如果创建在 1.1-R5之前，就只能用老的并且与此不同的方法了，这些东西在org.bukkit.util.configuration这个包里。这些实现方法彼此不兼容并且老的方法因为太过时了，在新版中被删去了。

This introduction assumes that you have some knowledge about proper object oriented design, Java, and the core design of Bukkit plugins. This page is not a substitute for the JavaDocs for the [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]

== 基本论述 ==

=== 配置文件对象 ===
<ref>key 键 value 值</ref>
当你的插件主类继承了 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin]的时候, 这个类也会继承JavaPlugin这个父类的的方法和属性。在被继承的方法其中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 。

你的插件在第一次使用''getConfig()''的时候，会从你插件的jar文件中读取相应的''config.yml'' ，同时从jar中的''config.yml''加载相应的默认值。需要注意的是，第一次使用之后再调用''getConfig()''只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的。除非你手动保存了，否则你对这个对象进行的修改并不会被保存。同理，在第一次调用''getConfig()''之后，对磁盘上的config.yml文件的修改不会被反映在这个对象里。如果在plugins文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml'', 也会加载一个空的''FileConfiguration''。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''，而不是将其分配给一个变量}}

=== 键值 ===

配置文件由键值组合构成，所有的键都是字符串.值对于其他键来说可能是一个''FileConfigurationSection''或是独立的数据. ''getKeys(boolean)'' 方法会返回现有''FileConfigurationSection''集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, ''getKeys(boolean)'' 方法必须加载在特定节点. 你可以通过''getConfigurationSection(String)''方法来获取这个部分.

{{warning| getKeys(boolean)方法返回的是这里的字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的插件jar里应该为用户准备一个默认的''config.yml''。当config.yml丢失或是不完整的情况出现时，将会访问jar内的 ''config.yml''来获取默认值。准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录。你应该在jar里的''config.yml''里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

如果你想动态的把一对键值作为默认值，你可以利用''addDefault(String, Object)'' 方法和 ''addDefaults(Map<String,Object>)'' 方法。

在某些情况下，如果你想附加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

你可以使用一堆 getter 方法来获取配置文件中的值。这些 getter 方法你可以在[http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html 这里]找到。每个 getter 方法 takes a configuration path detailed above. 一般条件下你应该需要这些 getter 来获取值：

*getBoolean(String) 获取键对应的类型为boolean的值
*getInt(String) 获取键对应的类型为 int 的值
*getString(String) 获取键对应的类型为 String 的值
*getList(String) 获取键对应的类型为 List 的值
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

If make any changes to the''FileConfiguration'' with set methods, or mutate any ''Lists'', you will need to save the changes to disk if you wish to keep these changes after the plugin is disabled. To save the file to disk invoke the saveConfig method for your plugin, it will overwrite the file already there. <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

If you suspect that users have made changes to the ''config.yml'' in the data folder, those changes are not reflected in memory. Invoke the ''reloadConfig()'' method of your plugin to load from the disk again. It will destroy all changes in memory. <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件，用于存储配置信息或坚持额外的游戏信息你需要访问额外的配置文件，写下你自己的方法。仿照 <big>JavaPlugin</big> 里的 getConfig，reloadConfig，saveConfig方法，下面是一个例子，如何编写你自己的方法来读取和保存自定义配置文件。由于这些配置文件，属于你的插件，你可以把这个方法在你的主类，这样你可以有相同的访问，你有config.yml 。你必须为每个YAML文件写的一套方法。这里的优势是，你可以使用都以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== Serializing and Deserializing Objects ===

The Configuration API, as mentioned above can store Java objects that implement the ''ConfigurationSerializable'' Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''. 

Classes, in addition to implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

Below is the an example plugin that uses the new Configuration API to be display messages as an MOTD as players join, and for the player to retrieve the rules on command. It does not follow proper style and plugin layout to keep the number of lines to a minimum.

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// Save a copy of the default config.yml if one is not there
this.saveDefaultConfig();

// Register a new listener
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// On player join send them the message from config.yml
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// Set the command executor for the rules command
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// On command send the rules from config.yml to the sender of the command
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> The default config.yml that is in the plugin's jar
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Configuration API Reference

2016-08-15T13:37:07Z

Tdiant：/* 默认值 */

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个帮助程序员们更快地解析与编辑配置文件的设置工具，让人们觉得配置文件更简单更容易编辑。不管是什么，这个API可以帮助你更容易的存储你插件的信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而，有了这个API，设计的能有更多的扩展空间，还能允许你实现其他的东西。

Configuration API可以在 org.bukkit.configuration 和 org.bukkit.configuration.file 这俩包里找到。插件的版本如果创建在 1.1-R5之前，就只能用老的并且与此不同的方法了，这些东西在org.bukkit.util.configuration这个包里。这些实现方法彼此不兼容并且老的方法因为太过时了，在新版中被删去了。

This introduction assumes that you have some knowledge about proper object oriented design, Java, and the core design of Bukkit plugins. This page is not a substitute for the JavaDocs for the [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]

== 基本论述 ==

=== 配置文件对象 ===
<ref>key 键 value 值</ref>
当你的插件主类继承了 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin]的时候, 这个类也会继承JavaPlugin这个父类的的方法和属性。在被继承的方法其中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 。

你的插件在第一次使用''getConfig()''的时候，会从你插件的jar文件中读取相应的''config.yml'' ，同时从jar中的''config.yml''加载相应的默认值。需要注意的是，第一次使用之后再调用''getConfig()''只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的。除非你手动保存了，否则你对这个对象进行的修改并不会被保存。同理，在第一次调用''getConfig()''之后，对磁盘上的config.yml文件的修改不会被反映在这个对象里。如果在plugins文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml'', 也会加载一个空的''FileConfiguration''。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''，而不是将其分配给一个变量}}

=== 键值 ===

配置文件由键值组合构成，所有的键都是字符串.值对于其他键来说可能是一个''FileConfigurationSection''或是独立的数据. ''getKeys(boolean)'' 方法会返回现有''FileConfigurationSection''集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, ''getKeys(boolean)'' 方法必须加载在特定节点. 你可以通过''getConfigurationSection(String)''方法来获取这个部分.

{{warning| getKeys(boolean)方法返回的是这里的字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的插件jar里应该为用户准备一个默认的''config.yml''。当config.yml丢失或是不完整的情况出现时，将会访问jar内的 ''config.yml''来获取默认值。准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录。你应该在jar里的''config.yml''里准备一个完整的基本结构。你可以在插件主类的适当的地方使用 saveDefaultConfig() 方法把jar里的config.yml文件从jar中复制到插件配置文件夹里。
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

如果你想动态的把一对键值作为默认值，你可以利用''addDefault(String, Object)'' 方法和 ''addDefaults(Map<String,Object>)'' 方法。

在某些情况下，如果你想附加一对新的键值给一个现存的 config.yml 文件，你可以通过通过传参布尔值 true给ConfigurationOptions对象里的copyDefaults方法来实现这一目的。
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/你的插件/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

Reading values from the configuration involves invoking one of the many getter methods. A complete list of getters can be found [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html here]. Every getter method takes a configuration path detailed above. Some of the commonly used getter methods are as follows

*getBoolean(String)
*getInt(String)
*getString(String)
*getList(String)
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

If make any changes to the''FileConfiguration'' with set methods, or mutate any ''Lists'', you will need to save the changes to disk if you wish to keep these changes after the plugin is disabled. To save the file to disk invoke the saveConfig method for your plugin, it will overwrite the file already there. <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

If you suspect that users have made changes to the ''config.yml'' in the data folder, those changes are not reflected in memory. Invoke the ''reloadConfig()'' method of your plugin to load from the disk again. It will destroy all changes in memory. <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件，用于存储配置信息或坚持额外的游戏信息你需要访问额外的配置文件，写下你自己的方法。仿照 <big>JavaPlugin</big> 里的 getConfig，reloadConfig，saveConfig方法，下面是一个例子，如何编写你自己的方法来读取和保存自定义配置文件。由于这些配置文件，属于你的插件，你可以把这个方法在你的主类，这样你可以有相同的访问，你有config.yml 。你必须为每个YAML文件写的一套方法。这里的优势是，你可以使用都以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== Serializing and Deserializing Objects ===

The Configuration API, as mentioned above can store Java objects that implement the ''ConfigurationSerializable'' Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''. 

Classes, in addition to implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

Below is the an example plugin that uses the new Configuration API to be display messages as an MOTD as players join, and for the player to retrieve the rules on command. It does not follow proper style and plugin layout to keep the number of lines to a minimum.

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// Save a copy of the default config.yml if one is not there
this.saveDefaultConfig();

// Register a new listener
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// On player join send them the message from config.yml
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// Set the command executor for the rules command
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// On command send the rules from config.yml to the sender of the command
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> The default config.yml that is in the plugin's jar
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Configuration API Reference

2016-08-15T12:56:51Z

Tdiant：/* Configuration对象 */

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个帮助程序员们更快地解析与编辑配置文件的设置工具，让人们觉得配置文件更简单更容易编辑。不管是什么，这个API可以帮助你更容易的存储你插件的信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而，有了这个API，设计的能有更多的扩展空间，还能允许你实现其他的东西。

Configuration API可以在 org.bukkit.configuration 和 org.bukkit.configuration.file 这俩包里找到。插件的版本如果创建在 1.1-R5之前，就只能用老的并且与此不同的方法了，这些东西在org.bukkit.util.configuration这个包里。这些实现方法彼此不兼容并且老的方法因为太过时了，在新版中被删去了。

This introduction assumes that you have some knowledge about proper object oriented design, Java, and the core design of Bukkit plugins. This page is not a substitute for the JavaDocs for the [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]

== 基本论述 ==

=== 配置文件对象 ===
<ref>key 键 value 值</ref>
当你的插件主类继承了 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin]的时候, 这个类也会继承JavaPlugin这个父类的的方法和属性。在被继承的方法其中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 。

你的插件在第一次使用''getConfig()''的时候，会从你插件的jar文件中读取相应的''config.yml'' ，同时从jar中的''config.yml''加载相应的默认值。需要注意的是，第一次使用之后再调用''getConfig()''只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的。除非你手动保存了，否则你对这个对象进行的修改并不会被保存。同理，在第一次调用''getConfig()''之后，对磁盘上的config.yml文件的修改不会被反映在这个对象里。如果在plugins文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml'', 也会加载一个空的''FileConfiguration''。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''，而不是将其分配给一个变量}}

=== 键值 ===

配置文件由键值组合构成，所有的键都是字符串.值对于其他键来说可能是一个''FileConfigurationSection''或是独立的数据. ''getKeys(boolean)'' 方法会返回现有''FileConfigurationSection''集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, ''getKeys(boolean)'' 方法必须加载在特定节点. 你可以通过''getConfigurationSection(String)''方法来获取这个部分.

{{warning| getKeys(boolean)方法返回的是这里的字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的jar中应该为用户准备一个默认的''config.yml''.当出现config.yml丢失或是不完整的情况时,程序将会访问jar内的 ''config.yml''来获取值.准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录. The file should have the intended structure of your ''config.yml''. This file can be copied as is into the datafolder by invoking saveDefaultConfig() on the Appropriate instance of JavaPlugin.
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

If dynamic key-value pairs are required as default values, they can added as defaults to the configuration with invocations of ''addDefault(String, Object)'' and ''addDefaults(Map<String,Object>)'' methods.

In certain cases if you wish to append new key-value pairs to an existing config.yml you can set the copyDefaults to true for the ConfigurationOptions object.
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/YourPlugin/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

Reading values from the configuration involves invoking one of the many getter methods. A complete list of getters can be found [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html here]. Every getter method takes a configuration path detailed above. Some of the commonly used getter methods are as follows

*getBoolean(String)
*getInt(String)
*getString(String)
*getList(String)
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

If make any changes to the''FileConfiguration'' with set methods, or mutate any ''Lists'', you will need to save the changes to disk if you wish to keep these changes after the plugin is disabled. To save the file to disk invoke the saveConfig method for your plugin, it will overwrite the file already there. <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

If you suspect that users have made changes to the ''config.yml'' in the data folder, those changes are not reflected in memory. Invoke the ''reloadConfig()'' method of your plugin to load from the disk again. It will destroy all changes in memory. <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件，用于存储配置信息或坚持额外的游戏信息你需要访问额外的配置文件，写下你自己的方法。仿照 <big>JavaPlugin</big> 里的 getConfig，reloadConfig，saveConfig方法，下面是一个例子，如何编写你自己的方法来读取和保存自定义配置文件。由于这些配置文件，属于你的插件，你可以把这个方法在你的主类，这样你可以有相同的访问，你有config.yml 。你必须为每个YAML文件写的一套方法。这里的优势是，你可以使用都以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== Serializing and Deserializing Objects ===

The Configuration API, as mentioned above can store Java objects that implement the ''ConfigurationSerializable'' Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''. 

Classes, in addition to implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

Below is the an example plugin that uses the new Configuration API to be display messages as an MOTD as players join, and for the player to retrieve the rules on command. It does not follow proper style and plugin layout to keep the number of lines to a minimum.

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// Save a copy of the default config.yml if one is not there
this.saveDefaultConfig();

// Register a new listener
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// On player join send them the message from config.yml
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// Set the command executor for the rules command
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// On command send the rules from config.yml to the sender of the command
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> The default config.yml that is in the plugin's jar
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Configuration API Reference

2016-08-15T12:56:24Z

Tdiant：/* Configuration对象 */

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个帮助程序员们更快地解析与编辑配置文件的设置工具，让人们觉得配置文件更简单更容易编辑。不管是什么，这个API可以帮助你更容易的存储你插件的信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而，有了这个API，设计的能有更多的扩展空间，还能允许你实现其他的东西。

Configuration API可以在 org.bukkit.configuration 和 org.bukkit.configuration.file 这俩包里找到。插件的版本如果创建在 1.1-R5之前，就只能用老的并且与此不同的方法了，这些东西在org.bukkit.util.configuration这个包里。这些实现方法彼此不兼容并且老的方法因为太过时了，在新版中被删去了。

This introduction assumes that you have some knowledge about proper object oriented design, Java, and the core design of Bukkit plugins. This page is not a substitute for the JavaDocs for the [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]

== 基本论述 ==

=== Configuration对象 ===
<ref>key 键 value 值</ref>
当你的插件主类继承了 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin]的时候, 这个类也会继承JavaPlugin这个父类的的方法和属性。在被继承的方法其中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类型的对象。这个对象就代表你插件数据文件夹里的''config.yml'' 。

你的插件在第一次使用''getConfig()''的时候，会从你插件的jar文件中读取相应的''config.yml'' ，同时从jar中的''config.yml''加载相应的默认值。需要注意的是，第一次使用之后再调用''getConfig()''只会返回内存中保存的''FileConfiguration'' 对象，而并非磁盘上保存的最新的。除非你手动保存了，否则你对这个对象进行的修改并不会被保存。同理，在第一次调用''getConfig()''之后，对磁盘上的config.yml文件的修改不会被反映在这个对象里。如果在plugins文件夹中对应的插件文件夹里不存在 ''config.yml'' ，这时会等价于存在一个空的''config.yml'', 也会加载一个空的''FileConfiguration''。

{{warning| 如果你在利用''getConfig()''的返回值，请不要把它赋给一个变量来使用}} 
{{warning| 如果需要这样的话，一定要记住在重载配置文件后，再把 ''getConfig()'' 分配给那个变量}} 
{{warning| 保险起见，推荐你尽可能的直接用''getConfig()''，而不是将其分配给一个变量}}

=== 键值 ===

配置文件由键值组合构成，所有的键都是字符串.值对于其他键来说可能是一个''FileConfigurationSection''或是独立的数据. ''getKeys(boolean)'' 方法会返回现有''FileConfigurationSection''集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, ''getKeys(boolean)'' 方法必须加载在特定节点. 你可以通过''getConfigurationSection(String)''方法来获取这个部分.

{{warning| getKeys(boolean)方法返回的是这里的字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的jar中应该为用户准备一个默认的''config.yml''.当出现config.yml丢失或是不完整的情况时,程序将会访问jar内的 ''config.yml''来获取值.准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录. The file should have the intended structure of your ''config.yml''. This file can be copied as is into the datafolder by invoking saveDefaultConfig() on the Appropriate instance of JavaPlugin.
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

If dynamic key-value pairs are required as default values, they can added as defaults to the configuration with invocations of ''addDefault(String, Object)'' and ''addDefaults(Map<String,Object>)'' methods.

In certain cases if you wish to append new key-value pairs to an existing config.yml you can set the copyDefaults to true for the ConfigurationOptions object.
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/YourPlugin/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

Reading values from the configuration involves invoking one of the many getter methods. A complete list of getters can be found [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html here]. Every getter method takes a configuration path detailed above. Some of the commonly used getter methods are as follows

*getBoolean(String)
*getInt(String)
*getString(String)
*getList(String)
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

If make any changes to the''FileConfiguration'' with set methods, or mutate any ''Lists'', you will need to save the changes to disk if you wish to keep these changes after the plugin is disabled. To save the file to disk invoke the saveConfig method for your plugin, it will overwrite the file already there. <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

If you suspect that users have made changes to the ''config.yml'' in the data folder, those changes are not reflected in memory. Invoke the ''reloadConfig()'' method of your plugin to load from the disk again. It will destroy all changes in memory. <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== 高级 ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== 菜单 ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== 自定义配置文件 ===

如果你需要额外的YAML文件，用于存储配置信息或坚持额外的游戏信息你需要访问额外的配置文件，写下你自己的方法。仿照 <big>JavaPlugin</big> 里的 getConfig，reloadConfig，saveConfig方法，下面是一个例子，如何编写你自己的方法来读取和保存自定义配置文件。由于这些配置文件，属于你的插件，你可以把这个方法在你的主类，这样你可以有相同的访问，你有config.yml 。你必须为每个YAML文件写的一套方法。这里的优势是，你可以使用都以相同的方式设置为默认设置的方法config.yml 。另外，添加额外的方法可以保持较低的计数方法，并允许访问多个文件。

==== JavaPlugin 镜像的实现 ====
javaplugin实现方法config.yml。插件需要实现它自己的方法来访问插件的配置文件。实现插件的方法后，就可以调用相同的上下文中的继承”getconfig() '、' reloadconfig() '、' saveconfig() '，和' savedefaultconfig()”方法javaplugin。以下可以做成一个类可以访问任何YAML文件。这样一个类可以在这里找到：

[https://gist.github.com/3174347 ClickHere]

首先，您需要声明2个字段，并将其初始化为每个自定义配置文件空值。一个“'fileconfiguration”对象和一个"file‘’的对象。file对象表示磁盘上的文件，和fileconfiguration代表配置的内容。

<source lang="java">
private FileConfiguration customConfig = null;
private File customConfigFile = null;
</source>

===== 实现重载 =====
然后，你写的方法负责从磁盘加载配置。它将加载文件和搜索位于jar里的默认customconfig.yml 。
<source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}
</source>

===== 实现获取 =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk.

<source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}
</source>

===== 实现保存 =====

Finally, write the save method, which saves changes and overwrites the file on disk.

<source lang="java">
public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}
</source>

===== 实施默认覆盖 =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method.
<source lang="java">
public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}
</source>

=== Serializing and Deserializing Objects ===

The Configuration API, as mentioned above can store Java objects that implement the ''ConfigurationSerializable'' Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''. 

Classes, in addition to implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== 使用样例 ==

Below is the an example plugin that uses the new Configuration API to be display messages as an MOTD as players join, and for the player to retrieve the rules on command. It does not follow proper style and plugin layout to keep the number of lines to a minimum.

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// Save a copy of the default config.yml if one is not there
this.saveDefaultConfig();

// Register a new listener
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// On player join send them the message from config.yml
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// Set the command executor for the rules command
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// On command send the rules from config.yml to the sender of the command
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules){
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> The default config.yml that is in the plugin's jar
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

WorldEdit/CraftScript

2016-01-17T10:28:37Z

Tdiant：/* 介绍 */

[[分类:开发教程]]
{{模板:待翻译}}

WorldEdit里的脚本可以让你不用Java和编译你的代码，方便地写一个操控世界的代码。这个脚本在WorldEdit中被称作''CraftScripts''，并且这一切都基于JavaScript和你的'''craftscripts/''' 文件. 使用基于WorldEdit写的脚本有这些优点:

* 能够与WorldEdit的 undo（撤销）/redo（反撤销）功能对接
* 能够使用WorldEdit来优化编辑方块的操作
* 允许使用WorldEdit强大的方块类型语法 //set sign:3|How|are|you?
* 能够轻易获取用户选择的区域空间

此脚本需要通过Mozilla Rhino JavaScript在Java 6 或更高版本上运行。但是，如果WorldEdit的路径下有一个独立的Rhino版本，它会被优先使用。为了最大化的兼容性，请在Rhino的Java稳定版本上编写脚本。
脚本支持在v0.8时曾被移除。在v2.13后，脚本支持被重新加入。然而v0.8或更低的版本的脚本并不能兼容。
{{warning|请不要运行来自不受信任的来源的脚本。}}

请查看 [http://docs.sk89q.com/ WorldEdit的API文档].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> 是一个 [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext] 的实例。
* <code>player</code> 是一个玩家的附件，是 [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer] 的实例。
* <code>argv</code> 是一个String类型的Java数组

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. 这个对象会自动处理历史和方块放置的顺序。为了得到你自己的脚本的一个编辑样本，请使用：
<source lang="java">
var sess = context.remember();
</source>
任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. 这是因为方块包含各种各样的数据（如箱子方块里面的物品），如果只有方块类型ID的话，很多数据就会被丢失。 <code>BaseBlock</code> 与block是独立的，他并不能获取得到对象所在的世界。这意味着你可以传递一个<code>BaseBlock</code> 到任何地方并重复使用他。 <code>BaseBlock</code>们记录着方块种类和数据。对于一些复杂的方块，比如说告示牌和箱子，你可以使用<code>BaseBlock</code> 就像这样<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
设置一个带有4号颜色的羊毛方块
 
<source lang="java">
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</source>

标记这个是因为 <code>BaseBlock</code> 是在''com.sk89q.worldedit.blocks'' 的命名空间,它必须被引入先. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> 有一个方块类型的列表. <code>setBlock()</code>方法的第一个参数是一个表示在一个世界的位置的<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code>。

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== 处理参数 ==

Arguments由<code>argv</code>变量传递。如果你需要去检查用户提供的参数是不是正确的，你可以用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

举个例子:检查参数 
<source lang="java">context.checkArgs(1, 3, "<block> [width] [height]");</source>

如果你要去处理一个方块名字使其成为<code>BaseBlock</code>, 你可以使用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. 这个方法可以检查方块黑名单, however. 如果你需要一个方块去, 比如说, 替换, 你可以 ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

举个例子:Getting the passed in block 
<source lang="java">
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</source>

如果用户输入的是一个无效的方块的话，将会抛出一个异常。并且，抛出异常后如果你没有去捕捉他，用户就会被提示这个异常，然后这个脚本就会被终止，就不会再进行下去。

== 配合使用Java包 ==

你可以通过使用以下的语法来引入一个Java包:

importPackage(Packages.package.name.here);

注意：如果你安装了Mozilla's Rhino库，则不需要"Packages."前缀，但为了保持在默认的Java Rhino上运行的稳定性，"Packages."前缀是推荐的。
当安装了以后，你可以使用所有Java的扩展库，以及所有WorldEdit的类。

== 例程 ==

例子:设置附近的发射器装满箭
<source lang="java">
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</source>

例子: 迷宫生成脚本
<source lang="java">
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</source>

WorldEdit/CraftScript

2016-01-17T10:26:10Z

Tdiant：/* 在方块上工作 */

[[分类:开发教程]]
{{模板:待翻译}}

WorldEdit里的脚本可以让你不用Java和编译你的代码，方便地写一个操控世界的代码。这个脚本在WorldEdit中被称作''CraftScripts''，并且这一切都基于JavaScript和你的'''craftscripts/''' 文件. 使用基于WorldEdit写的脚本有这些优点:

* 能够与WorldEdit的 undo（撤销）/redo（反撤销）功能对接
* 能够使用WorldEdit来优化编辑方块的操作
* 允许使用WorldEdit强大的方块类型语法 //set sign:3|How|are|you?
* 能够轻易获取用户选择的区域空间

此脚本需要通过Mozilla Rhino JavaScript在Java 6 或更高版本上运行。但是，如果WorldEdit的路径下有一个独立的Rhino版本，它会被优先使用。为了最大化的兼容性，请在Rhino的Java稳定版本上编写脚本。
脚本支持在v0.8时曾被移除。在v2.13后，脚本支持被重新加入。然而v0.8或更低的版本的脚本并不能兼容。
{{warning|请不要运行来自不受信任的来源的脚本。}}

请查看 [http://docs.sk89q.com/ WorldEdit的API文档].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> 是一个String类型的Java数组

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. 这个对象会自动处理历史和方块放置的顺序。为了得到你自己的脚本的一个编辑样本，请使用：
<source lang="java">
var sess = context.remember();
</source>
任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. 这是因为方块包含各种各样的数据（如箱子方块里面的物品），如果只有方块类型ID的话，很多数据就会被丢失。 <code>BaseBlock</code> 与block是独立的，他并不能获取得到对象所在的世界。这意味着你可以传递一个<code>BaseBlock</code> 到任何地方并重复使用他。 <code>BaseBlock</code>们记录着方块种类和数据。对于一些复杂的方块，比如说告示牌和箱子，你可以使用<code>BaseBlock</code> 就像这样<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
设置一个带有4号颜色的羊毛方块
 
<source lang="java">
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</source>

标记这个是因为 <code>BaseBlock</code> 是在''com.sk89q.worldedit.blocks'' 的命名空间,它必须被引入先. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> 有一个方块类型的列表. <code>setBlock()</code>方法的第一个参数是一个表示在一个世界的位置的<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code>。

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== 处理参数 ==

Arguments由<code>argv</code>变量传递。如果你需要去检查用户提供的参数是不是正确的，你可以用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

举个例子:检查参数 
<source lang="java">context.checkArgs(1, 3, "<block> [width] [height]");</source>

如果你要去处理一个方块名字使其成为<code>BaseBlock</code>, 你可以使用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. 这个方法可以检查方块黑名单, however. 如果你需要一个方块去, 比如说, 替换, 你可以 ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

举个例子:Getting the passed in block 
<source lang="java">
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</source>

如果用户输入的是一个无效的方块的话，将会抛出一个异常。并且，抛出异常后如果你没有去捕捉他，用户就会被提示这个异常，然后这个脚本就会被终止，就不会再进行下去。

== 配合使用Java包 ==

你可以通过使用以下的语法来引入一个Java包:

importPackage(Packages.package.name.here);

注意：如果你安装了Mozilla's Rhino库，则不需要"Packages."前缀，但为了保持在默认的Java Rhino上运行的稳定性，"Packages."前缀是推荐的。
当安装了以后，你可以使用所有Java的扩展库，以及所有WorldEdit的类。

== 例程 ==

例子:设置附近的发射器装满箭
<source lang="java">
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</source>

例子: 迷宫生成脚本
<source lang="java">
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</source>

WorldEdit/CraftScript

2016-01-17T10:21:19Z

Tdiant：/* 在方块上工作 */

[[分类:开发教程]]
{{模板:待翻译}}

WorldEdit里的脚本可以让你不用Java和编译你的代码，方便地写一个操控世界的代码。这个脚本在WorldEdit中被称作''CraftScripts''，并且这一切都基于JavaScript和你的'''craftscripts/''' 文件. 使用基于WorldEdit写的脚本有这些优点:

* 能够与WorldEdit的 undo（撤销）/redo（反撤销）功能对接
* 能够使用WorldEdit来优化编辑方块的操作
* 允许使用WorldEdit强大的方块类型语法 //set sign:3|How|are|you?
* 能够轻易获取用户选择的区域空间

此脚本需要通过Mozilla Rhino JavaScript在Java 6 或更高版本上运行。但是，如果WorldEdit的路径下有一个独立的Rhino版本，它会被优先使用。为了最大化的兼容性，请在Rhino的Java稳定版本上编写脚本。
脚本支持在v0.8时曾被移除。在v2.13后，脚本支持被重新加入。然而v0.8或更低的版本的脚本并不能兼容。
{{warning|请不要运行来自不受信任的来源的脚本。}}

请查看 [http://docs.sk89q.com/ WorldEdit的API文档].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> 是一个String类型的Java数组

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. 这个对象会自动处理历史和方块放置的顺序。为了得到你自己的脚本的一个编辑样本，请使用：
<source lang="java">
var sess = context.remember();
</source>
任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. 这是因为方块包含各种各样的数据（如箱子方块里面的物品），如果只有方块类型ID的话，很多数据就会被丢失。 <code>BaseBlock</code> is an independent representation of a block; it doesn't know where it is in the world. 这意味着你可以传递一个<code>BaseBlock</code> 到任何地方并重复使用他。 <code>BaseBlock</code>s remember block type and block data. For more complex blocks such as signs and chests, you will use a <code>BaseBlock</code> derivative such as <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
设置一个带有4号颜色的羊毛方块
 
<source lang="java">
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</source>

标记这个是因为 <code>BaseBlock</code> 是在''com.sk89q.worldedit.blocks'' 的命名空间,它必须被引入先. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> 有一个方块类型的列表. The first argument for <code>setBlock()</code> is a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code> indicating the position in the world.

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== 处理参数 ==

Arguments由<code>argv</code>变量传递。如果你需要去检查用户提供的参数是不是正确的，你可以用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

举个例子:检查参数 
<source lang="java">context.checkArgs(1, 3, "<block> [width] [height]");</source>

如果你要去处理一个方块名字使其成为<code>BaseBlock</code>, 你可以使用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. 这个方法可以检查方块黑名单, however. 如果你需要一个方块去, 比如说, 替换, 你可以 ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

举个例子:Getting the passed in block 
<source lang="java">
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</source>

如果用户输入的是一个无效的方块的话，将会抛出一个异常。并且，抛出异常后如果你没有去捕捉他，用户就会被提示这个异常，然后这个脚本就会被终止，就不会再进行下去。

== 配合使用Java包 ==

你可以通过使用以下的语法来引入一个Java包:

importPackage(Packages.package.name.here);

注意：如果你安装了Mozilla's Rhino库，则不需要"Packages."前缀，但为了保持在默认的Java Rhino上运行的稳定性，"Packages."前缀是推荐的。
当安装了以后，你可以使用所有Java的扩展库，以及所有WorldEdit的类。

== 例程 ==

例子:设置附近的发射器装满箭
<source lang="java">
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</source>

例子: 迷宫生成脚本
<source lang="java">
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</source>

WorldEdit/CraftScript

2016-01-17T10:20:50Z

Tdiant：/* 处理参数 */

[[分类:开发教程]]
{{模板:待翻译}}

WorldEdit里的脚本可以让你不用Java和编译你的代码，方便地写一个操控世界的代码。这个脚本在WorldEdit中被称作''CraftScripts''，并且这一切都基于JavaScript和你的'''craftscripts/''' 文件. 使用基于WorldEdit写的脚本有这些优点:

* 能够与WorldEdit的 undo（撤销）/redo（反撤销）功能对接
* 能够使用WorldEdit来优化编辑方块的操作
* 允许使用WorldEdit强大的方块类型语法 //set sign:3|How|are|you?
* 能够轻易获取用户选择的区域空间

此脚本需要通过Mozilla Rhino JavaScript在Java 6 或更高版本上运行。但是，如果WorldEdit的路径下有一个独立的Rhino版本，它会被优先使用。为了最大化的兼容性，请在Rhino的Java稳定版本上编写脚本。
脚本支持在v0.8时曾被移除。在v2.13后，脚本支持被重新加入。然而v0.8或更低的版本的脚本并不能兼容。
{{warning|请不要运行来自不受信任的来源的脚本。}}

请查看 [http://docs.sk89q.com/ WorldEdit的API文档].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> 是一个String类型的Java数组

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. 这个对象会自动处理历史和方块放置的顺序。为了得到你自己的脚本的一个编辑样本，请使用：
<source lang="java">
var sess = context.remember();
</source>
任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. 这是因为方块包含各种各样的数据（如箱子方块里面的物品），如果只有方块类型ID的话，很多数据就会被丢失。 <code>BaseBlock</code> is an independent representation of a block; it doesn't know where it is in the world. 这意味着你可以传递一个<code>BaseBlock</code> 到任何地方并重复使用他。 <code>BaseBlock</code>s remember block type and block data. For more complex blocks such as signs and chests, you will use a <code>BaseBlock</code> derivative such as <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
Setting a cloth block with color value 4
 
<source lang="java">
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</source>

标记这个是因为 <code>BaseBlock</code> 是在''com.sk89q.worldedit.blocks'' 的命名空间,它必须被引入先. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> 有一个方块类型的列表. The first argument for <code>setBlock()</code> is a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code> indicating the position in the world.

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== 处理参数 ==

Arguments由<code>argv</code>变量传递。如果你需要去检查用户提供的参数是不是正确的，你可以用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

举个例子:检查参数 
<source lang="java">context.checkArgs(1, 3, "<block> [width] [height]");</source>

如果你要去处理一个方块名字使其成为<code>BaseBlock</code>, 你可以使用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. 这个方法可以检查方块黑名单, however. 如果你需要一个方块去, 比如说, 替换, 你可以 ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

举个例子:Getting the passed in block 
<source lang="java">
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</source>

如果用户输入的是一个无效的方块的话，将会抛出一个异常。并且，抛出异常后如果你没有去捕捉他，用户就会被提示这个异常，然后这个脚本就会被终止，就不会再进行下去。

== 配合使用Java包 ==

你可以通过使用以下的语法来引入一个Java包:

importPackage(Packages.package.name.here);

注意：如果你安装了Mozilla's Rhino库，则不需要"Packages."前缀，但为了保持在默认的Java Rhino上运行的稳定性，"Packages."前缀是推荐的。
当安装了以后，你可以使用所有Java的扩展库，以及所有WorldEdit的类。

== 例程 ==

例子:设置附近的发射器装满箭
<source lang="java">
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</source>

例子: 迷宫生成脚本
<source lang="java">
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</source>

WorldEdit/CraftScript

2016-01-17T10:19:06Z

Tdiant：/* 例程 */

[[分类:开发教程]]
{{模板:待翻译}}

WorldEdit里的脚本可以让你不用Java和编译你的代码，方便地写一个操控世界的代码。这个脚本在WorldEdit中被称作''CraftScripts''，并且这一切都基于JavaScript和你的'''craftscripts/''' 文件. 使用基于WorldEdit写的脚本有这些优点:

* 能够与WorldEdit的 undo（撤销）/redo（反撤销）功能对接
* 能够使用WorldEdit来优化编辑方块的操作
* 允许使用WorldEdit强大的方块类型语法 //set sign:3|How|are|you?
* 能够轻易获取用户选择的区域空间

此脚本需要通过Mozilla Rhino JavaScript在Java 6 或更高版本上运行。但是，如果WorldEdit的路径下有一个独立的Rhino版本，它会被优先使用。为了最大化的兼容性，请在Rhino的Java稳定版本上编写脚本。
脚本支持在v0.8时曾被移除。在v2.13后，脚本支持被重新加入。然而v0.8或更低的版本的脚本并不能兼容。
{{warning|请不要运行来自不受信任的来源的脚本。}}

请查看 [http://docs.sk89q.com/ WorldEdit的API文档].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> 是一个String类型的Java数组

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. 这个对象会自动处理历史和方块放置的顺序。为了得到你自己的脚本的一个编辑样本，请使用：
<source lang="java">
var sess = context.remember();
</source>
任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. 这是因为方块包含各种各样的数据（如箱子方块里面的物品），如果只有方块类型ID的话，很多数据就会被丢失。 <code>BaseBlock</code> is an independent representation of a block; it doesn't know where it is in the world. 这意味着你可以传递一个<code>BaseBlock</code> 到任何地方并重复使用他。 <code>BaseBlock</code>s remember block type and block data. For more complex blocks such as signs and chests, you will use a <code>BaseBlock</code> derivative such as <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
Setting a cloth block with color value 4
 
<source lang="java">
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</source>

标记这个是因为 <code>BaseBlock</code> 是在''com.sk89q.worldedit.blocks'' 的命名空间,它必须被引入先. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> 有一个方块类型的列表. The first argument for <code>setBlock()</code> is a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code> indicating the position in the world.

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== 处理参数 ==

Arguments由<code>argv</code>变量传递。如果你需要去检查用户提供的参数是不是正确的，你可以用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

举个例子:检查参数 
<source lang="java">context.checkArgs(1, 3, "<block> [width] [height]");</source>

如果你要去处理一个方块名字使其成为<code>BaseBlock</code>, 你可以使用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. 这个方法可以检查方块黑名单, however. 如果你需要一个方块去, 比如说, 替换, 你可以 ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

举个例子:Getting the passed in block 
<source lang="java">
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</source>

如果用户输入的是一个无效的方块会怎么样？会抛出一个异常。并且如果你没有去捕捉他，用户就会被提示这个异常，然后这个脚本就会被终止，不再进行下去。

== 配合使用Java包 ==

你可以通过使用以下的语法来引入一个Java包:

importPackage(Packages.package.name.here);

注意：如果你安装了Mozilla's Rhino库，则不需要"Packages."前缀，但为了保持在默认的Java Rhino上运行的稳定性，"Packages."前缀是推荐的。
当安装了以后，你可以使用所有Java的扩展库，以及所有WorldEdit的类。

== 例程 ==

例子:设置附近的发射器装满箭
<source lang="java">
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</source>

例子: 迷宫生成脚本
<source lang="java">
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</source>

WorldEdit/CraftScript

2015-12-20T03:25:55Z

Tdiant：小汉化X2

{{模板:待翻译}}

WorldEdit里的脚本可以让你不用Java和编译你的代码，方便地写一个操控世界的代码。这个脚本在WorldEdit中被称作''CraftScripts''，并且这一切都基于JavaScript and go into your '''craftscripts/''' 文件. 使用基于WorldEdit写的脚本有这些优点:

* 能够与WorldEdit的 undo（撤销）/redo（反撤销）功能对接
* 能够使用WorldEdit来优化编辑方块的操作
* Accept WorldEdit's powerful block type syntax //set sign:3|How|are|you?
* 能够轻易获取用户选择的区域空间

Mozilla Rhino JavaScript engine bundled with Java 6 and above is used to evaluate the scripts. However, if an independent version of Rhino is found in WorldEdit's classpath, it will be used instead. For maximum portability, write scripts for Java's built-in version of Rhino.

Scripting support was re-added in v2.13 after having been removed in v0.8. However, scripts written for v0.8 and below are not compatible.

{{warning|Do not run scripts from untrusted sources.}}

Check out [http://docs.sk89q.com/ WorldEdit's API documentation].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> 是一个String类型的Java数组

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. This object handles history and block placement order all automatically. To get an edit session for your own script, use:

var sess = context.remember();

任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. The reason is that blocks contain data (and in some cases, complex data like chest contents), and if only block types were passed around, a lot of data would be lost. <code>BaseBlock</code> is an independent representation of a block; it doesn't know where it is in the world. That means that you can pass a <code>BaseBlock</code> around everywhere and reuse it. <code>BaseBlock</code>s remember block type and block data. For more complex blocks such as signs and chests, you will use a <code>BaseBlock</code> derivative such as <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
Setting a cloth block with color value 4
 
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</pre>}}

Note that because <code>BaseBlock</code> is in the ''com.sk89q.worldedit.blocks'' namespace, it had to be imported first. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> has a list of block types. The first argument for <code>setBlock()</code> is a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code> indicating the position in the world.

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== 处理参数 ==

Arguments are passed in under the <code>argv</code> variable. 如果你需要去检查用户提供的参数是不是正确的，你可以用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

举个例子:检查参数 
<pre>context.checkArgs(1, 3, "<block> [width] [height]");</pre>

如果你要去处理一个方块名字使其成为<code>BaseBlock</code>, 你可以使用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. 这个方法可以检查方块黑名单, however. 如果你需要一个方块去, 比如说, 替换, 你可以 ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

举个例子:Getting the passed in block 
<pre>
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</pre>

如果用户输入的是一个无效的方块会怎么样？会抛出一个异常。并且如果你没有去捕捉他，用户就会被提示这个异常，然后这个脚本就会被终止，不再进行下去。

== Working with Java packages ==

To import a java package, you can use the following syntax:

importPackage(Packages.package.name.here);

Tip: The "Packages." prefix is not required if you installed Mozilla's Rhino library, but to keep portability with the default bundle of Rhino in Java, it is recommended that you use it.

You have access to all of Java's vast library as it is installed. WorldEdit's classes are also fully available.

== 例程 ==

例子:设置附近的发射器装满箭
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</pre>

Example: Maze generation script
<pre>
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</pre>

WorldEdit/CraftScript

2015-12-20T03:24:52Z

Tdiant：小小的汉化了一下

{{模板:待翻译}}

WorldEdit里的脚本可以让你不用Java和编译你的代码，方便地写一个操控世界的代码。这个脚本在WorldEdit中被称作''CraftScripts''，并且这一切都基于JavaScript and go into your '''craftscripts/''' 文件. 使用基于WorldEdit写的脚本有这些优点:

* 能够与WorldEdit的 undo（撤销）/redo（反撤销）功能对接
* 能够使用WorldEdit来优化编辑方块的操作
* Accept WorldEdit's powerful block type syntax //set sign:3|How|are|you?
* 能够轻易获取用户选择的区域空间

Mozilla Rhino JavaScript engine bundled with Java 6 and above is used to evaluate the scripts. However, if an independent version of Rhino is found in WorldEdit's classpath, it will be used instead. For maximum portability, write scripts for Java's built-in version of Rhino.

Scripting support was re-added in v2.13 after having been removed in v0.8. However, scripts written for v0.8 and below are not compatible.

{{warning|Do not run scripts from untrusted sources.}}

Check out [http://docs.sk89q.com/ WorldEdit's API documentation].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> is a Java array of arguments as strings

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. This object handles history and block placement order all automatically. To get an edit session for your own script, use:

var sess = context.remember();

任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. The reason is that blocks contain data (and in some cases, complex data like chest contents), and if only block types were passed around, a lot of data would be lost. <code>BaseBlock</code> is an independent representation of a block; it doesn't know where it is in the world. That means that you can pass a <code>BaseBlock</code> around everywhere and reuse it. <code>BaseBlock</code>s remember block type and block data. For more complex blocks such as signs and chests, you will use a <code>BaseBlock</code> derivative such as <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
Setting a cloth block with color value 4
 
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</pre>}}

Note that because <code>BaseBlock</code> is in the ''com.sk89q.worldedit.blocks'' namespace, it had to be imported first. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> has a list of block types. The first argument for <code>setBlock()</code> is a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code> indicating the position in the world.

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== 处理参数 ==

Arguments are passed in under the <code>argv</code> variable. 如果你需要去检查用户提供的参数是不是正确的，你可以用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

举个例子:检查参数 
<pre>context.checkArgs(1, 3, "<block> [width] [height]");</pre>

如果你要去处理一个方块名字使其成为<code>BaseBlock</code>, 你可以使用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. 这个方法可以检查方块黑名单, however. 如果你需要一个方块去, 比如说, 替换, 你可以 ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

举个例子:Getting the passed in block 
<pre>
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</pre>

如果用户输入的是一个无效的方块会怎么样？会抛出一个异常。并且如果你没有去捕捉他，用户就会被提示这个异常，然后这个脚本就会被终止，不再进行下去。

== Working with Java packages ==

To import a java package, you can use the following syntax:

importPackage(Packages.package.name.here);

Tip: The "Packages." prefix is not required if you installed Mozilla's Rhino library, but to keep portability with the default bundle of Rhino in Java, it is recommended that you use it.

You have access to all of Java's vast library as it is installed. WorldEdit's classes are also fully available.

== 例程 ==

例子:设置附近的发射器装满箭
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</pre>

Example: Maze generation script
<pre>
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</pre>

WorldEdit/CraftScript

2015-12-20T03:16:07Z

Tdiant：/* 处理参数 */

{{模板:待翻译}}

Scripting in WorldEdit allows you to write world manipulation code without having to learn Java or compile your code. Scripts, called ''CraftScripts'' in WorldEdit, and are written in JavaScript and go into your '''craftscripts/''' directory. The advantages of writing scripts with WorldEdit are:

* Hook right into WorldEdit's undo/redo system
* Use WorldEdit's block place prioritization
* Accept WorldEdit's powerful block type syntax //set sign:3|How|are|you?
* Get the region selected by the user

The Mozilla Rhino JavaScript engine bundled with Java 6 and above is used to evaluate the scripts. However, if an independent version of Rhino is found in WorldEdit's classpath, it will be used instead. For maximum portability, write scripts for Java's built-in version of Rhino.

Scripting support was re-added in v2.13 after having been removed in v0.8. However, scripts written for v0.8 and below are not compatible.

{{warning|Do not run scripts from untrusted sources.}}

Check out [http://docs.sk89q.com/ WorldEdit's API documentation].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> is a Java array of arguments as strings

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. This object handles history and block placement order all automatically. To get an edit session for your own script, use:

var sess = context.remember();

任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. The reason is that blocks contain data (and in some cases, complex data like chest contents), and if only block types were passed around, a lot of data would be lost. <code>BaseBlock</code> is an independent representation of a block; it doesn't know where it is in the world. That means that you can pass a <code>BaseBlock</code> around everywhere and reuse it. <code>BaseBlock</code>s remember block type and block data. For more complex blocks such as signs and chests, you will use a <code>BaseBlock</code> derivative such as <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
Setting a cloth block with color value 4
 
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</pre>}}

Note that because <code>BaseBlock</code> is in the ''com.sk89q.worldedit.blocks'' namespace, it had to be imported first. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> has a list of block types. The first argument for <code>setBlock()</code> is a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code> indicating the position in the world.

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== 处理参数 ==

Arguments are passed in under the <code>argv</code> variable. 如果你需要去检查用户提供的参数是不是正确的，你可以用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

举个例子:检查参数 
<pre>context.checkArgs(1, 3, "<block> [width] [height]");</pre>

如果你要去处理一个方块名字使其成为<code>BaseBlock</code>, 你可以使用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. 这个方法可以检查方块黑名单, however. 如果你需要一个方块去, 比如说, 替换, 你可以 ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

举个例子:Getting the passed in block 
<pre>
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</pre>

如果用户输入的是一个无效的方块会怎么样？会抛出一个异常。并且如果你没有去捕捉他，用户就会被提示这个异常，然后这个脚本就会被终止，不再进行下去。

== Working with Java packages ==

To import a java package, you can use the following syntax:

importPackage(Packages.package.name.here);

Tip: The "Packages." prefix is not required if you installed Mozilla's Rhino library, but to keep portability with the default bundle of Rhino in Java, it is recommended that you use it.

You have access to all of Java's vast library as it is installed. WorldEdit's classes are also fully available.

== 例程 ==

例子:设置附近的发射器装满箭
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</pre>

Example: Maze generation script
<pre>
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</pre>

WorldEdit/CraftScript

2015-12-20T03:11:57Z

Tdiant：/* Example scripts */

{{模板:待翻译}}

Scripting in WorldEdit allows you to write world manipulation code without having to learn Java or compile your code. Scripts, called ''CraftScripts'' in WorldEdit, and are written in JavaScript and go into your '''craftscripts/''' directory. The advantages of writing scripts with WorldEdit are:

* Hook right into WorldEdit's undo/redo system
* Use WorldEdit's block place prioritization
* Accept WorldEdit's powerful block type syntax //set sign:3|How|are|you?
* Get the region selected by the user

The Mozilla Rhino JavaScript engine bundled with Java 6 and above is used to evaluate the scripts. However, if an independent version of Rhino is found in WorldEdit's classpath, it will be used instead. For maximum portability, write scripts for Java's built-in version of Rhino.

Scripting support was re-added in v2.13 after having been removed in v0.8. However, scripts written for v0.8 and below are not compatible.

{{warning|Do not run scripts from untrusted sources.}}

Check out [http://docs.sk89q.com/ WorldEdit's API documentation].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> is a Java array of arguments as strings

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. This object handles history and block placement order all automatically. To get an edit session for your own script, use:

var sess = context.remember();

任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. The reason is that blocks contain data (and in some cases, complex data like chest contents), and if only block types were passed around, a lot of data would be lost. <code>BaseBlock</code> is an independent representation of a block; it doesn't know where it is in the world. That means that you can pass a <code>BaseBlock</code> around everywhere and reuse it. <code>BaseBlock</code>s remember block type and block data. For more complex blocks such as signs and chests, you will use a <code>BaseBlock</code> derivative such as <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
Setting a cloth block with color value 4
 
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</pre>}}

Note that because <code>BaseBlock</code> is in the ''com.sk89q.worldedit.blocks'' namespace, it had to be imported first. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> has a list of block types. The first argument for <code>setBlock()</code> is a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code> indicating the position in the world.

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== 处理参数 ==

Arguments are passed in under the <code>argv</code> variable. 如果你需要去检查用户提供的参数是不是正确的，你可以用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

举个例子:Checking arguments 
<pre>context.checkArgs(1, 3, "<block> [width] [height]");</pre>

如果你要去处理一个方块名字使其成为<code>BaseBlock</code>, 你可以使用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. That method checks the block blacklist, however. If you need a block for, for example, replacing, you can ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

举个例子:Getting the passed in block 
<pre>
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</pre>

What happens if the user inputs an invalid block? An exception will be raised and if you don't catch it, the user will be informed about their error and your script will be halted.

== Working with Java packages ==

To import a java package, you can use the following syntax:

importPackage(Packages.package.name.here);

Tip: The "Packages." prefix is not required if you installed Mozilla's Rhino library, but to keep portability with the default bundle of Rhino in Java, it is recommended that you use it.

You have access to all of Java's vast library as it is installed. WorldEdit's classes are also fully available.

== 例程 ==

例子:设置附近的发射器装满箭
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</pre>

Example: Maze generation script
<pre>
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</pre>

WorldEdit/CraftScript

2015-12-20T03:09:59Z

Tdiant：/* Processing arguments */

{{模板:待翻译}}

Scripting in WorldEdit allows you to write world manipulation code without having to learn Java or compile your code. Scripts, called ''CraftScripts'' in WorldEdit, and are written in JavaScript and go into your '''craftscripts/''' directory. The advantages of writing scripts with WorldEdit are:

* Hook right into WorldEdit's undo/redo system
* Use WorldEdit's block place prioritization
* Accept WorldEdit's powerful block type syntax //set sign:3|How|are|you?
* Get the region selected by the user

The Mozilla Rhino JavaScript engine bundled with Java 6 and above is used to evaluate the scripts. However, if an independent version of Rhino is found in WorldEdit's classpath, it will be used instead. For maximum portability, write scripts for Java's built-in version of Rhino.

Scripting support was re-added in v2.13 after having been removed in v0.8. However, scripts written for v0.8 and below are not compatible.

{{warning|Do not run scripts from untrusted sources.}}

Check out [http://docs.sk89q.com/ WorldEdit's API documentation].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> is a Java array of arguments as strings

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. This object handles history and block placement order all automatically. To get an edit session for your own script, use:

var sess = context.remember();

任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. The reason is that blocks contain data (and in some cases, complex data like chest contents), and if only block types were passed around, a lot of data would be lost. <code>BaseBlock</code> is an independent representation of a block; it doesn't know where it is in the world. That means that you can pass a <code>BaseBlock</code> around everywhere and reuse it. <code>BaseBlock</code>s remember block type and block data. For more complex blocks such as signs and chests, you will use a <code>BaseBlock</code> derivative such as <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
Setting a cloth block with color value 4
 
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</pre>}}

Note that because <code>BaseBlock</code> is in the ''com.sk89q.worldedit.blocks'' namespace, it had to be imported first. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> has a list of block types. The first argument for <code>setBlock()</code> is a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code> indicating the position in the world.

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== 处理参数 ==

Arguments are passed in under the <code>argv</code> variable. 如果你需要去检查用户提供的参数是不是正确的，你可以用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

举个例子:Checking arguments 
<pre>context.checkArgs(1, 3, "<block> [width] [height]");</pre>

如果你要去处理一个方块名字使其成为<code>BaseBlock</code>, 你可以使用 <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. That method checks the block blacklist, however. If you need a block for, for example, replacing, you can ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

举个例子:Getting the passed in block 
<pre>
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</pre>

What happens if the user inputs an invalid block? An exception will be raised and if you don't catch it, the user will be informed about their error and your script will be halted.

== Working with Java packages ==

To import a java package, you can use the following syntax:

importPackage(Packages.package.name.here);

Tip: The "Packages." prefix is not required if you installed Mozilla's Rhino library, but to keep portability with the default bundle of Rhino in Java, it is recommended that you use it.

You have access to all of Java's vast library as it is installed. WorldEdit's classes are also fully available.

== Example scripts ==

Example:Set nearby dispensers to be filled with arrows
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</pre>

Example: Maze generation script
<pre>
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</pre>

WorldEdit/CraftScript

2015-12-20T03:06:14Z

Tdiant：/* Working with blocks */

{{模板:待翻译}}

Scripting in WorldEdit allows you to write world manipulation code without having to learn Java or compile your code. Scripts, called ''CraftScripts'' in WorldEdit, and are written in JavaScript and go into your '''craftscripts/''' directory. The advantages of writing scripts with WorldEdit are:

* Hook right into WorldEdit's undo/redo system
* Use WorldEdit's block place prioritization
* Accept WorldEdit's powerful block type syntax //set sign:3|How|are|you?
* Get the region selected by the user

The Mozilla Rhino JavaScript engine bundled with Java 6 and above is used to evaluate the scripts. However, if an independent version of Rhino is found in WorldEdit's classpath, it will be used instead. For maximum portability, write scripts for Java's built-in version of Rhino.

Scripting support was re-added in v2.13 after having been removed in v0.8. However, scripts written for v0.8 and below are not compatible.

{{warning|Do not run scripts from untrusted sources.}}

Check out [http://docs.sk89q.com/ WorldEdit's API documentation].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> is a Java array of arguments as strings

想要运行一个脚本，请使用指令 /cs YourScript.js

== 在方块上工作 ==

在WorldEdit中所有的方块编辑操作都基于一个 <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. This object handles history and block placement order all automatically. To get an edit session for your own script, use:

var sess = context.remember();

任何时候你调用这个方法，你都会得到一个新的 <code>EditSession</code>, 所以一定要保持一个左右。要设置一个方块，而不是给一个方块的物品ID。你给一个<code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. The reason is that blocks contain data (and in some cases, complex data like chest contents), and if only block types were passed around, a lot of data would be lost. <code>BaseBlock</code> is an independent representation of a block; it doesn't know where it is in the world. That means that you can pass a <code>BaseBlock</code> around everywhere and reuse it. <code>BaseBlock</code>s remember block type and block data. For more complex blocks such as signs and chests, you will use a <code>BaseBlock</code> derivative such as <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

举个例子: 
Setting a cloth block with color value 4
 
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</pre>}}

Note that because <code>BaseBlock</code> is in the ''com.sk89q.worldedit.blocks'' namespace, it had to be imported first. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> has a list of block types. The first argument for <code>setBlock()</code> is a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code> indicating the position in the world.

想要得到方块，使用基于<code>EditSession</code>的<code>getBlock()</code>函数。你将也能得到一个<code>BaseBlock</code>。

== Processing arguments ==

Arguments are passed in under the <code>argv</code> variable. If you need to check whether the right number of arguments was provided by the user, you can use <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

Exmaple:Checking arguments 
<pre>context.checkArgs(1, 3, "<block> [width] [height]");</pre>

If you need to resolve a block name to a <code>BaseBlock</code>, you can use <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. That method checks the block blacklist, however. If you need a block for, for example, replacing, you can ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

Example:Getting the passed in block 
<pre>
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</pre>

What happens if the user inputs an invalid block? An exception will be raised and if you don't catch it, the user will be informed about their error and your script will be halted.

== Working with Java packages ==

To import a java package, you can use the following syntax:

importPackage(Packages.package.name.here);

Tip: The "Packages." prefix is not required if you installed Mozilla's Rhino library, but to keep portability with the default bundle of Rhino in Java, it is recommended that you use it.

You have access to all of Java's vast library as it is installed. WorldEdit's classes are also fully available.

== Example scripts ==

Example:Set nearby dispensers to be filled with arrows
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</pre>

Example: Maze generation script
<pre>
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</pre>

WorldEdit/CraftScript

2015-12-20T02:59:50Z

Tdiant：/* Introduction */

{{模板:待翻译}}

Scripting in WorldEdit allows you to write world manipulation code without having to learn Java or compile your code. Scripts, called ''CraftScripts'' in WorldEdit, and are written in JavaScript and go into your '''craftscripts/''' directory. The advantages of writing scripts with WorldEdit are:

* Hook right into WorldEdit's undo/redo system
* Use WorldEdit's block place prioritization
* Accept WorldEdit's powerful block type syntax //set sign:3|How|are|you?
* Get the region selected by the user

The Mozilla Rhino JavaScript engine bundled with Java 6 and above is used to evaluate the scripts. However, if an independent version of Rhino is found in WorldEdit's classpath, it will be used instead. For maximum portability, write scripts for Java's built-in version of Rhino.

Scripting support was re-added in v2.13 after having been removed in v0.8. However, scripts written for v0.8 and below are not compatible.

{{warning|Do not run scripts from untrusted sources.}}

Check out [http://docs.sk89q.com/ WorldEdit's API documentation].

== 介绍 ==

脚本有以下在他们的命名空间中的三个变量：

* <code>context</code> is an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html CraftScriptContext]
* <code>player</code> is a copy of the player, an instance of [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/LocalPlayer.html LocalPlayer]
* <code>argv</code> is a Java array of arguments as strings

想要运行一个脚本，请使用指令 /cs YourScript.js

== Working with blocks ==

All block editing in WorldEdit is done through an <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/EditSession.html EditSession]</code>. This object handles history and block placement order all automatically. To get an edit session for your own script, use:

var sess = context.remember();

Every time you call that method, you will get a new <code>EditSession</code>, so be sure to keep one around. To set blocks, rather than giving a block type number, you give a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BaseBlock.html BaseBlock]</code>. The reason is that blocks contain data (and in some cases, complex data like chest contents), and if only block types were passed around, a lot of data would be lost. <code>BaseBlock</code> is an independent representation of a block; it doesn't know where it is in the world. That means that you can pass a <code>BaseBlock</code> around everywhere and reuse it. <code>BaseBlock</code>s remember block type and block data. For more complex blocks such as signs and chests, you will use a <code>BaseBlock</code> derivative such as <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/SignBlock.html SignBlock]</code>.

Example: 
Setting a cloth block with color value 4
 
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);
var sess = context.remember();
sess.setBlock(player.getBlockOn(), new BaseBlock(BlockID.CLOTH, 4));</pre>}}

Note that because <code>BaseBlock</code> is in the ''com.sk89q.worldedit.blocks'' namespace, it had to be imported first. <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/blocks/BlockID.html BlockID]</code> has a list of block types. The first argument for <code>setBlock()</code> is a <code>[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/Vector.html Vector]</code> indicating the position in the world.

To get blocks, use <code>getBlock()</code> on <code>EditSession</code>. You'll get back a <code>BaseBlock</code> too.

== Processing arguments ==

Arguments are passed in under the <code>argv</code> variable. If you need to check whether the right number of arguments was provided by the user, you can use <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#checkArgs%28int,%20int,%20java.lang.String%29 checkArgs]()</code>.

Exmaple:Checking arguments 
<pre>context.checkArgs(1, 3, "<block> [width] [height]");</pre>

If you need to resolve a block name to a <code>BaseBlock</code>, you can use <code>CraftScriptContext.[http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String%29 getBlock]()</code>. That method checks the block blacklist, however. If you need a block for, for example, replacing, you can ignore the blacklist by [http://docs.sk89q.com/worldedit/apidocs/com/sk89q/worldedit/scripting/CraftScriptContext.html#getBlock%28java.lang.String,%20boolean%29 adding a boolean "true" for a third parameter].

Example:Getting the passed in block 
<pre>
context.checkArgs(1, 3, "<block> [width] [height]");
var block = context.getBlock(argv[1]);
</pre>

What happens if the user inputs an invalid block? An exception will be raised and if you don't catch it, the user will be informed about their error and your script will be halted.

== Working with Java packages ==

To import a java package, you can use the following syntax:

importPackage(Packages.package.name.here);

Tip: The "Packages." prefix is not required if you installed Mozilla's Rhino library, but to keep portability with the default bundle of Rhino in Java, it is recommended that you use it.

You have access to all of Java's vast library as it is installed. WorldEdit's classes are also fully available.

== Example scripts ==

Example:Set nearby dispensers to be filled with arrows
<pre>
importPackage(Packages.com.sk89q.worldedit.blocks);

var session = context.remember();
var origin = player.getPosition();

var arrows = new BaseItemStack(262, 64);

var items = [arrows, arrows, arrows,
arrows, arrows, arrows,
arrows, arrows, arrows]

for (var x = -4; x <= 4; x++) {
for (var y = -4; y <= 4; y++) {
for (var z = -4; z <= 4; z++) {
var pt = origin.add(x, y, z);
var id = session.getBlockType(pt);

if (id == BlockID.DISPENSER) {
var block = session.getBlock(pt);
block.setItems(items);
session.setBlock(pt, block);

player.print("Arrows set @ " + pt);
}
}
}
}</pre>

Example: Maze generation script
<pre>
importPackage(Packages.com.sk89q.worldedit);
importPackage(Packages.com.sk89q.worldedit.blocks);

context.checkArgs(1, 3, "<block> [width] [height]");

var sess = context.remember();

// This may throw an exception that is caught by the script processor
var block = context.getBlock(argv[1]);
var w = argv.length > 2 ? parseInt(argv[2]) : 5;
var h = argv.length > 3 ? parseInt(argv[3]) : 5;

function id(x, y) {
return y * (w + 1) + x;
}

function $x(i) {
return i % (w + 1);
}

function $y(i) {
return Math.floor(i / (w + 1));
}

function shuffle(arr) {
var i = arr.length;
if (i == 0) return false;
while (--i) {
var j = Math.floor(Math.random() * (i + 1));
var tempi = arr[i];
var tempj = arr[j];
arr[i] = tempj;
arr[j] = tempi;
}
}

var stack = [];
var visited = {};
var noWallLeft = new Array(w * h);
var noWallAbove = new Array(w * h);
var current = 0;

stack.push(id(0, 0))

while (stack.length > 0) {
var cell = stack.pop();
var x = $x(cell), y = $y(cell);
visited[cell] = true;

var neighbors = []

if (x > 0) neighbors.push(id(x - 1, y));
if (x < w - 1) neighbors.push(id(x + 1, y));
if (y > 0) neighbors.push(id(x, y - 1));
if (y < h - 1) neighbors.push(id(x, y + 1));

shuffle(neighbors);

while (neighbors.length > 0) {
var neighbor = neighbors.pop();
var nx = $x(neighbor), ny = $y(neighbor);

if (visited[neighbor] != true) {
stack.push(cell);

if (y == ny) {
if (nx < x) {
noWallLeft[cell] = true;
} else {
noWallLeft[neighbor] = true;
}
} else {
if (ny < y) {
noWallAbove[cell] = true;
} else {
noWallAbove[neighbor] = true;
}
}

stack.push(neighbor);
break;
}
}
}

var origin = player.getBlockIn();

for (var y = 0; y <= h; y++) {
for (var x = 0; x <= w; x++) {
var cell = id(x, y)
if (!noWallLeft[cell] && y < h) {
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2), block);
}
if (!noWallAbove[cell] && x < w) {
sess.setBlock(origin.add(x * 2, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2, 1, y * 2 - 1), block);
}
sess.setBlock(origin.add(x * 2 - 1, 0, y * 2 - 1), block);
sess.setBlock(origin.add(x * 2 - 1, 1, y * 2 - 1), block);
}
}</pre>

Developing a permissions plugin

2015-09-03T12:33:32Z

Tdiant：汉化引言部分

[[Developing a permissions plugin/en|点击此处查看原文]]
{{待翻译}}
== 引言 ==

这篇教程将会带领你了解有关怎么基于新的BukkitPermissionsAPI给你插件创建权限。

=== 前提 ===

这篇教程需要你掌握很好的Java知识和一些插件开发知识。这篇教程只会涵盖有关Bukkit Permissions API的各种细节。

== Permissible ==

Everything that can have permissions set must inherit the ''Permissible'' class. Currently these only include the ''Player'' and ''CommandSender'' classes, however in theory anything could have permissions. For the future of this tutorial we will mention the player rather than a permissible object.

== PermissionAttachments ==

=== What is a PermissionAttachment? ===

A permission attachment is a way for a plugin to manage a player's permissions, and even better, allows multiple plugins to manage the player's permissions without interference, unless of course they want to set the same permission.

=== How to create and remove them ===

Every player must first be "attached" to the plugin so that it can be managed. To create a PermissionAttachment, use the following:

<source lang="java">PermissionAttachment attachment = player.addAttachment(plugin);</source>

You can even create an attachment that will only last for a limited number of ticks:

<source lang="java">PermissionAttachment attachment = player.addAttachment(plugin,ticks);</source>

This attachment needs to be stored somewhere though. The best solution is to create a <source lang="java">HashMap<UUID,PermissionAttachment></source> and store it in there with the player's Unique ID. That will later allow you to manage a particular player's permissions via their Unique ID, and remove the attachment when it's no longer needed. The best places to remove the attachment are in the ''onPlayerQuit'' event, ''onPlayerKick'' event, and remove them all in the plugin's ''onDisable'' event. Removing the attachment is as follows:

<source lang="java">player.removeAttachment(attachment);</source>

== Assigning permissions ==

There are two main ways to set a player's permission:

#Via a string. This is probably the easiest method, and the one which I will explain first.
#Via a permission Object. This is slightly more complicated, however it works in exactly the same way as the first internally, so I won't bother going over this.

 

To set a player's permission you firstly have to get the PermissionAttachment you created earlier from the HashMap. Once you have this then setting a player's permissions is easy via the following:

<source lang="java">attachment.setPermission(permissionName,permissionValue);</source>

The permissionName is a String, and permissionValue is a boolean. You can later unset a player's permission (different to setting it to false) through the following:

<source lang="java">attachment.unsetPermission(permissionName);</source>

The reason you may want to unset a player's permission is if you want to allow a different permissions plugin to set it.

== Conclusion ==

That's about all there is to know about writing your own permissions plugin. The actual implementation of the plugin however is up to you. I can however provide a few examples:

*An RPG plugin that gives player's permissions based on their XP
*A forum bridge that links groups/permissions from a forum such as phpBB to bukkit's permissions

[[Category:开发教程]]

Bukkit/插件开发教程

2015-09-03T09:04:19Z

Tdiant：更正不妥当的翻译

{{模板:待翻译}}
{{模板:待完善}}
本页面英文原文内容来源 [http://wiki.bukkit.org/Plugin_Tutorial]
== 介绍 ==

这篇内容丰富的教程旨在帮助你学会如何开发Bukkit插件.这一篇教程不可能完全涉及到Bukkit中所有的可能性,而是最基本的一般概述. 前提是你懂得Java这门语言,并在IDE中设置好你的工作区,此教程介绍了大多数Bukkit插件所必需的语法结构.

== 学习Java ==

'''理解这些教程需要具备Java这门编程语言的基本知识.'''如果你刚开始学习Java或者需要重温一下相关知识，下面有一个并不完整的网站列表可供参考.

<big>[http://docs.oracle.com/javase/tutorial/ Oracle's Java Tutorials]</big> - 官方教程
*[http://www.java2s.com/Tutorial/Java/CatalogJava.htm Java2s.com] - 教程
*[http://www.javacoffeebreak.com/java101/java101.html Java 101] - 教程
*[http://math.hws.edu/javanotes/ JavaNotes] - 免费的在线教科书
*[http://thenewboston.org/list.php?cat=31 TheNewBoston] - 视频教程.

== 开发环境 ==

在编写一个插件前 (或学习Java前) 你需要配置一个开发者环境，这个包括但不限于安装IDE (Integrated Development Environment，集成开发环境)。接下来的教程中有关于Eclipse上IDE的操作指南。

:: ''更多信息，请参见 [[Bukkit/插件开发教程-建立工作区|建立工作区]]''

你'''必须'''下载'''Java'''开发者使用的Eclipse构建版本, '''不是''' '''Java EE'''开发者的版本。 Java EE 开发者的版本不包含此教程需要的Maven支持。

== 新建插件开发项目 ==
=== 创建一个新的项目 ===

在开始工作之前，你需要先在Eclipse中配置好工作区和文件. 打开Eclipse,然后依次点击''File -> New -> Project:''来创建一个新的项目.

[[Image:Newproject.png]]

现在,打开''Maven''文件夹, 然后选择''Maven Project''.点击next,之后在下一个菜单中选择''Create a simple project'', 再次点击''Next'':
如果你看不到''Maven''文件夹, 那么你需要[http://eclipse.org/m2e/download/ 下载m2eclipse]

[[Image:Newproject2.png]]

现在，你需要给你的组用户命名，就像下面这样:
* 如果你拥有一个域名，package则填写逆转的域名地址.
** 例如: i-am-a-bukkit-developer.com 你的package地址即是com.i_am_a_bukkit_developer [http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html source]
** 避免使用一个不属于你自己的域名.
* 没有域名? 这里有几种方法可供选择。
*# 在资源管理站点创建一个用户，比如GitHub或是sourceforge
*#* 对于使用GitHub的用户, 请参照[http://pages.github.com/ 这里的说明] 之后你将获得一个子域名,所以你的package地址是io.github.<username> 
*# 使用你的邮箱. 例如: <username>@gmail.com格式的邮箱应输入com.gmail.<username> 
*# 最不济的方法.：使用独特的组名命名方式，这应当是你最后的解决方法。

以下几个地址不能作为package中的地址前缀:
* org.bukkit
* net.bukkit
* com.bukkit
* net.minecraft

完成基础的组名以后，你需要在最后加上插件的名称. 在这里用 GitHub页面作为讲解的实例. 如果你创建了一个名为 ''TestPlugin''的插件，那么完整的组名是''io.github.<username>'', 你的工程名也是 ''TestPlugin''. 至于版本，默认即可，稍后可以修改。
完成向导:

[[Image:Newproject3.png]]

如果这是你首次使用Eclipse, 点击右上角的"X" 来关闭Welcome提示页面. 现在，你的窗口视图看起来就像下面的图片这样:

[[Image:Eclipsemain.png]]

点击工程名称右边的箭头来进行下一步，现在我们正式开始。
=== 添加Bukkit API ===

在开发插件之前，你需要添加 Bukkit API库文件到你的项目，作为一个dependency, 你也可以添加其他你想实用的API.

找到项目文件夹中部的''pom.xml''并双击进行编辑. 点击''pom.xml''中部的 tab,你将会看到下图所示内容:

[[Image:Pomeditor.png]]

如果你想使用Java 6以上版本的语言特性,你需要指定搭建项目的Java版本.复制并粘贴以下内容(设定项目只能使用Java 7及以下的版本)到 ''</project>''之前:

<code>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<nowiki><</nowiki>source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
</plugins>
</build>
</code>

你或许想使用其他版本,例如 <code>1.8</code> 使用Java 8. 请注意 [http://mcstats.org/global/ 根据MCStats数据统计], 大多数服主选择了Java 7, 所以使用Java 8会使许多服务器无法运行你的插件. 如果你使用Java 1.7的特性, Eclipse将会在报错代码"error"中建议你更改语言版本.同意即可.

在位于代码中段的''</project>''之前粘贴以下内容(这段代码告诉Eclipse关于Bukkit's repository的地址):

<code>
<repositories>
<repository>
<id>bukkit-repo</id>
<url>http://repo.bukkit.org/content/groups/public/</url>
</repository>
</repositories>
</code>

然后继续在 ''</project>''前粘贴以下内容 (这段代码告诉Eclipse搭建插件的Bukkit版本):

<code>
<dependencies>
<dependency>
<groupId>org.bukkit</groupId>
<artifactId>bukkit</artifactId>
<version>1.7.2-R0.3</version>
<type>jar</type>
<scope>provided</scope>
</dependency>
</dependencies>
</code>

你也可以修改这里的Bukkit版本.你可以在[http://repo.bukkit.org/content/groups/public/org/bukkit/bukkit/ here]这里通过查看 maven-metadata.xml文件下的版本列表来获取可用的服务端版本号.

当你完成上述步骤后,''pom.xml''中的内容应该是这样:

[[Image:Finishedpom.png]]

通过菜单 ''File -> Save''或者按住 <code>Ctrl + S</code> 来保存''pom.xml''文件 . 之后, 右键项目标题，然后依次选择 ''Maven -> Update Project''.

=== Bukkit Java文档 ===

如果你曾经使用过Eclipse和Java，你会知道当你将鼠标准心移至class或者 method中的代码部分时，一个含有相关文档内容的黄色小框会弹出来. 这就是（Java的）Java文档。

你可以[http://download.oracle.com/javase/6/docs/api/ Oracle website 在线获取]它.。Bukkit同样拥有文档，这些文档内容包含了关于API中method和class的有用描述。

你可以在[http://jd.bukkit.org/ 这]找到它 (Beta版的Java文档在[http://jd.bukkit.org/ 这]找, 新开发出来的Java文档在

[http://jd.bukkit.org/ 这]) 。为了在Eclipse里使用Java文档,这样的话当你的鼠标停留在Bukkit的class和method上时，

（Bukkit的）Java文档就会冒出来。
JavaDoc in spigot [https://hub.spigotmc.org/javadocs/bukkit/ Click Here]

首先右键在侧边栏里的"Maven Dependencies"下面的Bukkit jar,选择"Properties".选中窗口左边的''Javadoc Location'', 并粘贴如下网址

'''http://jd.bukkit.org/''' (或者上面的测试版/最新版 Java文档链接也好) 到"Javadoc URL"下面的输入框内. 就像这样:

[[Image:Bukkitjavadocs.png]]

点击 "Validate",然后再点击"OK"就完成了.现在Bukkit Javadocs已经连接到Bukkit提供的资源,同时你也可以通过Eclipse来获得帮助类文档信息了.

=== 创建一个包 ===

现在你需要创建一个包，它将储存所有我们需要使用的Java类文件. 右键展开''src/main/java''折叠并选择 ''New > Package'':

[[Image:Newpackage.png]]

包名的话，先写上你的组名，然后加个点，再写上你的小写Artifact ID。举例, 如果你的组名是''io.github.name''，你的artifact名是 ''TestPlugin''。

你的包名就应该是''io.github.name.testplugin''.

=== 创建插件的类文件 ===

既然我们已经建立好了我们的项目，我们接下来可以开始添加类文件以及制作插件了. 插件的主类指的是拓展(extends)JavaPlugin的类文件. 在你的插件中只能有一个类文件拓展JavaPlugin，无论直接还是间接. 先创建你的主类文件并保持名称与插件名一致是个很好的习惯.右键你之前新建的包,并选择  ''New > Class''.你将会创建一个新的类文件，就像下面这样

package {$GroupName}.{$ArtifactName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$ArtifactName} extends JavaPlugin {

}

警告：插件绝对不应该调用自己的构造函数并实例化

=== 创建plugin.yml ===

你已经创建了项目和主类，如果你想要Bukkit能够加载你的插件，你还必须创建 '''[[Plugin YAML|plugin.yml]]''' 文件. 这个文件包含有基础的插件信息，如果缺失这个文件，你的插件也将会失效. 此时你需要右键''src/main/resources''. 选择''New > File''. 命名为"'''plugin.yml'''" 并右键完成新文件的创建.Eclipse会打开默认的文本编辑窗口来显示'''plugin.yml'''文件中空白的内容并提供编辑. ''(Hint: 如果你想要使得你的工作空间更加规整，关闭文本编辑器并将'''plugin.yml''' 文件拖到主工作空间(拖到文件目录的右边) 之后你就可以在eclipse中编辑文件了.)''

有三个基础的内容需要在plugin.yml写明.
: name: 插件名称.
: main: [http://docs.oracle.com/javase/specs/jls/se7/html/jls-6.html#jls-6.7 插件主类的完整，合法名称] .
: version: 插件当前版本号.

最简单的 '''plugin.yml''' 文件内就像这样 :

name: {插件名称}
main: {包名}.{主类}
version: {版本号}

PS:插件的包名经常会包括插件的名称，所以看到这个的时候不要感到惊讶。
你的主类是否是你的插件名取决于你之前的命名方式，时刻记住这一点很重要。

'''''更多例子''', 请看[[#Example_Files_and_Templates]]''

此时你的插件已经可以被Bukkit加载了,同时服务端日志也会开始记录你的插件. 不过它现在什么用都没有!

== onEnable()和onDisable()方法 ==

这些方法将在插件启用与卸载时生效. 默认情况下，你的插件在被加载时会调用这些方法，所以你可以在这里注册你需要用到的事件和提供一些调试信息. <code>onEnable()</code> 方法会在插件启用时被调用, 需要包含初始化插件的逻辑语句. <code>onDisable()</code> 方法会在插件卸载时被调用，需要包含清理(clean up)插件的逻辑语句和连接声明(associated state)。此外，插件可以重写 <code>onLoad()</code> 方法来在插件载入时执行附加的逻辑语句。

=== onEnable()和onDisable()方法介绍 ===

在前面的章节中，我们在主类创建了<code>onEnable()</code> 和 <code>onDisable()</code> 方法. 此时，这些代码看起来就像下面这样

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
// 插件载入时要执行的代码（略）
}

@Override
public void onDisable() {
// 插件卸载时要执行的代码（略）
}
}

这些方法已经创建，但目前它们还没有任何作用.
注意: 不需要添加代码来实现输出信息"{$PluginName} has been enabled!" ，因为bukkit会自动输出此类信息
有关更多事件的信息请查看 [[Event_API_Reference|这里]].

=== 发送提示信息 ===

插件能够输出信息至控制台与服务器日志。这是通过调用插件记录器里正确的方法来实现的。首先我们必须调用 <code>getLogger()</code> 方法来检索该插件的记录器，

然后我们就可以开始记录信息了。

我们通过调用<code>onEnable()</code>方法可以实现输出信息。我们需要在<code>onEnable()</code>方法下面插入如下代码：

getLogger().info("onEnable has been invoked!");

在 <code>'''onDisable()'''</code>方法里面，你也可以做类似的事情，不过要改改输出信息。

此时你的主类文件就像这样:

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
getLogger().info("onEnable has been invoked!");
}

@Override
public void onDisable() {
getLogger().info("onDisable has been invoked!");
}
}

=== 防止重载后插件失效 ===

你需要知道的是，插件并不只会伴随服务器关闭、启动而重载，你的插件也可能会被其他插件启用、关闭，或是在服务器运行时使用/reload命令.
假设服务器启动之后一会儿后，你的插件才被启用，这时便是危险的,因为服务器中可能已经有玩家在线、额外的世界被加载以及很多预想不到的不同之处(与"插件同服务器同时加载"的情况相比较).

举个例子来说:
* 你有一个用来储存HashMap中的玩家登入信息的插件
* 你希望该信息对所有玩家都可见
* 一名管理员使用/reload命令
* 你的插件被卸载，所有储存的数据都丢失了
* 你的插件被再次启用时，一些玩家已经在线
* 这些玩家在HashMap并没有储存的信息
* 你试图重新获得他们的信息，但是失败了!

为了插件重载以后能够正常工作, 你需要在插件启用时加载所有已经在线的玩家的信息并将之储存在HashMap中.

for (Player player : Bukkit.getServer().getOnlinePlayers()) {
playerList.put(player.getName(), playerData(player));
}

== 监听器 ==
监听器是一种方法被调用来对事件作出反应的类.所有的监听器使用 org.bukkit.event.Listener接口.更多有关监听器创建的细节,
:: '' 请查看: [[Event API Reference]]''

== 指令 ==

=== onCommand() 方法 ===

现在你已经知道如何注册一个事件并做出响应,但是如果你只是想要在命令输入之后做出响应呢? 你可以使用 <code>'''onCommand'''</code>方法.

这个代码的作用是当玩家输入“/”时，监听该操作并执行相关语句"/" . 举个例子来说.输入 "/do something" 将会执行 <code>'''onCommand'''</code>方法.

此种情况下，因为没有特定的行为被编程，所以并不会发生任何事情。

请避免使用和bukkit所提供的指令重名的指令, 然后深思你的指令名的唯一性。

例如.指令"give"已经被好几个插件使用了, 如果你执行了另外一个"give"指令, 你的插件将会和这些插件冲突。

你必须在插件的"plugins.yml"注册你的指令否则这个方法将不会被触发。

<code>'''onCommand'''</code>方法必须返回一个布尔值（true或false）。

如果返回值是true，你不会看到什么明显的事情发生。

但如果返回值是false，则会返回你的plugin.yml里的'usage:property'然后发送给命令使用者.

当使用 <code>'''onCommand'''</code>方法时, 你需要填写4个参数.

*<code>'''CommandSender sender'''</code> - 发送命令的对象

*<code>'''Command cmd'''</code> - 被执行的指令

*<code>'''String commandLabel'''</code> - 被执行指令的别名

*<code>'''String[] args'''</code> - 该指令的自变量数组。

例如.指令 ''/hello abc def'' 中， ''abc'' 会被存放进args[0]中, ''def'' 被存放进args[1]中。

==== 设置命令 ====
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { // 如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} //如果以上内容成功执行，则返回true
// 如果执行失败，则返回false.
return false;
}

每当使用<code>'''onCommand'''</code>方法时，在每个方法后面都加上一个 return false; 是一个惯例。

返回false会显示在plugin.yml里设置的usage信息 (看下面). 用这种方法的话，一旦执行出错便会显示usage信息。

每当方法return一个值的时候，这个方法就会退出，所以return true的时候，在它下面的代码就会被跳过,

除非return语句在一个if的嵌套中，或者类似的嵌套情况。

<code>'''.equalsIgnoreCase("basic")'''</code>代表忽略英文大小写. 在这种情况下,字符串"BAsIc" 和 "BasiC"和 basic相同，代码会被照常执行。

和以前一样，加两行import在你的java文件头

import org.bukkit.command.Command;

import org.bukkit.command.CommandSender;

=== 在Plugin.yml中添加你的指令 ===

你需要添加你的指令到 '''plugin.yml''' 文件里. 如下是指令/basic添加到 '''plugin.yml'''的例子（请在plugins.yml的末尾添加如下代码）:

commands:
basic:
description: This is a demo command.
usage: /<command> [player]
permission: <plugin name>.basic
permission-message: You don't have <permission></source> </code> </blockquote>

*<code>'''basic'''</code> - 指令名称

*<code>'''description'''</code> - 指令描述

*<code>'''usage'''</code> - 在oncommand方法return false后显示的用法提示。尽量简洁, 使别人能够理解指令是什么以及如何使用它。

*<code>'''permission'''</code> - 被一些显示帮助信息的插件使用，用来决定向玩家显示哪个指令（完全不对劲吧！）。

*<code>'''permission-message'''</code> - 当玩家使用了这个指令而没有权限时输出的信息。

PS:yml文件使用两个空格作为制表符,使用tab键输入制表符会导致错误。

===控制台指令vs玩家指令===

你可能注意到了上文的<code>'''CommandSender sender'''</code>参数. <code>'''CommandSender'''</code> 是个Bukkit接口，

它有两个（对插件编写者）有用的子类：<code>'''Player'''</code> 和 <code>'''ConsoleCommandSender'''</code>.

所以当你编写插件的时候, 确定这个指令从控制台发出后能完全正常工作是十分必要的,

那些只能由在线玩家执行的指令 ''只能'' 由一个在线玩家执行。

有的插件在判断命令执行对象不是玩家时仅仅用return进行处理 (比如当有人从控制台发出指令),

即便这些指令能够在控制台完美运行（比如改变天气的指令）。

一个判断sender的方法:
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { //如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} else if (cmd.getName().equalsIgnoreCase("basic2")) {
if (!(sender instanceof Player)) { //如果sender与Player类不匹配
sender.sendMessage("This command can only be run by a player.");
} else {
Player player = (Player) sender;
// 所需要执行的事（此处略）
}
return true;
}
return false;
}

在这个例子里，指令'''basic'''能由任何人发出 - 一个在线的玩家, 或者服务器后台的op.

但是指令'''basic2'''只能由一个在线的玩家发出.

大体上说,你应该允许尽可能多的指令在控制台和玩家聊天框里都正常执行.

需要在线玩家执行的指令可以使用以上例子中的机制来检测<code>'''CommandSender'''</code>是一个玩家.

很多指令广泛依靠于一些玩家的属性（例如可以被tp或被给予物品等等）。

如果你想更进一步, 你可以对你的指令的自变量做一些额外的检测，例如传送指令在提供玩家ID的情况下（也只有在这种情况下）可以在控制台被执行。

=== 使用独立的 CommandExecutor class ===

以上的例子必须把 <code>'''onCommand()'''</code> 方法放在插件的主类里。

对于小插件来说，这是极好的,但如果你要写一个大点的插件,把你的 <code>'''onCommand()'''</code>方法放在独立的类里将会很有意义。

幸运的是，这并不难:

*在你的包里创建一个新类. 命名为'''MyPluginCommandExecutor'''之类的 (当然，要把'''MyPlugin'''替换成你制作的插件的名字)。这个类 '''必须''' 继承Bukkit 的'''CommandExecutor'''接口。

*在你的插件的<code>'''onEnable()'''</code>方法中,你需要实例化你创建的命令执行类(CommandExecutor class), 然后做一个像下面一样的调用：<code>getCommand("basic").setExecutor(myExecutor);</code>
其中"basic"是我们需要操控的指令, <code>myExecutor</code> 是我们创建的实例.

废话少说直接吔我例子:

'''MyPlugin.java''' (插件的主类):
@Override
public void onEnable() {
// 如果你没有在plugins.yml注册过指令的话，此处会抛出空指针异常！
this.getCommand("basic").setExecutor(new MyPluginCommandExecutor(this));
}

'''MyPluginCommandExecutor.java'''（独立CommandExecutor类）:
public class MyPluginCommandExecutor implements CommandExecutor {
private final MyPlugin plugin;

public MyPluginCommandExecutor(MyPlugin plugin) {
this.plugin = plugin; // Store the plugin in situations where you need it.
}

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 和以前一样执行就好…
}
}

请注意我们是如何把主类里的对象指向'''MyPluginCommandExecutor'''的. 这允许我们轻易的使用主类对象的方法（如果我们需要的话）。

这么做的话, 我们便能更好的组织代码 - 如果 <code>'''onCommand()'''</code> 方法又大又复杂, 它就能被划分为子类，从而不使插件的主类显得凌乱。

PS：如果你的插件含有多个指令的话, 你需要为每一个指令单独设立一个commandexecutor.

=== 写一个安全的指令 ===
当写一个指令的时候,别进行任何假设（很重要）, 例如假设执行者一定是个玩家. 请牢记以下原则:

==== 在命令执行前确定发出者是玩家 ====

使用简单的例子来进行检测:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (sender instanceof Player) {
Player player = (Player) sender;
// do something
} else {
sender.sendMessage("You must be a player!");
return false;
}
// do something
return false;
}

==== 检测自变量个数 ====

别老是认为玩家都能打对正确数量的自变量.

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (args.length > 4) {
sender.sendMessage("Too many arguments!");
return false;
}
if (args.length < 2) {
sender.sendMessage("Not enough arguments!");
return false;
}
}

==== 在获取玩家之前先检测他们是否在线 ====

有时你想通过命令发出者打出的ID来获取其他玩家，请确保他们在线再说！

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
Player target = (Bukkit.getServer().getPlayer(args[0]));
if (target == null) {
sender.sendMessage(args[0] + " is not online!");
return false;
}
return false;
}

如果你想对离线玩家进行操作，<code>'''OfflinePlayer'''</code>类提供了基础操作的方法.

== 插件的配置/设置 ==
Bukkit API 为插件提供了一种简便的方法，用来管理用户自定义的设置。同时，通过这种方法也可以储存数据。
:: ''详情请查看: [[Configuration API Reference]]''

== 权限 ==

利用新的Bukkit API来设置权限是再容易不过的事情. 检测玩家是否拥有权限，可以使用以下代码:
<blockquote><source lang="java">if (player.hasPermission("some.pointless.permission")) {
//执行此段代码(有权限)
} else {
//执行此段代码(无权限)
}</source> </blockquote>
你也可以检测一个权限节点是否被定义过，(等效于 Java 语言中的'''null''')，使用下面的方法:
<blockquote><source lang="java">boolean isPermissionSet(String name)</source></blockquote>
你或许对此抱有疑惑:为什么这段代码中没有任何用户群的信息？因为它们并不是必需的. 之前这段代码想要实现的主要功能之一就是根据用户群格式化聊天信息. 但其实使用权限就可以很容易地完成这项工作.你可以在聊天插件的配置文件中定义权限与前缀的对应关系. 举例来说，"someChat.prefix.admin" 权限可以对应前缀[Admin].当拥有此权限的玩家发出聊天信息时，聊天前缀便是[Admin].

另一个想要实现的主要功能则是给所有拥有权限的在线用户发一条信息.你可以这样做:
<blockquote><source lang="java">for (Player player: Bukkit.getServer().getOnlinePlayers()) {
if (player.hasPermission("send.receive.message")) {
player.sendMessage("You were sent a message");
}
}</source> </blockquote>
看到这里你可能会问，若是没有权限组我该如何配置玩家的 [[权限]] ？既然 [[Bukkit]] API 本身并没有提供用户组的预设, 你必须通过安装一款权限组插件，像 [[permissionsBukkit]] 这样的插件来帮助你配置用户群. '''API 只是提供接口而不是提供已实现的类.'''

=== 配置权限 ===
{{Hide|标题=译者注 |内容= 其一，以下代码中部分内容将以''//文字''翻译，使用时请不要加入其中内容，仅做教程中的翻译参考；
其二，default:true在下面翻译为全员默认拥有该权限，default:false则翻译为全员默认没有该权限，请注意理解。 }}
如果你想要更多地控制你的权限，例如设置权限的默认值或是子权限节点，不如将权限节点加入你的 ''[[plugin.yml]]''文件.这并不是必须的，但我们推荐你这样做. 下面是一个实例，显示了当你将权限添加在''plugin.yml''文件末尾时的样子:
<blockquote><code><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //给予使用doorman所有命令的权限
children: //子权限节点
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false
doorman.kick:
description: Allows you to kick a user //允许你踢出一名用户
default: op //OP默认拥有该权限
doorman.ban:
description: Allows you to ban a user //允许你封禁一名用户
default: op //OP默认拥有该权限
doorman.knock:
description: Knocks on the door! //敲门
default: true //全员默认拥有该权限
doorman.denied:
description: Prevents this user from entering the door //禁止拥有该权限节点的用户进入门内</source> </code> </blockquote>
值得注意的是,你的插件使用的每个权限都被定义为 ''permissions'' 这个节点的子权限节点. 每个权限都能够拥有一个描述，默认值以及子权限节点。
==== 默认值 ====

当一个权限没有明确是否为玩家所拥有 ，''hasPermission''<ref>这是一个检测玩家是否拥有指定权限节点的方法</ref> 将返回false<ref>该方法返回的boolean值</ref>. 在你的[[plugin.yml]] you can change this by setting the default node to be one of four values:

*'''true''' - 全员默认拥有该权限.
*'''false''' - 全员默认没有该权限.
*'''op''' - 如果玩家是一名OP<ref>Operator，服务器管理员</ref>，那么他将拥有该权限.
*'''not op''' - 如果玩家不是一名OP，那么他将拥有该权限.

==== 子权限 ====

在这之前你可能已经习惯了通过权限节点自动分配所有的子权限<ref>原句:Before now you will probably be used to the * permission to automatically assign all sub permissions.此处的sub permissions应是同上文“你的插件使用的每个权限都被定义为 permissions 这个节点的子权限节点.”相照应</ref>. 现在这种方法已经随着bukkit API<ref>应用程序编程接口(Application Programming Interface)</ref>的更新而改变，现在你可以自己定义子权限了. 这将使得插件具有更多的灵活性. 下面是一个例子:
<blockquote><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //翻译见上
children:
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false</source> </blockquote>
在这里，''doorman.*'' 权限拥有几个子权限并分配在其下. 子权限工作的方式就是当''doorman.*'' 权限节点被设置为true时,子权限也会随之设置为 ''plugin.yml''中的默认值. 然而当''doorman.*'' 被设置为false时，所有子权限都会设置为与默认值相反的值（true->false,false->true）.
<references />

=== 设置你自己的权限 ===

如果你希望想知道更多有关开发你自己的权限插件的事情(即是设置权限的管理类插件) ，那么请前往查看教程 [[Developing a permissions plugin]].

== Scheduling Tasks and Background Tasks ==

Currently, Minecraft servers operate nearly all of the game logic in one thread, so each individual task that happens in the game needs to be kept very short. A complicated piece of code in your plugin has the potential to cause huge delays and lag spikes to the game logic, if not handled properly.

Luckily, Bukkit has support for scheduling code in your plugin. You can submit a Runnable task to occur once in the future, or on a recurring basis, or you can spin off a whole new independent thread that can perform lengthy tasks in parallel with the game logic.

There is a separate [[Scheduler Programming]] tutorial which introduces the Scheduler, and gives more information on using it to schedule synchronous tasks, and on kicking off asynchronous tasks in Bukkit.

== 方块操控 ==

这是一个很容易的方法创建、获取或修改一个方块, 例如当你想要修改往你头上数第五格的方块时, 首先你需要做的是获取你当前的坐标点, 然后往你当前的坐标点的Y轴加上五, 获取目标方块后我们便能够很容易地修改它了, 例子如下:
<blockquote><source lang="java">
@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
// 得到玩家当前的坐标.
Location loc = event.getPlayer().getLocation();
// 设置目标坐标为玩家头顶 5 格处.
loc.setY(loc.getY() + 5);
// 得到目标坐标的方块
Block b = loc.getBlock();
// 将目标坐标的方块更改为石头 (stone).
b.setType(Material.STONE);
}</source> </blockquote>
上面的代码获取了玩家的所在位置，获取头上的第五个方块，并且放上一个石头（stone）。 Note that once you have a <code>Block</code>, there are other things you can do besides set its type. 你可以查阅JavaDoc获取更多的东西。

你可以用这样相似的观念去生成一些建筑，并且还可以用编程的方式通过算法生成一些独特的方块（这里指由很多个方块拼在一起的四四方方的方块）。比如，去生成一个实心的方块建筑，你可能在生成建筑的时候还需要用到<code>for</code>循环，去一遍遍循环来生成这些建筑，填满这些建筑等。
下面，是一个在指定坐标生成一个实心的方块建筑的实例方法：
<blockquote><source lang="java">
public void generateCube(Location loc, int length) {
// 放置这个方块最中间的方块并且获取这个方块的坐标。
// Uses getBlockN() instead of getN() to avoid casting to an int later.
int x1 = loc.getBlockX();
int y1 = loc.getBlockY();
int z1 = loc.getBlockZ();

// Figure out the opposite corner of the cube by taking the corner and adding length to all coordinates.
int x2 = x1 + length;
int y2 = y1 + length;
int z2 = z1 + length;

World world = loc.getWorld();

// Loop over the cube in the x dimension.
for (int xPoint = x1; xPoint <= x2; xPoint++) {
// Loop over the cube in the y dimension.
for (int yPoint = y1; yPoint <= y2; yPoint++) {
// Loop over the cube in the z dimension.
for (int zPoint = z1; zPoint <= z2; zPoint++) {
// Get the block that we are currently looping over.
Block currentBlock = world.getBlockAt(xPoint, yPoint, zPoint);
// 设置方块ID为57号(钻石块!)
currentBlock.setType(Material.DIAMOND_BLOCK); //这里下面会提到
}
}
}
}</source></blockquote>
这个方法将会在程序给予这个方法高度和起始坐标（最中间的方块的坐标）时，构建一个3D的方块建筑。简单的删除方块也可以使用这个方法的思路实现，但是，但是设置方块的时候，记得把上面标注会提到的那行，设置为物品ID为0的方块(空气方块)。 
<blockquote></blockquote>

== (玩家)修改背包 ==

这个部分大部分讲的是修改玩家的背包。但是在某些情况下，修改箱子里的内容与此相同，当然得在你能找到获取箱子里内容的方法才可以。 :P. 这是一个修改玩家背包的一个例子:
<blockquote><source lang="java">public void onPlayerJoin(PlayerJoinEvent evt) {
Player player = evt.getPlayer(); // 当玩家加入游戏
PlayerInventory inventory = player.getInventory(); // 获取玩家背包列表
ItemStack itemstack = new ItemStack(Material.DIAMOND, 64); // 生成一组钻石

if (inventory.contains(itemstack)) {
inventory.addItem(itemstack); // 将一组钻石放到玩家的背包里
player.sendMessage("Wow！你看上去很土豪啊！"); //向玩家发送消息("Wow！你看上去很土豪啊！")
}
}</source> </blockquote>
所以，上面代码里面的 onPlayerJoin 方法中，我们首先构建了一些变量，让我们的工作变得更容易一些。变量分别是： player, inventory and itemstack。 inventory 变量是玩家的背包内容，itemstack是那64个钻石的物品栈。然后我们判断了玩家是不是有一组钻石。如果有，我们就用inventory.addItem(itemstack)方法再给玩家一组钻石，并且给他发送一个消息“Wow！你看上去很土豪啊！”。所以修改背包并不像我们想象的那么难，如果我们想实现让玩家进入游戏，检测到一组钻石后删掉这组钻石，只需要把代码里的inventory.addItem(itemstack)替换成inventory.remove(itemstack)。或许你还需要把“Wow！你看上去很土豪啊！”改成“Wow！你看上去好穷啊！”2333333。

== 控制物品 ==

当你需要写一个对物品们做出行为的代码时，你要使用ItemStack类来查阅有关那个栈的所有设置信息。

=== 附魔属性 ===

你想给一个物品附魔，你首先需要了解[http://www.minecraftwiki.net/wiki/Data_values Item Code]和[http://www.minecraftwiki.net/wiki/Talk:Enchanting#Effect_IDs Effect ID]. Enchantments他们自己不能例示(new Enchantment() won't work) 因为他们是抽象的。所以你必须要用一个EnchantmentWrapper。如果你想去附魔物品，还不想在默认的SMP里附魔，可以使用addEnchantment()里面的addUnsafeEnchantment()

<source lang="java">
int itemCode = 280; //use the item code you want here
int effectId = 20; //use the enchantment code you want here
int enchantmentLevel = 100;

ItemStack myItem = new ItemStack(itemCode); //new item of item code
Enchantment myEnchantment = new EnchantmentWrapper(effectId); //new enchantment of effect id
myItem.addEnchantment(myEnchantment, enchantmentLevel); //给物品附魔
</source>

=== ItemMeta ===
You can set the display name of an item by doing this.
<source lang="java">
String myDisplayName = "Awesome Sword"; //这里是保存了你想要显示的名字

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //你要更改的方块
ItemMeta im = myItem.getItemMeta(); //得到方块的元数据
im.setDisplayName(myDisplayName); //设置它显示的名字
myItem.setItemMeta(im); //保存更改
</source>
You can also set the lores of an item. The lores are the small annotations on an item, like "+5 attack damage" on a stone sword.
<source lang="java">
List<String> lores = new ArrayList<String>();
lores.add("Example lore", "this one comes on line 2");

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //your item
ItemMeta im = myItem.getItemMeta(); //get the itemmeta of the item again
im.setLore(lores); //add the lores of course
myItem.setItemMeta(im); //give the item the new itemmeta
</source>

== Maps, and Sets, and Lists, Oh My! <ref>标题中Map,Set,List均为Java类集中的接口，故不翻译</ref> ==

除了Map类和HashMap类，Java中还提供了其它的数据结构类集。

他们提供这些不同的类，是因为有些时候，使用Map类并不合适。<nowiki>[[Java data structure classes]]</nowiki>在这个条目中，有对Java数据框架类集更深入的讲述。

<nowiki>=== HashMaps概览以及如何使用此接口 ===</nowiki>

<nowiki><big></nowiki>

<nowiki>'''</nowiki>Keep in mind to never use a player in a hashmap!<nowiki>'''</nowiki><ref>下面有讲解。</ref>

应在HashMap中使用字符串.，使用 "p.getName()" 来添加，移除或是检查列表中是否含有某个玩家.

将玩家当作object储存在HashMap中会造成大量内存泄漏.

<nowiki></big></nowiki>

When making a plugin you will get to a point where just using single variables to state an event has happened or a condition has been met will be insufficient, due to more than one player performing that action/event.

This was the problem I had with one of my old plugins, Zones, now improved and re-named to Regions. I was getting most of these errors because I didn't consider how the plugin would behave on an actual server with more than one on at any given time. I was using a single boolean variable to check whether players were in the region or not and obviously this wouldn't work as the values for each individual player need to be separate. So if one player was in a region and one was out the variable would constantly be changing which could/would/did cause numerous errors.

A HashMap is an excellent way of doing this. A HashMap is a way of mapping/assigning a value to a key. You could set up the HashMap so that the key is a player and the value could be anything you want, however the useful things with HashMaps is that one key can only contain one value and there can be no duplicate keys. So say for example I put "adam" as the key and assigned a value of "a" to it. That would work as intended, but then say afterwards I wanted to assign the value of "b" to key "adam" I would be able to and would get no errors but the value of "a" assigned to key "adam" in the HashMap would be overwritten because HashMaps cannot contain duplicate values.

<nowiki>==== Defining a HashMap ====</nowiki>

<nowiki><blockquote><source lang="java">public Map<KeyType, DataType> HashMapName = new HashMap<>(); //Example syntax</nowiki>

// Example Declaration

public Map<String, Boolean> pluginEnabled = new HashMap<>();

public Map<String, Boolean> isGodMode = new HashMap<>();

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Keep that code in mind because we will be using it for the rest of the tutorial on HashMaps. So, for example lets create a simple function which will toggle whether the plugin has been enabled or not. Firstly, inside your on command function which I explained earlier you will need to create a function to send the player name to the function and adjust the players state accordingly.

So inside on command you'll need this, the function name can be different but for the sake of simplicity it's best if you keep it the same.

<nowiki><blockquote><source lang="java">Player player = (Player) sender;</nowiki>

togglePluginState(player);<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

This code above will cast the value of sender to player and pass that argument to the function togglePluginState(). But now we need to create our togglePluginState() function.

<nowiki><blockquote><source lang="java">public void togglePluginState(Player player) {</nowiki>

// Notice how we use the player name as the key here,

// not the player object

String playerName = player.getName();

if (pluginEnabled.containsKey(playerName)) {

if (pluginEnabled.get(playerName)) {

pluginEnabled.put(playerName, false);

player.sendMessage("Plugin disabled");

} else {

pluginEnabled.put(playerName, true);

player.sendMessage("Plugin enabled");

}

} else {

pluginEnabled.put(playerName, true); //If you want plugin disabled by default change this value to false.

player.sendMessage("Plugin enabled");

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Now, what this code is doing is checking if the HashMap first contains the key player, so if it has been put into the HashMap, if it is then we check the value of the HashMap key by get(player); if this is true then set value to false and send the player a message, else if the value is false then do the opposite, set the value to true and send a message again. But if the HashMap does not contain the key player then we can assume that this is their first run/use so we change the default value and add the player to the HashMap.

<nowiki>==== More Ideas for HashMaps ====</nowiki>

A HashMap (or really any kind of Map in Java) is an association. It allows quick and efficient lookup of some sort of <nowiki>'''value''', given a unique '''key'''</nowiki>. Anywhere this happens in your code, a Map may be your solution.

Here are a few other ideas which are ideally suited to using Maps. As you will see, it doesn't have to be data that you store per player, but can be any kind of data that needs to be "translated" from one form to another.

<nowiki>===== Data Value Lookups =====</nowiki>

<nowiki><blockquote><source lang="java"></nowiki>

public Map<String, Integer> wool_colors = new HashMap<>();

// Run this on plugin startup (ideally reading from a file instead of copied out row by row):

wool_colors.put("orange", 1);

wool_colors.put("magenta", 2);

wool_colors.put("light blue", 3);

..

wool_colors.put("black", 15);

// Run this in response to user commands - turn "green" into 13

int datavalue = 0;

if (wool_colors.containsKey(argument)) {

datavalue = wool_colors.get(argument);

} else {

try { datavalue = Integer.parseInt(argument); }

catch (Exception e) {}

}

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

<nowiki>==== Saving/Loading a HashMap ====</nowiki>

Once you know how to work with HashMaps, you probably want to know how to save and load the HashMap data. Saving and loading HashMap data is appropriate if

<nowiki>*</nowiki>you don't want an administrator to edit the data manually

<nowiki>*</nowiki>you need to save data in binary format (too complex to organize for YAML)

<nowiki>*</nowiki>you want to avoid parsing block names and/or other objects from freeform text

This is very simple way how to save any HashMap. You can replace HashMap&lt;String, Integer&gt; with any type of HashMap you want. Let's take an example HashMap with code to save it:

<nowiki><blockquote><source lang="java"></nowiki>

HashMap<String, Integer> mapToSave = new HashMap<String,Integer>();

public void save(HashMap<String, Integer> map, String path) {

try {

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(map);

oos.flush();

oos.close();

//Handle I/O exceptions

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

save(mapToSave, getDataFolder() + File.separator + "example.bin");<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can see it's really easy. Loading works very very similar but we use ObjectInputStream instead of ObjectOutputStream ,FileInputStream instead of FileOutputStream,readObject() instead of writeObject() and we return the HashMap.

<nowiki><blockquote><source lang="java">public HashMap<String, Integer> load(String path) {</nowiki>

try {

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

Object result = ois.readObject();

//you can feel free to cast result to HashMap<String, Integer> if you know there's that HashMap in the file

return (HashMap<String, Integer>)result;

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

HashMap<Integer, String> loadedMap;

String path = getDataFolder() + File.separator + "example.bin";

File file = new File(path);

if (file.exists()) { // check if file exists before loading to avoid errors!

loadedMap = load(path);

}<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can use this "API" for saving/loading HashMaps, ArrayLists, and all Objects which implement Serializable or Externalizable interface.

<nowiki><blockquote><source lang="java">/** SLAPI = Saving/Loading API</nowiki>

* API for Saving and Loading Objects.

* Everyone has permission to include this code in their plugins as they wish :)

* @author Tomsik68<tomsik68@gmail.com>

*/

public class SLAPI

{

public static <T extends Object> void save(T obj,String path) throws Exception

{

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(obj);

oos.flush();

oos.close();

}

public static <T extends Object> T load(String path) throws Exception

{

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

T result = (T)ois.readObject();

ois.close();

return result;

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Example implementation of this API: <nowiki>'''</nowiki>I'm skipping some part of code in this source<nowiki>'''</nowiki>

<nowiki><blockquote><source lang="java">public class Example extends JavaPlugin {</nowiki>

private ArrayList<Object> list = new ArrayList<>();

@Override

public void onEnable() {

try {

list = SLAPI.load("example.bin");

} catch(Exception e) {

//handle the exception

e.printStackTrace();

}

}

@Override

public void onDisable() {

try {

SLAPI.save(list,"example.bin");

} catch(Exception e) {

e.printStackTrace();

}

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Note #1: This will work un-modified with almost all well-known Java types like Integer, String, HashMap. It will also work for some Bukkit types as well. If you're writing your own data object classes, and you may want to save their state using this technique, you should read about Java's Serializable or Externalizable interface. The only difference between Externalizable and Serializable is, that Serializable automatically takes all of class's fields and tries to serialize them, while Externalizable allows you to define method for reading and writing the Object. It's easy to add to your code, and it will make your data persistent with very little work required. No more parsing!

Note #2: This API doesn't support changes. Once you change something in the class, data files saved with older version of your plugin won't load correctly.

<nowiki>===== Tips & Examples =====</nowiki>

1.) Simplify your save structure

Try to use as much simple types as possible. E.g. if you want to save player, save their UUID instead. If you want to save world, save its UUID. If you want to save location, save x,y,z world UUID. DO NOT DIRECTLY SAVE BUKKIT TYPES!

2.) Save version number along with data

You should always remember, that you don't know what you'll be saving in the same file tomorrow. Will you ever migrate this file because of newer version of your plugin, bukkit, or minecraft? You don't know!

3.) Migrate older files

If your plugin finds older version of some file, it should update the file accordingly and change version number.

<references />

== 元数据 ==

Bukkit正在尝试尽可能的让制作插件变得更简单，所以带有一个键值例如Player, Entity, World，甚至是一个block的HashMaps都可以用元数据取缔掉。元数据是一些替代HashMap的方式。他可以允许你去自定义"fields"给Players, Entities, Worlds and Blocks.这些东西都是元数据类的一个成员(详见[http://jd.bukkit.org/doxygen/de/d59/interfaceorg_1_1bukkit_1_1metadata_1_1MetadataValue.html#ab49975fe013a0626dd29d3b85c63a82f])It works very simply. Everything that is Metadatable holds its own HashMap of Metadata which you have access to. That means, for example, if you're creating an economy plugin, you would need a HashMap of Player and Float or Double. 如果用了元数据，你不必去做! You just attach to player new metadata 值, and that's it! 

=== 为何要去使用元数据 ===

* Metadata is all handled by Bukkit, which makes it a very good alternative to HashMaps.
* 元数据可以用来跟其他插件分享信息与数据。

=== 为什么不去使用元数据 ===

* Slightly more difficult to get the value.
* It is not saved on shutdown (but then again, neither are any Maps that you create).

=== 获取 & 设置元数据 ===

<source lang="java">
public void setMetadata(Metadatable object, String key, Object value, Plugin plugin) {
object.setMetadata(key, new FixedMetadataValue(plugin,value));
}

public Object getMetadata(Metadatable object, String key, Plugin plugin) {
List<MetadataValue> values = object.getMetadata(key);
for (MetadataValue value : values) {
// Plugins are singleton objects, so using == is safe here
if (value.getOwningPlugin() == plugin) {
return value.value();
}
}
return null;
}</source>

Note: If you're manipulating with numbers, booleans or strings, use convenient method to get the result. For example, you can use asInt(), asString() or asBoolean() instead of value to find out the value.

== Databases ==

Sometimes flat files aren't enough for what your looking to do, this is where databases come in. The most common database engines available on Linux/Mac/Windows machines typically run on some flavor of SQL (Structured Query Language).

Software offering SQL allow you to create databases with columns and header to identify to contents of each cell. Think of it as a spreadsheet on steroids, where every column you set up in your database can enforce rules to ensure integrity. Apart from being more organised than a simple custom data file, SQL provides faster access and better searching than flat files.

The SQL standard helps applications like Bukkit implement database storage for their data in a consistent way. Unfortunately, there's more than one SQL-ready database engine, and each has minor differences in how to configure and use it. Which one you choose may depend on your particular needs. (Some plugins even offer configurable options to connect to multiple database engines!)

=== SQLite ===

Alta189 has written a [http://forums.bukkit.org/threads/lib-tut-mysql-sqlite-bukkit-drivers.33849/ fantastic SQLite tutorial] which I suggest you watch if you're interested in using SQL in your plugins, included with the tutorials is a handy library you can download and import to make using SQL easier. Once you have watched these video tutorials I would suggest you go and learn some SQL syntax, it's very straightforward and shouldn't take you long to pick up. SQL Tutorials [http://www.w3schools.com/sql/default.asp @W3Schools] and [http://www.1keydata.com/sql/sql.html @1Keydata].

SQLite is great for very simple databases, because there's no server concerns to set up. Just make a few calls to create a new database and table. It's easy to back up: just copy the whole database file in one go. SQLite is a little bit weaker at data integrity, flexibility in data types, and it may not be something you would want to trust for huge databases of millions of rows. But for a new plugin in development, it's often easiest and fastest to get the SQL basics squared away with SQLite, even if you "graduate" to a more server-class database engine later.

=== MySQL ===

Another popular SQL database engine is called MySQL. It is closer to server-grade than SQLite, where many popular companies or websites depend on it for millions of webpage hits every day. With that security comes a little bit steeper learning-curve, because MySQL has more tunable parameters and capabilities.

The coding for plugins accessing MySQL is mostly the same as tiny SQLite or mega-sized Oracle, with only small differences in syntax here or there. But the administration has room to grow. You may want to set up accounts and privileges inside your MySQL setup. You may want to set up SQL scripts that organize your backups and rollback to previous states.

== 部署你的插件 ==

总之你写好的你的插件,如何把它变成一个可安装在服务端的jar文件呢?

首先我们需要建立一个水桶服务器。 [http://wiki.bukkit.org/Setting_up_a_server 在这里] 能找到开服相关信息.接下来你需要把插件导出为一个.jar文件，

这样你就能在你的服务器里运行它。在Eclipse里, 右键工程，点击''Run as > Maven install''即可:

[[Image:Maveninstall.png]]

将来呢, 当你对插件进行了改动后,在做上述操作之前，如果你想删除之前的.jar文件，你可以右键工程，点击 ''Run as > Maven clean'' 。

如果你在编译插件时遇到了问题, 请检查你的JDK是否正确安装，并浏览[[建立工作区]]条目。

如果你在Eclipse控制台看到了和JDK有关的错误，你可能需要手动调整JDK,因为Eclipse的检测可能发生了错误。

点击''Window -> Preferences'', 然后是''Java -> Installed JREs''。选中你最近安装的JDK作为Java运行环境（JRE）并添加, 并取消掉原来那个报错的JDK:

[[Image:Jrelocation.png]]

如果你的工程成功被编译,JAR文件会生产在 ''target'' 目录下，具体在Eclipse的工作空间里名字为工程名的文件夹中。

这个JAR文件就是一个能正常工作的Bukkit插件了。当然前提是你的plugin.yml里没出差错。

你可以把这个jar文件丢到服务器的plugins文件夹里,重载或重启服务器,就可以测试你的新插件啦。

为了连接上使用你自己的电脑开的服务器 ,在多人游戏的ip里填上你的本地ip即可。

如果出现了错误而你又不能解决的话, 试试这里[http://forums.bukkit.org/forums/plugin-development.5/ plugin development forum],

在这里提问[http://wiki.bukkit.org/IRC bukkitdev IRC channel],或者重新阅读wiki。

当你做完了一个实用的插件,可以考虑把它发表在这里[http://dev.bukkit.org/ dev.bukkit]（为了Bukkit社区的访问量）。

以上可知,JAR格式是默认压缩生成的(JAR文件基于ZIP文件的格式)。这么说来，在上传插件到Bukkit上时把JAR文件压缩成ZIP只会增加文件体积罢了。

而且呢, 放在JAR中的config文件可以在检测不到插件目录（插件自动生成的文件夹，名字与插件名相同，里面是该插件的配置）下的config文件时自动生成。

所以我们一般不把jar文件转换成其他格式。

== 导入其它插件 ==
你可能会希望编辑其它那些有源代码的插件. 如果插件在它的目录下有''pom.xml''(大多数知名插件,例如WorldEdit和Essentials都有),你可以通过点击''File -> Import''来把它作为一个工程导入, 然后打开''Maven''项并选择''Existing Maven Projects'':

[[Image:Importmaven.png]]

然后选择''pom.xml''所在的目录,这个工程就应该出现在你的侧边栏里了。就像平常一样编辑并编译它吧。

== 小贴士 ==

=== 使玩家着火 ===

Bukkit API有很多碉堡的功能。以下是实现一些功能的代码片段。

下面的代码运行一个玩家使另一个玩家着火。通过类似于'''/ignite Notch'''这样的指令，这个指令会让 Notch 着火。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 使用 equalsIgnoreCase() 来忽视大小写
if (cmd.getName().equalsIgnoreCase("ignite")) {
// 确保玩家只输入了一个自变量(要被点着的玩家名).
if (args.length != 1) {
// 当return false时，该指令的使用信息会显示出来。
return false;
}

// 确保命令发出者是个玩家.
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can set other players on fire.");
sender.sendMessage("This is an arbitrary requirement for demonstration purposes only.");
return true;
}

// 获取那个要被点着的玩家. 请注意下标起始是0，不是1.
Player target = Bukkit.getServer().getPlayer(args[0]);

// 确保这个玩家在线。
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}

// 让这个玩家着火1000 ticks (一秒钟大概有20ticks,所以总共是50秒).
target.setFireTicks(1000);
return true;
}
return false;
}

=== 干掉玩家 ===

和标题一样.这里是要干掉某个玩家。

在你的onCommand方法里使用这个:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("KillPlayer")) {
Player target = sender.getServer().getPlayer(args[0]);
// 确保玩家在线.
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}
target.setHealth(0);
}
return false;
}

这里有个小扩展,会使用一个爆炸来杀死玩家:

float explosionPower = 4F; //爆炸等级 - TNT的爆炸等级默认是4F
Player target = sender.getWorld().getPlayer(args[0]);
target.getWorld().createExplosion(target.getLocation(), explosionPower);
target.setHealth(0);

=== 创造一个假爆炸 ===

这段代码会生产一个看起来和听起来与TNT/苦力怕产生的爆炸一样的效果。但是不会对实体和方块产生破坏。在保留爆炸的艺术的同时又削弱了爆炸的威力，真是太有用了（
@EventHandler
public void onExplosionPrime(ExplosionPrimeEvent event) {
Entity entity = event.getEntity();

// 如果事件和点燃的TNT有关,执行一些代码（又略）
if (entity instanceof TNTPrimed) {
entity.getWorld().createExplosion(entity.getLocation(), 0);
}
}

=== 使一个玩家对另外一个玩家隐形 ===

通过输入指令，能让指令执行者对特定的玩家隐形。然而其他人仍然能看到指令执行者。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("HideMe") && args.length == 1) {
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can use this command!");
return true;
}
// 检测指令执行者是玩家后，我们便可以安全的进行强制转换类操作。
Player s = (Player) sender;

// 获取命令执行者指定的玩家
Player target = Bukkit.getServer().getPlayer(args[0]);
if (target == null) {
sender.sendMessage("Player " + args[0] + " is not online.");
return true;
}
// 将 s 从 target 的视野中隐藏起来.
target.hidePlayer(s);
return true;
}
return false;
}

=== 在玩家准星所指处生产闪电 ===

如下代码运行手持鱼竿的玩家通过点击来生成闪电 (当然要用准星瞄准)。真是个简单好玩的恶作剧（。

@EventHandler
public void onPlayerInteractBlock(PlayerInteractEvent event) {
Player player = event.getPlayer();
if (player.getItemInHand().getType() == Material.FISHING_ROD) {
// 在给定坐标中生成一道闪电. 在本例中, 这个坐标是玩家准星瞄准的地方.
// 只能指向200格以内的坐标.
player.getWorld().strikeLightning(player.getTargetBlock(null, 200).getLocation());
}
}

=== 自动格式 ===

Eclipse提供了将你的代码自动转成Oracle规定的格式, 修正了不符合常规的缩进, 空格等等。在侧边栏选中你的项目,然后选择''Source -> Format''即可对其进行更改。

== 插件需求专区 ==

http://forums.bukkit.org/forums/plugin-requests.13/

== 范例文件和样板 ==

*[https://github.com/Bukkit/SamplePlugin/ Bukkit/SamplePlugin on GitHub]

*[http://pastebin.com/wpeTPx7N Example.Java]

*[http://pastebin.com/MTwaAVCT ExamplePlayerListener.Java]

*[http://pastebin.com/6FLixfH3 ExampleBlockListener.Java]

*[http://pastebin.com/8UZ6pkWC ExampleEntityListener.Java]

If you have any more questions on this matter, don't hesitate to visit the BukkitDev [[IRC]] channel and ask!

[[Category:开发教程]]

Bukkit/插件开发教程

2015-09-03T09:01:38Z

Tdiant：更正错别字

{{模板:待翻译}}
{{模板:待完善}}
本页面英文原文内容来源 [http://wiki.bukkit.org/Plugin_Tutorial]
== 介绍 ==

这篇内容丰富的教程旨在帮助你学会如何开发Bukkit插件.这一篇教程不可能完全涉及到Bukkit中所有的可能性,而是最基本的一般概述. 前提是你懂得Java这门语言,并在IDE中设置好你的工作区,此教程介绍了大多数Bukkit插件所必需的语法结构.

== 学习Java ==

'''理解这些教程需要具备Java这门编程语言的基本知识.'''如果你刚开始学习Java或者需要重温一下相关知识，下面有一个并不完整的网站列表可供参考.

<big>[http://docs.oracle.com/javase/tutorial/ Oracle's Java Tutorials]</big> - 官方教程
*[http://www.java2s.com/Tutorial/Java/CatalogJava.htm Java2s.com] - 教程
*[http://www.javacoffeebreak.com/java101/java101.html Java 101] - 教程
*[http://math.hws.edu/javanotes/ JavaNotes] - 免费的在线教科书
*[http://thenewboston.org/list.php?cat=31 TheNewBoston] - 视频教程.

== 开发环境 ==

在编写一个插件前 (或学习Java前) 你需要配置一个开发者环境，这个包括但不限于安装IDE (Integrated Development Environment，集成开发环境)。接下来的教程中有关于Eclipse上IDE的操作指南。

:: ''更多信息，请参见 [[Bukkit/插件开发教程-建立工作区|建立工作区]]''

你'''必须'''下载'''Java'''开发者使用的Eclipse构建版本, '''不是''' '''Java EE'''开发者的版本。 Java EE 开发者的版本不包含此教程需要的Maven支持。

== 新建插件开发项目 ==
=== 创建一个新的项目 ===

在开始工作之前，你需要先在Eclipse中配置好工作区和文件. 打开Eclipse,然后依次点击''File -> New -> Project:''来创建一个新的项目.

[[Image:Newproject.png]]

现在,打开''Maven''文件夹, 然后选择''Maven Project''.点击next,之后在下一个菜单中选择''Create a simple project'', 再次点击''Next'':
如果你看不到''Maven''文件夹, 那么你需要[http://eclipse.org/m2e/download/ 下载m2eclipse]

[[Image:Newproject2.png]]

现在，你需要给你的组用户命名，就像下面这样:
* 如果你拥有一个域名，package则填写逆转的域名地址.
** 例如: i-am-a-bukkit-developer.com 你的package地址即是com.i_am_a_bukkit_developer [http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html source]
** 避免使用一个不属于你自己的域名.
* 没有域名? 这里有几种方法可供选择。
*# 在资源管理站点创建一个用户，比如GitHub或是sourceforge
*#* 对于使用GitHub的用户, 请参照[http://pages.github.com/ 这里的说明] 之后你将获得一个子域名,所以你的package地址是io.github.<username> 
*# 使用你的邮箱. 例如: <username>@gmail.com格式的邮箱应输入com.gmail.<username> 
*# 最不济的方法.：使用独特的组名命名方式，这应当是你最后的解决方法。

以下几个地址不能作为package中的地址前缀:
* org.bukkit
* net.bukkit
* com.bukkit
* net.minecraft

完成基础的组名以后，你需要在最后加上插件的名称. 在这里用 GitHub页面作为讲解的实例. 如果你创建了一个名为 ''TestPlugin''的插件，那么完整的组名是''io.github.<username>'', 你的工程名也是 ''TestPlugin''. 至于版本，默认即可，稍后可以修改。
完成向导:

[[Image:Newproject3.png]]

如果这是你首次使用Eclipse, 点击右上角的"X" 来关闭Welcome提示页面. 现在，你的窗口视图看起来就像下面的图片这样:

[[Image:Eclipsemain.png]]

点击工程名称右边的箭头来进行下一步，现在我们正式开始。
=== 添加Bukkit API ===

在开发插件之前，你需要添加 Bukkit API库文件到你的项目，作为一个dependency, 你也可以添加其他你想实用的API.

找到项目文件夹中部的''pom.xml''并双击进行编辑. 点击''pom.xml''中部的 tab,你将会看到下图所示内容:

[[Image:Pomeditor.png]]

如果你想使用Java 6以上版本的语言特性,你需要指定搭建项目的Java版本.复制并粘贴以下内容(设定项目只能使用Java 7及以下的版本)到 ''</project>''之前:

<code>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<nowiki><</nowiki>source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
</plugins>
</build>
</code>

你或许想使用其他版本,例如 <code>1.8</code> 使用Java 8. 请注意 [http://mcstats.org/global/ 根据MCStats数据统计], 大多数服主选择了Java 7, 所以使用Java 8会使许多服务器无法运行你的插件. 如果你使用Java 1.7的特性, Eclipse将会在报错代码"error"中建议你更改语言版本.同意即可.

在位于代码中段的''</project>''之前粘贴以下内容(这段代码告诉Eclipse关于Bukkit's repository的地址):

<code>
<repositories>
<repository>
<id>bukkit-repo</id>
<url>http://repo.bukkit.org/content/groups/public/</url>
</repository>
</repositories>
</code>

然后继续在 ''</project>''前粘贴以下内容 (这段代码告诉Eclipse搭建插件的Bukkit版本):

<code>
<dependencies>
<dependency>
<groupId>org.bukkit</groupId>
<artifactId>bukkit</artifactId>
<version>1.7.2-R0.3</version>
<type>jar</type>
<scope>provided</scope>
</dependency>
</dependencies>
</code>

你也可以修改这里的Bukkit版本.你可以在[http://repo.bukkit.org/content/groups/public/org/bukkit/bukkit/ here]这里通过查看 maven-metadata.xml文件下的版本列表来获取可用的服务端版本号.

当你完成上述步骤后,''pom.xml''中的内容应该是这样:

[[Image:Finishedpom.png]]

通过菜单 ''File -> Save''或者按住 <code>Ctrl + S</code> 来保存''pom.xml''文件 . 之后, 右键项目标题，然后依次选择 ''Maven -> Update Project''.

=== Bukkit Java文档 ===

如果你曾经使用过Eclipse和Java，你会知道当你将鼠标准心移至class或者 method中的代码部分时，一个含有相关文档内容的黄色小框会弹出来. 这就是（Java的）Java文档。

你可以[http://download.oracle.com/javase/6/docs/api/ Oracle website 在线获取]它.。Bukkit同样拥有文档，这些文档内容包含了关于API中method和class的有用描述。

你可以在[http://jd.bukkit.org/ 这]找到它 (Beta版的Java文档在[http://jd.bukkit.org/ 这]找, 新开发出来的Java文档在

[http://jd.bukkit.org/ 这]) 。为了在Eclipse里使用Java文档,这样的话当你的鼠标停留在Bukkit的class和method上时，

（Bukkit的）Java文档就会冒出来。
JavaDoc in spigot [https://hub.spigotmc.org/javadocs/bukkit/ Click Here]

首先右键在侧边栏里的"Maven Dependencies"下面的Bukkit jar,选择"Properties".选中窗口左边的''Javadoc Location'', 并粘贴如下网址

'''http://jd.bukkit.org/''' (或者上面的测试版/最新版 Java文档链接也好) 到"Javadoc URL"下面的输入框内. 就像这样:

[[Image:Bukkitjavadocs.png]]

点击 "Validate",然后再点击"OK"就完成了.现在Bukkit Javadocs已经连接到Bukkit提供的资源,同时你也可以通过Eclipse来获得帮助类文档信息了.

=== 创建一个包 ===

现在你需要创建一个包，它将储存所有我们需要使用的Java类文件. 右键展开''src/main/java''折叠并选择 ''New > Package'':

[[Image:Newpackage.png]]

包名的话，先写上你的组名，然后加个点，再写上你的小写Artifact ID。举例, 如果你的组名是''io.github.name''，你的artifact名是 ''TestPlugin''。

你的包名就应该是''io.github.name.testplugin''.

=== 创建插件的类文件 ===

既然我们已经建立好了我们的项目，我们接下来可以开始添加类文件以及制作插件了. 插件的主类指的是拓展(extends)JavaPlugin的类文件. 在你的插件中只能有一个类文件拓展JavaPlugin，无论直接还是间接. 先创建你的主类文件并保持名称与插件名一致是个很好的习惯.右键你之前新建的包,并选择  ''New > Class''.你将会创建一个新的类文件，就像下面这样

package {$GroupName}.{$ArtifactName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$ArtifactName} extends JavaPlugin {

}

警告：插件绝对不应该调用自己的构造函数并实例化

=== 创建plugin.yml ===

你已经创建了项目和主类，如果你想要Bukkit能够加载你的插件，你还必须创建 '''[[Plugin YAML|plugin.yml]]''' 文件. 这个文件包含有基础的插件信息，如果缺失这个文件，你的插件也将会失效. 此时你需要右键''src/main/resources''. 选择''New > File''. 命名为"'''plugin.yml'''" 并右键完成新文件的创建.Eclipse会打开默认的文本编辑窗口来显示'''plugin.yml'''文件中空白的内容并提供编辑. ''(Hint: 如果你想要使得你的工作空间更加规整，关闭文本编辑器并将'''plugin.yml''' 文件拖到主工作空间(拖到文件目录的右边) 之后你就可以在eclipse中编辑文件了.)''

有三个基础的内容需要在plugin.yml写明.
: name: 插件名称.
: main: [http://docs.oracle.com/javase/specs/jls/se7/html/jls-6.html#jls-6.7 插件主类的完整，合法名称] .
: version: 插件当前版本号.

最简单的 '''plugin.yml''' 文件内就像这样 :

name: {插件名称}
main: {包名}.{主类}
version: {版本号}

PS:插件的包名经常会包括插件的名称，所以看到这个的时候不要感到惊讶。
你的主类是否是你的插件名取决于你之前的命名方式，时刻记住这一点很重要。

'''''更多例子''', 请看[[#Example_Files_and_Templates]]''

此时你的插件已经可以被Bukkit加载了,同时服务端日志也会开始记录你的插件. 不过它现在什么用都没有!

== onEnable()和onDisable()方法 ==

这些方法将在插件启用与卸载时生效. 默认情况下，你的插件在被加载时会调用这些方法，所以你可以在这里注册你需要用到的事件和提供一些调试信息. <code>onEnable()</code> 方法会在插件启用时被调用, 需要包含初始化插件的逻辑语句. <code>onDisable()</code> 方法会在插件卸载时被调用，需要包含清理(clean up)插件的逻辑语句和连接声明(associated state)。此外，插件可以重写 <code>onLoad()</code> 方法来在插件载入时执行附加的逻辑语句。

=== onEnable()和onDisable()方法介绍 ===

在前面的章节中，我们在主类创建了<code>onEnable()</code> 和 <code>onDisable()</code> 方法. 此时，这些代码看起来就像下面这样

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
// 插件载入时要执行的代码（略）
}

@Override
public void onDisable() {
// 插件卸载时要执行的代码（略）
}
}

这些方法已经创建，但目前它们还没有任何作用.
注意: 不需要添加代码来实现输出信息"{$PluginName} has been enabled!" ，因为bukkit会自动输出此类信息
有关更多事件的信息请查看 [[Event_API_Reference|这里]].

=== 发送提示信息 ===

插件能够输出信息至控制台与服务器日志。这是通过调用插件记录器里正确的方法来实现的。首先我们必须调用 <code>getLogger()</code> 方法来检索该插件的记录器，

然后我们就可以开始记录信息了。

我们通过调用<code>onEnable()</code>方法可以实现输出信息。我们需要在<code>onEnable()</code>方法下面插入如下代码：

getLogger().info("onEnable has been invoked!");

在 <code>'''onDisable()'''</code>方法里面，你也可以做类似的事情，不过要改改输出信息。

此时你的主类文件就像这样:

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
getLogger().info("onEnable has been invoked!");
}

@Override
public void onDisable() {
getLogger().info("onDisable has been invoked!");
}
}

=== 防止重载后插件失效 ===

你需要知道的是，插件并不只会伴随服务器关闭、启动而重载，你的插件也可能会被其他插件启用、关闭，或是在服务器运行时使用/reload命令.
假设服务器启动之后一会儿后，你的插件才被启用，这时便是危险的,因为服务器中可能已经有玩家在线、额外的世界被加载以及很多预想不到的不同之处(与"插件同服务器同时加载"的情况相比较).

举个例子来说:
* 你有一个用来储存HashMap中的玩家登入信息的插件
* 你希望该信息对所有玩家都可见
* 一名管理员使用/reload命令
* 你的插件被卸载，所有储存的数据都丢失了
* 你的插件被再次启用时，一些玩家已经在线
* 这些玩家在HashMap并没有储存的信息
* 你试图重新获得他们的信息，但是失败了!

为了插件重载以后能够正常工作, 你需要在插件启用时加载所有已经在线的玩家的信息并将之储存在HashMap中.

for (Player player : Bukkit.getServer().getOnlinePlayers()) {
playerList.put(player.getName(), playerData(player));
}

== 监听器 ==
监听器是一种方法被调用来对事件作出反应的类.所有的监听器使用 org.bukkit.event.Listener接口.更多有关监听器创建的细节,
:: '' 请查看: [[Event API Reference]]''

== 指令 ==

=== onCommand() 方法 ===

现在你已经知道如何注册一个事件并做出响应,但是如果你只是想要在命令输入之后做出响应呢? 你可以使用 <code>'''onCommand'''</code>方法.

这个代码的作用是当玩家输入“/”时，监听该操作并执行相关语句"/" . 举个例子来说.输入 "/do something" 将会执行 <code>'''onCommand'''</code>方法.

此种情况下，因为没有特定的行为被编程，所以并不会发生任何事情。

请避免使用和bukkit所提供的指令重名的指令, 然后深思你的指令名的唯一性。

例如.指令"give"已经被好几个插件使用了, 如果你执行了另外一个"give"指令, 你的插件将会和这些插件冲突。

你必须在插件的"plugins.yml"注册你的指令否则这个方法将不会被触发。

<code>'''onCommand'''</code>方法必须返回一个布尔值（true或false）。

如果返回值是true，你不会看到什么明显的事情发生。

但如果返回值是false，则会返回你的plugin.yml里的'usage:property'然后发送给命令使用者.

当使用 <code>'''onCommand'''</code>方法时, 你需要填写4个参数.

*<code>'''CommandSender sender'''</code> - 发送命令的对象

*<code>'''Command cmd'''</code> - 被执行的指令

*<code>'''String commandLabel'''</code> - 被执行指令的别名

*<code>'''String[] args'''</code> - 该指令的自变量数组。

例如.指令 ''/hello abc def'' 中， ''abc'' 会被存放进args[0]中, ''def'' 被存放进args[1]中。

==== 设置命令 ====
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { // 如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} //如果以上内容成功执行，则返回true
// 如果执行失败，则返回false.
return false;
}

每当使用<code>'''onCommand'''</code>方法时，在每个方法后面都加上一个 return false; 是一个惯例。

返回false会显示在plugin.yml里设置的usage信息 (看下面). 用这种方法的话，一旦执行出错便会显示usage信息。

每当方法return一个值的时候，这个方法就会退出，所以return true的时候，在它下面的代码就会被跳过,

除非return语句在一个if的嵌套中，或者类似的嵌套情况。

<code>'''.equalsIgnoreCase("basic")'''</code>代表忽略英文大小写. 在这种情况下,字符串"BAsIc" 和 "BasiC"和 basic相同，代码会被照常执行。

和以前一样，加两行import在你的java文件头

import org.bukkit.command.Command;

import org.bukkit.command.CommandSender;

=== 在Plugin.yml中添加你的指令 ===

你需要添加你的指令到 '''plugin.yml''' 文件里. 如下是指令/basic添加到 '''plugin.yml'''的例子（请在plugins.yml的末尾添加如下代码）:

commands:
basic:
description: This is a demo command.
usage: /<command> [player]
permission: <plugin name>.basic
permission-message: You don't have <permission></source> </code> </blockquote>

*<code>'''basic'''</code> - 指令名称

*<code>'''description'''</code> - 指令描述

*<code>'''usage'''</code> - 在oncommand方法return false后显示的用法提示。尽量简洁, 使别人能够理解指令是什么以及如何使用它。

*<code>'''permission'''</code> - 被一些显示帮助信息的插件使用，用来决定向玩家显示哪个指令（完全不对劲吧！）。

*<code>'''permission-message'''</code> - 当玩家使用了这个指令而没有权限时输出的信息。

PS:yml文件使用两个空格作为制表符,使用tab键输入制表符会导致错误。

===控制台指令vs玩家指令===

你可能注意到了上文的<code>'''CommandSender sender'''</code>参数. <code>'''CommandSender'''</code> 是个Bukkit接口，

它有两个（对插件编写者）有用的子类：<code>'''Player'''</code> 和 <code>'''ConsoleCommandSender'''</code>.

所以当你编写插件的时候, 确定这个指令从控制台发出后能完全正常工作是十分必要的,

那些只能由在线玩家执行的指令 ''只能'' 由一个在线玩家执行。

有的插件在判断命令执行对象不是玩家时仅仅用return进行处理 (比如当有人从控制台发出指令),

即便这些指令能够在控制台完美运行（比如改变天气的指令）。

一个判断sender的方法:
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { //如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} else if (cmd.getName().equalsIgnoreCase("basic2")) {
if (!(sender instanceof Player)) { //如果sender与Player类不匹配
sender.sendMessage("This command can only be run by a player.");
} else {
Player player = (Player) sender;
// 所需要执行的事（此处略）
}
return true;
}
return false;
}

在这个例子里，指令'''basic'''能由任何人发出 - 一个在线的玩家, 或者服务器后台的op.

但是指令'''basic2'''只能由一个在线的玩家发出.

大体上说,你应该允许尽可能多的指令在控制台和玩家聊天框里都正常执行.

需要在线玩家执行的指令可以使用以上例子中的机制来检测<code>'''CommandSender'''</code>是一个玩家.

很多指令广泛依靠于一些玩家的属性（例如可以被tp或被给予物品等等）。

如果你想更进一步, 你可以对你的指令的自变量做一些额外的检测，例如传送指令在提供玩家ID的情况下（也只有在这种情况下）可以在控制台被执行。

=== 使用独立的 CommandExecutor class ===

以上的例子必须把 <code>'''onCommand()'''</code> 方法放在插件的主类里。

对于小插件来说，这是极好的,但如果你要写一个大点的插件,把你的 <code>'''onCommand()'''</code>方法放在独立的类里将会很有意义。

幸运的是，这并不难:

*在你的包里创建一个新类. 命名为'''MyPluginCommandExecutor'''之类的 (当然，要把'''MyPlugin'''替换成你制作的插件的名字)。这个类 '''必须''' 继承Bukkit 的'''CommandExecutor'''接口。

*在你的插件的<code>'''onEnable()'''</code>方法中,你需要实例化你创建的命令执行类(CommandExecutor class), 然后做一个像下面一样的调用：<code>getCommand("basic").setExecutor(myExecutor);</code>
其中"basic"是我们需要操控的指令, <code>myExecutor</code> 是我们创建的实例.

废话少说直接吔我例子:

'''MyPlugin.java''' (插件的主类):
@Override
public void onEnable() {
// 如果你没有在plugins.yml注册过指令的话，此处会抛出空指针异常！
this.getCommand("basic").setExecutor(new MyPluginCommandExecutor(this));
}

'''MyPluginCommandExecutor.java'''（独立CommandExecutor类）:
public class MyPluginCommandExecutor implements CommandExecutor {
private final MyPlugin plugin;

public MyPluginCommandExecutor(MyPlugin plugin) {
this.plugin = plugin; // Store the plugin in situations where you need it.
}

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 和以前一样执行就好…
}
}

请注意我们是如何把主类里的对象指向'''MyPluginCommandExecutor'''的. 这允许我们轻易的使用主类对象的方法（如果我们需要的话）。

这么做的话, 我们便能更好的组织代码 - 如果 <code>'''onCommand()'''</code> 方法又大又复杂, 它就能被划分为子类，从而不使插件的主类显得凌乱。

PS：如果你的插件含有多个指令的话, 你需要为每一个指令单独设立一个commandexecutor.

=== 写一个安全的指令 ===
当写一个指令的时候,别进行任何假设（很重要）, 例如假设执行者一定是个玩家. 请牢记以下原则:

==== 在命令执行前确定发出者是玩家 ====

使用简单的例子来进行检测:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (sender instanceof Player) {
Player player = (Player) sender;
// do something
} else {
sender.sendMessage("You must be a player!");
return false;
}
// do something
return false;
}

==== 检测自变量个数 ====

别老是认为玩家都能打对正确数量的自变量.

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (args.length > 4) {
sender.sendMessage("Too many arguments!");
return false;
}
if (args.length < 2) {
sender.sendMessage("Not enough arguments!");
return false;
}
}

==== 在获取玩家之前先检测他们是否在线 ====

有时你想通过命令发出者打出的ID来获取其他玩家，请确保他们在线再说！

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
Player target = (Bukkit.getServer().getPlayer(args[0]));
if (target == null) {
sender.sendMessage(args[0] + " is not online!");
return false;
}
return false;
}

如果你想对离线玩家进行操作，<code>'''OfflinePlayer'''</code>类提供了基础操作的方法.

== 插件的配置/设置 ==
Bukkit API 为插件提供了一种简便的方法，用来管理用户自定义的设置。同时，通过这种方法也可以储存数据。
:: ''详情请查看: [[Configuration API Reference]]''

== 权限 ==

利用新的Bukkit API来设置权限是再容易不过的事情. 检测玩家是否拥有权限，可以使用以下代码:
<blockquote><source lang="java">if (player.hasPermission("some.pointless.permission")) {
//执行此段代码(有权限)
} else {
//执行此段代码(无权限)
}</source> </blockquote>
你也可以检测一个权限节点是否被定义过，(等效于 Java 语言中的'''null''')，使用下面的方法:
<blockquote><source lang="java">boolean isPermissionSet(String name)</source></blockquote>
你或许对此抱有疑惑:为什么这段代码中没有任何用户群的信息？因为它们并不是必需的. 之前这段代码想要实现的主要功能之一就是根据用户群格式化聊天信息. 但其实使用权限就可以很容易地完成这项工作.你可以在聊天插件的配置文件中定义权限与前缀的对应关系. 举例来说，"someChat.prefix.admin" 权限可以对应前缀[Admin].当拥有此权限的玩家发出聊天信息时，聊天前缀便是[Admin].

另一个想要实现的主要功能则是给所有拥有权限的在线用户发一条信息.你可以这样做:
<blockquote><source lang="java">for (Player player: Bukkit.getServer().getOnlinePlayers()) {
if (player.hasPermission("send.receive.message")) {
player.sendMessage("You were sent a message");
}
}</source> </blockquote>
看到这里你可能会问，若是没有权限组我该如何配置玩家的 [[权限]] ？既然 [[Bukkit]] API 本身并没有提供用户组的预设, 你必须通过安装一款权限组插件，像 [[permissionsBukkit]] 这样的插件来帮助你配置用户群. '''API 只是提供接口而不是提供已实现的类.'''

=== 配置权限 ===
{{Hide|标题=译者注 |内容= 其一，以下代码中部分内容将以''//文字''翻译，使用时请不要加入其中内容，仅做教程中的翻译参考；
其二，default:true在下面翻译为全员默认拥有该权限，default:false则翻译为全员默认没有该权限，请注意理解。 }}
如果你想要更多地控制你的权限，例如设置权限的默认值或是子权限节点，不如将权限节点加入你的 ''[[plugin.yml]]''文件.这并不是必须的，但我们推荐你这样做. 下面是一个实例，显示了当你将权限添加在''plugin.yml''文件末尾时的样子:
<blockquote><code><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //给予使用doorman所有命令的权限
children: //子权限节点
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false
doorman.kick:
description: Allows you to kick a user //允许你踢出一名用户
default: op //OP默认拥有该权限
doorman.ban:
description: Allows you to ban a user //允许你封禁一名用户
default: op //OP默认拥有该权限
doorman.knock:
description: Knocks on the door! //敲门
default: true //全员默认拥有该权限
doorman.denied:
description: Prevents this user from entering the door //禁止拥有该权限节点的用户进入门内</source> </code> </blockquote>
值得注意的是,你的插件使用的每个权限都被定义为 ''permissions'' 这个节点的子权限节点. 每个权限都能够拥有一个描述，默认值以及子权限节点。
==== 默认值 ====

当一个权限没有明确是否为玩家所拥有 ，''hasPermission''<ref>这是一个检测玩家是否拥有指定权限节点的方法</ref> 将返回false<ref>该方法返回的boolean值</ref>. 在你的[[plugin.yml]] you can change this by setting the default node to be one of four values:

*'''true''' - 全员默认拥有该权限.
*'''false''' - 全员默认没有该权限.
*'''op''' - 如果玩家是一名OP<ref>Operator，服务器管理员</ref>，那么他将拥有该权限.
*'''not op''' - 如果玩家不是一名OP，那么他将拥有该权限.

==== 子权限 ====

在这之前你可能已经习惯了通过权限节点自动分配所有的子权限<ref>原句:Before now you will probably be used to the * permission to automatically assign all sub permissions.此处的sub permissions应是同上文“你的插件使用的每个权限都被定义为 permissions 这个节点的子权限节点.”相照应</ref>. 现在这种方法已经随着bukkit API<ref>应用程序编程接口(Application Programming Interface)</ref>的更新而改变，现在你可以自己定义子权限了. 这将使得插件具有更多的灵活性. 下面是一个例子:
<blockquote><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //翻译见上
children:
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false</source> </blockquote>
在这里，''doorman.*'' 权限拥有几个子权限并分配在其下. 子权限工作的方式就是当''doorman.*'' 权限节点被设置为true时,子权限也会随之设置为 ''plugin.yml''中的默认值. 然而当''doorman.*'' 被设置为false时，所有子权限都会设置为与默认值相反的值（true->false,false->true）.
<references />

=== 设置你自己的权限 ===

如果你希望想知道更多有关开发你自己的权限插件的事情(即是设置权限的管理类插件) ，那么请前往查看教程 [[Developing a permissions plugin]].

== Scheduling Tasks and Background Tasks ==

Currently, Minecraft servers operate nearly all of the game logic in one thread, so each individual task that happens in the game needs to be kept very short. A complicated piece of code in your plugin has the potential to cause huge delays and lag spikes to the game logic, if not handled properly.

Luckily, Bukkit has support for scheduling code in your plugin. You can submit a Runnable task to occur once in the future, or on a recurring basis, or you can spin off a whole new independent thread that can perform lengthy tasks in parallel with the game logic.

There is a separate [[Scheduler Programming]] tutorial which introduces the Scheduler, and gives more information on using it to schedule synchronous tasks, and on kicking off asynchronous tasks in Bukkit.

== 方块操控 ==

这是一个很容易的方法创建、获取或修改一个方块, 例如当你想要修改往你头上数第五格的方块时, 首先你需要做的是获取你当前的坐标点, 然后往你当前的坐标点的Y轴加上五, 获取目标方块后我们便能够很容易地修改它了, 例子如下:
<blockquote><source lang="java">
@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
// 得到玩家当前的坐标.
Location loc = event.getPlayer().getLocation();
// 设置目标坐标为玩家头顶 5 格处.
loc.setY(loc.getY() + 5);
// 得到目标坐标的方块
Block b = loc.getBlock();
// 将目标坐标的方块更改为石头 (stone).
b.setType(Material.STONE);
}</source> </blockquote>
上面的代码获取了玩家的所在位置，获取头上的第五个方块，并且放上一个石头（stone）。 Note that once you have a <code>Block</code>, there are other things you can do besides set its type. 你可以查阅JavaDoc获取更多的东西。

你可以用这样相似的观念去生成一些建筑，并且还可以用编程的方式通过算法生成一些独特的方块（这里指由很多个方块拼在一起的四四方方的方块）。比如，去生成一个实心的方块建筑，你可能在生成建筑的时候还需要用到<code>for</code>循环，去一遍遍循环来生成这些建筑，填满这些建筑等。
下面，是一个在指定坐标生成一个实心的方块建筑的实例方法：
<blockquote><source lang="java">
public void generateCube(Location loc, int length) {
// 放置这个方块最中间的方块并且获取这个方块的坐标。
// Uses getBlockN() instead of getN() to avoid casting to an int later.
int x1 = loc.getBlockX();
int y1 = loc.getBlockY();
int z1 = loc.getBlockZ();

// Figure out the opposite corner of the cube by taking the corner and adding length to all coordinates.
int x2 = x1 + length;
int y2 = y1 + length;
int z2 = z1 + length;

World world = loc.getWorld();

// Loop over the cube in the x dimension.
for (int xPoint = x1; xPoint <= x2; xPoint++) {
// Loop over the cube in the y dimension.
for (int yPoint = y1; yPoint <= y2; yPoint++) {
// Loop over the cube in the z dimension.
for (int zPoint = z1; zPoint <= z2; zPoint++) {
// Get the block that we are currently looping over.
Block currentBlock = world.getBlockAt(xPoint, yPoint, zPoint);
// 设置方块ID为57号(钻石块!)
currentBlock.setType(Material.DIAMOND_BLOCK); //这里下面会提到
}
}
}
}</source></blockquote>
这个方法将会在程序给予这个方法高度和起始坐标（最中间的方块的坐标）时，构建一个3D的方块建筑。简单的删除方块也可以使用这个方法的思路实现，但是，但是设置方块的时候，记得把上面标注会提到的那行，设置为物品ID为0的方块(空气方块)。 
<blockquote></blockquote>

== (玩家)操控背包 ==

这个部分大部分讲的是操控玩家的背包。但是在某些情况下，操控箱子里的内容与此相同，当然得在你能找到获取箱子里内容的方法才可以。 :P. 这是一个操控玩家背包的一个例子:
<blockquote><source lang="java">public void onPlayerJoin(PlayerJoinEvent evt) {
Player player = evt.getPlayer(); // 当玩家加入游戏
PlayerInventory inventory = player.getInventory(); // 获取玩家背包列表
ItemStack itemstack = new ItemStack(Material.DIAMOND, 64); // 生成一组钻石

if (inventory.contains(itemstack)) {
inventory.addItem(itemstack); // 将一组钻石放到玩家的背包里
player.sendMessage("Wow！你看上去很土豪啊！"); //向玩家发送消息("Wow！你看上去很土豪啊！")
}
}</source> </blockquote>
所以，上面代码里面的 onPlayerJoin 方法中，我们首先构建了一些变量，让我们的工作变得更容易一些。变量分别是： player, inventory and itemstack。 inventory 变量是玩家的背包内容，itemstack是那64个钻石的物品栈。然后我们判断了玩家是不是有一组钻石。如果有，我们就用inventory.addItem(itemstack)方法再给玩家一组钻石，并且给他发送一个消息“Wow！你看上去很土豪啊！”。所以操控背包并不像我们想象的那么难，如果我们想实现让玩家进入游戏，检测到一组钻石后删掉这组钻石，只需要把代码里的inventory.addItem(itemstack)替换成inventory.remove(itemstack)。或许你还需要把“Wow！你看上去很土豪啊！”改成“Wow！你看上去好穷啊！”2333333。

== 控制物品 ==

当你需要写一个对物品们做出行为的代码时，你要使用ItemStack类来查阅有关那个栈的所有设置信息。

=== 附魔属性 ===

你想给一个物品附魔，你首先需要了解[http://www.minecraftwiki.net/wiki/Data_values Item Code]和[http://www.minecraftwiki.net/wiki/Talk:Enchanting#Effect_IDs Effect ID]. Enchantments他们自己不能例示(new Enchantment() won't work) 因为他们是抽象的。所以你必须要用一个EnchantmentWrapper。如果你想去附魔物品，还不想在默认的SMP里附魔，可以使用addEnchantment()里面的addUnsafeEnchantment()

<source lang="java">
int itemCode = 280; //use the item code you want here
int effectId = 20; //use the enchantment code you want here
int enchantmentLevel = 100;

ItemStack myItem = new ItemStack(itemCode); //new item of item code
Enchantment myEnchantment = new EnchantmentWrapper(effectId); //new enchantment of effect id
myItem.addEnchantment(myEnchantment, enchantmentLevel); //给物品附魔
</source>

=== ItemMeta ===
You can set the display name of an item by doing this.
<source lang="java">
String myDisplayName = "Awesome Sword"; //这里是保存了你想要显示的名字

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //你要更改的方块
ItemMeta im = myItem.getItemMeta(); //得到方块的元数据
im.setDisplayName(myDisplayName); //设置它显示的名字
myItem.setItemMeta(im); //保存更改
</source>
You can also set the lores of an item. The lores are the small annotations on an item, like "+5 attack damage" on a stone sword.
<source lang="java">
List<String> lores = new ArrayList<String>();
lores.add("Example lore", "this one comes on line 2");

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //your item
ItemMeta im = myItem.getItemMeta(); //get the itemmeta of the item again
im.setLore(lores); //add the lores of course
myItem.setItemMeta(im); //give the item the new itemmeta
</source>

== Maps, and Sets, and Lists, Oh My! <ref>标题中Map,Set,List均为Java类集中的接口，故不翻译</ref> ==

除了Map类和HashMap类，Java中还提供了其它的数据结构类集。

他们提供这些不同的类，是因为有些时候，使用Map类并不合适。<nowiki>[[Java data structure classes]]</nowiki>在这个条目中，有对Java数据框架类集更深入的讲述。

<nowiki>=== HashMaps概览以及如何使用此接口 ===</nowiki>

<nowiki><big></nowiki>

<nowiki>'''</nowiki>Keep in mind to never use a player in a hashmap!<nowiki>'''</nowiki><ref>下面有讲解。</ref>

应在HashMap中使用字符串.，使用 "p.getName()" 来添加，移除或是检查列表中是否含有某个玩家.

将玩家当作object储存在HashMap中会造成大量内存泄漏.

<nowiki></big></nowiki>

When making a plugin you will get to a point where just using single variables to state an event has happened or a condition has been met will be insufficient, due to more than one player performing that action/event.

This was the problem I had with one of my old plugins, Zones, now improved and re-named to Regions. I was getting most of these errors because I didn't consider how the plugin would behave on an actual server with more than one on at any given time. I was using a single boolean variable to check whether players were in the region or not and obviously this wouldn't work as the values for each individual player need to be separate. So if one player was in a region and one was out the variable would constantly be changing which could/would/did cause numerous errors.

A HashMap is an excellent way of doing this. A HashMap is a way of mapping/assigning a value to a key. You could set up the HashMap so that the key is a player and the value could be anything you want, however the useful things with HashMaps is that one key can only contain one value and there can be no duplicate keys. So say for example I put "adam" as the key and assigned a value of "a" to it. That would work as intended, but then say afterwards I wanted to assign the value of "b" to key "adam" I would be able to and would get no errors but the value of "a" assigned to key "adam" in the HashMap would be overwritten because HashMaps cannot contain duplicate values.

<nowiki>==== Defining a HashMap ====</nowiki>

<nowiki><blockquote><source lang="java">public Map<KeyType, DataType> HashMapName = new HashMap<>(); //Example syntax</nowiki>

// Example Declaration

public Map<String, Boolean> pluginEnabled = new HashMap<>();

public Map<String, Boolean> isGodMode = new HashMap<>();

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Keep that code in mind because we will be using it for the rest of the tutorial on HashMaps. So, for example lets create a simple function which will toggle whether the plugin has been enabled or not. Firstly, inside your on command function which I explained earlier you will need to create a function to send the player name to the function and adjust the players state accordingly.

So inside on command you'll need this, the function name can be different but for the sake of simplicity it's best if you keep it the same.

<nowiki><blockquote><source lang="java">Player player = (Player) sender;</nowiki>

togglePluginState(player);<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

This code above will cast the value of sender to player and pass that argument to the function togglePluginState(). But now we need to create our togglePluginState() function.

<nowiki><blockquote><source lang="java">public void togglePluginState(Player player) {</nowiki>

// Notice how we use the player name as the key here,

// not the player object

String playerName = player.getName();

if (pluginEnabled.containsKey(playerName)) {

if (pluginEnabled.get(playerName)) {

pluginEnabled.put(playerName, false);

player.sendMessage("Plugin disabled");

} else {

pluginEnabled.put(playerName, true);

player.sendMessage("Plugin enabled");

}

} else {

pluginEnabled.put(playerName, true); //If you want plugin disabled by default change this value to false.

player.sendMessage("Plugin enabled");

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Now, what this code is doing is checking if the HashMap first contains the key player, so if it has been put into the HashMap, if it is then we check the value of the HashMap key by get(player); if this is true then set value to false and send the player a message, else if the value is false then do the opposite, set the value to true and send a message again. But if the HashMap does not contain the key player then we can assume that this is their first run/use so we change the default value and add the player to the HashMap.

<nowiki>==== More Ideas for HashMaps ====</nowiki>

A HashMap (or really any kind of Map in Java) is an association. It allows quick and efficient lookup of some sort of <nowiki>'''value''', given a unique '''key'''</nowiki>. Anywhere this happens in your code, a Map may be your solution.

Here are a few other ideas which are ideally suited to using Maps. As you will see, it doesn't have to be data that you store per player, but can be any kind of data that needs to be "translated" from one form to another.

<nowiki>===== Data Value Lookups =====</nowiki>

<nowiki><blockquote><source lang="java"></nowiki>

public Map<String, Integer> wool_colors = new HashMap<>();

// Run this on plugin startup (ideally reading from a file instead of copied out row by row):

wool_colors.put("orange", 1);

wool_colors.put("magenta", 2);

wool_colors.put("light blue", 3);

..

wool_colors.put("black", 15);

// Run this in response to user commands - turn "green" into 13

int datavalue = 0;

if (wool_colors.containsKey(argument)) {

datavalue = wool_colors.get(argument);

} else {

try { datavalue = Integer.parseInt(argument); }

catch (Exception e) {}

}

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

<nowiki>==== Saving/Loading a HashMap ====</nowiki>

Once you know how to work with HashMaps, you probably want to know how to save and load the HashMap data. Saving and loading HashMap data is appropriate if

<nowiki>*</nowiki>you don't want an administrator to edit the data manually

<nowiki>*</nowiki>you need to save data in binary format (too complex to organize for YAML)

<nowiki>*</nowiki>you want to avoid parsing block names and/or other objects from freeform text

This is very simple way how to save any HashMap. You can replace HashMap&lt;String, Integer&gt; with any type of HashMap you want. Let's take an example HashMap with code to save it:

<nowiki><blockquote><source lang="java"></nowiki>

HashMap<String, Integer> mapToSave = new HashMap<String,Integer>();

public void save(HashMap<String, Integer> map, String path) {

try {

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(map);

oos.flush();

oos.close();

//Handle I/O exceptions

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

save(mapToSave, getDataFolder() + File.separator + "example.bin");<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can see it's really easy. Loading works very very similar but we use ObjectInputStream instead of ObjectOutputStream ,FileInputStream instead of FileOutputStream,readObject() instead of writeObject() and we return the HashMap.

<nowiki><blockquote><source lang="java">public HashMap<String, Integer> load(String path) {</nowiki>

try {

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

Object result = ois.readObject();

//you can feel free to cast result to HashMap<String, Integer> if you know there's that HashMap in the file

return (HashMap<String, Integer>)result;

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

HashMap<Integer, String> loadedMap;

String path = getDataFolder() + File.separator + "example.bin";

File file = new File(path);

if (file.exists()) { // check if file exists before loading to avoid errors!

loadedMap = load(path);

}<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can use this "API" for saving/loading HashMaps, ArrayLists, and all Objects which implement Serializable or Externalizable interface.

<nowiki><blockquote><source lang="java">/** SLAPI = Saving/Loading API</nowiki>

* API for Saving and Loading Objects.

* Everyone has permission to include this code in their plugins as they wish :)

* @author Tomsik68<tomsik68@gmail.com>

*/

public class SLAPI

{

public static <T extends Object> void save(T obj,String path) throws Exception

{

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(obj);

oos.flush();

oos.close();

}

public static <T extends Object> T load(String path) throws Exception

{

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

T result = (T)ois.readObject();

ois.close();

return result;

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Example implementation of this API: <nowiki>'''</nowiki>I'm skipping some part of code in this source<nowiki>'''</nowiki>

<nowiki><blockquote><source lang="java">public class Example extends JavaPlugin {</nowiki>

private ArrayList<Object> list = new ArrayList<>();

@Override

public void onEnable() {

try {

list = SLAPI.load("example.bin");

} catch(Exception e) {

//handle the exception

e.printStackTrace();

}

}

@Override

public void onDisable() {

try {

SLAPI.save(list,"example.bin");

} catch(Exception e) {

e.printStackTrace();

}

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Note #1: This will work un-modified with almost all well-known Java types like Integer, String, HashMap. It will also work for some Bukkit types as well. If you're writing your own data object classes, and you may want to save their state using this technique, you should read about Java's Serializable or Externalizable interface. The only difference between Externalizable and Serializable is, that Serializable automatically takes all of class's fields and tries to serialize them, while Externalizable allows you to define method for reading and writing the Object. It's easy to add to your code, and it will make your data persistent with very little work required. No more parsing!

Note #2: This API doesn't support changes. Once you change something in the class, data files saved with older version of your plugin won't load correctly.

<nowiki>===== Tips & Examples =====</nowiki>

1.) Simplify your save structure

Try to use as much simple types as possible. E.g. if you want to save player, save their UUID instead. If you want to save world, save its UUID. If you want to save location, save x,y,z world UUID. DO NOT DIRECTLY SAVE BUKKIT TYPES!

2.) Save version number along with data

You should always remember, that you don't know what you'll be saving in the same file tomorrow. Will you ever migrate this file because of newer version of your plugin, bukkit, or minecraft? You don't know!

3.) Migrate older files

If your plugin finds older version of some file, it should update the file accordingly and change version number.

<references />

== 元数据 ==

Bukkit正在尝试尽可能的让制作插件变得更简单，所以带有一个键值例如Player, Entity, World，甚至是一个block的HashMaps都可以用元数据取缔掉。元数据是一些替代HashMap的方式。他可以允许你去自定义"fields"给Players, Entities, Worlds and Blocks.这些东西都是元数据类的一个成员(详见[http://jd.bukkit.org/doxygen/de/d59/interfaceorg_1_1bukkit_1_1metadata_1_1MetadataValue.html#ab49975fe013a0626dd29d3b85c63a82f])It works very simply. Everything that is Metadatable holds its own HashMap of Metadata which you have access to. That means, for example, if you're creating an economy plugin, you would need a HashMap of Player and Float or Double. 如果用了元数据，你不必去做! You just attach to player new metadata 值, and that's it! 

=== 为何要去使用元数据 ===

* Metadata is all handled by Bukkit, which makes it a very good alternative to HashMaps.
* 元数据可以用来跟其他插件分享信息与数据。

=== 为什么不去使用元数据 ===

* Slightly more difficult to get the value.
* It is not saved on shutdown (but then again, neither are any Maps that you create).

=== 获取 & 设置元数据 ===

<source lang="java">
public void setMetadata(Metadatable object, String key, Object value, Plugin plugin) {
object.setMetadata(key, new FixedMetadataValue(plugin,value));
}

public Object getMetadata(Metadatable object, String key, Plugin plugin) {
List<MetadataValue> values = object.getMetadata(key);
for (MetadataValue value : values) {
// Plugins are singleton objects, so using == is safe here
if (value.getOwningPlugin() == plugin) {
return value.value();
}
}
return null;
}</source>

Note: If you're manipulating with numbers, booleans or strings, use convenient method to get the result. For example, you can use asInt(), asString() or asBoolean() instead of value to find out the value.

== Databases ==

Sometimes flat files aren't enough for what your looking to do, this is where databases come in. The most common database engines available on Linux/Mac/Windows machines typically run on some flavor of SQL (Structured Query Language).

Software offering SQL allow you to create databases with columns and header to identify to contents of each cell. Think of it as a spreadsheet on steroids, where every column you set up in your database can enforce rules to ensure integrity. Apart from being more organised than a simple custom data file, SQL provides faster access and better searching than flat files.

The SQL standard helps applications like Bukkit implement database storage for their data in a consistent way. Unfortunately, there's more than one SQL-ready database engine, and each has minor differences in how to configure and use it. Which one you choose may depend on your particular needs. (Some plugins even offer configurable options to connect to multiple database engines!)

=== SQLite ===

Alta189 has written a [http://forums.bukkit.org/threads/lib-tut-mysql-sqlite-bukkit-drivers.33849/ fantastic SQLite tutorial] which I suggest you watch if you're interested in using SQL in your plugins, included with the tutorials is a handy library you can download and import to make using SQL easier. Once you have watched these video tutorials I would suggest you go and learn some SQL syntax, it's very straightforward and shouldn't take you long to pick up. SQL Tutorials [http://www.w3schools.com/sql/default.asp @W3Schools] and [http://www.1keydata.com/sql/sql.html @1Keydata].

SQLite is great for very simple databases, because there's no server concerns to set up. Just make a few calls to create a new database and table. It's easy to back up: just copy the whole database file in one go. SQLite is a little bit weaker at data integrity, flexibility in data types, and it may not be something you would want to trust for huge databases of millions of rows. But for a new plugin in development, it's often easiest and fastest to get the SQL basics squared away with SQLite, even if you "graduate" to a more server-class database engine later.

=== MySQL ===

Another popular SQL database engine is called MySQL. It is closer to server-grade than SQLite, where many popular companies or websites depend on it for millions of webpage hits every day. With that security comes a little bit steeper learning-curve, because MySQL has more tunable parameters and capabilities.

The coding for plugins accessing MySQL is mostly the same as tiny SQLite or mega-sized Oracle, with only small differences in syntax here or there. But the administration has room to grow. You may want to set up accounts and privileges inside your MySQL setup. You may want to set up SQL scripts that organize your backups and rollback to previous states.

== 部署你的插件 ==

总之你写好的你的插件,如何把它变成一个可安装在服务端的jar文件呢?

首先我们需要建立一个水桶服务器。 [http://wiki.bukkit.org/Setting_up_a_server 在这里] 能找到开服相关信息.接下来你需要把插件导出为一个.jar文件，

这样你就能在你的服务器里运行它。在Eclipse里, 右键工程，点击''Run as > Maven install''即可:

[[Image:Maveninstall.png]]

将来呢, 当你对插件进行了改动后,在做上述操作之前，如果你想删除之前的.jar文件，你可以右键工程，点击 ''Run as > Maven clean'' 。

如果你在编译插件时遇到了问题, 请检查你的JDK是否正确安装，并浏览[[建立工作区]]条目。

如果你在Eclipse控制台看到了和JDK有关的错误，你可能需要手动调整JDK,因为Eclipse的检测可能发生了错误。

点击''Window -> Preferences'', 然后是''Java -> Installed JREs''。选中你最近安装的JDK作为Java运行环境（JRE）并添加, 并取消掉原来那个报错的JDK:

[[Image:Jrelocation.png]]

如果你的工程成功被编译,JAR文件会生产在 ''target'' 目录下，具体在Eclipse的工作空间里名字为工程名的文件夹中。

这个JAR文件就是一个能正常工作的Bukkit插件了。当然前提是你的plugin.yml里没出差错。

你可以把这个jar文件丢到服务器的plugins文件夹里,重载或重启服务器,就可以测试你的新插件啦。

为了连接上使用你自己的电脑开的服务器 ,在多人游戏的ip里填上你的本地ip即可。

如果出现了错误而你又不能解决的话, 试试这里[http://forums.bukkit.org/forums/plugin-development.5/ plugin development forum],

在这里提问[http://wiki.bukkit.org/IRC bukkitdev IRC channel],或者重新阅读wiki。

当你做完了一个实用的插件,可以考虑把它发表在这里[http://dev.bukkit.org/ dev.bukkit]（为了Bukkit社区的访问量）。

以上可知,JAR格式是默认压缩生成的(JAR文件基于ZIP文件的格式)。这么说来，在上传插件到Bukkit上时把JAR文件压缩成ZIP只会增加文件体积罢了。

而且呢, 放在JAR中的config文件可以在检测不到插件目录（插件自动生成的文件夹，名字与插件名相同，里面是该插件的配置）下的config文件时自动生成。

所以我们一般不把jar文件转换成其他格式。

== 导入其它插件 ==
你可能会希望编辑其它那些有源代码的插件. 如果插件在它的目录下有''pom.xml''(大多数知名插件,例如WorldEdit和Essentials都有),你可以通过点击''File -> Import''来把它作为一个工程导入, 然后打开''Maven''项并选择''Existing Maven Projects'':

[[Image:Importmaven.png]]

然后选择''pom.xml''所在的目录,这个工程就应该出现在你的侧边栏里了。就像平常一样编辑并编译它吧。

== 小贴士 ==

=== 使玩家着火 ===

Bukkit API有很多碉堡的功能。以下是实现一些功能的代码片段。

下面的代码运行一个玩家使另一个玩家着火。通过类似于'''/ignite Notch'''这样的指令，这个指令会让 Notch 着火。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 使用 equalsIgnoreCase() 来忽视大小写
if (cmd.getName().equalsIgnoreCase("ignite")) {
// 确保玩家只输入了一个自变量(要被点着的玩家名).
if (args.length != 1) {
// 当return false时，该指令的使用信息会显示出来。
return false;
}

// 确保命令发出者是个玩家.
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can set other players on fire.");
sender.sendMessage("This is an arbitrary requirement for demonstration purposes only.");
return true;
}

// 获取那个要被点着的玩家. 请注意下标起始是0，不是1.
Player target = Bukkit.getServer().getPlayer(args[0]);

// 确保这个玩家在线。
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}

// 让这个玩家着火1000 ticks (一秒钟大概有20ticks,所以总共是50秒).
target.setFireTicks(1000);
return true;
}
return false;
}

=== 干掉玩家 ===

和标题一样.这里是要干掉某个玩家。

在你的onCommand方法里使用这个:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("KillPlayer")) {
Player target = sender.getServer().getPlayer(args[0]);
// 确保玩家在线.
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}
target.setHealth(0);
}
return false;
}

这里有个小扩展,会使用一个爆炸来杀死玩家:

float explosionPower = 4F; //爆炸等级 - TNT的爆炸等级默认是4F
Player target = sender.getWorld().getPlayer(args[0]);
target.getWorld().createExplosion(target.getLocation(), explosionPower);
target.setHealth(0);

=== 创造一个假爆炸 ===

这段代码会生产一个看起来和听起来与TNT/苦力怕产生的爆炸一样的效果。但是不会对实体和方块产生破坏。在保留爆炸的艺术的同时又削弱了爆炸的威力，真是太有用了（
@EventHandler
public void onExplosionPrime(ExplosionPrimeEvent event) {
Entity entity = event.getEntity();

// 如果事件和点燃的TNT有关,执行一些代码（又略）
if (entity instanceof TNTPrimed) {
entity.getWorld().createExplosion(entity.getLocation(), 0);
}
}

=== 使一个玩家对另外一个玩家隐形 ===

通过输入指令，能让指令执行者对特定的玩家隐形。然而其他人仍然能看到指令执行者。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("HideMe") && args.length == 1) {
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can use this command!");
return true;
}
// 检测指令执行者是玩家后，我们便可以安全的进行强制转换类操作。
Player s = (Player) sender;

// 获取命令执行者指定的玩家
Player target = Bukkit.getServer().getPlayer(args[0]);
if (target == null) {
sender.sendMessage("Player " + args[0] + " is not online.");
return true;
}
// 将 s 从 target 的视野中隐藏起来.
target.hidePlayer(s);
return true;
}
return false;
}

=== 在玩家准星所指处生产闪电 ===

如下代码运行手持鱼竿的玩家通过点击来生成闪电 (当然要用准星瞄准)。真是个简单好玩的恶作剧（。

@EventHandler
public void onPlayerInteractBlock(PlayerInteractEvent event) {
Player player = event.getPlayer();
if (player.getItemInHand().getType() == Material.FISHING_ROD) {
// 在给定坐标中生成一道闪电. 在本例中, 这个坐标是玩家准星瞄准的地方.
// 只能指向200格以内的坐标.
player.getWorld().strikeLightning(player.getTargetBlock(null, 200).getLocation());
}
}

=== 自动格式 ===

Eclipse提供了将你的代码自动转成Oracle规定的格式, 修正了不符合常规的缩进, 空格等等。在侧边栏选中你的项目,然后选择''Source -> Format''即可对其进行更改。

== 插件需求专区 ==

http://forums.bukkit.org/forums/plugin-requests.13/

== 范例文件和样板 ==

*[https://github.com/Bukkit/SamplePlugin/ Bukkit/SamplePlugin on GitHub]

*[http://pastebin.com/wpeTPx7N Example.Java]

*[http://pastebin.com/MTwaAVCT ExamplePlayerListener.Java]

*[http://pastebin.com/6FLixfH3 ExampleBlockListener.Java]

*[http://pastebin.com/8UZ6pkWC ExampleEntityListener.Java]

If you have any more questions on this matter, don't hesitate to visit the BukkitDev [[IRC]] channel and ask!

[[Category:开发教程]]

Configuration API Reference

2015-09-02T12:28:01Z

Tdiant：修整名称错误

[[Configuration API Reference/en|点击此处浏览原文]]
{{待翻译}}

Configuration API是一个帮助程序员们更快地解析与编辑配置文件的设置工具，让人们觉得配置文件更简单更容易编辑。不管是什么，这个API可以帮助你更容易的存储你插件的信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而，有了这个API，设计的能有更多的扩展空间，还能允许你实现其他的东西。

Configuration API可以在 org.bukkit.configuration 和 org.bukkit.configuration.file 这俩包里找到。插件的版本如果创建在 1.1-R5之前，就只能用老的并且与此不同的方法了，这些东西在org.bukkit.util.configuration这个包里。这些实现方法彼此不兼容并且老的方法因为太OUT了，在新版中被删去了。

This introduction assumes that you have some knowledge about proper object oriented design, Java, and the core design of Bukkit plugins. This page is not a substitute for the JavaDocs for the [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]

== 基本论述 ==

=== Configuration对象 ===
<ref>key 键 value 值</ref>
你的插件继承了 [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin], 由此,你也继承了JavaPlugin这个父类的的方法和属性. 继承的方法中, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' 返回的是一个 [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]类的对象.这个对象就代表你插件数据文件夹里的''config.yml'' .

插件初次使用''getConfig()''时会把''config.yml'' 从磁盘中载入, 同时从jar中加载默认值. 但''getConfig()''的后续调用这时只会返回现存的''FileConfiguration'' 对象. 除了显式保存，对此对象执行的操作不会写入到磁盘. 同样，在文件被加载之后的任何修改将不会被反映在对象中. 如果在你的数据文件夹中不存在 ''config.yml'' ,此时在程序中等价于存在一个空的''config.yml'', 也会加载一个空的''FileConfiguration''.

{{warning| 如果你分配了利用''getConfig()''返回的对象，请不要将其分配给一个全局属性}} 
{{warning| 若要如此，记住在重载配置文件之后再把 ''getConfig()'' 分配给一个变量}} 
{{warning| 最好直接用''getConfig()''而不是将其分配给一个实例变量}}

=== 键值 ===

配置文件由键值组合构成，所有的键都是字符串.值对于其他键来说可能是一个''FileConfigurationSection''或是独立的数据. ''getKeys(boolean)'' 方法会返回现有''FileConfigurationSection''集合的值.布尔值决定返回的集合是不是递归的,如果为true，其将返回指定节点的键与子键, 如果为false则只会返回指定节点的键.为了获得特定节点的键, ''getKeys(boolean)'' 方法必须加载在特定节点. 你可以通过''getConfigurationSection(String)''方法来获取这个部分.

{{warning| getKeys(boolean)方法返回的是这里的字符串[http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html 集合]}}

=== 路径 ===

Configuration API 使用路径来形成独立的键值组合.路径是键的集合用来将其与值关联的.每层都被路径分隔符区分开来,默认的分隔符是 '.' (段落).举例来说，下面的YAML文件就有着一个路径的集合.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== 默认值 ===

你的jar中应该为用户准备一个默认的''config.yml''.当出现config.yml丢失或是不完整的情况时,程序将会访问jar内的 ''config.yml''来获取值.准备好的文件必须被命名为 ''config.yml'' ，且应当放在与 [[Plugin YAML|plugin.yml]]相同的目录. The file should have the intended structure of your ''config.yml''. This file can be copied as is into the datafolder by invoking saveDefaultConfig() on the Appropriate instance of JavaPlugin.
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

If dynamic key-value pairs are required as default values, they can added as defaults to the configuration with invocations of ''addDefault(String, Object)'' and ''addDefaults(Map<String,Object>)'' methods.

In certain cases if you wish to append new key-value pairs to an existing config.yml you can set the copyDefaults to true for the ConfigurationOptions object.
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== 创建一份config.yml的拷贝 ====
你可以使用JavaPlugin类中的saveDefaultConfig()方法，将jar中的config.yml拷贝一份至插件的数据文件夹中<ref>/plugins/YourPlugin/</ref> . saveDefaultConfig()并不会覆盖已有的文件.

=== 获得值 ===

Reading values from the configuration involves invoking one of the many getter methods. A complete list of getters can be found [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html here]. Every getter method takes a configuration path detailed above. Some of the commonly used getter methods are as follows

*getBoolean(String)
*getInt(String)
*getString(String)
*getList(String)
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== 设定值 ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== 保存文件 ===

If make any changes to the''FileConfiguration'' with set methods, or mutate any ''Lists'', you will need to save the changes to disk if you wish to keep these changes after the plugin is disabled. To save the file to disk invoke the saveConfig method for your plugin, it will overwrite the file already there. <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== 从磁盘中重载配置文件 ===

If you suspect that users have made changes to the ''config.yml'' in the data folder, those changes are not reflected in memory. Invoke the ''reloadConfig()'' method of your plugin to load from the disk again. It will destroy all changes in memory. <blockquote><source lang="java">this.reloadConfig();</source></blockquote>
<references />

== Advanced Topics ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== Options ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== Arbitrary Configurations ===

If you require additional YAML files, for storing configuration information or persisting additional game information you will need to write your own methods for accessing the additional configuration files. Modeled after JavaPlugin getConfig, reloadConfig, saveConfig methods, the following is an example how to write your own methods to read and save to custom configuration files. Since these config files belong to your plugin, you can put this method in your main class so that you can have the same access as you have with config.yml. You will have to write a set of these methods for each YAML file. The advantage here, is that you can use each set in the same manner as the provided methods for the default config.yml. Alternately, adding additional methods can keep the method count lower and allow access to multiple files.

==== Mirroring the JavaPlugin implementation ====
JavaPlugin implements methods for config.yml. A plugin needs to implement its own methods to access configuration files unique to the plugin. After implementing the methods for the plugin, they can be invoked in the same context as the inherited ''getConfig()'', ''reloadConfig()'', ''saveConfig()'', and ''saveDefaultConfig()'' methods from JavaPlugin. The following can be made into a single class which allows access to any yaml file. Such a class can be found [https://gist.github.com/3174347 here]

First you will need to declare two fields and initialize them to null for each of the custom configuration files. One to hold the ''FileConfiguration'' object and one to hold the ''File'' object. The File object represents the file on the disk, and the FileConfiguration represents the contents of the configuration.
<blockquote><source lang="java">private FileConfiguration customConfig = null;
private File customConfigFile = null;</source></blockquote>

===== Implementation for Reloading =====
Then, write the method that is responsible for loading the config from disk. It will load the file, and search the jar for a default customConfig.yml. <blockquote><source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}</source></blockquote>

===== Implementation for Getting =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk. <blockquote><source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}</source></blockquote>

===== Implementation for Saving =====
Finally, write the save method, which saves changes and overwrites the file on disk. <blockquote><source lang="java">public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}</source></blockquote>

===== Implementation for Defaults =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method. <blockquote><source lang="java">public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}</source></blockquote>

=== Serializing and Deserializing Objects ===

The Configuration API, as mentioned above can store Java objects that implement the ''ConfigurationSerializable'' Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''. 

Classes, in addition to implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== Example Use ==

Below is the an example plugin that uses the new Configuration API to be display messages as an MOTD as players join, and for the player to retrieve the rules on command. It does not follow proper style and plugin layout to keep the number of lines to a minimum.

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// Save a copy of the default config.yml if one is not there
this.saveDefaultConfig();

// Register a new listener
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// On player join send them the message from config.yml
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// Set the command executor for the rules command
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// On command send the rules from config.yml to the sender of the command
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules)
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> The default config.yml that is in the plugin's jar
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Bukkit/插件开发教程

2015-09-01T12:28:23Z

Tdiant：翻译了控制物品の附魔属性

{{模板:待翻译}}
{{模板:待完善}}
本页面英文原文内容来源 [http://wiki.bukkit.org/Plugin_Tutorial]
== 介绍 ==

这篇内容丰富的教程旨在帮助你学会如何开发Bukkit插件.这一篇教程不可能完全涉及到Bukkit中所有的可能性,而是最基本的一般概述. 前提是你懂得Java这门语言,并在IDE中设置好你的工作区,此教程介绍了大多数Bukkit插件所必需的语法结构.

== 学习Java ==

'''理解这些教程需要具备Java这门编程语言的基本知识.'''如果你刚开始学习Java或者需要重温一下相关知识，下面有一个并不完整的网站列表可供参考.

<big>[http://docs.oracle.com/javase/tutorial/ Oracle's Java Tutorials]</big> - 官方教程
*[http://www.java2s.com/Tutorial/Java/CatalogJava.htm Java2s.com] - 教程
*[http://www.javacoffeebreak.com/java101/java101.html Java 101] - 教程
*[http://math.hws.edu/javanotes/ JavaNotes] - 免费的在线教科书
*[http://thenewboston.org/list.php?cat=31 TheNewBoston] - 视频教程.

== 开发环境 ==

在编写一个插件前 (或学习Java前) 你需要配置一个开发者环境，这个包括但不限于安装IDE (Integrated Development Environment，集成开发环境)。接下来的教程中有关于Eclipse上IDE的操作指南。

:: ''更多信息，请参见 [[Bukkit/插件开发教程-建立工作区|建立工作区]]''

你'''必须'''下载'''Java'''开发者使用的Eclipse构建版本, '''不是''' '''Java EE'''开发者的版本。 Java EE 开发者的版本不包含此教程需要的Maven支持。

== 新建插件开发项目 ==
=== 创建一个新的项目 ===

在开始工作之前，你需要先在Eclipse中配置好工作区和文件. 打开Eclipse,然后依次点击''File -> New -> Project:''来创建一个新的项目.

[[Image:Newproject.png]]

现在,打开''Maven''文件夹, 然后选择''Maven Project''.点击next,之后在下一个菜单中选择''Create a simple project'', 再次点击''Next'':
如果你看不到''Maven''文件夹, 那么你需要[http://eclipse.org/m2e/download/ 下载m2eclipse]

[[Image:Newproject2.png]]

现在，你需要给你的组用户命名，就像下面这样:
* 如果你拥有一个域名，package则填写逆转的域名地址.
** 例如: i-am-a-bukkit-developer.com 你的package地址即是com.i_am_a_bukkit_developer [http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html source]
** 避免使用一个不属于你自己的域名.
* 没有域名? 这里有几种方法可供选择。
*# 在资源管理站点创建一个用户，比如GitHub或是sourceforge
*#* 对于使用GitHub的用户, 请参照[http://pages.github.com/ 这里的说明] 之后你将获得一个子域名,所以你的package地址是io.github.<username> 
*# 使用你的邮箱. 例如: <username>@gmail.com格式的邮箱应输入com.gmail.<username> 
*# 最不济的方法.：使用独特的组名命名方式，这应当是你最后的解决方法。

以下几个地址不能作为package中的地址前缀:
* org.bukkit
* net.bukkit
* com.bukkit
* net.minecraft

完成基础的组名以后，你需要在最后加上插件的名称. 在这里用 GitHub页面作为讲解的实例. 如果你创建了一个名为 ''TestPlugin''的插件，那么完整的组名是''io.github.<username>'', 你的工程名也是 ''TestPlugin''. 至于版本，默认即可，稍后可以修改。
完成向导:

[[Image:Newproject3.png]]

如果这是你首次使用Eclipse, 点击右上角的"X" 来关闭Welcome提示页面. 现在，你的窗口视图看起来就像下面的图片这样:

[[Image:Eclipsemain.png]]

点击工程名称右边的箭头来进行下一步，现在我们正式开始。
=== 添加Bukkit API ===

在开发插件之前，你需要添加 Bukkit API库文件到你的项目，作为一个dependency, 你也可以添加其他你想实用的API.

找到项目文件夹中部的''pom.xml''并双击进行编辑. 点击''pom.xml''中部的 tab,你将会看到下图所示内容:

[[Image:Pomeditor.png]]

如果你想使用Java 6以上版本的语言特性,你需要指定搭建项目的Java版本.复制并粘贴以下内容(设定项目只能使用Java 7及以下的版本)到 ''</project>''之前:

<code>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<nowiki><</nowiki>source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
</plugins>
</build>
</code>

你或许想使用其他版本,例如 <code>1.8</code> 使用Java 8. 请注意 [http://mcstats.org/global/ 根据MCStats数据统计], 大多数服主选择了Java 7, 所以使用Java 8会使许多服务器无法运行你的插件. 如果你使用Java 1.7的特性, Eclipse将会在报错代码"error"中建议你更改语言版本.同意即可.

在位于代码中段的''</project>''之前粘贴以下内容(这段代码告诉Eclipse关于Bukkit's repository的地址):

<code>
<repositories>
<repository>
<id>bukkit-repo</id>
<url>http://repo.bukkit.org/content/groups/public/</url>
</repository>
</repositories>
</code>

然后继续在 ''</project>''前粘贴以下内容 (这段代码告诉Eclipse搭建插件的Bukkit版本):

<code>
<dependencies>
<dependency>
<groupId>org.bukkit</groupId>
<artifactId>bukkit</artifactId>
<version>1.7.2-R0.3</version>
<type>jar</type>
<scope>provided</scope>
</dependency>
</dependencies>
</code>

你也可以修改这里的Bukkit版本.你可以在[http://repo.bukkit.org/content/groups/public/org/bukkit/bukkit/ here]这里通过查看 maven-metadata.xml文件下的版本列表来获取可用的服务端版本号.

当你完成上述步骤后,''pom.xml''中的内容应该是这样:

[[Image:Finishedpom.png]]

通过菜单 ''File -> Save''或者按住 <code>Ctrl + S</code> 来保存''pom.xml''文件 . 之后, 右键项目标题，然后依次选择 ''Maven -> Update Project''.

=== Bukkit Java文档 ===

如果你曾经使用过Eclipse和Java，你会知道当你将鼠标准心移至class或者 method中的代码部分时，一个含有相关文档内容的黄色小框会弹出来. 这就是（Java的）Java文档。

你可以[http://download.oracle.com/javase/6/docs/api/ Oracle website 在线获取]它.。Bukkit同样拥有文档，这些文档内容包含了关于API中method和class的有用描述。

你可以在[http://jd.bukkit.org/ 这]找到它 (Beta版的Java文档在[http://jd.bukkit.org/ 这]找, 新开发出来的Java文档在

[http://jd.bukkit.org/ 这]) 。为了在Eclipse里使用Java文档,这样的话当你的鼠标停留在Bukkit的class和method上时，

（Bukkit的）Java文档就会冒出来。
JavaDoc in spigot [https://hub.spigotmc.org/javadocs/bukkit/ Click Here]

首先右键在侧边栏里的"Maven Dependencies"下面的Bukkit jar,选择"Properties".选中窗口左边的''Javadoc Location'', 并粘贴如下网址

'''http://jd.bukkit.org/''' (或者上面的测试版/最新版 Java文档链接也好) 到"Javadoc URL"下面的输入框内. 就像这样:

[[Image:Bukkitjavadocs.png]]

点击 "Validate",然后再点击"OK"就完成了.现在Bukkit Javadocs已经连接到Bukkit提供的资源,同时你也可以通过Eclipse来获得帮助类文档信息了.

=== 创建一个包 ===

现在你需要创建一个包，它将储存所有我们需要使用的Java类文件. 右键展开''src/main/java''折叠并选择 ''New > Package'':

[[Image:Newpackage.png]]

包名的话，先写上你的组名，然后加个点，再写上你的小写Artifact ID。举例, 如果你的组名是''io.github.name''，你的artifact名是 ''TestPlugin''。

你的包名就应该是''io.github.name.testplugin''.

=== 创建插件的类文件 ===

既然我们已经建立好了我们的项目，我们接下来可以开始添加类文件以及制作插件了. 插件的主类指的是拓展(extends)JavaPlugin的类文件. 在你的插件中只能有一个类文件拓展JavaPlugin，无论直接还是间接. 先创建你的主类文件并保持名称与插件名一致是个很好的习惯.右键你之前新建的包,并选择  ''New > Class''.你将会创建一个新的类文件，就像下面这样

package {$GroupName}.{$ArtifactName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$ArtifactName} extends JavaPlugin {

}

警告：插件绝对不应该调用自己的构造函数并实例化

=== 创建plugin.yml ===

你已经创建了项目和主类，如果你想要Bukkit能够加载你的插件，你还必须创建 '''[[Plugin YAML|plugin.yml]]''' 文件. 这个文件包含有基础的插件信息，如果缺失这个文件，你的插件也将会失效. 此时你需要右键''src/main/resources''. 选择''New > File''. 命名为"'''plugin.yml'''" 并右键完成新文件的创建.Eclipse会打开默认的文本编辑窗口来显示'''plugin.yml'''文件中空白的内容并提供编辑. ''(Hint: 如果你想要使得你的工作空间更加规整，关闭文本编辑器并将'''plugin.yml''' 文件拖到主工作空间(拖到文件目录的右边) 之后你就可以在eclipse中编辑文件了.)''

有三个基础的内容需要在plugin.yml写明.
: name: 插件名称.
: main: [http://docs.oracle.com/javase/specs/jls/se7/html/jls-6.html#jls-6.7 插件主类的完整，合法名称] .
: version: 插件当前版本号.

最简单的 '''plugin.yml''' 文件内就像这样 :

name: {插件名称}
main: {包名}.{主类}
version: {版本号}

PS:插件的包名经常会包括插件的名称，所以看到这个的时候不要感到惊讶。
你的主类是否是你的插件名取决于你之前的命名方式，时刻记住这一点很重要。

'''''更多例子''', 请看[[#Example_Files_and_Templates]]''

此时你的插件已经可以被Bukkit加载了,同时服务端日志也会开始记录你的插件. 不过它现在什么用都没有!

== onEnable()和onDisable()方法 ==

这些方法将在插件启用与卸载时生效. 默认情况下，你的插件在被加载时会调用这些方法，所以你可以在这里注册你需要用到的事件和提供一些调试信息. <code>onEnable()</code> 方法会在插件启用时被调用, 需要包含初始化插件的逻辑语句. <code>onDisable()</code> 方法会在插件卸载时被调用，需要包含清理(clean up)插件的逻辑语句和连接声明(associated state)。此外，插件可以重写 <code>onLoad()</code> 方法来在插件载入时执行附加的逻辑语句。

=== onEnable()和onDisable()方法介绍 ===

在前面的章节中，我们在主类创建了<code>onEnable()</code> 和 <code>onDisable()</code> 方法. 此时，这些代码看起来就像下面这样

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
// 插件载入时要执行的代码（略）
}

@Override
public void onDisable() {
// 插件卸载时要执行的代码（略）
}
}

这些方法已经创建，但目前它们还没有任何作用.
注意: 不需要添加代码来实现输出信息"{$PluginName} has been enabled!" ，因为bukkit会自动输出此类信息
有关更多事件的信息请查看 [[Event_API_Reference|这里]].

=== 发送提示信息 ===

插件能够输出信息至控制台与服务器日志。这是通过调用插件记录器里正确的方法来实现的。首先我们必须调用 <code>getLogger()</code> 方法来检索该插件的记录器，

然后我们就可以开始记录信息了。

我们通过调用<code>onEnable()</code>方法可以实现输出信息。我们需要在<code>onEnable()</code>方法下面插入如下代码：

getLogger().info("onEnable has been invoked!");

在 <code>'''onDisable()'''</code>方法里面，你也可以做类似的事情，不过要改改输出信息。

此时你的主类文件就像这样:

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
getLogger().info("onEnable has been invoked!");
}

@Override
public void onDisable() {
getLogger().info("onDisable has been invoked!");
}
}

=== 防止重载后插件失效 ===

你需要知道的是，插件并不只会伴随服务器关闭、启动而重载，你的插件也可能会被其他插件启用、关闭，或是在服务器运行时使用/reload命令.
假设服务器启动之后一会儿后，你的插件才被启用，这时便是危险的,因为服务器中可能已经有玩家在线、额外的世界被加载以及很多预想不到的不同之处(与"插件同服务器同时加载"的情况相比较).

举个例子来说:
* 你有一个用来储存HashMap中的玩家登入信息的插件
* 你希望该信息对所有玩家都可见
* 一名管理员使用/reload命令
* 你的插件被卸载，所有储存的数据都丢失了
* 你的插件被再次启用时，一些玩家已经在线
* 这些玩家在HashMap并没有储存的信息
* 你试图重新获得他们的信息，但是失败了!

为了插件重载以后能够正常工作, 你需要在插件启用时加载所有已经在线的玩家的信息并将之储存在HashMap中.

for (Player player : Bukkit.getServer().getOnlinePlayers()) {
playerList.put(player.getName(), playerData(player));
}

== 监听器 ==
监听器是一种方法被调用来对事件作出反应的类.所有的监听器使用 org.bukkit.event.Listener接口.更多有关监听器创建的细节,
:: '' 请查看: [[Event API Reference]]''

== 指令 ==

=== onCommand() 方法 ===

现在你已经知道如何注册一个事件并做出响应,但是如果你只是想要在命令输入之后做出响应呢? 你可以使用 <code>'''onCommand'''</code>方法.

这个代码的作用是当玩家输入“/”时，监听该操作并执行相关语句"/" . 举个例子来说.输入 "/do something" 将会执行 <code>'''onCommand'''</code>方法.

此种情况下，因为没有特定的行为被编程，所以并不会发生任何事情。

请避免使用和bukkit所提供的指令重名的指令, 然后深思你的指令名的唯一性。

例如.指令"give"已经被好几个插件使用了, 如果你执行了另外一个"give"指令, 你的插件将会和这些插件冲突。

你必须在插件的"plugins.yml"注册你的指令否则这个方法将不会被触发。

<code>'''onCommand'''</code>方法必须返回一个布尔值（true或false）。

如果返回值是true，你不会看到什么明显的事情发生。

但如果返回值是false，则会返回你的plugin.yml里的'usage:property'然后发送给命令使用者.

当使用 <code>'''onCommand'''</code>方法时, 你需要填写4个参数.

*<code>'''CommandSender sender'''</code> - 发送命令的对象

*<code>'''Command cmd'''</code> - 被执行的指令

*<code>'''String commandLabel'''</code> - 被执行指令的别名

*<code>'''String[] args'''</code> - 该指令的自变量数组。

例如.指令 ''/hello abc def'' 中， ''abc'' 会被存放进args[0]中, ''def'' 被存放进args[1]中。

==== 设置命令 ====
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { // 如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} //如果以上内容成功执行，则返回true
// 如果执行失败，则返回false.
return false;
}

每当使用<code>'''onCommand'''</code>方法时，在每个方法后面都加上一个 return false; 是一个惯例。

返回false会显示在plugin.yml里设置的usage信息 (看下面). 用这种方法的话，一旦执行出错便会显示usage信息。

每当方法return一个值的时候，这个方法就会退出，所以return true的时候，在它下面的代码就会被跳过,

除非return语句在一个if的嵌套中，或者类似的嵌套情况。

<code>'''.equalsIgnoreCase("basic")'''</code>代表忽略英文大小写. 在这种情况下,字符串"BAsIc" 和 "BasiC"和 basic相同，代码会被照常执行。

和以前一样，加两行import在你的java文件头

import org.bukkit.command.Command;

import org.bukkit.command.CommandSender;

=== 在Plugin.yml中添加你的指令 ===

你需要添加你的指令到 '''plugin.yml''' 文件里. 如下是指令/basic添加到 '''plugin.yml'''的例子（请在plugins.yml的末尾添加如下代码）:

commands:
basic:
description: This is a demo command.
usage: /<command> [player]
permission: <plugin name>.basic
permission-message: You don't have <permission></source> </code> </blockquote>

*<code>'''basic'''</code> - 指令名称

*<code>'''description'''</code> - 指令描述

*<code>'''usage'''</code> - 在oncommand方法return false后显示的用法提示。尽量简洁, 使别人能够理解指令是什么以及如何使用它。

*<code>'''permission'''</code> - 被一些显示帮助信息的插件使用，用来决定向玩家显示哪个指令（完全不对劲吧！）。

*<code>'''permission-message'''</code> - 当玩家使用了这个指令而没有权限时输出的信息。

PS:yml文件使用两个空格作为制表符,使用tab键输入制表符会导致错误。

===控制台指令vs玩家指令===

你可能注意到了上文的<code>'''CommandSender sender'''</code>参数. <code>'''CommandSender'''</code> 是个Bukkit接口，

它有两个（对插件编写者）有用的子类：<code>'''Player'''</code> 和 <code>'''ConsoleCommandSender'''</code>.

所以当你编写插件的时候, 确定这个指令从控制台发出后能完全正常工作是十分必要的,

那些只能由在线玩家执行的指令 ''只能'' 由一个在线玩家执行。

有的插件在判断命令执行对象不是玩家时仅仅用return进行处理 (比如当有人从控制台发出指令),

即便这些指令能够在控制台完美运行（比如改变天气的指令）。

一个判断sender的方法:
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { //如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} else if (cmd.getName().equalsIgnoreCase("basic2")) {
if (!(sender instanceof Player)) { //如果sender与Player类不匹配
sender.sendMessage("This command can only be run by a player.");
} else {
Player player = (Player) sender;
// 所需要执行的事（此处略）
}
return true;
}
return false;
}

在这个例子里，指令'''basic'''能由任何人发出 - 一个在线的玩家, 或者服务器后台的op.

但是指令'''basic2'''只能由一个在线的玩家发出.

大体上说,你应该允许尽可能多的指令在控制台和玩家聊天框里都正常执行.

需要在线玩家执行的指令可以使用以上例子中的机制来检测<code>'''CommandSender'''</code>是一个玩家.

很多指令广泛依靠于一些玩家的属性（例如可以被tp或被给予物品等等）。

如果你想更进一步, 你可以对你的指令的自变量做一些额外的检测，例如传送指令在提供玩家ID的情况下（也只有在这种情况下）可以在控制台被执行。

=== 使用独立的 CommandExecutor class ===

以上的例子必须把 <code>'''onCommand()'''</code> 方法放在插件的主类里。

对于小插件来说，这是极好的,但如果你要写一个大点的插件,把你的 <code>'''onCommand()'''</code>方法放在独立的类里将会很有意义。

幸运的是，这并不难:

*在你的包里创建一个新类. 命名为'''MyPluginCommandExecutor'''之类的 (当然，要把'''MyPlugin'''替换成你制作的插件的名字)。这个类 '''必须''' 继承Bukkit 的'''CommandExecutor'''接口。

*在你的插件的<code>'''onEnable()'''</code>方法中,你需要实例化你创建的命令执行类(CommandExecutor class), 然后做一个像下面一样的调用：<code>getCommand("basic").setExecutor(myExecutor);</code>
其中"basic"是我们需要操控的指令, <code>myExecutor</code> 是我们创建的实例.

废话少说直接吔我例子:

'''MyPlugin.java''' (插件的主类):
@Override
public void onEnable() {
// 如果你没有在plugins.yml注册过指令的话，此处会抛出空指针异常！
this.getCommand("basic").setExecutor(new MyPluginCommandExecutor(this));
}

'''MyPluginCommandExecutor.java'''（独立CommandExecutor类）:
public class MyPluginCommandExecutor implements CommandExecutor {
private final MyPlugin plugin;

public MyPluginCommandExecutor(MyPlugin plugin) {
this.plugin = plugin; // Store the plugin in situations where you need it.
}

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 和以前一样执行就好…
}
}

请注意我们是如何把主类里的对象指向'''MyPluginCommandExecutor'''的. 这允许我们轻易的使用主类对象的方法（如果我们需要的话）。

这么做的话, 我们便能更好的组织代码 - 如果 <code>'''onCommand()'''</code> 方法又大又复杂, 它就能被划分为子类，从而不使插件的主类显得凌乱。

PS：如果你的插件含有多个指令的话, 你需要为每一个指令单独设立一个commandexecutor.

=== 写一个安全的指令 ===
当写一个指令的时候,别进行任何假设（很重要）, 例如假设执行者一定是个玩家. 请牢记以下原则:

==== 在命令执行前确定发出者是玩家 ====

使用简单的例子来进行检测:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (sender instanceof Player) {
Player player = (Player) sender;
// do something
} else {
sender.sendMessage("You must be a player!");
return false;
}
// do something
return false;
}

==== 检测自变量个数 ====

别老是认为玩家都能打对正确数量的自变量.

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (args.length > 4) {
sender.sendMessage("Too many arguments!");
return false;
}
if (args.length < 2) {
sender.sendMessage("Not enough arguments!");
return false;
}
}

==== 在获取玩家之前先检测他们是否在线 ====

有时你想通过命令发出者打出的ID来获取其他玩家，请确保他们在线再说！

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
Player target = (Bukkit.getServer().getPlayer(args[0]));
if (target == null) {
sender.sendMessage(args[0] + " is not online!");
return false;
}
return false;
}

如果你想对离线玩家进行操作，<code>'''OfflinePlayer'''</code>类提供了基础操作的方法.

== 插件的配置/设置 ==
Bukkit API 为插件提供了一种简便的方法，用来管理用户自定义的设置。同时，通过这种方法也可以储存数据。
:: ''详情请查看: [[Configuration API Reference]]''

== 权限 ==

利用新的Bukkit API来设置权限是再容易不过的事情. 检测玩家是否拥有权限，可以使用以下代码:
<blockquote><source lang="java">if (player.hasPermission("some.pointless.permission")) {
//执行此段代码(有权限)
} else {
//执行此段代码(无权限)
}</source> </blockquote>
你也可以检测一个权限节点是否被定义过，(等效于 Java 语言中的'''null''')，使用下面的方法:
<blockquote><source lang="java">boolean isPermissionSet(String name)</source></blockquote>
你或许对此抱有疑惑:为什么这段代码中没有任何用户群的信息？因为它们并不是必需的. 之前这段代码想要实现的主要功能之一就是根据用户群格式化聊天信息. 但其实使用权限就可以很容易地完成这项工作.你可以在聊天插件的配置文件中定义权限与前缀的对应关系. 举例来说，"someChat.prefix.admin" 权限可以对应前缀[Admin].当拥有此权限的玩家发出聊天信息时，聊天前缀便是[Admin].

另一个想要实现的主要功能则是给所有拥有权限的在线用户发一条信息.你可以这样做:
<blockquote><source lang="java">for (Player player: Bukkit.getServer().getOnlinePlayers()) {
if (player.hasPermission("send.receive.message")) {
player.sendMessage("You were sent a message");
}
}</source> </blockquote>
看到这里你可能会问，若是没有权限组我该如何配置玩家的 [[权限]] ？既然 [[Bukkit]] API 本身并没有提供用户组的预设, 你必须通过安装一款权限组插件，像 [[permissionsBukkit]] 这样的插件来帮助你配置用户群. '''API 只是提供接口而不是提供implementation.'''

=== 配置权限 ===
{{Hide|标题=译者注 |内容= 其一，以下代码中部分内容将以''//文字''翻译，使用时请不要加入其中内容，仅做教程中的翻译参考；
其二，default:true在下面翻译为全员默认拥有该权限，default:false则翻译为全员默认没有该权限，请注意理解。 }}
如果你想要更多地控制你的权限，例如设置权限的默认值或是子权限节点，不如将权限节点加入你的 ''[[plugin.yml]]''文件.这并不是必须的，但我们推荐你这样做. 下面是一个实例，显示了当你将权限添加在''plugin.yml''文件末尾时的样子:
<blockquote><code><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //给予使用doorman所有命令的权限
children: //子权限节点
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false
doorman.kick:
description: Allows you to kick a user //允许你踢出一名用户
default: op //OP默认拥有该权限
doorman.ban:
description: Allows you to ban a user //允许你封禁一名用户
default: op //OP默认拥有该权限
doorman.knock:
description: Knocks on the door! //敲门
default: true //全员默认拥有该权限
doorman.denied:
description: Prevents this user from entering the door //禁止拥有该权限节点的用户进入门内</source> </code> </blockquote>
值得注意的是,你的插件使用的每个权限都被定义为 ''permissions'' 这个节点的子权限节点. 每个权限都能够拥有一个描述，默认值以及子权限节点。
==== 默认值 ====

当一个权限没有明确是否为玩家所拥有 ，''hasPermission''<ref>这是一个检测玩家是否拥有指定权限节点的方法</ref> 将返回false<ref>该方法返回的boolean值</ref>. 在你的[[plugin.yml]] you can change this by setting the default node to be one of four values:

*'''true''' - 全员默认拥有该权限.
*'''false''' - 全员默认没有该权限.
*'''op''' - 如果玩家是一名OP<ref>Operator，服务器管理员</ref>，那么他将拥有该权限.
*'''not op''' - 如果玩家不是一名OP，那么他将拥有该权限.

==== 子权限 ====

在这之前你可能已经习惯了通过权限节点自动分配所有的子权限<ref>原句:Before now you will probably be used to the * permission to automatically assign all sub permissions.此处的sub permissions应是同上文“你的插件使用的每个权限都被定义为 permissions 这个节点的子权限节点.”相照应</ref>. 现在这种方法已经随着bukkit API<ref>应用程序编程接口(Application Programming Interface)</ref>的更新而改变，现在你可以自己定义子权限了. 这将使得插件具有更多的灵活性. 下面是一个例子:
<blockquote><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //翻译见上
children:
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false</source> </blockquote>
在这里，''doorman.*'' 权限拥有几个子权限并分配在其下. 子权限工作的方式就是当''doorman.*'' 权限节点被设置为true时,子权限也会随之设置为 ''plugin.yml''中的默认值. 然而当''doorman.*'' 被设置为false时，所有子权限都会设置为与默认值相反的值（true->false,false->true）.
<references />

=== 设置你自己的权限 ===

如果你希望想知道更多有关开发你自己的权限插件的事情(即是设置权限的管理类插件) ，那么请前往查看教程 [[Developing a permissions plugin]].

== Scheduling Tasks and Background Tasks ==

Currently, Minecraft servers operate nearly all of the game logic in one thread, so each individual task that happens in the game needs to be kept very short. A complicated piece of code in your plugin has the potential to cause huge delays and lag spikes to the game logic, if not handled properly.

Luckily, Bukkit has support for scheduling code in your plugin. You can submit a Runnable task to occur once in the future, or on a recurring basis, or you can spin off a whole new independent thread that can perform lengthy tasks in parallel with the game logic.

There is a separate [[Scheduler Programming]] tutorial which introduces the Scheduler, and gives more information on using it to schedule synchronous tasks, and on kicking off asynchronous tasks in Bukkit.

== 方块操控 ==

这是一个很容易的方法创建、获取或修改一个方块, 例如当你想要修改往你头上数第五格的方块时, 首先你需要做的是获取你当前的坐标点, 然后往你当前的坐标点的Y轴加上五, 获取目标方块后我们便能够很容易地修改它了, 例子如下:
<blockquote><source lang="java">
@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
// 得到玩家当前的坐标.
Location loc = event.getPlayer().getLocation();
// 设置目标坐标为玩家头顶 5 格处.
loc.setY(loc.getY() + 5);
// 得到目标坐标的方块
Block b = loc.getBlock();
// 将目标坐标的方块更改为石头 (stone).
b.setType(Material.STONE);
}</source> </blockquote>
上面的代码获取了玩家的所在位置，获取头上的第五个方块，并且放上一个石头（stone）。 Note that once you have a <code>Block</code>, there are other things you can do besides set its type. 你可以查阅JavaDoc获取更多的东西。

你可以用这样相似的观念去生成一些建筑，并且还可以用编程的方式通过算法生成一些独特的方块（这里指由很多个方块拼在一起的四四方方的方块）。比如，去生成一个实心的方块建筑，你可能在生成建筑的时候还需要用到<code>for</code>循环，去一遍遍循环来生成这些建筑，填满这些建筑等。
下面，是一个在指定坐标生成一个实心的方块建筑的实例方法：
<blockquote><source lang="java">
public void generateCube(Location loc, int length) {
// 放置这个方块最中间的方块并且获取这个方块的坐标。
// Uses getBlockN() instead of getN() to avoid casting to an int later.
int x1 = loc.getBlockX();
int y1 = loc.getBlockY();
int z1 = loc.getBlockZ();

// Figure out the opposite corner of the cube by taking the corner and adding length to all coordinates.
int x2 = x1 + length;
int y2 = y1 + length;
int z2 = z1 + length;

World world = loc.getWorld();

// Loop over the cube in the x dimension.
for (int xPoint = x1; xPoint <= x2; xPoint++) {
// Loop over the cube in the y dimension.
for (int yPoint = y1; yPoint <= y2; yPoint++) {
// Loop over the cube in the z dimension.
for (int zPoint = z1; zPoint <= z2; zPoint++) {
// Get the block that we are currently looping over.
Block currentBlock = world.getBlockAt(xPoint, yPoint, zPoint);
// 设置方块ID为57号(钻石块!)
currentBlock.setType(Material.DIAMOND_BLOCK); //这里下面会提到
}
}
}
}</source></blockquote>
这个方法将会在程序给予这个方法高度和起始坐标（最中间的方块的坐标）时，构建一个3D的方块建筑。简单的删除方块也可以使用这个方法的思路实现，但是，但是设置方块的时候，记得把上面标注会提到的那行，设置为物品ID为0的方块(空气方块)。 
<blockquote></blockquote>

== (玩家)操控背包 ==

这个部分大部分讲的是操控玩家的背包。但是在某些情况下，操控箱子里的内容与此相同，当然得在你能找到获取箱子里内容的方法才可以。 :P. 这是一个操控玩家背包的一个例子:
<blockquote><source lang="java">public void onPlayerJoin(PlayerJoinEvent evt) {
Player player = evt.getPlayer(); // 当玩家加入游戏
PlayerInventory inventory = player.getInventory(); // 获取玩家背包列表
ItemStack itemstack = new ItemStack(Material.DIAMOND, 64); // 生成一组钻石

if (inventory.contains(itemstack)) {
inventory.addItem(itemstack); // 将一组钻石放到玩家的背包里
player.sendMessage("Wow！你看上去很土豪啊！"); //向玩家发送消息("Wow！你看上去很土豪啊！")
}
}</source> </blockquote>
所以，上面代码里面的 onPlayerJoin 方法中，我们首先构建了一些变量，让我们的工作变得更容易一些。变量分别是： player, inventory and itemstack。 inventory 变量是玩家的背包内容，itemstack是那64个钻石的物品栈。然后我们判断了玩家是不是有一组钻石。如果有，我们就用inventory.addItem(itemstack)方法再给玩家一组钻石，并且给他发送一个消息“Wow！你看上去很土豪啊！”。所以操控背包并不像我们想象的那么难，如果我们想实现让玩家进入游戏，检测到一组钻石后删掉这组钻石，只需要把代码里的inventory.addItem(itemstack)替换成inventory.remove(itemstack)。获取你还得把“Wow！你看上去很土豪啊！”改成“Wow！你看上去好穷啊！”2333333。

== 控制物品 ==

当你需要写一个对物品们做出行为的代码时，你要使用ItemStack类来查阅有关那个栈的所有设置信息。

=== 附魔属性 ===

你想给一个物品附魔，你首先需要了解[http://www.minecraftwiki.net/wiki/Data_values Item Code]和[http://www.minecraftwiki.net/wiki/Talk:Enchanting#Effect_IDs Effect ID]. Enchantments他们自己不能例示(new Enchantment() won't work) 因为他们是抽象的。所以你必须要用一个EnchantmentWrapper。如果你想去附魔物品，还不想在默认的SMP里附魔，可以使用addEnchantment()里面的addUnsafeEnchantment()

<source lang="java">
int itemCode = 280; //use the item code you want here
int effectId = 20; //use the enchantment code you want here
int enchantmentLevel = 100;

ItemStack myItem = new ItemStack(itemCode); //new item of item code
Enchantment myEnchantment = new EnchantmentWrapper(effectId); //new enchantment of effect id
myItem.addEnchantment(myEnchantment, enchantmentLevel); //给物品附魔
</source>

=== ItemMeta ===
You can set the display name of an item by doing this.
<source lang="java">
String myDisplayName = "Awesome Sword"; //这里是保存了你想要显示的名字

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //你要更改的方块
ItemMeta im = myItem.getItemMeta(); //得到方块的元数据
im.setDisplayName(myDisplayName); //设置它显示的名字
myItem.setItemMeta(im); //保存更改
</source>
You can also set the lores of an item. The lores are the small annotations on an item, like "+5 attack damage" on a stone sword.
<source lang="java">
List<String> lores = new ArrayList<String>();
lores.add("Example lore", "this one comes on line 2");

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //your item
ItemMeta im = myItem.getItemMeta(); //get the itemmeta of the item again
im.setLore(lores); //add the lores of course
myItem.setItemMeta(im); //give the item the new itemmeta
</source>

== Maps, and Sets, and Lists, Oh My! <ref>标题中Map,Set,List均为Java类集中的接口，故不翻译</ref> ==

除了Map类和HashMap类，Java中还提供了其它的数据结构类集。

他们提供这些不同的类，是因为有些时候，使用Map类并不合适。<nowiki>[[Java data structure classes]]</nowiki>在这个条目中，有对Java数据框架类集更深入的讲述。

<nowiki>=== HashMaps概览以及如何使用此接口 ===</nowiki>

<nowiki><big></nowiki>

<nowiki>'''</nowiki>Keep in mind to never use a player in a hashmap!<nowiki>'''</nowiki><ref>下面有讲解。</ref>

应在HashMap中使用字符串.，使用 "p.getName()" 来添加，移除或是检查列表中是否含有某个玩家.

将玩家当作object储存在HashMap中会造成大量内存泄漏.

<nowiki></big></nowiki>

When making a plugin you will get to a point where just using single variables to state an event has happened or a condition has been met will be insufficient, due to more than one player performing that action/event.

This was the problem I had with one of my old plugins, Zones, now improved and re-named to Regions. I was getting most of these errors because I didn't consider how the plugin would behave on an actual server with more than one on at any given time. I was using a single boolean variable to check whether players were in the region or not and obviously this wouldn't work as the values for each individual player need to be separate. So if one player was in a region and one was out the variable would constantly be changing which could/would/did cause numerous errors.

A HashMap is an excellent way of doing this. A HashMap is a way of mapping/assigning a value to a key. You could set up the HashMap so that the key is a player and the value could be anything you want, however the useful things with HashMaps is that one key can only contain one value and there can be no duplicate keys. So say for example I put "adam" as the key and assigned a value of "a" to it. That would work as intended, but then say afterwards I wanted to assign the value of "b" to key "adam" I would be able to and would get no errors but the value of "a" assigned to key "adam" in the HashMap would be overwritten because HashMaps cannot contain duplicate values.

<nowiki>==== Defining a HashMap ====</nowiki>

<nowiki><blockquote><source lang="java">public Map<KeyType, DataType> HashMapName = new HashMap<>(); //Example syntax</nowiki>

// Example Declaration

public Map<String, Boolean> pluginEnabled = new HashMap<>();

public Map<String, Boolean> isGodMode = new HashMap<>();

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Keep that code in mind because we will be using it for the rest of the tutorial on HashMaps. So, for example lets create a simple function which will toggle whether the plugin has been enabled or not. Firstly, inside your on command function which I explained earlier you will need to create a function to send the player name to the function and adjust the players state accordingly.

So inside on command you'll need this, the function name can be different but for the sake of simplicity it's best if you keep it the same.

<nowiki><blockquote><source lang="java">Player player = (Player) sender;</nowiki>

togglePluginState(player);<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

This code above will cast the value of sender to player and pass that argument to the function togglePluginState(). But now we need to create our togglePluginState() function.

<nowiki><blockquote><source lang="java">public void togglePluginState(Player player) {</nowiki>

// Notice how we use the player name as the key here,

// not the player object

String playerName = player.getName();

if (pluginEnabled.containsKey(playerName)) {

if (pluginEnabled.get(playerName)) {

pluginEnabled.put(playerName, false);

player.sendMessage("Plugin disabled");

} else {

pluginEnabled.put(playerName, true);

player.sendMessage("Plugin enabled");

}

} else {

pluginEnabled.put(playerName, true); //If you want plugin disabled by default change this value to false.

player.sendMessage("Plugin enabled");

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Now, what this code is doing is checking if the HashMap first contains the key player, so if it has been put into the HashMap, if it is then we check the value of the HashMap key by get(player); if this is true then set value to false and send the player a message, else if the value is false then do the opposite, set the value to true and send a message again. But if the HashMap does not contain the key player then we can assume that this is their first run/use so we change the default value and add the player to the HashMap.

<nowiki>==== More Ideas for HashMaps ====</nowiki>

A HashMap (or really any kind of Map in Java) is an association. It allows quick and efficient lookup of some sort of <nowiki>'''value''', given a unique '''key'''</nowiki>. Anywhere this happens in your code, a Map may be your solution.

Here are a few other ideas which are ideally suited to using Maps. As you will see, it doesn't have to be data that you store per player, but can be any kind of data that needs to be "translated" from one form to another.

<nowiki>===== Data Value Lookups =====</nowiki>

<nowiki><blockquote><source lang="java"></nowiki>

public Map<String, Integer> wool_colors = new HashMap<>();

// Run this on plugin startup (ideally reading from a file instead of copied out row by row):

wool_colors.put("orange", 1);

wool_colors.put("magenta", 2);

wool_colors.put("light blue", 3);

..

wool_colors.put("black", 15);

// Run this in response to user commands - turn "green" into 13

int datavalue = 0;

if (wool_colors.containsKey(argument)) {

datavalue = wool_colors.get(argument);

} else {

try { datavalue = Integer.parseInt(argument); }

catch (Exception e) {}

}

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

<nowiki>==== Saving/Loading a HashMap ====</nowiki>

Once you know how to work with HashMaps, you probably want to know how to save and load the HashMap data. Saving and loading HashMap data is appropriate if

<nowiki>*</nowiki>you don't want an administrator to edit the data manually

<nowiki>*</nowiki>you need to save data in binary format (too complex to organize for YAML)

<nowiki>*</nowiki>you want to avoid parsing block names and/or other objects from freeform text

This is very simple way how to save any HashMap. You can replace HashMap&lt;String, Integer&gt; with any type of HashMap you want. Let's take an example HashMap with code to save it:

<nowiki><blockquote><source lang="java"></nowiki>

HashMap<String, Integer> mapToSave = new HashMap<String,Integer>();

public void save(HashMap<String, Integer> map, String path) {

try {

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(map);

oos.flush();

oos.close();

//Handle I/O exceptions

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

save(mapToSave, getDataFolder() + File.separator + "example.bin");<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can see it's really easy. Loading works very very similar but we use ObjectInputStream instead of ObjectOutputStream ,FileInputStream instead of FileOutputStream,readObject() instead of writeObject() and we return the HashMap.

<nowiki><blockquote><source lang="java">public HashMap<String, Integer> load(String path) {</nowiki>

try {

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

Object result = ois.readObject();

//you can feel free to cast result to HashMap<String, Integer> if you know there's that HashMap in the file

return (HashMap<String, Integer>)result;

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

HashMap<Integer, String> loadedMap;

String path = getDataFolder() + File.separator + "example.bin";

File file = new File(path);

if (file.exists()) { // check if file exists before loading to avoid errors!

loadedMap = load(path);

}<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can use this "API" for saving/loading HashMaps, ArrayLists, and all Objects which implement Serializable or Externalizable interface.

<nowiki><blockquote><source lang="java">/** SLAPI = Saving/Loading API</nowiki>

* API for Saving and Loading Objects.

* Everyone has permission to include this code in their plugins as they wish :)

* @author Tomsik68<tomsik68@gmail.com>

*/

public class SLAPI

{

public static <T extends Object> void save(T obj,String path) throws Exception

{

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(obj);

oos.flush();

oos.close();

}

public static <T extends Object> T load(String path) throws Exception

{

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

T result = (T)ois.readObject();

ois.close();

return result;

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Example implementation of this API: <nowiki>'''</nowiki>I'm skipping some part of code in this source<nowiki>'''</nowiki>

<nowiki><blockquote><source lang="java">public class Example extends JavaPlugin {</nowiki>

private ArrayList<Object> list = new ArrayList<>();

@Override

public void onEnable() {

try {

list = SLAPI.load("example.bin");

} catch(Exception e) {

//handle the exception

e.printStackTrace();

}

}

@Override

public void onDisable() {

try {

SLAPI.save(list,"example.bin");

} catch(Exception e) {

e.printStackTrace();

}

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Note #1: This will work un-modified with almost all well-known Java types like Integer, String, HashMap. It will also work for some Bukkit types as well. If you're writing your own data object classes, and you may want to save their state using this technique, you should read about Java's Serializable or Externalizable interface. The only difference between Externalizable and Serializable is, that Serializable automatically takes all of class's fields and tries to serialize them, while Externalizable allows you to define method for reading and writing the Object. It's easy to add to your code, and it will make your data persistent with very little work required. No more parsing!

Note #2: This API doesn't support changes. Once you change something in the class, data files saved with older version of your plugin won't load correctly.

<nowiki>===== Tips & Examples =====</nowiki>

1.) Simplify your save structure

Try to use as much simple types as possible. E.g. if you want to save player, save their UUID instead. If you want to save world, save its UUID. If you want to save location, save x,y,z world UUID. DO NOT DIRECTLY SAVE BUKKIT TYPES!

2.) Save version number along with data

You should always remember, that you don't know what you'll be saving in the same file tomorrow. Will you ever migrate this file because of newer version of your plugin, bukkit, or minecraft? You don't know!

3.) Migrate older files

If your plugin finds older version of some file, it should update the file accordingly and change version number.

<references />

== 元数据 ==

Bukkit正在尝试尽可能的让制作插件变得更简单，所以带有一个键值例如Player, Entity, World，甚至是一个block的HashMaps都可以用元数据取缔掉。元数据是一些替代HashMap的方式。他可以允许你去自定义"fields"给Players, Entities, Worlds and Blocks.这些东西都是元数据类的一个成员(详见[http://jd.bukkit.org/doxygen/de/d59/interfaceorg_1_1bukkit_1_1metadata_1_1MetadataValue.html#ab49975fe013a0626dd29d3b85c63a82f])It works very simply. Everything that is Metadatable holds its own HashMap of Metadata which you have access to. That means, for example, if you're creating an economy plugin, you would need a HashMap of Player and Float or Double. 如果用了元数据，你不必去做! You just attach to player new metadata 值, and that's it! 

=== 为何要去使用元数据 ===

* Metadata is all handled by Bukkit, which makes it a very good alternative to HashMaps.
* 元数据可以用来跟其他插件分享信息与数据。

=== 为什么不去使用元数据 ===

* Slightly more difficult to get the value.
* It is not saved on shutdown (but then again, neither are any Maps that you create).

=== 获取 & 设置元数据 ===

<source lang="java">
public void setMetadata(Metadatable object, String key, Object value, Plugin plugin) {
object.setMetadata(key, new FixedMetadataValue(plugin,value));
}

public Object getMetadata(Metadatable object, String key, Plugin plugin) {
List<MetadataValue> values = object.getMetadata(key);
for (MetadataValue value : values) {
// Plugins are singleton objects, so using == is safe here
if (value.getOwningPlugin() == plugin) {
return value.value();
}
}
return null;
}</source>

Note: If you're manipulating with numbers, booleans or strings, use convenient method to get the result. For example, you can use asInt(), asString() or asBoolean() instead of value to find out the value.

== Databases ==

Sometimes flat files aren't enough for what your looking to do, this is where databases come in. The most common database engines available on Linux/Mac/Windows machines typically run on some flavor of SQL (Structured Query Language).

Software offering SQL allow you to create databases with columns and header to identify to contents of each cell. Think of it as a spreadsheet on steroids, where every column you set up in your database can enforce rules to ensure integrity. Apart from being more organised than a simple custom data file, SQL provides faster access and better searching than flat files.

The SQL standard helps applications like Bukkit implement database storage for their data in a consistent way. Unfortunately, there's more than one SQL-ready database engine, and each has minor differences in how to configure and use it. Which one you choose may depend on your particular needs. (Some plugins even offer configurable options to connect to multiple database engines!)

=== SQLite ===

Alta189 has written a [http://forums.bukkit.org/threads/lib-tut-mysql-sqlite-bukkit-drivers.33849/ fantastic SQLite tutorial] which I suggest you watch if you're interested in using SQL in your plugins, included with the tutorials is a handy library you can download and import to make using SQL easier. Once you have watched these video tutorials I would suggest you go and learn some SQL syntax, it's very straightforward and shouldn't take you long to pick up. SQL Tutorials [http://www.w3schools.com/sql/default.asp @W3Schools] and [http://www.1keydata.com/sql/sql.html @1Keydata].

SQLite is great for very simple databases, because there's no server concerns to set up. Just make a few calls to create a new database and table. It's easy to back up: just copy the whole database file in one go. SQLite is a little bit weaker at data integrity, flexibility in data types, and it may not be something you would want to trust for huge databases of millions of rows. But for a new plugin in development, it's often easiest and fastest to get the SQL basics squared away with SQLite, even if you "graduate" to a more server-class database engine later.

=== MySQL ===

Another popular SQL database engine is called MySQL. It is closer to server-grade than SQLite, where many popular companies or websites depend on it for millions of webpage hits every day. With that security comes a little bit steeper learning-curve, because MySQL has more tunable parameters and capabilities.

The coding for plugins accessing MySQL is mostly the same as tiny SQLite or mega-sized Oracle, with only small differences in syntax here or there. But the administration has room to grow. You may want to set up accounts and privileges inside your MySQL setup. You may want to set up SQL scripts that organize your backups and rollback to previous states.

== 部署你的插件 ==

总之你写好的你的插件,如何把它变成一个可安装在服务端的jar文件呢?

首先我们需要建立一个水桶服务器。 [http://wiki.bukkit.org/Setting_up_a_server 在这里] 能找到开服相关信息.接下来你需要把插件导出为一个.jar文件，

这样你就能在你的服务器里运行它。在Eclipse里, 右键工程，点击''Run as > Maven install''即可:

[[Image:Maveninstall.png]]

将来呢, 当你对插件进行了改动后,在做上述操作之前，如果你想删除之前的.jar文件，你可以右键工程，点击 ''Run as > Maven clean'' 。

如果你在编译插件时遇到了问题, 请检查你的JDK是否正确安装，并浏览[[建立工作区]]条目。

如果你在Eclipse控制台看到了和JDK有关的错误，你可能需要手动调整JDK,因为Eclipse的检测可能发生了错误。

点击''Window -> Preferences'', 然后是''Java -> Installed JREs''。选中你最近安装的JDK作为Java运行环境（JRE）并添加, 并取消掉原来那个报错的JDK:

[[Image:Jrelocation.png]]

如果你的工程成功被编译,JAR文件会生产在 ''target'' 目录下，具体在Eclipse的工作空间里名字为工程名的文件夹中。

这个JAR文件就是一个能正常工作的Bukkit插件了。当然前提是你的plugin.yml里没出差错。

你可以把这个jar文件丢到服务器的plugins文件夹里,重载或重启服务器,就可以测试你的新插件啦。

为了连接上使用你自己的电脑开的服务器 ,在多人游戏的ip里填上你的本地ip即可。

如果出现了错误而你又不能解决的话, 试试这里[http://forums.bukkit.org/forums/plugin-development.5/ plugin development forum],

在这里提问[http://wiki.bukkit.org/IRC bukkitdev IRC channel],或者重新阅读wiki。

当你做完了一个实用的插件,可以考虑把它发表在这里[http://dev.bukkit.org/ dev.bukkit]（为了Bukkit社区的访问量）。

以上可知,JAR格式是默认压缩生成的(JAR文件基于ZIP文件的格式)。这么说来，在上传插件到Bukkit上时把JAR文件压缩成ZIP只会增加文件体积罢了。

而且呢, 放在JAR中的config文件可以在检测不到插件目录（插件自动生成的文件夹，名字与插件名相同，里面是该插件的配置）下的config文件时自动生成。

所以我们一般不把jar文件转换成其他格式。

== 导入其它插件 ==
你可能会希望编辑其它那些有源代码的插件. 如果插件在它的目录下有''pom.xml''(大多数知名插件,例如WorldEdit和Essentials都有),你可以通过点击''File -> Import''来把它作为一个工程导入, 然后打开''Maven''项并选择''Existing Maven Projects'':

[[Image:Importmaven.png]]

然后选择''pom.xml''所在的目录,这个工程就应该出现在你的侧边栏里了。就像平常一样编辑并编译它吧。

== 小贴士 ==

=== 使玩家着火 ===

Bukkit API有很多碉堡的功能。以下是实现一些功能的代码片段。

下面的代码运行一个玩家使另一个玩家着火。通过类似于'''/ignite Notch'''这样的指令，这个指令会让 Notch 着火。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 使用 equalsIgnoreCase() 来忽视大小写
if (cmd.getName().equalsIgnoreCase("ignite")) {
// 确保玩家只输入了一个自变量(要被点着的玩家名).
if (args.length != 1) {
// 当return false时，该指令的使用信息会显示出来。
return false;
}

// 确保命令发出者是个玩家.
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can set other players on fire.");
sender.sendMessage("This is an arbitrary requirement for demonstration purposes only.");
return true;
}

// 获取那个要被点着的玩家. 请注意下标起始是0，不是1.
Player target = Bukkit.getServer().getPlayer(args[0]);

// 确保这个玩家在线。
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}

// 让这个玩家着火1000 ticks (一秒钟大概有20ticks,所以总共是50秒).
target.setFireTicks(1000);
return true;
}
return false;
}

=== 干掉玩家 ===

和标题一样.这里是要干掉某个玩家。

在你的onCommand方法里使用这个:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("KillPlayer")) {
Player target = sender.getServer().getPlayer(args[0]);
// 确保玩家在线.
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}
target.setHealth(0);
}
return false;
}

这里有个小扩展,会使用一个爆炸来杀死玩家:

float explosionPower = 4F; //爆炸等级 - TNT的爆炸等级默认是4F
Player target = sender.getWorld().getPlayer(args[0]);
target.getWorld().createExplosion(target.getLocation(), explosionPower);
target.setHealth(0);

=== 创造一个假爆炸 ===

这段代码会生产一个看起来和听起来与TNT/苦力怕产生的爆炸一样的效果。但是不会对实体和方块产生破坏。在保留爆炸的艺术的同时又削弱了爆炸的威力，真是太有用了（
@EventHandler
public void onExplosionPrime(ExplosionPrimeEvent event) {
Entity entity = event.getEntity();

// 如果事件和点燃的TNT有关,执行一些代码（又略）
if (entity instanceof TNTPrimed) {
entity.getWorld().createExplosion(entity.getLocation(), 0);
}
}

=== 使一个玩家对另外一个玩家隐形 ===

通过输入指令，能让指令执行者对特定的玩家隐形。然而其他人仍然能看到指令执行者。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("HideMe") && args.length == 1) {
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can use this command!");
return true;
}
// 检测指令执行者是玩家后，我们便可以安全的进行强制转换类操作。
Player s = (Player) sender;

// 获取命令执行者指定的玩家
Player target = Bukkit.getServer().getPlayer(args[0]);
if (target == null) {
sender.sendMessage("Player " + args[0] + " is not online.");
return true;
}
// 将 s 从 target 的视野中隐藏起来.
target.hidePlayer(s);
return true;
}
return false;
}

=== 在玩家准星所指处生产闪电 ===

如下代码运行手持鱼竿的玩家通过点击来生成闪电 (当然要用准星瞄准)。真是个简单好玩的恶作剧（。

@EventHandler
public void onPlayerInteractBlock(PlayerInteractEvent event) {
Player player = event.getPlayer();
if (player.getItemInHand().getType() == Material.FISHING_ROD) {
// 在给定坐标中生成一道闪电. 在本例中, 这个坐标是玩家准星瞄准的地方.
// 只能指向200格以内的坐标.
player.getWorld().strikeLightning(player.getTargetBlock(null, 200).getLocation());
}
}

=== 自动格式 ===

Eclipse提供了将你的代码自动转成Oracle规定的格式, 修正了不符合常规的缩进, 空格等等。在侧边栏选中你的项目,然后选择''Source -> Format''即可对其进行更改。

== 插件需求专区 ==

http://forums.bukkit.org/forums/plugin-requests.13/

== 范例文件和样板 ==

*[https://github.com/Bukkit/SamplePlugin/ Bukkit/SamplePlugin on GitHub]

*[http://pastebin.com/wpeTPx7N Example.Java]

*[http://pastebin.com/MTwaAVCT ExamplePlayerListener.Java]

*[http://pastebin.com/6FLixfH3 ExampleBlockListener.Java]

*[http://pastebin.com/8UZ6pkWC ExampleEntityListener.Java]

If you have any more questions on this matter, don't hesitate to visit the BukkitDev [[IRC]] channel and ask!

[[Category:教程]]
[[Category:大篇幅条目]]

Configuration API Reference

2015-09-01T12:15:12Z

Tdiant：小小的翻译了一下

{{待翻译}}

Configuration API是一个帮助程序员们更快地解析与编辑配置文件的设置工具，让人们觉得配置文件更简单更容易编辑。不管是什么，这个API可以帮助你更容易的存储你插件的信息。目前只有这个 [http://en.wikipedia.org/wiki/YAML YAML] configurations 可以用。然而，有了这个API，设计的能有更多的扩展空间，还能允许你实现其他的东西。

Configuration API可以在 org.bukkit.configuration 和 org.bukkit.configuration.file 这俩包里找到。插件的版本如果创建在 1.1-R5之前，就只能用老的并且与此不同的方法了，这些东西在org.bukkit.util.configuration这个包里。这些实现方法彼此不兼容并且老的方法因为太OUT了，在新版中被删去了。

This introduction assumes that you have some knowledge about proper object oriented design, Java, and the core design of Bukkit plugins. This page is not a substitute for the JavaDocs for the [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfiguration.html FileConfiguration Class]

== Basic Topics ==

=== The Configuration Object ===

Your plugin extends [http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html JavaPlugin], and in doing so, you inherited methods and fields from JavaPlugin. The inherited method, ''[http://jd.bukkit.org/doxygen/d7/deb/classorg_1_1bukkit_1_1plugin_1_1java_1_1JavaPlugin.html#a79493f3bc9db2acbf9405c3a33e0acfd getConfig()]'' returns an object of type [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html FileConfiguration]. This is the object that represents ''config.yml'' inside your plugin's data folder.

The first time ''getConfig()'' is invoked on your plugin, ''config.yml'' is loaded from disk, and default values are loaded from the jar. Subsequent invocations of ''getConfig()'' will return the existing ''FileConfiguration'' object that is in memory. Operations performed on this object will not be written to disk unless explicitly saved. Likewise, any modifications done after the file has been loaded will not be reflected in the object. If ''config.yml'' does not exist in your data folder, it is equivalent to an empty ''config.yml'', and will load an empty ''FileConfiguration''.

{{warning}} if you assign the returned object from ''getConfig()'' DO NOT assign it to a static field {{warning}} if you do the above, assign ''getConfig()'' to the variable AGAIN after a reloadConfig
{{note|it is better to just use ''getConfig()'' instead of assigning it to an instance variable}}

=== Keys ===

A configuration file is organized into key value pairs where all keys are Strings. The value for the other keys may be a ConfigurationSection or a single piece of data. The ''getKeys(boolean)'' method returns the set of keys for the current ''FileConfigurationSection''. The boolean value determines if the returned set is recursive, if true it will return the keys of the given section and their children keys, if false will only return keys of the given section. To get the keys of a particular section, the ''getKeys(boolean)'' method must be invoked on that particular section. To get the section you will have to invoke ''getConfigurationSection(String)''.

{{note|The getKeys method returns a [http://download.oracle.com/javase/1,5.0/docs/api/java/util/Set.html Set] of Strings}}

=== Paths ===

The Configuration API uses Paths to form a unique key to value pairs. A path is the set of keys used to associate a value. Each level is separated by the path separator, which is by default the '.' (period). For example the following YAML file has the following set of paths.
<blockquote><source lang="yaml">key: value
one:
two: value
three:
- values
- values
- values
four:
five: value
*:
six: value
seven: value
</source></blockquote>

*key
*one
*one.two
*one.three
*one.four
*one.four.five
*one.*
*one.*.six
*one.*.seven

=== Default Values ===

A default ''config.yml'' should be provided in your jar for users. In the event that a config.yml is missing or incomplete, values will be loaded from included ''config.yml''. The provided file must be named ''config.yml'' and be placed in the same directory as your [[Plugin YAML|plugin.yml]]. The file should have the intended structure of your ''config.yml''. This file can be copied as is into the datafolder by invoking saveDefaultConfig() on the Appropriate instance of JavaPlugin.
<blockquote><source lang="java">this.saveDefaultConfig()</source></blockquote>

If dynamic key-value pairs are required as default values, they can added as defaults to the configuration with invocations of ''addDefault(String, Object)'' and ''addDefaults(Map<String,Object>)'' methods.

In certain cases if you wish to append new key-value pairs to an existing config.yml you can set the copyDefaults to true for the ConfigurationOptions object.
<blockquote><source lang="java">this.getConfig().options().copyDefaults(true)</source></blockquote>

==== Creating a copy of config.yml ====
You can create a copy of config.yml from the jar into the plugin's data folder by invoking JavaPlugin's saveDefaultConfig() method. saveDefaultConfig() will not overwrite an existing file.

=== Getting Values ===

Reading values from the configuration involves invoking one of the many getter methods. A complete list of getters can be found [http://jd.bukkit.org/doxygen/dd/d7c/classorg_1_1bukkit_1_1configuration_1_1file_1_1FileConfiguration.html here]. Every getter method takes a configuration path detailed above. Some of the commonly used getter methods are as follows

*getBoolean(String)
*getInt(String)
*getString(String)
*getList(String)
*getStringList(String)

==== HashMaps ====

In the case of HashMaps as a value, they are treated differently than other forms of data. There is a restriction for Map types. It must use a String as a key, and the value but be either a boxed primitive, String, List, Map, or a ConfigurationSerializable type. They will lose their type.

To get a ''HashMap'', a ''ConfigurationSection'' must must first be retrieved. You can return the configuration with getConfigurationSection method. The getValues method will return the values in the ConfigurationSection as a map, it takes a boolean which controls if the nested maps will be returned in the map. You can obtain the original map by invoking getValues(false) on the returned ConfigurationSection. Due to the way Java handles generic classes, type information will be lost, thus a cast will need to be performed to set the original type information. The API makes no guarantees that the cast you perform will be safe.
<blockquote><source lang="java">this.getConfig().getConfigurationSection("path.to.map").getValues(false)</source></blockquote>

=== Setting Values ===

Writing values involves invoking the ''set(String, Object)'' method on an instance of Configuration. Unlike the different get methods that ''FileConfiguration'' has, there is only one set method. Not all objects can be set, only primitive types, ''String'', ''Lists'', and types that implement ''ConfigurationSerializable'', such as ''Vector'' and ''ItemStack'', can be set. To erase a value supply null as a parameter. All changes made by set will only affect the copy of the configuration in memory, and will not persist beyond restarting the server until the configuration is saved. Following are some example uses:
<blockquote><source lang="java">// setting a boolean value
this.getConfig().set("path.to.boolean", true);

// setting a String
String stringValue = "Hello World!";
this.getConfig().set("path.to.string", stringValue);

// setting an int value
int integerValue = 8;
this.getConfig().set("path.to.integer", integerValue);

// Setting a List of Strings
// The List of Strings is first defined in this array
List<String> listOfStrings = Arrays.asList("Hello World", "Welcome to Bukkit", "Have a Good Day!");
this.getConfig().set("path.to.list", listOfStrings);

// Setting a vector
// event is assumed to be an existing event inside an "onEvent" method.
Vector vector = event.getPlayer().getLocation().toVector();
this.getConfig().set("path.to.vector", vector);

// Erasing a value
this.getConfig().set("path.to.value", null);</source></blockquote>
 

==== HashMaps ====

When HashMaps are used as a value, they are treated slightly differently. The Map must parameterized with a String type for the key, and the value must be parameterized as a boxed primitive, String, List, Map, or a ConfigurationSerializable.

While you can use the set method to directly set a HashMap to a key, you cannot directly retrieve the Map back with the get method after reading directly from disk. The [[#HashMaps|context above]] is to minimize unpredictability.

To set a ''HashMap'', a ''ConfigurationSection'' must be created for that HashMap. You can only set HashMap where the key is a string the the value is something that is ConfigurationSerializable. The createSectionMethod
<blockquote><source lang="java">this.getConfig().createSection(String path, Map< String, Object > map)</source></blockquote>

=== Saving the File ===

If make any changes to the''FileConfiguration'' with set methods, or mutate any ''Lists'', you will need to save the changes to disk if you wish to keep these changes after the plugin is disabled. To save the file to disk invoke the saveConfig method for your plugin, it will overwrite the file already there. <blockquote><source lang="java">this.saveConfig();</source></blockquote>

=== Reloading from Disk ===

If you suspect that users have made changes to the ''config.yml'' in the data folder, those changes are not reflected in memory. Invoke the ''reloadConfig()'' method of your plugin to load from the disk again. It will destroy all changes in memory. <blockquote><source lang="java">this.reloadConfig();</source></blockquote>

== Advanced Topics ==

The following are some more advanced topics, meant for more advanced plugins. If you only require the default ''config.yml'', creating custom methods for reading, and saving, you will not need to go this far.

=== Options ===

Every ''FileConfiguration'' instance is associated with a [http://jd.bukkit.org/apidocs/index.html?org/bukkit/configuration/file/FileConfigurationOptions.html FileConfigurationOptions] object. The ''FileConfigurationOptions'' object controls the behavior of the ''FileConfiguration'' it is associated with. ''FileConfiguration'''s ''options()'' method returns the ''FileConfigurationOption's'' responsible for it. With it you can check and set each option. There are currently four options. Be aware that the methods are overloaded, for example ''copyDefaults()'' which returns a boolean and ''copyDefaults(boolean)'' which returns it self, but has a side effect which changes the state.

==== CopyDefaults ====

The ''copyDefaults'' option changes the behavior of Configuration's save method. By default, the defaults of the configuration will not be written to the target save file. If set to true, it will write out the default values, to the target file. However, once written, you will not be able to tell the difference between a default and a value from the configuration.

==== PathSeperator ====

PathSeperator changes the character that is used to separate the different levels of the configuration. By default it is the "." (period) but it can be changed to any char.

==== Header ====

Header is the comment block at the top of a YAML file, it is applied to the save output. The header is the only comment that Configuration API knows how to copy.

==== copyHeader ====

If ''copyHeader()'' returns true then the header will be copied on save, from the default source.

=== Arbitrary Configurations ===

If you require additional YAML files, for storing configuration information or persisting additional game information you will need to write your own methods for accessing the additional configuration files. Modeled after JavaPlugin getConfig, reloadConfig, saveConfig methods, the following is an example how to write your own methods to read and save to custom configuration files. Since these config files belong to your plugin, you can put this method in your main class so that you can have the same access as you have with config.yml. You will have to write a set of these methods for each YAML file. The advantage here, is that you can use each set in the same manner as the provided methods for the default config.yml. Alternately, adding additional methods can keep the method count lower and allow access to multiple files.

==== Mirroring the JavaPlugin implementation ====
JavaPlugin implements methods for config.yml. A plugin needs to implement its own methods to access configuration files unique to the plugin. After implementing the methods for the plugin, they can be invoked in the same context as the inherited ''getConfig()'', ''reloadConfig()'', ''saveConfig()'', and ''saveDefaultConfig()'' methods from JavaPlugin. The following can be made into a single class which allows access to any yaml file. Such a class can be found [https://gist.github.com/3174347 here]

First you will need to declare two fields and initialize them to null for each of the custom configuration files. One to hold the ''FileConfiguration'' object and one to hold the ''File'' object. The File object represents the file on the disk, and the FileConfiguration represents the contents of the configuration.
<blockquote><source lang="java">private FileConfiguration customConfig = null;
private File customConfigFile = null;</source></blockquote>

===== Implementation for Reloading =====
Then, write the method that is responsible for loading the config from disk. It will load the file, and search the jar for a default customConfig.yml. <blockquote><source lang="java">
public void reloadCustomConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
customConfig = YamlConfiguration.loadConfiguration(customConfigFile);

// Look for defaults in the jar
Reader defConfigStream = new InputStreamReader(this.getResource("customConfig.yml"), "UTF8");
if (defConfigStream != null) {
YamlConfiguration defConfig = YamlConfiguration.loadConfiguration(defConfigStream);
customConfig.setDefaults(defConfig);
}
}</source></blockquote>

===== Implementation for Getting =====
Next, you need to write the getter method. Check if ''customConfig'' is null, if it is load from disk. <blockquote><source lang="java">
public FileConfiguration getCustomConfig() {
if (customConfig == null) {
reloadCustomConfig();
}
return customConfig;
}</source></blockquote>

===== Implementation for Saving =====
Finally, write the save method, which saves changes and overwrites the file on disk. <blockquote><source lang="java">public void saveCustomConfig() {
if (customConfig == null || customConfigFile == null) {
return;
}
try {
getCustomConfig().save(customConfigFile);
} catch (IOException ex) {
getLogger().log(Level.SEVERE, "Could not save config to " + customConfigFile, ex);
}
}</source></blockquote>

===== Implementation for Defaults =====
Optionally, you may want to write a method that mimics JavaPlugin's saveDefaultConfig() method. <blockquote><source lang="java">public void saveDefaultConfig() {
if (customConfigFile == null) {
customConfigFile = new File(getDataFolder(), "customConfig.yml");
}
if (!customConfigFile.exists()) {
plugin.saveResource("customConfig.yml", false);
}
}</source></blockquote>

=== Serializing and Deserializing Objects ===

The Configuration API, as mentioned above can store Java objects that implement the ''ConfigurationSerializable'' Interface. Object serialization facilitates easy saving and loading so plugin authors can focus on other parts of their plugin. It greatly simplifies tasks such as storing a ''[http://jd.bukkit.org/doxygen/da/dac/classorg_1_1bukkit_1_1Location.html Location]'' in YAML, a developer can serialize a wrapper class, which provide methods to retrieve a ''Location''. 

Classes, in addition to implementing the ''ConfigurationSerializable'' interface must also implment one of the following as noted in the Javadoc, so that they can be serialized by the API:

*A constructor that accepts a single ''Map''.
*A static method "deserialize" that accepts a single ''Map'' and returns the class.
*A static method "valueOf" that accepts a single Map and returns the class.

In order for a serialized object to be deserialized, it must also be registered with ConfigurationSerialization. The static registerClass method must be invoked once per class that has been serialized.

This statement must be placed in your onEnable method or some other location that gets called every time your plugin is initialized:
<blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>)</source></blockquote>
{{warning}}Do not use a static block to execute the above; if you do so, it will not be called a second time when <code>/reload</code> is used and you will encounter errors due to it not being registered!

==== Aliases ====

When classes are serialized they are marked with their fully qualified name.
You can provide an alias to your class so that it does not serialize with the fully qualified name of your class, but the alias instead. You provide the alias with the ''SerializableAs'' annotation to the class implementing ''ConfigurationSerializable''. <source lang="java">@SerializableAs(String)</source> When registering a class with an alias, the alias must be provided on registration. <blockquote><source lang="java">ConfigurationSerialization.registerClass(Class<? extends ConfigurationSerializable>, String)</source></blockquote>

== Example Use ==

Below is the an example plugin that uses the new Configuration API to be display messages as an MOTD as players join, and for the player to retrieve the rules on command. It does not follow proper style and plugin layout to keep the number of lines to a minimum.

<blockquote><source lang="java">import java.util.*;
import org.bukkit.command.*;
import org.bukkit.event.*;
import org.bukkit.plugin.java.JavaPlugin;
import org.bukkit.configuration.file.FileConfiguration;

public class SimpleMOTD extends JavaPlugin {

@Override
public void onEnable() {
// Save a copy of the default config.yml if one is not there
this.saveDefaultConfig();

// Register a new listener
getServer().getPluginManager().registerEvents(new Listener() {

@EventHandler
public void playerJoin(PlayerJoinEvent event) {
// On player join send them the message from config.yml
event.getPlayer().sendMessage(this.getConfig().getString("message"));
}
}, this);

// Set the command executor for the rules command
this.getCommand("rules").setExecutor(new CommandExecutor() {

public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
// On command send the rules from config.yml to the sender of the command
List<String> rules = this.getConfig().getStringList("rules");
for (String s : rules)
sender.sendMessage(s);
}
return true;
}
});
}
}</source></blockquote> The default config.yml that is in the plugin's jar
<source lang="yaml"># default config.yml
message: Hello World and Welcome! :)
rules:
- Play Nice
- Respect others
- Have Fun</source>

Bukkit/插件开发教程

2015-08-31T07:58:58Z

Tdiant：/* Metadata */

{{模板:待翻译}}
{{模板:待完善}}
本页面英文原文内容来源 [http://wiki.bukkit.org/Plugin_Tutorial]
== 介绍 ==

这篇内容丰富的教程旨在帮助你学会如何开发Bukkit插件.这一篇教程不可能完全涉及到Bukkit中所有的可能性,而是最基本的一般概述. 前提是你懂得Java这门语言,并在IDE中设置好你的工作区,此教程介绍了大多数Bukkit插件所必需的语法结构.

== 学习Java ==

'''理解这些教程需要具备Java这门编程语言的基本知识.'''如果你刚开始学习Java或者需要重温一下相关知识，下面有一个并不完整的网站列表可供参考.

<big>[http://docs.oracle.com/javase/tutorial/ Oracle's Java Tutorials]</big> - 官方教程
*[http://www.java2s.com/Tutorial/Java/CatalogJava.htm Java2s.com] - 教程
*[http://www.javacoffeebreak.com/java101/java101.html Java 101] - 教程
*[http://math.hws.edu/javanotes/ JavaNotes] - 免费的在线教科书
*[http://thenewboston.org/list.php?cat=31 TheNewBoston] - 视频教程.

== 开发环境 ==

在编写一个插件前 (或学习Java前) 你需要配置一个开发者环境，这个包括但不限于安装IDE (Integrated Development Environment，集成开发环境)。接下来的教程中有关于Eclipse上IDE的操作指南。

:: ''更多信息，请参见 [[Bukkit/插件开发教程-建立工作区|建立工作区]]''

你'''必须'''下载'''Java'''开发者使用的Eclipse构建版本, '''不是''' '''Java EE'''开发者的版本。 Java EE 开发者的版本不包含此教程需要的Maven支持。

== 新建插件开发项目 ==
=== 创建一个新的项目 ===

在开始工作之前，你需要先在Eclipse中配置好工作区和文件. 打开Eclipse,然后依次点击''File -> New -> Project:''来创建一个新的项目.

[[Image:Newproject.png]]

现在,打开''Maven''文件夹, 然后选择''Maven Project''.点击next,之后在下一个菜单中选择''Create a simple project'', 再次点击''Next'':
如果你看不到''Maven''文件夹, 那么你需要[http://eclipse.org/m2e/download/ 下载m2eclipse]

[[Image:Newproject2.png]]

现在，你需要给你的组用户命名，就像下面这样:
* 如果你拥有一个域名，package则填写逆转的域名地址.
** 例如: i-am-a-bukkit-developer.com 你的package地址即是com.i_am_a_bukkit_developer [http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html source]
** 避免使用一个不属于你自己的域名.
* 没有域名? 这里有几种方法可供选择。
*# 在资源管理站点创建一个用户，比如GitHub或是sourceforge
*#* 对于使用GitHub的用户, 请参照[http://pages.github.com/ 这里的说明] 之后你将获得一个子域名,所以你的package地址是io.github.<username> 
*# 使用你的邮箱. 例如: <username>@gmail.com格式的邮箱应输入com.gmail.<username> 
*# 最不济的方法.：使用独特的组名命名方式，这应当是你最后的解决方法。

以下几个地址不能作为package中的地址前缀:
* org.bukkit
* net.bukkit
* com.bukkit
* net.minecraft

完成基础的组名以后，你需要在最后加上插件的名称. 在这里用 GitHub页面作为讲解的实例. 如果你创建了一个名为 ''TestPlugin''的插件，那么完整的组名是''io.github.<username>'', 你的工程名也是 ''TestPlugin''. 至于版本，默认即可，稍后可以修改。
完成向导:

[[Image:Newproject3.png]]

如果这是你首次使用Eclipse, 点击右上角的"X" 来关闭Welcome提示页面. 现在，你的窗口视图看起来就像下面的图片这样:

[[Image:Eclipsemain.png]]

点击工程名称右边的箭头来进行下一步，现在我们正式开始。
=== 添加Bukkit API ===

在开发插件之前，你需要添加 Bukkit API库文件到你的项目，作为一个dependency, 你也可以添加其他你想实用的API.

找到项目文件夹中部的''pom.xml''并双击进行编辑. 点击''pom.xml''中部的 tab,你将会看到下图所示内容:

[[Image:Pomeditor.png]]

如果你想使用Java 6以上版本的语言特性,你需要指定搭建项目的Java版本.复制并粘贴以下内容(设定项目只能使用Java 7及以下的版本)到 ''</project>''之前:

<code>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<nowiki><</nowiki>source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
</plugins>
</build>
</code>

你或许想使用其他版本,例如 <code>1.8</code> 使用Java 8. 请注意 [http://mcstats.org/global/ 根据MCStats数据统计], 大多数服主选择了Java 7, 所以使用Java 8会使许多服务器无法运行你的插件. 如果你使用Java 1.7的特性, Eclipse将会在报错代码"error"中建议你更改语言版本.同意即可.

在位于代码中段的''</project>''之前粘贴以下内容(这段代码告诉Eclipse关于Bukkit's repository的地址):

<code>
<repositories>
<repository>
<id>bukkit-repo</id>
<url>http://repo.bukkit.org/content/groups/public/</url>
</repository>
</repositories>
</code>

然后继续在 ''</project>''前粘贴以下内容 (这段代码告诉Eclipse搭建插件的Bukkit版本):

<code>
<dependencies>
<dependency>
<groupId>org.bukkit</groupId>
<artifactId>bukkit</artifactId>
<version>1.7.2-R0.3</version>
<type>jar</type>
<scope>provided</scope>
</dependency>
</dependencies>
</code>

你也可以修改这里的Bukkit版本.你可以在[http://repo.bukkit.org/content/groups/public/org/bukkit/bukkit/ here]这里通过查看 maven-metadata.xml文件下的版本列表来获取可用的服务端版本号.

当你完成上述步骤后,''pom.xml''中的内容应该是这样:

[[Image:Finishedpom.png]]

通过菜单 ''File -> Save''或者按住 <code>Ctrl + S</code> 来保存''pom.xml''文件 . 之后, 右键项目标题，然后依次选择 ''Maven -> Update Project''.

=== Bukkit Java文档 ===

如果你曾经使用过Eclipse和Java，你会知道当你将鼠标准心移至class或者 method中的代码部分时，一个含有相关文档内容的黄色小框会弹出来. 这就是（Java的）Java文档。

你可以[http://download.oracle.com/javase/6/docs/api/ Oracle website 在线获取]它.。Bukkit同样拥有文档，这些文档内容包含了关于API中method和class的有用描述。

你可以在[http://jd.bukkit.org/ 这]找到它 (Beta版的Java文档在[http://jd.bukkit.org/ 这]找, 新开发出来的Java文档在

[http://jd.bukkit.org/ 这]) 。为了在Eclipse里使用Java文档,这样的话当你的鼠标停留在Bukkit的class和method上时，

（Bukkit的）Java文档就会冒出来。
JavaDoc in spigot [https://hub.spigotmc.org/javadocs/bukkit/ Click Here]

首先右键在侧边栏里的"Maven Dependencies"下面的Bukkit jar,选择"Properties".选中窗口左边的''Javadoc Location'', 并粘贴如下网址

'''http://jd.bukkit.org/''' (或者上面的测试版/最新版 Java文档链接也好) 到"Javadoc URL"下面的输入框内. 就像这样:

[[Image:Bukkitjavadocs.png]]

点击 "Validate",然后再点击"OK"就完成了.现在Bukkit Javadocs已经连接到Bukkit提供的资源,同时你也可以通过Eclipse来获得帮助类文档信息了.

=== 创建一个包 ===

现在你需要创建一个包，它将储存所有我们需要使用的Java类文件. 右键展开''src/main/java''折叠并选择 ''New > Package'':

[[Image:Newpackage.png]]

包名的话，先写上你的组名，然后加个点，再写上你的小写Artifact ID。举例, 如果你的组名是''io.github.name''，你的artifact名是 ''TestPlugin''。

你的包名就应该是''io.github.name.testplugin''.

=== 创建插件的类文件 ===

既然我们已经建立好了我们的项目，我们接下来可以开始添加类文件以及制作插件了. 插件的主类指的是拓展(extends)JavaPlugin的类文件. 在你的插件中只能有一个类文件拓展JavaPlugin，无论直接还是间接. 先创建你的主类文件并保持名称与插件名一致是个很好的习惯.右键你之前新建的包,并选择  ''New > Class''.你将会创建一个新的类文件，就像下面这样

package {$GroupName}.{$ArtifactName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$ArtifactName} extends JavaPlugin {

}

警告：插件绝对不应该调用自己的构造函数并实例化

=== 创建plugin.yml ===

你已经创建了项目和主类，如果你想要Bukkit能够加载你的插件，你还必须创建 '''[[Plugin YAML|plugin.yml]]''' 文件. 这个文件包含有基础的插件信息，如果缺失这个文件，你的插件也将会失效. 此时你需要右键''src/main/resources''. 选择''New > File''. 命名为"'''plugin.yml'''" 并右键完成新文件的创建.Eclipse会打开默认的文本编辑窗口来显示'''plugin.yml'''文件中空白的内容并提供编辑. ''(Hint: 如果你想要使得你的工作空间更加规整，关闭文本编辑器并将'''plugin.yml''' 文件拖到主工作空间(拖到文件目录的右边) 之后你就可以在eclipse中编辑文件了.)''

有三个基础的内容需要在plugin.yml写明.
: name: 插件名称.
: main: [http://docs.oracle.com/javase/specs/jls/se7/html/jls-6.html#jls-6.7 插件主类的完整，合法名称] .
: version: 插件当前版本号.

最简单的 '''plugin.yml''' 文件内就像这样 :

name: {插件名称}
main: {包名}.{主类}
version: {版本号}

PS:插件的包名经常会包括插件的名称，所以看到这个的时候不要感到惊讶。
你的主类是否是你的插件名取决于你之前的命名方式，时刻记住这一点很重要。

'''''更多例子''', 请看[[#Example_Files_and_Templates]]''

此时你的插件已经可以被Bukkit加载了,同时服务端日志也会开始记录你的插件. 不过它现在什么用都没有!

== onEnable()和onDisable()方法 ==

这些方法将在插件启用与卸载时生效. 默认情况下，你的插件在被加载时会调用这些方法，所以你可以在这里注册你需要用到的事件和提供一些调试信息. <code>onEnable()</code> 方法会在插件启用时被调用, 需要包含初始化插件的逻辑语句. <code>onDisable()</code> 方法会在插件卸载时被调用，需要包含清理(clean up)插件的逻辑语句和连接声明(associated state)。此外，插件可以重写 <code>onLoad()</code> 方法来在插件载入时执行附加的逻辑语句。

=== onEnable()和onDisable()方法介绍 ===

在前面的章节中，我们在主类创建了<code>onEnable()</code> 和 <code>onDisable()</code> 方法. 此时，这些代码看起来就像下面这样

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
// 插件载入时要执行的代码（略）
}

@Override
public void onDisable() {
// 插件卸载时要执行的代码（略）
}
}

这些方法已经创建，但目前它们还没有任何作用.
注意: 不需要添加代码来实现输出信息"{$PluginName} has been enabled!" ，因为bukkit会自动输出此类信息
有关更多事件的信息请查看 [[Event_API_Reference|这里]].

=== 发送提示信息 ===

插件能够输出信息至控制台与服务器日志。这是通过调用插件记录器里正确的方法来实现的。首先我们必须调用 <code>getLogger()</code> 方法来检索该插件的记录器，

然后我们就可以开始记录信息了。

我们通过调用<code>onEnable()</code>方法可以实现输出信息。我们需要在<code>onEnable()</code>方法下面插入如下代码：

getLogger().info("onEnable has been invoked!");

在 <code>'''onDisable()'''</code>方法里面，你也可以做类似的事情，不过要改改输出信息。

此时你的主类文件就像这样:

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
getLogger().info("onEnable has been invoked!");
}

@Override
public void onDisable() {
getLogger().info("onDisable has been invoked!");
}
}

=== 防止重载后插件失效 ===

你需要知道的是，插件并不只会伴随服务器关闭、启动而重载，你的插件也可能会被其他插件启用、关闭，或是在服务器运行时使用/reload命令.
假设服务器启动之后一会儿后，你的插件才被启用，这时便是危险的,因为服务器中可能已经有玩家在线、额外的世界被加载以及很多预想不到的不同之处(与"插件同服务器同时加载"的情况相比较).

举个例子来说:
* 你有一个用来储存HashMap中的玩家登入信息的插件
* 你希望该信息对所有玩家都可见
* 一名管理员使用/reload命令
* 你的插件被卸载，所有储存的数据都丢失了
* 你的插件被再次启用时，一些玩家已经在线
* 这些玩家在HashMap并没有储存的信息
* 你试图重新获得他们的信息，但是失败了!

为了插件重载以后能够正常工作, 你需要在插件启用时加载所有已经在线的玩家的信息并将之储存在HashMap中.

for (Player player : Bukkit.getServer().getOnlinePlayers()) {
playerList.put(player.getName(), playerData(player));
}

== 监听器 ==
监听器是一种方法被调用来对事件作出反应的类.所有的监听器使用 org.bukkit.event.Listener接口.更多有关监听器创建的细节,
:: '' 请查看: [[Event API Reference]]''

== 指令 ==

=== onCommand() 方法 ===

现在你已经知道如何注册一个事件并做出响应,但是如果你只是想要在命令输入之后做出响应呢? 你可以使用 <code>'''onCommand'''</code>方法.

这个代码的作用是当玩家输入“/”时，监听该操作并执行相关语句"/" . 举个例子来说.输入 "/do something" 将会执行 <code>'''onCommand'''</code>方法.

此种情况下，因为没有特定的行为被编程，所以并不会发生任何事情。

请避免使用和bukkit所提供的指令重名的指令, 然后深思你的指令名的唯一性。

例如.指令"give"已经被好几个插件使用了, 如果你执行了另外一个"give"指令, 你的插件将会和这些插件冲突。

你必须在插件的"plugins.yml"注册你的指令否则这个方法将不会被触发。

<code>'''onCommand'''</code>方法必须返回一个布尔值（true或false）。

如果返回值是true，你不会看到什么明显的事情发生。

但如果返回值是false，则会返回你的plugin.yml里的'usage:property'然后发送给命令使用者.

当使用 <code>'''onCommand'''</code>方法时, 你需要填写4个参数.

*<code>'''CommandSender sender'''</code> - 发送命令的对象

*<code>'''Command cmd'''</code> - 被执行的指令

*<code>'''String commandLabel'''</code> - 被执行指令的别名

*<code>'''String[] args'''</code> - 该指令的自变量数组。

例如.指令 ''/hello abc def'' 中， ''abc'' 会被存放进args[0]中, ''def'' 被存放进args[1]中。

==== 设置命令 ====
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { // 如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} //如果以上内容成功执行，则返回true
// 如果执行失败，则返回false.
return false;
}

每当使用<code>'''onCommand'''</code>方法时，在每个方法后面都加上一个 return false; 是一个惯例。

返回false会显示在plugin.yml里设置的usage信息 (看下面). 用这种方法的话，一旦执行出错便会显示usage信息。

每当方法return一个值的时候，这个方法就会退出，所以return true的时候，在它下面的代码就会被跳过,

除非return语句在一个if的嵌套中，或者类似的嵌套情况。

<code>'''.equalsIgnoreCase("basic")'''</code>代表忽略英文大小写. 在这种情况下,字符串"BAsIc" 和 "BasiC"和 basic相同，代码会被照常执行。

和以前一样，加两行import在你的java文件头

import org.bukkit.command.Command;

import org.bukkit.command.CommandSender;

=== 在Plugin.yml中添加你的指令 ===

你需要添加你的指令到 '''plugin.yml''' 文件里. 如下是指令/basic添加到 '''plugin.yml'''的例子（请在plugins.yml的末尾添加如下代码）:

commands:
basic:
description: This is a demo command.
usage: /<command> [player]
permission: <plugin name>.basic
permission-message: You don't have <permission></source> </code> </blockquote>

*<code>'''basic'''</code> - 指令名称

*<code>'''description'''</code> - 指令描述

*<code>'''usage'''</code> - 在oncommand方法return false后显示的用法提示。尽量简洁, 使别人能够理解指令是什么以及如何使用它。

*<code>'''permission'''</code> - 被一些显示帮助信息的插件使用，用来决定向玩家显示哪个指令（完全不对劲吧！）。

*<code>'''permission-message'''</code> - 当玩家使用了这个指令而没有权限时输出的信息。

PS:yml文件使用两个空格作为制表符,使用tab键输入制表符会导致错误。

===控制台指令vs玩家指令===

你可能注意到了上文的<code>'''CommandSender sender'''</code>参数. <code>'''CommandSender'''</code> 是个Bukkit接口，

它有两个（对插件编写者）有用的子类：<code>'''Player'''</code> 和 <code>'''ConsoleCommandSender'''</code>.

所以当你编写插件的时候, 确定这个指令从控制台发出后能完全正常工作是十分必要的,

那些只能由在线玩家执行的指令 ''只能'' 由一个在线玩家执行。

有的插件在判断命令执行对象不是玩家时仅仅用return进行处理 (比如当有人从控制台发出指令),

即便这些指令能够在控制台完美运行（比如改变天气的指令）。

一个判断sender的方法:
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { //如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} else if (cmd.getName().equalsIgnoreCase("basic2")) {
if (!(sender instanceof Player)) { //如果sender与Player类不匹配
sender.sendMessage("This command can only be run by a player.");
} else {
Player player = (Player) sender;
// 所需要执行的事（此处略）
}
return true;
}
return false;
}

在这个例子里，指令'''basic'''能由任何人发出 - 一个在线的玩家, 或者服务器后台的op.

但是指令'''basic2'''只能由一个在线的玩家发出.

大体上说,你应该允许尽可能多的指令在控制台和玩家聊天框里都正常执行.

需要在线玩家执行的指令可以使用以上例子中的机制来检测<code>'''CommandSender'''</code>是一个玩家.

很多指令广泛依靠于一些玩家的属性（例如可以被tp或被给予物品等等）。

如果你想更进一步, 你可以对你的指令的自变量做一些额外的检测，例如传送指令在提供玩家ID的情况下（也只有在这种情况下）可以在控制台被执行。

=== 使用独立的 CommandExecutor class ===

以上的例子必须把 <code>'''onCommand()'''</code> 方法放在插件的主类里。

对于小插件来说，这是极好的,但如果你要写一个大点的插件,把你的 <code>'''onCommand()'''</code>方法放在独立的类里将会很有意义。

幸运的是，这并不难:

*在你的包里创建一个新类. 命名为'''MyPluginCommandExecutor'''之类的 (当然，要把'''MyPlugin'''替换成你制作的插件的名字)。这个类 '''必须''' 继承Bukkit 的'''CommandExecutor'''接口。

*在你的插件的<code>'''onEnable()'''</code>方法中,你需要实例化你创建的命令执行类(CommandExecutor class), 然后做一个像下面一样的调用：<code>getCommand("basic").setExecutor(myExecutor);</code>
其中"basic"是我们需要操控的指令, <code>myExecutor</code> 是我们创建的实例.

废话少说直接吔我例子:

'''MyPlugin.java''' (插件的主类):
@Override
public void onEnable() {
// 如果你没有在plugins.yml注册过指令的话，此处会抛出空指针异常！
this.getCommand("basic").setExecutor(new MyPluginCommandExecutor(this));
}

'''MyPluginCommandExecutor.java'''（独立CommandExecutor类）:
public class MyPluginCommandExecutor implements CommandExecutor {
private final MyPlugin plugin;

public MyPluginCommandExecutor(MyPlugin plugin) {
this.plugin = plugin; // Store the plugin in situations where you need it.
}

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 和以前一样执行就好…
}
}

请注意我们是如何把主类里的对象指向'''MyPluginCommandExecutor'''的. 这允许我们轻易的使用主类对象的方法（如果我们需要的话）。

这么做的话, 我们便能更好的组织代码 - 如果 <code>'''onCommand()'''</code> 方法又大又复杂, 它就能被划分为子类，从而不使插件的主类显得凌乱。

PS：如果你的插件含有多个指令的话, 你需要为每一个指令单独设立一个commandexecutor.

=== 写一个安全的指令 ===
当写一个指令的时候,别进行任何假设（很重要）, 例如假设执行者一定是个玩家. 请牢记以下原则:

==== 在命令执行前确定发出者是玩家 ====

使用简单的例子来进行检测:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (sender instanceof Player) {
Player player = (Player) sender;
// do something
} else {
sender.sendMessage("You must be a player!");
return false;
}
// do something
return false;
}

==== 检测自变量个数 ====

别老是认为玩家都能打对正确数量的自变量.

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (args.length > 4) {
sender.sendMessage("Too many arguments!");
return false;
}
if (args.length < 2) {
sender.sendMessage("Not enough arguments!");
return false;
}
}

==== 在获取玩家之前先检测他们是否在线 ====

有时你想通过命令发出者打出的ID来获取其他玩家，请确保他们在线再说！

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
Player target = (Bukkit.getServer().getPlayer(args[0]));
if (target == null) {
sender.sendMessage(args[0] + " is not online!");
return false;
}
return false;
}

如果你想对离线玩家进行操作，<code>'''OfflinePlayer'''</code>类提供了基础操作的方法.

== 插件的配置/设置 ==
Bukkit API 为插件提供了一种简便的方法，用来管理用户自定义的设置。同时，通过这种方法也可以储存数据。
:: ''详情请查看: [[Configuration API Reference]]''

== 权限 ==

利用新的Bukkit API来设置权限是再容易不过的事情. 检测玩家是否拥有权限，可以使用以下代码:
<blockquote><source lang="java">if (player.hasPermission("some.pointless.permission")) {
//执行此段代码(有权限)
} else {
//执行此段代码(无权限)
}</source> </blockquote>
你也可以检测一个权限节点是否被定义过，(等效于 Java 语言中的'''null''')，使用下面的方法:
<blockquote><source lang="java">boolean isPermissionSet(String name)</source></blockquote>
你或许对此抱有疑惑:为什么这段代码中没有任何用户群的信息？因为它们并不是必需的. 之前这段代码想要实现的主要功能之一就是根据用户群格式化聊天信息. 但其实使用权限就可以很容易地完成这项工作.你可以在聊天插件的配置文件中定义权限与前缀的对应关系. 举例来说，"someChat.prefix.admin" 权限可以对应前缀[Admin].当拥有此权限的玩家发出聊天信息时，聊天前缀便是[Admin].

另一个想要实现的主要功能则是给所有拥有权限的在线用户发一条信息.你可以这样做:
<blockquote><source lang="java">for (Player player: Bukkit.getServer().getOnlinePlayers()) {
if (player.hasPermission("send.receive.message")) {
player.sendMessage("You were sent a message");
}
}</source> </blockquote>
看到这里你可能会问，若是没有权限组我该如何配置玩家的 [[权限]] ？既然 [[Bukkit]] API 本身并没有提供用户组的预设, 你必须通过安装一款权限组插件，像 [[permissionsBukkit]] 这样的插件来帮助你配置用户群. '''API 只是提供接口而不是提供implementation.'''

=== 配置权限 ===
{{Hide|标题=译者注 |内容= 其一，以下代码中部分内容将以''//文字''翻译，使用时请不要加入其中内容，仅做教程中的翻译参考；
其二，default:true在下面翻译为全员默认拥有该权限，default:false则翻译为全员默认没有该权限，请注意理解。 }}
如果你想要更多地控制你的权限，例如设置权限的默认值或是子权限节点，不如将权限节点加入你的 ''[[plugin.yml]]''文件.这并不是必须的，但我们推荐你这样做. 下面是一个实例，显示了当你将权限添加在''plugin.yml''文件末尾时的样子:
<blockquote><code><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //给予使用doorman所有命令的权限
children: //子权限节点
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false
doorman.kick:
description: Allows you to kick a user //允许你踢出一名用户
default: op //OP默认拥有该权限
doorman.ban:
description: Allows you to ban a user //允许你封禁一名用户
default: op //OP默认拥有该权限
doorman.knock:
description: Knocks on the door! //敲门
default: true //全员默认拥有该权限
doorman.denied:
description: Prevents this user from entering the door //禁止拥有该权限节点的用户进入门内</source> </code> </blockquote>
值得注意的是,你的插件使用的每个权限都被定义为 ''permissions'' 这个节点的子权限节点. 每个权限都能够拥有一个描述，默认值以及子权限节点。
==== 默认值 ====

当一个权限没有明确是否为玩家所拥有 ，''hasPermission''<ref>这是一个检测玩家是否拥有指定权限节点的方法</ref> 将返回false<ref>该方法返回的boolean值</ref>. 在你的[[plugin.yml]] you can change this by setting the default node to be one of four values:

*'''true''' - 全员默认拥有该权限.
*'''false''' - 全员默认没有该权限.
*'''op''' - 如果玩家是一名OP<ref>Operator，服务器管理员</ref>，那么他将拥有该权限.
*'''not op''' - 如果玩家不是一名OP，那么他将拥有该权限.

==== 子权限 ====

在这之前你可能已经习惯了通过权限节点自动分配所有的子权限<ref>原句:Before now you will probably be used to the * permission to automatically assign all sub permissions.此处的sub permissions应是同上文“你的插件使用的每个权限都被定义为 permissions 这个节点的子权限节点.”相照应</ref>. 现在这种方法已经随着bukkit API<ref>应用程序编程接口(Application Programming Interface)</ref>的更新而改变，现在你可以自己定义子权限了. 这将使得插件具有更多的灵活性. 下面是一个例子:
<blockquote><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //翻译见上
children:
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false</source> </blockquote>
在这里，''doorman.*'' 权限拥有几个子权限并分配在其下. 子权限工作的方式就是当''doorman.*'' 权限节点被设置为true时,子权限也会随之设置为 ''plugin.yml''中的默认值. 然而当''doorman.*'' 被设置为false时，所有子权限都会设置为与默认值相反的值（true->false,false->true）.
<references />

=== 设置你自己的权限 ===

如果你希望想知道更多有关开发你自己的权限插件的事情(即是设置权限的管理类插件) ，那么请前往查看教程 [[Developing a permissions plugin]].

== Scheduling Tasks and Background Tasks ==

Currently, Minecraft servers operate nearly all of the game logic in one thread, so each individual task that happens in the game needs to be kept very short. A complicated piece of code in your plugin has the potential to cause huge delays and lag spikes to the game logic, if not handled properly.

Luckily, Bukkit has support for scheduling code in your plugin. You can submit a Runnable task to occur once in the future, or on a recurring basis, or you can spin off a whole new independent thread that can perform lengthy tasks in parallel with the game logic.

There is a separate [[Scheduler Programming]] tutorial which introduces the Scheduler, and gives more information on using it to schedule synchronous tasks, and on kicking off asynchronous tasks in Bukkit.

== 方块操控 ==

这是一个很容易的方法创建、获取或修改一个方块, 例如当你想要修改往你头上数第五格的方块时, 首先你需要做的是获取你当前的坐标点, 然后往你当前的坐标点的Y轴加上五, 获取目标方块后我们便能够很容易地修改它了, 例子如下:
<blockquote><source lang="java">
@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
// 得到玩家当前的坐标.
Location loc = event.getPlayer().getLocation();
// 设置目标坐标为玩家头顶 5 格处.
loc.setY(loc.getY() + 5);
// 得到目标坐标的方块
Block b = loc.getBlock();
// 将目标坐标的方块更改为石头 (stone).
b.setType(Material.STONE);
}</source> </blockquote>
上面的代码获取了玩家的所在位置，获取头上的第五个方块，并且放上一个石头（stone）。 Note that once you have a <code>Block</code>, there are other things you can do besides set its type. 你可以查阅JavaDoc获取更多的东西。

你可以用这样相似的观念去生成一些建筑，并且还可以用编程的方式通过算法生成一些独特的方块（这里指由很多个方块拼在一起的四四方方的方块）。比如，去生成一个实心的方块建筑，你可能在生成建筑的时候还需要用到<code>for</code>循环，去一遍遍循环来生成这些建筑，填满这些建筑等。
下面，是一个在指定坐标生成一个实心的方块建筑的实例方法：
<blockquote><source lang="java">
public void generateCube(Location loc, int length) {
// 放置这个方块最中间的方块并且获取这个方块的坐标。
// Uses getBlockN() instead of getN() to avoid casting to an int later.
int x1 = loc.getBlockX();
int y1 = loc.getBlockY();
int z1 = loc.getBlockZ();

// Figure out the opposite corner of the cube by taking the corner and adding length to all coordinates.
int x2 = x1 + length;
int y2 = y1 + length;
int z2 = z1 + length;

World world = loc.getWorld();

// Loop over the cube in the x dimension.
for (int xPoint = x1; xPoint <= x2; xPoint++) {
// Loop over the cube in the y dimension.
for (int yPoint = y1; yPoint <= y2; yPoint++) {
// Loop over the cube in the z dimension.
for (int zPoint = z1; zPoint <= z2; zPoint++) {
// Get the block that we are currently looping over.
Block currentBlock = world.getBlockAt(xPoint, yPoint, zPoint);
// 设置方块ID为57号(钻石块!)
currentBlock.setType(Material.DIAMOND_BLOCK); //这里下面会提到
}
}
}
}</source></blockquote>
这个方法将会在程序给予这个方法高度和起始坐标（最中间的方块的坐标）时，构建一个3D的方块建筑。简单的删除方块也可以使用这个方法的思路实现，但是，但是设置方块的时候，记得把上面标注会提到的那行，设置为物品ID为0的方块(空气方块)。 
<blockquote></blockquote>

== (玩家)操控背包 ==

这个部分大部分讲的是操控玩家的背包。但是在某些情况下，操控箱子里的内容与此相同，当然得在你能找到获取箱子里内容的方法才可以。 :P. 这是一个操控玩家背包的一个例子:
<blockquote><source lang="java">public void onPlayerJoin(PlayerJoinEvent evt) {
Player player = evt.getPlayer(); // 当玩家加入游戏
PlayerInventory inventory = player.getInventory(); // 获取玩家背包列表
ItemStack itemstack = new ItemStack(Material.DIAMOND, 64); // 生成一组钻石

if (inventory.contains(itemstack)) {
inventory.addItem(itemstack); // 将一组钻石放到玩家的背包里
player.sendMessage("Wow！你看上去很土豪啊！"); //向玩家发送消息("Wow！你看上去很土豪啊！")
}
}</source> </blockquote>
所以，上面代码里面的 onPlayerJoin 方法中，我们首先构建了一些变量，让我们的工作变得更容易一些。变量分别是： player, inventory and itemstack。 inventory 变量是玩家的背包内容，itemstack是那64个钻石的物品栈。然后我们判断了玩家是不是有一组钻石。如果有，我们就用inventory.addItem(itemstack)方法再给玩家一组钻石，并且给他发送一个消息“Wow！你看上去很土豪啊！”。所以操控背包并不像我们想象的那么难，如果我们想实现让玩家进入游戏，检测到一组钻石后删掉这组钻石，只需要把代码里的inventory.addItem(itemstack)替换成inventory.remove(itemstack)。获取你还得把“Wow！你看上去很土豪啊！”改成“Wow！你看上去好穷啊！”2333333。

== Item Manipulation ==

When dealing with items in the code, you use the ItemStack class for looking up and setting all information on that stack.

=== Enchantments ===

To enchant an item you must first know the [http://www.minecraftwiki.net/wiki/Data_values Item Code] and the [http://www.minecraftwiki.net/wiki/Talk:Enchanting#Effect_IDs Effect ID]. Enchantments themselves cannot be instantiated (new Enchantment() won't work) because they're abstract, so you must use an EnchantmentWrapper. If you want to enchant items that can't be enchanted inside normal SMP, use addUnsafeEnchantment() instead of addEnchantment()

<source lang="java">
int itemCode = 280; //use the item code you want here
int effectId = 20; //use the enchantment code you want here
int enchantmentLevel = 100;

ItemStack myItem = new ItemStack(itemCode); //new item of item code
Enchantment myEnchantment = new EnchantmentWrapper(effectId); //new enchantment of effect id
myItem.addEnchantment(myEnchantment, enchantmentLevel); //enchant the item
</source>

=== ItemMeta ===
You can set the display name of an item by doing this.
<source lang="java">
String myDisplayName = "Awesome Sword"; //这里是保存了你想要显示的名字

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //你要更改的方块
ItemMeta im = myItem.getItemMeta(); //得到方块的元数据
im.setDisplayName(myDisplayName); //设置它显示的名字
myItem.setItemMeta(im); //保存更改
</source>
You can also set the lores of an item. The lores are the small annotations on an item, like "+5 attack damage" on a stone sword.
<source lang="java">
List<String> lores = new ArrayList<String>();
lores.add("Example lore", "this one comes on line 2");

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //your item
ItemMeta im = myItem.getItemMeta(); //get the itemmeta of the item again
im.setLore(lores); //add the lores of course
myItem.setItemMeta(im); //give the item the new itemmeta
</source>

== Maps, and Sets, and Lists, Oh My! <ref>标题中Map,Set,List均为Java类集中的接口，故不翻译</ref> ==

除了Map类和HashMap类，Java中还提供了其它的数据结构类集。

他们提供这些不同的类，是因为有些时候，使用Map类并不合适。<nowiki>[[Java data structure classes]]</nowiki>在这个条目中，有对Java数据框架类集更深入的讲述。

<nowiki>=== HashMaps概览以及如何使用此接口 ===</nowiki>

<nowiki><big></nowiki>

<nowiki>'''</nowiki>Keep in mind to never use a player in a hashmap!<nowiki>'''</nowiki><ref>下面有讲解。</ref>

应在HashMap中使用字符串.，使用 "p.getName()" 来添加，移除或是检查列表中是否含有某个玩家.

将玩家当作object储存在HashMap中会造成大量内存泄漏.

<nowiki></big></nowiki>

When making a plugin you will get to a point where just using single variables to state an event has happened or a condition has been met will be insufficient, due to more than one player performing that action/event.

This was the problem I had with one of my old plugins, Zones, now improved and re-named to Regions. I was getting most of these errors because I didn't consider how the plugin would behave on an actual server with more than one on at any given time. I was using a single boolean variable to check whether players were in the region or not and obviously this wouldn't work as the values for each individual player need to be separate. So if one player was in a region and one was out the variable would constantly be changing which could/would/did cause numerous errors.

A HashMap is an excellent way of doing this. A HashMap is a way of mapping/assigning a value to a key. You could set up the HashMap so that the key is a player and the value could be anything you want, however the useful things with HashMaps is that one key can only contain one value and there can be no duplicate keys. So say for example I put "adam" as the key and assigned a value of "a" to it. That would work as intended, but then say afterwards I wanted to assign the value of "b" to key "adam" I would be able to and would get no errors but the value of "a" assigned to key "adam" in the HashMap would be overwritten because HashMaps cannot contain duplicate values.

<nowiki>==== Defining a HashMap ====</nowiki>

<nowiki><blockquote><source lang="java">public Map<KeyType, DataType> HashMapName = new HashMap<>(); //Example syntax</nowiki>

// Example Declaration

public Map<String, Boolean> pluginEnabled = new HashMap<>();

public Map<String, Boolean> isGodMode = new HashMap<>();

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Keep that code in mind because we will be using it for the rest of the tutorial on HashMaps. So, for example lets create a simple function which will toggle whether the plugin has been enabled or not. Firstly, inside your on command function which I explained earlier you will need to create a function to send the player name to the function and adjust the players state accordingly.

So inside on command you'll need this, the function name can be different but for the sake of simplicity it's best if you keep it the same.

<nowiki><blockquote><source lang="java">Player player = (Player) sender;</nowiki>

togglePluginState(player);<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

This code above will cast the value of sender to player and pass that argument to the function togglePluginState(). But now we need to create our togglePluginState() function.

<nowiki><blockquote><source lang="java">public void togglePluginState(Player player) {</nowiki>

// Notice how we use the player name as the key here,

// not the player object

String playerName = player.getName();

if (pluginEnabled.containsKey(playerName)) {

if (pluginEnabled.get(playerName)) {

pluginEnabled.put(playerName, false);

player.sendMessage("Plugin disabled");

} else {

pluginEnabled.put(playerName, true);

player.sendMessage("Plugin enabled");

}

} else {

pluginEnabled.put(playerName, true); //If you want plugin disabled by default change this value to false.

player.sendMessage("Plugin enabled");

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Now, what this code is doing is checking if the HashMap first contains the key player, so if it has been put into the HashMap, if it is then we check the value of the HashMap key by get(player); if this is true then set value to false and send the player a message, else if the value is false then do the opposite, set the value to true and send a message again. But if the HashMap does not contain the key player then we can assume that this is their first run/use so we change the default value and add the player to the HashMap.

<nowiki>==== More Ideas for HashMaps ====</nowiki>

A HashMap (or really any kind of Map in Java) is an association. It allows quick and efficient lookup of some sort of <nowiki>'''value''', given a unique '''key'''</nowiki>. Anywhere this happens in your code, a Map may be your solution.

Here are a few other ideas which are ideally suited to using Maps. As you will see, it doesn't have to be data that you store per player, but can be any kind of data that needs to be "translated" from one form to another.

<nowiki>===== Data Value Lookups =====</nowiki>

<nowiki><blockquote><source lang="java"></nowiki>

public Map<String, Integer> wool_colors = new HashMap<>();

// Run this on plugin startup (ideally reading from a file instead of copied out row by row):

wool_colors.put("orange", 1);

wool_colors.put("magenta", 2);

wool_colors.put("light blue", 3);

..

wool_colors.put("black", 15);

// Run this in response to user commands - turn "green" into 13

int datavalue = 0;

if (wool_colors.containsKey(argument)) {

datavalue = wool_colors.get(argument);

} else {

try { datavalue = Integer.parseInt(argument); }

catch (Exception e) {}

}

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

<nowiki>==== Saving/Loading a HashMap ====</nowiki>

Once you know how to work with HashMaps, you probably want to know how to save and load the HashMap data. Saving and loading HashMap data is appropriate if

<nowiki>*</nowiki>you don't want an administrator to edit the data manually

<nowiki>*</nowiki>you need to save data in binary format (too complex to organize for YAML)

<nowiki>*</nowiki>you want to avoid parsing block names and/or other objects from freeform text

This is very simple way how to save any HashMap. You can replace HashMap&lt;String, Integer&gt; with any type of HashMap you want. Let's take an example HashMap with code to save it:

<nowiki><blockquote><source lang="java"></nowiki>

HashMap<String, Integer> mapToSave = new HashMap<String,Integer>();

public void save(HashMap<String, Integer> map, String path) {

try {

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(map);

oos.flush();

oos.close();

//Handle I/O exceptions

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

save(mapToSave, getDataFolder() + File.separator + "example.bin");<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can see it's really easy. Loading works very very similar but we use ObjectInputStream instead of ObjectOutputStream ,FileInputStream instead of FileOutputStream,readObject() instead of writeObject() and we return the HashMap.

<nowiki><blockquote><source lang="java">public HashMap<String, Integer> load(String path) {</nowiki>

try {

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

Object result = ois.readObject();

//you can feel free to cast result to HashMap<String, Integer> if you know there's that HashMap in the file

return (HashMap<String, Integer>)result;

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

HashMap<Integer, String> loadedMap;

String path = getDataFolder() + File.separator + "example.bin";

File file = new File(path);

if (file.exists()) { // check if file exists before loading to avoid errors!

loadedMap = load(path);

}<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can use this "API" for saving/loading HashMaps, ArrayLists, and all Objects which implement Serializable or Externalizable interface.

<nowiki><blockquote><source lang="java">/** SLAPI = Saving/Loading API</nowiki>

* API for Saving and Loading Objects.

* Everyone has permission to include this code in their plugins as they wish :)

* @author Tomsik68<tomsik68@gmail.com>

*/

public class SLAPI

{

public static <T extends Object> void save(T obj,String path) throws Exception

{

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(obj);

oos.flush();

oos.close();

}

public static <T extends Object> T load(String path) throws Exception

{

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

T result = (T)ois.readObject();

ois.close();

return result;

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Example implementation of this API: <nowiki>'''</nowiki>I'm skipping some part of code in this source<nowiki>'''</nowiki>

<nowiki><blockquote><source lang="java">public class Example extends JavaPlugin {</nowiki>

private ArrayList<Object> list = new ArrayList<>();

@Override

public void onEnable() {

try {

list = SLAPI.load("example.bin");

} catch(Exception e) {

//handle the exception

e.printStackTrace();

}

}

@Override

public void onDisable() {

try {

SLAPI.save(list,"example.bin");

} catch(Exception e) {

e.printStackTrace();

}

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Note #1: This will work un-modified with almost all well-known Java types like Integer, String, HashMap. It will also work for some Bukkit types as well. If you're writing your own data object classes, and you may want to save their state using this technique, you should read about Java's Serializable or Externalizable interface. The only difference between Externalizable and Serializable is, that Serializable automatically takes all of class's fields and tries to serialize them, while Externalizable allows you to define method for reading and writing the Object. It's easy to add to your code, and it will make your data persistent with very little work required. No more parsing!

Note #2: This API doesn't support changes. Once you change something in the class, data files saved with older version of your plugin won't load correctly.

<nowiki>===== Tips & Examples =====</nowiki>

1.) Simplify your save structure

Try to use as much simple types as possible. E.g. if you want to save player, save their UUID instead. If you want to save world, save its UUID. If you want to save location, save x,y,z world UUID. DO NOT DIRECTLY SAVE BUKKIT TYPES!

2.) Save version number along with data

You should always remember, that you don't know what you'll be saving in the same file tomorrow. Will you ever migrate this file because of newer version of your plugin, bukkit, or minecraft? You don't know!

3.) Migrate older files

If your plugin finds older version of some file, it should update the file accordingly and change version number.

<references />

== 元数据 ==

Bukkit正在尝试尽可能的让制作插件变得更简单，所以带有一个键值例如Player, Entity, World，甚至是一个block的HashMaps都可以用元数据取缔掉。元数据是一些替代HashMap的方式。他可以允许你去自定义"fields"给Players, Entities, Worlds and Blocks.这些东西都是元数据类的一个成员(详见[http://jd.bukkit.org/doxygen/de/d59/interfaceorg_1_1bukkit_1_1metadata_1_1MetadataValue.html#ab49975fe013a0626dd29d3b85c63a82f])It works very simply. Everything that is Metadatable holds its own HashMap of Metadata which you have access to. That means, for example, if you're creating an economy plugin, you would need a HashMap of Player and Float or Double. 如果用了元数据，你不必去做! You just attach to player new metadata 值, and that's it! 

=== 为何要去使用元数据 ===

* Metadata is all handled by Bukkit, which makes it a very good alternative to HashMaps.
* 元数据可以用来跟其他插件分享信息与数据。

=== 为什么不去使用元数据 ===

* Slightly more difficult to get the value.
* It is not saved on shutdown (but then again, neither are any Maps that you create).

=== 获取 & 设置元数据 ===

<source lang="java">
public void setMetadata(Metadatable object, String key, Object value, Plugin plugin) {
object.setMetadata(key, new FixedMetadataValue(plugin,value));
}

public Object getMetadata(Metadatable object, String key, Plugin plugin) {
List<MetadataValue> values = object.getMetadata(key);
for (MetadataValue value : values) {
// Plugins are singleton objects, so using == is safe here
if (value.getOwningPlugin() == plugin) {
return value.value();
}
}
return null;
}</source>

Note: If you're manipulating with numbers, booleans or strings, use convenient method to get the result. For example, you can use asInt(), asString() or asBoolean() instead of value to find out the value.

== Databases ==

Sometimes flat files aren't enough for what your looking to do, this is where databases come in. The most common database engines available on Linux/Mac/Windows machines typically run on some flavor of SQL (Structured Query Language).

Software offering SQL allow you to create databases with columns and header to identify to contents of each cell. Think of it as a spreadsheet on steroids, where every column you set up in your database can enforce rules to ensure integrity. Apart from being more organised than a simple custom data file, SQL provides faster access and better searching than flat files.

The SQL standard helps applications like Bukkit implement database storage for their data in a consistent way. Unfortunately, there's more than one SQL-ready database engine, and each has minor differences in how to configure and use it. Which one you choose may depend on your particular needs. (Some plugins even offer configurable options to connect to multiple database engines!)

=== SQLite ===

Alta189 has written a [http://forums.bukkit.org/threads/lib-tut-mysql-sqlite-bukkit-drivers.33849/ fantastic SQLite tutorial] which I suggest you watch if you're interested in using SQL in your plugins, included with the tutorials is a handy library you can download and import to make using SQL easier. Once you have watched these video tutorials I would suggest you go and learn some SQL syntax, it's very straightforward and shouldn't take you long to pick up. SQL Tutorials [http://www.w3schools.com/sql/default.asp @W3Schools] and [http://www.1keydata.com/sql/sql.html @1Keydata].

SQLite is great for very simple databases, because there's no server concerns to set up. Just make a few calls to create a new database and table. It's easy to back up: just copy the whole database file in one go. SQLite is a little bit weaker at data integrity, flexibility in data types, and it may not be something you would want to trust for huge databases of millions of rows. But for a new plugin in development, it's often easiest and fastest to get the SQL basics squared away with SQLite, even if you "graduate" to a more server-class database engine later.

=== MySQL ===

Another popular SQL database engine is called MySQL. It is closer to server-grade than SQLite, where many popular companies or websites depend on it for millions of webpage hits every day. With that security comes a little bit steeper learning-curve, because MySQL has more tunable parameters and capabilities.

The coding for plugins accessing MySQL is mostly the same as tiny SQLite or mega-sized Oracle, with only small differences in syntax here or there. But the administration has room to grow. You may want to set up accounts and privileges inside your MySQL setup. You may want to set up SQL scripts that organize your backups and rollback to previous states.

== 部署你的插件 ==

总之你写好的你的插件,如何把它变成一个可安装在服务端的jar文件呢?

首先我们需要建立一个水桶服务器。 [http://wiki.bukkit.org/Setting_up_a_server 在这里] 能找到开服相关信息.接下来你需要把插件导出为一个.jar文件，

这样你就能在你的服务器里运行它。在Eclipse里, 右键工程，点击''Run as > Maven install''即可:

[[Image:Maveninstall.png]]

将来呢, 当你对插件进行了改动后,在做上述操作之前，如果你想删除之前的.jar文件，你可以右键工程，点击 ''Run as > Maven clean'' 。

如果你在编译插件时遇到了问题, 请检查你的JDK是否正确安装，并浏览[[建立工作区]]条目。

如果你在Eclipse控制台看到了和JDK有关的错误，你可能需要手动调整JDK,因为Eclipse的检测可能发生了错误。

点击''Window -> Preferences'', 然后是''Java -> Installed JREs''。选中你最近安装的JDK作为Java运行环境（JRE）并添加, 并取消掉原来那个报错的JDK:

[[Image:Jrelocation.png]]

如果你的工程成功被编译,JAR文件会生产在 ''target'' 目录下，具体在Eclipse的工作空间里名字为工程名的文件夹中。

这个JAR文件就是一个能正常工作的Bukkit插件了。当然前提是你的plugin.yml里没出差错。

你可以把这个jar文件丢到服务器的plugins文件夹里,重载或重启服务器,就可以测试你的新插件啦。

为了连接上使用你自己的电脑开的服务器 ,在多人游戏的ip里填上你的本地ip即可。

如果出现了错误而你又不能解决的话, 试试这里[http://forums.bukkit.org/forums/plugin-development.5/ plugin development forum],

在这里提问[http://wiki.bukkit.org/IRC bukkitdev IRC channel],或者重新阅读wiki。

当你做完了一个实用的插件,可以考虑把它发表在这里[http://dev.bukkit.org/ dev.bukkit]（为了Bukkit社区的访问量）。

以上可知,JAR格式是默认压缩生成的(JAR文件基于ZIP文件的格式)。这么说来，在上传插件到Bukkit上时把JAR文件压缩成ZIP只会增加文件体积罢了。

而且呢, 放在JAR中的config文件可以在检测不到插件目录（插件自动生成的文件夹，名字与插件名相同，里面是该插件的配置）下的config文件时自动生成。

所以我们一般不把jar文件转换成其他格式。

== 导入其它插件 ==
你可能会希望编辑其它那些有源代码的插件. 如果插件在它的目录下有''pom.xml''(大多数知名插件,例如WorldEdit和Essentials都有),你可以通过点击''File -> Import''来把它作为一个工程导入, 然后打开''Maven''项并选择''Existing Maven Projects'':

[[Image:Importmaven.png]]

然后选择''pom.xml''所在的目录,这个工程就应该出现在你的侧边栏里了。就像平常一样编辑并编译它吧。

== 小贴士 ==

=== 使玩家着火 ===

Bukkit API有很多碉堡的功能。以下是实现一些功能的代码片段。

下面的代码运行一个玩家使另一个玩家着火。通过类似于'''/ignite Notch'''这样的指令，这个指令会让 Notch 着火。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 使用 equalsIgnoreCase() 来忽视大小写
if (cmd.getName().equalsIgnoreCase("ignite")) {
// 确保玩家只输入了一个自变量(要被点着的玩家名).
if (args.length != 1) {
// 当return false时，该指令的使用信息会显示出来。
return false;
}

// 确保命令发出者是个玩家.
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can set other players on fire.");
sender.sendMessage("This is an arbitrary requirement for demonstration purposes only.");
return true;
}

// 获取那个要被点着的玩家. 请注意下标起始是0，不是1.
Player target = Bukkit.getServer().getPlayer(args[0]);

// 确保这个玩家在线。
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}

// 让这个玩家着火1000 ticks (一秒钟大概有20ticks,所以总共是50秒).
target.setFireTicks(1000);
return true;
}
return false;
}

=== 干掉玩家 ===

和标题一样.这里是要干掉某个玩家。

在你的onCommand方法里使用这个:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("KillPlayer")) {
Player target = sender.getServer().getPlayer(args[0]);
// 确保玩家在线.
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}
target.setHealth(0);
}
return false;
}

这里有个小扩展,会使用一个爆炸来杀死玩家:

float explosionPower = 4F; //爆炸等级 - TNT的爆炸等级默认是4F
Player target = sender.getWorld().getPlayer(args[0]);
target.getWorld().createExplosion(target.getLocation(), explosionPower);
target.setHealth(0);

=== 创造一个假爆炸 ===

这段代码会生产一个看起来和听起来与TNT/苦力怕产生的爆炸一样的效果。但是不会对实体和方块产生破坏。在保留爆炸的艺术的同时又削弱了爆炸的威力，真是太有用了（
@EventHandler
public void onExplosionPrime(ExplosionPrimeEvent event) {
Entity entity = event.getEntity();

// 如果事件和点燃的TNT有关,执行一些代码（又略）
if (entity instanceof TNTPrimed) {
entity.getWorld().createExplosion(entity.getLocation(), 0);
}
}

=== 使一个玩家对另外一个玩家隐形 ===

通过输入指令，能让指令执行者对特定的玩家隐形。然而其他人仍然能看到指令执行者。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("HideMe") && args.length == 1) {
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can use this command!");
return true;
}
// 检测指令执行者是玩家后，我们便可以安全的进行强制转换类操作。
Player s = (Player) sender;

// 获取命令执行者指定的玩家
Player target = Bukkit.getServer().getPlayer(args[0]);
if (target == null) {
sender.sendMessage("Player " + args[0] + " is not online.");
return true;
}
// 将 s 从 target 的视野中隐藏起来.
target.hidePlayer(s);
return true;
}
return false;
}

=== 在玩家准星所指处生产闪电 ===

如下代码运行手持鱼竿的玩家通过点击来生成闪电 (当然要用准星瞄准)。真是个简单好玩的恶作剧（。

@EventHandler
public void onPlayerInteractBlock(PlayerInteractEvent event) {
Player player = event.getPlayer();
if (player.getItemInHand().getType() == Material.FISHING_ROD) {
// 在给定坐标中生成一道闪电. 在本例中, 这个坐标是玩家准星瞄准的地方.
// 只能指向200格以内的坐标.
player.getWorld().strikeLightning(player.getTargetBlock(null, 200).getLocation());
}
}

=== 自动格式 ===

Eclipse提供了将你的代码自动转成Oracle规定的格式, 修正了不符合常规的缩进, 空格等等。在侧边栏选中你的项目,然后选择''Source -> Format''即可对其进行更改。

== 插件需求专区 ==

http://forums.bukkit.org/forums/plugin-requests.13/

== 范例文件和样板 ==

*[https://github.com/Bukkit/SamplePlugin/ Bukkit/SamplePlugin on GitHub]

*[http://pastebin.com/wpeTPx7N Example.Java]

*[http://pastebin.com/MTwaAVCT ExamplePlayerListener.Java]

*[http://pastebin.com/6FLixfH3 ExampleBlockListener.Java]

*[http://pastebin.com/8UZ6pkWC ExampleEntityListener.Java]

If you have any more questions on this matter, don't hesitate to visit the BukkitDev [[IRC]] channel and ask!

[[Category:教程]]
[[Category:大篇幅条目]]

Bukkit/插件开发教程

2015-08-31T02:42:29Z

Tdiant：/* (Player) Inventory Manipulation */

{{模板:待翻译}}
{{模板:待完善}}
本页面英文原文内容来源 [http://wiki.bukkit.org/Plugin_Tutorial]
== 介绍 ==

这篇内容丰富的教程旨在帮助你学会如何开发Bukkit插件.这一篇教程不可能完全涉及到Bukkit中所有的可能性,而是最基本的一般概述. 前提是你懂得Java这门语言,并在IDE中设置好你的工作区,此教程介绍了大多数Bukkit插件所必需的语法结构.

== 学习Java ==

'''理解这些教程需要具备Java这门编程语言的基本知识.'''如果你刚开始学习Java或者需要重温一下相关知识，下面有一个并不完整的网站列表可供参考.

<big>[http://docs.oracle.com/javase/tutorial/ Oracle's Java Tutorials]</big> - 官方教程
*[http://www.java2s.com/Tutorial/Java/CatalogJava.htm Java2s.com] - 教程
*[http://www.javacoffeebreak.com/java101/java101.html Java 101] - 教程
*[http://math.hws.edu/javanotes/ JavaNotes] - 免费的在线教科书
*[http://thenewboston.org/list.php?cat=31 TheNewBoston] - 视频教程.

== 开发环境 ==

在编写一个插件前 (或学习Java前) 你需要配置一个开发者环境，这个包括但不限于安装IDE (Integrated Development Environment，集成开发环境)。接下来的教程中有关于Eclipse上IDE的操作指南。

:: ''更多信息，请参见 [[Bukkit/插件开发教程-建立工作区|建立工作区]]''

你'''必须'''下载'''Java'''开发者使用的Eclipse构建版本, '''不是''' '''Java EE'''开发者的版本。 Java EE 开发者的版本不包含此教程需要的Maven支持。

== 新建插件开发项目 ==
=== 创建一个新的项目 ===

在开始工作之前，你需要先在Eclipse中配置好工作区和文件. 打开Eclipse,然后依次点击''File -> New -> Project:''来创建一个新的项目.

[[Image:Newproject.png]]

现在,打开''Maven''文件夹, 然后选择''Maven Project''.点击next,之后在下一个菜单中选择''Create a simple project'', 再次点击''Next'':
如果你看不到''Maven''文件夹, 那么你需要[http://eclipse.org/m2e/download/ 下载m2eclipse]

[[Image:Newproject2.png]]

现在，你需要给你的组用户命名，就像下面这样:
* 如果你拥有一个域名，package则填写逆转的域名地址.
** 例如: i-am-a-bukkit-developer.com 你的package地址即是com.i_am_a_bukkit_developer [http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html source]
** 避免使用一个不属于你自己的域名.
* 没有域名? 这里有几种方法可供选择。
*# 在资源管理站点创建一个用户，比如GitHub或是sourceforge
*#* 对于使用GitHub的用户, 请参照[http://pages.github.com/ 这里的说明] 之后你将获得一个子域名,所以你的package地址是io.github.<username> 
*# 使用你的邮箱. 例如: <username>@gmail.com格式的邮箱应输入com.gmail.<username> 
*# 最不济的方法.：使用独特的组名命名方式，这应当是你最后的解决方法。

以下几个地址不能作为package中的地址前缀:
* org.bukkit
* net.bukkit
* com.bukkit
* net.minecraft

完成基础的组名以后，你需要在最后加上插件的名称. 在这里用 GitHub页面作为讲解的实例. 如果你创建了一个名为 ''TestPlugin''的插件，那么完整的组名是''io.github.<username>'', 你的工程名也是 ''TestPlugin''. 至于版本，默认即可，稍后可以修改。
完成向导:

[[Image:Newproject3.png]]

如果这是你首次使用Eclipse, 点击右上角的"X" 来关闭Welcome提示页面. 现在，你的窗口视图看起来就像下面的图片这样:

[[Image:Eclipsemain.png]]

点击工程名称右边的箭头来进行下一步，现在我们正式开始。
=== 添加Bukkit API ===

在开发插件之前，你需要添加 Bukkit API库文件到你的项目，作为一个dependency, 你也可以添加其他你想实用的API.

找到项目文件夹中部的''pom.xml''并双击进行编辑. 点击''pom.xml''中部的 tab,你将会看到下图所示内容:

[[Image:Pomeditor.png]]

如果你想使用Java 6以上版本的语言特性,你需要指定搭建项目的Java版本.复制并粘贴以下内容(设定项目只能使用Java 7及以下的版本)到 ''</project>''之前:

<code>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<nowiki><</nowiki>source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
</plugins>
</build>
</code>

你或许想使用其他版本,例如 <code>1.8</code> 使用Java 8. 请注意 [http://mcstats.org/global/ 根据MCStats数据统计], 大多数服主选择了Java 7, 所以使用Java 8会使许多服务器无法运行你的插件. 如果你使用Java 1.7的特性, Eclipse将会在报错代码"error"中建议你更改语言版本.同意即可.

在位于代码中段的''</project>''之前粘贴以下内容(这段代码告诉Eclipse关于Bukkit's repository的地址):

<code>
<repositories>
<repository>
<id>bukkit-repo</id>
<url>http://repo.bukkit.org/content/groups/public/</url>
</repository>
</repositories>
</code>

然后继续在 ''</project>''前粘贴以下内容 (这段代码告诉Eclipse搭建插件的Bukkit版本):

<code>
<dependencies>
<dependency>
<groupId>org.bukkit</groupId>
<artifactId>bukkit</artifactId>
<version>1.7.2-R0.3</version>
<type>jar</type>
<scope>provided</scope>
</dependency>
</dependencies>
</code>

你也可以修改这里的Bukkit版本.你可以在[http://repo.bukkit.org/content/groups/public/org/bukkit/bukkit/ here]这里通过查看 maven-metadata.xml文件下的版本列表来获取可用的服务端版本号.

当你完成上述步骤后,''pom.xml''中的内容应该是这样:

[[Image:Finishedpom.png]]

通过菜单 ''File -> Save''或者按住 <code>Ctrl + S</code> 来保存''pom.xml''文件 . 之后, 右键项目标题，然后依次选择 ''Maven -> Update Project''.

=== Bukkit Java文档 ===

如果你曾经使用过Eclipse和Java，你会知道当你将鼠标准心移至class或者 method中的代码部分时，一个含有相关文档内容的黄色小框会弹出来. 这就是（Java的）Java文档。

你可以[http://download.oracle.com/javase/6/docs/api/ Oracle website 在线获取]它.。Bukkit同样拥有文档，这些文档内容包含了关于API中method和class的有用描述。

你可以在[http://jd.bukkit.org/ 这]找到它 (Beta版的Java文档在[http://jd.bukkit.org/ 这]找, 新开发出来的Java文档在

[http://jd.bukkit.org/ 这]) 。为了在Eclipse里使用Java文档,这样的话当你的鼠标停留在Bukkit的class和method上时，

（Bukkit的）Java文档就会冒出来。
JavaDoc in spigot [https://hub.spigotmc.org/javadocs/bukkit/ Click Here]

首先右键在侧边栏里的"Maven Dependencies"下面的Bukkit jar,选择"Properties".选中窗口左边的''Javadoc Location'', 并粘贴如下网址

'''http://jd.bukkit.org/''' (或者上面的测试版/最新版 Java文档链接也好) 到"Javadoc URL"下面的输入框内. 就像这样:

[[Image:Bukkitjavadocs.png]]

点击 "Validate",然后再点击"OK"就完成了.现在Bukkit Javadocs已经连接到Bukkit提供的资源,同时你也可以通过Eclipse来获得帮助类文档信息了.

=== 创建一个包 ===

现在你需要创建一个包，它将储存所有我们需要使用的Java类文件. 右键展开''src/main/java''折叠并选择 ''New > Package'':

[[Image:Newpackage.png]]

包名的话，先写上你的组名，然后加个点，再写上你的小写Artifact ID。举例, 如果你的组名是''io.github.name''，你的artifact名是 ''TestPlugin''。

你的包名就应该是''io.github.name.testplugin''.

=== 创建插件的类文件 ===

既然我们已经建立好了我们的项目，我们接下来可以开始添加类文件以及制作插件了. 插件的主类指的是拓展(extends)JavaPlugin的类文件. 在你的插件中只能有一个类文件拓展JavaPlugin，无论直接还是间接. 先创建你的主类文件并保持名称与插件名一致是个很好的习惯.右键你之前新建的包,并选择  ''New > Class''.你将会创建一个新的类文件，就像下面这样

package {$GroupName}.{$ArtifactName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$ArtifactName} extends JavaPlugin {

}

警告：插件绝对不应该调用自己的构造函数并实例化

=== 创建plugin.yml ===

你已经创建了项目和主类，如果你想要Bukkit能够加载你的插件，你还必须创建 '''[[Plugin YAML|plugin.yml]]''' 文件. 这个文件包含有基础的插件信息，如果缺失这个文件，你的插件也将会失效. 此时你需要右键''src/main/resources''. 选择''New > File''. 命名为"'''plugin.yml'''" 并右键完成新文件的创建.Eclipse会打开默认的文本编辑窗口来显示'''plugin.yml'''文件中空白的内容并提供编辑. ''(Hint: 如果你想要使得你的工作空间更加规整，关闭文本编辑器并将'''plugin.yml''' 文件拖到主工作空间(拖到文件目录的右边) 之后你就可以在eclipse中编辑文件了.)''

有三个基础的内容需要在plugin.yml写明.
: name: 插件名称.
: main: [http://docs.oracle.com/javase/specs/jls/se7/html/jls-6.html#jls-6.7 插件主类的完整，合法名称] .
: version: 插件当前版本号.

最简单的 '''plugin.yml''' 文件内就像这样 :

name: {插件名称}
main: {包名}.{主类}
version: {版本号}

PS:插件的包名经常会包括插件的名称，所以看到这个的时候不要感到惊讶。
你的主类是否是你的插件名取决于你之前的命名方式，时刻记住这一点很重要。

'''''更多例子''', 请看[[#Example_Files_and_Templates]]''

此时你的插件已经可以被Bukkit加载了,同时服务端日志也会开始记录你的插件. 不过它现在什么用都没有!

== onEnable()和onDisable()方法 ==

这些方法将在插件启用与卸载时生效. 默认情况下，你的插件在被加载时会调用这些方法，所以你可以在这里注册你需要用到的事件和提供一些调试信息. <code>onEnable()</code> 方法会在插件启用时被调用, 需要包含初始化插件的逻辑语句. <code>onDisable()</code> 方法会在插件卸载时被调用，需要包含清理(clean up)插件的逻辑语句和连接声明(associated state)。此外，插件可以重写 <code>onLoad()</code> 方法来在插件载入时执行附加的逻辑语句。

=== onEnable()和onDisable()方法介绍 ===

在前面的章节中，我们在主类创建了<code>onEnable()</code> 和 <code>onDisable()</code> 方法. 此时，这些代码看起来就像下面这样

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
// 插件载入时要执行的代码（略）
}

@Override
public void onDisable() {
// 插件卸载时要执行的代码（略）
}
}

这些方法已经创建，但目前它们还没有任何作用.
注意: 不需要添加代码来实现输出信息"{$PluginName} has been enabled!" ，因为bukkit会自动输出此类信息
有关更多事件的信息请查看 [[Event_API_Reference|这里]].

=== 发送提示信息 ===

插件能够输出信息至控制台与服务器日志。这是通过调用插件记录器里正确的方法来实现的。首先我们必须调用 <code>getLogger()</code> 方法来检索该插件的记录器，

然后我们就可以开始记录信息了。

我们通过调用<code>onEnable()</code>方法可以实现输出信息。我们需要在<code>onEnable()</code>方法下面插入如下代码：

getLogger().info("onEnable has been invoked!");

在 <code>'''onDisable()'''</code>方法里面，你也可以做类似的事情，不过要改改输出信息。

此时你的主类文件就像这样:

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
getLogger().info("onEnable has been invoked!");
}

@Override
public void onDisable() {
getLogger().info("onDisable has been invoked!");
}
}

=== 防止重载后插件失效 ===

你需要知道的是，插件并不只会伴随服务器关闭、启动而重载，你的插件也可能会被其他插件启用、关闭，或是在服务器运行时使用/reload命令.
假设服务器启动之后一会儿后，你的插件才被启用，这时便是危险的,因为服务器中可能已经有玩家在线、额外的世界被加载以及很多预想不到的不同之处(与"插件同服务器同时加载"的情况相比较).

举个例子来说:
* 你有一个用来储存HashMap中的玩家登入信息的插件
* 你希望该信息对所有玩家都可见
* 一名管理员使用/reload命令
* 你的插件被卸载，所有储存的数据都丢失了
* 你的插件被再次启用时，一些玩家已经在线
* 这些玩家在HashMap并没有储存的信息
* 你试图重新获得他们的信息，但是失败了!

为了插件重载以后能够正常工作, 你需要在插件启用时加载所有已经在线的玩家的信息并将之储存在HashMap中.

for (Player player : Bukkit.getServer().getOnlinePlayers()) {
playerList.put(player.getName(), playerData(player));
}

== 监听器 ==
监听器是一种方法被调用来对事件作出反应的类.所有的监听器使用 org.bukkit.event.Listener接口.更多有关监听器创建的细节,
:: '' 请查看: [[Event API Reference]]''

== 指令 ==

=== onCommand() 方法 ===

现在你已经知道如何注册一个事件并做出响应,但是如果你只是想要在命令输入之后做出响应呢? 你可以使用 <code>'''onCommand'''</code>方法.

这个代码的作用是当玩家输入“/”时，监听该操作并执行相关语句"/" . 举个例子来说.输入 "/do something" 将会执行 <code>'''onCommand'''</code>方法.

此种情况下，因为没有特定的行为被编程，所以并不会发生任何事情。

请避免使用和bukkit所提供的指令重名的指令, 然后深思你的指令名的唯一性。

例如.指令"give"已经被好几个插件使用了, 如果你执行了另外一个"give"指令, 你的插件将会和这些插件冲突。

你必须在插件的"plugins.yml"注册你的指令否则这个方法将不会被触发。

<code>'''onCommand'''</code>方法必须返回一个布尔值（true或false）。

如果返回值是true，你不会看到什么明显的事情发生。

但如果返回值是false，则会返回你的plugin.yml里的'usage:property'然后发送给命令使用者.

当使用 <code>'''onCommand'''</code>方法时, 你需要填写4个参数.

*<code>'''CommandSender sender'''</code> - 发送命令的对象

*<code>'''Command cmd'''</code> - 被执行的指令

*<code>'''String commandLabel'''</code> - 被执行指令的别名

*<code>'''String[] args'''</code> - 该指令的自变量数组。

例如.指令 ''/hello abc def'' 中， ''abc'' 会被存放进args[0]中, ''def'' 被存放进args[1]中。

==== 设置命令 ====
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { // 如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} //如果以上内容成功执行，则返回true
// 如果执行失败，则返回false.
return false;
}

每当使用<code>'''onCommand'''</code>方法时，在每个方法后面都加上一个 return false; 是一个惯例。

返回false会显示在plugin.yml里设置的usage信息 (看下面). 用这种方法的话，一旦执行出错便会显示usage信息。

每当方法return一个值的时候，这个方法就会退出，所以return true的时候，在它下面的代码就会被跳过,

除非return语句在一个if的嵌套中，或者类似的嵌套情况。

<code>'''.equalsIgnoreCase("basic")'''</code>代表忽略英文大小写. 在这种情况下,字符串"BAsIc" 和 "BasiC"和 basic相同，代码会被照常执行。

和以前一样，加两行import在你的java文件头

import org.bukkit.command.Command;

import org.bukkit.command.CommandSender;

=== 在Plugin.yml中添加你的指令 ===

你需要添加你的指令到 '''plugin.yml''' 文件里. 如下是指令/basic添加到 '''plugin.yml'''的例子（请在plugins.yml的末尾添加如下代码）:

commands:
basic:
description: This is a demo command.
usage: /<command> [player]
permission: <plugin name>.basic
permission-message: You don't have <permission></source> </code> </blockquote>

*<code>'''basic'''</code> - 指令名称

*<code>'''description'''</code> - 指令描述

*<code>'''usage'''</code> - 在oncommand方法return false后显示的用法提示。尽量简洁, 使别人能够理解指令是什么以及如何使用它。

*<code>'''permission'''</code> - 被一些显示帮助信息的插件使用，用来决定向玩家显示哪个指令（完全不对劲吧！）。

*<code>'''permission-message'''</code> - 当玩家使用了这个指令而没有权限时输出的信息。

PS:yml文件使用两个空格作为制表符,使用tab键输入制表符会导致错误。

===控制台指令vs玩家指令===

你可能注意到了上文的<code>'''CommandSender sender'''</code>参数. <code>'''CommandSender'''</code> 是个Bukkit接口，

它有两个（对插件编写者）有用的子类：<code>'''Player'''</code> 和 <code>'''ConsoleCommandSender'''</code>.

所以当你编写插件的时候, 确定这个指令从控制台发出后能完全正常工作是十分必要的,

那些只能由在线玩家执行的指令 ''只能'' 由一个在线玩家执行。

有的插件在判断命令执行对象不是玩家时仅仅用return进行处理 (比如当有人从控制台发出指令),

即便这些指令能够在控制台完美运行（比如改变天气的指令）。

一个判断sender的方法:
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { //如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} else if (cmd.getName().equalsIgnoreCase("basic2")) {
if (!(sender instanceof Player)) { //如果sender与Player类不匹配
sender.sendMessage("This command can only be run by a player.");
} else {
Player player = (Player) sender;
// 所需要执行的事（此处略）
}
return true;
}
return false;
}

在这个例子里，指令'''basic'''能由任何人发出 - 一个在线的玩家, 或者服务器后台的op.

但是指令'''basic2'''只能由一个在线的玩家发出.

大体上说,你应该允许尽可能多的指令在控制台和玩家聊天框里都正常执行.

需要在线玩家执行的指令可以使用以上例子中的机制来检测<code>'''CommandSender'''</code>是一个玩家.

很多指令广泛依靠于一些玩家的属性（例如可以被tp或被给予物品等等）。

如果你想更进一步, 你可以对你的指令的自变量做一些额外的检测，例如传送指令在提供玩家ID的情况下（也只有在这种情况下）可以在控制台被执行。

=== 使用独立的 CommandExecutor class ===

以上的例子必须把 <code>'''onCommand()'''</code> 方法放在插件的主类里。

对于小插件来说，这是极好的,但如果你要写一个大点的插件,把你的 <code>'''onCommand()'''</code>方法放在独立的类里将会很有意义。

幸运的是，这并不难:

*在你的包里创建一个新类. 命名为'''MyPluginCommandExecutor'''之类的 (当然，要把'''MyPlugin'''替换成你制作的插件的名字)。这个类 '''必须''' 继承Bukkit 的'''CommandExecutor'''接口。

*在你的插件的<code>'''onEnable()'''</code>方法中,你需要实例化你创建的命令执行类(CommandExecutor class), 然后做一个像下面一样的调用：<code>getCommand("basic").setExecutor(myExecutor);</code>
其中"basic"是我们需要操控的指令, <code>myExecutor</code> 是我们创建的实例.

废话少说直接吔我例子:

'''MyPlugin.java''' (插件的主类):
@Override
public void onEnable() {
// 如果你没有在plugins.yml注册过指令的话，此处会抛出空指针异常！
this.getCommand("basic").setExecutor(new MyPluginCommandExecutor(this));
}

'''MyPluginCommandExecutor.java'''（独立CommandExecutor类）:
public class MyPluginCommandExecutor implements CommandExecutor {
private final MyPlugin plugin;

public MyPluginCommandExecutor(MyPlugin plugin) {
this.plugin = plugin; // Store the plugin in situations where you need it.
}

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 和以前一样执行就好…
}
}

请注意我们是如何把主类里的对象指向'''MyPluginCommandExecutor'''的. 这允许我们轻易的使用主类对象的方法（如果我们需要的话）。

这么做的话, 我们便能更好的组织代码 - 如果 <code>'''onCommand()'''</code> 方法又大又复杂, 它就能被划分为子类，从而不使插件的主类显得凌乱。

PS：如果你的插件含有多个指令的话, 你需要为每一个指令单独设立一个commandexecutor.

=== 写一个安全的指令 ===
当写一个指令的时候,别进行任何假设（很重要）, 例如假设执行者一定是个玩家. 请牢记以下原则:

==== 在命令执行前确定发出者是玩家 ====

使用简单的例子来进行检测:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (sender instanceof Player) {
Player player = (Player) sender;
// do something
} else {
sender.sendMessage("You must be a player!");
return false;
}
// do something
return false;
}

==== 检测自变量个数 ====

别老是认为玩家都能打对正确数量的自变量.

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (args.length > 4) {
sender.sendMessage("Too many arguments!");
return false;
}
if (args.length < 2) {
sender.sendMessage("Not enough arguments!");
return false;
}
}

==== 在获取玩家之前先检测他们是否在线 ====

有时你想通过命令发出者打出的ID来获取其他玩家，请确保他们在线再说！

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
Player target = (Bukkit.getServer().getPlayer(args[0]));
if (target == null) {
sender.sendMessage(args[0] + " is not online!");
return false;
}
return false;
}

如果你想对离线玩家进行操作，<code>'''OfflinePlayer'''</code>类提供了基础操作的方法.

== 插件的配置/设置 ==
Bukkit API 为插件提供了一种简便的方法，用来管理用户自定义的设置。同时，通过这种方法也可以储存数据。
:: ''详情请查看: [[Configuration API Reference]]''

== 权限 ==

利用新的Bukkit API来设置权限是再容易不过的事情. 检测玩家是否拥有权限，可以使用以下代码:
<blockquote><source lang="java">if (player.hasPermission("some.pointless.permission")) {
//执行此段代码(有权限)
} else {
//执行此段代码(无权限)
}</source> </blockquote>
你也可以检测一个权限节点是否被定义过，(等效于 Java 语言中的'''null''')，使用下面的方法:
<blockquote><source lang="java">boolean isPermissionSet(String name)</source></blockquote>
你或许对此抱有疑惑:为什么这段代码中没有任何用户群的信息？因为它们并不是必需的. 之前这段代码想要实现的主要功能之一就是根据用户群格式化聊天信息. 但其实使用权限就可以很容易地完成这项工作.你可以在聊天插件的配置文件中定义权限与前缀的对应关系. 举例来说，"someChat.prefix.admin" 权限可以对应前缀[Admin].当拥有此权限的玩家发出聊天信息时，聊天前缀便是[Admin].

另一个想要实现的主要功能则是给所有拥有权限的在线用户发一条信息.你可以这样做:
<blockquote><source lang="java">for (Player player: Bukkit.getServer().getOnlinePlayers()) {
if (player.hasPermission("send.receive.message")) {
player.sendMessage("You were sent a message");
}
}</source> </blockquote>
看到这里你可能会问，若是没有权限组我该如何配置玩家的 [[权限]] ？既然 [[Bukkit]] API 本身并没有提供用户组的预设, 你必须通过安装一款权限组插件，像 [[permissionsBukkit]] 这样的插件来帮助你配置用户群. '''API 只是提供接口而不是提供implementation.'''

=== 配置权限 ===
{{Hide|标题=译者注 |内容= 其一，以下代码中部分内容将以''//文字''翻译，使用时请不要加入其中内容，仅做教程中的翻译参考；
其二，default:true在下面翻译为全员默认拥有该权限，default:false则翻译为全员默认没有该权限，请注意理解。 }}
如果你想要更多地控制你的权限，例如设置权限的默认值或是子权限节点，不如将权限节点加入你的 ''[[plugin.yml]]''文件.这并不是必须的，但我们推荐你这样做. 下面是一个实例，显示了当你将权限添加在''plugin.yml''文件末尾时的样子:
<blockquote><code><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //给予使用doorman所有命令的权限
children: //子权限节点
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false
doorman.kick:
description: Allows you to kick a user //允许你踢出一名用户
default: op //OP默认拥有该权限
doorman.ban:
description: Allows you to ban a user //允许你封禁一名用户
default: op //OP默认拥有该权限
doorman.knock:
description: Knocks on the door! //敲门
default: true //全员默认拥有该权限
doorman.denied:
description: Prevents this user from entering the door //禁止拥有该权限节点的用户进入门内</source> </code> </blockquote>
值得注意的是,你的插件使用的每个权限都被定义为 ''permissions'' 这个节点的子权限节点. 每个权限都能够拥有一个描述，默认值以及子权限节点。
==== 默认值 ====

当一个权限没有明确是否为玩家所拥有 ，''hasPermission''<ref>这是一个检测玩家是否拥有指定权限节点的方法</ref> 将返回false<ref>该方法返回的boolean值</ref>. 在你的[[plugin.yml]] you can change this by setting the default node to be one of four values:

*'''true''' - 全员默认拥有该权限.
*'''false''' - 全员默认没有该权限.
*'''op''' - 如果玩家是一名OP<ref>Operator，服务器管理员</ref>，那么他将拥有该权限.
*'''not op''' - 如果玩家不是一名OP，那么他将拥有该权限.

==== 子权限 ====

在这之前你可能已经习惯了通过权限节点自动分配所有的子权限<ref>原句:Before now you will probably be used to the * permission to automatically assign all sub permissions.此处的sub permissions应是同上文“你的插件使用的每个权限都被定义为 permissions 这个节点的子权限节点.”相照应</ref>. 现在这种方法已经随着bukkit API<ref>应用程序编程接口(Application Programming Interface)</ref>的更新而改变，现在你可以自己定义子权限了. 这将使得插件具有更多的灵活性. 下面是一个例子:
<blockquote><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //翻译见上
children:
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false</source> </blockquote>
在这里，''doorman.*'' 权限拥有几个子权限并分配在其下. 子权限工作的方式就是当''doorman.*'' 权限节点被设置为true时,子权限也会随之设置为 ''plugin.yml''中的默认值. 然而当''doorman.*'' 被设置为false时，所有子权限都会设置为与默认值相反的值（true->false,false->true）.
<references />

=== 设置你自己的权限 ===

如果你希望想知道更多有关开发你自己的权限插件的事情(即是设置权限的管理类插件) ，那么请前往查看教程 [[Developing a permissions plugin]].

== Scheduling Tasks and Background Tasks ==

Currently, Minecraft servers operate nearly all of the game logic in one thread, so each individual task that happens in the game needs to be kept very short. A complicated piece of code in your plugin has the potential to cause huge delays and lag spikes to the game logic, if not handled properly.

Luckily, Bukkit has support for scheduling code in your plugin. You can submit a Runnable task to occur once in the future, or on a recurring basis, or you can spin off a whole new independent thread that can perform lengthy tasks in parallel with the game logic.

There is a separate [[Scheduler Programming]] tutorial which introduces the Scheduler, and gives more information on using it to schedule synchronous tasks, and on kicking off asynchronous tasks in Bukkit.

== 方块操控 ==

这是一个很容易的方法创建、获取或修改一个方块, 例如当你想要修改往你头上数第五格的方块时, 首先你需要做的是获取你当前的坐标点, 然后往你当前的坐标点的Y轴加上五, 获取目标方块后我们便能够很容易地修改它了, 例子如下:
<blockquote><source lang="java">
@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
// 得到玩家当前的坐标.
Location loc = event.getPlayer().getLocation();
// 设置目标坐标为玩家头顶 5 格处.
loc.setY(loc.getY() + 5);
// 得到目标坐标的方块
Block b = loc.getBlock();
// 将目标坐标的方块更改为石头 (stone).
b.setType(Material.STONE);
}</source> </blockquote>
上面的代码获取了玩家的所在位置，获取头上的第五个方块，并且放上一个石头（stone）。 Note that once you have a <code>Block</code>, there are other things you can do besides set its type. 你可以查阅JavaDoc获取更多的东西。

你可以用这样相似的观念去生成一些建筑，并且还可以用编程的方式通过算法生成一些独特的方块（这里指由很多个方块拼在一起的四四方方的方块）。比如，去生成一个实心的方块建筑，你可能在生成建筑的时候还需要用到<code>for</code>循环，去一遍遍循环来生成这些建筑，填满这些建筑等。
下面，是一个在指定坐标生成一个实心的方块建筑的实例方法：
<blockquote><source lang="java">
public void generateCube(Location loc, int length) {
// 放置这个方块最中间的方块并且获取这个方块的坐标。
// Uses getBlockN() instead of getN() to avoid casting to an int later.
int x1 = loc.getBlockX();
int y1 = loc.getBlockY();
int z1 = loc.getBlockZ();

// Figure out the opposite corner of the cube by taking the corner and adding length to all coordinates.
int x2 = x1 + length;
int y2 = y1 + length;
int z2 = z1 + length;

World world = loc.getWorld();

// Loop over the cube in the x dimension.
for (int xPoint = x1; xPoint <= x2; xPoint++) {
// Loop over the cube in the y dimension.
for (int yPoint = y1; yPoint <= y2; yPoint++) {
// Loop over the cube in the z dimension.
for (int zPoint = z1; zPoint <= z2; zPoint++) {
// Get the block that we are currently looping over.
Block currentBlock = world.getBlockAt(xPoint, yPoint, zPoint);
// 设置方块ID为57号(钻石块!)
currentBlock.setType(Material.DIAMOND_BLOCK); //这里下面会提到
}
}
}
}</source></blockquote>
这个方法将会在程序给予这个方法高度和起始坐标（最中间的方块的坐标）时，构建一个3D的方块建筑。简单的删除方块也可以使用这个方法的思路实现，但是，但是设置方块的时候，记得把上面标注会提到的那行，设置为物品ID为0的方块(空气方块)。 
<blockquote></blockquote>

== (玩家)操控背包 ==

这个部分大部分讲的是操控玩家的背包。但是在某些情况下，操控箱子里的内容与此相同，当然得在你能找到获取箱子里内容的方法才可以。 :P. 这是一个操控玩家背包的一个例子:
<blockquote><source lang="java">public void onPlayerJoin(PlayerJoinEvent evt) {
Player player = evt.getPlayer(); // 当玩家加入游戏
PlayerInventory inventory = player.getInventory(); // 获取玩家背包列表
ItemStack itemstack = new ItemStack(Material.DIAMOND, 64); // 生成一组钻石

if (inventory.contains(itemstack)) {
inventory.addItem(itemstack); // 将一组钻石放到玩家的背包里
player.sendMessage("Wow！你看上去很土豪啊！"); //向玩家发送消息("Wow！你看上去很土豪啊！")
}
}</source> </blockquote>
所以，上面代码里面的 onPlayerJoin 方法中，我们首先构建了一些变量，让我们的工作变得更容易一些。变量分别是： player, inventory and itemstack。 inventory 变量是玩家的背包内容，itemstack是那64个钻石的物品栈。然后我们判断了玩家是不是有一组钻石。如果有，我们就用inventory.addItem(itemstack)方法再给玩家一组钻石，并且给他发送一个消息“Wow！你看上去很土豪啊！”。所以操控背包并不像我们想象的那么难，如果我们想实现让玩家进入游戏，检测到一组钻石后删掉这组钻石，只需要把代码里的inventory.addItem(itemstack)替换成inventory.remove(itemstack)。获取你还得把“Wow！你看上去很土豪啊！”改成“Wow！你看上去好穷啊！”2333333。

== Item Manipulation ==

When dealing with items in the code, you use the ItemStack class for looking up and setting all information on that stack.

=== Enchantments ===

To enchant an item you must first know the [http://www.minecraftwiki.net/wiki/Data_values Item Code] and the [http://www.minecraftwiki.net/wiki/Talk:Enchanting#Effect_IDs Effect ID]. Enchantments themselves cannot be instantiated (new Enchantment() won't work) because they're abstract, so you must use an EnchantmentWrapper. If you want to enchant items that can't be enchanted inside normal SMP, use addUnsafeEnchantment() instead of addEnchantment()

<source lang="java">
int itemCode = 280; //use the item code you want here
int effectId = 20; //use the enchantment code you want here
int enchantmentLevel = 100;

ItemStack myItem = new ItemStack(itemCode); //new item of item code
Enchantment myEnchantment = new EnchantmentWrapper(effectId); //new enchantment of effect id
myItem.addEnchantment(myEnchantment, enchantmentLevel); //enchant the item
</source>

=== ItemMeta ===
You can set the display name of an item by doing this.
<source lang="java">
String myDisplayName = "Awesome Sword"; //这里是保存了你想要显示的名字

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //你要更改的方块
ItemMeta im = myItem.getItemMeta(); //得到方块的元数据
im.setDisplayName(myDisplayName); //设置它显示的名字
myItem.setItemMeta(im); //保存更改
</source>
You can also set the lores of an item. The lores are the small annotations on an item, like "+5 attack damage" on a stone sword.
<source lang="java">
List<String> lores = new ArrayList<String>();
lores.add("Example lore", "this one comes on line 2");

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //your item
ItemMeta im = myItem.getItemMeta(); //get the itemmeta of the item again
im.setLore(lores); //add the lores of course
myItem.setItemMeta(im); //give the item the new itemmeta
</source>

== Maps, and Sets, and Lists, Oh My! <ref>标题中Map,Set,List均为Java类集中的接口，故不翻译</ref> ==

除了Map类和HashMap类，Java中还提供了其它的数据结构类集。

他们提供这些不同的类，是因为有些时候，使用Map类并不合适。<nowiki>[[Java data structure classes]]</nowiki>在这个条目中，有对Java数据框架类集更深入的讲述。

<nowiki>=== HashMaps概览以及如何使用此接口 ===</nowiki>

<nowiki><big></nowiki>

<nowiki>'''</nowiki>Keep in mind to never use a player in a hashmap!<nowiki>'''</nowiki><ref>下面有讲解。</ref>

应在HashMap中使用字符串.，使用 "p.getName()" 来添加，移除或是检查列表中是否含有某个玩家.

将玩家当作object储存在HashMap中会造成大量内存泄漏.

<nowiki></big></nowiki>

When making a plugin you will get to a point where just using single variables to state an event has happened or a condition has been met will be insufficient, due to more than one player performing that action/event.

This was the problem I had with one of my old plugins, Zones, now improved and re-named to Regions. I was getting most of these errors because I didn't consider how the plugin would behave on an actual server with more than one on at any given time. I was using a single boolean variable to check whether players were in the region or not and obviously this wouldn't work as the values for each individual player need to be separate. So if one player was in a region and one was out the variable would constantly be changing which could/would/did cause numerous errors.

A HashMap is an excellent way of doing this. A HashMap is a way of mapping/assigning a value to a key. You could set up the HashMap so that the key is a player and the value could be anything you want, however the useful things with HashMaps is that one key can only contain one value and there can be no duplicate keys. So say for example I put "adam" as the key and assigned a value of "a" to it. That would work as intended, but then say afterwards I wanted to assign the value of "b" to key "adam" I would be able to and would get no errors but the value of "a" assigned to key "adam" in the HashMap would be overwritten because HashMaps cannot contain duplicate values.

<nowiki>==== Defining a HashMap ====</nowiki>

<nowiki><blockquote><source lang="java">public Map<KeyType, DataType> HashMapName = new HashMap<>(); //Example syntax</nowiki>

// Example Declaration

public Map<String, Boolean> pluginEnabled = new HashMap<>();

public Map<String, Boolean> isGodMode = new HashMap<>();

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Keep that code in mind because we will be using it for the rest of the tutorial on HashMaps. So, for example lets create a simple function which will toggle whether the plugin has been enabled or not. Firstly, inside your on command function which I explained earlier you will need to create a function to send the player name to the function and adjust the players state accordingly.

So inside on command you'll need this, the function name can be different but for the sake of simplicity it's best if you keep it the same.

<nowiki><blockquote><source lang="java">Player player = (Player) sender;</nowiki>

togglePluginState(player);<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

This code above will cast the value of sender to player and pass that argument to the function togglePluginState(). But now we need to create our togglePluginState() function.

<nowiki><blockquote><source lang="java">public void togglePluginState(Player player) {</nowiki>

// Notice how we use the player name as the key here,

// not the player object

String playerName = player.getName();

if (pluginEnabled.containsKey(playerName)) {

if (pluginEnabled.get(playerName)) {

pluginEnabled.put(playerName, false);

player.sendMessage("Plugin disabled");

} else {

pluginEnabled.put(playerName, true);

player.sendMessage("Plugin enabled");

}

} else {

pluginEnabled.put(playerName, true); //If you want plugin disabled by default change this value to false.

player.sendMessage("Plugin enabled");

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Now, what this code is doing is checking if the HashMap first contains the key player, so if it has been put into the HashMap, if it is then we check the value of the HashMap key by get(player); if this is true then set value to false and send the player a message, else if the value is false then do the opposite, set the value to true and send a message again. But if the HashMap does not contain the key player then we can assume that this is their first run/use so we change the default value and add the player to the HashMap.

<nowiki>==== More Ideas for HashMaps ====</nowiki>

A HashMap (or really any kind of Map in Java) is an association. It allows quick and efficient lookup of some sort of <nowiki>'''value''', given a unique '''key'''</nowiki>. Anywhere this happens in your code, a Map may be your solution.

Here are a few other ideas which are ideally suited to using Maps. As you will see, it doesn't have to be data that you store per player, but can be any kind of data that needs to be "translated" from one form to another.

<nowiki>===== Data Value Lookups =====</nowiki>

<nowiki><blockquote><source lang="java"></nowiki>

public Map<String, Integer> wool_colors = new HashMap<>();

// Run this on plugin startup (ideally reading from a file instead of copied out row by row):

wool_colors.put("orange", 1);

wool_colors.put("magenta", 2);

wool_colors.put("light blue", 3);

..

wool_colors.put("black", 15);

// Run this in response to user commands - turn "green" into 13

int datavalue = 0;

if (wool_colors.containsKey(argument)) {

datavalue = wool_colors.get(argument);

} else {

try { datavalue = Integer.parseInt(argument); }

catch (Exception e) {}

}

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

<nowiki>==== Saving/Loading a HashMap ====</nowiki>

Once you know how to work with HashMaps, you probably want to know how to save and load the HashMap data. Saving and loading HashMap data is appropriate if

<nowiki>*</nowiki>you don't want an administrator to edit the data manually

<nowiki>*</nowiki>you need to save data in binary format (too complex to organize for YAML)

<nowiki>*</nowiki>you want to avoid parsing block names and/or other objects from freeform text

This is very simple way how to save any HashMap. You can replace HashMap&lt;String, Integer&gt; with any type of HashMap you want. Let's take an example HashMap with code to save it:

<nowiki><blockquote><source lang="java"></nowiki>

HashMap<String, Integer> mapToSave = new HashMap<String,Integer>();

public void save(HashMap<String, Integer> map, String path) {

try {

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(map);

oos.flush();

oos.close();

//Handle I/O exceptions

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

save(mapToSave, getDataFolder() + File.separator + "example.bin");<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can see it's really easy. Loading works very very similar but we use ObjectInputStream instead of ObjectOutputStream ,FileInputStream instead of FileOutputStream,readObject() instead of writeObject() and we return the HashMap.

<nowiki><blockquote><source lang="java">public HashMap<String, Integer> load(String path) {</nowiki>

try {

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

Object result = ois.readObject();

//you can feel free to cast result to HashMap<String, Integer> if you know there's that HashMap in the file

return (HashMap<String, Integer>)result;

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

HashMap<Integer, String> loadedMap;

String path = getDataFolder() + File.separator + "example.bin";

File file = new File(path);

if (file.exists()) { // check if file exists before loading to avoid errors!

loadedMap = load(path);

}<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can use this "API" for saving/loading HashMaps, ArrayLists, and all Objects which implement Serializable or Externalizable interface.

<nowiki><blockquote><source lang="java">/** SLAPI = Saving/Loading API</nowiki>

* API for Saving and Loading Objects.

* Everyone has permission to include this code in their plugins as they wish :)

* @author Tomsik68<tomsik68@gmail.com>

*/

public class SLAPI

{

public static <T extends Object> void save(T obj,String path) throws Exception

{

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(obj);

oos.flush();

oos.close();

}

public static <T extends Object> T load(String path) throws Exception

{

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

T result = (T)ois.readObject();

ois.close();

return result;

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Example implementation of this API: <nowiki>'''</nowiki>I'm skipping some part of code in this source<nowiki>'''</nowiki>

<nowiki><blockquote><source lang="java">public class Example extends JavaPlugin {</nowiki>

private ArrayList<Object> list = new ArrayList<>();

@Override

public void onEnable() {

try {

list = SLAPI.load("example.bin");

} catch(Exception e) {

//handle the exception

e.printStackTrace();

}

}

@Override

public void onDisable() {

try {

SLAPI.save(list,"example.bin");

} catch(Exception e) {

e.printStackTrace();

}

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Note #1: This will work un-modified with almost all well-known Java types like Integer, String, HashMap. It will also work for some Bukkit types as well. If you're writing your own data object classes, and you may want to save their state using this technique, you should read about Java's Serializable or Externalizable interface. The only difference between Externalizable and Serializable is, that Serializable automatically takes all of class's fields and tries to serialize them, while Externalizable allows you to define method for reading and writing the Object. It's easy to add to your code, and it will make your data persistent with very little work required. No more parsing!

Note #2: This API doesn't support changes. Once you change something in the class, data files saved with older version of your plugin won't load correctly.

<nowiki>===== Tips & Examples =====</nowiki>

1.) Simplify your save structure

Try to use as much simple types as possible. E.g. if you want to save player, save their UUID instead. If you want to save world, save its UUID. If you want to save location, save x,y,z world UUID. DO NOT DIRECTLY SAVE BUKKIT TYPES!

2.) Save version number along with data

You should always remember, that you don't know what you'll be saving in the same file tomorrow. Will you ever migrate this file because of newer version of your plugin, bukkit, or minecraft? You don't know!

3.) Migrate older files

If your plugin finds older version of some file, it should update the file accordingly and change version number.

<references />

== Metadata ==

Bukkit is trying to make plugin development as easy as possible, so HashMaps with key of type Player, Entity, World or even a Block were replaced by Metadata. Metadata is some kind of alternative to HashMap. It allows you to add custom "fields" to Players, Entities, Worlds and Blocks. These things are all members of Metadatable class(check [http://jd.bukkit.org/doxygen/de/d59/interfaceorg_1_1bukkit_1_1metadata_1_1MetadataValue.html#ab49975fe013a0626dd29d3b85c63a82f])It works very simply. Everything that is Metadatable holds its own HashMap of Metadata which you have access to. That means, for example, if you're creating an economy plugin, you would need a HashMap of Player and Float or Double. With Metadata, you don't have to! You just attach to player new metadata value, and that's it! 

=== Why to use Metadata ===

* Metadata is all handled by Bukkit, which makes it a very good alternative to HashMaps.
* Metadata can be used to share information between plugins.

=== Why not use Metadata ===

* Slightly more difficult to get the value.
* It is not saved on shutdown (but then again, neither are any Maps that you create).

=== Getting & Setting Metadata ===

<source lang="java">
public void setMetadata(Metadatable object, String key, Object value, Plugin plugin) {
object.setMetadata(key, new FixedMetadataValue(plugin,value));
}

public Object getMetadata(Metadatable object, String key, Plugin plugin) {
List<MetadataValue> values = object.getMetadata(key);
for (MetadataValue value : values) {
// Plugins are singleton objects, so using == is safe here
if (value.getOwningPlugin() == plugin) {
return value.value();
}
}
return null;
}</source>

Note: If you're manipulating with numbers, booleans or strings, use convenient method to get the result. For example, you can use asInt(), asString() or asBoolean() instead of value to find out the value.

== Databases ==

Sometimes flat files aren't enough for what your looking to do, this is where databases come in. The most common database engines available on Linux/Mac/Windows machines typically run on some flavor of SQL (Structured Query Language).

Software offering SQL allow you to create databases with columns and header to identify to contents of each cell. Think of it as a spreadsheet on steroids, where every column you set up in your database can enforce rules to ensure integrity. Apart from being more organised than a simple custom data file, SQL provides faster access and better searching than flat files.

The SQL standard helps applications like Bukkit implement database storage for their data in a consistent way. Unfortunately, there's more than one SQL-ready database engine, and each has minor differences in how to configure and use it. Which one you choose may depend on your particular needs. (Some plugins even offer configurable options to connect to multiple database engines!)

=== SQLite ===

Alta189 has written a [http://forums.bukkit.org/threads/lib-tut-mysql-sqlite-bukkit-drivers.33849/ fantastic SQLite tutorial] which I suggest you watch if you're interested in using SQL in your plugins, included with the tutorials is a handy library you can download and import to make using SQL easier. Once you have watched these video tutorials I would suggest you go and learn some SQL syntax, it's very straightforward and shouldn't take you long to pick up. SQL Tutorials [http://www.w3schools.com/sql/default.asp @W3Schools] and [http://www.1keydata.com/sql/sql.html @1Keydata].

SQLite is great for very simple databases, because there's no server concerns to set up. Just make a few calls to create a new database and table. It's easy to back up: just copy the whole database file in one go. SQLite is a little bit weaker at data integrity, flexibility in data types, and it may not be something you would want to trust for huge databases of millions of rows. But for a new plugin in development, it's often easiest and fastest to get the SQL basics squared away with SQLite, even if you "graduate" to a more server-class database engine later.

=== MySQL ===

Another popular SQL database engine is called MySQL. It is closer to server-grade than SQLite, where many popular companies or websites depend on it for millions of webpage hits every day. With that security comes a little bit steeper learning-curve, because MySQL has more tunable parameters and capabilities.

The coding for plugins accessing MySQL is mostly the same as tiny SQLite or mega-sized Oracle, with only small differences in syntax here or there. But the administration has room to grow. You may want to set up accounts and privileges inside your MySQL setup. You may want to set up SQL scripts that organize your backups and rollback to previous states.

== 部署你的插件 ==

总之你写好的你的插件,如何把它变成一个可安装在服务端的jar文件呢?

首先我们需要建立一个水桶服务器。 [http://wiki.bukkit.org/Setting_up_a_server 在这里] 能找到开服相关信息.接下来你需要把插件导出为一个.jar文件，

这样你就能在你的服务器里运行它。在Eclipse里, 右键工程，点击''Run as > Maven install''即可:

[[Image:Maveninstall.png]]

将来呢, 当你对插件进行了改动后,在做上述操作之前，如果你想删除之前的.jar文件，你可以右键工程，点击 ''Run as > Maven clean'' 。

如果你在编译插件时遇到了问题, 请检查你的JDK是否正确安装，并浏览[[建立工作区]]条目。

如果你在Eclipse控制台看到了和JDK有关的错误，你可能需要手动调整JDK,因为Eclipse的检测可能发生了错误。

点击''Window -> Preferences'', 然后是''Java -> Installed JREs''。选中你最近安装的JDK作为Java运行环境（JRE）并添加, 并取消掉原来那个报错的JDK:

[[Image:Jrelocation.png]]

如果你的工程成功被编译,JAR文件会生产在 ''target'' 目录下，具体在Eclipse的工作空间里名字为工程名的文件夹中。

这个JAR文件就是一个能正常工作的Bukkit插件了。当然前提是你的plugin.yml里没出差错。

你可以把这个jar文件丢到服务器的plugins文件夹里,重载或重启服务器,就可以测试你的新插件啦。

为了连接上使用你自己的电脑开的服务器 ,在多人游戏的ip里填上你的本地ip即可。

如果出现了错误而你又不能解决的话, 试试这里[http://forums.bukkit.org/forums/plugin-development.5/ plugin development forum],

在这里提问[http://wiki.bukkit.org/IRC bukkitdev IRC channel],或者重新阅读wiki。

当你做完了一个实用的插件,可以考虑把它发表在这里[http://dev.bukkit.org/ dev.bukkit]（为了Bukkit社区的访问量）。

以上可知,JAR格式是默认压缩生成的(JAR文件基于ZIP文件的格式)。这么说来，在上传插件到Bukkit上时把JAR文件压缩成ZIP只会增加文件体积罢了。

而且呢, 放在JAR中的config文件可以在检测不到插件目录（插件自动生成的文件夹，名字与插件名相同，里面是该插件的配置）下的config文件时自动生成。

所以我们一般不把jar文件转换成其他格式。

== 导入其它插件 ==
你可能会希望编辑其它那些有源代码的插件. 如果插件在它的目录下有''pom.xml''(大多数知名插件,例如WorldEdit和Essentials都有),你可以通过点击''File -> Import''来把它作为一个工程导入, 然后打开''Maven''项并选择''Existing Maven Projects'':

[[Image:Importmaven.png]]

然后选择''pom.xml''所在的目录,这个工程就应该出现在你的侧边栏里了。就像平常一样编辑并编译它吧。

== 小贴士 ==

=== 使玩家着火 ===

Bukkit API有很多碉堡的功能。以下是实现一些功能的代码片段。

下面的代码运行一个玩家使另一个玩家着火。通过类似于'''/ignite Notch'''这样的指令，这个指令会让 Notch 着火。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 使用 equalsIgnoreCase() 来忽视大小写
if (cmd.getName().equalsIgnoreCase("ignite")) {
// 确保玩家只输入了一个自变量(要被点着的玩家名).
if (args.length != 1) {
// 当return false时，该指令的使用信息会显示出来。
return false;
}

// 确保命令发出者是个玩家.
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can set other players on fire.");
sender.sendMessage("This is an arbitrary requirement for demonstration purposes only.");
return true;
}

// 获取那个要被点着的玩家. 请注意下标起始是0，不是1.
Player target = Bukkit.getServer().getPlayer(args[0]);

// 确保这个玩家在线。
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}

// 让这个玩家着火1000 ticks (一秒钟大概有20ticks,所以总共是50秒).
target.setFireTicks(1000);
return true;
}
return false;
}

=== 干掉玩家 ===

和标题一样.这里是要干掉某个玩家。

在你的onCommand方法里使用这个:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("KillPlayer")) {
Player target = sender.getServer().getPlayer(args[0]);
// 确保玩家在线.
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}
target.setHealth(0);
}
return false;
}

这里有个小扩展,会使用一个爆炸来杀死玩家:

float explosionPower = 4F; //爆炸等级 - TNT的爆炸等级默认是4F
Player target = sender.getWorld().getPlayer(args[0]);
target.getWorld().createExplosion(target.getLocation(), explosionPower);
target.setHealth(0);

=== 创造一个假爆炸 ===

这段代码会生产一个看起来和听起来与TNT/苦力怕产生的爆炸一样的效果。但是不会对实体和方块产生破坏。在保留爆炸的艺术的同时又削弱了爆炸的威力，真是太有用了（
@EventHandler
public void onExplosionPrime(ExplosionPrimeEvent event) {
Entity entity = event.getEntity();

// 如果事件和点燃的TNT有关,执行一些代码（又略）
if (entity instanceof TNTPrimed) {
entity.getWorld().createExplosion(entity.getLocation(), 0);
}
}

=== 使一个玩家对另外一个玩家隐形 ===

通过输入指令，能让指令执行者对特定的玩家隐形。然而其他人仍然能看到指令执行者。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("HideMe") && args.length == 1) {
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can use this command!");
return true;
}
// 检测指令执行者是玩家后，我们便可以安全的进行强制转换类操作。
Player s = (Player) sender;

// 获取命令执行者指定的玩家
Player target = Bukkit.getServer().getPlayer(args[0]);
if (target == null) {
sender.sendMessage("Player " + args[0] + " is not online.");
return true;
}
// 将 s 从 target 的视野中隐藏起来.
target.hidePlayer(s);
return true;
}
return false;
}

=== 在玩家准星所指处生产闪电 ===

如下代码运行手持鱼竿的玩家通过点击来生成闪电 (当然要用准星瞄准)。真是个简单好玩的恶作剧（。

@EventHandler
public void onPlayerInteractBlock(PlayerInteractEvent event) {
Player player = event.getPlayer();
if (player.getItemInHand().getType() == Material.FISHING_ROD) {
// 在给定坐标中生成一道闪电. 在本例中, 这个坐标是玩家准星瞄准的地方.
// 只能指向200格以内的坐标.
player.getWorld().strikeLightning(player.getTargetBlock(null, 200).getLocation());
}
}

=== 自动格式 ===

Eclipse提供了将你的代码自动转成Oracle规定的格式, 修正了不符合常规的缩进, 空格等等。在侧边栏选中你的项目,然后选择''Source -> Format''即可对其进行更改。

== 插件需求专区 ==

http://forums.bukkit.org/forums/plugin-requests.13/

== 范例文件和样板 ==

*[https://github.com/Bukkit/SamplePlugin/ Bukkit/SamplePlugin on GitHub]

*[http://pastebin.com/wpeTPx7N Example.Java]

*[http://pastebin.com/MTwaAVCT ExamplePlayerListener.Java]

*[http://pastebin.com/6FLixfH3 ExampleBlockListener.Java]

*[http://pastebin.com/8UZ6pkWC ExampleEntityListener.Java]

If you have any more questions on this matter, don't hesitate to visit the BukkitDev [[IRC]] channel and ask!

[[Category:教程]]
[[Category:大篇幅条目]]

Bukkit/插件开发教程

2015-08-31T02:23:13Z

Tdiant：/* 方块操控 */

{{模板:待翻译}}
{{模板:待完善}}
本页面英文原文内容来源 [http://wiki.bukkit.org/Plugin_Tutorial]
== 介绍 ==

这篇内容丰富的教程旨在帮助你学会如何开发Bukkit插件.这一篇教程不可能完全涉及到Bukkit中所有的可能性,而是最基本的一般概述. 前提是你懂得Java这门语言,并在IDE中设置好你的工作区,此教程介绍了大多数Bukkit插件所必需的语法结构.

== 学习Java ==

'''理解这些教程需要具备Java这门编程语言的基本知识.'''如果你刚开始学习Java或者需要重温一下相关知识，下面有一个并不完整的网站列表可供参考.

<big>[http://docs.oracle.com/javase/tutorial/ Oracle's Java Tutorials]</big> - 官方教程
*[http://www.java2s.com/Tutorial/Java/CatalogJava.htm Java2s.com] - 教程
*[http://www.javacoffeebreak.com/java101/java101.html Java 101] - 教程
*[http://math.hws.edu/javanotes/ JavaNotes] - 免费的在线教科书
*[http://thenewboston.org/list.php?cat=31 TheNewBoston] - 视频教程.

== 开发环境 ==

在编写一个插件前 (或学习Java前) 你需要配置一个开发者环境，这个包括但不限于安装IDE (Integrated Development Environment，集成开发环境)。接下来的教程中有关于Eclipse上IDE的操作指南。

:: ''更多信息，请参见 [[Bukkit/插件开发教程-建立工作区|建立工作区]]''

你'''必须'''下载'''Java'''开发者使用的Eclipse构建版本, '''不是''' '''Java EE'''开发者的版本。 Java EE 开发者的版本不包含此教程需要的Maven支持。

== 新建插件开发项目 ==
=== 创建一个新的项目 ===

在开始工作之前，你需要先在Eclipse中配置好工作区和文件. 打开Eclipse,然后依次点击''File -> New -> Project:''来创建一个新的项目.

[[Image:Newproject.png]]

现在,打开''Maven''文件夹, 然后选择''Maven Project''.点击next,之后在下一个菜单中选择''Create a simple project'', 再次点击''Next'':
如果你看不到''Maven''文件夹, 那么你需要[http://eclipse.org/m2e/download/ 下载m2eclipse]

[[Image:Newproject2.png]]

现在，你需要给你的组用户命名，就像下面这样:
* 如果你拥有一个域名，package则填写逆转的域名地址.
** 例如: i-am-a-bukkit-developer.com 你的package地址即是com.i_am_a_bukkit_developer [http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html source]
** 避免使用一个不属于你自己的域名.
* 没有域名? 这里有几种方法可供选择。
*# 在资源管理站点创建一个用户，比如GitHub或是sourceforge
*#* 对于使用GitHub的用户, 请参照[http://pages.github.com/ 这里的说明] 之后你将获得一个子域名,所以你的package地址是io.github.<username> 
*# 使用你的邮箱. 例如: <username>@gmail.com格式的邮箱应输入com.gmail.<username> 
*# 最不济的方法.：使用独特的组名命名方式，这应当是你最后的解决方法。

以下几个地址不能作为package中的地址前缀:
* org.bukkit
* net.bukkit
* com.bukkit
* net.minecraft

完成基础的组名以后，你需要在最后加上插件的名称. 在这里用 GitHub页面作为讲解的实例. 如果你创建了一个名为 ''TestPlugin''的插件，那么完整的组名是''io.github.<username>'', 你的工程名也是 ''TestPlugin''. 至于版本，默认即可，稍后可以修改。
完成向导:

[[Image:Newproject3.png]]

如果这是你首次使用Eclipse, 点击右上角的"X" 来关闭Welcome提示页面. 现在，你的窗口视图看起来就像下面的图片这样:

[[Image:Eclipsemain.png]]

点击工程名称右边的箭头来进行下一步，现在我们正式开始。
=== 添加Bukkit API ===

在开发插件之前，你需要添加 Bukkit API库文件到你的项目，作为一个dependency, 你也可以添加其他你想实用的API.

找到项目文件夹中部的''pom.xml''并双击进行编辑. 点击''pom.xml''中部的 tab,你将会看到下图所示内容:

[[Image:Pomeditor.png]]

如果你想使用Java 6以上版本的语言特性,你需要指定搭建项目的Java版本.复制并粘贴以下内容(设定项目只能使用Java 7及以下的版本)到 ''</project>''之前:

<code>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<nowiki><</nowiki>source>1.7</source>
<target>1.7</target>
</configuration>
</plugin>
</plugins>
</build>
</code>

你或许想使用其他版本,例如 <code>1.8</code> 使用Java 8. 请注意 [http://mcstats.org/global/ 根据MCStats数据统计], 大多数服主选择了Java 7, 所以使用Java 8会使许多服务器无法运行你的插件. 如果你使用Java 1.7的特性, Eclipse将会在报错代码"error"中建议你更改语言版本.同意即可.

在位于代码中段的''</project>''之前粘贴以下内容(这段代码告诉Eclipse关于Bukkit's repository的地址):

<code>
<repositories>
<repository>
<id>bukkit-repo</id>
<url>http://repo.bukkit.org/content/groups/public/</url>
</repository>
</repositories>
</code>

然后继续在 ''</project>''前粘贴以下内容 (这段代码告诉Eclipse搭建插件的Bukkit版本):

<code>
<dependencies>
<dependency>
<groupId>org.bukkit</groupId>
<artifactId>bukkit</artifactId>
<version>1.7.2-R0.3</version>
<type>jar</type>
<scope>provided</scope>
</dependency>
</dependencies>
</code>

你也可以修改这里的Bukkit版本.你可以在[http://repo.bukkit.org/content/groups/public/org/bukkit/bukkit/ here]这里通过查看 maven-metadata.xml文件下的版本列表来获取可用的服务端版本号.

当你完成上述步骤后,''pom.xml''中的内容应该是这样:

[[Image:Finishedpom.png]]

通过菜单 ''File -> Save''或者按住 <code>Ctrl + S</code> 来保存''pom.xml''文件 . 之后, 右键项目标题，然后依次选择 ''Maven -> Update Project''.

=== Bukkit Java文档 ===

如果你曾经使用过Eclipse和Java，你会知道当你将鼠标准心移至class或者 method中的代码部分时，一个含有相关文档内容的黄色小框会弹出来. 这就是（Java的）Java文档。

你可以[http://download.oracle.com/javase/6/docs/api/ Oracle website 在线获取]它.。Bukkit同样拥有文档，这些文档内容包含了关于API中method和class的有用描述。

你可以在[http://jd.bukkit.org/ 这]找到它 (Beta版的Java文档在[http://jd.bukkit.org/ 这]找, 新开发出来的Java文档在

[http://jd.bukkit.org/ 这]) 。为了在Eclipse里使用Java文档,这样的话当你的鼠标停留在Bukkit的class和method上时，

（Bukkit的）Java文档就会冒出来。
JavaDoc in spigot [https://hub.spigotmc.org/javadocs/bukkit/ Click Here]

首先右键在侧边栏里的"Maven Dependencies"下面的Bukkit jar,选择"Properties".选中窗口左边的''Javadoc Location'', 并粘贴如下网址

'''http://jd.bukkit.org/''' (或者上面的测试版/最新版 Java文档链接也好) 到"Javadoc URL"下面的输入框内. 就像这样:

[[Image:Bukkitjavadocs.png]]

点击 "Validate",然后再点击"OK"就完成了.现在Bukkit Javadocs已经连接到Bukkit提供的资源,同时你也可以通过Eclipse来获得帮助类文档信息了.

=== 创建一个包 ===

现在你需要创建一个包，它将储存所有我们需要使用的Java类文件. 右键展开''src/main/java''折叠并选择 ''New > Package'':

[[Image:Newpackage.png]]

包名的话，先写上你的组名，然后加个点，再写上你的小写Artifact ID。举例, 如果你的组名是''io.github.name''，你的artifact名是 ''TestPlugin''。

你的包名就应该是''io.github.name.testplugin''.

=== 创建插件的类文件 ===

既然我们已经建立好了我们的项目，我们接下来可以开始添加类文件以及制作插件了. 插件的主类指的是拓展(extends)JavaPlugin的类文件. 在你的插件中只能有一个类文件拓展JavaPlugin，无论直接还是间接. 先创建你的主类文件并保持名称与插件名一致是个很好的习惯.右键你之前新建的包,并选择  ''New > Class''.你将会创建一个新的类文件，就像下面这样

package {$GroupName}.{$ArtifactName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$ArtifactName} extends JavaPlugin {

}

警告：插件绝对不应该调用自己的构造函数并实例化

=== 创建plugin.yml ===

你已经创建了项目和主类，如果你想要Bukkit能够加载你的插件，你还必须创建 '''[[Plugin YAML|plugin.yml]]''' 文件. 这个文件包含有基础的插件信息，如果缺失这个文件，你的插件也将会失效. 此时你需要右键''src/main/resources''. 选择''New > File''. 命名为"'''plugin.yml'''" 并右键完成新文件的创建.Eclipse会打开默认的文本编辑窗口来显示'''plugin.yml'''文件中空白的内容并提供编辑. ''(Hint: 如果你想要使得你的工作空间更加规整，关闭文本编辑器并将'''plugin.yml''' 文件拖到主工作空间(拖到文件目录的右边) 之后你就可以在eclipse中编辑文件了.)''

有三个基础的内容需要在plugin.yml写明.
: name: 插件名称.
: main: [http://docs.oracle.com/javase/specs/jls/se7/html/jls-6.html#jls-6.7 插件主类的完整，合法名称] .
: version: 插件当前版本号.

最简单的 '''plugin.yml''' 文件内就像这样 :

name: {插件名称}
main: {包名}.{主类}
version: {版本号}

PS:插件的包名经常会包括插件的名称，所以看到这个的时候不要感到惊讶。
你的主类是否是你的插件名取决于你之前的命名方式，时刻记住这一点很重要。

'''''更多例子''', 请看[[#Example_Files_and_Templates]]''

此时你的插件已经可以被Bukkit加载了,同时服务端日志也会开始记录你的插件. 不过它现在什么用都没有!

== onEnable()和onDisable()方法 ==

这些方法将在插件启用与卸载时生效. 默认情况下，你的插件在被加载时会调用这些方法，所以你可以在这里注册你需要用到的事件和提供一些调试信息. <code>onEnable()</code> 方法会在插件启用时被调用, 需要包含初始化插件的逻辑语句. <code>onDisable()</code> 方法会在插件卸载时被调用，需要包含清理(clean up)插件的逻辑语句和连接声明(associated state)。此外，插件可以重写 <code>onLoad()</code> 方法来在插件载入时执行附加的逻辑语句。

=== onEnable()和onDisable()方法介绍 ===

在前面的章节中，我们在主类创建了<code>onEnable()</code> 和 <code>onDisable()</code> 方法. 此时，这些代码看起来就像下面这样

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
// 插件载入时要执行的代码（略）
}

@Override
public void onDisable() {
// 插件卸载时要执行的代码（略）
}
}

这些方法已经创建，但目前它们还没有任何作用.
注意: 不需要添加代码来实现输出信息"{$PluginName} has been enabled!" ，因为bukkit会自动输出此类信息
有关更多事件的信息请查看 [[Event_API_Reference|这里]].

=== 发送提示信息 ===

插件能够输出信息至控制台与服务器日志。这是通过调用插件记录器里正确的方法来实现的。首先我们必须调用 <code>getLogger()</code> 方法来检索该插件的记录器，

然后我们就可以开始记录信息了。

我们通过调用<code>onEnable()</code>方法可以实现输出信息。我们需要在<code>onEnable()</code>方法下面插入如下代码：

getLogger().info("onEnable has been invoked!");

在 <code>'''onDisable()'''</code>方法里面，你也可以做类似的事情，不过要改改输出信息。

此时你的主类文件就像这样:

package {$TopLevelDomain}.{$Domain}.{$PluginName};

import org.bukkit.plugin.java.JavaPlugin;

public final class {$PluginName} extends JavaPlugin {
@Override
public void onEnable() {
getLogger().info("onEnable has been invoked!");
}

@Override
public void onDisable() {
getLogger().info("onDisable has been invoked!");
}
}

=== 防止重载后插件失效 ===

你需要知道的是，插件并不只会伴随服务器关闭、启动而重载，你的插件也可能会被其他插件启用、关闭，或是在服务器运行时使用/reload命令.
假设服务器启动之后一会儿后，你的插件才被启用，这时便是危险的,因为服务器中可能已经有玩家在线、额外的世界被加载以及很多预想不到的不同之处(与"插件同服务器同时加载"的情况相比较).

举个例子来说:
* 你有一个用来储存HashMap中的玩家登入信息的插件
* 你希望该信息对所有玩家都可见
* 一名管理员使用/reload命令
* 你的插件被卸载，所有储存的数据都丢失了
* 你的插件被再次启用时，一些玩家已经在线
* 这些玩家在HashMap并没有储存的信息
* 你试图重新获得他们的信息，但是失败了!

为了插件重载以后能够正常工作, 你需要在插件启用时加载所有已经在线的玩家的信息并将之储存在HashMap中.

for (Player player : Bukkit.getServer().getOnlinePlayers()) {
playerList.put(player.getName(), playerData(player));
}

== 监听器 ==
监听器是一种方法被调用来对事件作出反应的类.所有的监听器使用 org.bukkit.event.Listener接口.更多有关监听器创建的细节,
:: '' 请查看: [[Event API Reference]]''

== 指令 ==

=== onCommand() 方法 ===

现在你已经知道如何注册一个事件并做出响应,但是如果你只是想要在命令输入之后做出响应呢? 你可以使用 <code>'''onCommand'''</code>方法.

这个代码的作用是当玩家输入“/”时，监听该操作并执行相关语句"/" . 举个例子来说.输入 "/do something" 将会执行 <code>'''onCommand'''</code>方法.

此种情况下，因为没有特定的行为被编程，所以并不会发生任何事情。

请避免使用和bukkit所提供的指令重名的指令, 然后深思你的指令名的唯一性。

例如.指令"give"已经被好几个插件使用了, 如果你执行了另外一个"give"指令, 你的插件将会和这些插件冲突。

你必须在插件的"plugins.yml"注册你的指令否则这个方法将不会被触发。

<code>'''onCommand'''</code>方法必须返回一个布尔值（true或false）。

如果返回值是true，你不会看到什么明显的事情发生。

但如果返回值是false，则会返回你的plugin.yml里的'usage:property'然后发送给命令使用者.

当使用 <code>'''onCommand'''</code>方法时, 你需要填写4个参数.

*<code>'''CommandSender sender'''</code> - 发送命令的对象

*<code>'''Command cmd'''</code> - 被执行的指令

*<code>'''String commandLabel'''</code> - 被执行指令的别名

*<code>'''String[] args'''</code> - 该指令的自变量数组。

例如.指令 ''/hello abc def'' 中， ''abc'' 会被存放进args[0]中, ''def'' 被存放进args[1]中。

==== 设置命令 ====
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { // 如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} //如果以上内容成功执行，则返回true
// 如果执行失败，则返回false.
return false;
}

每当使用<code>'''onCommand'''</code>方法时，在每个方法后面都加上一个 return false; 是一个惯例。

返回false会显示在plugin.yml里设置的usage信息 (看下面). 用这种方法的话，一旦执行出错便会显示usage信息。

每当方法return一个值的时候，这个方法就会退出，所以return true的时候，在它下面的代码就会被跳过,

除非return语句在一个if的嵌套中，或者类似的嵌套情况。

<code>'''.equalsIgnoreCase("basic")'''</code>代表忽略英文大小写. 在这种情况下,字符串"BAsIc" 和 "BasiC"和 basic相同，代码会被照常执行。

和以前一样，加两行import在你的java文件头

import org.bukkit.command.Command;

import org.bukkit.command.CommandSender;

=== 在Plugin.yml中添加你的指令 ===

你需要添加你的指令到 '''plugin.yml''' 文件里. 如下是指令/basic添加到 '''plugin.yml'''的例子（请在plugins.yml的末尾添加如下代码）:

commands:
basic:
description: This is a demo command.
usage: /<command> [player]
permission: <plugin name>.basic
permission-message: You don't have <permission></source> </code> </blockquote>

*<code>'''basic'''</code> - 指令名称

*<code>'''description'''</code> - 指令描述

*<code>'''usage'''</code> - 在oncommand方法return false后显示的用法提示。尽量简洁, 使别人能够理解指令是什么以及如何使用它。

*<code>'''permission'''</code> - 被一些显示帮助信息的插件使用，用来决定向玩家显示哪个指令（完全不对劲吧！）。

*<code>'''permission-message'''</code> - 当玩家使用了这个指令而没有权限时输出的信息。

PS:yml文件使用两个空格作为制表符,使用tab键输入制表符会导致错误。

===控制台指令vs玩家指令===

你可能注意到了上文的<code>'''CommandSender sender'''</code>参数. <code>'''CommandSender'''</code> 是个Bukkit接口，

它有两个（对插件编写者）有用的子类：<code>'''Player'''</code> 和 <code>'''ConsoleCommandSender'''</code>.

所以当你编写插件的时候, 确定这个指令从控制台发出后能完全正常工作是十分必要的,

那些只能由在线玩家执行的指令 ''只能'' 由一个在线玩家执行。

有的插件在判断命令执行对象不是玩家时仅仅用return进行处理 (比如当有人从控制台发出指令),

即便这些指令能够在控制台完美运行（比如改变天气的指令）。

一个判断sender的方法:
@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("basic")) { //如果玩家输入了/basic则执行如下内容...
// 所需要执行的事（此处略）
return true;
} else if (cmd.getName().equalsIgnoreCase("basic2")) {
if (!(sender instanceof Player)) { //如果sender与Player类不匹配
sender.sendMessage("This command can only be run by a player.");
} else {
Player player = (Player) sender;
// 所需要执行的事（此处略）
}
return true;
}
return false;
}

在这个例子里，指令'''basic'''能由任何人发出 - 一个在线的玩家, 或者服务器后台的op.

但是指令'''basic2'''只能由一个在线的玩家发出.

大体上说,你应该允许尽可能多的指令在控制台和玩家聊天框里都正常执行.

需要在线玩家执行的指令可以使用以上例子中的机制来检测<code>'''CommandSender'''</code>是一个玩家.

很多指令广泛依靠于一些玩家的属性（例如可以被tp或被给予物品等等）。

如果你想更进一步, 你可以对你的指令的自变量做一些额外的检测，例如传送指令在提供玩家ID的情况下（也只有在这种情况下）可以在控制台被执行。

=== 使用独立的 CommandExecutor class ===

以上的例子必须把 <code>'''onCommand()'''</code> 方法放在插件的主类里。

对于小插件来说，这是极好的,但如果你要写一个大点的插件,把你的 <code>'''onCommand()'''</code>方法放在独立的类里将会很有意义。

幸运的是，这并不难:

*在你的包里创建一个新类. 命名为'''MyPluginCommandExecutor'''之类的 (当然，要把'''MyPlugin'''替换成你制作的插件的名字)。这个类 '''必须''' 继承Bukkit 的'''CommandExecutor'''接口。

*在你的插件的<code>'''onEnable()'''</code>方法中,你需要实例化你创建的命令执行类(CommandExecutor class), 然后做一个像下面一样的调用：<code>getCommand("basic").setExecutor(myExecutor);</code>
其中"basic"是我们需要操控的指令, <code>myExecutor</code> 是我们创建的实例.

废话少说直接吔我例子:

'''MyPlugin.java''' (插件的主类):
@Override
public void onEnable() {
// 如果你没有在plugins.yml注册过指令的话，此处会抛出空指针异常！
this.getCommand("basic").setExecutor(new MyPluginCommandExecutor(this));
}

'''MyPluginCommandExecutor.java'''（独立CommandExecutor类）:
public class MyPluginCommandExecutor implements CommandExecutor {
private final MyPlugin plugin;

public MyPluginCommandExecutor(MyPlugin plugin) {
this.plugin = plugin; // Store the plugin in situations where you need it.
}

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 和以前一样执行就好…
}
}

请注意我们是如何把主类里的对象指向'''MyPluginCommandExecutor'''的. 这允许我们轻易的使用主类对象的方法（如果我们需要的话）。

这么做的话, 我们便能更好的组织代码 - 如果 <code>'''onCommand()'''</code> 方法又大又复杂, 它就能被划分为子类，从而不使插件的主类显得凌乱。

PS：如果你的插件含有多个指令的话, 你需要为每一个指令单独设立一个commandexecutor.

=== 写一个安全的指令 ===
当写一个指令的时候,别进行任何假设（很重要）, 例如假设执行者一定是个玩家. 请牢记以下原则:

==== 在命令执行前确定发出者是玩家 ====

使用简单的例子来进行检测:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (sender instanceof Player) {
Player player = (Player) sender;
// do something
} else {
sender.sendMessage("You must be a player!");
return false;
}
// do something
return false;
}

==== 检测自变量个数 ====

别老是认为玩家都能打对正确数量的自变量.

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (args.length > 4) {
sender.sendMessage("Too many arguments!");
return false;
}
if (args.length < 2) {
sender.sendMessage("Not enough arguments!");
return false;
}
}

==== 在获取玩家之前先检测他们是否在线 ====

有时你想通过命令发出者打出的ID来获取其他玩家，请确保他们在线再说！

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
Player target = (Bukkit.getServer().getPlayer(args[0]));
if (target == null) {
sender.sendMessage(args[0] + " is not online!");
return false;
}
return false;
}

如果你想对离线玩家进行操作，<code>'''OfflinePlayer'''</code>类提供了基础操作的方法.

== 插件的配置/设置 ==
Bukkit API 为插件提供了一种简便的方法，用来管理用户自定义的设置。同时，通过这种方法也可以储存数据。
:: ''详情请查看: [[Configuration API Reference]]''

== 权限 ==

利用新的Bukkit API来设置权限是再容易不过的事情. 检测玩家是否拥有权限，可以使用以下代码:
<blockquote><source lang="java">if (player.hasPermission("some.pointless.permission")) {
//执行此段代码(有权限)
} else {
//执行此段代码(无权限)
}</source> </blockquote>
你也可以检测一个权限节点是否被定义过，(等效于 Java 语言中的'''null''')，使用下面的方法:
<blockquote><source lang="java">boolean isPermissionSet(String name)</source></blockquote>
你或许对此抱有疑惑:为什么这段代码中没有任何用户群的信息？因为它们并不是必需的. 之前这段代码想要实现的主要功能之一就是根据用户群格式化聊天信息. 但其实使用权限就可以很容易地完成这项工作.你可以在聊天插件的配置文件中定义权限与前缀的对应关系. 举例来说，"someChat.prefix.admin" 权限可以对应前缀[Admin].当拥有此权限的玩家发出聊天信息时，聊天前缀便是[Admin].

另一个想要实现的主要功能则是给所有拥有权限的在线用户发一条信息.你可以这样做:
<blockquote><source lang="java">for (Player player: Bukkit.getServer().getOnlinePlayers()) {
if (player.hasPermission("send.receive.message")) {
player.sendMessage("You were sent a message");
}
}</source> </blockquote>
看到这里你可能会问，若是没有权限组我该如何配置玩家的 [[权限]] ？既然 [[Bukkit]] API 本身并没有提供用户组的预设, 你必须通过安装一款权限组插件，像 [[permissionsBukkit]] 这样的插件来帮助你配置用户群. '''API 只是提供接口而不是提供implementation.'''

=== 配置权限 ===
{{Hide|标题=译者注 |内容= 其一，以下代码中部分内容将以''//文字''翻译，使用时请不要加入其中内容，仅做教程中的翻译参考；
其二，default:true在下面翻译为全员默认拥有该权限，default:false则翻译为全员默认没有该权限，请注意理解。 }}
如果你想要更多地控制你的权限，例如设置权限的默认值或是子权限节点，不如将权限节点加入你的 ''[[plugin.yml]]''文件.这并不是必须的，但我们推荐你这样做. 下面是一个实例，显示了当你将权限添加在''plugin.yml''文件末尾时的样子:
<blockquote><code><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //给予使用doorman所有命令的权限
children: //子权限节点
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false
doorman.kick:
description: Allows you to kick a user //允许你踢出一名用户
default: op //OP默认拥有该权限
doorman.ban:
description: Allows you to ban a user //允许你封禁一名用户
default: op //OP默认拥有该权限
doorman.knock:
description: Knocks on the door! //敲门
default: true //全员默认拥有该权限
doorman.denied:
description: Prevents this user from entering the door //禁止拥有该权限节点的用户进入门内</source> </code> </blockquote>
值得注意的是,你的插件使用的每个权限都被定义为 ''permissions'' 这个节点的子权限节点. 每个权限都能够拥有一个描述，默认值以及子权限节点。
==== 默认值 ====

当一个权限没有明确是否为玩家所拥有 ，''hasPermission''<ref>这是一个检测玩家是否拥有指定权限节点的方法</ref> 将返回false<ref>该方法返回的boolean值</ref>. 在你的[[plugin.yml]] you can change this by setting the default node to be one of four values:

*'''true''' - 全员默认拥有该权限.
*'''false''' - 全员默认没有该权限.
*'''op''' - 如果玩家是一名OP<ref>Operator，服务器管理员</ref>，那么他将拥有该权限.
*'''not op''' - 如果玩家不是一名OP，那么他将拥有该权限.

==== 子权限 ====

在这之前你可能已经习惯了通过权限节点自动分配所有的子权限<ref>原句:Before now you will probably be used to the * permission to automatically assign all sub permissions.此处的sub permissions应是同上文“你的插件使用的每个权限都被定义为 permissions 这个节点的子权限节点.”相照应</ref>. 现在这种方法已经随着bukkit API<ref>应用程序编程接口(Application Programming Interface)</ref>的更新而改变，现在你可以自己定义子权限了. 这将使得插件具有更多的灵活性. 下面是一个例子:
<blockquote><source lang="yaml">permissions:
doorman.*:
description: Gives access to all doorman commands //翻译见上
children:
doorman.kick: true
doorman.ban: true
doorman.knock: true
doorman.denied: false</source> </blockquote>
在这里，''doorman.*'' 权限拥有几个子权限并分配在其下. 子权限工作的方式就是当''doorman.*'' 权限节点被设置为true时,子权限也会随之设置为 ''plugin.yml''中的默认值. 然而当''doorman.*'' 被设置为false时，所有子权限都会设置为与默认值相反的值（true->false,false->true）.
<references />

=== 设置你自己的权限 ===

如果你希望想知道更多有关开发你自己的权限插件的事情(即是设置权限的管理类插件) ，那么请前往查看教程 [[Developing a permissions plugin]].

== Scheduling Tasks and Background Tasks ==

Currently, Minecraft servers operate nearly all of the game logic in one thread, so each individual task that happens in the game needs to be kept very short. A complicated piece of code in your plugin has the potential to cause huge delays and lag spikes to the game logic, if not handled properly.

Luckily, Bukkit has support for scheduling code in your plugin. You can submit a Runnable task to occur once in the future, or on a recurring basis, or you can spin off a whole new independent thread that can perform lengthy tasks in parallel with the game logic.

There is a separate [[Scheduler Programming]] tutorial which introduces the Scheduler, and gives more information on using it to schedule synchronous tasks, and on kicking off asynchronous tasks in Bukkit.

== 方块操控 ==

这是一个很容易的方法创建、获取或修改一个方块, 例如当你想要修改往你头上数第五格的方块时, 首先你需要做的是获取你当前的坐标点, 然后往你当前的坐标点的Y轴加上五, 获取目标方块后我们便能够很容易地修改它了, 例子如下:
<blockquote><source lang="java">
@EventHandler
public void onPlayerMove(PlayerMoveEvent event) {
// 得到玩家当前的坐标.
Location loc = event.getPlayer().getLocation();
// 设置目标坐标为玩家头顶 5 格处.
loc.setY(loc.getY() + 5);
// 得到目标坐标的方块
Block b = loc.getBlock();
// 将目标坐标的方块更改为石头 (stone).
b.setType(Material.STONE);
}</source> </blockquote>
上面的代码获取了玩家的所在位置，获取头上的第五个方块，并且放上一个石头（stone）。 Note that once you have a <code>Block</code>, there are other things you can do besides set its type. 你可以查阅JavaDoc获取更多的东西。

你可以用这样相似的观念去生成一些建筑，并且还可以用编程的方式通过算法生成一些独特的方块（这里指由很多个方块拼在一起的四四方方的方块）。比如，去生成一个实心的方块建筑，你可能在生成建筑的时候还需要用到<code>for</code>循环，去一遍遍循环来生成这些建筑，填满这些建筑等。
下面，是一个在指定坐标生成一个实心的方块建筑的实例方法：
<blockquote><source lang="java">
public void generateCube(Location loc, int length) {
// 放置这个方块最中间的方块并且获取这个方块的坐标。
// Uses getBlockN() instead of getN() to avoid casting to an int later.
int x1 = loc.getBlockX();
int y1 = loc.getBlockY();
int z1 = loc.getBlockZ();

// Figure out the opposite corner of the cube by taking the corner and adding length to all coordinates.
int x2 = x1 + length;
int y2 = y1 + length;
int z2 = z1 + length;

World world = loc.getWorld();

// Loop over the cube in the x dimension.
for (int xPoint = x1; xPoint <= x2; xPoint++) {
// Loop over the cube in the y dimension.
for (int yPoint = y1; yPoint <= y2; yPoint++) {
// Loop over the cube in the z dimension.
for (int zPoint = z1; zPoint <= z2; zPoint++) {
// Get the block that we are currently looping over.
Block currentBlock = world.getBlockAt(xPoint, yPoint, zPoint);
// 设置方块ID为57号(钻石块!)
currentBlock.setType(Material.DIAMOND_BLOCK); //这里下面会提到
}
}
}
}</source></blockquote>
这个方法将会在程序给予这个方法高度和起始坐标（最中间的方块的坐标）时，构建一个3D的方块建筑。简单的删除方块也可以使用这个方法的思路实现，但是，但是设置方块的时候，记得把上面标注会提到的那行，设置为物品ID为0的方块(空气方块)。 
<blockquote></blockquote>

== (Player) Inventory Manipulation ==

This section mostly covers player inventory manipulation, but the same applies to chest inventory manipulation as well if you find out how to get a chest's inventory :P. Here is a simple example of inventory manipulation:
<blockquote><source lang="java">public void onPlayerJoin(PlayerJoinEvent evt) {
Player player = evt.getPlayer(); // 当玩家加入游戏
PlayerInventory inventory = player.getInventory(); // 获取玩家背包列表
ItemStack itemstack = new ItemStack(Material.DIAMOND, 64); // 生成一组钻石

if (inventory.contains(itemstack)) {
inventory.addItem(itemstack); // 将一组钻石放到玩家的背包里
player.sendMessage("Welcome! You seem to be reeeally rich, so we gave you some more diamonds!"); //向玩家发送消息("你看起来很有钱的样子....balabala")
}
}</source> </blockquote>
So inside onPlayerJoin we first make a few variables to make our job easier: player, inventory and itemstack. Inventory is the player's inventory and itemstack is a ItemStack that has 64 diamonds. After that we check if the player's inventory contains a stack of diamonds. If the player has a stack of diamonds, we give him/her another stack with inventory.addItem(itemstack) and send a message. So inventory manipulation isn't actually that hard, if we wanted we could remove the stack of diamonds by simply replacing inventory.addItem(itemstack) with inventory.remove(itemstack) and change the message a little bit. Hopefully this helped!

== Item Manipulation ==

When dealing with items in the code, you use the ItemStack class for looking up and setting all information on that stack.

=== Enchantments ===

To enchant an item you must first know the [http://www.minecraftwiki.net/wiki/Data_values Item Code] and the [http://www.minecraftwiki.net/wiki/Talk:Enchanting#Effect_IDs Effect ID]. Enchantments themselves cannot be instantiated (new Enchantment() won't work) because they're abstract, so you must use an EnchantmentWrapper. If you want to enchant items that can't be enchanted inside normal SMP, use addUnsafeEnchantment() instead of addEnchantment()

<source lang="java">
int itemCode = 280; //use the item code you want here
int effectId = 20; //use the enchantment code you want here
int enchantmentLevel = 100;

ItemStack myItem = new ItemStack(itemCode); //new item of item code
Enchantment myEnchantment = new EnchantmentWrapper(effectId); //new enchantment of effect id
myItem.addEnchantment(myEnchantment, enchantmentLevel); //enchant the item
</source>

=== ItemMeta ===
You can set the display name of an item by doing this.
<source lang="java">
String myDisplayName = "Awesome Sword"; //这里是保存了你想要显示的名字

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //你要更改的方块
ItemMeta im = myItem.getItemMeta(); //得到方块的元数据
im.setDisplayName(myDisplayName); //设置它显示的名字
myItem.setItemMeta(im); //保存更改
</source>
You can also set the lores of an item. The lores are the small annotations on an item, like "+5 attack damage" on a stone sword.
<source lang="java">
List<String> lores = new ArrayList<String>();
lores.add("Example lore", "this one comes on line 2");

ItemStack myItem = new ItemStack(Material.DIAMOND_SWORD); //your item
ItemMeta im = myItem.getItemMeta(); //get the itemmeta of the item again
im.setLore(lores); //add the lores of course
myItem.setItemMeta(im); //give the item the new itemmeta
</source>

== Maps, and Sets, and Lists, Oh My! <ref>标题中Map,Set,List均为Java类集中的接口，故不翻译</ref> ==

除了Map类和HashMap类，Java中还提供了其它的数据结构类集。

他们提供这些不同的类，是因为有些时候，使用Map类并不合适。<nowiki>[[Java data structure classes]]</nowiki>在这个条目中，有对Java数据框架类集更深入的讲述。

<nowiki>=== HashMaps概览以及如何使用此接口 ===</nowiki>

<nowiki><big></nowiki>

<nowiki>'''</nowiki>Keep in mind to never use a player in a hashmap!<nowiki>'''</nowiki><ref>下面有讲解。</ref>

应在HashMap中使用字符串.，使用 "p.getName()" 来添加，移除或是检查列表中是否含有某个玩家.

将玩家当作object储存在HashMap中会造成大量内存泄漏.

<nowiki></big></nowiki>

When making a plugin you will get to a point where just using single variables to state an event has happened or a condition has been met will be insufficient, due to more than one player performing that action/event.

This was the problem I had with one of my old plugins, Zones, now improved and re-named to Regions. I was getting most of these errors because I didn't consider how the plugin would behave on an actual server with more than one on at any given time. I was using a single boolean variable to check whether players were in the region or not and obviously this wouldn't work as the values for each individual player need to be separate. So if one player was in a region and one was out the variable would constantly be changing which could/would/did cause numerous errors.

A HashMap is an excellent way of doing this. A HashMap is a way of mapping/assigning a value to a key. You could set up the HashMap so that the key is a player and the value could be anything you want, however the useful things with HashMaps is that one key can only contain one value and there can be no duplicate keys. So say for example I put "adam" as the key and assigned a value of "a" to it. That would work as intended, but then say afterwards I wanted to assign the value of "b" to key "adam" I would be able to and would get no errors but the value of "a" assigned to key "adam" in the HashMap would be overwritten because HashMaps cannot contain duplicate values.

<nowiki>==== Defining a HashMap ====</nowiki>

<nowiki><blockquote><source lang="java">public Map<KeyType, DataType> HashMapName = new HashMap<>(); //Example syntax</nowiki>

// Example Declaration

public Map<String, Boolean> pluginEnabled = new HashMap<>();

public Map<String, Boolean> isGodMode = new HashMap<>();

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Keep that code in mind because we will be using it for the rest of the tutorial on HashMaps. So, for example lets create a simple function which will toggle whether the plugin has been enabled or not. Firstly, inside your on command function which I explained earlier you will need to create a function to send the player name to the function and adjust the players state accordingly.

So inside on command you'll need this, the function name can be different but for the sake of simplicity it's best if you keep it the same.

<nowiki><blockquote><source lang="java">Player player = (Player) sender;</nowiki>

togglePluginState(player);<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

This code above will cast the value of sender to player and pass that argument to the function togglePluginState(). But now we need to create our togglePluginState() function.

<nowiki><blockquote><source lang="java">public void togglePluginState(Player player) {</nowiki>

// Notice how we use the player name as the key here,

// not the player object

String playerName = player.getName();

if (pluginEnabled.containsKey(playerName)) {

if (pluginEnabled.get(playerName)) {

pluginEnabled.put(playerName, false);

player.sendMessage("Plugin disabled");

} else {

pluginEnabled.put(playerName, true);

player.sendMessage("Plugin enabled");

}

} else {

pluginEnabled.put(playerName, true); //If you want plugin disabled by default change this value to false.

player.sendMessage("Plugin enabled");

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Now, what this code is doing is checking if the HashMap first contains the key player, so if it has been put into the HashMap, if it is then we check the value of the HashMap key by get(player); if this is true then set value to false and send the player a message, else if the value is false then do the opposite, set the value to true and send a message again. But if the HashMap does not contain the key player then we can assume that this is their first run/use so we change the default value and add the player to the HashMap.

<nowiki>==== More Ideas for HashMaps ====</nowiki>

A HashMap (or really any kind of Map in Java) is an association. It allows quick and efficient lookup of some sort of <nowiki>'''value''', given a unique '''key'''</nowiki>. Anywhere this happens in your code, a Map may be your solution.

Here are a few other ideas which are ideally suited to using Maps. As you will see, it doesn't have to be data that you store per player, but can be any kind of data that needs to be "translated" from one form to another.

<nowiki>===== Data Value Lookups =====</nowiki>

<nowiki><blockquote><source lang="java"></nowiki>

public Map<String, Integer> wool_colors = new HashMap<>();

// Run this on plugin startup (ideally reading from a file instead of copied out row by row):

wool_colors.put("orange", 1);

wool_colors.put("magenta", 2);

wool_colors.put("light blue", 3);

..

wool_colors.put("black", 15);

// Run this in response to user commands - turn "green" into 13

int datavalue = 0;

if (wool_colors.containsKey(argument)) {

datavalue = wool_colors.get(argument);

} else {

try { datavalue = Integer.parseInt(argument); }

catch (Exception e) {}

}

<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

<nowiki>==== Saving/Loading a HashMap ====</nowiki>

Once you know how to work with HashMaps, you probably want to know how to save and load the HashMap data. Saving and loading HashMap data is appropriate if

<nowiki>*</nowiki>you don't want an administrator to edit the data manually

<nowiki>*</nowiki>you need to save data in binary format (too complex to organize for YAML)

<nowiki>*</nowiki>you want to avoid parsing block names and/or other objects from freeform text

This is very simple way how to save any HashMap. You can replace HashMap&lt;String, Integer&gt; with any type of HashMap you want. Let's take an example HashMap with code to save it:

<nowiki><blockquote><source lang="java"></nowiki>

HashMap<String, Integer> mapToSave = new HashMap<String,Integer>();

public void save(HashMap<String, Integer> map, String path) {

try {

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(map);

oos.flush();

oos.close();

//Handle I/O exceptions

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

save(mapToSave, getDataFolder() + File.separator + "example.bin");<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can see it's really easy. Loading works very very similar but we use ObjectInputStream instead of ObjectOutputStream ,FileInputStream instead of FileOutputStream,readObject() instead of writeObject() and we return the HashMap.

<nowiki><blockquote><source lang="java">public HashMap<String, Integer> load(String path) {</nowiki>

try {

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

Object result = ois.readObject();

//you can feel free to cast result to HashMap<String, Integer> if you know there's that HashMap in the file

return (HashMap<String, Integer>)result;

} catch(Exception e) {

e.printStackTrace();

}

}

// ...

HashMap<Integer, String> loadedMap;

String path = getDataFolder() + File.separator + "example.bin";

File file = new File(path);

if (file.exists()) { // check if file exists before loading to avoid errors!

loadedMap = load(path);

}<nowiki></source></nowiki><nowiki></blockquote></nowiki>

You can use this "API" for saving/loading HashMaps, ArrayLists, and all Objects which implement Serializable or Externalizable interface.

<nowiki><blockquote><source lang="java">/** SLAPI = Saving/Loading API</nowiki>

* API for Saving and Loading Objects.

* Everyone has permission to include this code in their plugins as they wish :)

* @author Tomsik68<tomsik68@gmail.com>

*/

public class SLAPI

{

public static <T extends Object> void save(T obj,String path) throws Exception

{

ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(path));

oos.writeObject(obj);

oos.flush();

oos.close();

}

public static <T extends Object> T load(String path) throws Exception

{

ObjectInputStream ois = new ObjectInputStream(new FileInputStream(path));

T result = (T)ois.readObject();

ois.close();

return result;

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Example implementation of this API: <nowiki>'''</nowiki>I'm skipping some part of code in this source<nowiki>'''</nowiki>

<nowiki><blockquote><source lang="java">public class Example extends JavaPlugin {</nowiki>

private ArrayList<Object> list = new ArrayList<>();

@Override

public void onEnable() {

try {

list = SLAPI.load("example.bin");

} catch(Exception e) {

//handle the exception

e.printStackTrace();

}

}

@Override

public void onDisable() {

try {

SLAPI.save(list,"example.bin");

} catch(Exception e) {

e.printStackTrace();

}

}

}<nowiki></source></nowiki> <nowiki></blockquote></nowiki>

Note #1: This will work un-modified with almost all well-known Java types like Integer, String, HashMap. It will also work for some Bukkit types as well. If you're writing your own data object classes, and you may want to save their state using this technique, you should read about Java's Serializable or Externalizable interface. The only difference between Externalizable and Serializable is, that Serializable automatically takes all of class's fields and tries to serialize them, while Externalizable allows you to define method for reading and writing the Object. It's easy to add to your code, and it will make your data persistent with very little work required. No more parsing!

Note #2: This API doesn't support changes. Once you change something in the class, data files saved with older version of your plugin won't load correctly.

<nowiki>===== Tips & Examples =====</nowiki>

1.) Simplify your save structure

Try to use as much simple types as possible. E.g. if you want to save player, save their UUID instead. If you want to save world, save its UUID. If you want to save location, save x,y,z world UUID. DO NOT DIRECTLY SAVE BUKKIT TYPES!

2.) Save version number along with data

You should always remember, that you don't know what you'll be saving in the same file tomorrow. Will you ever migrate this file because of newer version of your plugin, bukkit, or minecraft? You don't know!

3.) Migrate older files

If your plugin finds older version of some file, it should update the file accordingly and change version number.

<references />

== Metadata ==

Bukkit is trying to make plugin development as easy as possible, so HashMaps with key of type Player, Entity, World or even a Block were replaced by Metadata. Metadata is some kind of alternative to HashMap. It allows you to add custom "fields" to Players, Entities, Worlds and Blocks. These things are all members of Metadatable class(check [http://jd.bukkit.org/doxygen/de/d59/interfaceorg_1_1bukkit_1_1metadata_1_1MetadataValue.html#ab49975fe013a0626dd29d3b85c63a82f])It works very simply. Everything that is Metadatable holds its own HashMap of Metadata which you have access to. That means, for example, if you're creating an economy plugin, you would need a HashMap of Player and Float or Double. With Metadata, you don't have to! You just attach to player new metadata value, and that's it! 

=== Why to use Metadata ===

* Metadata is all handled by Bukkit, which makes it a very good alternative to HashMaps.
* Metadata can be used to share information between plugins.

=== Why not use Metadata ===

* Slightly more difficult to get the value.
* It is not saved on shutdown (but then again, neither are any Maps that you create).

=== Getting & Setting Metadata ===

<source lang="java">
public void setMetadata(Metadatable object, String key, Object value, Plugin plugin) {
object.setMetadata(key, new FixedMetadataValue(plugin,value));
}

public Object getMetadata(Metadatable object, String key, Plugin plugin) {
List<MetadataValue> values = object.getMetadata(key);
for (MetadataValue value : values) {
// Plugins are singleton objects, so using == is safe here
if (value.getOwningPlugin() == plugin) {
return value.value();
}
}
return null;
}</source>

Note: If you're manipulating with numbers, booleans or strings, use convenient method to get the result. For example, you can use asInt(), asString() or asBoolean() instead of value to find out the value.

== Databases ==

Sometimes flat files aren't enough for what your looking to do, this is where databases come in. The most common database engines available on Linux/Mac/Windows machines typically run on some flavor of SQL (Structured Query Language).

Software offering SQL allow you to create databases with columns and header to identify to contents of each cell. Think of it as a spreadsheet on steroids, where every column you set up in your database can enforce rules to ensure integrity. Apart from being more organised than a simple custom data file, SQL provides faster access and better searching than flat files.

The SQL standard helps applications like Bukkit implement database storage for their data in a consistent way. Unfortunately, there's more than one SQL-ready database engine, and each has minor differences in how to configure and use it. Which one you choose may depend on your particular needs. (Some plugins even offer configurable options to connect to multiple database engines!)

=== SQLite ===

Alta189 has written a [http://forums.bukkit.org/threads/lib-tut-mysql-sqlite-bukkit-drivers.33849/ fantastic SQLite tutorial] which I suggest you watch if you're interested in using SQL in your plugins, included with the tutorials is a handy library you can download and import to make using SQL easier. Once you have watched these video tutorials I would suggest you go and learn some SQL syntax, it's very straightforward and shouldn't take you long to pick up. SQL Tutorials [http://www.w3schools.com/sql/default.asp @W3Schools] and [http://www.1keydata.com/sql/sql.html @1Keydata].

SQLite is great for very simple databases, because there's no server concerns to set up. Just make a few calls to create a new database and table. It's easy to back up: just copy the whole database file in one go. SQLite is a little bit weaker at data integrity, flexibility in data types, and it may not be something you would want to trust for huge databases of millions of rows. But for a new plugin in development, it's often easiest and fastest to get the SQL basics squared away with SQLite, even if you "graduate" to a more server-class database engine later.

=== MySQL ===

Another popular SQL database engine is called MySQL. It is closer to server-grade than SQLite, where many popular companies or websites depend on it for millions of webpage hits every day. With that security comes a little bit steeper learning-curve, because MySQL has more tunable parameters and capabilities.

The coding for plugins accessing MySQL is mostly the same as tiny SQLite or mega-sized Oracle, with only small differences in syntax here or there. But the administration has room to grow. You may want to set up accounts and privileges inside your MySQL setup. You may want to set up SQL scripts that organize your backups and rollback to previous states.

== 部署你的插件 ==

总之你写好的你的插件,如何把它变成一个可安装在服务端的jar文件呢?

首先我们需要建立一个水桶服务器。 [http://wiki.bukkit.org/Setting_up_a_server 在这里] 能找到开服相关信息.接下来你需要把插件导出为一个.jar文件，

这样你就能在你的服务器里运行它。在Eclipse里, 右键工程，点击''Run as > Maven install''即可:

[[Image:Maveninstall.png]]

将来呢, 当你对插件进行了改动后,在做上述操作之前，如果你想删除之前的.jar文件，你可以右键工程，点击 ''Run as > Maven clean'' 。

如果你在编译插件时遇到了问题, 请检查你的JDK是否正确安装，并浏览[[建立工作区]]条目。

如果你在Eclipse控制台看到了和JDK有关的错误，你可能需要手动调整JDK,因为Eclipse的检测可能发生了错误。

点击''Window -> Preferences'', 然后是''Java -> Installed JREs''。选中你最近安装的JDK作为Java运行环境（JRE）并添加, 并取消掉原来那个报错的JDK:

[[Image:Jrelocation.png]]

如果你的工程成功被编译,JAR文件会生产在 ''target'' 目录下，具体在Eclipse的工作空间里名字为工程名的文件夹中。

这个JAR文件就是一个能正常工作的Bukkit插件了。当然前提是你的plugin.yml里没出差错。

你可以把这个jar文件丢到服务器的plugins文件夹里,重载或重启服务器,就可以测试你的新插件啦。

为了连接上使用你自己的电脑开的服务器 ,在多人游戏的ip里填上你的本地ip即可。

如果出现了错误而你又不能解决的话, 试试这里[http://forums.bukkit.org/forums/plugin-development.5/ plugin development forum],

在这里提问[http://wiki.bukkit.org/IRC bukkitdev IRC channel],或者重新阅读wiki。

当你做完了一个实用的插件,可以考虑把它发表在这里[http://dev.bukkit.org/ dev.bukkit]（为了Bukkit社区的访问量）。

以上可知,JAR格式是默认压缩生成的(JAR文件基于ZIP文件的格式)。这么说来，在上传插件到Bukkit上时把JAR文件压缩成ZIP只会增加文件体积罢了。

而且呢, 放在JAR中的config文件可以在检测不到插件目录（插件自动生成的文件夹，名字与插件名相同，里面是该插件的配置）下的config文件时自动生成。

所以我们一般不把jar文件转换成其他格式。

== 导入其它插件 ==
你可能会希望编辑其它那些有源代码的插件. 如果插件在它的目录下有''pom.xml''(大多数知名插件,例如WorldEdit和Essentials都有),你可以通过点击''File -> Import''来把它作为一个工程导入, 然后打开''Maven''项并选择''Existing Maven Projects'':

[[Image:Importmaven.png]]

然后选择''pom.xml''所在的目录,这个工程就应该出现在你的侧边栏里了。就像平常一样编辑并编译它吧。

== 小贴士 ==

=== 使玩家着火 ===

Bukkit API有很多碉堡的功能。以下是实现一些功能的代码片段。

下面的代码运行一个玩家使另一个玩家着火。通过类似于'''/ignite Notch'''这样的指令，这个指令会让 Notch 着火。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
// 使用 equalsIgnoreCase() 来忽视大小写
if (cmd.getName().equalsIgnoreCase("ignite")) {
// 确保玩家只输入了一个自变量(要被点着的玩家名).
if (args.length != 1) {
// 当return false时，该指令的使用信息会显示出来。
return false;
}

// 确保命令发出者是个玩家.
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can set other players on fire.");
sender.sendMessage("This is an arbitrary requirement for demonstration purposes only.");
return true;
}

// 获取那个要被点着的玩家. 请注意下标起始是0，不是1.
Player target = Bukkit.getServer().getPlayer(args[0]);

// 确保这个玩家在线。
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}

// 让这个玩家着火1000 ticks (一秒钟大概有20ticks,所以总共是50秒).
target.setFireTicks(1000);
return true;
}
return false;
}

=== 干掉玩家 ===

和标题一样.这里是要干掉某个玩家。

在你的onCommand方法里使用这个:

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("KillPlayer")) {
Player target = sender.getServer().getPlayer(args[0]);
// 确保玩家在线.
if (target == null) {
sender.sendMessage(args[0] + " is not currently online.");
return true;
}
target.setHealth(0);
}
return false;
}

这里有个小扩展,会使用一个爆炸来杀死玩家:

float explosionPower = 4F; //爆炸等级 - TNT的爆炸等级默认是4F
Player target = sender.getWorld().getPlayer(args[0]);
target.getWorld().createExplosion(target.getLocation(), explosionPower);
target.setHealth(0);

=== 创造一个假爆炸 ===

这段代码会生产一个看起来和听起来与TNT/苦力怕产生的爆炸一样的效果。但是不会对实体和方块产生破坏。在保留爆炸的艺术的同时又削弱了爆炸的威力，真是太有用了（
@EventHandler
public void onExplosionPrime(ExplosionPrimeEvent event) {
Entity entity = event.getEntity();

// 如果事件和点燃的TNT有关,执行一些代码（又略）
if (entity instanceof TNTPrimed) {
entity.getWorld().createExplosion(entity.getLocation(), 0);
}
}

=== 使一个玩家对另外一个玩家隐形 ===

通过输入指令，能让指令执行者对特定的玩家隐形。然而其他人仍然能看到指令执行者。

@Override
public boolean onCommand(CommandSender sender, Command cmd, String label, String[] args) {
if (cmd.getName().equalsIgnoreCase("HideMe") && args.length == 1) {
if (!(sender instanceof Player)) {
sender.sendMessage("Only players can use this command!");
return true;
}
// 检测指令执行者是玩家后，我们便可以安全的进行强制转换类操作。
Player s = (Player) sender;

// 获取命令执行者指定的玩家
Player target = Bukkit.getServer().getPlayer(args[0]);
if (target == null) {
sender.sendMessage("Player " + args[0] + " is not online.");
return true;
}
// 将 s 从 target 的视野中隐藏起来.
target.hidePlayer(s);
return true;
}
return false;
}

=== 在玩家准星所指处生产闪电 ===

如下代码运行手持鱼竿的玩家通过点击来生成闪电 (当然要用准星瞄准)。真是个简单好玩的恶作剧（。

@EventHandler
public void onPlayerInteractBlock(PlayerInteractEvent event) {
Player player = event.getPlayer();
if (player.getItemInHand().getType() == Material.FISHING_ROD) {
// 在给定坐标中生成一道闪电. 在本例中, 这个坐标是玩家准星瞄准的地方.
// 只能指向200格以内的坐标.
player.getWorld().strikeLightning(player.getTargetBlock(null, 200).getLocation());
}
}

=== 自动格式 ===

Eclipse提供了将你的代码自动转成Oracle规定的格式, 修正了不符合常规的缩进, 空格等等。在侧边栏选中你的项目,然后选择''Source -> Format''即可对其进行更改。

== 插件需求专区 ==

http://forums.bukkit.org/forums/plugin-requests.13/

== 范例文件和样板 ==

*[https://github.com/Bukkit/SamplePlugin/ Bukkit/SamplePlugin on GitHub]

*[http://pastebin.com/wpeTPx7N Example.Java]

*[http://pastebin.com/MTwaAVCT ExamplePlayerListener.Java]

*[http://pastebin.com/6FLixfH3 ExampleBlockListener.Java]

*[http://pastebin.com/8UZ6pkWC ExampleEntityListener.Java]

If you have any more questions on this matter, don't hesitate to visit the BukkitDev [[IRC]] channel and ask!

[[Category:教程]]
[[Category:大篇幅条目]]