Implementation of hopper logic for pushing, pulling and picking up items for PocketMine-MP.

VanillaHopper

In pm4, hopper blocks were implemented to have an inventory. But the logic for pushing, pulling and picking up items was missing nonetheless. This plugin aims to add this logic to the hopper.

Optimizations

Normally a hopper should run a block update every tick to reduce and check its cooldown if it has expired. Because it is highly inefficient to update all loaded hoppers every tick, just for letting them reduce their cooldown by one, the block update of hoppers is always scheduled to the expiration of their cooldown and not directly the next tick. To prevent any issues with the cooldown, hoppers are saving in which tick they were lastly updated to prevent them from updating too early.

Customizations

Customizations can be done in the config.yml in the plugin's plugin_data folder:

• hopper.transferCooldown: 8
  • The default cooldown of hoppers in Minecraft is 8 ticks. To in- or decrease the cooldown, you can just edit this number.
• hopper.itemsPerUpdate: 1
  • Normally a hopper only pushes one item and pulls or picks up one per update. You can specify how many items a hopper will try to push, pull or pick up when updated. This can be useful if you increased the cooldown of hoppers but want to keep the same "item per tick" ratio.
• hopper.alwaysSetCooldown: false
  • A hopper is normally only set on cooldown if it either pushed, pulled or picked up an item in an update. If it couldn't, it would receive another update in the next tick. As it is very performance costly that maybe dozens of hoppers of an empty hopper system are updated every tick, you can specify if hoppers should even be set back on cooldown, if they haven't pushed, pulled or picked up an item.
• hopper.updatesPerTick: 0
  • By default, there is no limit on how many block updates can be scheduled per tick. As it would be very performance costly to have scheduled hundreds of hopper updates scheduled on the same tick, you can change this number, to limit the number of hopper updates that are allowed to be scheduled per tick. If a hopper update would be scheduled on a tick that is already on the max value, the update is scheduled on the next tick that's not on the max value.

FAQ

What are your sources?

Every information about the logic for pushing, pulling and picking up items came from the minecraft fandom wiki.

Why are there so many comments in the code?

Minecraft's hopper logic is very complex. To prevent anybody from getting confused about how certain things were done, most parts were commented to explain what was done and why.

Why not create a PR?

I did, but it was stated that hopper logic won't be implemented in pm4 and because I didn't want to maintain a PR for the time till pm5, I closed it. Still, I wanted to use that logic in a plugin to use it myself and therefore I created this.

Tests

• Functionality tests

  • Every block a hopper can push items into was tested if it works as explained in the sources.
  • Every block a hopper can pull items from was tested if it works as explained in the sources.
  • The collision box of the area where the hopper should pick up items was checked and works as explained in the sources.

• "Performance" tests

  • 128 hoppers pushing 27 * 64 dirt from one chest to another (Timings):

For developers

Event handling

• Through the different events, you can easily implement your own rules for hoppers. Handle these events by simply creating an ordinary listener (class EventListener implements Listener) in your plugin and import (use keyword) them by their namespace (event name: namespace).
• BlockItemPickupEvent: pocketmine\event\block\BlockItemPickupEvent
  • This event is called when a hopper tries to pick up an item.
• HopperEvent: ColinHDev\VanillaHopper\events\HopperEvent
  • This event is called when a hopper either tries to push or pull an item.
• HopperPushEvent: ColinHDev\VanillaHopper\events\HopperPushEvent
  • This event is called when a hopper tries to push an item.
• HopperPushContainerEvent: ColinHDev\VanillaHopper\events\HopperPushContainerEvent
  • This event is called when a hopper tries to push an item into a block's inventory.
• HopperPushJukeboxEvent: ColinHDev\VanillaHopper\events\HopperPushJukeboxEvent
  • This event is called when a hopper tries to push a record into a jukebox.
• HopperPullEvent: ColinHDev\VanillaHopper\events\HopperPullEvent
  • This event is called when a hopper tries to pull an item.
• HopperPullContainerEvent: ColinHDev\VanillaHopper\events\HopperPullContainerEvent
  • This event is called when a hopper tries to pull an item from a block's inventory.