Interface WorldGenAccess

All Known Implementing Classes:
BukkitWorldGenAccess, NMSWorldGenAccess
public interface WorldGenAccess
Provides a unified abstraction layer for interacting with the world during generation and population phases.

This interface is designed to safely expose block and entity manipulation in contexts where direct Bukkit API usage may be unsafe or restricted (such as async chunk generation or custom world pipelines).

Implementations may:

  • Buffer writes instead of applying them immediately
  • Bypass Bukkit thread restrictions
  • Operate on custom world representations

All coordinates are expected to be in absolute world space unless otherwise stated.

  • Method Summary

    Modifier and Type
    Method
    Description
    @Nullable org.bukkit.entity.Entity
    addEntity(double x, double y, double z, @NotNull SavedEntity entity)
    Spawns a SavedEntity at the given coordinates.
    void
    addEntity(double x, double y, double z, @NotNull CustomEntity<?> entity)
    Spawns a CustomEntity at the given coordinates.
    @NotNull org.bukkit.entity.Entity
    addEntity(double x, double y, double z, @NotNull org.bukkit.entity.EntityType type)
    Spawns a vanilla Entity at the given coordinates.
    @NotNull org.bukkit.block.Biome
    getBiome(int x, int y, int z)
    Retrieves the Biome at the given coordinates.
    @NotNull org.bukkit.block.data.BlockData
    getBlockData(int x, int y, int z)
    Retrieves the BlockData at the given coordinates.
    @NotNull org.bukkit.block.BlockState
    getBlockState(int x, int y, int z)
    Retrieves a snapshot BlockState at the given coordinates.
    int
    getHighestBlockY(int x, int z, org.bukkit.HeightMap heightMap)
    Retrieves the highest Y coordinate at the given X/Z position based on a HeightMap.
    @NotNull Random
    getRandom()
    Returns the Random instance used for this generation pass.
    @NotNull org.bukkit.Material
    getType(int x, int y, int z)
    Retrieves the Material at the given coordinates.
    @NotNull org.bukkit.World
    getWorld()
    Returns the backing World instance.
    void
    setBlock(int x, int y, int z, @NotNull CustomBlock block)
    Places a CustomBlock at the given coordinates.
    void
    setBlock(int x, int y, int z, @NotNull CustomBlock block, @NotNull org.bukkit.block.data.BlockData data)
    Places a CustomBlock with explicit BlockData.
    void
    setBlock(int x, int y, int z, @NotNull org.bukkit.Material material)
    Sets a block at the given coordinates using a Material.
    void
    setBlock(int x, int y, int z, @NotNull org.bukkit.block.data.BlockData data)
    Sets a block at the given coordinates using full BlockData.

  • Method Details

    • setBlock

      void setBlock(int x, int y, int z, @NotNull @NotNull org.bukkit.Material material)
      Sets a block at the given coordinates using a Material.

      This replaces any existing block at the target position.

      Parameters:
      x - The absolute X coordinate
      y - The absolute Y coordinate
      z - The absolute Z coordinate
      material - The material to place (must represent a valid block)

    • setBlock

      void setBlock(int x, int y, int z, @NotNull @NotNull org.bukkit.block.data.BlockData data)
      Sets a block at the given coordinates using full BlockData.

      This allows specifying block states such as orientation, waterlogging, etc.

      Parameters:
      x - The absolute X coordinate
      y - The absolute Y coordinate
      z - The absolute Z coordinate
      data - The block data to apply

    • setBlock

      void setBlock(int x, int y, int z, @NotNull @NotNull CustomBlock block)
      Places a CustomBlock at the given coordinates.

      The implementation is responsible for correctly initializing any associated custom logic, metadata, or block entities.

      Parameters:
      x - The absolute X coordinate
      y - The absolute Y coordinate
      z - The absolute Z coordinate
      block - The custom block instance to place

    • setBlock

      void setBlock(int x, int y, int z, @NotNull @NotNull CustomBlock block, @NotNull @NotNull org.bukkit.block.data.BlockData data)
      Places a CustomBlock with explicit BlockData.

      This allows combining custom logic with a specific visual or state configuration.

      Parameters:
      x - The absolute X coordinate
      y - The absolute Y coordinate
      z - The absolute Z coordinate
      block - The custom block instance
      data - The block data defining its visual/state configuration

    • addEntity

      @NotNull @NotNull org.bukkit.entity.Entity addEntity(double x, double y, double z, @NotNull @NotNull org.bukkit.entity.EntityType type)
      Spawns a vanilla Entity at the given coordinates.

      Implementations must ensure this operation is safe within the generation context (e.g. deferred execution if required by threading constraints).

      Parameters:
      x - The absolute X coordinate (double precision)
      y - The absolute Y coordinate (double precision)
      z - The absolute Z coordinate (double precision)
      type - The EntityType to spawn
      Returns:
      The created entity instance

    • addEntity

      void addEntity(double x, double y, double z, @NotNull @NotNull CustomEntity<?> entity)
      Spawns a CustomEntity at the given coordinates.

      The provided entity acts as a template and should be instantiated according to its internal logic.

      Parameters:
      x - The absolute X coordinate (double precision)
      y - The absolute Y coordinate (double precision)
      z - The absolute Z coordinate (double precision)
      entity - The custom entity template

    • addEntity

      @Nullable @Nullable org.bukkit.entity.Entity addEntity(double x, double y, double z, @NotNull @NotNull SavedEntity entity)
      Spawns a SavedEntity at the given coordinates.

      This typically restores an entity from serialized data (NBT or similar).

      Parameters:
      x - The absolute X coordinate (double precision)
      y - The absolute Y coordinate (double precision)
      z - The absolute Z coordinate (double precision)
      entity - The saved entity definition
      Returns:
      The spawned entity instance, or null if spawning failed

    • getType

      @NotNull @NotNull org.bukkit.Material getType(int x, int y, int z)
      Retrieves the Material at the given coordinates.
      Parameters:
      x - The absolute X coordinate
      y - The absolute Y coordinate
      z - The absolute Z coordinate
      Returns:
      The material at the specified position

    • getBlockData

      @NotNull @NotNull org.bukkit.block.data.BlockData getBlockData(int x, int y, int z)
      Retrieves the BlockData at the given coordinates.
      Parameters:
      x - The absolute X coordinate
      y - The absolute Y coordinate
      z - The absolute Z coordinate
      Returns:
      The block data at the specified position

    • getBlockState

      @NotNull @NotNull org.bukkit.block.BlockState getBlockState(int x, int y, int z)
      Retrieves a snapshot BlockState at the given coordinates.

      This includes tile entity data where applicable.

      Parameters:
      x - The absolute X coordinate
      y - The absolute Y coordinate
      z - The absolute Z coordinate
      Returns:
      The block state snapshot

    • getBiome

      @NotNull @NotNull org.bukkit.block.Biome getBiome(int x, int y, int z)
      Retrieves the Biome at the given coordinates.
      Parameters:
      x - The absolute X coordinate
      y - The absolute Y coordinate
      z - The absolute Z coordinate
      Returns:
      The biome at the specified position

    • getHighestBlockY

      int getHighestBlockY(int x, int z, org.bukkit.HeightMap heightMap)
      Retrieves the highest Y coordinate at the given X/Z position based on a HeightMap.

      The result depends on the selected heightmap type (e.g. surface, ocean floor).

      Parameters:
      x - The absolute X coordinate
      z - The absolute Z coordinate
      heightMap - The height map type to query
      Returns:
      The highest Y coordinate matching the height map criteria

    • getWorld

      @NotNull @NotNull org.bukkit.World getWorld()
      Returns the backing World instance.

      Note that direct interaction with the returned world may not always be safe depending on the implementation context.

      Returns:
      The world associated with this generation access

    • getRandom

      @NotNull @NotNull Random getRandom()
      Returns the Random instance used for this generation pass.

      This should be preferred over creating new random instances to ensure deterministic generation when required.

      Returns:
      The random source