Minecraft-Spigot插件开发入门

Plugin.yml文件

plugin.yml 是一个包含你的插件信息的文件。没有这个文件，你的插件将无法工作。它由一组属性组成，每个属性都定义在一个新的行上，没有缩进。
所有的属性都是区分大小写的。

Plugin文件必要的三个属性

main

• 这个属性指向你的插件的类，它扩展了 JavaPlugin。
• 这必须包含完整的命名空间，包括类文件本身。

main: love.iloveworld.Test

name

• 这个属性是你的插件的名称。
• 必须由所有字母数字字符和下划线组成（a-z,A-Z,0-9,_）。
• 用于确定插件的数据文件夹的名称。
• 推荐的做法是将你的 jar 命名为与此相同（例如：MyPlugin.jar）。

name: MyPlugin

version

• 你的插件的版本。
• 最常见的版本格式是语义版本，写成 MAJOR.MINOR.PATCH（例如：1.4.1或9.12.4）。

version: 1.0

可选的属性

description

• 对你的插件所提供的功能进行人性化的描述。
• 该描述可以有多行。

description: This plugin does so much stuff it can't be contained!

api-version

• 你想使用的 API 的版本。
• 1.13、1.14、1.15、1.16、1.17、1.18 和 1.19 是可用版本。
• 这将向服务器发出信号，表明你的插件在编码时已经考虑到了特定的服务器版本，它不应该应用任何形式的向后兼容措施。因此，你还需要确保你的代码编程时考虑到了对旧配置、数据等的读取。每个服务器版本可以决定如何实现兼容性，未知或未来的版本将阻止插件启用。从 1.14 版本开始，仍然允许使用 api-version 1.13 然而未来的版本可能会基于这个版本放弃向后支持。

api-version: 1.12

load

• 你想使用的API的版本。明确说明插件应该在什么时候被加载。如果不提供将默认为 POSTWORLD。
• 有两个可能的值。STARTUP 和 POSTWORLD。

load: POSTWORLD

author

• 唯一标识这个插件的开发者。
• 在一些服务器错误信息中使用，以提供有用的反馈信息，说明发生错误时应与谁联系。
• 建议使用 SpigotMC.org 论坛或电子邮件地址。

author: TobyCold

authors

• 如果是一个合作项目，允许你列出多个作者。
• 必须是有效的 YAML 列表格式。

authors: [md_5, thinkofdeath]

website

• 该插件的或作者的网站。
• 如果你没有专门的网站，建议链接到该插件所在的页面。

website: iloveworld.love

depend

• 插件依赖列表。
• 必须是有效的 YAML 列表格式。
• 使用所需插件的名称属性，以指定依赖关系。
• 如果这里列出的任何插件没有找到，你的插件将无法加载。
• 如果多个插件互相列出依赖关系，以至于没有插件没有可加载的依赖关系，那么所有的插件都会加载失败。

depend: [WorldEdit, Towny]

prefix

• 控制台日志所使用的名称，而不是插件的名称。

prefix: Testing

softdepend

• 一个插件的列表，这些插件是你的插件拥有完整功能所必需的。
• 必须是有效的 YAML 列表格式。
• 使用所需插件的名称属性，以指定依赖性。
• 你的插件将在这里列出的任何插件之后加载。
• 循环软依赖会被任意加载。

softdepend: [Essentials, AnotherPlugin]

loadbefore

• 一个应该在此插件之后加载的插件列表。
• 必须是有效的 YAML 列表格式。
• 处理方法是，如果列出的插件软依赖于这个插件。
• 使用所需插件的名称属性来指定目标。
• 你的插件将在这里列出的任何插件之前加载。
• 循环软依赖会被任意加载。

loadbefore: [OnePlugin, AnotherPlugin]

libraries
Warning

Library loading 仍然是一个预览功能。

您的插件需要的库列表，可以从 Maven Central 加载。
有助于减少插件的大小并消除重定位的需要。
拟用于大型非 Minecraft 的依赖性。专门的库仍然应该被遮蔽和重新定位。
例如

libraries:
- com.squareup.okhttp3:okhttp:4.9.0
commands
插件希望注册的命令的名称，以及一个可选的命令属性列表。
该命令名称不应包含发布命令所需的前缀 '/'。
例如

commands:
flagrate:
[optional command attributes]
permissions
该插件希望注册的权限。每个节点代表一个要注册的权限。
每个权限可以有多个属性。
权限注册是可选的，也可以从代码中完成。
权限注册允许你设置描述、默认值和上下级关系。
权限名称应该保持在 .[category].[category]. 的风格上。
例如

permissions:
inferno.*:
[optional permission attributes]
inferno.flagate:
[optional permission attributes]
命令
一个命令块以命令的名称开始，然后有一个可选的属性列表。

description
对该命令所做工作的简短描述。
可以和 /help 一起使用
例如

description: A simple description.
aliases
用户可以使用的替代命令名称。
你可以指定任何一个或多个别名。
如果你指定一个以上的别名，它们必须是有效的 YAML 列表格式。
例如

aliases: [foobar, fubar] #
!
permission
使用该命令所需的最基本的权限节点。
这个权限节点可以用来确定一个用户是否应该能够看到这个命令。
例如

permission: test.foo
permission-message
如果用户没有使用该命令的必要权限，将向其显示无权限信息。
你可以使用空引号来表示不应显示任何内容。
例如

permission-message: You do not have permission to use this command.
usage
关于如何使用该命令的简短描述。
当插件的命令处理程序（通常是 onCommand）没有返回 true 时，会显示给发出命令的人。
是一个宏，在它出现的地方会被替换成发出的命令。
要使用字符串 "Usage:" (例如: usage: Usage: /test command)，用双引号包围用法标签后的文本。(例如：usage: "Usage: /test command")
例如

usage: "Usage: / [test|stop]"
权限
一个权限块以权限的名称开始，后面是属性的节点。

description
对该权限的简短描述。
允许程序性访问，并帮助服务器管理员。
例如

description: Allows you to use the command /test
default
设置权限的默认值。
如果节点不存在, 权限默认为 op.
允许的默认值是：true, false, op, not op
例如

default: true
说明

true 默认将总是授予玩家该权限。
false 默认不会授予玩家权限。
op 如果玩家是管理员，默认为 true。
not op 是与 op 相反的行为。
children
允许你为权限设置子节点。子节点是权限名称。
每个子节点必须设置为真或假。
true 的子节点继承父权限。
false 的子节点继承反向的父权限。
也可以包含其他权限节点。
例如

这些数值不是本文中使用的数值。它们只是为了说明。

permissions:
test.all:
children:
test.foo: true
test.bar: false
示例

main: org.spigotmc.annotationtest.Test
name: TestPlugin
version: '1.0'
description: A test plugin
load: POSTWORLD
author: md_5
website: spigotmc.org
prefix: Testing
depend:

• WorldEdit
• Towny
  softdepend:
• FAWE
  loadbefore:
• Essentials
  commands:
  foo:
  description: Foo command
  aliases:
  • foobar
  • fubar
    permission: test.foo
    permission-message: You do not have permission!
    usage: / [test|stop]
    permissions:
    test.foo:
    description: Allows foo command
    default: op
    test.*:
    description: Wildcard permission
    default: op
    children:
    test.foo: true
    注解
    如果你不想处理为每个项目创建 plugin.yml 的麻烦，那么有一个方便的小工具专门为你准备的！它叫做插件注释。它叫做 Plugin Annotations。它是一个简单的注释处理器，可以为你自动生成一个正确的 plugin.yml。

要使用它，只需把它作为一个依赖项添加到你的项目中。

在 pom.xml 目录下执行：

gradle init --type pom