Method Overriding

Overriding Methods

The STB item inheritance hierarchy looks like this:






Each subclass adds a few methods, most of which provide default behaviour, but a few of which are abstract and must be implemented by you. All of these methods are detailed in the following section.


Abstract Methods

You must always provide an implementation for the following methods:

public String getItemName()The custom item's display name (as returned by item.getItemMeta().getDisplayName())

public String[] getLore()

The custom item's lore (as returned by item.getItemMeta().getLore()) - this is where you can put some descriptive text about what the item does, for example

public MaterialData getMaterialData()

The vanilla material and data used to represent the item in an inventory. Note this returns a MaterialData, not just a plain Material; this allows for coloured glass/clay etc. to be used. The STBUtil.makeColouredMaterial() utilty method may be handy here.

public Recipe getRecipe()

Returns a recipe to make the item. You can return null here if you don't want the item to be crafted with a vanilla recipe.

Optional Methods

You may also implement/override the following methods:

public String getDisplaySuffix()Any string returned here is appended to the item's display name. You can override this to encode some of the item's state (e.g. paint level in a Paint Brush) in the item's display name

public String[] getExtraLore()

Any string array returned here is appened to the item's lore. This can be used to encode more of the item's state (e.g. items filtered by an Item Router module)

public Recipe[] getExtraRecipes()

If there's more than one way to make your item, you can override this method to return one or more extra vanilla recipes.

public boolean hasGlow()

If you want the vanilla item that represents your STB item to have a glow effect (as if enchanted), override this method to return true. Note that items will only glow if ProtocolLib is installed.

public boolean isWearable()

If your item uses a vanilla material but should not be worn, override this method to return false.

public ItemStack getSmeltingResult()

If your item can be smelted (in a vanilla furnace, or STB Smelter), override this method to return the item that should be produced as a result. This method returns null by default.

public boolean isEnchantable()

Define whether this item may be enchanted in a vanilla enchanting table. By default, this method returns true. If your item uses an enchantable material, but enchanting it doesn't make sense, return false here.

Event Handler Methods

The following methods define how items respond to certain events. The default behaviour is generally to ignore the event, but you may override any or all of these:

public void onInteractItem(PlayerInteractEvent event)Called when a player interacts with your item while holding it.

public void onItemConsume(PlayerItemConsumeEvent event)

Called when a player attempts to consume your item (which will only happen if your item uses a vanilla material which is consumable, e.g. food, water bottle...)

public void onInteractEntity(PlayerInteractEntityEvent event)

Called when a player right-clicks some entity while holding your item.

public void onItemHeld(PlayerItemHeldEvent event)

Called when a player holds shift and rolls the mouse wheel while holding your item. Note that the held item will never be changed in this case; STB overrides the shift-mouse-wheel to call this event. It may be useful to configure some numeric or cyclable property of your item.

public void onBreakBlockWithItem(BlockBreakEvent event)

Called when a block is broken while holding your item. Note that is only called when the block will definitely be broken; you must never cancel or otherwise change the outcome of the BlockBreakEvent.


Optional Methods

public int getTickRate()

Defines how often the onServerTick() method (see below) should be called for this object. Default is 0, which means never call onServerTick(). If your block should have some periodic behaviour, override this method and onServerTick() to define how frequently it should act.

Event Handler Methods

public void onBlockDamage(BlockDamageEvent event)Called when this block is damaged. This event may be cancelled to prevent damage.

public void onBlockPhysics(BlockPhysicsEvent event)

Called when this block receives a physics event; a change in state of a neighbouring block.

public void onInteractBlock(PlayerInteractEvent event)

Called when a player interacts with this block in some way. The default behaviour is to attach a label sign if left-clicked with a sign; if you want to preserve this behaviour in your block, then be sure to call super.onInteractBlock(event) in your overriden method.

public boolean onSignChange(SignChangeEvent event)

Called when a sign attached to your block is updated. You could override this to allow some kind of configuration of the block based on the sign's text.

public boolean onEntityExplode(EntityExplodeEvent event)

Called when this block is affected by an explosion. Default behaviour is to return true, meaning the block will break, and drop its item form. If you override this to return false, your block will be immune to explosions.

public void onServerTick()

Called periodically for this block. The frequency of this call depends on what you have define for getTickRate() (see above)

public void onBlockPlace(BlockPlaceEvent event)

Called when this block is placed in the world. If you override this, you must always call super.onBlockPlace(event).

public void onBlockBreak(BlockBreakEvent event)

Called when this block broken. If you override this, you must always call super.onBlockBreak(event) and you must never cancel the event or otherwise alter the event's outcome.

Last updated