284 lines
9.2 KiB
Markdown
284 lines
9.2 KiB
Markdown
|
# 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.
|
||
|
|
The length of the tube is limited to 100 nodes.
|
||
|
|
|
||
|
|
For StackItem exchange we have to distinguish the following roles:
|
||
|
|
- client: An active node calling push/pull functions
|
||
|
|
- server: A passive node typically with inventory, which will be called
|
||
|
|
|
||
|
|
Client and server API use the following special parameters:
|
||
|
|
|
||
|
|
- `side` the contact side where the items shall be pulled out or pushed in.
|
||
|
|
This is one of B(ack), R(ight), F(ront), L(eft), D(own), U(p) according to the
|
||
|
|
following diagram (view onto the placed node). It can be used to separate
|
||
|
|
incoming items for different inventories.
|
||
|
|
|
||
|
|
```
|
||
|
|
Up Back
|
||
|
|
| /
|
||
|
|
| /
|
||
|
|
+--|-----+
|
||
|
|
/ o /|
|
||
|
|
+--------+ |
|
||
|
|
Left ----| |o---- Right
|
||
|
|
| o | |
|
||
|
|
| / | +
|
||
|
|
| / |/
|
||
|
|
+-/------+
|
||
|
|
/ |
|
||
|
|
Front |
|
||
|
|
|
|
||
|
|
Down
|
||
|
|
```
|
||
|
|
|
||
|
|
- `player_name`: Normally the name of the player, who placed the pushing node.
|
||
|
|
But this could also be used to identify the player interacting with the
|
||
|
|
pushing node.
|
||
|
|
|
||
|
|
The use of both parameters on server side is not required. See chap. 4 for an example
|
||
|
|
of an inventory node.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
## 2. Data communication
|
||
|
|
|
||
|
|
For the data communication an addressing method based on node numbers is used.
|
||
|
|
Each registered node gets a unique node 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 node 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 return the response
|
||
|
|
|
||
|
|
It is up to the programmer, which messages shall be supported.
|
||
|
|
But if a node can be switched on/off or started/stopped, use "on" and "off" as commands
|
||
|
|
for both cases.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
## 3. API Functions
|
||
|
|
|
||
|
|
|
||
|
|
### Register, Add, Remove Nodes
|
||
|
|
|
||
|
|
Before a node can take part on the item exchange via tubes or data communication,
|
||
|
|
it has to be registered once.
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
tubelib.register_node(name, add_names, node_definition)
|
||
|
|
```
|
||
|
|
Call this function only at load time!
|
||
|
|
Parameters:
|
||
|
|
- name: The node name like "tubelib:pusher"
|
||
|
|
- add_names: A table with additional node names if needed, e.g.: "tubelib:pusher_active"
|
||
|
|
- node_definition: A table with the server callback functions according to:
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
{
|
||
|
|
on_pull_item = func(pos, side, player_name),
|
||
|
|
-- Pull an item from the node inventory.
|
||
|
|
-- The function shall return an item stack with one element
|
||
|
|
-- like ItemStack("default:cobble") or nil.
|
||
|
|
-- Param side: The node contact side, where the item shall be pulled out.
|
||
|
|
-- Param player_name: Can be used to check access rights.
|
||
|
|
|
||
|
|
on_push_item = func(pos, side, item, player_name),
|
||
|
|
-- Push the given item into the node inventory.
|
||
|
|
-- Param side: The node contact side, where the item shall be pushed in.
|
||
|
|
-- Param player_name: Can be used to check access rights.
|
||
|
|
-- The function shall return true if successful, or false if not.
|
||
|
|
|
||
|
|
on_unpull_item = func(pos, side, item, player_name),
|
||
|
|
-- Undo the previous pull and place the given item back into the inventory.
|
||
|
|
-- Param side: The node contact side, where the item shall be unpulled.
|
||
|
|
-- Param player_name: Can be used to check access rights.
|
||
|
|
-- The function shall return true if successful, or false if not.
|
||
|
|
|
||
|
|
on_recv_message = func(pos, topic, payload),
|
||
|
|
-- Execute the requested message
|
||
|
|
-- Param topic: A topic string like "on"
|
||
|
|
-- Param payload: Additional data for more come complex commands,
|
||
|
|
-- payload can be a number, string, or table.
|
||
|
|
-- The function shall return true/false for commands like on/off
|
||
|
|
-- or return the requested data for commands like a "state" request.
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
**Each node has to call:**
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
tubelib.add_node(pos, name)
|
||
|
|
```
|
||
|
|
`add_node` shall be called when the node is placed.
|
||
|
|
The function is used to register the nodes position for the communication node
|
||
|
|
number and to update the tube surrounding.
|
||
|
|
`pos` the node position, `name` is the node name.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
tubelib.remove_node(pos)
|
||
|
|
```
|
||
|
|
'remove_node' shall be called then the node is dig.
|
||
|
|
The function is used to remove the node number from the internal list.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
### Item Exchange via Tubes
|
||
|
|
|
||
|
|
For item exchange as a pushing/pulling node the following functions exist:
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
tubelib.pull_items(pos, side, player_name)
|
||
|
|
```
|
||
|
|
Pull one item from the given position specified by `pos` and `side`.
|
||
|
|
Parameters:
|
||
|
|
- `pos` is the own node position
|
||
|
|
- `side` is the contact side, where the item shall be pulled in
|
||
|
|
- `player_name` can be used to check access rights.
|
||
|
|
- The function returns an item stack with one element like ItemStack("default:cobble") or nil.
|
||
|
|
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
tubelib.push_items(pos, side, items, player_name)
|
||
|
|
```
|
||
|
|
Push one item to the given position specified by `pos` and `side`.
|
||
|
|
Parameters:
|
||
|
|
- `pos` is the own node position
|
||
|
|
- `side` is the contact side, where the item shall be pushed out
|
||
|
|
- `item` is an item stack with one element like ItemStack("default:cobble")
|
||
|
|
- `player_name` can be used to check access rights.
|
||
|
|
The function returns true if successful, or false if not.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
tubelib.unpull_items(pos, side, items, player_name)`
|
||
|
|
```
|
||
|
|
Undo the previous pull and place the item back into the inventory.
|
||
|
|
Parameters:
|
||
|
|
- `pos` is the own node position
|
||
|
|
- `side` id the node contact side, where the item shall be unpulled
|
||
|
|
- `player_name` can be used to check access rights.
|
||
|
|
The function returns true if successful, or false if not.
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
### Wireless Data Communication
|
||
|
|
|
||
|
|
For data communication the following functions exist:
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
tubelib.send_message(numbers, placer_name, clicker_name, topic, payload)
|
||
|
|
```
|
||
|
|
Send a message to all nodes referenced by `numbers`, a string with
|
||
|
|
one or more destination node numbers separated by blanks.
|
||
|
|
The message is based on a topic string (e.g. "start") and
|
||
|
|
a topic related payload.
|
||
|
|
The placer and clicker names are needed to check the protection rights.
|
||
|
|
`placer_name` is the name of the player, who places the node.
|
||
|
|
`clicker_name` is the name of the player, who uses the node.
|
||
|
|
`placer_name` of sending and receiving nodes have to be the same.
|
||
|
|
If every player should be able to send a message, use nil for `clicker_name`.
|
||
|
|
Because several nodes could be addressed, the function don't return any response.
|
||
|
|
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
tubelib.send_request(number, topic, payload)
|
||
|
|
```
|
||
|
|
In contrast to `send_message` this functions send a message to exactly one node
|
||
|
|
referenced by `number` and returns the node response.
|
||
|
|
The message is based on the topic string (e.g. "state") and
|
||
|
|
topic related payload.
|
||
|
|
|
||
|
|
|
||
|
|
## 4. Code Snippets
|
||
|
|
|
||
|
|
### Register Node (from 'legacy_nodes.lua')
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
tubelib.register_node("default:chest", {"default:chest_open"}, {
|
||
|
|
on_pull_item = function(pos, side, player_name)
|
||
|
|
local meta = minetest.get_meta(pos)
|
||
|
|
return tubelib.get_item(meta, "main")
|
||
|
|
end,
|
||
|
|
on_push_item = function(pos, side, item, player_name)
|
||
|
|
local meta = minetest.get_meta(pos)
|
||
|
|
return tubelib.put_item(meta, "main", item)
|
||
|
|
end,
|
||
|
|
on_unpull_item = function(pos, side, item, player_name)
|
||
|
|
local meta = minetest.get_meta(pos)
|
||
|
|
return tubelib.put_item(meta, "main", item)
|
||
|
|
end,
|
||
|
|
})
|
||
|
|
```
|
||
|
|
|
||
|
|
|
||
|
|
### Add/remove node (from 'lamp.lua')
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
after_place_node = function(pos, placer)
|
||
|
|
local number = tubelib.add_node(pos, "tubelib:lamp")
|
||
|
|
...
|
||
|
|
end,
|
||
|
|
|
||
|
|
after_dig_node = function(pos)
|
||
|
|
tubelib.remove_node(pos)
|
||
|
|
end,
|
||
|
|
```
|
||
|
|
|
||
|
|
### Item exchange via tubes (from 'pusher.lua')
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
local items = tubelib.pull_items(pos, "L", player_name)
|
||
|
|
if items ~= nil then
|
||
|
|
if tubelib.push_items(pos, "R", items, player_name) == false then
|
||
|
|
tubelib.unpull_items(pos, "L", items, player_name)
|
||
|
|
end
|
||
|
|
end
|
||
|
|
```
|
||
|
|
|
||
|
|
### Message communication (from 'button.lua')
|
||
|
|
|
||
|
|
```LUA
|
||
|
|
local number = meta:get_string("number")
|
||
|
|
local placer_name = meta:get_string("placer_name")
|
||
|
|
tubelib.send_message(number, placer_name, nil, "stop", nil)
|
||
|
|
```
|
||
|
|
|
||
|
|
### 5. Example Code
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
|
||
|
|
## 6. Further information
|
||
|
|
|
||
|
|
The complete functionality is implemented in the file
|
||
|
|
.
|
||
|
|
This file has further helper functions and is recommended for deeper study.
|
||
|
|
|
||
|
|
## 7. History
|
||
|
|
|
||
|
|
2017-10-02 First draft
|
||
|
|
2017-10-29 Commands start/stop replaced by on/off
|
||
|
|
2018-03-31 Corrections for 'send_request' and 'add_node'
|