Custom Item Reference - jojodmo/CustomItems GitHub Wiki
This is for advanced users only. Instead, you should use /cui create or /cui edit to create your item entirely from an in-game GUI
General Info
Everything in [brackets] is required. Everything in (parentheses) is optional.
For more in-depth info about some of the options, see https://github.com/jojodmo/CustomItems/wiki/Creating-a-Custom-Item
If you're confused on how some of the options work, check out the example configuration at the bottom of this page, here, keeping in mind that this item won't actually load! It's just meant to show you how certain aspects work: https://github.com/jojodmo/CustomItems/wiki/Custom-Item-Reference#custom-item-reference-example
Just incase you don't know, A string is something in quotes "like this", and a list can be made using -'s, so a list of strings is
myList:
- "item 1"
- "item 2"
Reference Lists
Minecraft Item List Minecraft Entity Type List Minecraft Potion Type List Minecraft Enchantment List Minecraft Biome List
Referencing Items
For custom items, use the custom item's unique id (yml file name). For Minecraft items, use the Minecraft item name (preferably prefixed with "minecraft:")
If you're using Minecraft 1.13 and below, you can sometimes use data values in the item name (for example, in crafting recipes). In this case, just add a colon after the item name, followed by the data value. For example, ink_sack:7 or minecraft:ink_sack:7.
Referencing Colors
On any "color" attribute, you can provide a six-character hexadecimal color code like "00AAFF" or "E41517". Google "hex color code picker".
Hex support for 1.16+
Hex colour codes can be used for mc version 1.16+ like �aaff for everywhere in CustomItems
Referencing Enchantments
To reference enchantments, set create a key in the YAML file with the enchantment's name, and set it to the level of the enchantment. This also works with custom enchantments from other plugins:
enchantments:
# Unbreaking 3
"minecraft:DURABILITY": 3
# Thorns 2
"minecraft:THORNS": 2
See Minecraft Enchantment List for the names of the Minecraft enchantments
Referencing Potions
To reference just the effect (for string parameters), use the potion's Minecraft name (you can find a list of names in the reference list above)
To reference potions (for potion parameters), use the following keys:
type: [string - "NIGHT_VISION" for example]
time: (number - seconds | default: 20)
strength: (number | default: 1)
particles: (true/false | default: true)
ambient: (true/false | default: true)
showIcon: (true/false | default: true)
See Minecraft Potion Type List for the names of the Minecraft potion effects
Top level entries
#in myCustomItem.yml:
name: [string]
soulbound: (true/false | default: false | read below for more info)
category: (string | default: "miscellaneous")
native: (true/false | default: false | read below for more info)
version: (number | default: 1)
forceUpdate: (true/false | default: false)
item: [item - see below]
texture: (texture - see below)
armor: (armor - see below)
block: (block - see below)
info: (optional)
description: (string)
usage: (string)
making: (string)
obtaining: (string)
relatedItems: (string list)
recipes: (recipe list - see below)
canBeUsedGenerically: (true/false | default: false) (See Below For Explanation and use case)
canBePlaced: (true/false | default: canBeUsedGenerically if the item is a block, or true if canBeUsedGenerically isn't set and the item is a block)
consumable: (true/false | default: canBeUsedGenerically)
shootable: (true/false | default: canBeUsedGenerically) #DO NOT USE ON A BOW
enchantable: (true/false | default: true, or canBeUsedGenerically if set)
repairable: (true/false | default: true, or canBeUsedGenerically if set)
anvilRepairItems: (repair items — see below)
handlers: (handlers - see below)
See: item(https://github.com/jojodmo/CustomItems/wiki/Custom-Item-Reference#item) (recipe list) (texture) (armor) (block) (anvilRepairItems) (handlers)
Soulbound items
Set this to true if you want your item to be soulbond "kept on death"
Then, give the player permissions. To give them permission for a specific item, give them the permission customitems.soulbound.[myCustomItemIDHere]. To give them permission for an entire category, give them the permission customitems.soulbound.category.[myCustomItemCategoryHere].
Check out the permissions on wiki for more info: Permissions Soulbound(https://github.com/jojodmo/CustomItems/wiki/Permissions#customitemssoulbounditem)
Native
Set this to true only when you want to modify a default Minecraft item. Make sure that you set item.material to the Minecraft material, and name the item.yml file the name of the Minecraft item. For example, if you wanted to modify the behavior of Iron Ore,
# in iron_ore.yml (it MUST be called "iron_ore.yml" for iron ore)
name: "Iron Ore"
native: true
item:
material: "minecraft:IRON_ORE"
# anything else you want to put here
forceUpdate and version
If forceUpdate is true, all Custom Items of previous versions will automatically be updated to ones of the newest version when a player clicks on them. Be careful! Only enchantments are carried over to the new item — anything else the player added, like custom names, will be removed!
If you want to use forceUpdate, we recommend you increment the version of the item every time you want your players' items to update. If you want to force items to update every time the server starts (even if there were no changes), you can set version to -1 and forceUpdate to true, but keep in mind that setting version to -1 will cause the item to become unstackable. So, we recommend that you just increment the version number for every update, instead.
canBeUsedGenerically
The canBeUsedGenerically attribute simply tells the game if your custom item should act like your material by default, or not. This also allows your CustomItem to be used in crafting recipes in place of the vanilla item. It's recommended that it's only used for if you're making a tool very similar to a vanilla one.
So if you had canBeUsedGenerically on a material:apple, you're making a food item that by default acts/restores just like an apple. This also allows it to be used in crafting recipes in place of a normal Minecraft apple
Such as:
item:
material: apple
textureID: 1
canBeUsedGenerically: true
If the above purple_apple instead had false, you'd have a purple apple item that did nothing and had no actions, and also couldn't be used in place of an apple in crafting.
[item]
#in myCustomItem.yml
item:
material: [string]
dataValue: (number | for MC 1.13 and below | default: 0)
textureID: (number | default: nothing)
attributes: (attributes — see below)
displayName: (string)
lore: (list of strings)
enchantments: (list of strings)
color: (color - see "general info" above)
headOwner: (string - only valid for player heads — can be either a UUID or a username)
durability: (number | default: -1, meaning unbreakable)
itemDamage: (number | default: 0)
damageable: (true/false | default: true if durability is set)
glows: (true/false | default: false)
hideDurability: (true/false | default: false)
hideDurabilityBar: (true/false | default: false)
hideEnchantments: (true/false | default: false)
hideAttributes: (true/false | default: true if attributes set, otherwise false)
hideFlags: (true/false | default: false)
nbt: (map of string:value | see below)
Note that hideDurability will act just like hideAttributes if the item doesn't have a custom texture
see: (attributes)
nbt can be a map of string:value, like this:
item:
nbt:
nbtKey: nbtValue
nbtMap:
nbtMapKey: nbtMapValue
nbtList:
- nbtListValue1
- nbtListValue2
Making Custom Heads
1.14 and above
#in myCustomItem.yml
item:
material: PLAYER_HEAD
headOwner: 'I_mundercover'
1.13 and below
#in myCustomItem.yml
item:
material: SKULL_ITEM
dataValue: 3
headOwner: 'I_mundercover'
More custom heads
If you would like to use a head that doesn't belong to a skin (for example, a head from https://minecraft-heads.com/custom-heads), you will need to take the data from the /give command and put it into your item yml file under nbt under item. Check out the nbt section below for more info on how to do this.
nbt
There are two ways of setting nbt. The first way to do it is by simply setting keys and values, like this:
item:
nbt:
myFirstNBTKey: "myFirstValue"
mySecondNBTKey: 2
myThirdNBTKey: "three"
You can also set nbt to the special data from a /give command (the JSON data from the command). For example, for the command
/give @p minecraft:player_head{SkullOwner:{Id:"dddcc92a-e6d8-4b00-9043-3881966741b7",Properties:{textures:[{Value:"eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZjJjMjlkNTIyOThjMzM5NjdhOTFiOTdiODZkNjQ5Y2VkMTY5ZWNmMzRmMzFkMjk1ZGM0MGQwNDAyNmY1MzJlZiJ9fX0="}]}}}
You would use
#in myCustomItem.yml
item:
material: PLAYER_HEAD
nbt: '{SkullOwner:{Id:"dddcc92a-e6d8-4b00-9043-3881966741b7",Properties:{textures:[{Value:"eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZjJjMjlkNTIyOThjMzM5NjdhOTFiOTdiODZkNjQ5Y2VkMTY5ZWNmMzRmMzFkMjk1ZGM0MGQwNDAyNmY1MzJlZiJ9fX0="}]}}}'
(recipe list)
This is for advanced users only. Instead, you should use /cui create or /cui edit to create the recipes from an in-game GUI
#in myCustomItem.yml
recipes:
# Start of a new CRAFTING recipe
-
shaped: [true / false | required only for crafting recipes]
items: [required - see the two recipes below this one for more info]
-
item: [string - item reference - see above]
amount: (number | default: 1)
allowDamaged: (true/false | default: false)
key: [character - ONLY FOR SHAPED RECIPES - the character in the shape for this item]
-
item: [string - item reference 2 - see above]
# ...
-
#... etc
resultAmount: (number | default: 1)
permission: (string - permission required to use this recipe - becomes "customitems.recipe.PERMISSION_HERE")
noPermissionMessage: (string | default: "You don't have permission!")
# Start of a new SHAPED recipe
-
shaped: true
shape: [string list representing shape — see below]
items: [required]
-
item: [string — item reference — see above]
key: [character — the character in the shape for this item]
allowDamaged: (true/false | default: false)
amount: (number | default: 1)
-
# ... etc
# Start of a new SHAPELESS recipe
-
shaped: false
items: [required]
-
item: [string - item reference - see above]
allowDamaged: (true/false | default: false)
amount: (number | default: 1)
-
# ... etc
# Start of a new FURNACE recipe
-
type: "furnace" # this is REQUIRED
exp: (number | default: 0)
time: [number - number of ticks to smelt this item (1 second = 20 ticks)]
ingredient: [string - item reference - see above]
shape is the shape of the recipe, and is for SHAPED recipes only. Any character in the shape that doesn't exist in the items key.
This will create the diamond pickaxe recipe, and x is a blank slot because it does not exist in the items map:
shape:
- "aaa"
- "xbx"
- "xbx"
items:
-
item: "minecraft:DIAMOND"
key: 'a'
-
item: "minecraft:STICK"
key: 'b'
Additionally, you can set allowDamaged for each item to specify whether or not damaged items should be allowed in the recipe. By default, it's "false", meaning the recipe won't work unless the item has full durability
If you set permission to "magicStick", for example, the player will be required to have the permission customitems.recipe.magicStick to craft that recipe.
If you'd like to make it so that the permissions are NOT prefixed, set prefixPermissions to false. If prefixPermissions is false AND permission is set to "myPermission.magicStick", the player will be required to have the permission "myPermission.magicStick". If prefixPermissions is not set or true, they will need the permission "customitems.recipe.myPermission.magicStick"
For more info, see https://github.com/jojodmo/CustomItems/wiki/Example-Configurations
(texture)
This is used for automatic resource pack generation. For more info, check out Automatic Resource Pack Generation
texture:
type: [either "item" or "block"]
item:
id: [unique number greater than 1]
block: (optional)
id: [unique number between 1 and 160]
(armor)
#in myCustomItem.yml
armor:
category: (string)
strength: (number from 0 to 100 - recommended max is 25 | default: material default)
blastResistance: (number from 0 to 100 - recommended max is (25 - strength) | default: 0)
effects: (potion list - optional)
- # The first effect
potion: [potion type]
strength: (number | default: 1)
particles: (true/false | default: false)
ambient: (true/false | default: false)
showIcon: (true/false | default: false)
- # The second effect, optional
potion: [potion type] # The second potion type
# ...
strength is the protective strength of the armor, where 0 is nothing and 100 makes the player invincible. This adds for each piece of armor the player is wearing, so if the player wears a full set of armor with strength "25", they will be invincible.
blastResistance stacks with strength when the user is damaged by an explosion. So strength 25 and blastResistance 75 makes the user invincible to explosions
Explanation of strength & blastResistance
strength decreases the damage you take by that percentage, and it stacks for each item you have. So, strength of 20 decreases all damage you take by 20%
blastResistance stacks on top of strength to decrease the damage more
(attributes)
Attributes are a way that Minecraft adds buffs/debuffs to items. You can learn more about them on the Minecraft Wiki The attributes key should go under the "item" key.
Valid options for the attribute name are "armor", "armorToughness", "attackDamage", "attackKnockback", "attackSpeed", "flyingSpeed", "knockbackResistance", "luck", "maxHealth", and "speed". You can read more about them on the Minecraft Wiki
There are three ways to set attributes. If after you read one of them you would like to see an example, check out the Custom Item Reference Example below
If you're looking for a quick way to add attributes to an item, you can use this method to apply the given attribute to the item when it's in the player's main hand or off hand only. If you want it to apply while the player is wearing it, for example, use one of the other methods below
item:
attributes:
[attribute 1 name]: [decimal]
(attribute 2 name): [decimal]
# For example,
# attackDamage: 5.1
The simplest way is to set a selection of attributes for a specified slot, or multiple slots (the "selection of attributes" method):
item:
attributes:
[slot 1 name]: (string — options: "mainHand", "offHand", "feet", "legs", "chest", and "head" | default: "mainHand" and "offHand")
[attribute 1 name]: [decimal]
(attribute 2 name): [decimal]
# For example,
# attackDamage: 5.1
# ...
(slot 2 name):
[attribute 1 name]: [decimal]
# etc ...
By default, the number you provide will be added to that attribute. If you want to use a different operator, check out the other formats below.
Another way of doing it is to set an attribute for a selection of slots (the "selection of slots" method):
item:
attributes:
#Valid options for attribute name are "maxHealth", "speed", "attackDamage", "armor", "armorToughness", "attackSpeed", "luck"
[attribute name - string]:
name: (string | default: randomly generated)
amount: [decimal]
operator: (string - options "0", "1", and "2". See below for more info | default: "0", or "add")
slots: (string list — options: "mainHand", "offHand", "feet", "legs", "chest", and "head" | default: "mainHand" and "offHand")
uuidMost: (number | default: randomly generated)
uuidLeast: (number | default: randomly generated)
(attribute 2 name):
# ...
(attribute 3 name):
# ... etc
A more advanced way that is more powerful is to set an attribute for each slot (the "advanced" method):
item:
attributes:
[attribute name - string]:
[slot name — string]:
name: (string | default: randomly generated)
amount: [decimal]
operator: (string - options "0", "1", and "2". See below for more info | default: "0", or "add")
uuidMost: (number | default: randomly generated)
uuidLeast: (number | default: randomly generated)
(slot 2 name - string):
# ...
(slot 3 name — string):
# ...
(attribute 2 name):
[slot name — string]:
# ... etc
If you are struggling on getting it working your best bet is using the below example and going from there.
item:
attributes:
attackDamage:
slots:
- mainHand
- offHand
amount: 40
You can find more info about what each option does at these pages:
Operator Options: https://minecraft.gamepedia.com/Attribute#Operations Attribute Modifiers: http://minecraft.gamepedia.com/Attribute#Modifiers Item Attributes: http://minecraft.gamepedia.com/Player.dat_format#Attribute_Modifiers
If you would like to see each of these formats in action, check out the Custom Item Reference Example below.
(anvilRepairItems)
If this is a damageable and repairable item, use this to specify what this item can be combined with to repair it in an anvil. You must have repairable and damageable set to true for this to work.
Put each repairing item under anvilRepairItems, and then set repairAmount inside of that.
damageable: true
repairable: true
anvilRepairItems:
# combining with a diamond will repair the item by 10 durability points
"minecraft:DIAMOND":
repairAmount: 10
# combining with a diamond block will repair the item by 90 durability points
"minecraft:DIAMOND_BLOCK":
repairAmount: 90
# combining with the CustomItem "myCoolCustomItem" will repair the item by 25 durability points
"myCoolCustomItem":
repairAmount: 25
(block)
See https://github.com/jojodmo/CustomItems/wiki/Creating-a-Custom-Block
(handlers)
See https://github.com/jojodmo/CustomItems/wiki/Handlers-and-Actions
Custom Item Reference Example
KEEP IN MIND — This item won't actually load, because a lot of things in it don't make sense! This item is just to show you how to configure certain options if you're confused.
# in testCustomItem.yml
# So, the ID of the Custom Item is "testCustomItem"
# And you can get it by running /cui get testCustomItem
name: "My Custom Item"
category: "miscellaneous"
version: 1
forceUpdate: false
item:
material: "material:DIAMOND_PICKAXE"
dataValue: 77
textureID: 2
attributes:
# Using the "selection of attributes" format from (attributes) above
mainHand:
attackDamage: 5
armor: 2
armorToughness: 2
speed: 0.2
offHand:
attackDamage: 2
speed: 0.1
# Using the "selection of slots" format from (attributes) above
attackDamage:
slots:
- mainHand
- offHand
amount: 20
# Using the "advanced" format from (attributes) above
attackSpeed:
mainHand:
amount: 10
operator: "1"
offHand:
amount: 2
operator: "2"
displayName: "&eMy Custom Item"
lore:
- "Lore Line 1"
- "&cLore Line 2"
- "&dLore Line 3"
enchantments:
"minecraft:SILK_TOUCH": 1
"minecraft:DIG_SPEED": 4
color: "00AAFF"
headUsername: "jojodmo"
durability: 500
itemDamage: 100
damageable: true
glows: true
hideDurability: false
hideDurabilityBar: false
hideEnchantments: true
hideAttributes: false
hideFlags: false
armor:
strength: 10
blastResistance: 2
effects:
-
potion: "GLOWING"
-
potion: "INCREASE_DAMAGE"
strength: 2
particles: false
showIcon: true
block:
texture:
textureID: 3
doPhysics: true
exp: 10
doFortuneDrops: true
doSilkTouchDrops: true
drops:
"minecraft:DIAMOND": 10
"myCustomGemItemID": 2
generation:
-
method: "ore"
worlds:
- "world"
- "myOtherWorld"
biomes:
- "JUNGLE"
- "JUNGLE_EDGE"
- "JUNGLE_HILLS"
- "MODIFIED_JUNGLE"
- "MODIFIED_JUNGLE_EDGE"
continueChance: 0.4
generationChance: 0.3
amountPerChunk: 12
minY: 8
maxY: 32
-
method: "replace"
worlds:
- "world_the_nether"
blockTypes:
- "minecraft:NETHERRACK"
chance: 1.0
amountPerChunk: -1
minY: 0
maxY: 255
info:
description: "This is my Custom Item!"
usage: "This item is completely useless, and won't actually load!"
making: null
obtaining: "You need to craft this item!"
relatedItems:
- "minecraft:DIAMOND_PICKAXE"
- "myOtherCustomItemID"
recipes:
-
shaped: true
shape:
- "aaa"
- "xbx"
- "xbx"
items:
-
item: "material:EMERALD"
amount: 1
key: 'a'
-
item: "material:BLAZE_ROD"
amount: 2
key: 'b'
resultAmount: 1
prefixPermissions: true
permission: "myCustomItem"
noPermissionMessage: "You need the permission customitems.recipe.myCustomItem"
-
shaped: false
items:
-
item: "minecraft:DIAMOND_PICKAXE"
amount: 3
-
item: "minecraft:EMERALD"
amount: 4
-
type: "furnace"
exp: 10
time: 100 # 100 ticks = 5 seconds
ingredient: "minecraft:EMERALD_BLOCK"
canBeUsedGenerically: false
canBePlaced: false
consumable: false
shootable: false #DO NOT USE ON A BOW
enchantable: true
handlers: (see "Handlers and Actions" page)
rightClickBlock:
actions:
-
action: sendMessage
message: "You right clicked some type of block. You are in {player.location.world}, and you clicked a block at the location {location.x}, {location.y}, {location.z}"
leftClickBlock:
actions:
-
ifTypes:
- "minecraft:DIAMOND_BLOCK"
- "minecraft:GOLD_BLOCK"
ifHasPermission: "hitBroadcast"
ifStatementCombine: "OR"
action: consoleRunCommand
command: "say {player} Just hit a block! Either they have the permission customitems.action.hitBroadcast OR they hit a diamond/gold block"
-
ifSneaking: true
cooldown: 200
ifGamemode: "CREATIVE"
action: runActions
actions:
-
tickDelay: 10
action: runSkript
actionIDs:
- "skriptIdA"
- "skriptIdB"
-
probability: 0.2
runInterval: 2
action: givePlayerItem
type: "minecraft:DIAMOND"
amount: 4