# AdvancementInfo
AdvancementInfo API 是一套专门设计的库，用于简化插件中 Minecraft 成就的获取和操作。它通过提供统一的接口和使用反射与 Bukkit、Paper 等服务器内部机制配合的几种具体实现，抽象了访问成就数据的底层复杂性，例如标题、描述、图标、标准、奖励和显示设置。
---
## 概述
该 API 的核心是 `AdvancementInfo` 接口，该接口定义了获取成就详细信息的各种方法。`BukkitInfoImpl`、`ReflectInfoImpl` 和 `PaperInfoImpl` 等实现，通过反射从 Bukkit `Advancement` 对象中提取数据，并提供：
- **成就细节：** 标题、描述、图标和显示选项。
- **显示坐标：** 成就显示的 X 和 Y 位置。
- **视觉框架：** 成就的框架类型（例如，任务、目标、挑战）。
- **标准和要求：** 定义成就如何达成的标准。
- **奖励：** 完成后授予的奖励信息。
---
## 主要特性
- **统一接口：**
`AdvancementInfo` 接口提供了一个通用的 API 来访问成就数据，无论底层实现如何。
- **多种实现：**
不同的实现适应各种服务器版本和环境：
- **BukkitInfoImpl：** 使用 Bukkit 的标准成就显示方法。
- **ReflectInfoImpl：** 利用反射提取高级细节。
- **PaperInfoImpl：** 针对 Paper 服务器进行定制，使用 Paper 特定的方法和 LegacyComponentSerializer 进行文本转换。
- **版本兼容性：**
该 API 会根据服务器的 Minecraft 版本智能地选择正确的实现，确保广泛的兼容性。
- **基于反射：**
使用反射允许 API 访问成就的内部字段和方法，从而提供丰富的后续信息，即使 Bukkit API 并没有直接暴露这些信息。
---
## 使用示例
以下是一个示例，说明如何使用 AdvancementInfo API 来检索和显示有关 Minecraft 成就的信息。
### 示例：检索成就信息
```java
package com.example.myplugin;
import me.croabeast.advancement.AdvancementInfo;
import org.bukkit.Bukkit;
import org.bukkit.advancement.Advancement;
import org.bukkit.plugin.java.JavaPlugin;
public class MyPlugin extends JavaPlugin {
@Override
public void onEnable() {
// 通过其键检索 Bukkit 成就
Advancement advancement = Bukkit.getAdvancement(new org.bukkit.NamespacedKey(this, "example_advancement"));
if (advancement != null) {
// 使用静态工厂方法从成就创建 AdvancementInfo 实例
AdvancementInfo info = AdvancementInfo.create(advancement);
if (info != null) {
// 将成就详情打印到控制台
getLogger().info("成就标题: " + info.getTitle());
getLogger().info("描述: " + info.getDescription());
// 检索带有最多 40 个字符长度的格式化描述数组
String[] lines = info.getDescriptionArray(40);
for (String line : lines) {
getLogger().info("行: " + line);
}
} else {
getLogger().warning("检索成就信息失败。");
}
} else {
getLogger().warning("未找到成就。");
}
}
}
```
### 说明
- **检索成就：**
该示例通过其键获取 Bukkit `Advancement`。
- **使用工厂方法：**
`AdvancementInfo.from(advancement)` 返回根据服务器版本选择的适当实现（Bukkit、Paper 或 Reflect）。
- **访问成就数据：**
获取 `AdvancementInfo` 实例后，您可以访问其标题、描述、标准、奖励和显示设置。
- **格式化描述：**
该示例演示如何将描述拆分为一个行数组，确保每行不超过指定的长度。
---
## Maven / Gradle 安装
要将 AdvancementInfo 添加到项目中，请将以下存储库和依赖项添加到构建配置中。将 `${version}` 替换为所需的版本标记。
### Maven
将存储库和依赖项添加到您的 `pom.xml`：
```xml
croabeast-repo
https://croabeast.github.io/repo/
me.croabeast
AdvancementInfo
${version}
compile
```
### Gradle
将存储库和依赖项添加到您的 `build.gradle`：
```groovy
repositories {
maven {
url "https://croabeast.github.io/repo/"
}
}
dependencies {
implementation "me.croabeast:AdvancementInfo:${version}"
}
```
将 `${version}` 替换为适当的模块版本。
---
## 结论
AdvancementInfo API 提供了访问和处理 Minecraft 成就的强大、统一的方法。它抽象了反射和服务器版本差异的复杂性，使您可以专注于使用插件中的成就数据。无论您是构建自定义成就显示、将成就数据集成到插件逻辑中，还是仅仅记录成就详情，此 API 都可使您以一致的方式更轻松地与成就协同工作。
祝您编程愉快!
— *CroaBeast*
