Interface Spawner

All Known Implementing Classes:
NoSpawner, PrefabSpawner
public interface Spawner
Validates whether a candidate world position is suitable for placing content, and writes the chosen placement data to the event context once a valid position is accepted.

Spawners work in two phases:

  1. test(World, Vector3ic, Random) is called (potentially many times per tick) to probe candidate positions. Return true if the position is acceptable. Implementations may cache the result of any expensive selection made here (such as choosing a prefab or rotation) as fields, since onComplete(Vector3ic, WorldEvent) will be called with the same position that last returned true.
  2. onComplete(Vector3ic, WorldEvent) is called exactly once per stage completion, after all spawners have accepted the position. Write any context entries (e.g. PrefabPasteContext) here so that subsequent actions can reference them.

Multiple spawners can be registered on a single LocationCondition; all of them must return true from test(World, Vector3ic, Random) for a position to be accepted.

The static helpers findSurface(int, int, int, int, int, ChunkStore), getBlockId(int, int, int, ChunkStore), and getFluidId(int, int, int, ChunkStore) are provided for common terrain lookups.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Spawner.Config
    Asset-side factory for a Spawner.
    static enum 
    Spawner.Result
    Represents the result of a spawner test operation.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Spawner[]
    EMPTY_ARRAY
     
    static final int
    INVALID_HEIGHT
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    findSurface(int x, int startY, int z, int clearance, int searchRadius, ChunkStore store)
    Scans outward from startY for the nearest Y that is itself solid and has clearance open blocks above it.
    static int
    getBlockId(int x, int y, int z, ChunkStore store)
    Returns the block type ID at the given world position, or BlockType.UNKNOWN_ID if the chunk section is not loaded.
    static int
    getFluidId(int x, int y, int z, ChunkStore store)
    Returns the fluid ID at the given world position, or Fluid.EMPTY_ID if the chunk section is not loaded or contains no fluid.
    boolean
    onComplete(org.joml.Vector3ic position, WorldEvent event)
    Called once when the owning stage completes, with the position that last returned true from test(World, Vector3ic, Random).
    Spawner.Result
    test(World world, org.joml.Vector3ic position, Random random)
    Tests whether position is a valid placement site and records any state needed by onComplete(Vector3ic, WorldEvent).

  • Field Details

  • Method Details

    • test

      Spawner.Result test(@Nonnull World world, @Nonnull org.joml.Vector3ic position, @Nonnull Random random)
      Tests whether position is a valid placement site and records any state needed by onComplete(Vector3ic, WorldEvent).

      This may be called up to several times per tick with different positions, so keep it cheap. If the test involves selecting from a random set (e.g. choosing a prefab), store the selection as a field rather than regenerating it in onComplete(Vector3ic, WorldEvent).

      Check terrain validity using the static helpers on this interface. Reject the position (return false) if any required chunk is unloaded, i.e. if findSurface(int, int, int, int, int, ChunkStore) returns INVALID_HEIGHT.

      Parameters:
      world - the world the position is in
      position - the candidate block position, with Y already set to the nearest qualifying surface
      random - a random source for any stochastic validation logic
      Returns:
      true if the position is acceptable

    • onComplete

      boolean onComplete(@Nonnull org.joml.Vector3ic position, @Nonnull WorldEvent event)
      Called once when the owning stage completes, with the position that last returned true from test(World, Vector3ic, Random). Write any context values that downstream actions will need into the event context here.
      Parameters:
      position - the accepted block position
      event - the running world event whose context should be populated
      Returns:
      false if the spawner cannot produce a valid result, treating the stage as failed

    • findSurface

      static int findSurface(int x, int startY, int z, int clearance, int searchRadius, @Nonnull ChunkStore store)
      Scans outward from startY for the nearest Y that is itself solid and has clearance open blocks above it.

      Callers don't need to assume there is only one surface layer. An outdoor top, a cave floor, or any other layer are all just "the nearest qualifying surface" to whatever search origin is given.

      Parameters:
      x - world x-coordinate
      startY - the search origin, e.g. a candidate's own Y or an already-accepted nearby position's Y
      z - world z-coordinate
      clearance - the number of open blocks required above the surface
      searchRadius - the maximum number of blocks to search in either direction from startY
      store - the chunk store to query
      Returns:
      the nearest qualifying surface Y, or INVALID_HEIGHT if none is found or the chunk is not loaded

    • getBlockId

      static int getBlockId(int x, int y, int z, @Nonnull ChunkStore store)
      Returns the block type ID at the given world position, or BlockType.UNKNOWN_ID if the chunk section is not loaded.
      Parameters:
      x - world x-coordinate
      y - world y-coordinate
      z - world z-coordinate
      store - the chunk store to query
      Returns:
      the block type ID, or BlockType.UNKNOWN_ID

    • getFluidId

      static int getFluidId(int x, int y, int z, @Nonnull ChunkStore store)
      Returns the fluid ID at the given world position, or Fluid.EMPTY_ID if the chunk section is not loaded or contains no fluid.
      Parameters:
      x - world x-coordinate
      y - world y-coordinate
      z - world z-coordinate
      store - the chunk store to query
      Returns:
      the fluid ID, or Fluid.EMPTY_ID