mirror of
https://github.com/rollerozxa/voxelmanip-wiki
synced 2024-05-05 08:01:02 -07:00
94 lines
4.7 KiB
Markdown
94 lines
4.7 KiB
Markdown
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:**
|
|
- `pos1` - Vector: First corner of the cuboid region (inclusive)
|
|
- `pos2` - Vector: Second corner of the cuboid region (inclusive)
|
|
|
|
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 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:<X>,<Y>,<Z>` 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()`
|
|
Get the inventory associated with the node.
|
|
|
|
**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* |