From fe972dacb2afc81b5fbdaeb91eea600fb6988017 Mon Sep 17 00:00:00 2001
From: rubenwardy <rubenwardy@gmail.com>
Date: Fri, 25 Sep 2015 17:38:44 +0100
Subject: [PATCH] Node Metadata: Created

---
 _data/links.yml           |  16 ++++--
 chapters/formspecs.md     |   4 +-
 chapters/node_metadata.md | 113 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 124 insertions(+), 9 deletions(-)
 create mode 100644 chapters/node_metadata.md

diff --git a/_data/links.yml b/_data/links.yml
index 7ba21d5..429c5dd 100644
--- a/_data/links.yml
+++ b/_data/links.yml
@@ -25,32 +25,36 @@
   num:   5
   link:  chapters/node_drawtypes.html
 
-- title: Active Block Modifiers
+- title: Node Metadata
   num:   6
+  link:  chapters/node_metadata.html
+
+- title: Active Block Modifiers
+  num:   7
   link:  chapters/abms.html
 
 - hr: true
 
 - title: Chat and Commands
-  num:   7
+  num:   8
   link:  chapters/chat.html
 
 - title: Player Physics
-  num:   8
+  num:   9
   link:  chapters/player_physics.html
 
 - title: Formspecs
-  num:   9
+  num:   10
   link:  chapters/formspecs.html
 
 - title: HUD
-  num:   10
+  num:   11
   link:  chapters/hud.html
 
 - hr: true
 
 - title: Releasing a Mod
-  num: 11
+  num: 12
   link: chapters/releasing.html
 
 - hr: true
diff --git a/chapters/formspecs.md b/chapters/formspecs.md
index f34f5ed..c548335 100644
--- a/chapters/formspecs.md
+++ b/chapters/formspecs.md
@@ -246,7 +246,7 @@ end)
 ## Node Meta Formspecs
 
 minetest.show_formspec is not the only way to show a formspec, you can also
-add formspecs to a node's meta data. This is used on nodes such as chests to
+add formspecs to a [node's meta data](node_metadata.html). This is used on nodes such as chests to
 allow for faster opening times - you don't need to wait for the server to send
 the player the chest formspec.
 
@@ -281,5 +281,3 @@ This style of callback can trigger the callback when you press enter
 in a field, which is impossible with `minetest.show_formspec`,
 however, this kind of form can only be shown by right-clicking on a
 node. It cannot be triggered programmatically.
-
-*Note: node meta data will have been explained by this point in the full book*
diff --git a/chapters/node_metadata.md b/chapters/node_metadata.md
new file mode 100644
index 0000000..f473988
--- /dev/null
+++ b/chapters/node_metadata.md
@@ -0,0 +1,113 @@
+---
+title: Node Metadata
+layout: default
+root: ../
+---
+
+## Introduction
+
+In this chapter you will learn how to manipulate a node's metadata.
+
+* What is Node Metadata?
+* Getting a Metadata Object
+* Reading Metadata
+* Setting Metadata
+* Lua Tables
+* Your Turn
+
+## What is Node Metadata?
+
+Metadata is data about data. So Node Metadata is **data about a node**.
+
+You may use metadata to store:
+
+* an node's inventory (such as in a chest).
+* progress on crafting (such as in a furnace).
+* who owns the node (such as in a locked chest).
+
+The node's type, light levels
+and orientation are not stored in the metadata, but are rather part
+of the data itself.
+
+Metadata is stored in a key value relationship.
+
+| Key     | Value   |
+|---------|---------|
+| foo     | bar     |
+| owner   | player1 |
+| counter | 5       |
+
+## Getting a Metadata Object
+
+Once you have a position of a node, you can do this:
+
+{% highlight lua %}
+local meta = minetest.get_meta(pos)
+-- where pos = { x = 1, y = 5, z = 7 }
+{% endhighlight %}
+
+## Reading Metadata
+
+{% highlight lua %}
+local value = meta:get_string("key")
+
+if value then
+	print(value)
+else
+	-- value == nil
+	-- metadata of key "key" does not exist
+	print(value)
+end
+{% endhighlight %}
+
+Here are all the get functions you can use, as of writing:
+
+* get_string
+* get_int
+* get_float
+* get_inventory
+
+In order to do booleans, you should use `get_string` and `minetest.is_yes`:
+
+
+{% highlight lua %}
+local value = minetest.is_yes(meta:get_string("key"))
+
+if value then
+	print("is yes")
+else
+	print("is no")
+end
+{% endhighlight %}
+
+## Setting Metadata
+
+Setting meta data works pretty much exactly the same way.
+
+{% highlight lua %}
+local value = "one"
+meta:set_string("key", value)
+
+meta:set_string("foo", "bar")
+{% endhighlight %}
+
+Here are all the set functions you can use, as of writing:
+
+* set_string
+* set_int
+* set_float
+
+## Lua Tables
+
+You can convert to and from lua tables using `to_table` and `from_table`:
+
+{% highlight lua %}
+local tmp = meta:to_table()
+tmp.foo = "bar"
+meta:from_table(tmp)
+{% endhighlight %}
+
+## Your Turn
+
+* Make a block which disappears after it has been punched 5 times.
+  (use on_punch in the node def and minetest.set_node)