VoxeLibre/mods/ITEMS/mcl_armor/API.md

# mcl_armor

This mod implement the ability of creating armors.

Armors are basically items that a player can equip on four different slots on him (head, feet, torso and feet) to get advantages.

These armors have also a texture which is visible to other players, inside inventory or in 3rd person view.

## Creating an Armor Set

The `mcl_armor.register_set()` function aims to simplificate the process of creating a full set of armor.

This function register a four piece of armor (head, torso, leggings, feets) using a definition table:

```lua
mcl_armor.register_set({
	--name of the armor material (used for generating itemstrings)
	name = "dummy_armor",

	--description of the armor material
	--do NOT localize this string, it will be concatenated will each piece of armor's description and result will be automatically fetched from your mod's translation files
	description = "Dummy Armor",

	--overide description of each armor piece
	--do NOT localize this string
	descriptions = {
		head = "Cap",    --default: "Helmet"
		torso = "Tunic", --default: "Chestplate"
		legs = "Pants",  --default: "Leggings"
		feet = "Shoes",  --default: "Boots"
	},

	--this is used to calculate each armor piece durability with the minecraft algorithm
	--head durability = durability * 0.6857 + 1
	--torso durability = durability * 1.0 + 1
	--legs durability = durability * 0.9375 + 1
	--feet durability = durability * 0.8125 + 1
	durability = 80,

	--this is used then you need to specify the durability of each piece of armor
	--this field have the priority over the durability one
	--if the durability of some pieces of armor isn't specified in this field, the durability field will be used insteed
	durabilities = {
		head = 200,
		torso = 500,
		legs = 400,
		feet = 300,
	},

	--this define how good enchants you will get then enchanting one piece of the armor in an enchanting table
	--if set to zero or nil, the armor will not be enchantable
	enchantability = 15,

	--this define how much each piece of armor protect the player
	--these points will be shown in the HUD (chestplate bar above the health bar) 
	points = {
		head = 1,
		torso = 3,
		legs = 2,
		feet = 1,
	},

	--this attribute reduce strong damage even more
	--See https://minecraft.fandom.com/wiki/Armor#Armor_toughness for more explanations
	--default: 0
	toughness = 2,

	--this field is used to specify some items groups that will be added to each piece of armor
	--please note that some groups do NOT need to be added by hand, because they are already handeled by the register function:
	--(armor, combat_armor, armor_<element>, combat_armor_<element>, mcl_armor_points, mcl_armor_toughness, mcl_armor_uses, enchantability)
	groups = {op_armor = 1},

	--specify textures that will be overlayed on the entity wearing the armor
	--these fields have default values and its recommanded to keep the code clean by just using the default name for your textures
	textures = {
		head = "dummy_texture.png",  --default: "<modname>_helmet_<material>.png"
		torso = "dummy_texture.png", --default: "<modname>_chestplate_<material>.png"
		legs = "dummy_texture.png",  --default: "<modname>_leggings_<material>.png"
		feet = "dummy_texture.png",  --default: "<modname>_boots_<material>.png"
	},
	--you can also define these fields as functions, that will be called each time the API function mcl_armor.update(obj) is called (every time you equip/unequip some armor piece, take damage, and more)
	--note that the enchanting overlay will not appear unless you implement it in the function
	--this allow to make armors where the textures change whitout needing to register many other armors with different textures
	textures = {
		head = function(obj, itemstack)
			if mcl_enchanting.is_enchanted(itemstack) then
				return "dummy_texture.png^"..mcl_enchanting.overlay
			else
				return "dummy_texture.png"
			end
		end,
	},

	--WARNING: 2d preview will be deprecated soon
	--specify textures that will be shown in player inventory then you disabled the 3d player inventory preview
	--its similar to how works the textures field
	previews = {
		head = "dummy_texture.png",  --default: "<modname>_helmet_<material>_preview.png"
		torso = "dummy_texture.png", --default: "<modname>_chestplate_<material>_preview.png"
		legs = "dummy_texture.png",  --default: "<modname>_leggings_<material>_preview.png"
		feet = "dummy_texture.png",  --default: "<modname>_boots_<material>_preview.png"
	},

	--inventory textures aren't definable using a table similar to textures or previews
	--you are forced to use the default texture names which are:
	--head: "<modname>_inv_helmet_<material>.png
	--torso: "<modname>_inv_chestplate_<material>.png
	--legs: "<modname>_inv_leggings_<material>.png
	--feet: "<modname>_inv_boots_<material>.png

	--this callback table allow you to define functions that will be called each time an entity equip an armor piece or the mcl_armor.on_equip() function is called
	--the functions accept two arguments: obj and itemstack
	on_equip_callbacks = {
		head = function(obj, itemstack)
			--do stuff
		end,
	},

	--this callback table allow you to define functions that will be called each time an entity unequip an armor piece or the mcl_armor.on_unequip() function is called
	--the functions accept two arguments: obj and itemstack
	on_unequip_callbacks = {
		head = function(obj, itemstack)
			--do stuff
		end,
	},

	--this callback table allow you to define functions that will be called then an armor piece break
	--the functions accept one arguments: obj
	--the itemstack isn't sended due to how minetest handle items which have a zero durability
	on_break_callbacks = {
		head = function(obj)
			--do stuff
		end,
	},

	--this is used to generate automaticaly armor crafts based on each element type folowing the regular minecraft pattern
	--if set to nil no craft will be added
	craft_material = "mcl_mobitems:leather",

	--this is used to generate cooking crafts for each piece of armor
	--if set to nil no craft will be added 
	cook_material = "mcl_core:gold_nugget", --cooking any piece of this armor will output a gold nugged

	--this is used for allowing each piece of the armor to be repaired by using an anvil with repair_material as aditionnal material
	--it basicaly set the _repair_material item field of each piece of the armor
	--if set to nil no repair material will be added 
	repair_material = "mcl_core:iron_ingot",
})
```

## Creating an Armor Piece

If you don't want to register a full set of armor, then you will need to manually register your own single item.

```lua
minetest.register_tool("dummy_mod:random_armor", {
	description = S("Random Armor"),

	--these two item fields are used for ingame documentation
	--the mcl_armor.longdesc and mcl_armor.usage vars contains the basic usage and purpose of a piece of armor
	--these vars may not be enough for that you want to do, so you may add some extra informations like that:
	--_doc_items_longdesc = mcl_armor.longdesc.." "..S("Some extra informations.")
	_doc_items_longdesc = mcl_armor.longdesc,
	_doc_items_usagehelp = mcl_armor.usage,

	--this field is similar to any item definition in minetest
	--it just set the image shown then the armor is dropped as an item or inside an inventory
	inventory_image = "mcl_armor_inv_elytra.png",

	--this field is used by minetest internally and also by some helper functions
	--in order for the tool to be shown is the right creative inventory tab, the right groups should be added
	--mcl_armor_uses is required to give your armor a durability
	--in that case, tha armor can be worn by 10 points before breaking
	groups = {armor = 1, non_combat_armor = 1, armor_torso = 1, non_combat_torso = 1, mcl_armor_uses = 10},

	--this table is used by minetest for seraching item specific sounds
	--the _mcl_armor_equip and _mcl_armor_unequip are used by the armor implementation to play sounds on equip and unequip
	--note that you don't need to provide any file extention
	sounds = {
		_mcl_armor_equip = "mcl_armor_equip_leather",
		_mcl_armor_unequip = "mcl_armor_unequip_leather",
	},

	--these fields should be initialised like that in most cases
	--mcl_armor.equip_on_use is a function that try to equip the piece of armor you have in hand inside the right armor slot if the slot is empty 
	on_place = mcl_armor.equip_on_use,
	on_secondary_use = mcl_armor.equip_on_use,

	--this field define that the tool is ACTUALLY an armor piece and in which armor slot you can put it
	--it should be set to "head", "torso", "legs" or "feet"
	_mcl_armor_element = "torso",


	--this field is used to provide the texture that will be overlayed on the object (player or mob) skin
	--this field can be a texture name or a function that will be called each time the mcl_armor.update(obj) function is called
	--see the mcl_armor.register_set() documentation for more explanations
	_mcl_armor_texture = "mcl_armor_elytra.png"

	--callbacks
	--see the mcl_armor.register_set() documentation for more explanations

	_on_equip = function(obj, itemstack)
	end,
	_on_unequip = function(obj, itemstack)
	end,
	_on_break = function(obj)
	end,
})
```