Difference between revisions of "Block Interaction"

From Forge Community Wiki
(Created page with "There are many different ways players (and other things) can interact with blocks, such as right clicking, left clicking, colliding, walking on, and of course mining. This pa...")
 
(Update to 1.18)
 
(3 intermediate revisions by 2 users not shown)
Line 6: Line 6:
 
Since left clicking, or "punching", a block does not generally result in any unique behavior, it is probably fair to say right clicking, or "activation", is ''the''  most common method of interaction. And thankfully, it is also one of the simplest to handle.
 
Since left clicking, or "punching", a block does not generally result in any unique behavior, it is probably fair to say right clicking, or "activation", is ''the''  most common method of interaction. And thankfully, it is also one of the simplest to handle.
  
−
=== onBlockActivated ===
+
=== use ===
  
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
public ActionResultType onBlockActivated(BlockState state, World worldIn, BlockPos pos, PlayerEntity player, Hand handIn, BlockRayTraceResult hit)
+
public InteractionResult use(BlockState state, Level level, BlockPos pos, Player player, InteractionHand hand, BlockHitResult hit)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 20: Line 20:
 
|        <code><nowiki>BlockState</nowiki></code>      ||    <code><nowiki>state</nowiki></code>    ||  The state of the block that was clicked       
 
|        <code><nowiki>BlockState</nowiki></code>      ||    <code><nowiki>state</nowiki></code>    ||  The state of the block that was clicked       
 
|-
 
|-
−
|          <code><nowiki>World</nowiki></code>          ||  <code><nowiki>worldIn</nowiki></code>    ||  The world that the block was clicked in       
+
|          <code><nowiki>Level</nowiki></code>          ||  <code><nowiki>level</nowiki></code>    ||  The level that the block was clicked in       
 
|-
 
|-
 
|        <code><nowiki>BlockPos</nowiki></code>        ||    <code><nowiki>pos</nowiki></code>      ||  The position of the block that was clicked     
 
|        <code><nowiki>BlockPos</nowiki></code>        ||    <code><nowiki>pos</nowiki></code>      ||  The position of the block that was clicked     
 
|-
 
|-
−
|      <code><nowiki>PlayerEntity</nowiki></code>      ||    <code><nowiki>player</nowiki></code>    ||  The player who did the clicking               
+
|      <code><nowiki>Player</nowiki></code>      ||    <code><nowiki>player</nowiki></code>    ||  The player who did the clicking               
 
|-
 
|-
−
|          <code><nowiki>Hand</nowiki></code>          ||    <code><nowiki>handIn</nowiki></code>    ||  The hand with which the player clicked         
+
|          <code><nowiki>InteractionHand</nowiki></code>          ||    <code><nowiki>handIn</nowiki></code>    ||  The hand with which the player clicked         
 
|-
 
|-
−
|  <code><nowiki>BlockRayTraceResult</nowiki></code>  ||    <code><nowiki>hit</nowiki></code>      ||  Where on the block's bounds it was hit         
+
|  <code><nowiki>BlockHitResult</nowiki></code>  ||    <code><nowiki>hit</nowiki></code>      ||  Where on the block's bounds it was hit         
 
|-
 
|-
 
|}
 
|}
Line 34: Line 34:
 
==== Return Value ====
 
==== Return Value ====
  
−
<code><nowiki>ActionResultType</nowiki></code> is the result right clicking, see example usages below. <code><nowiki>ActionResultType.SUCCESS</nowiki></code> means the right click action was successful. <code><nowiki>ActionResultType.CONSUME</nowiki></code> means that the right click action was consumed. <code><nowiki>ActionResultType.PASS</nowiki></code> is the default behavior, for when the block has no right click behavior, and allows something else to handle the right click. <code><nowiki>ActionResultType.FAIL</nowiki></code> means that the action failed.
+
<code><nowiki>InteractionResult</nowiki></code> is the result right clicking, see example usages below. <code><nowiki>InteractionResult.SUCCESS</nowiki></code> means the right click action was successful. <code><nowiki>InteractionResult.CONSUME</nowiki></code> means that the right click action was consumed. <code><nowiki>InteractionResult.CONSUME_PARTIAL</nowiki></code> means that the right click action is being consumed. <code><nowiki>InteractionResult.PASS</nowiki></code> is the default behavior, for when the block has no right click behavior, and allows something else to handle the right click. <code><nowiki>InteractionResult.FAIL</nowiki></code> means that the action failed.
  
 
{| class="wikitable sortable" border=1
 
{| class="wikitable sortable" border=1
Line 42: Line 42:
 
|-
 
|-
 
|    <code><nowiki>CONSUME</nowiki></code>  ||  Tuning a noteblock.                                               
 
|    <code><nowiki>CONSUME</nowiki></code>  ||  Tuning a noteblock.                                               
 +
|-
 +
| <code><nowiki>CONSUME_PARTIAL</nowiki></code> ||  Eating a carrot.                                           
 
|-
 
|-
 
|    <code><nowiki>PASS</nowiki></code>    ||  When right-clicking dirt. Or any other basic block.               
 
|    <code><nowiki>PASS</nowiki></code>    ||  When right-clicking dirt. Or any other basic block.               
Line 49: Line 51:
 
|}
 
|}
  
−
{{Colored box|title=Important|content=Returning <code><nowiki>ActionResultType.CONSUME</nowiki></code> from this method on the client will prevent it being called on the server. It is common practice to just check <code><nowiki>worldIn.isRemote</nowiki></code> and return <code><nowiki>ActionResultType.SUCCESS</nowiki></code>, and otherwise go on to normal activation logic. Vanilla has many examples of this, such as the chest.}}
+
{{Tip/Important|Returning <code><nowiki>InteractionResult.CONSUME</nowiki></code> from this method on the client will prevent it being called on the server. It is common practice to just check <code><nowiki>level.isClientSide</nowiki></code> and return <code><nowiki>InteractionResult.SUCCESS</nowiki></code>, and otherwise go on to normal activation logic. Vanilla has many examples of this, such as the chest.}}
  
  
Line 56: Line 58:
 
The uses for activation are literally endless. However, there are some common ones which deserve their own section.
 
The uses for activation are literally endless. However, there are some common ones which deserve their own section.
  
−
==== GUIs ====
+
==== Screens ====
  
−
One of the most common things to do on block activation is opening a GUI. Many blocks in vanilla behave this way, such as chests, hoppers, furnaces, and many more. More about GUIs can be found on [their page](GUIs).
+
One of the most common things to do on block activation is opening a <code>Screen</code>. Many blocks in vanilla behave this way, such as chests, hoppers, furnaces, and many more.
  
 
==== Activation ====
 
==== Activation ====
Line 64: Line 66:
 
Another common use for activation is, well, activation. This can be something like "turning on" a block, or triggering it to perform some action. For instance, a block could light up when activated. A vanilla example would be buttons or levers.
 
Another common use for activation is, well, activation. This can be something like "turning on" a block, or triggering it to perform some action. For instance, a block could light up when activated. A vanilla example would be buttons or levers.
  
−
{{Colored box|title=Important|content=<code><nowiki>onBlockActivated</nowiki></code> is called on both the client and the server, so be sure to keep the [[Sides|sidedness]] of your code in mind. Many things, like opening GUIs and modifying the world, should only be done on the server-side.}}
+
{{Tip/Important|<code><nowiki>use</nowiki></code> is called on both the client and the server, so be sure to keep the [[Sides|sidedness]] of your code in mind. Many things, like opening <code>AbstractContainerMenu</code>s and modifying the level, should only be done on the server-side.}}
  
  
 
=== Block Placement ==
 
=== Block Placement ==
  
−
=== onBlockPlacedBy ===
+
=== setPlacedBy ===
  
 
<syntaxhighlight lang="java" >
 
<syntaxhighlight lang="java" >
−
public void onBlockPlacedBy(World worldIn, BlockPos pos, BlockState state, @Nullable LivingEntity placer, ItemStack stack)
+
public void setPlacedBy(Level level, BlockPos pos, BlockState state, @Nullable LivingEntity placer, ItemStack stack)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Called by ''BlockItem''s after a block is set in the world, to allow post-place logic.
+
Called by ''BlockItem''s after a block is set in the level, to allow post-place logic.
  
  
Line 82: Line 84:
 
!          Type        !!      Name        !!                  Description                   
 
!          Type        !!      Name        !!                  Description                   
 
|-
 
|-
−
|      <code><nowiki>World</nowiki></code>      ||  <code><nowiki>worldIn</nowiki></code>    ||  The world that the block was placed in         
+
|      <code><nowiki>Level</nowiki></code>      ||  <code><nowiki>level</nowiki></code>    ||  The level that the block was placed in         
 
|-
 
|-
 
|    <code><nowiki>BlockPos</nowiki></code>    ||    <code><nowiki>pos</nowiki></code>      ||  The position where the block was placed       
 
|    <code><nowiki>BlockPos</nowiki></code>    ||    <code><nowiki>pos</nowiki></code>      ||  The position where the block was placed       
Line 96: Line 98:
 
== Player Break/Destroy ==
 
== Player Break/Destroy ==
  
−
=== onBlockClicked ===
+
=== attack ===
  
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
public void onBlockClicked(BlockState state, World worldIn, BlockPos pos, PlayerEntity player)
+
public void attack(BlockState state, Level level, BlockPos pos, Player player)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 105: Line 107:
  
 
{{Colored box|title=Info |content=This method is for when the player ''left-clicks'' on a block.<br>
 
{{Colored box|title=Info |content=This method is for when the player ''left-clicks'' on a block.<br>
−
Don't get this confused with <code><nowiki>onBlockActivated</nowiki></code>, which is called when the player ''right-clicks''.}}
+
Don't get this confused with <code><nowiki>use</nowiki></code>, which is called when the player ''right-clicks''.}}
  
 
=== Parameters ===
 
=== Parameters ===
Line 113: Line 115:
 
|    <code><nowiki>BlockState</nowiki></code>  ||    <code><nowiki>state</nowiki></code>    ||  The state of the block that was clicked       
 
|    <code><nowiki>BlockState</nowiki></code>  ||    <code><nowiki>state</nowiki></code>    ||  The state of the block that was clicked       
 
|-
 
|-
−
|      <code><nowiki>World</nowiki></code>      ||  <code><nowiki>worldIn</nowiki></code>    ||  The world that the block was clicked in       
+
|      <code><nowiki>Level</nowiki></code>      ||  <code><nowiki>level</nowiki></code>    ||  The level that the block was clicked in       
 
|-
 
|-
 
|    <code><nowiki>BlockPos</nowiki></code>    ||    <code><nowiki>pos</nowiki></code>      ||  The position of the block that was clicked     
 
|    <code><nowiki>BlockPos</nowiki></code>    ||    <code><nowiki>pos</nowiki></code>      ||  The position of the block that was clicked     
 
|-
 
|-
−
|  <code><nowiki>PlayerEntity</nowiki></code>  ||    <code><nowiki>player</nowiki></code>    ||  The player who did the clicking               
+
|  <code><nowiki>Player</nowiki></code>  ||    <code><nowiki>player</nowiki></code>    ||  The player who did the clicking               
 
|-
 
|-
 
|}
 
|}
Line 127: Line 129:
 
Two blocks that override this method are the <code>NoteBlock</code> and the <code>RedstoneOreBlock</code>.
 
Two blocks that override this method are the <code>NoteBlock</code> and the <code>RedstoneOreBlock</code>.
  
−
Note blocks override this method so that when left-clicked, it plays a sound.   
+
<code>NoteBlock</code> override this method so that when left-clicked, it plays a sound.   
−
Redstone ore overrides this method so that when left-clicked, it gives off emits faint light for a few seconds.
+
<code>RedStoneOreBlock</code> overrides this method so that when left-clicked, it gives off emits faint light for a few seconds.
  
−
== onBlockHarvested ==
+
== playerWillDestroy ==
  
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
public void onBlockHarvested(World worldIn, BlockPos pos, BlockState state, PlayerEntity player)
+
public void playerWillDestroy(Level level, BlockPos pos, BlockState state, Player player)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Called before the Block is set to air in the world. Called regardless of if the player's tool can actually collect this block.
+
Called before the Block is set to air in the level. Called regardless of if the player's tool can actually collect this block.
  
 
=== Parameters ===
 
=== Parameters ===
Line 142: Line 144:
 
!          Type        !!        Name      !!                Description                   
 
!          Type        !!        Name      !!                Description                   
 
|-
 
|-
−
|      <code><nowiki>World</nowiki></code>      ||  <code><nowiki>worldIn</nowiki></code>  ||  The world that the block was destroyed       
+
|      <code><nowiki>Level</nowiki></code>      ||  <code><nowiki>level</nowiki></code>  ||  The level that the block was destroyed       
 
|-
 
|-
 
|    <code><nowiki>BlockPos</nowiki></code>    ||    <code><nowiki>pos</nowiki></code>    ||  The position of the block that was destroyed  
 
|    <code><nowiki>BlockPos</nowiki></code>    ||    <code><nowiki>pos</nowiki></code>    ||  The position of the block that was destroyed  
Line 148: Line 150:
 
|    <code><nowiki>BlockState</nowiki></code>  ||    <code><nowiki>state</nowiki></code>    ||  The state of the block that was destroyed     
 
|    <code><nowiki>BlockState</nowiki></code>  ||    <code><nowiki>state</nowiki></code>    ||  The state of the block that was destroyed     
 
|-
 
|-
−
|  <code><nowiki>PlayerEntity</nowiki></code>  ||    <code><nowiki>player</nowiki></code>  ||  The player who harvested the block           
+
|  <code><nowiki>Player</nowiki></code>  ||    <code><nowiki>player</nowiki></code>  ||  The player who harvested the block           
 
|-
 
|-
 
|}
 
|}
Line 157: Line 159:
 
This method has important behavior in the <code><nowiki>Block</nowiki></code> class so be sure to call the super method.
 
This method has important behavior in the <code><nowiki>Block</nowiki></code> class so be sure to call the super method.
 
<syntaxhighlight lang="java" >
 
<syntaxhighlight lang="java" >
−
super.onBlockHarvested(worldIn, pos, state, player);
+
super.playerWillDestroy(level, pos, state, player);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
The <code>TNTBlock</code> overrides this method to cause it's explosion when a player destroys it.   
+
The <code>TntBlock</code> overrides this method to cause it's explosion when a player destroys it if its <code>unstable</code> property is <code>true</code>.   
−
This method is used by extended pistons; since an extended piston is made up of two blocks. (the extended head and the base)
+
This method is used by extended pistons; since an extended piston is made up of two blocks: the extended head and the base.
 
The <code>PistonHeadBlock</code> makes use of this method to destroy the base block when the moving head is destroyed.  
 
The <code>PistonHeadBlock</code> makes use of this method to destroy the base block when the moving head is destroyed.  
  
Line 167: Line 169:
 
== Entity Collision ==
 
== Entity Collision ==
  
−
== onEntityCollision ==
+
== entityInside ==
  
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
public void onEntityCollision(BlockState state, World worldIn, BlockPos pos, Entity entityIn)
+
public void entityInside(BlockState state, Level level, BlockPos pos, Entity entity)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 182: Line 184:
 
|    <code><nowiki>BlockState</nowiki></code>  ||    <code><nowiki>state</nowiki></code>    ||  The state of the block that was collided with     
 
|    <code><nowiki>BlockState</nowiki></code>  ||    <code><nowiki>state</nowiki></code>    ||  The state of the block that was collided with     
 
|-
 
|-
−
|      <code><nowiki>World</nowiki></code>      ||  <code><nowiki>worldIn</nowiki></code>  ||  The world where the collided block is located     
+
|      <code><nowiki>Level</nowiki></code>      ||  <code><nowiki>level</nowiki></code>  ||  The level where the collided block is located     
 
|-
 
|-
 
|    <code><nowiki>BlockPos</nowiki></code>    ||    <code><nowiki>pos</nowiki></code>    ||  The position of the block that was collided with  
 
|    <code><nowiki>BlockPos</nowiki></code>    ||    <code><nowiki>pos</nowiki></code>    ||  The position of the block that was collided with  
 
|-
 
|-
−
|    <code><nowiki>Entity</nowiki></code>      ||  <code><nowiki>entityIn</nowiki></code>  ||  The entity who collided with the block           
+
|    <code><nowiki>Entity</nowiki></code>      ||  <code><nowiki>entity</nowiki></code>  ||  The entity who collided with the block           
 
|-
 
|-
 
|}
 
|}

Latest revision as of 13:46, 12 January 2022

There are many different ways players (and other things) can interact with blocks, such as right clicking, left clicking, colliding, walking on, and of course mining.

This page will cover the basics of the most common types of interaction with blocks.

Player Right Click

Since left clicking, or "punching", a block does not generally result in any unique behavior, it is probably fair to say right clicking, or "activation", is the most common method of interaction. And thankfully, it is also one of the simplest to handle.

use

public InteractionResult use(BlockState state, Level level, BlockPos pos, Player player, InteractionHand hand, BlockHitResult hit)

This is the method that controls right click behavior.

Parameters

Type Name Description
BlockState state The state of the block that was clicked
Level level The level that the block was clicked in
BlockPos pos The position of the block that was clicked
Player player The player who did the clicking
InteractionHand handIn The hand with which the player clicked
BlockHitResult hit Where on the block's bounds it was hit

Return Value

InteractionResult is the result right clicking, see example usages below. InteractionResult.SUCCESS means the right click action was successful. InteractionResult.CONSUME means that the right click action was consumed. InteractionResult.CONSUME_PARTIAL means that the right click action is being consumed. InteractionResult.PASS is the default behavior, for when the block has no right click behavior, and allows something else to handle the right click. InteractionResult.FAIL means that the action failed.

Enum Value Example Usage
SUCCESS Eating a slice of cake.
CONSUME Tuning a noteblock.
CONSUME_PARTIAL Eating a carrot.
PASS When right-clicking dirt. Or any other basic block.
FAIL When attempting to place a minecart on a block other than rails.

Important

Returning InteractionResult.CONSUME from this method on the client will prevent it being called on the server. It is common practice to just check level.isClientSide and return InteractionResult.SUCCESS, and otherwise go on to normal activation logic. Vanilla has many examples of this, such as the chest.


Usage examples

The uses for activation are literally endless. However, there are some common ones which deserve their own section.

Screens

One of the most common things to do on block activation is opening a Screen. Many blocks in vanilla behave this way, such as chests, hoppers, furnaces, and many more.

Activation

Another common use for activation is, well, activation. This can be something like "turning on" a block, or triggering it to perform some action. For instance, a block could light up when activated. A vanilla example would be buttons or levers.

Important

use is called on both the client and the server, so be sure to keep the sidedness of your code in mind. Many things, like opening AbstractContainerMenus and modifying the level, should only be done on the server-side.


= Block Placement

setPlacedBy

public void setPlacedBy(Level level, BlockPos pos, BlockState state, @Nullable LivingEntity placer, ItemStack stack)

Called by BlockItems after a block is set in the level, to allow post-place logic.


Parameters

Type Name Description
Level level The level that the block was placed in
BlockPos pos The position where the block was placed
BlockState state The state of the block that was placed
LivingEntity placer The entity who placed the block
ItemStack stack The item block that was placed

Player Break/Destroy

attack

public void attack(BlockState state, Level level, BlockPos pos, Player player)

Called on a block when it is clicked by a player.

Info

This method is for when the player left-clicks on a block.

Don't get this confused with use, which is called when the player right-clicks.

Parameters

Type Name Description
BlockState state The state of the block that was clicked
Level level The level that the block was clicked in
BlockPos pos The position of the block that was clicked
Player player The player who did the clicking

Usage example

This method is perfect for adding custom events when a player clicks on a block.

By default this method does nothing. Two blocks that override this method are the NoteBlock and the RedstoneOreBlock.

NoteBlock override this method so that when left-clicked, it plays a sound. RedStoneOreBlock overrides this method so that when left-clicked, it gives off emits faint light for a few seconds.

playerWillDestroy

public void playerWillDestroy(Level level, BlockPos pos, BlockState state, Player player)

Called before the Block is set to air in the level. Called regardless of if the player's tool can actually collect this block.

Parameters

Type Name Description
Level level The level that the block was destroyed
BlockPos pos The position of the block that was destroyed
BlockState state The state of the block that was destroyed
Player player The player who harvested the block

Usage example

This method is perfect for adding custom events as a result of a player destroying a block

This method has important behavior in the Block class so be sure to call the super method. 

super.playerWillDestroy(level, pos, state, player);

The TntBlock overrides this method to cause it's explosion when a player destroys it if its unstable property is true. This method is used by extended pistons; since an extended piston is made up of two blocks: the extended head and the base. The PistonHeadBlock makes use of this method to destroy the base block when the moving head is destroyed.


Entity Collision

entityInside

public void entityInside(BlockState state, Level level, BlockPos pos, Entity entity)

This method is called whenever an entity collides with the block.


Parameters

Type Name Description
BlockState state The state of the block that was collided with
Level level The level where the collided block is located
BlockPos pos The position of the block that was collided with
Entity entity The entity who collided with the block

Usage examples

An example use of this method is by the CampfireBlock which uses this method to light those on fire that collide with the campfire.

Retrieved from ‘https://forge.gemwire.uk/index.php?title=Block_Interaction&oldid=3109’