UltimateAdvancementAPI - 自定义进度API

UltimateAdvancementAPI 是一款强大的 Minecraft 插件，它允许服务器管理员和开发者轻松创建、管理自定义进度，并提供完整的 API 供其他插件调用。所有操作均基于数据包，确保服务器运行流畅无延迟。

💡重要须知

• 请通过 Discord 或 GitHub 提交 Bug 报告，在评论中提交的 Bug 将不予处理。
• 若新 Minecraft 版本发布后插件未更新，请先查阅 FAQ 获取信息。

🎮核心特性

• 简单易用：轻松为服务器创建自定义进度。
• 异步无延迟：所有操作均基于数据包，不会造成服务器卡顿。
• 进度可见性：可自定义进度界面的显示方式。
• 团队进度：同一团队成员的进度会自动同步。
• 离线玩家支持：提供完整的 API 来修改离线玩家的进度数据。
• 自定义提示：发送自定义的进度完成提示（Toast）。
• 数据库系统：支持快速可靠的存储方式（SQLite、MySQL、内存存储）。
• 禁用原版进度：无需修改服务端核心文件，即可完全禁用原版进度。

🔧使用说明

本插件主要面向开发者。如果您使用的某个插件依赖它，只需下载对应服务器版本的插件，并将其放入 plugins 文件夹即可。

开发者集成

• 通过 Maven 将依赖添加到您的项目并开始编码。
• 请查阅 Wiki 以了解如何使用 API。

Maven 依赖

<repositories>
    <repository>
        <id>fren_gor</id>
        <url>https://nexus.frengor.com/repository/public/</url>
    </repository>
</repositories>
<dependency>
    <groupId>com.frengor</groupId>
    <artifactId>ultimateadvancementapi</artifactId>
    <version>2.7.2</version>
    <scope>provided</scope>
</dependency>

• 插件也提供可嵌入（Shadeable）版本，详情请查阅相关 Wiki 页面。

✨优势亮点

• 高度可定制：创建属于您自己的进度。
• 易于使用：提供完整且文档齐全的 API。
• 支持玩家团队：原生支持团队，让多名玩家可以协作。
• Maven 与嵌入支持：API 通过 Maven 分发，并可嵌入到您的插件中。
• 优质支持：欢迎在我们的 Discord 服务器 提问。
• 在线生成器：配套 UltimateAdvancementGenerator 官方工具，可图形化设计进度并自动生成 Java 代码。

⭐UltimateAdvancementGenerator

这是用于图形化设计进度的官方在线工具。该工具会自动为您的插件生成相应的 Java 类。

• 立即尝试：UltimateAdvancementGenerator
• 视频教程：请查看相关视频。

> 警告：该工具目前处于 BETA 测试阶段，请在 GitHub 上报告遇到的问题。

🎮命令与权限

主命令

• /ultimateadvancementapi <progression|grant|revoke> ...

- 权限：`ultimateadvancementapi.command`

授予进度

• /ultimateadvancementapi grant <all|tab|one> ...

- 权限：`ultimateadvancementapi.grant`

• /ultimateadvancementapi grant all <player> [giveRewards]

- 权限：`ultimateadvancementapi.grant.all`

• /ultimateadvancementapi grant tab <advancementTab> [player] [giveRewards]

- 权限：`ultimateadvancementapi.grant.tab`

• /ultimateadvancementapi grant one <advancement> [player] [giveRewards]

- 权限：`ultimateadvancementapi.grant.one`

撤销进度

• /ultimateadvancementapi revoke <all|tab|one> ...

- 权限：`ultimateadvancementapi.revoke`

• /ultimateadvancementapi revoke all <player> [hideTab]

- 权限：`ultimateadvancementapi.revoke.all`

• /ultimateadvancementapi revoke tab <advancementTab> [player] [hideTab]

- 权限：`ultimateadvancementapi.revoke.tab`

• /ultimateadvancementapi revoke one <advancement> [player]

- 权限：`ultimateadvancementapi.revoke.one`

管理进度值

• /ultimateadvancementapi progression <get|set> ...

- 权限：`ultimateadvancementapi.progression`

• /ultimateadvancementapi progression get <advancement> [player]

- 权限：`ultimateadvancementapi.progression.get`

• /ultimateadvancementapi progression set <advancement> <progression> [player] [giveRewards]

- 权限：`ultimateadvancementapi.progression.set`

🔧代码示例

以下示例创建一个名为 “Example” 的进度，其描述为 “A random” 和 “description.”。

// Creates an advancement called "Example" with the description:
// - "A random"
// - "description."
public class MainClass extends JavaPlugin implements Listener {
    private AdvancementTab advancementTab;
    private UltimateAdvancementAPI api;

    @Override
    public void onEnable() {
        api = UltimateAdvancementAPI.getInstance(this);
        advancementTab = api.createAdvancementTab("your_tab_name");

        AdvancementDisplay rootDisplay = new AdvancementDisplay(
            Material.GRASS_BLOCK,
            "Example",
            AdvancementFrameType.TASK,
            true,
            true,
            0,
            0,
            "A random",
            "description."
        );

        RootAdvancement root = new RootAdvancement(advancementTab, "root", rootDisplay, "textures/block/stone.png");
        advancementTab.registerAdvancements(root);
        Bukkit.getPluginManager().registerEvents(this, this);
    }

    @EventHandler
    public void onJoin(PlayerLoadingCompletedEvent e) {
        // Called after a player has successfully been loaded by the API
        Player p = e.getPlayer();
        // Here you can show tabs to players
        advancementTab.showTab(p);
    }
}

❓相关链接

• Wiki • Issues • Javadoc • GitHub • Discord • Generator • FAQ
• 本插件使用 Metrics 收集匿名数据以帮助改进。

完整的 Wiki 可在官方 GitHub 页面找到。

以下是一个简单的示例，用于创建一个带有随机描述的示例进度：

💡代码示例 (Java)

public class MainClass extends JavaPlugin implements Listener {
    private AdvancementTab advancementTab;
    private UltimateAdvancementAPI api;

    @Override
    public void onEnable() {
        api = UltimateAdvancementAPI.getInstance(this);
        advancementTab = api.createAdvancementTab("your_tab_name");

        AdvancementDisplay rootDisplay = new AdvancementDisplay(
            Material.GRASS_BLOCK,
            "Example",
            AdvancementFrameType.TASK,
            true,
            true,
            0,
            0,
            "A random",
            "description."
        );

        RootAdvancement root = new RootAdvancement(advancementTab, "root", rootDisplay, "textures/block/stone.png");
        advancementTab.registerAdvancements(root);
        Bukkit.getPluginManager().registerEvents(this, this);
    }

    @EventHandler
    public void onJoin(PlayerLoadingCompletedEvent e) {
        // 在玩家被 API 成功加载后调用
        Player p = e.getPlayer();
        // 在这里可以向玩家显示进度标签页
        advancementTab.showTab(p);
    }
}

🎮示例结果

该代码将创建一个名为“Example”的进度标签页，其根进度显示为草方块图标，并带有“A random description.”的描述。当玩家加入服务器并加载完成后，该进度标签页将自动显示给玩家。