The rules that keep a consumer plugin correct across upgrades, reloads and both editions.
Epic Mobs holds no locks and does no work off the server thread. Calling in from an async task is undefined and will eventually corrupt the registry.
// Wrong
Bukkit.getScheduler().runTaskAsynchronously(this, () -> {
for (EpicMobHandle mob : api.getEpicMobs()) { ... }
});
// Right
Bukkit.getScheduler().runTaskAsynchronously(this, () -> {
List<Row> rows = database.query(); // slow work off thread
Bukkit.getScheduler().runTask(this, () -> {
for (EpicMobHandle mob : api.getEpicMobs()) { ... } // API work on thread
});
});Every event is fired on the main thread, so a handler is already in the right place.
The provider is installed during Epic Mobs' own enable. A static initialiser, a field initialiser or a constructor that runs before that sees nothing.
// Wrong: runs at class load, before Epic Mobs enabled
private static final EpicMobsAPI API = EpicMobsProvider.get();
// Right
private EpicMobsAPI api;
@Override
public void onEnable() {
this.api = EpicMobsProvider.find().orElse(null);
}provided in Maven, compileOnly in Gradle. Two copies of me.jaymar921.epicmobs.api on
one server, under different class loaders, are two different types, and every cast across
the boundary throws ClassCastException at runtime.
/ep reload rebuilds every definition. Store the key, resolve on use.
// Wrong
private final EpicMobDefinitionView warden = api.getDefinition("crypt warden").orElseThrow();
// Right
private static final String WARDEN = "crypt warden";
api.getDefinition(WARDEN).ifPresent(this::use);Handles to live mobs are fine to keep. So are keys and UUIDs.
Epic Mobs wraps every event it fires and logs what threw, so a badly written listener cannot
take the plugin down. But a handler that throws inside EpicMobDeathEvent still costs that
death whatever your listener was going to do.
@EventHandler
public void onDeath(EpicMobDeathEvent event) {
try {
payBounty(event);
} catch (Exception failed) {
getLogger().warning("Bounty failed: " + failed.getMessage());
}
}| Method | Moves when | Gate on it? |
|---|---|---|
apiVersion() |
the api package changes shape |
yes |
version() |
every plugin release | for display only |
private static final int REQUIRED_API = 1;
if (api.apiVersion() < REQUIRED_API) {
getLogger().severe("Needs Epic Mobs API v" + REQUIRED_API
+ ", server has v" + api.apiVersion() + ". Disabling.");
getServer().getPluginManager().disablePlugin(this);
return;
}New methods and new events bump apiVersion(). Compiling against a newer API jar than the
server runs is what produces NoSuchMethodError, so state your minimum and check it.
apiVersion() |
Plugin | Added |
|---|---|---|
| 1 | 1.0-RC1, 1.0.0 | everything on the reference page except the row below |
| 2 | 1.1.0, 1.2.0 | EpicMobDefinitionView.mythicMob() |
If the only v2 method you touch is mythicMob(), you can keep a v1 minimum and branch on
the version at the call site rather than refusing to enable:
String origin = definition.entityType().name();
if (api.apiVersion() >= 2 && definition.mythicMob().isPresent()) {
origin = "MythicMobs " + definition.mythicMob().get();
}Develop against Lite. Every query and every event works there, so if your plugin only reads and reacts, Lite is a complete test environment.
| Behaves differently in Lite | |
|---|---|
spawn, remove, startRaid, stopRaid |
empty or false |
getRunningArenas() |
always empty |
EpicMobDefinitionView.companionAllowed() |
always false |
EpicMobDefinitionView.phased() |
always false |
RaidView.bossUp() |
always false |
EpicMobHandle.phase() |
always -1 |
Degrade, do not disable:
if (api.canMutate()) {
registerAdminCommands();
} else {
getLogger().info("Epic Mobs Lite detected. Admin spawning is off, "
+ "tracking and rewards are on.");
}isEpicMob is one hash lookup and safe in a hot listener. getEpicMobs() builds a snapshot
collection, so it is not.
// Wrong: allocates the whole world's mobs on every hit
@EventHandler
public void onDamage(EntityDamageEvent event) {
for (EpicMobHandle mob : api.getEpicMobs()) {
if (mob.id().equals(event.getEntity().getUniqueId())) { ... }
}
}
// Right
@EventHandler
public void onDamage(EntityDamageEvent event) {
api.getEpicMob(event.getEntity()).ifPresent(mob -> { ... });
}Order your handler's checks cheapest first, and prefer the narrower query:
| Instead of | Use |
|---|---|
iterating getEpicMobs() to find one entity |
getEpicMob(entity) |
iterating getEpicMobs() filtering on key |
getEpicMobs(key) |
iterating getDefinitions() to find one |
getDefinition(nameOrKey) |
calling getEpicMobs() every tick |
call it on a repeating task at 20 ticks or slower |
| Can be null | Never null |
|---|---|
EpicMobDamageEvent.getAttacker() |
EpicMobHandle.entity() |
EpicMobDeathEvent.getKiller() |
anything returning Optional |
EpicMobLootDropEvent.getKiller() |
any Collection or List returned |
EpicMobHandle.owner() |
|
RaidView.centre() |
entity() is never null but may be dead or removed. Check alive() or isValid().
- The API jar is
providedorcompileOnly, not shaded -
softdepend: [ EpicMobsRework ](ordepend) is in yourplugin.yml - The API is resolved in
onEnable, not in a field or static initialiser - Your plugin logs a clear line when Epic Mobs is absent, and does not crash
- No API call happens off the main thread
- No
EpicMobDefinitionViewis held in a field - Every handler that can throw is wrapped
- Hot handlers filter before they work
-
canMutate()gates anything that spawns, removes or starts a raid - Tested with the plugin present, absent, and after a
/ep reload