API Java d'EliteMobs
La référence Java générée permet de rechercher les classes, méthodes et signatures. La version des sources et le commit utilisés sont indiqués pour chaque module.
Ce guide concerne l'API EliteMobs 10.9. La version Maven publique actuelle est com.magmaguy:EliteMobs:10.9.13. Utilisez la portée provided ou compileOnly et déclarez depend: [EliteMobs]. Choisissez la dépendance correspondant au plugin installé. L'index développeur présente la configuration Maven et Gradle.
Points d'entrée
| Package ou type | Rôle |
|---|---|
com.magmaguy.elitemobs.api | Événements Bukkit pour le combat, les quêtes, les PNJ, les téléportations, les donjons et l'initialisation |
com.magmaguy.elitemobs.api.instanced | Événements du cycle de vie des parties instanciées |
com.magmaguy.elitemobs.api.utils.EliteItemManager | Utilitaires d'identification, de niveau, de dégâts et de défense des objets élites |
com.magmaguy.elitemobs.entitytracker.EntityTracker | Retrouve l'entité EliteMobs suivie à partir d'une entité Bukkit |
com.magmaguy.elitemobs.api.power.EliteLuaPowerService | Enregistre et attache des pouvoirs Lua via le moteur d'exécution EliteMobs |
com.magmaguy.elitemobs.api.mind.EliteMindService | Enregistre des programmes Lua Mind et fait apparaître des acteurs qui les exécutent |
EliteEntity, CustomBossEntity et RegionalBossEntity représentent des acteurs actifs gérés par le plugin. Ils exposent davantage de détails d'implémentation que les contrats des événements. Ne conservez leurs références que tant que l'acteur existe et évitez de modifier directement les collections du système de suivi.
Écouter les gains d'XP de compétence
Cette classe complète de plugin annule les gains d'XP de compétence de combat des joueurs possédant la permission example.blockskillxp de votre intégration. Indiquez son nom de classe pleinement qualifié comme valeur de main dans votre propre plugin.yml.
package example;
import com.magmaguy.elitemobs.api.EliteSkillXpGainEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;
public final class SkillXpIntegration extends JavaPlugin implements Listener {
@Override
public void onEnable() {
getServer().getPluginManager().registerEvents(this, this);
}
@EventHandler(ignoreCancelled = true)
public void onSkillXp(EliteSkillXpGainEvent event) {
if (event.getPlayer().hasPermission("example.blockskillxp")) {
event.setCancelled(true);
}
}
}
EliteSkillXpGainEvent s'exécute de façon synchrone après les vérifications d'admissibilité au combat et les multiplicateurs natifs ou liés aux permissions. getOriginalXp() donne la quantité lors de la création de l'événement ; getXp() inclut les modifications des écouteurs précédents. setXp(long) refuse les valeurs négatives. L'annulation ou une quantité finale nulle supprime le gain et sa notification.
EliteMobs applique la quantité acceptée, assure sa persistance et déclenche les effets de montée de niveau. N'écrivez pas séparément l'XP du joueur depuis cet écouteur. Les modifications administratives d'XP et l'XP de classe suivent des chemins distincts et ne correspondent pas au gain de compétence de combat représenté par cet événement.
Les autres événements ont leurs propres contrats. En particulier, annuler EliteMobSpawnEvent empêche la construction et supprime l'entité vivante sous-jacente ; cela ne laisse pas un mob ordinaire à sa place. EliteMobDeathEvent et EliteMobRemoveEvent décrivent des transitions différentes du cycle de vie. Vérifiez l'événement et le code qui le déclenche avant d'assimiler toute suppression à une mort ou à une récompense.
Retrouver une entité suivie
EliteEntity elite = EntityTracker.getEliteMobEntity(bukkitEntity);
if (elite == null) {
return;
}
Importez com.magmaguy.elitemobs.entitytracker.EntityTracker et com.magmaguy.elitemobs.mobconstructor.EliteEntity. La recherche peut renvoyer null : une entité Bukkit n'est pas nécessairement un EliteMob actuellement suivi. Fournissez une entité Bukkit existante et non nulle, et effectuez cette recherche sur le thread du serveur.
Pour l'équipement, commencez par EliteItemManager.isEliteMobsItem(itemStack), puis utilisez l'utilitaire correspondant à la valeur recherchée, par exemple getItemLevel, getEliteDefense ou getTotalDPS. Ces valeurs sont distinctes : le niveau d'un objet ne correspond pas à ses dégâts finaux. Vérifiez la gestion de null de chaque méthode au lieu de supposer qu'elles acceptent toutes un objet vide.
Initialisation et rechargements
EliteMobs réalise une initialisation asynchrone, puis une initialisation sur le thread du serveur. EliteMobsInitializedEvent est déclenché après la réussite de cette séquence, y compris lors d'un rechargement. Enregistrez vos écouteurs assez tôt pour le recevoir. Les intégrations activées après cet événement doivent également gérer le cas où le plugin est déjà initialisé.
Les références d'entités, les attachements et les services en cache peuvent devenir périmés pendant un rechargement. Récupérez de nouveau les objets nécessaires à votre intégration à la fin de l'initialisation. N'appelez pas onEnable, onDisable ni l'arrêt de MagmaCore pour le compte d'EliteMobs.
Intégration des pouvoirs Lua
Récupérez le service via Bukkit après l'initialisation d'EliteMobs :
EliteLuaPowerService powers = Bukkit.getServicesManager()
.load(EliteLuaPowerService.class);
if (powers == null) {
return;
}
Importez org.bukkit.Bukkit et com.magmaguy.elitemobs.api.power.EliteLuaPowerService. Si le service est absent, considérez-le comme indisponible au lieu de construire vous-même son implémentation.
registerLuaPower(owner, key, revision, source) enregistre un programme appartenant à votre plugin. setPowers(owner, eliteEntity, orderedPowerKeys) remplace l'ensemble des pouvoirs de l'acteur par de nouvelles instances d'exécution, dans l'ordre fourni. Chaque clé doit appartenir à ce propriétaire et les doublons sont refusés. Cette opération n'ajoute pas simplement des pouvoirs à ceux que le boss possède déjà. La distribution des événements exécute les pouvoirs par executionPriority() croissante et n'utilise l'ordre fourni que pour départager les égalités.
inspectPowers renvoie les programmes gérés par le service dans leur ordre d'attachement. inspectPowerActivity expose leur activité à l'exécution. unregisterOwner(owner) retire les entrées du catalogue de ce propriétaire et détache ses instances d'exécution des acteurs actifs ; utilisez cette méthode à la désactivation de votre intégration, tant que le service reste disponible.
Toutes les modifications s'effectuent sur le thread du serveur. Le service évite volontairement d'exposer les types de script MagmaCore entre les chargeurs de classes des plugins. Fournissez les types de l'API EliteMobs, plutôt que des objets provenant d'une copie privée de MagmaCore intégrée à votre JAR.
Pour écrire des hooks et du contenu Lua, consultez la référence de script partagée. Le service Java coordonne les attachements et leur propriété ; EliteMobs reste responsable du cycle de vie des pouvoirs.
Programmes Lua Mind
com.magmaguy.elitemobs.api.mind.EliteMindService exécute une IA écrite en Lua sur les acteurs EliteMobs. Récupérez-le via le gestionnaire de services de Bukkit après EliteMobsInitializedEvent, comme le service de pouvoirs. EliteMobs ne l'enregistre que si l'adaptateur NMS du serveur peut héberger des Minds natifs ; sinon, la recherche renvoie null.
Enregistrez les modules avec registerLuaModule(owner, key, revision, source) avant les programmes qui les utilisent, puis enregistrez les programmes avec registerLuaProgram. L'espace de noms de chaque clé doit appartenir à votre plugin, et l'identifiant et la révision de la définition Lua doivent correspondre à la clé et à la révision que vous transmettez. L'identifiant d'un programme ne peut pas être celui de l'un de ses modules. Répéter un enregistrement identique n'a aucun effet. Une source modifiée nécessite une révision supérieure. Le format Lua, y compris les settings de module, qu'EliteMobs ne lit pas, est décrit dans Programmes de comportement.
spawn(EliteMindSpawnRequest) crée un acteur sur un corps Mind natif exécutant le programme demandé, à un niveau supérieur ou égal à 1. setProgram remplace le programme d'un acteur qui possède déjà un corps Mind ; il ne convertit pas les élites ordinaires. setPaused suspend et reprend les ticks Mind ainsi que les callbacks de pouvoirs de l'acteur, inspect renvoie l'état actuel et clearProgram supprime l'acteur. registerNaturalSpawnProvider permet à votre plugin de laisser, de supprimer ou de remplacer les apparitions naturelles d'élites avant la conversion aléatoire propre à EliteMobs. unregisterOwner(owner) retire vos modules, programmes et fournisseurs, ainsi que les acteurs qui exécutent encore vos programmes.
Les actions Mind atteignent les pouvoirs attachés à l'acteur via on_mind_action. Les intégrations Java peuvent aussi gérer une action destinée à l'un de leurs pouvoirs avec EliteLuaPowerService.registerActionHandler ; les hooks Lua ont la priorité pour l'accepter. Consultez le contexte d'un programme Mind pour le côté Lua.
Compiler depuis les sources
Le dépôt EliteMobs se compile avec Gradle 9.1.0 et une toolchain JDK 21. Il inclut le wrapper Gradle pour Windows. Depuis la racine du dépôt, exécutez :
.\gradlew.bat shadowJar
Le dépôt n'a pas de script Unix gradlew. Sur les autres systèmes, installez la version de Gradle indiquée dans gradle/wrapper/gradle-wrapper.properties et exécutez gradle shadowJar.
Le plugin déployable est build/libs/EliteMobs.jar. build/libs/EliteMobs-min.jar ne contient que les classes d'EliteMobs et n'est pas un plugin fonctionnel. Si la variable d'environnement MC_DIST_DIR ou la propriété Gradle mcDistDir est définie, le build copie aussi EliteMobs.jar dans ce dossier.
Le jar intègre (shade) MagmaCore, bStats et commons-io. MagmaCore, son runtime Lua, sa bibliothèque reflections et easyminecraftgoals sont relocalisés sous com.magmaguy.elitemobs : EliteMobs possède donc sa propre copie, distincte des autres plugins qui intègrent MagmaCore. bStats est relocalisé sous com.magmaguy.shaded.bstats. Le build résout com.magmaguy:MagmaCore:2.2.0-SNAPSHOT depuis Maven Local avant le dépôt Maven de MagmaGuy ; -PmagmacoreVersion=<version> sélectionne une autre version publiée de MagmaCore. Lorsque les sources nécessitent des changements de MagmaCore plus récents que le build publié, publiez d'abord MagmaCore dans Maven Local, comme décrit dans Recompiler un consommateur après modification de la bibliothèque. Il en va de même pour un FreeMinecraftModels modifié localement, contre lequel le build compile en tant que version 2.12.2.
La tâche test compile et exécute les tests sur une toolchain JDK 25, car l'API de test de Paper nécessite Java 25. Le plugin lui-même cible Java 21.