Velocity 插件基础

现在我们将为你的第一个插件奠定基础。我们将介绍如何创建你的第一个 Velocity 插件。

创建插件类

创建一个新类（比如说 com.example.velocityplugin.VelocityTest) 并粘贴以下内容：

package com.example.velocityplugin;

import com.google.inject.Inject;
import com.velocitypowered.api.plugin.Plugin;
import com.velocitypowered.api.proxy.ProxyServer;
import org.slf4j.Logger;

@Plugin(id = "myfirstplugin", name = "My First Plugin", version = "0.1.0-SNAPSHOT",
        url = "https://example.org", description = "我做到了！", authors = {"我"})
public class VelocityTest {

    private final ProxyServer server;
    private final Logger logger;

    @Inject
    public VelocityTest(ProxyServer server, Logger logger) {
        this.server = server;
        this.logger = logger;

        logger.info("你好！我用 Velocity 制作了我的第一个插件。");
    }
}

你刚才做了什么？这里有很多内容需要解释，让我们专注于 Velocity 特有的部分：

@Plugin(id = "myfirstplugin", name = "My First Plugin", version = "0.1.0-SNAPSHOT",
        url = "awesome.org", description = "我做到了！", authors = {"我"})
public class VelocityTest {

这告诉 Velocity 这个类包含你的插件（myfirstplugin），这样它就可以在代理启动时加载。当你编译插件时，Velocity 会检测到插件将驻留的位置。

继续，这是什么？

@Inject
public VelocityTest(ProxyServer server, Logger logger) {
    this.server = server;
    this.logger = logger;

    logger.info("你好，这是我制作的测试插件！");
}

这看起来像魔法！Velocity 是如何做到的？答案在于 @Inject，它表示 Velocity 应该在构造你的插件时注入一个 ProxyServer 和 Logger。当你开始使用 Velocity 时，这两个接口会对你有帮助。我们不会过多讨论依赖注入：你只需要知道 Velocity 会帮你完成这个工作。

你只需要构建你的插件，将它放在你的 plugins/ 目录中，然后试试看！这不是很好吗？在下一节中，你将学习更多关于如何使用 API 的内容。

选择 `@Plugin` 信息

明智地选择你的插件 ID。其他插件将使用这个 ID 来依赖你的插件。如果你改变它，可能会破坏兼容性。

插件名称相对不那么重要。它将作为你的插件的显示名称显示给用户，但调整它不会造成灾难性的后果。

对于版本，我们建议遵循语义化版本控制 - 你可以在 semver.org 上阅读更多关于这个概念的内容。基本上，在你的版本中使用 3 个数字，比如 1.4.25。当你进行向后不兼容的破坏性更改时增加主版本号，当你添加向后兼容的功能时增加次版本号，当你修复错误或进行其他在实现中不易察觉的更改时增加补丁版本号。

你也可以在你的 @Plugin 注解中描述你的插件的 URL、作者和描述。对其他插件的依赖也要在那里指定，但我们稍后会在依赖管理页面中讨论这个问题。

一个警告

警告

在 Velocity 中，插件加载分为两个步骤：构造和初始化。你的插件构造函数中的代码是构造阶段的一部分。在构造期间你能安全做的事情很少，特别是因为 API 没有指定在构造期间哪些操作是安全的。值得注意的是，你不能在构造函数中注册事件监听器，因为你需要有一个有效的插件注册，但 Velocity 在插件构造完成之前无法注册插件，这导致了"先有鸡还是先有蛋"的问题。

要打破这个恶性循环，你应该始终等待初始化，当 Velocity 触发 ProxyInitializeEvent 时就表示初始化完成。我们可以通过为这个事件添加一个监听器来在初始化时执行操作，如下所示。注意，Velocity 会自动将你的插件主类注册为监听器。

@Subscribe
public void onProxyInitialization(ProxyInitializeEvent event) {
    // 在这里执行需要访问 Velocity API 的操作。
    // 例如，我们可以注册一个事件：
    server.getEventManager().register(this, new PluginListener());
}

获取你的插件目录

在某些时候你可能需要你的插件目录。要做到这一点，在你的插件构造函数参数中添加 @DataDirectory Path dataDirectory：

private final Path dataDirectory;

@Inject
public VelocityTest(ProxyServer server, Logger logger, @DataDirectory Path dataDirectory) {
    this.server = server;
    this.logger = logger;
    this.dataDirectory = dataDirectory;
}

这将为你提供一个你的插件目录的 Path。如果你绝对需要一个 File，你可以使用 Path#toFile()。但是，Velocity 通常使用 Path。

创建插件类​

选择 @Plugin 信息​

一个警告​

获取你的插件目录​

创建插件类

选择 `@Plugin` 信息

一个警告

获取你的插件目录