Package net.minestom.server.instance.block

Class CustomBlock

java.lang.Object
net.minestom.server.instance.block.CustomBlock
public abstract class CustomBlock
extends java.lang.Object
Represents the handler of a custom block type which can be registered with BlockManager.registerCustomBlock(CustomBlock).

There should be only one instance of this class for each custom block type, every individual blocks will execute the callbacks present there. Each of which contains the custom block position and the instance concerned.

Each block in a chunk contains 2 id, the block state id (only visual) and a custom block id corresponding to getCustomBlockId(). A custom block is responsible for the blocks tick, the custom break time feature, and some useful callbacks.

  • Field Details

  • Constructor Details

    • CustomBlock

      public CustomBlock​(short defaultBlockStateId, @NotNull java.lang.String identifier)
      Parameters:
      defaultBlockStateId - the default block state id
      identifier - the custom block identifier

    • CustomBlock

      public CustomBlock​(@NotNull Block block, @NotNull java.lang.String identifier)

  • Method Details

    • getBreakEntityId

      public int getBreakEntityId​(Player firstBreaker)

    • update

      public void update​(@NotNull Instance instance, @NotNull BlockPosition blockPosition, @Nullable Data data)
      Calling delay depends on getUpdateOption() which should be overridden.
      Parameters:
      instance - the instance of the block
      blockPosition - the position of the block
      data - the data associated with the block
      Throws:
      java.lang.UnsupportedOperationException - if getUpdateOption() is not null but the update method is not overridden

    • getUpdateOption

      @Nullable public UpdateOption getUpdateOption()
      The update option is used to define the delay between two update(Instance, BlockPosition, Data) execution.

      If this is not null, update(Instance, BlockPosition, Data) should be overridden or errors with occurs.

      Returns:
      the update option of the block, null if not any

    • onPlace

      public abstract void onPlace​(@NotNull Instance instance, @NotNull BlockPosition blockPosition, @Nullable Data data)
      Called when a custom block has been placed.
      Parameters:
      instance - the instance of the block
      blockPosition - the position of the block
      data - the data associated with the block

    • onDestroy

      public abstract void onDestroy​(@NotNull Instance instance, @NotNull BlockPosition blockPosition, @Nullable Data data)
      Called when a custom block has been destroyed or replaced.
      Parameters:
      instance - the instance of the block
      blockPosition - the position of the block
      data - the data associated with the block

    • onInteract

      public abstract boolean onInteract​(@NotNull Player player, @NotNull Player.Hand hand, @NotNull BlockPosition blockPosition, @Nullable Data data)
      Handles interactions with this block. Can also block normal item use (containers should block when opening the menu, this prevents the player from placing a block when opening it for instance).
      Parameters:
      player - the player interacting
      hand - the hand used to interact
      blockPosition - the position of this block
      data - the data at this position
      Returns:
      true if this block blocks normal item use, false otherwise

    • getCustomBlockId

      public abstract short getCustomBlockId()
      This id can be serialized in chunk file, meaning no duplicate should exist Changing this value halfway should mean potentially breaking the world
      Returns:
      the custom block id

    • getBreakDelay

      public int getBreakDelay​(@NotNull Player player, @NotNull BlockPosition position, byte stage, java.util.Set<Player> breakers)
      Called when the player requests the next stage break delay
      Parameters:
      player - the player who is trying to break the block
      position - the block position
      stage - the current break stage of the block (0-10)
      breakers - the list containing all the players currently digging this block
      Returns:
      the time in tick to pass to the next state, 0 to instant break it. negative value allow to skip stages (-2 will skip 2 stages per tick)
      See Also:
      to enable/disable it

    • enableCustomBreakDelay

      public boolean enableCustomBreakDelay()
      Used to enable the custom break delay from getBreakDelay(Player, BlockPosition, byte, Set) Disabling it would result in having vanilla time
      Returns:
      true to enable custom break delay

    • enableMultiPlayerBreaking

      public boolean enableMultiPlayerBreaking()
      Gets if this block breaking time can be reduced by having multiple players digging it.

      WARNING: this should be constant, do not change this value halfway.

      Returns:
      true to enable the multi-player breaking feature

    • hasUpdate

      public boolean hasUpdate()
      Gets if this CustomBlock requires any tick update.
      Returns:
      true if getUpdateOption() is not null and the value is positive

    • handleContact

      public void handleContact​(@NotNull Instance instance, @NotNull BlockPosition position, @NotNull Entity touching)
      Defines custom behaviour for entities touching this block.
      Parameters:
      instance - the instance
      position - the position at which the block is
      touching - the entity currently touching the block

    • getDefaultBlockStateId

      public short getDefaultBlockStateId()
      This is the default block state id when the custom block is set, it is possible to change this value per block using BlockModifier.setSeparateBlocks(int, int, int, short, short)

      Meaning that you should not believe that your custom blocks id will always be this one.

      Returns:
      the default visual block id

    • getIdentifier

      @NotNull public java.lang.String getIdentifier()
      The custom block identifier, used to retrieve the custom block object with BlockManager.getCustomBlock(String) and to set custom block in the instance.
      Returns:
      the custom block identifier

    • createData

      @Nullable public Data createData​(@NotNull Instance instance, @NotNull BlockPosition blockPosition, @Nullable Data data)
      Initialises data for this block.
      Parameters:
      blockPosition - the position of the targeted block
      data - data given to 'setBlock', can be null
      Returns:
      Data for this block. Can be null, 'data', or a new object

    • updateFromNeighbor

      public void updateFromNeighbor​(@NotNull Instance instance, @NotNull BlockPosition thisPosition, @NotNull BlockPosition neighborPosition, boolean directNeighbor)
      Updates this block from a neighbor. By default calls 'update' if directNeighbor is true.
      Parameters:
      instance - current instance
      thisPosition - this block's position
      neighborPosition - the neighboring block which triggered the update
      directNeighbor - is the neighbor directly connected to this block? (No diagonals)

    • scheduledUpdate

      public void scheduledUpdate​(@NotNull Instance instance, @NotNull BlockPosition position, @Nullable Data blockData)
      Called when a scheduled update on this block happens. By default, calls 'update'.
      Parameters:
      instance - the instance of the block
      position - the position of the block
      blockData - the data of the block

    • getDrag

      public float getDrag​(@NotNull Instance instance, @NotNull BlockPosition blockPosition)
      Gets the drag of this block.

      It has to be between 0 and 1.

      Returns:
      the drag of this block

    • writeBlockEntity

      public void writeBlockEntity​(@NotNull BlockPosition position, @Nullable Data blockData, @NotNull org.jglrxavpok.hephaistos.nbt.NBTCompound nbt)
      Allows custom block to write block entity data to a given NBT compound. Used to send block entity data to the client over the network. Can also be used to save block entity data on disk for compatible chunk savers.
      Parameters:
      position - position of the block
      blockData - equivalent to 
      instance.getBlockData(position)
      nbt - the nbt to write in the ChunkDataPacket

    • onExplode

      public boolean onExplode​(@NotNull Instance instance, @NotNull BlockPosition position, Data lootTableArguments)
      Called when an explosion wants to destroy this block.
      Parameters:
      instance - the instance
      lootTableArguments - arguments used in the loot table loot generation
      Returns:
      'true' if the explosion should happen on this block, 'false' to cancel the destruction. Returning true does NOT block the explosion rays, ie it does not change the block explosion resistance

    • getLootTable

      @Nullable public LootTable getLootTable​(@NotNull LootTableManager tableManager)
      Returns the loot table associated to this block. Return null to use vanilla behavior.
      Parameters:
      tableManager - the loot table manager
      Returns:
      the loot table associated to this block

    • startDigging

      public void startDigging​(@NotNull Instance instance, @NotNull BlockPosition blockPosition, @NotNull Player player)
      Called when a player start digging this custom block, process all necessary data if enableMultiPlayerBreaking() is enabled.
      Parameters:
      instance - the instance of the block
      blockPosition - the position of the block
      player - the player who started digging

    • stopDigging

      public void stopDigging​(@NotNull Instance instance, @NotNull BlockPosition blockPosition, @NotNull Player player)
      Called when a player stop digging a block, does remove the block break animation if he was the only breaker.
      Parameters:
      instance - the instance of the block
      blockPosition - the position of the block
      player - the player who stopped digging

    • processStage

      public boolean processStage​(@NotNull Instance instance, @NotNull BlockPosition blockPosition, @NotNull Player player, byte stageIncrease)
      Process one stage on the block, break it if it excess MAX_STAGE, only if enableMultiPlayerBreaking() is enabled.
      Parameters:
      instance - the instance of the block
      blockPosition - the position of the block
      player - the player who processed one stage on the block
      stageIncrease - the number of stage increase
      Returns:
      true if the block can continue being digged
      Throws:
      java.lang.IllegalStateException - if enableMultiPlayerBreaking() is disabled

    • removeDiggingInformation

      public void removeDiggingInformation​(@NotNull Instance instance, @NotNull BlockPosition blockPosition)

    • getBreakers

      @Nullable public java.util.Set<Player> getBreakers​(@NotNull Instance instance, @NotNull BlockPosition blockPosition)
      Gets all the breakers of a block, only if enableMultiPlayerBreaking() is enabled.
      Parameters:
      instance - the instance of the block
      blockPosition - the position of the block
      Returns:
      the Set of breakers of a block
      Throws:
      java.lang.IllegalStateException - if enableMultiPlayerBreaking() is disabled

    • getBreakStage

      public byte getBreakStage​(@NotNull Instance instance, @NotNull BlockPosition blockPosition)
      Gets the block break stage at a position, only work if enableMultiPlayerBreaking() is enabled.
      Parameters:
      instance - the instance of the custom block
      blockPosition - the position of the custom block
      Returns:
      the break stage at the position. Can also be 0 when nonexistent