Doc ID: SIRC-069

LevelledMobs API 文档

LevelledMobs 是一个 Minecraft 服务器插件，用于为怪物添加等级系统，提供 RPG 风格的怪物升级体验。该插件支持高度自定义的等级策略和修改器。

Overview

LevelledMobs API 文档

概述

LevelledMobs 是一个 Minecraft 服务器插件，用于为怪物添加等级系统，提供 RPG 风格的怪物升级体验。该插件支持高度自定义的等级策略和修改器。

包结构

  • 主包: io.github.arcaneplugins.levelledmobs
  • 事件包: io.github.arcaneplugins.levelledmobs.events
  • 自定义掉落包: io.github.arcaneplugins.levelledmobs.customdrops
  • 枚举包: io.github.arcaneplugins.levelledmobs.enums
  • 管理器包: io.github.arcaneplugins.levelledmobs.managers
  • 规则包: io.github.arcaneplugins.levelledmobs.rules
  • 策略包: io.github.arcaneplugins.levelledmobs.rules.strategies
  • 工具包: io.github.arcaneplugins.levelledmobs.util
  • 包装器包: io.github.arcaneplugins.levelledmobs.wrappers

核心 API 接口

LevelInterface

这是 API 中使用的主要接口，暴露了使用通用类来应用和修改 LevelledMobs 主要功能的方法。

主要方法：

  • getLevellableState(LivingEntity livingEntity): LevellableState – 检查现有怪物是否允许被等级化
  • getLevelOfMob(LivingEntity livingEntity): Int – 获取等级化怪物的等级
  • getMobNametag(LivingEntity livingEntity): String? – 获取怪物的名称标签
  • isLevelled(LivingEntity livingEntity): Boolean – 检查 LivingEntity 是否是等级化怪物
  • removeLevel(LivingEntity livingEntity) – 移除怪物的等级

LevelInterface2

扩展了 LevelInterface，为 LM 本身和其他插件提供全局接口来应用和修改 LevelledMobs 的主要功能。

扩展方法：

  • applyLevelToMob(lmEntity: LivingEntityWrapper, level: Int, isSummoned: Boolean, bypassLimits: Boolean, additionalLevelInformation: MutableSet<AdditionalLevelInformation>?) – 将等级应用到目标怪物
  • generateLevel(lmEntity: LivingEntityWrapper): Int – 为怪物生成等级
  • generateLevel(lmEntity: LivingEntityWrapper, minLevel: Int, maxLevel: Int): Int – 在指定范围内为怪物生成等级

事件系统

MobPreLevelEvent

在怪物被等级化之前触发的事件。注意：当使用 /lm summon 命令生成怪物时不会触发此事件。

构造函数：

MobPreLevelEvent(
    val entity: LivingEntity,
    var level: Int,
    val levelCause: MobPreLevelEvent.LevelCause,
    val additionalInformation: MutableSet<AdditionalLevelInformation>?
) : Event, Cancellable

MobPostLevelEvent

在怪物被等级化之后触发的事件。其他插件可以取消此事件。

构造函数：

MobPostLevelEvent(
    val lmEntity: LivingEntityWrapper,
    val levelCause: MobPostLevelEvent.LevelCause,
    val additionalInformation: MutableSet<AdditionalLevelInformation>?
) : Event

SummonedMobPreLevelEvent

在怪物被等级化之前触发的事件，但仅当使用 /lm summon 命令生成怪物时触发。

构造函数：

SummonedMobPreLevelEvent(
    val entity: LivingEntity,
    var level: Int
) : Event, Cancellable

自定义掉落系统

核心类

CustomDropInstance

保存一个怪物或组实例，并将其与自定义掉落物品列表关联。这是为怪物/组设置覆盖的地方。

CustomDropItem

保存为自定义掉落物品设置的所有属性。

ExternalCustomDrops

为第三方插件提供添加自定义掉落的接口。

ExternalCustomDropsImpl

允许第三方直接将自定义掉落添加到 LevelledMobs。

自定义掉落集成示例

private void testCustomDrops() {
    ItemStack itemStack = new ItemStack(Material.NETHERITE_SWORD);
    ItemMeta meta = itemStack.getItemMeta();
    assert meta != null;
    meta.setDisplayName("Cool Netherite Sword");
    meta.setLore(List.of("Created via API"));
    itemStack.setItemMeta(meta);
    
    LevelledMobs lm = LevelledMobs.getInstance();
    CustomDropItem customDropItem = new CustomDropItem(lm);
    customDropItem.setItemStack(itemStack);
    customDropItem.chance = 1.0F;
    customDropItem.equippedSpawnChance = 1.0F;
    
    final CustomDropInstance customDropInstance = new CustomDropInstance(EntityType.ZOMBIE);
    customDropInstance.customItems.add(customDropItem);
    lm.customDropsHandler.externalCustomDrops.addCustomDrop(customDropInstance);
}

枚举类型

LevellableState

怪物是否允许被等级化的状态枚举：

  • ALLOWED – 允许
  • DENIED_FORCE_BLOCKED_ENTITY_TYPE – 强制阻止的实体类型
  • DENIED_CONFIGURATION_BLOCKED_ENTITY_TYPE – 配置阻止的实体类型
  • DENIED_CONFIGURATION_COMPATIBILITY_MYTHIC_MOBS – MythicMobs 兼容性配置阻止
  • DENIED_CONFIGURATION_COMPATIBILITY_ELITE_MOBS – EliteMobs 兼容性配置阻止
  • DENIED_CONFIGURATION_COMPATIBILITY_SIMPLEPETS – SimplePets 兼容性配置阻止
  • DENIED_CONFIGURATION_COMPATIBILITY_ELITE_BOSSES – EliteBosses 兼容性配置阻止
  • DENIED_EXTERNAL_PLUGIN – 外部插件阻止
  • DENIED_CONFIGURATION_CONDITION_NAMETAGGED – 名称标签条件配置阻止
  • DENIED_NO_APPLICABLE_RULES – 没有适用的规则
  • DENIED_OTHER – 其他原因阻止
  • DENIED_LEVEL_0 – 等级为 0

Addition

属性加成类型枚举：

  • ATTRIBUTE_MOVEMENT_SPEED – 移动速度
  • ATTRIBUTE_ATTACK_DAMAGE – 攻击伤害
  • ATTRIBUTE_MAX_HEALTH – 最大生命值
  • CUSTOM_RANGED_ATTACK_DAMAGE – 自定义远程攻击伤害
  • CUSTOM_ITEM_DROP – 自定义物品掉落
  • CUSTOM_XP_DROP – 自定义经验掉落
  • CREEPER_BLAST_DAMAGE – 苦力怕爆炸伤害
  • ATTRIBUTE_ARMOR_BONUS – 护甲加成
  • ATTRIBUTE_ARMOR_TOUGHNESS – 护甲韧性
  • ATTRIBUTE_ATTACK_KNOCKBACK – 攻击击退
  • ATTRIBUTE_FLYING_SPEED – 飞行速度
  • ATTRIBUTE_KNOCKBACK_RESISTANCE – 击退抗性
  • ATTRIBUTE_HORSE_JUMP_STRENGTH – 马跳跃强度
  • ATTRIBUTE_ZOMBIE_SPAWN_REINFORCEMENTS – 僵尸生成增援
  • ATTRIBUTE_FOLLOW_RANGE – 跟随范围

StrategyType

等级策略类型枚举：

  • RANDOM – 随机
  • WEIGHTED_RANDOM – 加权随机
  • RANDOM_VARIANCE – 随机方差
  • Y_COORDINATE – Y坐标
  • CUSTOM – 自定义
  • SPAWN_DISTANCE – 生成距离
  • PLAYER_VARIABLE – 玩家变量

主要管理器

LevelManager

等级管理器，继承自 LevelInterface2，负责处理怪物的等级化逻辑。

CustomDropsHandler

自定义掉落处理器，包含用于解析、实例化自定义掉落物品的有用函数。

ExternalCompatibilityManager

外部兼容性管理器，处理与其他插件的兼容性。

包装器类

LivingEntityWrapper

LivingEntity 的包装器，提供额外的功能和方法。

实用工具

获取怪物等级（不使用 API）

怪物等级存储在持久数据容器（PDC）中。您可以使用以下代码获取等级而不使用 LevelledMobs API：

简化解决方案：

public int getMobLevel(LivingEntity livingEntity) {
    Plugin levelledMobsPlugin = Bukkit.getPluginManager().getPlugin("LevelledMobs");
    if (levelledMobsPlugin == null) return 0;
    NamespacedKey levelKey = new NamespacedKey(levelledMobsPlugin, "level");
    return Objects.requireNonNullElse(
        livingEntity.getPersistentDataContainer().get(levelKey, PersistentDataType.INTEGER),
        0
    );
}

优雅解决方案：

public class LevelledMobsManager {
    private final Boolean levelledMobsIsInstalled;
    private NamespacedKey key;
    
    public LevelledMobsManager() {
        Plugin levelledMobsPlugin = Bukkit.getPluginManager().getPlugin("LevelledMobs");
        levelledMobsIsInstalled = levelledMobsPlugin != null && levelledMobsPlugin.isEnabled();
        if (levelledMobsIsInstalled) {
            key = new NamespacedKey(levelledMobsPlugin, "level");
        }
    }
    
    public boolean hasLevelledMobsInstalled() {
        return levelledMobsIsInstalled != null && levelledMobsIsInstalled;
    }
    
    public int getLevelledMobsMobLevel(Entity entity) {
        if (!hasLevelledMobsInstalled()) return 0;
        Integer mobLevel = entity.getPersistentDataContainer().get(key, PersistentDataType.INTEGER);
        return Objects.requireNonNullElse(mobLevel, 0);
    }
}

插件集成指南

1. 获取 LevelledMobs 实例

LevelledMobs lm = LevelledMobs.getInstance();

2. 检查怪物是否可等级化

LevellableState state = lm.getLevellableState(livingEntity);
if (state == LevellableState.ALLOWED) {
    // 怪物可以等级化
}

3. 获取怪物等级

int level = lm.getLevelOfMob(livingEntity);

4. 监听等级化事件

@EventHandler
public void onMobPreLevel(MobPreLevelEvent event) {
    // 在怪物等级化之前执行操作
    // 可以修改 event.level 或取消事件
}

@EventHandler
public void onMobPostLevel(MobPostLevelEvent event) {
    // 在怪物等级化之后执行操作
}

5. 添加自定义掉落

// 创建自定义掉落物品
CustomDropItem customDropItem = new CustomDropItem(lm);
customDropItem.setItemStack(yourItemStack);
customDropItem.chance = 0.5F; // 50% 掉落几率

// 创建掉落实例
CustomDropInstance customDropInstance = new CustomDropInstance(EntityType.ZOMBIE);
customDropInstance.customItems.add(customDropItem);

// 注册掉落
lm.customDropsHandler.externalCustomDrops.addCustomDrop(customDropInstance);

版本信息

  • 当前文档版本：4.0.3.1
  • 支持 Minecraft 版本：1.20 – 1.21+
  • 支持服务器软件：PaperMC, Spigot, Purpur, Folia

注意事项

  1. 所有 API 调用应在服务器线程上执行
  2. 事件处理应遵循 Bukkit 事件系统的最佳实践
  3. 自定义掉落集成应确保线程安全
  4. 持久数据容器（PDC）是存储怪物等级的主要方式