API développeur

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 sont indiqués pour chaque module.

Prérequis

BetterStructures nécessite :

Java 21 ou supérieur
Serveur Spigot/Paper
Plugin WorldEdit (dépendance obligatoire)

Dépendances optionnelles :

WorldGuard - Pour les fonctionnalités de protection de régions (nécessite également l'installation d'EliteMobs pour une intégration complète)
EliteMobs - Pour l'intégration de l'apparition de monstres d'élite
MythicMobs - Pour l'intégration des monstres mythiques
Terralith, Iris, Terra, TerraformGenerator - Pour la compatibilité avec les biomes personnalisés

Dépôt public

Maven

<repositories>
    <repository>
        <id>magmaguy-repo-releases</id>
        <name>MagmaGuy's Repository</name>
        <url>https://repo.magmaguy.com/releases</url>
    </repository>
</repositories>

<dependency>
  <groupId>com.magmaguy</groupId>
  <artifactId>BetterStructures</artifactId>
  <version>2.7.7</version>
  <scope>provided</scope>
</dependency>

Consultez le dépôt Maven pour les versions disponibles. L'exemple utilise la version publiée 2.7.7 ; les sources actuelles sont en version 2.7.7. Choisissez la version correspondant au plugin installé.

Gradle

repositories {
  maven {
    name = "magmaguyRepoReleases"
    url = uri("https://repo.magmaguy.com/releases")
  }
}

dependencies {
    compileOnly("com.magmaguy:BetterStructures:2.7.7")
}

Événements

Note : Les événements se trouvent dans com.magmaguy.betterstructures.api

Imports de packages

import com.magmaguy.betterstructures.api.BuildCustomMarkerEvent;
import com.magmaguy.betterstructures.api.BuildPasteCompleteEvent;
import com.magmaguy.betterstructures.api.BuildPlaceEvent;
import com.magmaguy.betterstructures.api.ChestFillEvent;
import com.magmaguy.betterstructures.api.WorldGenerationFinishEvent;
import com.magmaguy.betterstructures.buildingfitter.FitAnything;
import com.magmaguy.betterstructures.modules.ModularWorld;
import com.magmaguy.betterstructures.thirdparty.WorldGuard;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.Location;
import org.bukkit.Material;
import org.bukkit.block.Container;
import org.bukkit.entity.EntityType;
import org.bukkit.inventory.Inventory;
import org.bukkit.inventory.ItemStack;
import java.util.List;

BuildPlaceEvent

Appelé lorsqu'une construction est sur le point d'être placée. Expose, entre autres, les données relatives à la construction qui va être placée et à son emplacement, via l'objet FitAnything.

N'essayez pas de modifier la construction en cours de placement ! Vous pouvez modifier des éléments mineurs, mais changer toute la construction entraînera probablement un mauvais ajustement.

Cet événement est annulable.

ChestFillEvent

Appelé lorsqu'un coffre est rempli. Utilise l'inventaire instantané du conteneur pour stocker en toute sécurité les données à appliquer.

Vous pouvez modifier le butin en utilisant les méthodes addItem() ou removeItem() de l'inventaire instantané du conteneur, obtenu via getContainer().getSnapshotInventory().

Vous pouvez également appeler getTreasureConfigFilename() pour identifier quelle configuration de table de butin a été utilisée pour remplir ce coffre.

Cet événement est annulable.

BuildCustomMarkerEvent

Appelé une fois pour chaque panneau [custom] après le collage des blocs, du butin, des créatures et des entités de la structure. BetterStructures retire d'abord le panneau : le bloc situé à getLocation() est donc de l'air et vous pouvez y placer ce que vous voulez.

getId() - Les lignes 2 à 4 du panneau jointes sans séparateurs, par exemple Zombie_Plus
getLines() - Les lignes 2 à 4 séparément, sans espaces superflus, les lignes vides devenant des chaînes vides
getLocation() - L'emplacement du panneau dans le monde
getFitAnything() - La structure en cours de collage, comme dans BuildPlaceEvent

Cet événement n'est PAS annulable.

BuildPasteCompleteEvent

Appelé une fois qu'une structure ordinaire est entièrement collée, après chaque BuildCustomMarkerEvent qui la concerne. Le collage s'étale sur plusieurs ticks : c'est donc le moment fiable pour travailler sur la structure placée. BuildPlaceEvent est déclenché avant que tout cela ne se produise. Si une étape de finition échoue, par exemple un boss de panneau qui ne peut pas apparaître, le collage s'arrête et cet événement n'est pas déclenché.

getFitAnything() - La structure qui a été collée
getLowestCorner() et getHighestCorner() - Les coins en blocs du schematic collé, en coordonnées du monde, tous deux inclus
getBoundingBox() - L'espace couvert par ces blocs
getContainerLocations() - Chaque coffre, coffre piégé, boîte de Shulker et tonneau du schematic, que BetterStructures l'ait rempli de butin ou non

Cet événement n'est PAS annulable.

WorldGenerationFinishEvent

Appelé lorsqu'un donjon modulaire généré dans son propre monde (isWorldGeneration: true) a fini d'être collé. Les donjons collés dans des mondes existants ne le déclenchent pas. Donne accès à l'objet ModularWorld qui contient toutes les données du monde généré, y compris les points d'apparition, les emplacements des coffres et les points de sortie.

Cet événement n'est PAS annulable.

Vous pouvez accéder aux données du monde via la méthode getModularWorld(). Consultez la section ModularWorld ci-dessous pour toutes les méthodes disponibles.

Exemple d'écouteur d'événements

public class MyBetterStructuresListener implements Listener {

    @EventHandler
    public void onBuildPlace(BuildPlaceEvent event) {
        FitAnything build = event.getFitAnything();
        Location location = build.getLocation();
        // Custom logic here
        // event.setCancelled(true); // To prevent placement
    }

    @EventHandler
    public void onChestFill(ChestFillEvent event) {
        Container container = event.getContainer();
        Inventory inv = container.getSnapshotInventory();
        // Modify inventory here
        inv.addItem(new ItemStack(Material.DIAMOND, 1));
    }

    @EventHandler
    public void onCustomMarker(BuildCustomMarkerEvent event) {
        if (!event.getId().equals("Zombie_Plus")) return;
        // Spawn your own mob at the marker
        event.getLocation().getWorld().spawnEntity(event.getLocation().add(0.5, 0, 0.5), EntityType.ZOMBIE);
    }

    @EventHandler
    public void onPasteComplete(BuildPasteCompleteEvent event) {
        for (Location containerLocation : event.getContainerLocations()) {
            if (!(containerLocation.getBlock().getState() instanceof Container container)) continue;
            // Replace the contents with your own loot
            container.getInventory().clear();
            container.getInventory().addItem(new ItemStack(Material.EMERALD, 3));
        }
    }

    @EventHandler
    public void onWorldGenFinish(WorldGenerationFinishEvent event) {
        ModularWorld world = event.getModularWorld();
        // Access generated world data
        List<Location> spawns = world.getSpawnLocations();
    }
}

Classes clés

FitAnything

La classe FitAnything est la classe instanciée lorsqu'une construction est collée ; elle gère tous les aspects du collage, y compris le remplissage des coffres et l'apparition des monstres.

Méthodes d'accès (getters) disponibles :

getSchematicContainer() - Retourne le conteneur du schematic
getSchematicClipboard() - Retourne l'objet Clipboard de WorldEdit
getSchematicOffset() - Retourne le décalage Vector pour le placement
getLocation() - Retourne le Location de placement

Ces méthodes sont utiles lors de la création de protections de régions personnalisées ou de l'analyse des placements de constructions.

ModularWorld

La classe ModularWorld représente un monde modulaire généré et est fournie via le WorldGenerationFinishEvent. Elle contient toutes les données d'emplacement et les méthodes permettant de faire apparaître des entités et des conteneurs dans le monde généré.

Méthodes clés :

getWorld() - Retourne l'instance Bukkit World
getWorldFolder() - Retourne le dossier File du monde
getCenter() - Retourne le point de départ du donjon, à partir duquel les tranches de difficulté sont mesurées
getHorizontalSize() - Retourne la largeur du donjon en blocs, (2 × radius − 1) × moduleSizeXZ
getDifficultyId(Location) - Retourne l'identifiant de difficulté d'instance EliteMobs d'un emplacement : 2 à moins d'un sixième de la largeur du centre (mesuré comme le plus grand des décalages en X et en Z), 1 à moins d'un tiers, sinon 0
getSpawnLocations() - Retourne tous les emplacements d'apparition marqués (List<Location>)
getChestLocations() - Retourne tous les emplacements d'apparition de coffres (List<Location>)
getBarrelLocations() - Retourne tous les emplacements d'apparition de tonneaux (List<Location>)
getExitLocations() - Retourne tous les emplacements des points de sortie. Notez que ExitLocation est un record imbriqué privé : depuis l'extérieur du plugin, vous ne pouvez conserver le résultat que sous forme de liste avec joker ; il n'existe actuellement aucun type public pour ses éléments.
spawnChests() - Fait apparaître des coffres aux emplacements marqués, retourne List<Block>
spawnBarrels() - Fait apparaître des tonneaux aux emplacements marqués, retourne List<Block>
spawnInaccessibleExitLocations() - Fait apparaître les schematics d'ascenseur supérieurs, retourne List<Location>
spawnAccessibleExitLocations() - Fait apparaître les schematics d'ascenseur inférieurs, retourne List<Location>
spawnOtherEntities() - Au tick suivant, traite les panneaux de pool d'apparition que le collage n'a pas déjà gérés, puis déclenche de nouveau WorldGenerationFinishEvent. Le collage gère normalement lui-même tous les panneaux de pool. L'appeler depuis un écouteur de WorldGenerationFinishEvent le fait se répéter à chaque tick.
spawnInstancedEntities() - Fait apparaître les boss instanciés des pools d'apparition en attente au maxLevel de leur pool, chacun avec l'identifiant de difficulté donné par getDifficultyId, et retourne List<InstancedBossEntity>. Chaque boss porte le nom de fichier du pool d'apparition comme donnée personnalisée sous la clé betterstructures:spawnpool.

WorldGuard

La classe WorldGuard gère les protections de régions WorldGuard. La méthode utilitaire public static ProtectedRegion generateProtectedRegion(FitAnything fitAnything, String regionName) est mise à la disposition des développeurs pour intégrer facilement un schéma de protection de région personnalisé par-dessus BetterStructures.

Autres méthodes utiles :

checkArea(Location, Player) - Vérifie si un emplacement se trouve dans une région protégée par BetterStructures (retourne true si elle est protégée, envoie un message d'avertissement au joueur)
Protect(...) - Crée des régions protégées par programmation
Unprotect(CustomBossEntity) - Supprime la protection de région lorsqu'un boss est tué

Prérequis​

Dépôt public

Maven​

Gradle

Événements

Imports de packages​

BuildPlaceEvent​

ChestFillEvent​

BuildCustomMarkerEvent​

BuildPasteCompleteEvent​

WorldGenerationFinishEvent​

Exemple d'écouteur d'événements

Classes clés

FitAnything​

ModularWorld​

WorldGuard​

Prérequis

Maven

Imports de packages

BuildPlaceEvent

ChestFillEvent

BuildCustomMarkerEvent

BuildPasteCompleteEvent

WorldGenerationFinishEvent

FitAnything

ModularWorld

WorldGuard