Block Entities - Revision history

Nexus-Dino at 18:01, 20 September 2022

2022-09-20T18:01:23Z

ChampionAsh5357: Update to 1.18

2022-01-12T13:44:27Z

Update to 1.18

Dipo: /* Attaching a BlockEntity to a Block */

2022-01-10T03:29:10Z

Attaching a BlockEntity to a Block

ChampionAsh5357: Update to 1.17

2021-07-31T23:39:18Z

Update to 1.17

Show changes

ChampionAsh5357: ChampionAsh5357 moved page Tile Entities to Block Entities: Class rename

2021-07-31T23:19:20Z

ChampionAsh5357 moved page Block Entities to Block Entities: Class rename

SciWhiz12: SciWhiz12 moved page Basics of Tile Entities to Tile Entities: remove the "Basics of" part

2021-01-11T05:12:51Z

SciWhiz12 moved page Tile Entities to Block Entities: remove the "Basics of" part

SciWhiz12: Text replacement - "{{Colored box|title=Important|content=" to "{{Tip/Important|"

2020-12-21T03:01:14Z

Text replacement - "{{Colored box|title=Important|content=" to "{{Tip/Important|"

Unbekannt: update the Blocks with the Cplored Box

2020-12-19T08:33:01Z

update the Blocks with the Cplored Box

Unbekannt: Inital Import dokuwiki

2020-10-24T19:07:57Z

Inital Import dokuwiki

New page

Tile entities are like simplified entities that are bound to a <code>Block</code>. They are used to store dynamic data, execute tick based tasks and for dynamic rendering. Some examples from vanilla Minecraft would be: handling of inventories (chests), smelting logic on furnaces, or area effects for beacons. More advanced examples exist in mods, such as quarries, sorting machines, pipes, and displays.
<block tip>
A <code>TileEntity</code> isn’t a solution for everything, and they can cause lag when used wrongly. When possible, try to avoid them.
</block>

== Creating a <code>TileEntity</code> ==

In order to create a <code>TileEntity</code> you need to extend the <code>TileEntity</code> class. To register it, listen for the appropriate registry event and create a <code>TileEntityType</code>:
<syntaxhighlight lang="java">
@SubscribeEvent
public static void registerTE(RegistryEvent.Register<TileEntityType<?>> evt) {
TileEntityType<?> type = TileEntityType.Builder.create(factory, validBlocks).build(null);
type.setRegistryName("examplemod", "myte");
evt.getRegistry().register(type);
}
</syntaxhighlight>
You can also use a <code>DeferredRegister</code> instead.
<syntaxhighlight lang="java">
public static final DeferredRegister<TileEntityType<?>> TILE_ENTITIES = DeferredRegister.create(ForgeRegistries.TILE_ENTITIES, "examplemod");

public static final RegistryObject<TileEntityType<?>> MY_TE = TILE_ENTITIES.register("myte", () -> TileEntityType.Builder.create(factory, validBlocks).build(null));
</syntaxhighlight>

In this example, <code>factory</code> is a function that creates a new instance of your <code>TileEntity</code>. A method reference or a lambda is commonly used. The variable <code>validBlocks</code> is one or more blocks (<code><nowiki>TileEntityType$Builder::create</nowiki></code> is varargs) that the tile entity can exist for.

== Attaching a <code>TileEntity</code> to a <code>Block</code> ==
To attach your new <code>TileEntity</code> to a <code>Block</code> you need to override 2 (two) methods within the <code>Block</code> class.
<syntaxhighlight lang="java">
IForgeBlock#hasTileEntity(BlockState state)

IForgeBlock#createTileEntity(BlockState state, IBlockReader world)
</syntaxhighlight>
Using the parameters you can choose if the block should have a <code>TileEntity</code> or not. Usually you will return true in the first method and a new instance of your <code>TileEntity</code> in the second method.

== Storing Data within your <code>TileEntity</code> ==
In order to save data, override the following two methods
<code>
TileEntity#write(CompoundNBT nbt)

TileEntity#read(BlockState state, CompoundNBT nbt)
</code>
These methods are called whenever the <code>Chunk</code> containing the <code>TileEntity</code> gets loaded from/saved to NBT. Use them to read and write to the fields in your tile entity class.

<block tip>
Whenever your data changes you need to call <code><nowiki>TileEntity#markDirty()</nowiki></code>, otherwise the <code>Chunk</code> containing your <code>TileEntity</code> might be skipped while the world is saved.
</block>

<block important>
It is important that you call the super methods!

The tag names <code>id</code>, <code>x</code>, <code>y</code>, <code>z</code>, <code>ForgeData</code> and <code>ForgeCaps</code> are reserved by the super methods.
</block>

== Ticking <code>TileEntity</code> ==
If you need a ticking <code>TileEntity</code>, for example to keep track of the progress during a smelting process, you need to add the <code><nowiki>ITickableTileEntity</nowiki></code> interface to your <code>TileEntity</code>. Now you can implement all your calculations within
<syntaxhighlight lang="java">
ITickableTileEntity#tick()
</syntaxhighlight>
<block tip>
This method is called each tick. Therefore, you should avoid having complicated calculations in here. If possible, you should make more complex calculations just every X ticks. (The amount of ticks in a second may be lower than 20 (twenty) but won’t be higher)
</block>

== Synchronizing the Data to the Client ==
There are 3 (three) ways of syncing data to the client. Synchronizing on chunk load, synchronizing on block updates and synchronizing with a custom network message.
=== Synchronizing on chunk load ===
For this you need to override
<syntaxhighlight lang="java">
TileEntity#getUpdateTag()

IForgeTileEntity#handleUpdateTag(BlockState state, CompoundNBT tag)
</syntaxhighlight>
Again, this is pretty simple, the first method collects the data that should be send to the client, while the second one processes that data. If your <code>TileEntity</code> doesn’t contain much data you might be able to use the methods out of the [[#storing_data|Storing Data]] section.

<block important>
Synchronizing excessive/useless data for tile entities can lead to network congestion. You should optimize your network usage by sending only the information the client needs when the client needs it. For instance, it is more often than not unnecessary to send the inventory of a tile entity in the update tag, as this can be synchronized via its GUI.
</block>

=== Synchronizing on block update ===
This method is a bit more complicated, but again you just need to override 2 methods. Here is a tiny example implementation of it
<syntaxhighlight lang="java">
@Override
public SUpdateTileEntityPacket getUpdatePacket(){
CompoundNBT nbtTag = new CompoundNBT();
//Write your data into the nbtTag
return new SUpdateTileEntityPacket(getPos(), -1, nbtTag);
}

@Override
public void onDataPacket(NetworkManager net, SUpdateTileEntityPacket pkt){
CompoundNBT tag = pkt.getNbtCompound();
//Handle your Data
}
</syntaxhighlight>
The Constructor of <code>SUpdateTileEntityPacket</code> takes:
* The position of your <code>TileEntity</code>.
* An ID, though it isn’t really used besides by Vanilla, therefore you can just put a -1 in there.
* An <code>CompoundNBT</code> which should contain your data.

Now, to send the packet, an update notification must be given on the server.
<code>
World#notifyBlockUpdate(BlockPos pos, BlockState oldState, BlockState newState, int flags)
</code>
The <code>pos</code> should be your <code>TileEntity</code>’s position. For <code>oldState</code> and <code>newState</code> you can pass the current <code>BlockState</code> at that position. The <code>flags</code> are a bitmask and should contain <code>2</code>, which will sync the changes to the client. See <code>Constants$BlockFlags</code> for more info as well as the rest of the flags. The flag <code>2</code> is equivalent to <code><nowiki>Constants$BlockFlags#BLOCK_UPDATE</nowiki></code>.

=== Synchronizing using a custom network message ===

This way of synchronizing is probably the most complicated one, but is usually also the most optimized one, as you can make sure that only the data you need to be synchronized is actually synchronized. You should first check out the <code>[[latest:advanced:networking:start|Networking]]</code> section and especially <code>[[latest:advanced:networking:simplechannel|SimpleImpl]]</code> before attempting this. Once you’ve created your custom network message, you can send it to all users that have the <code>TileEntity</code> loaded with:
<syntaxhighlight lang="java">
SimpleChannel#send(PacketDistributor.TRACKING_CHUNK.with(() -> chunk), MSG);
</syntaxhighlight>
<block alert>
It is important that you do safety checks, the TileEntity might already be destroyed/replaced when the message arrives at the player! You should also check if the area is loaded using (<code><nowiki>World#isAreaLoaded(BlockPos, int)</nowiki></code>)
</block>

@@ Line 29: / Line 29: @@
 In order to save data, override the following two methods
 <syntaxhighlight lang="java">
-BlockEntity#save(CompoundTag tag)
+BlockEntity#saveAdditional(CompoundTag tag)
 BlockEntity#load(CompoundTag tag)
@@ Line 74: / Line 74: @@
 === Synchronizing on block update  ===
-This method is a bit more complicated, but again you just need to override 2 methods. Here is a tiny example implementation of it:
+This method is a bit more complicated, but again you just need to override 2 or 3 methods. Here is a tiny example implementation of it:
 <syntaxhighlight lang="java">
 @Override
-public ClientboundBlockEntityDataPacket getUpdatePacket(){
+public CompoundTag getUpdateTag() {
-    CompoundTag tag = new CompoundTag();
+  CompoundTag tag = new CompoundTag();
-    //Write your data into the tag
+  //Write your data into the tag
-    return new ClientboundBlockEntityDataPacket(getBlockPos(), -1, tag);
+  return tag;
+}
 @Override
-public void onDataPacket(Connection connection, ClientboundBlockEntityDataPacket pkt){
+public Packet<ClientGamePacketListener> getUpdatePacket() {
-    CompoundTag tag = pkt.getTag();
+  // Will get tag from #getUpdateTag
-    //Handle your Data
+  return ClientboundBlockEntityDataPacket.create(this);
+}
 </syntaxhighlight>
-The Constructor of <code>ClientboundBlockEntityDataPacket</code> takes:
+The static constructors <code>ClientboundBlockEntityDataPacket#create</code> takes:
-* The position of your <code>BlockEntity</code>.
+* The <code>BlockEntity</code>.
-* An ID, though it isn’t really used besides by Vanilla, therefore you can just put a -1 in there.
+* An optional function to get the <code>CompoundTag</code> from the <code>BlockEntity</code>. By default, this uses <code>BlockEntity#getUpdateTag</code>.
 Now, to send the packet, an update notification must be given on the server.
@@ Line 98: / Line 99: @@
 Level#sendBlockUpdated(BlockPos pos, BlockState oldState, BlockState newState, int flags)
 </code>
-The <code>pos</code> should be your <code>BlockEntity</code>’s position. For <code>oldState</code> and <code>newState</code> you can pass the current <code>BlockState</code> at that position. The <code>flags</code> are a bitmask and should contain <code>2</code>, which will sync the changes to the client. See <code>Constants$BlockFlags</code> for more info as well as the rest of the flags. The flag <code>2</code> is equivalent to <code><nowiki>Constants$BlockFlags#BLOCK_UPDATE</nowiki></code>.
+The <code>pos</code> should be your <code>BlockEntity</code>’s position. For <code>oldState</code> and <code>newState</code> you can pass the current <code>BlockState</code> at that position. The <code>flags</code> are a bitmask and should contain <code>2</code>, which will sync the changes to the client. See <code>Block</code> for more info as well as the rest of the flags. The flag <code>2</code> is equivalent to <code><nowiki>Block#UPDATE_CLIENTS</nowiki></code>.
 === Synchronizing using a custom network message ===

@@ Line 24: / Line 24: @@
 == Attaching a <code>BlockEntity</code> to a <code>Block</code> ==
-To attach your new <code>BlockEntity</code> to a <code>Block</code>, the <code>EntityBlock</code> interface must be implemented on your <code>Block</code> subclass. The method <code>EntityBlock#newBlockEntity(BlockPos, BlockState)</code> must be implemented and return a new isntance of your <code>BlockEntity</code>.
+To attach your new <code>BlockEntity</code> to a <code>Block</code>, the <code>EntityBlock</code> interface must be implemented on your <code>Block</code> subclass. The method <code>EntityBlock#newBlockEntity(BlockPos, BlockState)</code> must be implemented and return a new instance of your <code>BlockEntity</code>.
 == Storing Data within your <code>BlockEntity</code> ==

@@ Line 44: / Line 44: @@
-{{Colored box|title=Important|content=It is important that you call the super methods!
+{{Tip/Important|It is important that you call the super methods!
 The tag names <code>id</code>, <code>x</code>, <code>y</code>, <code>z</code>, <code>ForgeData</code> and <code>ForgeCaps</code> are reserved by the super methods.}}
@@ Line 67: / Line 67: @@
 Again, this is pretty simple, the first method collects the data that should be send to the client, while the second one processes that data. If your <code>TileEntity</code> doesn’t contain much data you might be able to use the methods out of the [[#storing_data|Storing Data]] section.
-{{Colored box|title=Important|content=Synchronizing excessive/useless data for tile entities can lead to network congestion. You should optimize your network usage by sending only the information the client needs when the client needs it. For instance, it is more often than not unnecessary to send the inventory of a tile entity in the update tag, as this can be synchronized via its GUI.)}}
+{{Tip/Important|Synchronizing excessive/useless data for tile entities can lead to network congestion. You should optimize your network usage by sending only the information the client needs when the client needs it. For instance, it is more often than not unnecessary to send the inventory of a tile entity in the update tag, as this can be synchronized via its GUI.)}}
 === Synchronizing on block update  ===

@@ Line 4: / Line 4: @@
 == Creating a <code>BlockEntity</code> ==
 You can also use a <code>DeferredRegister</code> instead.
 <syntaxhighlight lang="java">

← Older revision	Revision as of 23:19, 31 July 2021
(No difference)

← Older revision	Revision as of 05:12, 11 January 2021
(No difference)

@@ Line 1: / Line 1: @@
 Tile entities are like simplified entities that are bound to a <code>Block</code>. They are used to store dynamic data, execute tick based tasks and for dynamic rendering. Some examples from vanilla Minecraft would be: handling of inventories (chests), smelting logic on furnaces, or area effects for beacons. More advanced examples exist in mods, such as quarries, sorting machines, pipes, and displays.
-<block tip>
-A <code>TileEntity</code> isn’t a solution for everything, and they can cause lag when used wrongly. When possible, try to avoid them.
+{{Colored box|title=Tip|content=A <code>TileEntity</code> isn’t a solution for everything, and they can cause lag when used wrongly. When possible, try to avoid them.}}
 == Creating a <code>TileEntity</code> ==
@@ Line 42: / Line 41: @@
 These methods are called whenever the <code>Chunk</code> containing the <code>TileEntity</code> gets loaded from/saved to NBT. Use them to read and write to the fields in your tile entity class.
-<block tip>
+{{Colored box|title=Tip|content=Whenever your data changes you need to call <code><nowiki>TileEntity#markDirty()</nowiki></code>, otherwise the <code>Chunk</code> containing your <code>TileEntity</code> might be skipped while the world is saved.}}
-The tag names <code>id</code>, <code>x</code>, <code>y</code>, <code>z</code>, <code>ForgeData</code> and <code>ForgeCaps</code> are reserved by the super methods.
+{{Colored box|title=Important|content=It is important that you call the super methods!
-</block>
 == Ticking <code>TileEntity</code> ==
@@ Line 57: / Line 53: @@
 ITickableTileEntity#tick()
 </syntaxhighlight>
-<block tip>
-This method is called each tick. Therefore, you should avoid having complicated calculations in here. If possible, you should make more complex calculations just every X ticks. (The amount of ticks in a second may be lower than 20 (twenty) but won’t be higher)
+{{Colored box|title=Tip|content=This method is called each tick. Therefore, you should avoid having complicated calculations in here. If possible, you should make more complex calculations just every X ticks. (The amount of ticks in a second may be lower than 20 (twenty) but won’t be higher)}}
 == Synchronizing the Data to the Client ==
@@ Line 72: / Line 67: @@
 Again, this is pretty simple, the first method collects the data that should be send to the client, while the second one processes that data. If your <code>TileEntity</code> doesn’t contain much data you might be able to use the methods out of the [[#storing_data|Storing Data]] section.
-<block important>
+{{Colored box|title=Important|content=Synchronizing excessive/useless data for tile entities can lead to network congestion. You should optimize your network usage by sending only the information the client needs when the client needs it. For instance, it is more often than not unnecessary to send the inventory of a tile entity in the update tag, as this can be synchronized via its GUI.)}}
 === Synchronizing on block update  ===
@@ Line 109: / Line 102: @@
 SimpleChannel#send(PacketDistributor.TRACKING_CHUNK.with(() -> chunk), MSG);
 </syntaxhighlight>
-<block alert>
+{{Colored box|title=Alert|content=It is important that you do safety checks, the TileEntity might already be destroyed/replaced when the message arrives at the player! You should also check if the area is loaded using (<code><nowiki>World#isAreaLoaded(BlockPos, int)</nowiki></code>)}}