💻Developer API

EnchantedMobs 2.0.0 exposes registries for custom abilities, conditions, modifiers, and triggers. Register extensions after EnchantedMobs has enabled.

Maven dependency

<repositories>
    <repository>
        <id>repo-lanink-cn</id>
        <url>https://repo.lanink.cn/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>cn.superiormc.enchantedmobs</groupId>
        <artifactId>plugin</artifactId>
        <version>2.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Add a hard dependency when your plugin requires the API:

depend:
  - EnchantedMobs

Registry keys

Ability, condition, and modifier keys are normalized by:

• converting to lowercase;

• replacing - with _.

My-Ability and my_ability therefore refer to the same key. Registering a duplicate normalized key throws IllegalArgumentException; built-ins are not silently replaced.

Custom ability

Register a factory during onEnable:

@Override
public void onEnable() {
    AbilityManager.abilityManager.register("launch_ring", LaunchRingAbility::new);
}

public final class LaunchRingAbility extends AbstractAbility {

    public LaunchRingAbility(ConfigurationSection section) {
        super("launch_ring", section);
    }

    @Override
    public boolean execute(PowerContext context) {
        Entity target = getTargetEntity(context);
        if (target == null) {
            return false;
        }

        double strength = getDouble("strength", 1.0, context);
        Vector velocity = target.getVelocity();
        velocity.setY(strength);
        target.setVelocity(velocity);
        return false;
    }

    @Override
    public TargetEntityType getDefaultTargetEntityType() {
        return TargetEntityType.TARGET;
    }
}

Returning true requests cancellation of a cancellable trigger event. Most effect abilities return false.

The base class applies common typed conditions, random, cooldown, times, dynamic values, entity selectors, and location offsets.

abilities:
  launch:
    type: launch_ring
    target: TARGET
    strength: 1.4

Custom condition

PowerConditionsManager.powerConditions.register(new PowerConditionIsNamed());

public final class PowerConditionIsNamed extends AbstractPowerCondition {

    public PowerConditionIsNamed() {
        super("is_named");
    }

    @Override
    protected boolean onMatch(ObjectSingleCondition condition) {
        PowerContext context = condition.getContext();
        if (context == null) {
            return false;
        }

        LivingEntity target = context.livingEntity(
                condition.getString("target", "TARGET"),
                EntitySelector.TARGET
        );
        return target != null && target.getCustomName() != null;
    }
}

The base implementation applies the common not: true inversion after onMatch returns.

conditions:
  named-target:
    type: is_named
    target: TARGET

Custom modifier

PowerModifiersManager.powerModifiers.register(
        "minimum_damage",
        MinimumDamageModifier::new
);

public final class MinimumDamageModifier extends AbstractPowerModifier {

    public MinimumDamageModifier(ConfigurationSection section) {
        super("minimum_damage", section);
    }

    @Override
    protected void onApply(PowerContext context) {
        double current = context.result().damage(context.triggerData());
        double minimum = getDouble(
                "value",
                1.0,
                context,
                "original",
                String.valueOf(current)
        );
        context.result().damage(Math.max(current, minimum));
    }
}

The modifier base class evaluates typed conditions, random, and per-path cooldown before onApply.

Manual trigger

A manual trigger lets another plugin expose a custom power section without adapting a Bukkit event.

public final class MyPlugin extends JavaPlugin {

    private ManualTrigger ragePulse;

    @Override
    public void onEnable() {
        TriggerManager manager = EnchantedMobs.instance.getTriggerManager();
        ragePulse = manager.register(this, "rage_pulse");
    }

    public TriggerResult fireRagePulse(
            LivingEntity owner,
            LivingEntity target
    ) {
        TriggerData data = TriggerData.builder(owner)
                .source(owner)
                .skill(owner)
                .target(target)
                .location(target.getLocation())
                .build();

        return EnchantedMobs.instance
                .getTriggerManager()
                .fire(ragePulse, data);
    }

    @Override
    public void onDisable() {
        EnchantedMobs.instance
                .getTriggerManager()
                .unregisterAll(this);
    }
}

The power section key is the trigger's namespaced key. For a plugin named MyPlugin:

'myplugin:rage_pulse':
  conditions:
    close-enough:
      type: distance
      max: 12
  abilities:
    effect:
      type: particle
      particle: ANGRY_VILLAGER

TriggerData.builder(owner) requires an owner. Source, skill, target, block, location, Bukkit event, tick number, and typed extra context values are optional.

TriggerManager.fire evaluates the owner's assigned powers, applies their final result, and returns a TriggerResult containing execution and cancellation state.

Custom event-backed trigger

Advanced integrations may extend AbstractTrigger<E>, provide a unique NamespacedKey and configuration key, declare supported TriggerEventType values, and register it with:

EnchantedMobs.instance
        .getTriggerManager()
        .register(this, customTrigger);

The trigger manager dispatches registered triggers for their event types. Call unregisterAll(plugin) during disable to remove every trigger owned by that plugin.

Lifecycle cleanup

Custom ability, modifier, and condition implementations may override:

public void onUnload()
public void onEntityUnload(UUID entityId)

These hooks are intended for type-wide runtime cleanup during EnchantedMobs reload/unload and tracked entity removal. Do not make cleanup depend on one particular YAML section instance.

Compatibility guidance

• Use scheduler-safe entity operations when supporting Folia.

• Store UUIDs instead of retaining unloaded entity objects.

• Validate that required context entities and result values exist for the trigger.

• Keep published type IDs stable because user YAML depends on them.

• Re-test integrations when the EnchantedMobs API version changes across a major release.