Minetest/VoxeLibre
2
0
Fork 0
mirror of https://git.minetest.land/VoxeLibre/VoxeLibre.git synced 2024-11-25 12:01:06 +01:00
Code Issues Projects Releases Packages Wiki Activity

Add documentation (README.md, API.md)

Browse source
This commit is contained in:
Mikita Wiśniewski 2024-06-24 12:42:03 +07:00 committed by the-real-herowl
parent a66c35a9ea
commit 49b6d09985
4 changed files with 239 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

209
mods/ITEMS/mcl_chests/API.md Normal file
View file

@ -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.

19
mods/ITEMS/mcl_chests/README.md Normal file
View file

@ -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

15
mods/ITEMS/mcl_chests/chests.lua
View file

@ -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,

5
mods/ITEMS/mcl_chests/example.lua
View file

@ -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."