Add documentation (README.md, API.md)

mods/ITEMS/mcl_chests/API.md

@@ -0,0 +1,209 @@
+# `mcl_chests` API
+
+## `mcl_chests.register_chest(basename, definition)`
+
+This function allows for simple chest registration, used by both regular and
+trapped chests.
+
+* `basename` is a string that will be concatenated to form full nodenames for
+  chests, for example `"mcl_chests:basename_small"`.
+* `definition` is a key-value table, with following fields:
+
+```lua
+{
+    desc = S("Stone Chest"),
+    -- Equivalent to `description` field of Item/Node definition.
+    -- Will be shown as chest's name in the inventory.
+
+    title = {
+        small = S("Stone Chest") -- the same as `desc` if not specified
+        double = S("Large Stone Chest") -- defaults to `"Large " .. desc`
+    }
+    -- These will be shown when opening the chest (in formspecs).
+    
+    longdesc = S(
+        "Stone Chests are containers which provide 27 inventory slots. Stone Chests can be turned into" ..
+        "large stone chests with double the capacity by placing two stone chests next to each other."
+    ),
+    usagehelp = S("To access its inventory, rightclick it. When broken, the items will drop out."),
+    tt_help = S("27 inventory slots") .. "\n" .. S("Can be combined to a large stone chest"),
+    -- Equivalent to `_doc_items_longdesc`, `_doc_items_usagehelp` and
+    -- `_tt_help` fields of Item/Node definition. Shown in the tooltip and wiki.
+
+    tiles = { 
+        small = { "vl_stone_chests_small.png" },
+        double = { "vl_stone_chests_double.png" },
+        inv = {
+            "vl_stone_chests_top.png",
+            "vl_stone_chests_bottom.png",
+            "vl_stone_chests_right.png",
+            "vl_stone_chests_left.png",
+            "vl_stone_chests_back.png",
+            "vl_stone_chests_front.png"
+        },
+    },
+    -- `small` and `double` fields contain the textures that will be applied to
+    -- chest entities.
+    -- `inv` field contains table of textures (6 in total, for each cube side),
+    -- that will be used to render the chest "node" in the inventory.
+
+    groups = {
+        pickaxey = 1,
+        stone = 1,
+        material_stone = 1,
+    },
+    -- Equivalent to `groups` field of Item/Node definition. There is some table
+    -- merging occuring internally, but it is purely for entity rendering.
+
+    sounds = { 
+        mcl_sounds.node_sound_stone_defaults(), -- defaults to `nil`
+        "vl_stone_chests_sound" -- defaults to `"default_chest"`
+    },
+    -- First value is equivalent to `sounds` field of Item/Node definition.
+    -- Second value is a sound prefix, from which the actual sounds will be
+    -- concatenated (e.g. `vl_stone_chests_sound_open.ogg`). See `api.lua`.
+
+    hardness = 4.0,
+    -- Equivalent to `_mcl_blast_resistance` and `_mcl_hardness` fields of
+    -- Item/Node definition. They are always equal for chests.
+
+    hidden = false,
+    -- Equivalent to `_doc_items_hidden` field of Item/Node definition.
+
+    mesecons = { 
+        receptor = { 
+            state = mesecon.state.on,
+            rules = mesecon.rules.pplate,
+        },
+    },
+    -- Equivalent to `mesecons` field of Item/Node definition.
+
+    on_rightclick = function(pos, node, clicker)
+        mcl_util.deal_damage(clicker, 2)
+    end,
+    -- If provided, will be executed at the end of the actual `on_rightclick`
+    -- function of the chest node.
+    -- If `on_rightclick_left` or `on_rightclick_right` are not provided, this
+    -- will also be what is executed for left and right double chest nodes,
+    -- respectively.
+
+    drop = "chest",
+    -- If provided, the chest will not drop itself, but the item of the chest
+    -- with that basename.
+
+    canonical_basename = "chest",
+    -- If provided, the chest will turn into chest with that basename in
+    -- `on_construct`.
+}
+```
+
+For usage examples, see `chests.lua` and `example.lua`.
+
+
+## `mcl_chests.create_entity(pos, node_name, textures, param2, double, sound_prefix, mesh_prefix, animation_type, dir, entity_pos)`
+
+This function creates a chest entity based on parameters:
+
+* `pos` is the position vector.
+* `node_name` is a string used in initialization data for the entity.
+* `textures` is the entity textures.
+* `param2` is a node param2, which then will be converted to entity direction.
+* `double` is a boolean value for whether the chest is double or not.
+* `sound_prefix` is a string, from which the actual sounds for the entity will
+  be concatenated.
+* `mesh_prefix` is the same thing as `sound_prefix`, but for meshes.
+* `animation_type` is a string that will be used in `set_animation` method of
+  chest entity.
+* `dir` and `entity_pos` are number and vector values used to get entity info.
+
+Returned value is either a luaentity, or `nil` if failed (in which case a
+warning message gets written into the console).
+
+
+## `find_or_create_entity(pos, node_name, textures, param2, double, sound_prefix, mesh_prefix, animation_type, dir, entity_pos)`
+
+This function finds an existing entity, or creates one if failed. Parameters:
+
+* `pos` is the position vector.
+* `node_name` is a string used in initialization data for the entity.
+* `textures` is the entity textures.
+* `param2` is a node param2, which then will be converted to entity direction.
+* `double` is a boolean value for whether the chest is double or not.
+* `sound_prefix` is a string, from which the actual sounds for the entity will
+  be concatenated.
+* `mesh_prefix` is the same thing as `sound_prefix`, but for meshes.
+* `animation_type` is a string that will be used in `set_animation` method of
+  chest entity.
+* `dir` and `entity_pos` are number and vector values used to get entity info.
+
+Returned value is either a luaentity, or `nil` if failed (in which case a
+warning message gets written into the console).
+
+
+## `mcl_chests.no_rotate`
+
+This function is equivalent to `screwdriver.disallow` and is used when a chest
+can't be rotated, and is applied in `on_rotate` field of Node definition.
+
+
+## `mcl_chests.simple_rotate(pos, node, user, mode, new_param2)`
+
+This function allows for simple rotation with the entity being affected as well,
+and is applied in `on_rotate` field of Node definition.
+
+
+## `mcl_chests.open_chests`
+
+This table contains all currently open chests, indexed by player name.
+
+`nil` if player is not using a chest, and `{ pos = <chest node position> }`
+otherwise (where position is a vector value).
+
+
+## `mcl_chests.protection_check_move(pos, from_list, from_index, to_list, to_index, count, player)`
+
+This function is called in `allow_metadata_inventory_move` field of Node
+definition.
+
+## `mcl_chests.protection_check_put_take(pos, listname, index, stack, player)`
+
+This function is called in `allow_metadata_inventory_put` and
+`allow_metadata_inventory_take` fields of Node definition.
+
+
+## `mcl_chests.player_chest_open(player, pos, node_name, textures, param2, double, sound, mesh, shulker)`
+
+This function opens a chest based on parameters:
+
+* `player` is an ObjectRef.
+* `pos` is the position vector.
+* `node_name` is a string used in initialization data for the entity.
+* `textures` is the entity textures.
+* `param2` is a node param2, which then will be converted to entity direction.
+* `double` is a boolean value for whether the chest is double or not.
+* `sound` is a prefix string, from which the actual sounds for the entity will
+  be concatenated.
+* `mesh` is the same thing as `sound`, but for meshes.
+* `shulker` is a boolean value for whether the chest is a shulker or not.
+
+
+## `mcl_chests.player_chest_close(player)`
+
+This function has to be called when a player closes a chest.
+
+* `player` is an ObjectRef.
+
+
+## `mcl_chests.chest_update_after_close(pos)`
+
+This function is called when a chest is closed by `player_chest_close`.
+
+* `pos` is the chest's position vector.
+
+
+## `mcl_chests.is_not_shulker_box(stack)`
+
+This function checks for whether `stack` is a shulker box, and returns `false`
+if it is. Used internally to disallow putting shulker boxes into shulker boxes.
+
+* `stack` is an ItemStack.

mods/ITEMS/mcl_chests/README.md

@@ -0,0 +1,19 @@
+# `mcl_chests`
+
+This mod adds normal and large chests, trapped chests, ender chests and
+shulkers, providing an API for mods to register their own chests.
+
+The API is documented in `API.md`.
+
+
+## License of source code
+
+Copyright (C) 2011-2012 celeron55, Perttu Ahola <celeron55@gmail.com>\
+Copyright (C) 2024 rudzik8, Mikita Wiśniewski <rudzik8@protonmail.com>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation; either version 2.1 of the License, or
+(at your option) any later version.
+
+http://www.gnu.org/licenses/lgpl-2.1.html

mods/ITEMS/mcl_chests/chests.lua

@@ -2,7 +2,6 @@ local S = minetest.get_translator(minetest.get_current_modname())
 local F = minetest.formspec_escape
 local C = minetest.colorize
 local get_double_container_neighbor_pos = mcl_util.get_double_container_neighbor_pos
-local trapped_chest_mesecons_rules = mesecon.rules.pplate
 
 local chestusage = S("To access its inventory, rightclick it. When broken, the items will drop out.")
 
@@ -65,7 +64,7 @@ mcl_chests.register_chest("trapped_chest", {
 	mesecons = {
 		receptor = {
 			state = mesecon.state.off,
-			rules = trapped_chest_mesecons_rules,
+			rules = mesecon.rules.pplate,
 		},
 	},
 	on_rightclick = function(pos, node, clicker)
@@ -73,7 +72,7 @@ mcl_chests.register_chest("trapped_chest", {
 		mcl_chests.find_or_create_entity(pos, "mcl_chests:trapped_chest_on_small", { "mcl_chests_trapped.png" },
 			node.param2, false, "default_chest", "mcl_chests_chest", "chest")
 			:reinitialize("mcl_chests:trapped_chest_on_small")
-		mesecon.receptor_on(pos, trapped_chest_mesecons_rules)
+		mesecon.receptor_on(pos, mesecon.rules.pplate)
 	end,
 	on_rightclick_left = function(pos, node, clicker)
 		local meta = minetest.get_meta(pos)
@@ -83,23 +82,23 @@ mcl_chests.register_chest("trapped_chest", {
 		mcl_chests.find_or_create_entity(pos, "mcl_chests:trapped_chest_on_left",
 			mcl_chests.tiles.chest_trapped_double, node.param2, true, "default_chest", "mcl_chests_chest",
 			"chest"):reinitialize("mcl_chests:trapped_chest_on_left")
-		mesecon.receptor_on(pos, trapped_chest_mesecons_rules)
+		mesecon.receptor_on(pos, mesecon.rules.pplate)
 
 		local pos_other = get_double_container_neighbor_pos(pos, node.param2, "left")
 		minetest.swap_node(pos_other, { name = "mcl_chests:trapped_chest_on_right", param2 = node.param2 })
-		mesecon.receptor_on(pos_other, trapped_chest_mesecons_rules)
+		mesecon.receptor_on(pos_other, mesecon.rules.pplate)
 	end,
 	on_rightclick_right = function(pos, node, clicker)
 		local pos_other = get_double_container_neighbor_pos(pos, node.param2, "right")
 
 		minetest.swap_node(pos, { name = "mcl_chests:trapped_chest_on_right", param2 = node.param2 })
-		mesecon.receptor_on(pos, trapped_chest_mesecons_rules)
+		mesecon.receptor_on(pos, mesecon.rules.pplate)
 
 		minetest.swap_node(pos_other, { name = "mcl_chests:trapped_chest_on_left", param2 = node.param2 })
 		mcl_chests.find_or_create_entity(pos_other, "mcl_chests:trapped_chest_on_left",
 			mcl_chests.tiles.chest_trapped_double, node.param2, true, "default_chest", "mcl_chests_chest",
 			"chest"):reinitialize("mcl_chests:trapped_chest_on_left")
-		mesecon.receptor_on(pos_other, trapped_chest_mesecons_rules)
+		mesecon.receptor_on(pos_other, mesecon.rules.pplate)
 	end
 })
 
@@ -126,7 +125,7 @@ mcl_chests.register_chest("trapped_chest_on", {
 	mesecons = {
 		receptor = {
 			state = mesecon.state.on,
-			rules = trapped_chest_mesecons_rules,
+			rules = mesecon.rules.pplate,
 		},
 	},
 	on_rightclick = nil,

mods/ITEMS/mcl_chests/example.lua

@@ -6,7 +6,10 @@ local trapped_chest_mesecons_rules = mesecon.rules.pplate
 
 mcl_chests.register_chest("stone_chest", {
 	desc = S("Stone Chest"),
-	large_desc = S("Large Stone Chest"),
+	title = {
+		small = S("Stone Chest"),
+		double = S("Large Stone Chest")
+	},
 	longdesc = S(
 		"Stone Chests are containers which provide 27 inventory slots. Stone Chests can be turned into" ..
 		"large stone chests with double the capacity by placing two stone chests next to each other."