^ The rotation of the node is stored in param2. Furnaces and chests are
rotated this way. Can be made by using minetest.dir_to_facedir().
+Nodes can also contain extra data. See "Node Metadata".
+
Representations of simple things
--------------------------------
Position/vector:
Groups in crafting recipes
---------------------------
-- Not implemented yet. (TODO)
-- Will probably look like this:
+An example:
{
output = 'food:meat_soup_raw',
recipe = {
{'group:water'},
{'group:bowl'},
},
- preserve = {'group:bowl'},
+ preserve = {'group:bowl'}, -- Not implemented yet (TODO)
}
Special groups
* If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be
automatically filled in based on the location of ''puncher''.
+Node Metadata
+-------------
+The instance of a node in the world normally only contains the three values
+mentioned in "Nodes". However, it is possible to insert extra data into a
+node. It is called "node metadata"; See "NodeMetaRef".
+
+Metadata contains two things:
+- A key-value store
+- An inventory
+
+Some of the values in the key-value store are handled specially:
+- formspec: Defines a right-click inventory menu. See "Formspec".
+- infotext: Text shown on the screen when the node is pointed at
+
+Example stuff:
+
+local meta = minetest.env:get_meta(pos)
+meta:set_string("formspec",
+ "invsize[8,9;]"..
+ "list[context;main;0,0;8,4;]"..
+ "list[current_player;main;0,5;8,4;]")
+meta:set_string("infotext", "Chest");
+local inv = meta:get_inventory()
+inv:set_size("main", 8*4)
+print(dump(meta:to_table()))
+meta:from_table({
+ inventory = {
+ main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", [5] = "", [6] = "", [7] = "", [8] = "", [9] = "", [10] = "", [11] = "", [12] = "", [13] = "", [14] = "default:cobble", [15] = "", [16] = "", [17] = "", [18] = "", [19] = "", [20] = "default:cobble", [21] = "", [22] = "", [23] = "", [24] = "", [25] = "", [26] = "", [27] = "", [28] = "", [29] = "", [30] = "", [31] = "", [32] = ""}
+ },
+ fields = {
+ formspec = "invsize[8,9;]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
+ infotext = "Chest"
+ }
+})
+
+Formspec
+--------
+Formspec defines a menu. Currently not much else than inventories are
+supported. It is a string, with a somewhat strange format.
+
+Spaces and newlines can be inserted between the blocks, as is used in the
+examples.
+
+Examples:
+- Chest:
+ invsize[8,9;]
+ list[context;main;0,0;8,4;]
+ list[current_player;main;0,5;8,4;]
+- Furnace:
+ invsize[8,9;]
+ list[context;fuel;2,3;1,1;]
+ list[context;src;2,1;1,1;]
+ list[context;dst;5,1;2,2;]
+ list[current_player;main;0,5;8,4;]
+- Minecraft-like player inventory
+ invsize[8,7.5;]
+ image[1,0.6;1,2;player.png]
+ list[current_player;main;0,3.5;8,4;]
+ list[current_player;craft;3,0;3,3;]
+ list[current_player;craftpreview;7,1;1,1;]
+
+Elements:
+
+invsize[<W>,<H>;]
+^ Define the size of the menu in inventory slots
+
+list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]
+^ Show an inventory list
+
+image[<X>,<Y>;<W>,<H>;<texture name>]
+^ Show an image
+^ Position and size units are inventory slots
+
+field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
+^ Textual field; will be sent to server when a button is clicked
+^ Position and size units are inventory slots
+^ Not implemented
+
+button[<X>,<Y>;<W>,<H>;<name>;<label>]
+^ Clickable button. When clicked, fields will be sent.
+^ Button will be visible as a field, with the value "active".
+^ Position and size units are inventory slots
+^ Not implemented
+
+Inventory location:
+- "context": Selected node metadata (deprecated: "current_name")
+- "current_player": Player to whom the menu is shown
+- "player:<name>": Any player
+- "nodemeta:<X>,<Y>,<Z>": Any node metadata
+
Helper functions
-----------------
dump2(obj, name="_", dumped={})
^ Called every server step, usually interval of 0.05s
minetest.register_on_placenode(func(pos, newnode, placer))
^ Called when a node has been placed
+^ Deprecated: Use on_construct or after_place_node in node definition instead
minetest.register_on_dignode(func(pos, oldnode, digger))
^ Called when a node has been dug. digger can be nil.
+^ Deprecated: Use on_destruct or after_dig_node in node definition instead
minetest.register_on_punchnode(func(pos, node, puncher))
^ Called when a node is punched
minetest.register_on_generated(func(minp, maxp, blockseed))
minetest.get_node_drops(nodename, toolname)
^ Returns list of item names.
^ Note: This will be removed or modified in a future version.
+minetest.get_craft_result(input) -> output, decremented_input
+^ input.method = 'normal' or 'cooking' or 'fuel'
+^ input.width = for example 3
+^ input.items = for example { stack 1, stack 2, stack 3, stack 4,
+ stack 5, stack 6, stack 7, stack 8, stack 9 }
+^ output.item = ItemStack, if unsuccessful: empty ItemStack
+^ output.time = number, if unsuccessful: 0
+^ decremented_input = like input
Defaults for the on_* item definition functions:
(These return the leftover itemstack)
^ Get rating of a group of an item. (0 = not in group)
minetest.get_node_group(name, group) -> rating
^ Deprecated: An alias for the former.
+minetest.serialize(table) -> string
+^ Convert a table containing tables, strings, numbers, booleans and nils
+ into string form readable by minetest.deserialize
+^ Example: serialize({foo='bar'}) -> 'return { ["foo"] = "bar" }'
+minetest.deserialize(string) -> table
+^ Convert a string returned by minetest.deserialize into a table
+^ String is loaded in an empty sandbox environment.
+^ Will load functions, but they cannot access the global environment.
+^ Example: deserialize('return { ["foo"] = "bar" }') -> {foo='bar'}
+^ Example: deserialize('print("foo")') -> nil (function call fails)
+ ^ error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)
Global objects:
minetest.env - EnvRef of the server environment and world.
methods:
- set_node(pos, node)
- add_node(pos, node): alias set_node(pos, node)
-- remove_node(pos): equivalent to set_node(pos, "air")
+ ^ Set node at position (node = {name="foo", param1=0, param2=0})
+- remove_node(pos)
+ ^ Equivalent to set_node(pos, "air")
- get_node(pos)
^ Returns {name="ignore", ...} for unloaded area
- get_node_or_nil(pos)
^ Returns nil for unloaded area
- get_node_light(pos, timeofday) -> 0...15 or nil
^ timeofday: nil = current time, 0 = night, 0.5 = day
+
+- place_node(pos, node)
+ ^ Place node with the same effects that a player would cause
+- dig_node(pos)
+ ^ Dig node with the same effects that a player would cause
+- punch_node(pos)
+ ^ Punch node with the same effects that a player would cause
+
- add_entity(pos, name): Spawn Lua-defined entity at position
^ Returns ObjectRef, or nil if failed
-- add_item(pos, itemstring): Spawn item
+- add_item(pos, item): Spawn item
^ Returns ObjectRef, or nil if failed
- get_meta(pos) -- Get a NodeMetaRef at that position
- get_player_by_name(name) -- Get an ObjectRef to a player
- add_rat(pos): Add C++ rat object (no-op)
- add_firefly(pos): Add C++ firefly object (no-op)
-NodeMetaRef (this stuff is subject to change in a future version)
+NodeMetaRef: Node metadata - reference extra data and functionality stored
+ in a node
+- Can be gotten via minetest.env:get_nodemeta(pos)
methods:
- set_string(name, value)
- get_string(name)
- set_float(name, value)
- get_float(name)
- get_inventory() -> InvRef
+- to_table() -> nil or {fields = {...}, inventory = {list1 = {}, ...}}
+- from_table(nil or {})
+ ^ See "Node Metadata"
ObjectRef: Moving things in the game are generally these
(basically reference to a C++ ServerActiveObject)
- get_entity_name() (DEPRECATED: Will be removed in a future version)
- get_luaentity()
Player-only: (no-op for other objects)
-- get_player_name(): will return nil if is not a player
+- is_player(): true for players, false for others
+- get_player_name(): returns "" if is not a player
- get_look_dir(): get camera direction as a unit vector
- get_look_pitch(): pitch in radians
- get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
InvRef: Reference to an inventory
methods:
+- is_empty(listname): return true if list is empty
- get_size(listname): get size of a list
- set_size(listname, size): set size of a list
- get_stack(listname, i): get a copy of stack index i in list
buildable_to = false,
drop = "",
-- alternatively drop = { max_items = ..., items = { ... } }
- metadata_name = "",
liquidtype = "none",
liquid_alternative_flowing = "",
liquid_alternative_source = "",
on_construct = func(pos),
^ Node constructor; always called after adding node
^ Can set up metadata and stuff like that
+ ^ default: nil
on_destruct = func(pos),
^ Node destructor; always called before removing node
+ ^ default: nil
+ after_destruct = func(pos, oldnode),
+ ^ Node destructor; always called after removing node
+ ^ default: nil
+
+ after_place_node = func(pos, placer),
+ ^ Called after constructing node when node was placed using
+ minetest.item_place_node / minetest.env:place_node
+ ^ default: nil
+ after_dig_node = func(pos, oldnode, oldmetadata, digger),
+ ^ oldmetadata is in table format
+ ^ Called after destructing node when node was dug using
+ minetest.node_dig / minetest.env:dig_node
+ ^ default: nil
+ can_dig = function(pos,player)
+ ^ returns true if node can be dug, or false if not
+ ^ default: nil
on_punch = func(pos, node, puncher),
^ default: minetest.node_punch
on_dig = func(pos, node, digger),
^ default: minetest.node_dig
^ By default: checks privileges, wears out tool and removes node
+
+ on_receive_fields = func(pos, formname, fields, sender),
+ ^ fields = {name1 = value1, name2 = value2, ...}
+ ^ Called when an UI form (eg. sign text input) returns data
+ ^ default: nil
+
+ on_metadata_inventory_move = func(pos, from_list, from_index,
+ to_list, to_index, count, player),
+ ^ Called when a player wants to move items inside the metadata
+ ^ Should move items, or some items, if permitted. If not, should do
+ nothing.
+ ^ The engine ensures the action is valid, i.e. the stack fits at the
+ given position
+ ^ default: minetest.node_metadata_inventory_move_allow_all
+
+ on_metadata_inventory_offer = func(pos, listname, index, stack, player),
+ ^ Called when a player wants to put something into the metadata
+ inventory
+ ^ Should check if the action is permitted (the engine ensures the
+ action is valid, i.e. the stack fits at the given position)
+ ^ If permitted, modify the metadata inventory and return the
+ "leftover" stack (normally nil).
+ ^ If not permitted, return itemstack.
+ ^ default: minetest.node_metadata_inventory_offer_allow_all
+
+ on_metadata_inventory_take = func(pos, listname, index, count, player),
+ ^ Called when a player wants to take something out of the metadata
+ inventory
+ ^ Should check if the action is permitted (the engine ensures the
+ action is valid, i.e. there's a stack of at least “count” items at
+ that position)
+ ^ If permitted, modify the metadata inventory and return the
+ stack of items
+ ^ If not permitted, return nil.
+ ^ default: minetest.node_metadata_inventory_take_allow_all
}
-Recipe: (register_craft)
+Recipe for register_craft: (shaped)
{
output = 'default:pick_stone',
recipe = {
{'default:cobble', 'default:cobble', 'default:cobble'},
{'', 'default:stick', ''},
- {'', 'default:stick', ''},
+ {'', 'default:stick', ''}, -- Also groups; eg. 'group:crumbly'
},
replacements = <optional list of item pairs,
replace one input item with another item on crafting>
}
-Recipe (shapeless):
+Recipe for register_craft (shapeless)
{
type = "shapeless",
output = 'mushrooms:mushroom_stew',
replace one input item with another item on crafting>
}
-Recipe (tool repair):
+Recipe for register_craft (tool repair)
{
type = "toolrepair",
additional_wear = -0.02,
}
-Recipe (cooking):
+Recipe for register_craft (cooking)
{
type = "cooking",
output = "default:glass",
cooktime = 3,
}
-Recipe (furnace fuel):
+Recipe for register_craft (furnace fuel)
{
type = "fuel",
recipe = "default:leaves",
projects / minetest.git / blobdiff