Saltar al contenido principal

API para desarrolladores

La referencia Java generada permite buscar clases, métodos y firmas, y registra la versión del código fuente y el commit de cada módulo.

Requisitos​

BetterStructures requiere:

  • Java 21 o superior
  • Servidor Spigot/Paper
  • Plugin WorldEdit (dependencia obligatoria)

Dependencias opcionales:

  • WorldGuard - Para funciones de protección de regiones (requiere que EliteMobs también esté instalado para una integración completa)
  • EliteMobs - Para la integración de aparición de mobs élite
  • MythicMobs - Para la integración con mobs míticos
  • Terralith, Iris, Terra, TerraformGenerator - Para compatibilidad con biomas personalizados

Repositorio público

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>

Consulta el repositorio Maven para ver las versiones disponibles. El ejemplo usa la versión publicada 2.7.7; el código actual es 2.7.7. Usa la versión que corresponda al plugin instalado.

Gradle

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

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

Consulta el repositorio Maven para ver las versiones disponibles. El ejemplo usa la versión publicada 2.7.7; el código actual es 2.7.7. Usa la versión que corresponda al plugin instalado.

Eventos

Nota: Los eventos se encuentran en com.magmaguy.betterstructures.api

Importaciones de paquetes​

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​

Se llama cuando una construcción está a punto de ser colocada. Expone datos sobre qué construcción se va a colocar y dónde, entre otras cosas, a través del objeto FitAnything.

¡No intentes modificar la construcción que se está colocando! Puedes modificar cosas menores, pero cambiar la construcción completa probablemente resultará en una construcción con un mal ajuste.

Este evento es cancelable.

ChestFillEvent​

Se llama cuando se llena un cofre. Utiliza el inventario snapshot del contenedor para almacenar de forma segura los datos que se aplicarán.

Puedes modificar el botín usando los métodos addItem() o removeItem() de Inventory sobre el inventario snapshot del contenedor obtenido mediante getContainer().getSnapshotInventory().

También puedes llamar a getTreasureConfigFilename() para identificar qué configuración de tabla de botín se usó para llenar este cofre.

Este evento es cancelable.

BuildCustomMarkerEvent​

Se llama una vez por cada cartel [custom] después de pegar los bloques, el botín, los mobs y las entidades de la estructura. BetterStructures elimina antes el cartel, así que el bloque en getLocation() es aire y puedes colocar ahí lo que quieras.

  • getId() - Las líneas 2-4 del cartel unidas sin separadores, por ejemplo Zombie_Plus
  • getLines() - Las líneas 2-4 por separado, recortadas, con las líneas vacías como cadenas vacías
  • getLocation() - La ubicación del cartel en el mundo
  • getFitAnything() - La estructura que se está pegando, como en BuildPlaceEvent

Este evento NO es cancelable.

BuildPasteCompleteEvent​

Se llama cuando una estructura normal se ha pegado por completo, después de todos sus BuildCustomMarkerEvent. El pegado se reparte entre varios ticks, así que este es el momento fiable para trabajar con la estructura colocada. BuildPlaceEvent se emite antes de que ocurra nada de esto. Si falla un paso final, por ejemplo un jefe de cartel que no puede aparecer, el pegado se detiene y este evento no se emite.

  • getFitAnything() - La estructura que se pegó
  • getLowestCorner() y getHighestCorner() - Las esquinas de bloques del schematic pegado en coordenadas del mundo, ambas inclusivas
  • getBoundingBox() - El espacio que ocupan esos bloques
  • getContainerLocations() - Todos los cofres, cofres trampa, cajas de shulker y barriles del schematic, tanto si BetterStructures los llenó de botín como si no

Este evento NO es cancelable.

WorldGenerationFinishEvent​

Se llama cuando una mazmorra modular generada en su propio mundo (isWorldGeneration: true) termina de pegarse. Las mazmorras pegadas en mundos existentes no lo emiten. Proporciona acceso al objeto ModularWorld que contiene todos los datos sobre el mundo generado, incluyendo puntos de aparición, ubicaciones de cofres y puntos de salida.

Este evento NO es cancelable.

Puedes acceder a los datos del mundo a través del método getModularWorld(). Consulta la sección ModularWorld más abajo para ver todos los métodos disponibles.

Ejemplo de receptor de eventos

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();
    }
}

Clases clave

FitAnything​

La clase FitAnything es la clase que se instancia cuando se pega una construcción y gestiona todos los aspectos del pegado, incluyendo el llenado de cofres y la aparición de mobs.

Métodos getter disponibles:

  • getSchematicContainer() - Devuelve el contenedor del schematic
  • getSchematicClipboard() - Devuelve el objeto Clipboard de WorldEdit
  • getSchematicOffset() - Devuelve el desplazamiento Vector para la colocación
  • getLocation() - Devuelve la Location de colocación

Estos métodos son útiles al crear protecciones de región personalizadas o al analizar colocaciones de construcciones.

ModularWorld​

La clase ModularWorld representa un mundo modular generado y se proporciona a través del WorldGenerationFinishEvent. Contiene todos los datos de ubicación y métodos para generar entidades y contenedores en el mundo generado.

Métodos clave:

  • getWorld() - Devuelve la instancia World de Bukkit
  • getWorldFolder() - Devuelve la carpeta File del mundo
  • getCenter() - Devuelve el punto de inicio de la mazmorra, desde el que se miden las franjas de dificultad
  • getHorizontalSize() - Devuelve el ancho de la mazmorra en bloques, (2 × radius − 1) × moduleSizeXZ
  • getDifficultyId(Location) - Devuelve el ID de dificultad de instancia de EliteMobs para una ubicación: 2 a menos de un sexto del ancho desde el centro (medido como el mayor de los desplazamientos en X y Z), 1 a menos de un tercio y 0 en cualquier otro caso
  • getSpawnLocations() - Devuelve todas las ubicaciones de aparición marcadas (List<Location>)
  • getChestLocations() - Devuelve todas las ubicaciones de aparición de cofres (List<Location>)
  • getBarrelLocations() - Devuelve todas las ubicaciones de aparición de barriles (List<Location>)
  • getExitLocations() - Devuelve todas las ubicaciones de puntos de salida. Ten en cuenta que ExitLocation es un record anidado privado, así que desde fuera del plugin solo puedes conservar el resultado como una lista con comodín; actualmente no hay un tipo público para sus elementos.
  • spawnChests() - Genera cofres en las ubicaciones marcadas, devuelve List<Block>
  • spawnBarrels() - Genera barriles en las ubicaciones marcadas, devuelve List<Block>
  • spawnInaccessibleExitLocations() - Genera schematics de ascensor superior, devuelve List<Location>
  • spawnAccessibleExitLocations() - Genera schematics de ascensor inferior, devuelve List<Location>
  • spawnOtherEntities() - En el siguiente tick, procesa los carteles de grupos de aparición que el pegado aún no haya gestionado y después vuelve a emitir WorldGenerationFinishEvent. Normalmente el pegado gestiona por sí mismo todos los carteles de grupos. Llamarlo desde un listener de WorldGenerationFinishEvent hace que se repita en cada tick.
  • spawnInstancedEntities() - Genera los jefes instanciados de grupos de aparición que están en cola con el maxLevel de su grupo, cada uno con el ID de dificultad de getDifficultyId, y devuelve List<InstancedBossEntity>. Cada jefe lleva el nombre de archivo del grupo de aparición como dato personalizado bajo la clave betterstructures:spawnpool.

WorldGuard​

La clase WorldGuard gestiona las protecciones de región de WorldGuard. El método utilitario public static ProtectedRegion generateProtectedRegion(FitAnything fitAnything, String regionName) está disponible para que los desarrolladores puedan integrar fácilmente un esquema de protección de regiones personalizado sobre BetterStructures.

Otros métodos útiles:

  • checkArea(Location, Player) - Comprueba si una ubicación está en una región protegida por BetterStructures (devuelve true si está protegida, envía un mensaje de advertencia al jugador)
  • Protect(...) - Crea regiones protegidas programáticamente
  • Unprotect(CustomBossEntity) - Elimina la protección de la región cuando se mata a un jefe