diff --git a/pages/NodeMetaData.md b/pages/NodeMetaData.md index 6bb2cc1..0aed1a0 100644 --- a/pages/NodeMetaData.md +++ b/pages/NodeMetaData.md @@ -9,111 +9,85 @@ The traditional node storage in Minetest is usually limited to: [toc] ## `minetest.get_meta(pos)` - Obtains a mutable NodeMetaData reference for the node at `pos`. -### Arguments - +**Arguments:** - `pos` - Vector: Node position on the map; floats are rounded appropriately. -### Returns - +**Returns:** - `meta` - NodeMetaData: Corresponding NodeMetaData reference ## `minetest.find_nodes_with_meta(pos1, pos2)` - Searches a region for nodes with non-empty metadata. -### Arguments - -Cuboid corners are rounded properly if they are not integers. - +**Arguments:** - `pos1` - Vector: First corner of the cuboid region (inclusive) - `pos2` - Vector: Second corner of the cuboid region (inclusive) -### Returns +Cuboid corners are rounded properly if they are not integers. +**Returns:** - `positions` - List of Vector: List of integer positions of nodes that have non-empty meta ## Special Fields ### `formspec` - FormSpec to show when the node is interacted with using the "place/use" key (rightclick by default). Has no effect if `on_rightclick` is defined in the node definition (see `minetest.register_node`). -The most notable advantage of this over calling -`minetest.show_formspec` in `on_rightclick` is clientside prediction: +The most notable advantage of this over calling `minetest.show_formspec` in `on_rightclick` is clientside prediction: -The client can immediately show the FormSpec; the second approach requires the client to first inform -the server of the interaction, to which the server then responds with the FormSpec. -This takes one round-trip time (RTT). +The client can immediately show the FormSpec; the second approach requires the client to first inform the server of the interaction, to which the server then responds with the FormSpec. This takes one round-trip time (RTT). -The obvious disadvantage is that FormSpecs can't be dynamically generated in response to user interaction; -formspecs must be mostly static. To alleviate this, formspecs provide context-dependant placeholders -like the `context` or `current_player` inventory locations (see FormSpec). +The obvious disadvantage is that FormSpecs can't be dynamically generated in response to user interaction; formspecs must be mostly static. To alleviate this, formspecs provide context-dependant placeholders like the `context` or `current_player` inventory locations (see FormSpec). -IMPORTANT: The `context` inventory location can only be used in FormSpecs using the special `formspec` NodeMetaData field. -FormSpecs shown using `minetest.show_formspec` must use `nodemeta:,,` to reference inventories instead. +IMPORTANT: The `context` inventory location can only be used in FormSpecs using the special `formspec` NodeMetaData field. FormSpecs shown using `minetest.show_formspec` must use `nodemeta:,,` to reference inventories instead. -Another disadvantage is that plenty of redundant metadata - often a constant FormSpec - has to be stored with every node. -This metadata also has to be sent to clients. Minetest's mapblock compression should be able to compress duplicate substrings - -FormSpecs in this case - reasonably well though. +Another disadvantage is that plenty of redundant metadata - often a constant FormSpec - has to be stored with every node. This metadata also has to be sent to clients. Minetest's mapblock compression should be able to compress duplicate substrings - FormSpecs in this case - reasonably well though. In terms of network traffic it depends: With meta, the FormSpec is "only" sent when the mapblock gets updated; whereas the other approach resends the FormSpec every time the user interacts with the node. ### `infotext` - -Text to show when the node is pointed at (same as the `infotext` object property). - -Long texts are line-wrapped, even longer texts are truncated. +Text to show when the node is pointed at (same as the `infotext` object property). Long texts are line-wrapped, even longer texts are truncated. ## Methods ### `:mark_as_private(keys)` +NodeMetaData is by default fully sent to clients; the special `formspec` and `infotext` fields triggering clientside behavior obviously need to be sent to clients to work. -NodeMetaData is by default fully sent to clients; -the special `formspec` and `infotext` fields triggering clientside behavior -obviously need to be sent to clients to work. - -All other fields do not need to be sent to clients -unless you want to explicitly support local mapsaving. +All other fields do not need to be sent to clients unless you want to explicitly support local mapsaving. TIP: Mark all other fields as private to reduce traffic. -If you don't want clients to be able to see private NodeMetaData fields - -usually to prevent cheating - you must mark them as private. +If you don't want clients to be able to see private NodeMetaData fields - usually to prevent cheating - you must mark them as private. NOTE: The private marking is tied to a key-value pair. -If the key-value pair is deleted, the private marking is deleted as well. -If the key-value pair is recreated, the private marking must be recreated as well. +- If the key-value pair is deleted, the private marking is deleted as well. +- If the key-value pair is recreated, the private marking must be recreated as well. NOTE: `to_table` and `from_table` do not keep track of which fields were marked as private. -#### Arguments - +**Arguments:** - `keys` - `{type-string}` or list of `{type-string}`: Either: - A single key to mark as private, or - A list of keys to mark as private ### `:get_inventory()` +Get the inventory associated with the node. -#### Returns - +**Returns:** - `inv` - Inventory: The inventory associated with the node ### `:to_table()` - Extends MetaData `:to_table()` by additionally adding an `inventory` field for a table `{[listname] = list}` where `list` is a list of ItemStrings (`""` for empty) with the same length as the size of the inventory list. TIP: Use `table = assert(meta:to_table())` to error if the operation failed. -#### `:from_table(table)` - +### `:from_table(table)` Extends MetaData `:from_table(table)` to add support for the `inventory` field. ---