API para programadores

A referência Java gerada permite pesquisar classes, métodos e assinaturas, com a versão e o commit do código-fonte registados para cada módulo.

Requisitos

O BetterStructures exige:

• Java 21 ou superior
• Servidor Spigot/Paper
• Plugin WorldEdit, dependência obrigatória

Dependências opcionais:

• WorldGuard para proteger regiões; a integração completa também exige EliteMobs
• EliteMobs para criar mobs de elite
• MythicMobs para integrar mobs MythicMobs
• Terralith, Iris, Terra e TerraformGenerator para compatibilidade com biomas personalizados

Repositório 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>

Consulte o repositório Maven para ver as versões disponíveis. O exemplo usa a versão publicada 2.7.7; o código atual está na versão 2.7.7. Escolha a versão correspondente ao plugin instalado.

Gradle

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

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

Consulte o repositório Maven para ver as versões disponíveis. O exemplo usa a versão publicada 2.7.7; o código atual está na versão 2.7.7. Escolha a versão correspondente ao plugin instalado.

Eventos

Os eventos pertencem a com.magmaguy.betterstructures.api.

Importações dos pacotes

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

É disparado antes de colocar uma construção. O objeto FitAnything disponibiliza, entre outros dados, a construção escolhida e a sua posição.

Não tente substituir a construção que vai ser colocada! Pode alterar pequenos detalhes, mas substituir a construção inteira provavelmente causa um encaixe inadequado.

Pode ser cancelado.

ChestFillEvent

É disparado ao preencher um baú. Usa o inventário do snapshot do contentor para guardar os dados a aplicar com segurança.

Pode alterar o saque com addItem() ou removeItem() de Inventory sobre o inventário obtido por getContainer().getSnapshotInventory().

getTreasureConfigFilename() identifica a configuração da tabela usada nesse baú.

Pode ser cancelado.

BuildCustomMarkerEvent

É disparado uma vez por cada placa [custom], depois de colocados os blocos, o saque, os mobs e as entidades da estrutura. O BetterStructures remove primeiro a placa, pelo que o bloco em getLocation() é ar e pode colocar lá qualquer coisa.

• getId(): linhas 2 a 4 da placa unidas sem separadores, por exemplo Zombie_Plus
• getLines(): linhas 2 a 4 individualmente, sem espaços nas extremidades, com as linhas vazias como strings vazias
• getLocation(): a localização da placa no mundo
• getFitAnything(): a estrutura a ser colocada, tal como em BuildPlaceEvent

NÃO pode ser cancelado.

BuildPasteCompleteEvent

É disparado quando uma estrutura normal termina de ser colocada, depois de todos os seus BuildCustomMarkerEvent. A colocação é distribuída por vários ticks, pelo que este é o momento fiável para trabalhar com a estrutura colocada. BuildPlaceEvent é disparado antes de qualquer destes passos. Se um passo de conclusão falhar, por exemplo um boss de placa que não consegue aparecer, a colocação para e este evento não é disparado.

• getFitAnything(): a estrutura que foi colocada
• getLowestCorner() e getHighestCorner(): os cantos de blocos do schematic colocado, em coordenadas do mundo, ambos inclusivos
• getBoundingBox(): o espaço ocupado por esses blocos
• getContainerLocations(): todos os baús, baús armadilhados, caixas de shulker e barris do schematic, quer o BetterStructures os tenha preenchido com saque ou não

NÃO pode ser cancelado.

WorldGenerationFinishEvent

É disparado quando uma masmorra modular gerada no seu próprio mundo (isWorldGeneration: true) termina de ser colocada. As masmorras colocadas em mundos existentes não o disparam. Disponibiliza o objeto ModularWorld com os dados do mundo gerado, incluindo posições iniciais, baús e saídas.

NÃO pode ser cancelado.

Use getModularWorld() para aceder aos dados. Consulte ModularWorld para os métodos disponíveis.

Exemplo de listener

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 principais

FitAnything

FitAnything é instanciada ao colocar uma construção e gere todos os aspetos dessa colocação, incluindo o preenchimento de baús e a criação de mobs.

Getters disponíveis:

• getSchematicContainer(): devolve o contentor do schematic
• getSchematicClipboard(): devolve o objeto Clipboard do WorldEdit
• getSchematicOffset(): devolve o Vector de desvio da colocação
• getLocation(): devolve a Location da colocação

Estes métodos servem para criar proteções de regiões personalizadas ou analisar as posições das construções.

ModularWorld

ModularWorld representa um mundo modular gerado e é disponibilizada por WorldGenerationFinishEvent. Contém os dados de posições e métodos para criar entidades e contentores nesse mundo.

Métodos principais:

• getWorld(): devolve a instância Bukkit World
• getWorldFolder(): devolve a pasta do mundo como File
• getCenter(): devolve o ponto inicial da masmorra, a partir do qual são medidas as faixas de dificuldade
• getHorizontalSize(): devolve a largura da masmorra em blocos, (2 × radius − 1) × moduleSizeXZ
• getDifficultyId(Location): devolve o ID de dificuldade de instância do EliteMobs para uma localização: 2 a menos de um sexto da largura a partir do centro (medido como o maior dos desvios em X e Z), 1 a menos de um terço e 0 nos restantes casos
• getSpawnLocations(): devolve todas as posições iniciais marcadas, List<Location>
• getChestLocations(): devolve todas as posições de baús, List<Location>
• getBarrelLocations(): devolve todas as posições de barris, List<Location>
• getExitLocations(): devolve todas as posições de saída. ExitLocation é um record aninhado privado; fora do plugin, só pode guardar o resultado numa lista com wildcard. Não existe atualmente um tipo público para os elementos.
• spawnChests(): cria baús nas posições marcadas e devolve List<Block>
• spawnBarrels(): cria barris nas posições marcadas e devolve List<Block>
• spawnInaccessibleExitLocations(): coloca os schematics superiores dos elevadores e devolve List<Location>
• spawnAccessibleExitLocations(): coloca os schematics inferiores dos elevadores e devolve List<Location>
• spawnOtherEntities(): no tick seguinte, processa as placas de conjuntos de aparecimento que a colocação ainda não tenha tratado e depois dispara novamente WorldGenerationFinishEvent. Normalmente, a colocação trata ela própria de todas as placas de conjuntos. Chamá-lo a partir de um listener de WorldGenerationFinishEvent faz com que se repita a cada tick.
• spawnInstancedEntities(): cria os bosses de instância em fila dos conjuntos de aparecimento com o maxLevel do respetivo conjunto, cada um com o ID de dificuldade de getDifficultyId, e devolve List<InstancedBossEntity>. Cada boss guarda o nome do ficheiro do conjunto como dados personalizados na chave betterstructures:spawnpool.

WorldGuard

A classe WorldGuard gere as proteções de regiões. O método public static ProtectedRegion generateProtectedRegion(FitAnything fitAnything, String regionName) permite integrar um esquema personalizado de proteção com o BetterStructures.

Outros métodos úteis:

• checkArea(Location, Player): verifica se o local pertence a uma região protegida pelo BetterStructures; devolve true se estiver protegido e avisa o jogador
• Protect(...): cria regiões protegidas por código
• Unprotect(CustomBossEntity): remove a proteção quando um boss é morto