Create your own Mechanic

Search…
also known as "How to superpower Oraxen?"
How does the Mechanic system work?
What's a mechanic?
A mechanic is a custom item property. There can be different variations of the same property on different items. For example, the durability property allows you to define a custom durability for an item, but not all items that have a durability mechanic have the same durability.
The durability mechanic works by storing the item's durability in its metadatas and uses the vanilla durability bar to display its custom durability and not its vanilla durability
So if a Mechanic is different for every Item, should I rewrite a different Durability everytime?
No, it would be far too long. Instead, Oraxen offers a MechanicFactory system. Basically you will have to create a Mechanics class that is configurable, and a MechanicsFactory class that will configure all the different versions of your Mechanic class. It will also manage the common code of all these versions.
Okay, but I want to modify the items which implement my Mechanic to store data in it, is it possible?
Of course, for this purpose Oraxen allows you to associate a list of ItemModifier to each mechanic. An ItemModifier is Function<ItemBuilder, ItemBuilder> which is basically a small piece of code that contains changes to be made to an item when it is generated by the server via its configuration. For example for durability mechanics I use an itemModifier that stores the durability chosen by the user in the item's metadatas.
1
item -> item.setCustomTag(NAMESPACED_KEY,
2
                        PersistentDataType.INTEGER, section.getInt("value"))
Copied!
Let's create our first mechanic
For this tutorial I will take as an example the durability mechanic (because it is very simple to understand) but you can follow this tutorial to create the one you want.
First step: create our mechanic class
Start by creating a class inheriting from Mechanic, if you use intelliJ you should get something like this:
1
class DurabilityMechanic extends Mechanic {
2
​
3
    public DurabilityMechanic(MechanicFactory mechanicFactory, 
4
                    ConfigurationSection section,
5
                    Function<ItemBuilder, ItemBuilder>... modifiers) {
6
        super(mechanicFactory, section, modifiers);
7
    }
8
​
9
}
Copied!
The Mechanic constructor takes three arguments:
1
- An instance of the Factory which created the Mechanic
2
- The section used to configure the Mechanic
3
- The item modifier(s)
Copied!
I want each variation of my mechanics to have a different durability, so I will read the configuration of the mechanics and store the value of the field value.
How the Mechanic configuration section will look like:
1
class DurabilityMechanic extends Mechanic {
2
​
3
    private int itemDurability;
4
​
5
    public DurabilityMechanic(MechanicFactory mechanicFactory, 
6
                              ConfigurationSection section) {
7
        /* We give:
8
        - an instance of the Factory which created the mechanic
9
        - the section used to configure the mechanic
10
        - the item modifier(s)
11
         */
12
        super(mechanicFactory, section, item ->
13
                item.setCustomTag(NAMESPACED_KEY,
14
                        PersistentDataType.INTEGER, section.getInt("value")));
15
        this.itemDurability = section.getInt("value");
16
    }
17
​
18
    public int getItemMaxDurability() {
19
        return itemDurability;
20
    }
21
}
Copied!
So now we have a DurabilityMechanic class that is able to adapt to any item and that will call our DurabilityModifier class to tell to Oraxen which modifications to do before creating them (here we just add a data in the item which contains the wanted new durability).
Second step: create our mechanic factory class
As before, use your ide features to automatically create a class that extends MechanicFactory:
1
class DurabilityMechanicFactory extends MechanicFactory {
2
​
3
    public DurabilityMechanicFactory(ConfigurationSection section) {
4
        super(section);
5
    }
6
​
7
    @Override
8
    public Mechanic parse(ConfigurationSection itemMechanicConfiguration) {
9
        return null;
10
    }
11
}
Copied!
We rewrite the parse method to create a new Mechanic (via the DurabilityMechanic class created previously). We also want to tell to Oraxen that this mechanic is successfully implemented and can be loaded using addToImplemented method. So our class now looks like that:
1
public class DurabilityMechanicFactory extends MechanicFactory {
2
​
3
    public DurabilityMechanicFactory(ConfigurationSection section) {
4
        super(section);
5
    }
6
​
7
    @Override
8
    public Mechanic parse(ConfigurationSection itemMechanicConfiguration) {
9
        Mechanic mechanic = new DurabilityMechanic(this, itemMechanicConfiguration);
10
        addToImplemented(mechanic);
11
        return mechanic;
12
    }
13
​
14
}
Copied!
Third step: add our features (events)
In my case I need to use only one event to play with durability and I will create a DurabilityMechanicsManager class that implements Listener to have a clean and tidy code but I could have done it directly in DurabilityMechanicFactory. I tell to Bukkit which class manages the events when the factory is built:
1
public class DurabilityMechanicFactory extends MechanicFactory {
2
​
3
    public DurabilityMechanicFactory(ConfigurationSection section) {
4
        super(section);
5
        MechanicsManager.registerListeners(OraxenPlugin.get(),
6
                new DurabilityMechanicsManager(this));
7
    }
8
​
9
    @Override
10
    public Mechanic parse(ConfigurationSection itemMechanicConfiguration) {
11
        Mechanic mechanic = new DurabilityMechanic(this, itemMechanicConfiguration);
12
        addToImplemented(mechanic);
13
        return mechanic;
14
    }
15
​
16
}
Copied!
In order to calculate the durability to display on the item according to the real durability managed by the plugin I use some simple maths:
bukkitDamage=bukkitMaxDurability−realDurability∗bukkitMaxDurabilityrealMaxDurabilitybukkitDamage = bukkitMaxDurability - \frac{realDurability*bukkitMaxDurability}{realMaxDurability}bukkitDamage=bukkitMaxDurability−realMaxDurabilityrealDurability∗bukkitMaxDurability​
So this is my DurabilityMechanicsManager class:
1
class DurabilityMechanicsManager implements Listener {
2
​
3
    private DurabilityMechanicFactory factory;
4
​
5
    public DurabilityMechanicsManager(DurabilityMechanicFactory factory) {
6
        this.factory = factory;
7
    }
8
​
9
    @EventHandler(priority = EventPriority.HIGH, ignoreCancelled = true)
10
    private void onItemDamaged(PlayerItemDamageEvent event) {
11
        ItemStack item = event.getItem();
12
        String itemID = OraxenItems.getIdByItem(item);
13
        if (factory.isNotImplementedIn(itemID))
14
            return;
15
​
16
        DurabilityMechanic durabilityMechanic = 
17
                (DurabilityMechanic) factory.getMechanic(itemID);
18
​
19
        ItemMeta itemMeta = item.getItemMeta();
20
        PersistentDataContainer persistentDataContainer = 
21
                itemMeta.getPersistentDataContainer();
22
        int realDurabilityLeft = persistentDataContainer
23
                .get(DurabilityMechanic.NAMESPACED_KEY, PersistentDataType.INTEGER) 
24
                        - event.getDamage();
25
​
26
        if (realDurabilityLeft > 0) {
27
            double realMaxDurability = 
28
                    //because int rounded values suck
29
                    durabilityMechanic.getItemMaxDurability();
30
            persistentDataContainer.set(DurabilityMechanic.NAMESPACED_KEY,
31
                    PersistentDataType.INTEGER, realDurabilityLeft);
32
            ((Damageable) itemMeta).setDamage((int) (item.getType()
33
                    .getMaxDurability() - realDurabilityLeft 
34
                    / realMaxDurability * item.getType().getMaxDurability()));
35
            item.setItemMeta(itemMeta);
36
        } else {
37
            item.setAmount(0);
38
        }
39
​
40
    }
41
​
42
}
Copied!
Last step: register our mechanic
Just call this line when you load your plugin (e.g. in your onEnable method):
1
MechanicsManager.registerMechanicFactory("durability", 
2
                                DurabilityMechanicFactory::new);
Copied!
Conclusion
To properly create a new mechanic it is recommended to separate its code into three parts:
A factory which extends MechanicFactory​
A mechanic which extends Mechanic​
Your own features in a <YourMechanicName>MechanicsManager class (optional too)
While it is possible to modify items using your mechanic thanks to an ItemModifier:
1
item -> item.setCustomTag(NAMESPACED_KEY,
2
                        PersistentDataType.INTEGER, section.getInt("value"))
Copied!
You can also modify the texture pack in a similar way:
1
ResourcePack.addModifiers(packFolder -> {/* your modifications */});
Copied!
Finally register your mechanic!
To summarize the tutorial, here is the complete source code of the durability mechanics.
Developers - Previous
API
Next - Developers
Add Compatibility with a plugin
Last modified 2mo ago
Copy link
Contents
How does the Mechanic system work?
What's a mechanic?
So if a Mechanic is different for every Item, should I rewrite a different Durability everytime?
Okay, but I want to modify the items which implement my Mechanic to store data in it, is it possible?
Let's create our first mechanic
First step: create our mechanic class
Second step: create our mechanic factory class
Third step: add our features (events)
Last step: register our mechanic
Conclusion