第二节 认识YAML语法

本节部分内容引用自 tdiant 编写的 BukkitDevelopmentNote 。

在配置文件中，服主可以设置插件/模组的功能。
同时，插件/模组的开发者有时也会把数据存储在配置文件中。

本文以 Essentials 插件举例。

我如何找到配置文件？

通常，配置文件与插件生成在一起（部分小型插件没有配置文件）你可以在/plugins/插件名/中找到它们。 譬如 Essentials 的配置文件就在/plugins/Essentials/中。

什么是配置文件？

一些简单的插件不带有配置文件。当插件加载失败时（如版本不对），也不会生成配置文件。

譬如你打开文件夹/plugins/Essentials/后，看到了一堆文件。

这些文件中，只有结尾是.yml的文件，才是我们讨论的配置文件。

其他的不是由.yml结尾的文件，因插件而异，那些文件就不在今天讨论范围内了，如有需要请查阅插件官方文档。

我该如何打开 .yml 这样的配置文件?

我们在开始前所做的准备工作中，安装了 Notepad++ 软件。

现在让我们右键.yml文件，单击”Edit with Notepad++”，就可以开始修改配置文件了！

对于配置文件来说，语法是很重要的，否则一定会导致插件报错。

语法一: 注释

譬如你打开 Essentials 后，开篇就有一堆注释：

  1. # 文本大部分引自 XXXXXX XX"  
  2. # 文本前带有"#"的都是阐释说明的内容,不会对格式产生影响."  
  3. # 如果你想要在该文件内添加非单字节内容,请保存为UTF-8格式,而不是ANSI,否则可能出现乱码  
  4. # 如果加载插件时出现了问题(例如:ERROR:null),请注意:  
  5. #   - 没有tab这样的间隔:YAML文件仅支持普通的空格  
  6. #   - 正确的"缩书写"(译注:不懂的去百度一下Indent):YAML文件的层次结构完全依赖于首行缩排.  
  7. #   - 如果文中需要使用单引号 ' , 请同时使用两个单引号, 例如：''  
  8. #   - 带有符号的文本被用单引号或双引号隔绝开来.  
  9. #   - 如果一个冒号后面有文本,则冒号与文本间必须有一个空格.  
  10. #   - 有些设置只能设置"true"或"false"  
  11. #   - 你保存该文本为UTF-8格式,而不是其他default,ANSI等格式."

这些以 “#” 开头的就是注释了，注释是给插件用户看的，让用户获得更好的插件体验，但并非所有插件作者都会在配置文件中写注释。

如果你觉得注释碍眼可以把注释删了，不会对插件功能造成影响。

同时你也可以自己写注释，但注释不推荐与配置文件内容同行，如:

  1. heal-cooldown: 60 #我是与配置节点同行的注释

语法二：节点

你可以在配置文件中看到譬如:

  1. ABCABC: XXXXXXX

注意：这里的冒号是 英 文 半 角 状 态 下的冒号，是 : 而不是：，仔细看看区别，极其容易忽略。

注意：这里的冒号后面有一个空格，极其容易忽略。

其中ABCABC称为节点名，读作”节点ABCABC”
而XXXXXXX就是节点下的内容了

内容的语法

你可以填以下内容：

汉字

譬如: 

  1. welcome: "欢迎来到服务器"

注意：汉字要用 英 文 半 角 状 态 下的引号扩起来，是 “ 而不是 “，极其容易忽略。

数字

譬如：

  1. player-health: 20

注意：当此处只能填数字时，你填了非数字内容，插件就会报错，譬如：

此处 player-health 的意思是玩家的血量，插件作者本意让你填写一个数字，你却：

  1. player-health: 玩家血量

此时如果插件作者没有做防护措施，插件就会崩溃报错。

“true”或 “false”

“true”代表开启，”false”代表关闭，譬如: 

  1. # 如果你想用其他的插件来设置玩家名字,将其改为"false"
  2. change-displayname: true

这里只能填写true或false，若填写了其他的内容，而插件作者未做防护措施，插件就会崩溃报错。

列

譬如:

  1. # 这些命令是当开启了/socialspy命令时可以看到的玩家私聊     
  2. # 你可以添加一些来自其他插件的命令    
  3. # 或者移除一些你不想看到的私聊命令    
  4. socialspy-commands:  
  5.   - msg      
  6.   - w    
  7.   - r  
  8.   - mail  
  9.   - m  
  10.   - t  
  11.   - whisper  
  12.   - emsg  
  13.   - tell  
  14.   - er  
  15.   - reply  
  16.   - ereply  
  17.   - email  
  18.   - action  
  19.   - describe  
  20.   - eme  
  21.   - eaction  
  22.   - edescribe  
  23.   - etell    
  24.   - ewhisper  
  25.   - pm

这样以’-‘引起的一些字符，可以写很多行

注意: ‘-‘ 前面 有 两 个 空 格， ‘-‘ 后面 有 一 个 空 格。

再一个节点

禁止套娃

譬如：

  1. # /kit快速工具命令,注意:所有物品后面必须写明数量!  
  2. # 所有的kit物品最好容易获得, 在/costs中价格较低,权限要求较低.  
  3. # 格式: - 物品ID[:数据值/耐久] 数量 [附魔:附魔等级]..[itemmeta:value]...  
  4. # 查看更多信息,请访问 http://wiki.ess3.net/wiki/Item_Meta  
  5. # 延迟时间(delay)以秒为单位.  
  6. # 查看更多信息,请访问 http://wiki.ess3.net/wiki/Kits  
  7. kits:  
  8.   tools:  
  9.     delay: 10  
  10.     items:  
  11.       - 272 1  
  12.       - 273 1  
  13.       - 274 1  
  14.       - 275 1

可见，在节点kits下，又写了一个tools节点，而tools节点下，又有一个delay与items节点

我们称它们为：子节点tools、子节点delay、子节点items

其中delay节点是只能写 数字，items节点是只能写 列，而且这个列在这个特定的插件里是有特定的格式要求的。

注意：每个子节点前面都要有两 个 空 格。

那问题就来了，为什么items前面没有两个空格呢？

这是因为delay与items都是tools的子节点，如果:

  1. kits:
  2.   tools:
  3.     delay: 10
  4.       items:
  5.         - 272 1
  6.         - 273 1
  7.         - 274 1
  8.         - 275 1

这样子的意思就是tools是kits的子节点，delay是tools的子节点，items是delay的子节点，与原意完全不相符。

注意：以上几个语法只是插件配置文件中普遍存在的，而不同的插件对配置文件的要求也是不同的，但是大体都可以分为以上几点。

注意：一定要按照插件原作者的要求写配置文件！

最后，改完配置文件别忘了点击左上角的保存按钮，再在服务器中重载配置文件！

乱码

指的是由于文本编辑器打开配置文件时，使用了不相应字符集而造成部分或所有字符无法被阅读的一系列字符。

在 NotePad++ 界面上方的”编码”处，点击转为 ANSI 或 UTF-8无BOM 编码，然后再保存。

一般情况下，Windows 系统的编码为ANSI，而Linux系统为UTF-8无BOM，如果无法确定，不妨两个都试一下。

注意：1.9+的服务端统一使用UTF-8无BOM编码！