Bring a Dungeons & Dragons inspired attunement system to Minecraft!
Artifactory introduces a highly configurable item bonding mechanic that allows items to be attuned to players enhancing gameplay with configurable bonuses, restrictions, and penalties. Whether you're running a roleplay-heavy server or chilling in single player this system will create meaningful interactions between players and their items.

Overview

Entirely data-driven attunement system where almost everything is configurable.
Create and grow bonds with existing items, armor, and weapons to gain unique benefits like unbreakable, attribute increases, and soulbound items that persist through death.
Protect your attuned items from despawning and being destroyed by the environment.
Only the player who is bonded to the item can use it, it's allegiance is entirely to them. Even holding an item that is bonded to another player causes bad things to happen.
Curios compatability.
Should be compatible with all other mods.
Default vanilla datapack included, you can install and play without any configurations. You can always tweak it to fit your world or server's needs as you go!

Getting Started

If you don't want to use the vanilla datapack provided or just want to tweak it then first you need to configure all of the items that you want to be attuneable by using datapacks. I will describe this in detail in the datapack section below. Once an item is configured to be attuneable it will look like this:

unattuned diamond sword

This shows that no attunement has been made with this item and it reserves 2 slots when attuned. It also does not say "Attunable (Required)" which would mean this item would be unusable in any way until it is attuned, gating the use of the item behind its attunement. To get started with the attunement process lets build the Attunement Nexus. The default recipe is:

Once you have an Attunement Nexus you will find a single slot in the menu. This is where you will place the attuneable item. It will only let you place items that can be attuned to. Once you place the item you will see some relevant information:

Attunement Level: The current level of attunement you have with the item. Not yet attuned if not.
Slots Reserved: The number of slots this item requires to attune.
Attunement Slots information. Hover over it for more details.
Level Cost: The number of levels that is consumed by the attunement process.
Level Threshold: The number of levels required to start the attunement process. This does not mean it will consume these levels, its just the minimum number required for the player to have before they can begin.
Items Required: You must place the required items in the slot in order to attune it. These are consumed.
Red Information Icon: If there are any requirements you currently do not meet to start the process. Hover for more information

If you meet the requirements then you can start the attunement process! After it completes it will consume the required levels and / or items (if any are configured) and then bond the item to you. This can only be done if you have the required attunement slots available for the first time you bond it (further levels do not take up more slots). There is a helpful red information icon to the left of the attune button if there are any issues with the attunement starting, that is the first place I would go for information on why the attunement process cannot start. Here is the progression of the vanilla datapack diamond sword from attunement level 1 (left) all the way to the max attunement level of 3 (right). Each level adds some new traits and stats to it.

Viewing and Breaking Attunements

You can view and manage your current attunements in the manage attunements screen. This can be opened from the attunement screen in the top right (the cog wheel icon) or from pressing the assigned hotkey (default 'o'). After attuning to the max level with the diamond sword above it will look like this:

If you want details about what each level of the attunement added to the item then hover over the blue (i) icon to get more information:

If you no longer want to have an attunement with the item then when you hover over the item card there will be a red X on the right side. Press this and confirm the prompt to break the attunement. This will remove all benefits from the item you gained while attuning it but will keep all other stats on the item like enchantments or modifications from other mods. The item can now be attuned to someone else and you can use the slots you gained back from breaking the attunement to attune to other items.

System Overviews

Attunement System

Artifactory adds a new attribute: attunement slots. When an item is configured to be attuneable you can specify how many attunement slots that item reserves once it is attuned. This can include reserving no slots so it can be freely attuned without affecting your slot limit. If you do not have the necessary number of open slots to attune an item then the item cannot be attuned until some spots are cleared up, which can be done by breaking attunements to other items or finding a way to increase that attribute. The attunement process can also require items or experience levels to attune which will be consumed when the attunement completes.

Enhancement System

Attuning an item offers fun and powerful benefits. As you grow your bond these benefits will grow as well.

When you attune an item for the first time you the item will reserve the number of attunement slots it was configured to and you will gain any of the benefits for a level one attunement with that item. If more levels are configured then you can ascend that bond to gain whatever benefits are configured for those levels. Currently those benefits can be:

Artifactory Modifications:

Invulnerable: The item can no longer be destroyed by environmental effects, like lava or a cactus. It will also never despawn when dropped onto the ground.
Unbreakable: If the item has a durability it will become unbreakable.
Soulbound: When you die the item will travel with you through death.

Attribute Modifications:

You can specify any attribute (including other mod attributes) to be added to the item when reaching an attunement level. These, combined with the basic modifications above, will allow you to create truly powerful items as you level them up.

Restriction System

An attuneable item can be configured such that it MUST be attuned before it can be used in any way or it can be usable as normal and attuning it just offer further benefits. If it must be attuned before it can be used then that item cannot do damage, break blocks, or be used in any way like trying to draw a bow, until it is attuned to you.

Items that are attuned cannot be used by other players in any capacity, it only shows allegiance to its owner. Further you may add effects that are applied to players when they are holding an attuned item that does not belong to them. Say slowness 3, poison 1, and / or wither 100, it's up to you. By gating powerful items behind requiring them be attuned, as well as having them reserve more slots once they are attuned, you can make it so players have to choose which items they want to have access to without letting them have access to everything in the game. This will allow many powerful armor, weapons, and items to exist and force players to have to pick certain ones to specialize in.

Unique items are another way to restrict items, but much more severely. A player can only attune a certain amount of unique items total (configured in server settings) regardless of any open attunement slots. Further, in a multiplayer setting, a unique item can only be attuned by ONE player, and NO others. If a player attunes to Sword of 1000 Truths and that item is configured to be unique, they are the only player who can attune to that item type in that world, even if another player finds another Sword of 1000 Truths. While they have that attunement in place no other player will be allowed to attune it until they break the attunement. On a single player server this allows you to further limit end game items, and on a multiplayer server it will create an interesting item economy as well as players who are known for being the weilder of a specific item. (I strongly suggest Simply Swords for this as their mythic weapons, of which there are plenty and they're pretty broken / awesome, would be a good target.)

Datapack Configuration

Let's change the default datapack's Diamond Sword attunement configuration. First in the datapack you will create a new file under data/minecraft/artifactory/diamond_sword.json and add these contents:

{
  "slots_used": 4,
  "attunement_levels": [
    {
      "modifications": [
        "invulnerable",
        "unbreakable",
        "attribute/minecraft:generic.attack_damage/addition/5/mainhand"
      ],
      "requirements": {
        "items": ["minecraft:diamond_sword", "minecraft:diamond#10", "minecraft:nether_star"]
      }
    },
    {
      "modifications": [
        "soulbound",
        "attribute/minecraft:generic.attack_speed/multiply_base/.5/mainhand",
        "attribute/minecraft:generic.attack_damage/addition/7/mainhand"
      ],
      "requirements": {
        "xpLevelsConsumed": 45,
        "xpLevelThreshold": 55,
        "items": ["minecraft:dragon_egg"]
      }
    }
  ],
  "use_without_attunement": false,
  "unique": true,
  "replace": true
}

This file describes the attunement configuration for the diamond sword. Lets go through each key.

"slots_used"

Semi-Optional - defaults to -1

How many attunement slots it takes up when attuning the item. In this example a diamond sword will take 4 of your attunement slots to attune to. If you leave this off then it will void the attunement configuration for this item and the item will no longer be attuneable. This is how you can overwrite and remove attunement information from another datapack.

"use_without_attunement"

Optional - defaults to true

If the item is usable without attuning to it first. false means the item will do no damage, break blocks, and cannot be used like when trying to draw a bow and fire it, until it is attuned. true means that the item is still usable as normal even when it isn't attuned. Attuning to it will just offer further benefits.

"replace"

Optional - defaults to false

If the current configuration should replace any existing configurations. If you try to create a new json file for a trident it will conflict with the one I already created in my mod. In order to tell it which one to use you will want to set "replace" to "true" so it knows to use this one. As a modpack maker you may as well add this to all of your configs to make sure they are the ones used. If for some reason you are using a mod that already has configs that include "replace": "true" in them you will then need to make sure your datapack loads AFTER theirs, it will take the most recently looked at config with "replace".

"attunement_levels"

Optional - defaults to a single level of attunement. That attunement level's experience level cost and threshold use the server configs values and when attuned it grants the 3 basic modifications: invulnerable, unbreakable, and soulbound. No attributes are included by default.

This is where you define what each level of attunement looks like. This is done in order, so the first object will be what applies for attunement level 1, the second for attunement level 2, and so on. For now it just consists of 2 keys, "modifications" and "requirements". "requirements" allows you to overwrite the server config requirements so you can customize each attunement level individually, as well as add item requirements. "modifications" is where you put all of the modifications to the item that happen when it is attuned.

-"modifications"

Optional - Defaults to applying invulnerable, unbreakable, and soulbound.

There are 3 basic modifications: invulnerable, unbreakable, and soulbound.

There are also attribute modifications which grant the item the attributes when they achieve the specified level of attunement. They are of the format

"attribute/modid:attributename/operation/value/equipmentslot".

operation can be 3 values: addition, multiply_base, multiply_total.

equipmentslot can be one of 6 values: mainhand, offhand, feet, legs, chest, head.

The operation and equipment slot values are vanilla minecraft constructs, so I would research those further there if you have questions. This is how the attribute is applied to the existing attribute and which slot the item must be worn in order for the attribute to take effect. Make sure you match up the equipment slot with the type of item you are dealing with. If you are configuring a helmet make sure to use head or the attributes will not apply when you put it on.

It should be noted that anytime you put an attuned item into the attunement nexus it syncs the modifications to the item, so if changes have been made to the datapack then all you need to do is put your item into the attunement nexus and it will update it with the changes.

In the example JSON above for attunement level one we have "attribute/minecraft:generic.attack_damage/addition/5/mainhand". We are specifying an attribute modification, a minecraft attribute increase to attack damage of 5, and telling it to apply only when item is in the mainhand. Since we are configuring a Diamond Sword this will add 5 damage once you have reached level 1 attunement with it and you're using it in your mainhand. You can also see in the level 2 attunement block it specifies the same attribute again but with a value of 7. When you reach level 2 attunement you will have a total of 12 additional attack damage, 5 from the level 1 attunement and 7 from the level 2 attunement. It also gives a 50% attack speed boost to the base attack speed at level 2.

-"requirements"

Optional - If left blank it will use the server config values

This allows you to overwrite the config values for a specific level of how many levels are required to start the attunement process and how many are consumed upon the attunement.

--"xpLevelsConsumed": How many levels are consumed to complete the attunement process

--"xpLevelThreshold": How many levels are required before the process can be started.

--"items": What items, if any, are required to attune. It will only take the first 3 items in the array. These take the form "modid:item_name#numberOfItems". The number of items is optional and defaults to 1 if left off. So if you wanted an attunement level to require a nether star and 64 diamonds you would put "items": ["minecraft:nether_star", "minecraft:diamond#64"].

We see both attunement levels require items and the level 2 attunement overwrites the xp server config values with new values that only apply when trying to attune to that level. This lets you specify requirements on a more granular level.

All said and done after you reach level 2 attunement the item will be unbreakable, invulnerable, soulbound, and grant 6 additional attack damage, as well as only being usable by you and no one else. Here is what that would look like at attunement level 2:

Now lets look at the simplest config possibly an attuneable item can have and what it means.

{ "slots_used": "1", "replace": true }

If we used this for our diamond sword instead by default it would create a single attunement level that requires the server configs xp levels and xp threshold to attune to. It would take up 1 attunement slot and is usable as a normal diamond sword even if you haven't attuned to it, so attuning is optional. When you attune to the item it will grant the item invulnerable, unbreakable, and soulbound. That is as far as that item can be attuned however, and no attributes are added by default.

In the final example we will remove an attunement configuration from an item from another datapack. The default datapack provided by this mod makes about 30 items attuneable, like the diamond sword. If you want to make it so these items aren't attuneable you need to overwrite them in your own datapack. To remove the ability for tridents to be attuned place this json file in your datapack at data/minecraft/artifactory/trident.json:

{ "replace": "true }

The replace tells it to use this configuration instead of the base one, and including no other information tells it to turn off this attunement. You should always use replace if you want this datapack configuration used instead of the other one. If while loading the datapack data there are more than one JSON files with "replace": true then it will use the last one loaded.

You can create attuned armor or weapons very easily and apply relevant attributes to those items, like extra armor for armor pieces or attack damage for swords, or vice versa, it's up to you. If you use a library like apothic attributes, which I highly recommend, it will give you a bunch of fun new attributes to apply to items as well.

Use cases

Here are some examples of use cases that I will be using this for in my modpack.

Create a fun system of bonding to a weapon and growing that bond while gaining cool, entirely customizable, benefits!
Limit items that are too powerful. Many mods add items that are very fun but too powerful. This becomes especially noticeable when a player amasses too many of these items and the combat, exploration, or travel of minecraft becomes trivial from having multiple mod's end game items. You might as well play creative at that point. I wanted a system to allow these endgame/chase items to exist but make them harder to obtain and so players would have to make a choice on which of these items they could use at any given time. The more powerful the item the more attunement slots it may take in order to attune, making you choose between having more individual but lower power items, are a few more powerful ones. This pairs great with the mythic weapons from Simply Swords.
Make older tier / less powerful items more desirable. Now instead of getting rid of your iron sword in favor of a diamond one you could attune the iron sword and gain special benefits as you bond with it. As you increase the attunement levels with it it could gain more damage and attack speed, along with it becoming unbreakable and soulbound. Throw on some enchantments and you could create a very powerful item! Diamond swords may also be attuneable but gain different benefits at different levels, or may not be attuneable at all. This creates an interesting item economy, gives value to different tiers of items, and gives more balancing options to modpack makers.

Possible Future Expansions

More Unique modifications alongside Soulbound / Invulnerable / Unbreakable.
Effect modifications - When wearing or holding the item the specified effects will be applied to the player.
Add more unique requirements to attune and strengthen the attunement on an item. Things like number of kills while wearing / using the item, killing certain bosses, performing certain feats, having it on you for a length of time, etc.

Please leave any comments, questions, suggestions if you'd like! If you have issues I would prefer creating an issue on the github repo with as much information as possible, but a question on here is fine too. Artifactory Issues

FAQ

Q: Will you make this for Fabric?

A: I will not be porting to Fabric, but anyone is welcome to do so! For Forge I will only be supporting 1.20.1 for now, and I will be porting this to NeoForge going forward on 1.21. From there I will stay on NeoForge, I don't have the time to manage too many different versions of this.

Q: Will you backport this to older Minecraft version?

A: Unless it sees a lot of interest I will only be developing on 1.20.1 and forward.

Q: Can I use this on my server or modpack?

A: Of course!

Featured projects

Curated by

Ascii like shader