BCMod

Custom item documentation

The custom item system exposes a large portion of minecraft's item system through nbt tags.
You can make custom items that can be used as pickaxes, shovels, axes (or multi-tools) or make a custom tool that is efficient at mining specific types of blocks, like leaves, obsidian, cobwebs or any other type of block in the game.
They can also be used to make custom weapons that can inflict poision, wither, slowness or any other status effect in the game (use the attackDamage attribute to change its base damage).
If you want custom armor they can do that too. You can configure what armor slot they can be equipped on, how much armor they provide and optionally how much protection they offer against specific damage types (like fire, explosion, void, drown, starve and many others).
Some mods add special armors that give you buffs while equipped, custom armor can do that too. They can also have some other useful abilities, like automatically extinguishing you when you're on fire, feeding you when you're hungry, curing you when you get debuffed or changing gravity's affect on you so you jump higher and fall slower.
Custom items can replicate the 'use' action of almost any item in the game (including blocks), so you could configure your custom item's use action to block like a sword, place a torch, hoe dirt, teleport like an ender pearl, shear sheep, or many other possiblities.
As well as replicating existing items they can also do a number of 'custom' things like mark/recall style teleporting (even across dimensions), giving yourself or a mob a status effect, mounting and controlling a mob (allowing you to ride spiders up walls), picking up and carrying a mob, dropping an item, breaking a block or giving yourself or a mob acceleration (allowing you to do things like lunge, backpedel, hover or fly)
Custom items can also be configured to do things while they are in your inventory, so you could make 'helium balloons' that decrease gravity while they are in your inventory (too many balloons would make you float upwards) or a ring that gives you invisibility while its on your hotbar.

To create a custom item open the BCMod recipe editor (CTRL+R while a BCMod interface is open), click the "Add custom item" tab in the filter panel, enter an id for the custom item and click the 'nbt' button. You can then use the nbt editor to configure the item. 
If you want to edit an existing custom item you can just double click it in the block selector list

The nbt editor features a nbt overview that allows you to easily navigate the nbt structure and has built in templates to easily add or modify enchantments, attributes and custom item tags


Here is an example of a custom item
{name:"Dirt Wand", renderAs:{id:"minecraft:redstone_torch", color:{b:255, g:125, r:0}}, tooltip:"A wand that can place 256 dirt blocks", durability:256, blockAction:{useItem:{id:"minecraft:dirt", durabilityCost:1}}}
This will make an item called 'Dirt Wand' that looks like a redstone torch colored blue, right-clicking with it will cost 1 durability and will place a dirt block


These are descriptions of the nbt tags used to configure custom items

name: "Unknown Item"
	the name of the item
renderAs: {id: "minecraft:item", damage: 0, tag: {}, color: 16777215, colorTag: %unset%, renderPasses: [0], enchanted: false}
	id, damage and tag define what item this should be rendered as (only id is required)
	color allows you to change the color of the item, if colorTag is present it should be like {r:255, g:255, b:255, a:255} and will be used instead of color
	renderPasses should be [0] for a solid item, [1] for a transparent item or [0, 1] for a semi transparent item, you can just use [0, 1] for everything
	enchanted controls whether or not the item is rendered with the enchanted glow
	There are also 4 true/false tags that control how the item gets rendered, these are disable_entity_rotation, disable_entity_bobbing, disable_block_3d, disable_inventory_block and disable_equipped_block
tooltip: ""
	\n will start a new line
	%% will be replaced with minecraft's formatting code, so %%9 makes the text blue. Formatting codes can be found at minecraft.gamepedia.com/Formatting_codes
	%damage% will be replaced with the items current damage
	%durability% will be replaced with the items total durability
	%durabilityLeft% will be replaced with how much durability the item has left (durability - damage)
	%durabilityPercent% will be replaced with the remaining durability as a percent of the default durability.
	Using the repairDurability action or a combineDurability recipe with 'exceedMaxDurability: true' allows %durabilityPercent% to go above 100%
durability: 0
	the default durability of the item, 0 means undamagable
stackLimit: 64
	the maximum number of items that can be stored in each stack
harvestLevel: {axe: -1, pickaxe: -1, shovel: -1 }
	if present these define what mining level of axe, pickaxe or shovel this item counts as
	0 = wood/gold, 1 = stone, 2 = iron, 3 = diamond, -1 = not that type of tool
miningSpeed: {all: 1.0, effective: 1.0}
	Defines how fast the item mines blocks
	Mining speed can be customized for individual block types like dirt by adding "minecraft.dirt:2" (replace : in the block id with .)
	{all: 1.0, minecraft.planks@0: 10.0} would mine oak planks 10 times faster than other blocks
canWear: {helmet: %unset%, chestplate: %unset%, leggings: %unset%, boots: %unset%}
	If present the value should be a tag of the form {armor: 0 -> 25} that defines how much armor it gives when equipped in that slot
	You can also add protection against specific types of damage, like helmet: {armor: 3, drown: 10} would reduce normal damage by 12% and drown damage by 40%
	The possible damage types are as follows (types marked with * are considered unblockable and will bypass normal armors and the armor tag)
		inFire, onFire*, lava, inWall*, drown*, starve*, cactus, fall*, outOfWorld*, generic*, magic*, wither*, anvil, fallingBlock, explosion,
		mob, player, thorns, explosion.player, arrow, thrown, indirectMagic* and fireball
armorDamageScale: {all: 1.0}
	Scales how much damage the item takes when it protects the player, this can include tags for any damage type
	A cloth armor might have armorDamageScale: {all: 1.0, inFire: 10, onFire: 10, lava: 10, magic: 0, fall: 0, cactus: 0.5}
armorEffects: {}
	these are the actions that should happen while the item is equipped as armor
attackMob: {}
	these are the actions that should happen when the item is used to attack a mob
mobAction: {}
	these are the actions that should happen when the item is 'used' on a mob
breakBlock: {}
	these are the actions that should happen when the item is used to break a block
blockAction: {}
	these are the actions that should happen when the item is 'used' on a block
useAction: {}
	these are the actions that should happen when the item is 'used'


An action tag consists of a compound tag containing one or more actions
These are actions that can be triggered from any event.

damageDurability: {amount: 1}
	Damages the item
repairDurability: {amount: 1, exceedMaxDurability: false}
	Repairs the item, if exceedMaxDurability is true it will be able to repair beyond 0 damage
accelerate: {x: 0, y: 0, z: 0, fallDistance: 0, targetRiddenMob: false, fullyDirectional: false, invertDirectionalY: false}
	Moves the player or target mob
	x == forward, y == up, fallDistance == how many blocks the player's fallen (more than 3 blocks will damage the player)
	to prevent fall damage fallDistance should be around -10 * y
	fullyDirectional will cause x to accelerate towards the camera (so it could travel staight up or straight down)
	invertDirectionalY will only apply with fullyDirectional, this causes you to accelerate up when looking straight down instead of accelerating down
	if the player/mob is riding another mob this will not have any effect unless targetRiddenMob is true
	xLimit, yLimit and zLimit prevent x, y or z from being accelerated beyond their limits, so accelerate: {y:4, yLimit:0.4} will never increase the acceleration
	by more than 0.4, {y:4, yLimit:-0.4} will only have an effect if y was decreased below -0.4
	These limits act on the overall acceleration change, rather than the players current speed, allowing yLimit to not be affected by the player jumping
	If no limit is provided it will default to x, y or z 
hurt: {amount: 1, min: -1, damageType: "generic", durabilityCost: 0}
	Damages the player or target mob. If their health is already less than or equal to min this will not do anything
	damageType can't be mob, arrow, thrown, indirectMagic or fireball as those would require additional infomation
	damageType for players also can't be player, player.explosion or thorns as those require another player
heal: {amount: 1, max: 20, durabilityCost: 0}
	Heals the player or mob up to 'max' health.
feed: {amount: 1, max: 20, durabilityCost: 0}
	Feeds the player.
ignite: {duration: 20, durabilityCost: 0}
	Sets the player or mob on fire for duration ticks (rounded to nearest second)
extinguish: {durabilityCost: 0}
	If the player or mob is on fire it puts them out.
cure: {id: 0, durabilityCost: 0}
	Removes a status effect (see http://minecraft.gamepedia.com/Status_effect for ids)
inflict: {id: 0, level: 1, duration: 20, durabilityCost: 0, combine: false}
	Gives the player or mob a status effect
	If the player already has that effect it won't do anything unless combine is true
dropItem: {id: "minecraft:dirt", damage: 0, count: 1, tag:{}, motionless: false, durabilityCost: 0, chance: 1.0}
	Drops an item, with or without random motion
	If chance is provided the item will only drop if a random number generated between 0 and 1 is less than chance
mark: {durabilityCost: 0}
	Remembers the player's current position and direction
recall: {durabilityCost: 0}
	Teleports the player or mob to the last marked location
	If your item has markOnCreation: true in its nbt data ({name:"Recall", markOnCreation:true, ...}) the item will remember the players position when it was created 
change: {id:%currentvalue%, damage:%currentvalue%, count:%currentvalue%, tag:%currenttag%}
	Changes the id, damage, count and/or nbt data of this item
controlMob: {mobTypes: %unset%, duration: -1}
	lets you control the mob you're riding
	controlled mobs will follow your directions but creepers will still explode and the wither's side heads will shoot you
	you can make this only target specific types of mobs by using mobTypes:{Spider:true, Creeper:false}
	if duration is set to a positive number the command will only last that many ticks
if: {damageEquals:0, then:{}, else:{}}
	checks each conditional in the tag and if they are all true runs the actions in 'then', otherwise runs the actions in 'else'
	possible conditionals are
	damageEquals:0 or [0, 1, 3], damageAbove:0, damageBelow:3
	healthEquals:10 or [10, 11, 12], healthAbove:5, healthBelow:7 (health is measured in half hearts and gets rounded down to nearest half heart)
	inWater:1, inLava:1, onGround:1, inAir:1
	nameEquals:"player name" or ["player name", "ridden mob name"]
	targetRidden:1 - if this is true the above conditionals will target the ridden mob instead of the player
	mob actions can have
		mobHealthEquals:0 or [0, 1], mobHealthAbove:0, mobHealthBelow:0
		mobType:"Spider" or ["Spider", "Creeper"] mob names can be found on minecraft.gamepedia.com/Data_values/Entity_IDs as 'Savegame ID's
		mobNameEquals:"named mob" or ["named mob", "Spider"]
		mobInWater:1, mobInLava:1, mobOnGround:1, mobInAir:1
	block actions can have
		blockId:"minecraft:dirt" or ["minecraft:dirt", "minecraft:stone"]
		blockAction can also have blockMetadata:0/[0]
ifAny: {damageEquals:0, then:{}, else:{}}
	like if, but will run 'then' if any of the conditionals are true
	
any action can have an 'and:{}' tag which will run the action again on the and tag, so cure:{id: 19, and: {id: 20}} will cure poison and wither
these 'and tags' can be nested, so inflict:{id:1, and:{id:3, and:{id:5}}} will inflict speed, haste and strength
durabilityCost tags will only be applied when the action was successful


blockAction can also include
useItem: {id: "minecraft:dirt", damage: 0, count: 1, tag: {}, durabilityCost: 0}
	calls another item's blockAction
	This can be used to place blocks
break: {dropItems: false, creative: false}
	breaks the block, if creative is true it will be able to break bedrock

	
attackMob and mobAction can also include
mount: {controlMob: %unset%}
	jumps on a mob, uncontrolled hostile mobs can attack you while you're riding them
	if controlMob is provided it should be a controlMob action tag 
carry: {}
	picks up a mob or puts down the mob you're carrying. you can also put them down with the useAction 'dropMob'
useItem: {id: "minecraft:dirt", damage: 0, count: 1, tag: {}, durabilityCost: 0}
	vanilla items just use attackMob to damage their durability
	vanilla items that will actually do something with mobAction are nametags, saddles, dyes and shears
	
You can use recall on other mobs, but it will only change its dimension if riskCreatingPortal is true 
(sending mobs to/from the nether may create a nether portal around x=0, z=0, but sending players will not cause that problem)

Actions that would normally target the player will instead target the mob, but you can add 'targetSelf: true' to any action tags that you want to target the player
You can target both the player and the mob by using the and tag, so {heal: {amount: 1, and: {amount: 1, targetSelf: true}} will heal both the mob and the player


useAction can also include
useItem: {id: "", damage: 0, count: 1, tag:{}, durabilityCost: 0}
	calls the useAction of another item
dropMob: {}
	drops the mob the player is carrying
duration: 0
	how long the item can be used for, or how long it takes to use the item
	this must be greater than 0 for 'onFinished:true' or 'frequency:X' actions to be triggered
bypassBlocks: false
	if this is present useAction will trigger before blockAction and before the block gets used (like for chests or furnaces)
	if this is true neither blockAction nor the blocks use will get triggered
type: "none"
	what type of action this is, this affects the animation and "block" will reduce incoming damage
	valid values are "eat", "drink", "block", "bow" or "none"
	if useItem is set this will default to that item's use type

Any action in useAction can have 2 extra tags that determine when it gets called
if an action has a 'frequency: X' tag it will be triggered every X ticks while the item is being used
if an action has 'onFinished: true' it will be triggered after the item has been used for 'duration' ticks
if an action has 'onFinished: false' or has neither frequency nor onFinished tags it will be triggered when the item starts being used
These tags also apply to 'and' subtags, so you can trigger the same action at multiple stages of use


Actions in passiveEffect and armorEffect will be triggered every 20 ticks while the item is in your inventory or worn as armor, but you can change the frequency with 'frequency:X'.
Passive effects can be restricted to only trigger when the item in on the hotbar with 'onHotbar:1' or only while held with 'whileHeld:1'
Because players could have multiple copies of an item you may want to limit the number of times the effect will be applied, you can do that with 'maxTriggers:X' (only the first X items with this id will be triggered)