More comments and credits

mods/ITEMS/mcl_copper/README.md

@@ -1,6 +1,6 @@
 # VoxeLibre Copper
 
-### by NO11
+### by NO11 and JoseDouglas26
 
 Adds copper ore, blocks and items.
 

mods/ITEMS/mcl_copper/crafting.lua

@@ -1,28 +1,28 @@
 --- This function determines the format of the crafting recipe in the crafting grid based on the
 ---block name. Each block must have its own crafting format for the given material(s).
 ---Some materials in the recipe can be pre-defined (e.g. copper bulbs have fixed materials
---(blaze stick and redstone) and materials that vary according to the material parameter)
+--(blaze stick and redstone) and materials that vary according to the material parameter).
 ---@param name string
 ---@param material string
 ---@return table
 local function get_shape(name, material)
-	if name == "cut" then -- Shape of cut copper blocks
+	if name == "cut" then -- Shape of cut copper blocks.
 		return {
 			{material, material},
 			{material, material}
 		}
-	elseif name == "grate" then -- Shape of copper grates
+	elseif name == "grate" then -- Shape of copper grates.
 		return {
 			{"", material, ""},
 			{material, "", material},
 			{"", material, ""}
 		}
-	elseif name == "chiseled" then -- Shape of chiseled copper blocks
+	elseif name == "chiseled" then -- Shape of chiseled copper blocks.
 		return {
 			{material},
 			{material},
 		}
-	elseif name == "bulb_off" then -- Shape of copper bulbs (with fixed materials)
+	elseif name == "bulb_off" then -- Shape of copper bulbs (with fixed materials).
 		return {
 			{"", material, ""},
 			{material, "mcl_mobitems:blaze_rod", material},
@@ -45,7 +45,7 @@ end
 local function register_variants_recipes(name, material, amount)
 	local names
 	local materials = {}
-	-- Handling the inconsistency of the original itemstrings
+	-- Handling the inconsistency of the original itemstrings.
 	if name ~= "cut" then
 		names = {
 			name, "waxed_"..name,
@@ -61,7 +61,7 @@ local function register_variants_recipes(name, material, amount)
 			"block_oxidized_"..name, "waxed_block_oxidized_"..name
 		}
 	end
-	-- Checking the type of material
+	-- Checking the type of material.
 	if type(material) == "string" then
 		materials = {
 			"mcl_copper:"..material, "mcl_copper:waxed_"..material,
@@ -74,7 +74,7 @@ local function register_variants_recipes(name, material, amount)
 	end
 	--[[
 		Registering each recipe according to the materials
-		blocks made from copper and its oxidized and waxed variations)
+		blocks made from copper and its oxidized and waxed variations).
 	]]
 	for i = 1, 8 do
 		minetest.register_craft({
@@ -83,7 +83,7 @@ local function register_variants_recipes(name, material, amount)
 		})
 	end
 end
--- Using the function above to record the recipes for cut copper blocks, copper grates and copper bulbs
+-- Using the function above to record the recipes for cut copper blocks, copper grates and copper bulbs.
 register_variants_recipes("cut", "block", 4)
 register_variants_recipes("grate", "block", 4)
 register_variants_recipes("bulb_off", "block", 4)
@@ -132,7 +132,7 @@ for _, w in ipairs(waxable_blocks) do
 		},
 	})
 end
--- List of blocks that can be cutted on stonecutter
+-- List of blocks that can be cutted on stonecutter.
 local cuttable_blocks = {
 	"block",
 	"waxed_block",
@@ -150,7 +150,7 @@ for _, c in ipairs(cuttable_blocks) do
 	--mcl_stonecutter.register_recipe("mcl_copper:"..c, "mcl_copper:"..c:gsub("block", "chiseled"), 4)
 	--mcl_stonecutter.register_recipe("mcl_copper:"..c.."_cut", "mcl_copper:"..c:gsub("block", "chiseled"))
 end
--- Registering blocks and items specific recipes
+-- Registering blocks and items specific recipes.
 minetest.register_craft({
 	output = "mcl_copper:block_raw",
 	recipe = {

mods/ITEMS/mcl_copper/descriptions.lua

@@ -1,5 +1,4 @@
 local S = minetest.get_translator("mcl_copper")
-local lit_desc = "(Lit)"
 
 mcl_copper.copper_descs = {
     ["block"] = {

mods/ITEMS/mcl_copper/mod.conf

@@ -1,4 +1,4 @@
 name = mcl_copper
-author = NO11
+author = NO11, JoseDouglas26
 depends = mcl_core, mcl_sounds, mcl_stairs, mcl_util, mcl_oxidation, mcl_stonecutter
 description = Adds Copper Ore, blocks and items.

mods/ITEMS/mcl_copper/nodes.lua

@@ -1,5 +1,14 @@
 local S = minetest.get_translator("mcl_copper")
-
+--- Function to set drop (only useful for copper bulbs that are not available in the creative inventory).
+--- To have a special drop, the block definition must contain the "drop" parameter.
+--- "old_name" must be a string containing the name of the node that will receive the special drop
+--- (for example, the lit copper bulb that should drop the unlit copper bulb).
+--- "index_name" contains the name of the dropped block (in the case of the previous example, name must
+--- be bulb_off to define the drop as the unlit and unpowered bulb).
+---@param drop string|nil
+---@param old_name string
+---@param index_name string
+---@return string|nil
 local function set_drop(drop, old_name, index_name)
 	if drop and old_name and index_name then
 		drop = "mcl_copper:"..old_name:gsub(index_name, drop)
@@ -28,7 +37,13 @@ local function set_groups(name, groups)
 
 	return groups
 end
-
+--- Function to set the light level for copper bulbs. Calculated based on the index passed to the function.
+--- "light_source" must be a integer which is the maximum desired light level. "index" must be a integer
+--- as well. "index" is used to define the level of oxidation of the bulb, as the light level decreases
+--- as the degree of oxidation advances.
+---@param light_source integer
+---@param index integer
+---@return integer
 local function set_light_level(light_source, index)
 	local ceil, floor_5, floor_7 = math.ceil(index / 2), math.floor(index / 5), math.floor(index / 7)
 	if light_source then
@@ -37,7 +52,12 @@ local function set_light_level(light_source, index)
 
 	return light_source
 end
-
+--- Function used to set tiles for blocks. "tiles" must be a table with 4 values ​​as the waxed variants
+--- use the same textures as the unwaxed versions. "index" must be an integer that must be, at most,
+--- twice the number of textures in the table (8 as the maximum value).
+---@param tiles table
+---@param index integer
+---@return string|nil
 local function set_tiles(tiles, index)
 	if not tiles or not index then
 		return
@@ -45,10 +65,17 @@ local function set_tiles(tiles, index)
 
 	return tiles[math.ceil(index / 2)]
 end
-
+--- Function used to register all blocks on the oxidation chain, including the waxed variants for each
+--- block. It also registers some special blocks like doors, trapdoors, slabs and stairs. "name" should
+--- be a string containing the subname of the block. "definitions" must be a table that contains only
+--- particular definitions for each block, such as the light level for copper bulbs or the "allfaces"
+--- drawtype for copper grates. Some nodes contain a special definition to define the registration of
+--- some other blocks (copper slabs and ladders are based on cut copper blocks).
+---@param name string
+---@param definitions table
 local function register_copper_variants(name, definitions)
 	local names, oxidized_variant, stripped_variant, waxed_variant, tiles
-
+	-- Handling the inconsistency of the original itemstrings.
 	if name ~= "cut" then
 		names = {
 			name, "waxed_"..name,
@@ -64,7 +91,7 @@ local function register_copper_variants(name, definitions)
 			"block_oxidized_"..name, "waxed_block_oxidized_"..name
 		}
 	end
-
+	-- Also handling the inconsistency of the original texture names.
 	if name == "block" then
 		tiles = {
 			"mcl_copper_block.png",
@@ -80,20 +107,33 @@ local function register_copper_variants(name, definitions)
 			"mcl_copper_oxidized_"..name..".png"
 		}
 	end
-
+	-- Registering the 8 nodes in the oxidation chain.
 	for i = 1, #names do
+		--[[
+			Defining whether the block is waxed and defining its stripped variant (its non-oxidized
+			variant, which must precede the waxed variant in the name table).
+		]]
 		if names[i]:find("waxed") then
 			stripped_variant = "mcl_copper:"..names[i-1]
 		else
+			--[[
+				While the "oxidized" variant is not found, this snippet defines the oxidized variant of
+				the block.
+			]]
 			if not names[i]:find("oxidized") then
 				oxidized_variant = "mcl_copper:"..names[i+2]
 			end
+			--[[
+				Defining the stripped variant with the exception of the first block in the chain
+				(and the waxed ones that were defined before).
+			]]
 			if i ~= 1 then
 				stripped_variant = "mcl_copper:"..names[i-2]
 			end
+			-- Defining the waxed variant for unwaxed variants.
 			waxed_variant = "mcl_copper:"..names[i+1]
 		end
-
+		-- Registering the blocks.
 		minetest.register_node("mcl_copper:"..names[i], {
 			description = mcl_copper.copper_descs[name][i],
 			drawtype = definitions.drawtype or "normal",
@@ -114,7 +154,7 @@ local function register_copper_variants(name, definitions)
 			_mcl_stripped_variant = stripped_variant,
 			_mcl_waxed_variant = waxed_variant,
 		})
-
+		-- Defining blocks that use mcl_stairs.
 		if definitions._mcl_stairs then
 			local subname = mcl_copper.stairs_subnames[name][i]
 
@@ -130,12 +170,20 @@ local function register_copper_variants(name, definitions)
 				mcl_copper.stairs_descs[subname][3], nil, nil, nil, "woodlike"
 			)
 		end
-
+		-- Defining blocks that use mcl_doors.
 		if definitions._mcl_doors then
 			local itemimg, lowertext, uppertext, frontimg, sideimg
+			-- Defining the special groups for doors and trapdoors.
 			local door_groups = set_groups(names[i]:gsub(name, "door"), definitions.groups)
 			local trapdoor_groups = set_groups(names[i]:gsub(name, "trapdoor"), definitions.groups)
-
+			--[[
+				Managing the textures related to doors and trapdoors, as well as the texture of the item
+				for each door. As with the other blocks, the waxed variant uses the same textures as the
+				unwaxed variants.
+				itemimg -> item image for the doors on inventory;
+				lowertext / uppertext -> lower and bottom textures for the doors;
+				frontimg / sideimg -> front and side textures for the trapdoors;
+			]]
 			if i % 2 == 1 then
 				itemimg = "mcl_copper_item_"..names[i]:gsub(name, "door")..".png"
 				lowertext = "mcl_copper_"..names[i]:gsub(name, "door").."_lower.png"
@@ -149,7 +197,7 @@ local function register_copper_variants(name, definitions)
 				frontimg = "mcl_copper_"..names[i-1]:gsub(name, "trapdoor")..".png"
 				sideimg = "mcl_copper_"..names[i-1]:gsub(name, "trapdoor").."_side.png"
 			end
-
+			-- Registering doors.
 			mcl_doors:register_door("mcl_copper:"..names[i]:gsub(name, "door"), {
 				description = mcl_copper.doors_descs[i][1],
 				groups = door_groups,
@@ -163,7 +211,7 @@ local function register_copper_variants(name, definitions)
 				_mcl_blast_resistance = 3,
 				_mcl_hardness = 3
 			})
-
+			-- Registering trapdoors.
 			mcl_doors:register_trapdoor("mcl_copper:"..names[i]:gsub(name, "trapdoor"), {
 				description = mcl_copper.doors_descs[i][2],
 				groups = trapdoor_groups,
@@ -180,42 +228,21 @@ local function register_copper_variants(name, definitions)
 		end
 	end
 end
-
+-- Using the function above to register the copper blocks.
-minetest.register_node("mcl_copper:stone_with_copper", {
-	description = S("Copper Ore"),
-	_doc_items_longdesc = S("Some copper contained in stone, it is pretty common and can be found below sea level."),
-	tiles = {"default_stone.png^mcl_copper_ore.png"},
-	is_ground_content = true,
-	groups = {pickaxey = 3, building_block = 1, material_stone = 1, blast_furnace_smeltable=1},
-	drop = "mcl_copper:raw_copper",
-	sounds = mcl_sounds.node_sound_stone_defaults(),
-	_mcl_blast_resistance = 3,
-	_mcl_hardness = 3,
-	_mcl_silk_touch_drop = true,
-	_mcl_fortune_drop = mcl_core.fortune_drop_ore,
-})
-
-minetest.register_node("mcl_copper:block_raw", {
-	description = S("Block of Raw Copper"),
-	_doc_items_longdesc = S("A block used for compact raw copper storage."),
-	tiles = {"mcl_copper_block_raw.png"},
-	is_ground_content = false,
-	groups = {pickaxey = 2, building_block = 1, blast_furnace_smeltable = 1},
-	sounds = mcl_sounds.node_sound_metal_defaults(),
-	_mcl_blast_resistance = 6,
-	_mcl_hardness = 5,
-})
-
 register_copper_variants("block", {
 	groups = {pickaxey = 2, building_block = 1},
+	--[[
+		Copper blocks are no longer the manufacturing material for doors but this definition will be
+		maintained here to avoid individual registration of 16 blocks.
+	]]
 	_mcl_doors = true,
 })
-
+-- Using the function above to register the cut copper blocks.
 register_copper_variants("cut", {
 	groups = {pickaxey = 2, building_block = 1},
 	_mcl_stairs = true,
 })
-
+-- Using the function above to register the copper grates.
 register_copper_variants("grate", {
 	drawtype = "allfaces",
 	groups = {pickaxey = 2, building_block = 1, disable_suffocation = 1},
@@ -277,3 +304,28 @@ register_copper_variants("bulb_powered_on", {
 	paramtype = "light"
 })
 ]]
+-- Registering specific blocks.
+minetest.register_node("mcl_copper:stone_with_copper", {
+	description = S("Copper Ore"),
+	_doc_items_longdesc = S("Some copper contained in stone, it is pretty common and can be found below sea level."),
+	tiles = {"default_stone.png^mcl_copper_ore.png"},
+	is_ground_content = true,
+	groups = {pickaxey = 3, building_block = 1, material_stone = 1, blast_furnace_smeltable=1},
+	drop = "mcl_copper:raw_copper",
+	sounds = mcl_sounds.node_sound_stone_defaults(),
+	_mcl_blast_resistance = 3,
+	_mcl_hardness = 3,
+	_mcl_silk_touch_drop = true,
+	_mcl_fortune_drop = mcl_core.fortune_drop_ore,
+})
+
+minetest.register_node("mcl_copper:block_raw", {
+	description = S("Block of Raw Copper"),
+	_doc_items_longdesc = S("A block used for compact raw copper storage."),
+	tiles = {"mcl_copper_block_raw.png"},
+	is_ground_content = false,
+	groups = {pickaxey = 2, building_block = 1, blast_furnace_smeltable = 1},
+	sounds = mcl_sounds.node_sound_metal_defaults(),
+	_mcl_blast_resistance = 6,
+	_mcl_hardness = 5,
+})