Adds documentation of API and datastructures

README.md

@@ -30,11 +30,93 @@ Set this to the maximum stages your node can have.
 
 This mod can be used in singleplayer and multiplayer. It comes with no direct content but exposes functions you can use in your mod.
 
+### Data structure
+
+One stage consists of at least the stage_name, next_stages and duration. 
+
+```lua
+local stage = {
+    {
+        stage_name = "modname:nodename", -- required, string, nodename to attach this stage to, must not exist previously
+        next_stages = "modname:same_or_other_nodename", -- required, string or table (see below), if missing last stage is assumed
+        --    OR 
+        next_stages = { -- required if not last stage, table format
+            {
+                "modname:same_or_other_nodename", -- required, string, target nodename must exist
+                50,  -- optional, number, chance for the node to switch to this target, defaults to 1
+                { can_set = mymod.optional_can_set_function, more_functions = ... }, -- optional, table, callback table of known keys and function values
+                { param1 = 90, param2 = 107, ... } -- optional, table, metadata table of known keys and whatever values they want
+            },
+            { "modname:same_or_other_nodename"}, -- as above, but without any optional fields
+            { "other_modname:their_nodename"} -- as above, but targets a node from different mod
+        },
+        duration = 120, -- required, number, fixed duration of stage in seconds, if missing last stage is assumed
+        tiles = {"modname_nodename_texturename.png", ... }, -- required, table, table of tiles
+        description = "Node description", -- required, string, node description
+        -- Optional "Node definition" aka "Used by minetest.register_node"
+        node_definition = {
+            drawtype = "normal",
+            ...
+        }
+    }
+}
+```
+
+A list of `{stage}` sit in a table `stages`:
+
+```lua
+local stages = {
+    {stage},
+    {stage},
+    ...
+}
+```
+
 ### Modmakers
 
 Use the following public functions related to nodestages.
 
+```lua
+yl_api_nodestages.get_stage(modname, nodename)
+```
 
+Gets a table with the values of the stage attached to the given `modname:nodename`. Returns `true, {stage}` or `false, errormessage` if an error occurred.
+
+```lua
+yl_api_nodestages.create_stage(stage)
+```
+
+Creates the node without attaching the stage. Returns `true` if the node was successfully created. Returns `false, "errormessage"` if not.
+
+```lua
+yl_api_nodestages.add_stage(stage)
+```
+
+Attaches a stage to an existing node. Returns `true` if the stage was successfully attached. Only successful if the stage does not yet exist. Returns `false, "errormessage"` if not.
+
+```lua
+yl_api_nodestages.overwrite_stage(stage)
+```
+
+Attaches a stage to an existing node. Returns `true` if the stage was successfully attached, regardless whether the stage already exist. Returns `false, "errormessage"` if not.
+
+```lua
+yl_api_nodestages.delete_stage(modname, nodename)
+```
+
+Deletes a stage from an existing node. Returns `true` if the stage was successfully removed. Returns `false, "errormessage"` if not.
+
+```lua
+yl_api_nodestages.register_stages(stages)
+```
+
+Registers all given `stages`, calls create_stage and add_stage. Returns `true, good, bad, total, {}` if all stages were registered successfully. Returns `false, good, bad, total, {reasons}` if at least one stage was not successfully registered.
+
+```lua
+yl_api_nodestages.validate_all_stages()
+```
+
+Validates all stages currently attached to any node. Returns `true, good, bad, total, {}` if all stages were validated successfully. Returns `false, good, bad, total, {reasons}` if at least one stage was not successfully validated.
 
 ## Limitations