diff --git a/README.md b/README.md index 2bd7c73..bf198c3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,23 @@ # Tube Library -Lumber tubes and a simple communication API for Minetest +Minetest Tube Mod for item exchange via lumber tubes and wireless message communication between nodes. + +The focus for this Mod are: +- minimized server load and thus minimized server lags +- simple and intuitive usage for players +- simple API for programmers + +The mod provides: +- lumber tubes to connect 2 blocks +- a Pusher block to pull/push items through tubes +- a Distributor block with 4 output channels to sort incoming items +- a Blackhole block which lets all items disappear (example/template for programmers) +- a Button/switch block to send "switch on/off" messages +- a Lamp block as receiving example for message communication +- support for default blocks: furnace and chests + +Hints for Admins: ![GitHub](https://github.com/joe7575/Minetest-Tubelib/blob/master/manual.md) +Programmers Manual: ![GitHub](https://github.com/joe7575/Minetest-Tubelib/blob/master/api.md) Browse on: ![GitHub](https://github.com/joe7575/Minetest-Tubelib) diff --git a/api.md b/api.md new file mode 100644 index 0000000..18204ce --- /dev/null +++ b/api.md @@ -0,0 +1,67 @@ +# Tubelib Programmers Interface + + +Tubelib supports: +- StackItem exchange via tubes and +- wireless data communication between nodes. + + +## 1. StackItem exchange + +Tubes represent connections between two nodes, so that it is irrelevant +if the receiving node is nearby or far away, connected via tubes. + +For StackItem exchange we have to distinguish the following roles: +- client: An acting node calling push/pull functions +- server: An addressed node typically with inventory, to be worked on + + +## 2. Data communication + +For the data communication an addressing method based on node numbers is used. +Each registered node gets a unique number with 4 figures (or more if needed). +The numbers are stored in a storage list. That means, a new node, placed on +the same position gets the same number as the previously placed node on that +position. + +The communication supports two services: +- send_message: Send a message to one or more nodes without response +- send_request: Send a messages to exactly one node and request a response + + +## 3. API funtions + +Before a node can take part on ItemStack exchange or data communication +it has to be registered once via: +- tubelib.register_node(name, add_names, node_definition) + +Each node shall call: +- tubelib.add_node(pos, name) when it was placed and +- tubelib.remove_node(pos) when it was dug. + +For StackItem exchange the following functions exist: +- tubelib.pull_items(pos, side) +- tubelib.push_items(pos, side, items) +- tubelib.unpull_items(pos, side, items) + +For data communication the following functions exist: +- tubelib.send_message(numbers, placer_name, clicker_name, topic, payload) +- tubelib.send_request(number, placer_name, clicker_name, topic, payload) + + +## 4. Examples + +Tubelib includes the following example nodes which can be used for study +and as templates for own projects: + +- pusher.lua: a simple client pushing/pulling items +- blackhole.lua: a simple server client, makes all items disappear +- button.lua: a simple communication node, only sending messages +- lamp.lua: a simple communication node, only receiving messages + + +## 5. Further information + +The complete API is located in the file [command.lua]. This file gives more information to each +API function and is recommended for further study. + diff --git a/command.lua b/command.lua index 0d5c19e..0ecf260 100644 --- a/command.lua +++ b/command.lua @@ -10,64 +10,8 @@ command.lua: - Tubelib supports: - 1) StackItem exchange via tubes and - 2) wireless data communication between nodes. - - - 1. StackItem exchange - - Tubes represent connection between two nodes, so that it is irrelevant - if the receiving node is nearby or far away, connected via tubes. - - For StackItem exchange we have to distinguish the following roles: - - client: An acting node calling push/pull functions - - server: An addressed node typically with inventory, to be worked on - - - 2. Data communication - - For the data communication an addressing method based on node numbers is used. - Each registered node gets a unique number with 4 figures (or more if needed). - The numbers are stored in a storage list. That means, a new node placed on - the same position gets the same number as the previouly placed node on that - position. - - The communication supports two services: - - send_message: Send a message to one or more nodes without response - - send_request: Send a messages to exactly one node and request a response + See [api.md] for the interface documentation - - 3. API funtions - - Before a node can take part on ItemStack exchange or data communication - it has to be registered once via: - - tubelib.register_node(name, add_names, node_definition) - - Each node shall call: - - tubelib.add_node(pos, name) when it was placed and - - tubelib.remove_node(pos) when it was dug. - - For StackItem exchange the following functions exist: - - tubelib.pull_items(pos, side) - - tubelib.push_items(pos, side, items) - - tubelib.unpull_items(pos, side, items) - - For data communication the following functions exist: - - tubelib.send_message(numbers, placer_name, clicker_name, topic, payload) - - tubelib.send_request(number, placer_name, clicker_name, topic, payload) - - - 4. Examples - - Tubelib includes the following example nodes which can be used for study - and as templates for own projects: - - - pusher.lua: a simple client pushing/pulling items - - blackhole.lua: a simple server client, makes all items disappear - - button.lua: a simple communication node, only sending messages - - lamp.lua: a simple communication node, only receiving messages - ]]-- -- diff --git a/manual.md b/manual.md new file mode 100644 index 0000000..d00f2fd --- /dev/null +++ b/manual.md @@ -0,0 +1,34 @@ +# Tubelib Library + +## Hints for Admins and Players + +Tubelib is little useful for itself, it makes only sense with extensions such as tubelib_addons1. + +But Tubelib provides the following basic blocks: + +### Tubes +Tubes allow the item exchange between two blocks. Forks are not possible. You have to use chests or other inventory blocks as hubs to build more complex structures. The maximum length of one tube is 48 blocks. +Tubes for itself are passive. For item exchange you have to use a pulling/pushing block in addition. + +### Pusher +The Pusher is able to pull one item out of one inventory block and pushing it into another inventory block by means of the tubes. +It the source block is empty or the destination block full, the Pusher goes for some seconds into STANDBY state. + +### Distributor +The Distributor works as filter and pusher. It allows to divide and distribute incoming items into 4 tube channels. +The channels can be switched on/off and individually configured with up to 6 items. The filter passes the configured +items and restrains all others. To increase the throughput, one item can be added several times to a filter. +An unconfigured but activated filter allows to pass up to 6 remaining items. + +### Button/Switch +The Button/Switch is a simple communication block for the Tubelib wireless communication. +This block can be configured as button and switch. For the button configuration different switching +times from 2 to 16 seconds are possible. The Button/Switch block has to be configured with the destination +number of the receiving block (e.g. Lamp). This block allows to configure several receivers by means or their numbers. + +### Lamp +The Lamp is a receiving block, showing its destination/communication number via "infotext". +The Lamp can be switched on/off by means of right mouse button (use function) or by means of messages commands +from a Button/Switch or any other command sending block. + +