跳至主要內容

開發者 API

要求​

BetterStructures 需要：

  • Java 21 或更高版本
  • Spigot/Paper 伺服器
  • WorldEdit 外掛（硬依賴）

可選依賴：

  • WorldGuard - 用於區域保護功能（需要同時安裝 EliteMobs 以實現完整整合）
  • EliteMobs - 用於精英怪物生成整合
  • MythicMobs - 用於 MythicMobs 整合
  • Terralith、Iris、Terra、TerraformGenerator - 用於自訂生態群系相容性

公共儲存庫

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.5.0</version>
  <scope>provided</scope>
</dependency>

注意：請造訪 https://repo.magmaguy.com/releases/com/magmaguy/BetterStructures 查看可用版本。最新穩定版：2.5.0

Gradle

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

dependencies {
    implementation 'com.magmaguy:BetterStructures:2.5.0'
}

注意：請造訪 https://repo.magmaguy.com/releases/com/magmaguy/BetterStructures 查看可用版本。最新穩定版：2.5.0

事件

注意：事件位於 com.magmaguy.betterstructures.api

套件匯入​

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;

BuildPlaceEvent​

當某個建築即將被放置時呼叫。透過 FitAnything 物件公開哪個建築將被放置在何處等資料。

請勿嘗試修改正在被放置的建築！ 你可以修改一些小細節，但更改整個建築很可能會導致適配不良。

此事件可以取消。

ChestFillEvent​

當箱子被填充時呼叫。使用容器的快照庫存來安全地儲存要套用的資料。

你可以透過 getContainer().getSnapshotInventory() 取得容器的快照庫存，然後使用 Inventory 方法 addItem() 或 removeItem() 修改戰利品。

你也可以呼叫 getTreasureConfigFilename() 來識別用於填充此箱子的戰利品表設定。

此事件可以取消。

WorldGenerationFinishEvent​

當世界生成完成時呼叫。提供對 ModularWorld 物件的存取，該物件包含已生成世界的所有資料，包括生成點、箱子位置與出口點。

此事件「不可」取消。

你可以透過 getModularWorld() 方法存取世界資料。請參閱下方的 ModularWorld 章節以了解所有可用方法。

事件監聽器範例

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 onWorldGenFinish(WorldGenerationFinishEvent event) {
        ModularWorld world = event.getModularWorld();
        // Access generated world data
        List<Location> spawns = world.getSpawnLocations();
    }
}

關鍵類別

FitAnything​

FitAnything 類別是在建築被貼上時所實例化的類別，負責處理貼上的每個面向，包括填充箱子與生成怪物。

可用的 getter 方法：

  • getSchematicContainer() - 返回結構圖容器
  • getSchematicClipboard() - 返回 WorldEdit 的 Clipboard 物件
  • getSchematicOffset() - 返回放置用的 Vector 偏移
  • getLocation() - 返回放置的 Location

這些方法在建立自訂區域保護或分析建築放置時很有用。

ModularWorld​

ModularWorld 類別代表已生成的模組化世界，並透過 WorldGenerationFinishEvent 提供。它包含所有位置資料，以及在已生成世界中生成實體與容器的方法。

關鍵方法：

  • getWorld() - 返回 Bukkit 的 World 實例
  • getWorldFolder() - 返回世界的 File 資料夾
  • getSpawnLocations() - 返回所有已標記的生成位置（List<Location>）
  • getChestLocations() - 返回所有箱子生成位置（List<Location>）
  • getBarrelLocations() - 返回所有木桶生成位置（List<Location>）
  • getExitLocations() - 返回所有出口點位置（List<ExitLocation>）
  • spawnChests() - 在已標記位置生成箱子，返回 List<Block>
  • spawnBarrels() - 在已標記位置生成木桶，返回 List<Block>
  • spawnInaccessibleExitLocations() - 生成上層電梯結構圖，返回 List<Location>
  • spawnAccessibleExitLocations() - 生成下層電梯結構圖，返回 List<Location>
  • spawnOtherEntities() - 從生成池生成自訂實體
  • spawnInstancedEntities(MatchInstance) - 生成實例化的 Boss 實體，返回 List<InstancedBossEntity>

WorldGuard​

WorldGuard 類別負責處理 WorldGuard 的區域保護。提供了實用方法 public static ProtectedRegion generateProtectedRegion(FitAnything fitAnything, String regionName)，讓開發者能夠輕鬆地在 BetterStructures 之上掛接自訂的區域保護方案。

其他有用的方法：

  • checkArea(Location, Player) - 檢查某位置是否位於受 BetterStructures 保護的區域內（如果受保護則返回 true，並向玩家傳送警告訊息）
  • Protect(...) - 以程式方式建立受保護區域
  • Unprotect(CustomBossEntity) - 當 Boss 被擊殺時移除區域保護