PluginApi - 实用Kotlin插件工具库

plugin-api 是一个用 Kotlin 编写的多功能插件工具库，旨在为 Spigot 插件开发提供一系列强大且类型安全的 API，涵盖事件处理、GUI、命令框架、配置管理等常见需求，并内置了 Kotlin 标准库和协程支持，以简化开发流程。

💡核心特性

• 类型安全的 API 对象构建器：以类型安全的方式构建各种 API 对象。
• 简洁的事件处理：提供更简洁、直观的事件监听与处理方式。
• GUI API 与 DSL：通过领域特定语言（DSL）轻松创建和管理图形用户界面。
• 命令框架：内置的命令处理框架，简化命令的注册与解析。
• 语言扩展：提供一些 Kotlin 语言的便利扩展功能。
• 运行时库捆绑：自动捆绑 kotlin-stdlib-jdk8、kotlin-reflect 和 kotlinx-coroutines-core 库。
• JSON 配置 API：支持基于 Gson 和 Jackson 的 JSON 配置文件管理。
• 协程与异步事件处理：集成协程调度器，支持异步处理事件。

🔧安装与使用

运行时安装

要使用依赖于此 API 的插件，你需要先安装其运行时库。

• 从发布页面下载 plugin-api 的运行时 JAR 文件。
• 将其放入服务器的 /plugins/ 目录中。
• 确保所有依赖于此 API 的插件都放置在同一个 /plugins/ 目录下。

构建依赖

该库分为五个功能模块，每个模块都依赖于 common 模块。你可以根据需要引入特定的模块。

以下是使用不同构建工具的配置示例。

Gradle (Groovy DSL)

repositories {
    mavenCentral()
    maven { url 'https://gitlab.com/api/v4/projects/10077943/packages/maven' }
    maven { url 'https://hub.spigotmc.org/nexus/content/repositories/snapshots/' }
    maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
}
dependencies {
    compileOnly 'org.spigotmc:spigot-api:1.18.1-R0.1-SNAPSHOT'
    compileOnly 'io.github.commandertvis:chat-components:18.0.0'
    compileOnly 'io.github.commandertvis:command:18.0.0'
    compileOnly 'io.github.commandertvis:common:18.0.0'
    compileOnly 'io.github.commandertvis:coroutines:18.0.0'
    compileOnly 'io.github.commandertvis:gui:18.0.0'
}

Gradle (Kotlin DSL)

repositories {
    mavenCentral()
    maven("https://gitlab.com/api/v4/projects/10077943/packages/maven")
    maven("https://hub.spigotmc.org/nexus/content/repositories/snapshots/")
    maven("https://oss.sonatype.org/content/repositories/snapshots")
}
dependencies {
    compileOnly("org.spigotmc:spigot-api:1.18.1-R0.1-SNAPSHOT")
    compileOnly("io.github.commandertvis:chat-components:18.0.0")
    compileOnly("io.github.commandertvis:command:18.0.0")
    compileOnly("io.github.commandertvis:common:18.0.0")
    compileOnly("io.github.commandertvis:coroutines:18.0.0")
    compileOnly("io.github.commandertvis:gui:18.0.0")
}

Maven

<repositories>
    <repository>
        <id>pluginApiGitlab</id>
        <url>https://gitlab.com/api/v4/projects/10077943/packages/maven</url>
    </repository>
    <repository>
        <id>spigotNexus</id>
        <url>https://hub.spigotmc.org/nexus/content/repositories/snapshots/</url>
    </repository>
    <repository>
        <id>sonatypeOss</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>org.spigotmc</groupId>
        <artifactId>spigot-api</artifactId>
        <version>${spigotApi.version}</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>io.github.commandertvis.plugin</groupId>
        <artifactId>common</artifactId>
        <version>18.0.0</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>io.github.commandertvis.plugin</groupId>
        <artifactId>command</artifactId>
        <version>18.0.0</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>io.github.commandertvis.plugin</groupId>
        <artifactId>coroutines</artifactId>
        <version>18.0.0</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>io.github.commandertvis.plugin</groupId>
        <artifactId>chat-components</artifactId>
        <version>18.0.0</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>io.github.commandertvis.plugin</groupId>
        <artifactId>gui</artifactId>
        <version>${pluginApi.version}</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

❓兼容性与支持

Spigot API 兼容性

• 大部分功能已在 Spigot 1.8.8 版本上测试通过。
• 为兼容旧版本进行了一些特别处理，但仍可能存在问题。如果遇到问题，请及时报告。

✨资源与链接

• 许可证：本项目基于 MIT 许可证 发布。
• 示例代码：示例项目发布于 CMDR_Tvis/plugin-api-examples。如果你需要某个特定 API 的示例，欢迎提交 Issue 请求。
• API 文档：完整的 API 文档已发布，可在此处查阅：plugin-api 文档。

💡简介

CMDR 是一个强大的 Minecraft 插件，它提供了一个直观、灵活的指令系统，旨在简化服务器管理并增强玩家体验。通过其独特的指令链、变量系统和强大的权限控制，管理员可以轻松创建复杂的自动化流程和交互式功能。

🎮核心特性

指令链

• 链式执行：允许将多个指令按顺序组合成一个指令链，只需执行一个主指令即可触发一系列操作。
• 条件分支：支持 if、else、switch 等条件判断，让指令执行更具逻辑性。
• 循环控制：提供 for、while、foreach 循环，便于处理重复性任务或遍历列表。

变量系统

• 变量存储：支持在指令链中定义和使用变量（如 {set: %player% to "Steve"}）。
• 动态解析：变量可以在指令执行时动态计算和替换，实现高度自定义。
• 作用域管理：变量拥有清晰的作用域（全局、玩家、临时），避免冲突。

权限与执行控制

• 细粒度权限：每个指令或指令链都可以设置独立的权限节点（如 cmdr.command.teleport）。
• 执行者控制：可以指定指令由控制台、玩家或两者执行。
• 条件执行：指令执行可基于玩家权限、世界、时间等多种条件进行限制。

🔧基本命令

玩家命令

• /help - 显示帮助信息。
• /teleport <player> - 传送至指定玩家。
• /home set - 设置家的位置。
• /home - 传送回家。

管理员命令

• /cmdr reload - 重载插件配置。
• /cmdr debug - 切换调试模式，查看指令执行详情。
• /cmdr run <chainName> - 手动执行指定的指令链。

✨安装与配置

安装步骤

• 将 CMDR.jar 文件放入服务器的 plugins 文件夹。
• 重启服务器。
• 插件将自动生成配置文件和数据文件夹。

配置文件

• config.yml：主配置文件，包含插件设置、默认变量和全局指令链定义。
• chains/ 目录：用于存放自定义的指令链文件（.yml 格式）。
• permissions.yml：权限节点定义文件（如果使用插件内置权限系统）。

基础配置示例

# config.yml 片段
settings:
  debug: false
  default-language: en
variables:
  server-name: "My Awesome Server"
chains:
  welcome-message:
    - 'tell: &aWelcome to {var:server-name}, %player%!'

❓常见问题

一般问题

• Q: 指令链不执行怎么办？
• A: 请检查控制台是否有错误日志，并确保指令链文件语法正确（注意缩进和冒号）。使用 /cmdr debug 查看执行流程。

• Q: 如何为指令设置权限？
• A: 在指令链定义中添加 permission: your.permission.node 即可。确保你的权限管理插件（如 LuckPerms）已正确配置该节点。

• Q: 变量没有被替换是怎么回事？
• A: 请确认变量名拼写正确，并且变量在其作用域内已被正确定义。在调试模式下可以查看变量的实际值。

故障排除

• 确保服务器运行的是受支持的 Minecraft 版本（例如 1.16.5 至 1.20.4）。
• 如果与其他插件冲突，尝试调整指令链的执行顺序或优先级。
• 查看官方文档或社区支持获取更多帮助。

⭐重要提示

• 在修改指令链或配置文件前，建议进行备份。
• 复杂的指令链建议先在测试服务器上进行验证。
• 本插件与大多数主流权限和经济插件兼容，但具体集成情况请查阅相关文档。