Add documentation (README.md, API.md)
This commit is contained in:
parent
a66c35a9ea
commit
49b6d09985
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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."
|
||||
|
|
|
|||
Loading…
Reference in New Issue