Developer API

Developer API

BetterMob registers a BetterMobAPI Bukkit service. Add depend: [BetterMob] (or softdepend) to your plugin.yml and compile against the jar with provided scope. Everything public is in eu.northsoft.bettermob.api.

Dependency

JitPack (no login):

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

<dependency>
    <groupId>com.github.HyperGaming99</groupId>
    <artifactId>bettermob</artifactId>
    <version>v1.1.5</version> <!-- a release tag -->
    <scope>provided</scope>
</dependency>

GitHub Packages (needs a read:packages token in your settings.xml, server id github):

<repository>
    <id>github</id>
    <url>https://maven.pkg.github.com/HyperGaming99/bettermob</url>
</repository>

<dependency>
    <groupId>eu.northsoft</groupId>
    <artifactId>bettermob</artifactId>
    <version>1.1.5</version>
    <scope>provided</scope>
</dependency>

Using the API

BetterMobAPI api = BetterMobAPI.get();

api.getMobs();                                   // all registered mobs (MobInfo)
api.getMob("zombie_brute");                      // Optional<MobInfo>
api.spawn("zombie_brute", player.getLocation()); // Optional<LivingEntity>
api.isBetterMob(entity);                         // is this one of ours?
api.getMobInfo(entity);                          // Optional<MobInfo>
api.getSkillIds();                               // all skill IDs
api.runSkill("wumpus_wave", player);             // any LivingEntity as caster
api.runSkill("wumpus_wave", caster, trigger);    // with a trigger (target of @trigger)
api.reload();                                    // same as /bettermob reload, living mobs included

MobInfo is a record: id, type, displayName, modelId, health, damage.

Events

BetterMobSpawnEvent and BetterMobDeathEvent (package eu.northsoft.bettermob.api.event). Both expose the entity and its MobInfo.

Custom mechanics

Register a mechanic and use it in skill lines like any built-in one:

api.registerMechanic(this, "heal", ctx -> {
    double amount = Double.parseDouble(ctx.params().getOrDefault("amount", "2"));
    if (ctx.target() instanceof LivingEntity living) living.heal(amount);
});

Skills:
  - heal{amount=4} @self ~onDamaged

• Built-in mechanics can't be overridden: registerMechanic returns false.
• unregisterMechanic(name) removes one. Your mechanics are removed automatically when your plugin is disabled.
• The MechanicContext gives you caster, trigger, the cancellable event, the resolved target entity and location, and the line's params (keys are lower case).
• An exception thrown by your mechanic is caught and logged, it doesn't stop the skill.

Example plugin

examples/api-example is a small plugin built on this API: it registers a heal{amount=4} mechanic, listens to BetterMobSpawnEvent and BetterMobDeathEvent and has a /apiexample <mob> command that spawns a mob.

mvn -f examples/api-example/pom.xml package

This resolves com.github.HyperGaming99:bettermob:v1.1.5 from JitPack. To compile it against your own checkout instead:

mvn install -DskipTests
mvn -f examples/api-example/pom.xml -Plocal -Dbettermob.version=<version in pom.xml> package

The workflow builds it that way on every push and pull request, so it keeps compiling with the API.