From 474e848fa223d08347cf932ca46e3be902b880cf Mon Sep 17 00:00:00 2001 From: ROllerozxa Date: Sat, 22 Jul 2023 15:29:36 +0000 Subject: [PATCH] NodeMetaData: Import from minetest_docs --- pages/NodeMetaData.md | 120 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 pages/NodeMetaData.md diff --git a/pages/NodeMetaData.md b/pages/NodeMetaData.md new file mode 100644 index 0000000..6bb2cc1 --- /dev/null +++ b/pages/NodeMetaData.md @@ -0,0 +1,120 @@ +NodeMetaData allows extending the basic node storage with a per-world, per-in-world-node persistent string key-value store implementing all methods of MetaData allowing you to associate arbitrary data with any node. Additionally, node metadata allows storing inventories for nodes like chests or furnaces. + +The traditional node storage in Minetest is usually limited to: + +* A content ID (determining the node name), +* The `param1` unsigned byte (`0` - `255` both inclusive) which is usually reserved for lighting, +* The `param2` unsigned byte (`0` - `255` both inclusive) which can be used depending on `paramtype2` + +[toc] + +## `minetest.get_meta(pos)` + +Obtains a mutable NodeMetaData reference for the node at `pos`. + +### Arguments + +- `pos` - Vector: Node position on the map; floats are rounded appropriately. + +### 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. + +- `pos1` - Vector: First corner of the cuboid region (inclusive) +- `pos2` - Vector: Second corner of the cuboid region (inclusive) + +### 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 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). + +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. + +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. + +## 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. + +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. + +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. + +NOTE: `to_table` and `from_table` do not keep track of which fields were marked as private. + +#### 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()` + +#### 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)` + +Extends MetaData `:from_table(table)` to add support for the `inventory` field. + +--- +*This article is originally based on an article from the minetest_docs project: [NodeMetaData.adoc](https://github.com/minetest/minetest_docs/blob/master/doc/classes/NodeMetaData.adoc) by Lars Müller, licensed under CC-BY 4.0* \ No newline at end of file