CMI API 文档

概述

CMI (Content Management Interface) 是一个功能强大的 Minecraft 服务器管理插件，提供了丰富的管理工具和玩家功能。CMI-API 是 CMI 插件的公共 API，允许开发者扩展 CMI 功能或将其集成到自己的插件中。

基本信息

项目名称: CMI-API
作者: Zrips (Zrips#9691)
版本: 9.7.14.3
Minecraft 版本: 1.20.4 (Spigot API)
GitHub 仓库: https://github.com/Zrips/CMI-API.git
官方文档: https://www.zrips.net/cmi/api/
Spigot 页面: https://www.spigotmc.org/resources/content-management-interface.3742/

项目结构

目录组织

CMI-API/
├── pom.xml                    # Maven 配置文件
├── README.md                  # 项目说明
├── resources/
│   ├── plugin.yml            # 插件元数据
│   └── LICENSE               # 许可证文件
└── src/com/Zrips/CMI/        # 源代码
    ├── CMI.java              # 主插件类
    ├── Config.java           # 配置管理
    ├── Containers/           # 数据容器 (CMIUser, CMIEvent 等)
    ├── events/               # 自定义事件 (50+ 事件类)
    ├── Modules/              # 功能模块 (70+ 模块)
    ├── AllListeners/         # 事件监听器
    ├── commands/             # 命令实现
    ├── Locale/               # 本地化
    ├── NBT/                  # NBT 数据处理
    └── utils/                # 工具类

代码规模

Java 源文件: 918 个文件
模块数量: 70+ 个独立功能模块
自定义事件: 50+ 个事件类
占位符: 150+ 个 PlaceholderAPI 占位符

核心特性

1. 玩家管理

模块	功能描述
`CMIUser`	玩家数据容器 (UUID, 经济, 家园, 在线时间等)
`AfkManager`	AFK 检测与管理
`VanishManager`	玩家隐身管理
`NickNameManager`	玩家昵称管理
`PlayerOptionsManager`	玩家偏好设置
`PlayTimeManager`	游戏时间跟踪
`PlayTimeRewardsManager`	游戏时间奖励

2. 传送系统

模块	功能描述
`TeleportManager`	传送系统 (暖机, 冷却, 延迟)
`HomeManager`	玩家家园系统
`WarpManager`	服务器地标系统
`BackManager`	返回上次位置

3. 经济与权限

模块	功能描述
`EconomyManager`	经济系统 (Vault 集成)
`PermissionManager`	权限管理
`JailManager`	监狱系统
`WarningManager`	玩家警告系统
`BanManager`	封禁管理

4. 视觉与 UI

模块	功能描述
`HologramManager`	全息文字管理
`ParticleManager`	粒子效果
`AnimationManager`	动画系统
`TabListManager`	标签页列表定制
`BossBarManager`	Boss 血条显示
`ScoreboardManager`	计分板管理

5. 聊天与交互

模块	功能描述
`ChatManager`	聊天管理与格式化
`ChatFilterManager`	聊天过滤
`SignManager`	动态告示牌
`MailManager`	邮件系统
`NoteManager`	便签系统

6. 物品与装备

模块	功能描述
`KitManager`	礼包系统
`EnchantManager`	自定义附魔
`RecipeManager`	自定义合成配方
`ItemManager`	物品管理
`RepairManager`	修理系统

7. 服务器工具

模块	功能描述
`PortalManager`	自定义传送门
`ElevatorManager`	电梯系统
`TimerManager`	定时器管理
`WeatherManager`	天气控制
`TimeManager`	时间控制

集成与钩子

支持的插件

CMI 与以下插件集成：

插件	集成类型	功能
Vault	经济/权限	经济系统和权限集成
PlaceholderAPI	占位符	150+ 个自定义占位符
ProtocolLib	协议	数据包操作支持
DiscordSRV	Discord	Discord 集成
DynMap	地图	动态地图集成
BlueMap	地图	3D 地图集成
Towny	城镇	城镇插件集成
mcMMO	技能	技能插件集成
Jobs	职业	职业插件集成
LuckPerms	权限	权限管理集成
Multiverse-Core	多世界	多世界支持

钩子类型 (CMIHookType.java)

CMILib, BlueMap, AureliumSkills, AuraSkills, DiscordSRV,
dynmap, Towny, mcMMO, Jobs, Vault, LWC, PlayerVaults,
PlaceholderAPI, MVdWPlaceholderAPI, Votifier, Citizens,
NoCheatPlus, ProtocolLib

API 使用指南

1. 基本使用模式

获取 CMI 实例

import com.Zrips.CMI.CMI;

// 获取 CMI 主实例
CMI cmi = CMI.getInstance();

获取玩家数据

import com.Zrips.CMI.Containers.CMIUser;

// 通过玩家对象获取 CMIUser
CMIUser user = cmi.getPlayerManager().getUser(player);

// 通过 UUID 获取
CMIUser user = cmi.getPlayerManager().getUser(uuid);

// 通过玩家名获取
CMIUser user = cmi.getPlayerManager().getUser("PlayerName");

访问玩家属性

// 获取经济余额
double balance = user.getBalance();

// 检查权限
boolean canFly = user.canFly();

// 获取玩家等级
int level = user.getLevel();

// 获取在线时间 (毫秒)
long playTime = user.getPlayTime();

// 获取家园数量
int homeCount = user.getHomeCount();

// 获取最后登录时间
Date lastLogin = user.getLastLogin();

3. 经济系统操作

// 获取经济管理器
EconomyManager economy = cmi.getEconomyManager();

// 存款
economy.deposit(user, 100.0);

// 取款
economy.withdraw(user, 50.0);

// 设置余额
economy.setBalance(user, 1000.0);

// 检查余额
if (economy.hasBalance(user, 500.0)) {
    // 执行操作
}

4. 传送系统操作

// 获取传送管理器
TeleportManager teleport = cmi.getTeleportManager();

// 传送玩家到位置
teleport.teleport(player, location);

// 传送玩家到地标
teleport.teleportToWarp(player, "spawn");

// 传送玩家到家园
teleport.teleportToHome(player, "home1");

// 设置玩家家园
cmi.getHomeManager().setHome(user, "home1", location);

// 删除家园
cmi.getHomeManager().removeHome(user, "home1");

5. 事件系统

CMI 提供了丰富的事件系统，允许插件监听 CMI 的各种操作。

事件示例

import com.Zrips.CMI.events.*;

// 监听 AFK 事件
@EventHandler
public void onAfkEnter(CMIAfkEnterEvent event) {
    Player player = event.getPlayer();
    player.sendMessage("你已进入 AFK 模式");
}

// 监听传送事件
@EventHandler
public void onTeleport(CMITeleportEvent event) {
    Player player = event.getPlayer();
    Location from = event.getFrom();
    Location to = event.getTo();

    // 取消传送
    // event.setCancelled(true);
}

// 监听经济交易
@EventHandler
public void onMoneyTransaction(CMIMoneyTransactionEvent event) {
    CMIUser from = event.getFromUser();
    CMIUser to = event.getToUser();
    double amount = event.getAmount();

    // 记录交易日志
}

可用事件类型

玩家事件: CMIAfkEnterEvent, CMIAfkLeaveEvent
经济事件: CMIMoneyTransactionEvent, CMIMoneyChangeEvent
传送事件: CMITeleportEvent, CMIWarpCreateEvent
家园事件: CMIHomeCreateEvent, CMIHomeDeleteEvent
封禁事件: CMIPlayerBanEvent, CMIIpBanEvent
物品事件: CMIAnvilItemRepairEvent, CMIAnvilItemRenameEvent
支票事件: CMIChequeCreationEvent, CMIChequeUsageEvent

6. 占位符系统

CMI 提供了 150+ 个 PlaceholderAPI 占位符，可用于聊天、计分板、标题等。

常用占位符

占位符	描述	示例
`%cmi_user_balance%`	玩家余额	1000.50
`%cmi_user_playtime%`	游戏时间	5h 30m
`%cmi_user_homecount%`	家园数量	3
`%cmi_user_afk%`	AFK 状态	true/false
`%cmi_user_god%`	上帝模式	true/false
`%cmi_user_fly%`	飞行状态	true/false
`%cmi_user_vanish%`	隐身状态	true/false
`%cmi_user_jailed%`	监禁状态	true/false
`%cmi_user_muted%`	禁言状态	true/false

使用示例

// 通过 PlaceholderAPI 解析占位符
String formatted = PlaceholderAPI.setPlaceholders(player, "余额: %cmi_user_balance%");
player.sendMessage(formatted);

管理器引用

主要管理器列表

以下是可通过 CMI.getInstance() 访问的主要管理器：

管理器	获取方法	功能描述
玩家管理器	`getPlayerManager()`	玩家数据管理
经济管理器	`getEconomyManager()`	经济系统管理
传送管理器	`getTeleportManager()`	传送系统管理
家园管理器	`getHomeManager()`	家园系统管理
地标管理器	`getWarpManager()`	地标系统管理
监狱管理器	`getJailManager()`	监狱系统管理
警告管理器	`getWarningManager()`	警告系统管理
封禁管理器	`getBanManager()`	封禁系统管理
AFK 管理器	`getAfkManager()`	AFK 系统管理
隐身管理器	`getVanishManager()`	隐身系统管理
聊天管理器	`getChatManager()`	聊天系统管理
全息管理器	`getHologramManager()`	全息文字管理
粒子管理器	`getParticleManager()`	粒子效果管理
动画管理器	`getAnimationManager()`	动画系统管理
礼包管理器	`getKitsManager()`	礼包系统管理
附魔管理器	`getEnchantManager()`	附魔系统管理
合成管理器	`getRecipeManager()`	合成配方管理
权限管理器	`getPermissionManager()`	权限系统管理
占位符管理器	`getPlaceholder()`	占位符系统管理
钩子管理器	`getHookManager()`	插件钩子管理

配置与本地化

配置文件

CMI 使用多层配置系统：

config.yml – 主配置文件
模块配置 – 各模块独立配置文件
消息文件 – 本地化消息配置

本地化支持

CMI 支持多语言，包含在 Locale/ 目录中：

// 获取本地化消息
String message = cmi.getLocaleManager().getMessage("prefix") +
                 cmi.getLocaleManager().getMessage("noPermission");

player.sendMessage(message);

构建与部署

构建要求

JDK 版本: 21
构建工具: Maven
Spigot API: 1.20.4-R0.1-SNAPSHOT

构建命令

mvn clean package

输出文件

构建后生成的 JAR 文件格式：CMI-API9.7.14.3.jar

许可证与限制

许可证条款

CMI-API 使用自定义许可证，包含以下限制：

使用限制: 代码仅限用于 Zrips 维护的插件，或获得其明确许可的插件
分发限制: 禁止在未授权的情况下分发或修改代码
版权声明: © 2022, Zrips#9691

合规建议

在商业项目中使用前，请咨询作者获取许可
遵守许可证条款，避免法律风险
参考官方文档获取最新许可信息

最佳实践

1. 错误处理

try {
    CMIUser user = cmi.getPlayerManager().getUser(player);
    if (user != null) {
        // 操作玩家数据
    }
} catch (Exception e) {
    // 记录错误日志
    e.printStackTrace();
}

2. 性能优化

// 避免频繁获取管理器实例
EconomyManager economy = cmi.getEconomyManager();

// 批量操作玩家数据
for (Player player : players) {
    CMIUser user = cmi.getPlayerManager().getUser(player);
    // 执行操作
}

3. 异步操作

// 对于耗时操作，使用异步任务
Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
    CMIUser user = cmi.getPlayerManager().getUser(uuid);
    // 执行数据库操作
    Bukkit.getScheduler().runTask(plugin, () -> {
        // 返回主线程更新UI
    });
});

常见问题

Q1: 如何检查 CMI 是否已安装？

public boolean isCMIAvailable() {
    try {
        Class.forName("com.Zrips.CMI.CMI");
        return Bukkit.getPluginManager().getPlugin("CMI") != null;
    } catch (ClassNotFoundException e) {
        return false;
    }
}

Q2: 如何处理玩家不存在的情况？

CMIUser user = cmi.getPlayerManager().getUser(player);
if (user == null || !user.isOnline()) {
    // 玩家不在线或不存在
    return;
}

Q3: 如何获取所有在线玩家数据？

for (Player player : Bukkit.getOnlinePlayers()) {
    CMIUser user = cmi.getPlayerManager().getUser(player);
    if (user != null) {
        // 处理玩家数据
    }
}

Q4: 如何监听 CMI 事件？

// 在插件主类中注册监听器
@Override
public void onEnable() {
    Bukkit.getPluginManager().registerEvents(new MyCMIListener(), this);
}

// 创建监听器类
public class MyCMIListener implements Listener {
    @EventHandler
    public void onCMIEvent(CMITeleportEvent event) {
        // 处理事件
    }
}

资源与支持

官方资源

文档: https://www.zrips.net/cmi/api/
GitHub: https://github.com/Zrips/CMI-API
Spigot: https://www.spigotmc.org/resources/content-management-interface.3742/
Discord: Zrips#9691

社区支持

SpigotMC 论坛: CMI 插件讨论区
GitHub Issues: 问题反馈与功能请求
Discord 社区: 开发者交流群组

更新日志

版本 9.7.14.3 (当前)

支持 Minecraft 1.20.4
新增多个事件类型
优化经济系统性能
修复已知问题

版本历史

9.7.x: 主要功能更新，新增模块
9.6.x: 性能优化，Bug 修复
9.5.x: 架构重构，API 改进

总结

CMI-API 是一个功能全面、结构清晰的 Spigot 插件 API，为 Minecraft 服务器开发提供了强大的管理工具集。通过模块化设计和丰富的事件系统，开发者可以轻松扩展 CMI 功能或集成到自己的插件中。

主要优势

功能全面: 涵盖服务器管理的各个方面
模块化设计: 70+ 个独立模块，易于扩展
良好集成: 支持主流 Minecraft 插件
丰富事件: 50+ 个自定义事件，高度可定制
详细文档: 官方文档和示例代码

使用建议

充分阅读文档: 参考官方 API 文档了解最新功能
遵守许可证: 注意使用限制，避免法律问题
测试兼容性: 在生产环境使用前充分测试
参与社区: 通过社区获取支持和更新信息

本文档基于 CMI-API 9.7.14.3 版本编写，最后更新: 2026年1月11日

注意: 本文档仅供参考，具体实现请以官方文档为准。

Overview