Verified Commit a0ddc479 authored by Dirk's avatar Dirk

API documentation update

parent 3095475a
...@@ -6,12 +6,13 @@ xFurniture provides API-like functions that allow and assist mods that add custo ...@@ -6,12 +6,13 @@ xFurniture provides API-like functions that allow and assist mods that add custo
Create all the necessary mod files (`depends.txt` and `init.lua` are enough for testing purposes). You need to depend on `xfurniture` to get access to the necessary functions. In your `init.lua` first you should localize the global function that will be used. Create all the necessary mod files (`depends.txt` and `init.lua` are enough for testing purposes). You need to depend on `xfurniture` to get access to the necessary functions. In your `init.lua` first you should localize the global function that will be used.
In addition to that you might want to get the nodes table. This table is different from Minetest’s `registered_nodes` as it is already filtered as defined by the user. The table can be iterated over later to register the custom furniture for all supported nodes. In addition to that you might want to get the nodes table. This table is different from Minetest’s `registered_nodes` as it is already filtered as defined by the user. The table can be iterated over later to register the custom furniture for all supported nodes. There is also a function `get_nodes()` available that can be used to filter the pre-filtered nodes through a whitelist.
```Lua ```Lua
local register = xfurniture.register local register = xfurniture.register
local apply_indent = xfurniture.apply_indent local apply_indent = xfurniture.apply_indent
local nodes = xfurniture.nodes local nodes = xfurniture.nodes
local get_nodes = xfurniture.get_nodes
``` ```
`apply_indent` is a helper function that allows you to apply the user-configured indent to the nodebox table. The indentation value is read from the configuration value `xfurniture_window_stuff_indent`. As seen from the name this is intended to be used with window decorations (things that are placed against walls). `apply_indent` is a helper function that allows you to apply the user-configured indent to the nodebox table. The indentation value is read from the configuration value `xfurniture_window_stuff_indent`. As seen from the name this is intended to be used with window decorations (things that are placed against walls).
...@@ -65,7 +66,7 @@ This is only useful for things that are placed against walls. Do not rely on ind ...@@ -65,7 +66,7 @@ This is only useful for things that are placed against walls. Do not rely on ind
# Register multiple objects # Register multiple objects
If you want to register multiple objects at once for all of the supported mods you can simply iterate over the previously mentioned `nodes` table. If you want to register multiple objects at once for all of the supported mods you can simply iterate over the previously mentioned `nodes` table or use the `get_nodes()` function.
```Lua ```Lua
for node in pairs(nodes) do for node in pairs(nodes) do
...@@ -88,3 +89,40 @@ end ...@@ -88,3 +89,40 @@ end
As you can see this is pretty much the same function call. Except this time it is in an iteration loop and uses `node` in the recipe and material value. This registers `mymodname:all_nodes_table_default_wood` where `default_wood` is a placeholder for all node names of all the nodes that are in the `nodes` table. As you can see this is pretty much the same function call. Except this time it is in an iteration loop and uses `node` in the recipe and material value. This registers `mymodname:all_nodes_table_default_wood` where `default_wood` is a placeholder for all node names of all the nodes that are in the `nodes` table.
Please note that this could register several hundred nodes depending on the user’s configuration and might crash Minetest by reaching the [max node limit](https://github.com/minetest/minetest/issues/6101). Please note that this could register several hundred nodes depending on the user’s configuration and might crash Minetest by reaching the [max node limit](https://github.com/minetest/minetest/issues/6101).
## Using the `get_nodes()` function
*When not providing a table containing filterstrings using `nodes` is faster than using `get_nodes()` and provides the exact same result.*
With `get_nodes()` all already pre-filtered nodes are filtered through a whitelist represented by a table of filterstrings. A filterstring is a comma delimited string containing a filter and a value. For example `group:foobar` is a filterstring that filters for the node being in group `foobar`. The following filters are available.
* `group` – Matches the group a node is in
* `startswith` – Matches the beginning of node name
* `endswith` – Matches the end of a node name
* `contains` – Matches if a node name contains the value
* `origin` – Matches the node’s `mod_origin` value
* `drawtype` – Matches the node’s drawtype value
* `a node ID` – Matches the exact node ID
The following example registers a table made from all nodes that contain “wood” at some place in the name (and overwrites the recipe from the previous example).
```Lua
for node in pairs(get_nodes({'contains:wood'})) do
register('all_nodes_table', {
name = 'My Cool Table For Wood Nodes',
material = node,
nodebox = {
{-0.0625, -0.5, -0.0625, 0.0625, 0.4375, 0.0625}, -- pole
{-0.375, 0.375, -0.375, 0.375, 0.5, 0.375} -- top
},
recipe = {
{node, node, node},
{'', node, '' },
{'', node, '' }
}
})
end
```
Filter are not applied in combination but individually. So for example using `{ 'group:foo', 'endwith:bar' }` will not match all nodes that are in group “foo” and end with “bar” but will match all nodes in group “foo” and all nodes that end with “bar”.
...@@ -48,3 +48,20 @@ for node in pairs(nodes) do ...@@ -48,3 +48,20 @@ for node in pairs(nodes) do
} }
}) })
end end
-- Using get_nodes() to ad-hoc filter the nodes
for node in pairs(get_nodes({'contains:wood'})) do
register('wooden_nodes_table', {
name = 'My Cool Table For Wood Nodes',
material = node,
nodebox = {
{-0.0625, -0.5, -0.0625, 0.0625, 0.4375, 0.0625}, -- pole
{-0.375, 0.375, -0.375, 0.375, 0.5, 0.375} -- top
},
recipe = { -- Overwrites “Register multiple objects”
{node, node, node},
{'', node, '' },
{'', node, '' }
}
})
end
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment