Effective
Base class for every custom item in the framework.
A subclass defines an item declaratively by overriding editMeta, getMaterial and getNamespacedData. On construction the item registers itself under its unique namespaced name (see getNamespacedName); creating a duplicate name throws.
Every stack produced by createItemStack carries the item's namespaced name in its persistent data (under ITEM_KEY), so a plain ItemStack can later be matched back to its EffectiveItem via getNamespacedKeyByItem / equalByNamespacedKey.
Behaviours are opt-in through the make* / add* methods, each backed by a dedicated Effective* interface (clickable, throwable, durable, wearable, craftable, droppable, …).
Declaring an item
object ExampleItem : EffectiveItem() {
override fun editMeta(meta: ItemMeta) {
meta.setDisplayName("§fExample item")
}
override fun getMaterial() = Material.FIREWORK_STAR
override fun getNamespacedData() = ExamplePlugin.instance to "example"
// Register behaviours here; call this from onEnable().
fun init() {
// makeThrowable { event -> ... } / makeDurable(3) / addClickHandler(...) / ...
}
}Picking a base material
If the item uses a custom texture from a resource pack (via a custom model/item model), prefer Material.FIREWORK_STAR as the base: it has virtually no vanilla use or behaviour, so overriding its model won't collide with a commonly-used item or trigger unwanted vanilla mechanics. Use a "real" material only when you want that material's own look/behaviour.
A Kotlin object is lazy — its code runs only when something first references it. Call the item's init() from onEnable so the class is actually loaded at startup; otherwise it is never constructed and its behaviours (click/throw/…) are never wired up. A telltale sign of a forgotten init() is the item simply not showing up (e.g. missing from /egive).
override fun onEnable() {
ExampleItem.init()
}(Loading also registers it under its getNamespacedName; two items with the same name throw.)
Textures
A getResourcePackData texture reaches the player only if the plugin enables its resource pack: call EffectiveResourcepack.addServerResourcepack(this, "", "") in onEnable after every item's init(). Without it the item exists (it's in /egive) but renders with the base material's look.
A built-in /egive <item> <player> command can hand out any registered item in-game.
Inheritors
Types
Resource-pack data for the item. Provide a model via modelPath (path to a model JSON inside the jar) or modelJson (the model JSON content itself); if both are null a default item/generated model is built from the texture. The texture comes from texturePath (a file inside the jar) or textureBytes (raw PNG bytes, e.g. generated at runtime); both are optional — omit them when the supplied model brings its own textures. modelJson takes precedence over modelPath, and textureBytes over texturePath.
Functions
Registers a brewing-stand recipe that yields this item.
Registers a click handler for stacks of this custom item (matched by key). To instead handle a plain vanilla Material, register through EffectiveClickable.addClickHandler with a non-custom stack.
Resolves the persistent-data key for the declared additional arg name — use it to read the per-stack value via EffectiveDataContainerUtils. See getAdditionalArgs for the full flow.
Registers a shapeless recipe that yields this item.
Creates a single stack of this item, fully finalized (meta, identity, behaviours).
Creates a stack of amount copies of this item.
Hook run on the finished stack after meta, identity and behaviours are applied.
Configures the stack's meta (name, lore, model, …). Called during every createItemStack.
Whether item is a stack of this item (matched by namespaced key).
Whether effectiveItem is the same registered item as this one.
Declares extra, per-stack parameters this item accepts — values baked into an individual stack's persistent data at creation time, so two stacks of the same item can carry different settings (e.g. a "radius" or "power" tuned per stack).
Namespaced keys backing this item's getAdditionalArgs (key → PDC type), or null if none.
The base Material the item is built from.
Owning plugin and a plugin-unique id; together they form the getNamespacedName.
Unique identity of the item as "<plugin-name>/<id>", both lowercased.
Optional resource-pack texture/model info for this item. When non-null, the framework generates the pack model/texture for it, and createItemStack automatically sets the stack's item_model to <plugin-namespace>:<id> so the custom texture shows — unless editMeta already set one.
Gives this item a durability bar acting as a limited-use counter.
Makes this item throwable: right-clicking launches a snowball carrying the item, and onHit runs when it lands. The projectile is identified by the item stored inside it.
Prevents this item from being dropped, and keeps it in the inventory on death.
Allows this item to be equipped to the head slot (right-click or helmet-slot drag).
Whether the getAdditionalArgs values are appended to the item's lore automatically.