372
edits
Changes
From Forge Community Wiki
Copy Block Interaction to MC1.16 archive
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.
=== onBlockActivated ===
<syntaxhighlight lang="java">
public ActionResultType onBlockActivated(BlockState state, World worldIn, BlockPos pos, PlayerEntity player, Hand handIn, BlockRayTraceResult hit)
</syntaxhighlight>
This is the method that controls right click behavior.
==== Parameters ====
{| class="wikitable sortable" border=1
! Type !! Name !! Description
|-
| <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>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>Hand</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
|-
|}
==== 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.
{| class="wikitable sortable" border=1
! Enum Value !! Example Usage
|-
| <code><nowiki>SUCCESS</nowiki></code> || Eating a slice of cake.
|-
| <code><nowiki>CONSUME</nowiki></code> || Tuning a noteblock.
|-
| <code><nowiki>PASS</nowiki></code> || When right-clicking dirt. Or any other basic block.
|-
| <code><nowiki>FAIL</nowiki></code> || When attempting to place a minecart on a block other than rails.
|-
|}
{{Tip/Important|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.}}
=== Usage examples ===
The uses for activation are literally endless. However, there are some common ones which deserve their own section.
==== GUIs ====
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).
==== 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.
{{Tip/Important|<code><nowiki>onBlockActivated</nowiki></code> is called on both the client and the server, so be sure to keep the [[Sides|sidedness/1.16]] of your code in mind. Many things, like opening GUIs and modifying the world, should only be done on the server-side.}}
=== Block Placement ==
=== onBlockPlacedBy ===
<syntaxhighlight lang="java" >
public void onBlockPlacedBy(World worldIn, BlockPos pos, BlockState state, @Nullable LivingEntity placer, ItemStack stack)
</syntaxhighlight>
Called by ''BlockItem''s after a block is set in the world, to allow post-place logic.
=== Parameters ===
{| class="wikitable sortable" border=1
! Type !! Name !! Description
|-
| <code><nowiki>World</nowiki></code> || <code><nowiki>worldIn</nowiki></code> || The world 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>BlockState</nowiki></code> || <code><nowiki>state</nowiki></code> || The state of the block that was placed
|-
| <code><nowiki>LivingEntity</nowiki></code> || <code><nowiki>placer</nowiki></code> || The entity who placed the block
|-
| <code><nowiki>ItemStack</nowiki></code> || <code><nowiki>stack</nowiki></code> || The item block that was placed
|-
|}
== Player Break/Destroy ==
=== onBlockClicked ===
<syntaxhighlight lang="java">
public void onBlockClicked(BlockState state, World worldIn, BlockPos pos, PlayerEntity player)
</syntaxhighlight>
Called on a block when it is clicked by a player.
{{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''.}}
=== Parameters ===
{| class="wikitable sortable" border=1
! Type !! Name !! Description
|-
| <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>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
|-
|}
=== 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 <code>NoteBlock</code> and the <code>RedstoneOreBlock</code>.
Note blocks 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.
== onBlockHarvested ==
<syntaxhighlight lang="java">
public void onBlockHarvested(World worldIn, BlockPos pos, BlockState state, PlayerEntity player)
</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.
=== Parameters ===
{| class="wikitable sortable" border=1
! Type !! Name !! Description
|-
| <code><nowiki>World</nowiki></code> || <code><nowiki>worldIn</nowiki></code> || The world 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>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
|-
|}
=== 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 <code><nowiki>Block</nowiki></code> class so be sure to call the super method.
<syntaxhighlight lang="java" >
super.onBlockHarvested(worldIn, pos, state, player);
</syntaxhighlight>
The <code>TNTBlock</code> overrides this method to cause it's explosion when a player destroys it.
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.
== Entity Collision ==
== onEntityCollision ==
<syntaxhighlight lang="java">
public void onEntityCollision(BlockState state, World worldIn, BlockPos pos, Entity entityIn)
</syntaxhighlight>
This method is called whenever an entity collides with the block.
=== Parameters ===
{| class="wikitable sortable" border=1
! Type !! Name !! Description
|-
| <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>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
|-
|}
=== Usage examples ===
An example use of this method is by the <code><nowiki>CampfireBlock</nowiki></code> which uses this method to light those on fire that collide with the campfire.
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.
=== onBlockActivated ===
<syntaxhighlight lang="java">
public ActionResultType onBlockActivated(BlockState state, World worldIn, BlockPos pos, PlayerEntity player, Hand handIn, BlockRayTraceResult hit)
</syntaxhighlight>
This is the method that controls right click behavior.
==== Parameters ====
{| class="wikitable sortable" border=1
! Type !! Name !! Description
|-
| <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>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>Hand</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
|-
|}
==== 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.
{| class="wikitable sortable" border=1
! Enum Value !! Example Usage
|-
| <code><nowiki>SUCCESS</nowiki></code> || Eating a slice of cake.
|-
| <code><nowiki>CONSUME</nowiki></code> || Tuning a noteblock.
|-
| <code><nowiki>PASS</nowiki></code> || When right-clicking dirt. Or any other basic block.
|-
| <code><nowiki>FAIL</nowiki></code> || When attempting to place a minecart on a block other than rails.
|-
|}
{{Tip/Important|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.}}
=== Usage examples ===
The uses for activation are literally endless. However, there are some common ones which deserve their own section.
==== GUIs ====
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).
==== 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.
{{Tip/Important|<code><nowiki>onBlockActivated</nowiki></code> is called on both the client and the server, so be sure to keep the [[Sides|sidedness/1.16]] of your code in mind. Many things, like opening GUIs and modifying the world, should only be done on the server-side.}}
=== Block Placement ==
=== onBlockPlacedBy ===
<syntaxhighlight lang="java" >
public void onBlockPlacedBy(World worldIn, BlockPos pos, BlockState state, @Nullable LivingEntity placer, ItemStack stack)
</syntaxhighlight>
Called by ''BlockItem''s after a block is set in the world, to allow post-place logic.
=== Parameters ===
{| class="wikitable sortable" border=1
! Type !! Name !! Description
|-
| <code><nowiki>World</nowiki></code> || <code><nowiki>worldIn</nowiki></code> || The world 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>BlockState</nowiki></code> || <code><nowiki>state</nowiki></code> || The state of the block that was placed
|-
| <code><nowiki>LivingEntity</nowiki></code> || <code><nowiki>placer</nowiki></code> || The entity who placed the block
|-
| <code><nowiki>ItemStack</nowiki></code> || <code><nowiki>stack</nowiki></code> || The item block that was placed
|-
|}
== Player Break/Destroy ==
=== onBlockClicked ===
<syntaxhighlight lang="java">
public void onBlockClicked(BlockState state, World worldIn, BlockPos pos, PlayerEntity player)
</syntaxhighlight>
Called on a block when it is clicked by a player.
{{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''.}}
=== Parameters ===
{| class="wikitable sortable" border=1
! Type !! Name !! Description
|-
| <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>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
|-
|}
=== 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 <code>NoteBlock</code> and the <code>RedstoneOreBlock</code>.
Note blocks 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.
== onBlockHarvested ==
<syntaxhighlight lang="java">
public void onBlockHarvested(World worldIn, BlockPos pos, BlockState state, PlayerEntity player)
</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.
=== Parameters ===
{| class="wikitable sortable" border=1
! Type !! Name !! Description
|-
| <code><nowiki>World</nowiki></code> || <code><nowiki>worldIn</nowiki></code> || The world 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>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
|-
|}
=== 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 <code><nowiki>Block</nowiki></code> class so be sure to call the super method.
<syntaxhighlight lang="java" >
super.onBlockHarvested(worldIn, pos, state, player);
</syntaxhighlight>
The <code>TNTBlock</code> overrides this method to cause it's explosion when a player destroys it.
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.
== Entity Collision ==
== onEntityCollision ==
<syntaxhighlight lang="java">
public void onEntityCollision(BlockState state, World worldIn, BlockPos pos, Entity entityIn)
</syntaxhighlight>
This method is called whenever an entity collides with the block.
=== Parameters ===
{| class="wikitable sortable" border=1
! Type !! Name !! Description
|-
| <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>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
|-
|}
=== Usage examples ===
An example use of this method is by the <code><nowiki>CampfireBlock</nowiki></code> which uses this method to light those on fire that collide with the campfire.