Blocks store data using a limited set of predefined BlockStates, render models through default rendering behavior, and execute logic via update and scheduling systems.
However, this approach has limitations and cannot directly support certain block behaviors required for game interactions.
Block entities solve this problem. They give ordinary blocks three key capabilities:
Block entities vary by block type, but a basic block entity typically contains:
Block entities are bound to blocks in the world. Each block position can only have one block entity instance.
Only blocks that are specifically declared can have block entities attached.
Block entities are added and removed alongside their blocks. However, through techniques like update suppression, you can retain a block entity even after its block is removed.
In Minecraft, the hopper is a block entity that handles automated item transfer.
A hopper block entity stores the following information:
inventory storage space (5 slots)transferCooldown cooldown (default is -1)lastTickTime world time of the last tickfacing directionEvery game tick, the hopper executes these steps:
Now, let's look at the detailed logic for pulling and outputting.
When the hopper is ready to operate, it first attempts to output to the container it's pointing at. Then it tries to extract items from above. Finally, if either operation succeeds, it sets the cooldown and syncs its data.
Let's look at output and pull separately.
First, output...
The output operation uses the insert() method, which transfers items from the hopper to the target container and returns a boolean indicating success. If the transfer succeeds, the hopper enters cooldown.
Basic output logic:
Check if the target container is available
Attempt to output items
When calling transfer() to move items, it returns an item stack:
That covers output. Now let's look at pulling.
The pull logic is similar to output, but in the opposite direction:
transfer()s items to the target container.transfer()s items to the hopper.Since we'll cover transfer() in detail next, we won't repeat it here.
transfer() is the core method that handles item transfer in hoppers. It takes the following parameters:
Here's how it works:
That covers the basic hopper mechanism. This foundation will help with the chapters ahead.
Another important block is moving_piston, commonly known as B36.
A moving piston block entity stores the following information:
pushedBlock the block being pushedfacing directionextending whether the piston is extending (determines animation direction)progress>=1, replace MOVING_PISTON with the block stored in pushedBlockFor details, see .
Decrease cooldown (cd)
Execute item transfer logic
Check the target slot
itemStack directly into it and clear itemStack.itemStack.Determine if the transfer succeeded
itemStack is empty, the transfer succeeded; otherwise it failed.Special timing for hopper-to-hopper transfers
8gt of cooldown.to has already ticked before the source hopper from, the target hopper to only receives 7gt of cooldown.
Note that this only occurs when the target hopper is empty.
Additionally, even iffromticks aftertoand applies8gtof cooldown,towill immediately subtract 1 when it ticks next, leaving only7gtof cooldown.
sourceprogress current movement progresssavedWorldTime world time when logic was last executedBlock entity ticking is managed by two lists in LevelChunk:
pendingBlockEntityTickers: block entities added during the current tick cycle.blockEntityTickers: block entities scheduled for ticking.Both lists are ArrayLists, so traversal order depends on insertion order. Here's the process:
tickBlockEntities() first appends pendingBlockEntityTickers to blockEntityTickers, then clears pendingBlockEntityTickers.blockEntityTickers, removed entries (isRemoved() returns true) are deleted; others have their method called.tick()New block entities are added via addBlockEntityTicker(). If ticking is in progress (tickingBlockEntities == true), they go to pendingBlockEntityTickers; otherwise to blockEntityTickers.
When unloading, block entities in the same chunk are stored in a Map<BlockPos, BlockEntity>. On reload, the map is iterated and each entity is added to blockEntityTickers via addBlockEntityTicker(), so execution order follows BlockPos.hashCode() order.
Across chunks, block entity order depends on which chunk loads first.
TL;DR:
Before unloading, block entity tick order matches placement order. After reloading, order within a chunk depends on position hash; across chunks, it depends on chunk load order.
Here's the relevant code (with some irrelevant content removed):