Doc ID: SIRC-101

MMOItems 基础 API 知识文档

MMOItems 是一个 Minecraft 插件，提供高级物品系统，包含自定义物品、技能、套装效果等功能。本文档基于 MMOItems-API 模块的源代码分析，重点关注 API 用法和包结构。

Overview

MMOItems API 文档

概述

MMOItems 是一个 Minecraft 插件，提供高级物品系统，包含自定义物品、技能、套装效果等功能。本文档基于 MMOItems-API 模块的源代码分析，重点关注 API 用法和包结构。

包结构

基础包

  • net.Indyuce.mmoitems.api – 核心 API 包

子包

  • net.Indyuce.mmoitems.api.block – 方块相关功能
  • net.Indyuce.mmoitems.api.crafting – 合成系统
  • net.Indyuce.mmoitems.api.droptable – 掉落表系统
  • net.Indyuce.mmoitems.api.edition – 物品编辑功能
  • net.Indyuce.mmoitems.api.event – 事件系统
  • net.Indyuce.mmoitems.api.interaction – 交互系统
  • net.Indyuce.mmoitems.api.item – 物品核心功能
  • net.Indyuce.mmoitems.api.player – 玩家数据管理
  • net.Indyuce.mmoitems.api.recipe/workbench/ingredients – 配方和工作台系统
  • net.Indyuce.mmoitems.api.util – 工具类
  • net.Indyuce.mmoitems.api.world – 世界相关功能

核心 API 类

1. MMOItemsAPI

主 API 入口类，提供插件间集成的主要功能。

构造函数

public MMOItemsAPI(JavaPlugin plugin)
  • plugin: 使用 API 的插件实例

主要方法

注册技能

public void registerSkill(RegisteredSkill skill)
  • 在 MMOItems 中注册一个技能
  • 必须在 MMOItems 启用前调用（在 onLoad() 中）
  • 不注册监听器，仅注册技能定义

获取技能

public RegisteredSkill getSkillById(String id)
  • 通过 ID 获取已注册的技能（如 "FIREBOLT"）
  • 如果找不到技能会抛出异常

获取玩家数据

public PlayerData getPlayerData(Player player)
  • 获取指定玩家的 PlayerData 对象

获取 RPG 信息

public RPGPlayer getRPGInfo(Player player)
  • 获取玩家的 RPG 信息（等级、属性等）

施放技能

public SkillResult castSkill(Player player, RegisteredSkill skill, 
                           @NotNull Map<String, Double> modifiers, 
                           @Nullable LivingEntity target, 
                           @Nullable AttackMetadata attackMeta)
  • 强制玩家对特定目标施放技能
  • player: 施放技能的玩家
  • skill: 要施放的技能（可通过 getSkillById 获取）
  • modifiers: 技能修饰符映射表（可为空）
  • target: 技能目标（可为 null）
  • attackMeta: 攻击元数据（仅对 ATTACK 类型触发器有用）

2. ConfigFile

配置文件管理类，简化 YAML 配置文件的操作。

构造函数

public ConfigFile(String name)
public ConfigFile(Plugin plugin, String name)
public ConfigFile(String path, String name)
public ConfigFile(Plugin plugin, String path, String name)
  • plugin: 拥有配置文件的插件
  • path: 文件夹路径
  • name: 配置文件名（不含 .yml 扩展名）

主要方法

@NotNull public FileConfiguration getConfig()
public boolean exists()
public void save()
public void setup()
public void registerTemplateEdition(ItemReference ref)

3. CustomSound

自定义音效枚举，定义物品的各种音效触发点。

枚举值

  • ON_ATTACK – 攻击实体时播放
  • ON_RIGHT_CLICK – 右键点击物品时播放
  • ON_BLOCK_BREAK – 用物品破坏方块时播放
  • ON_PICKUP – 从地面拾取物品时播放
  • ON_LEFT_CLICK – 左键点击物品时播放
  • ON_CRAFT – 在合成界面合成或熔炉熔炼时播放
  • ON_CONSUME – 物品被消耗后播放（食用/饮用动画后）
  • ON_ITEM_BREAK – 物品损坏时播放
  • ON_CROSSBOW – 弩发射箭时播放
  • ON_PLACED – 方块被放置时播放

方法

public ItemStack getItem()
public String getName()
public String[] getLore()
public int getSlot()

4. DeathItemsHandler

死亡物品处理器，管理灵魂绑定物品在玩家死亡时的处理。

主要方法

public void registerItem(@NotNull ItemStack item)
public void registerIfNecessary()
public void dropItems()
public void giveItems(@NotNull Player player)
public static void readAndRemove(@NotNull Player player)
@NotNull public static Collection<DeathItemsHandler> getActive()

5. ItemSet

物品套装系统，管理套装效果和加成。

主要功能

  • 支持 2-10 件套的套装效果
  • 支持属性加成、药水效果、技能、粒子效果、权限授予
  • 通过配置文件动态加载套装配置

内部类 SetBonuses

public static class SetBonuses {
    public void addStat(ItemStat<?, ?> stat, double value)
    public void addPotionEffect(PotionEffect effect)
    public void addAbility(AbilityData ability)
    public void addParticle(ParticleData particle)
    public void addPermission(@NotNull String permission)
    public void merge(SetBonuses bonuses)
}

6. ItemTier

物品等级系统，管理物品的稀有度和相关属性。

主要属性

  • 物品名称和 ID
  • 解构掉落表
  • 未鉴定信息
  • 物品发光效果
  • 工具提示纹理
  • 生成几率和容量

内部类 UnidentificationInfo

public static class UnidentificationInfo {
    public UnidentificationInfo(@NotNull ConfigurationSection config)
    public UnidentificationInfo(@NotNull String name, @NotNull String prefix, int range)
    @NotNull public String getPrefix()
    @NotNull public String getDisplayName()
    public int[] calculateRange(int level)
}

静态方法

@Nullable public static ItemTier ofItem(NBTItem item)

API 使用示例

1. 初始化 API

MMOItemsAPI mmoItemsAPI = new MMOItemsAPI(yourPlugin);

2. 注册自定义技能

RegisteredSkill mySkill = new MyCustomSkill();
mmoItemsAPI.registerSkill(mySkill);

3. 获取玩家数据

PlayerData playerData = mmoItemsAPI.getPlayerData(player);
RPGPlayer rpgPlayer = mmoItemsAPI.getRPGInfo(player);

4. 施放技能

RegisteredSkill skill = mmoItemsAPI.getSkillById("FIREBOLT");
Map<String, Double> modifiers = new HashMap<>();
modifiers.put("damage", 50.0);
modifiers.put("range", 10.0);

SkillResult result = mmoItemsAPI.castSkill(player, skill, modifiers, target, attackMeta);

5. 管理配置文件

ConfigFile config = new ConfigFile("my-config");
if (!config.exists()) {
    config.setup();
}
FileConfiguration fileConfig = config.getConfig();
// 使用配置...
config.save();

6. 处理死亡物品

// 在玩家死亡事件中
DeathItemsHandler handler = new DeathItemsHandler(player);
handler.registerItem(soulboundItem);
handler.registerIfNecessary();

// 在玩家重生时
DeathItemsHandler.readAndRemove(player);

依赖关系

MMOItems API 依赖于：

  • MythicLib – 用于技能系统、属性计算等
  • Bukkit/Spigot/Paper API
  • JetBrains Annotations

注意事项

  1. 技能注册时机：必须在 MMOItems 启用前注册技能，建议在插件的 onLoad() 方法中注册。

  2. 线程安全：大部分 API 方法不是线程安全的，应在主线程调用。

  3. 空值处理：API 方法使用 @Nullable 和 @NotNull 注解，调用时应注意空值检查。

  4. 错误处理：API 方法可能抛出 IllegalArgumentException 等异常，建议进行适当的异常处理。

  5. 版本兼容性：API 可能在不同版本间有变化，建议检查具体版本的文档。

扩展点

开发者可以通过以下方式扩展 MMOItems：

  1. 自定义技能：实现 RegisteredSkill 接口
  2. 自定义物品属性：扩展 ItemStat 类
  3. 自定义套装效果：通过配置文件定义
  4. 自定义物品等级：通过配置文件定义
  5. 事件监听：监听 MMOItems 提供的事件

最佳实践

  1. 在插件启用时初始化 MMOItemsAPI 实例
  2. 使用 try-catch 处理可能的异常
  3. 缓存频繁使用的数据（如玩家数据）
  4. 遵循 MMOItems 的命名约定
  5. 测试在不同游戏版本下的兼容性

文档基于 MMOItems-API 模块源代码分析，版本：master 分支（2024年更新）