summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLoïc Blot <nerzhul@users.noreply.github.com>2017-09-26 00:11:20 +0200
committerGitHub <noreply@github.com>2017-09-26 00:11:20 +0200
commit6f1c90720402415b62fb4d5e809ec7dbc1cd7f96 (patch)
tree6f94c2bbc2d343be50945a0074bc16da282a4bc1 /doc
parent6df312a608912b3cb21d04532151e29e8b0c7301 (diff)
downloadminetest-6f1c90720402415b62fb4d5e809ec7dbc1cd7f96.tar.gz
minetest-6f1c90720402415b62fb4d5e809ec7dbc1cd7f96.tar.bz2
minetest-6f1c90720402415b62fb4d5e809ec7dbc1cd7f96.zip
Implement mod communication channels (#6351)
Implement network communication for channels * Implement ModChannel manager server side to route incoming messages from clients to other clients * Add signal handler switch on client & ModChannelMgr on client to handle channels * Add Lua API bindings + client packet sending + unittests * Implement server message sending * Add callback from received message handler to Lua API using registration method
Diffstat (limited to 'doc')
-rw-r--r--doc/client_lua_api.md32
-rw-r--r--doc/lua_api.txt39
-rw-r--r--doc/mod_channels.pngbin0 -> 349332 bytes
3 files changed, 70 insertions, 1 deletions
diff --git a/doc/client_lua_api.md b/doc/client_lua_api.md
index 44c7c2787..4c48b6619 100644
--- a/doc/client_lua_api.md
+++ b/doc/client_lua_api.md
@@ -683,6 +683,12 @@ Call these functions only at load time!
* Called when the local player uses an item.
* Newest functions are called first.
* If any function returns true, the item use is not sent to server.
+* `minetest.register_on_modchannel_message(func(channel_name, sender, message))`
+ * Called when an incoming mod channel message is received
+ * You must have joined some channels before, and server must acknowledge the
+ join request.
+ * If message comes from a server mod, `sender` field is an empty string.
+
### Sounds
* `minetest.sound_play(spec, parameters)`: returns a handle
* `spec` is a `SimpleSoundSpec`
@@ -754,6 +760,16 @@ Call these functions only at load time!
* returns reference to mod private `StorageRef`
* must be called during mod load time
+### Mod channels
+![Mod channels communication scheme](docs/mod channels.png)
+
+* `minetest.mod_channel_join(channel_name)`
+ * Client joins channel `channel_name`, and creates it, if necessary. You
+ should listen from incoming messages with `minetest.register_on_modchannel_message`
+ call to receive incoming messages. Warning, this function is asynchronous.
+ * You should use a minetest.register_on_connect(function() ... end) to perform
+ a successful channel join on client startup.
+
### Misc.
* `minetest.parse_json(string[, nullvalue])`: returns something
* Convert a string containing JSON data into the Lua equivalent
@@ -827,9 +843,25 @@ Call these functions only at load time!
Class reference
---------------
+### ModChannel
+
+An interface to use mod channels on client and server
+
+#### Methods
+* `leave()`: leave the mod channel.
+ * Client leaves channel `channel_name`.
+ * No more incoming or outgoing messages can be sent to this channel from client mods.
+ * This invalidate all future object usage
+ * Ensure your set mod_channel to nil after that to free Lua resources
+* `is_writeable()`: returns true if channel is writeable and mod can send over it.
+* `send_all(message)`: Send `message` though the mod channel.
+ * If mod channel is not writeable or invalid, message will be dropped.
+ * Message size is limited to 65535 characters by protocol.
+
### Minimap
An interface to manipulate minimap on client UI
+#### Methods
* `show()`: shows the minimap (if not disabled by server)
* `hide()`: hides the minimap
* `set_pos(pos)`: sets the minimap position on screen
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index b71eb5477..812b857f7 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -1126,7 +1126,7 @@ The 2D perlin noise described by `noise_params` varies the Y co-ordinate of the
stratum midpoint. The 2D perlin noise described by `np_stratum_thickness`
varies the stratum's vertical thickness (in units of nodes). Due to being
continuous across mapchunk borders the stratum's vertical thickness is
-unlimited.
+unlimited.
`y_min` and `y_max` define the limits of the ore generation and for performance
reasons should be set as close together as possible but without clipping the
stratum's Y variation.
@@ -2496,6 +2496,20 @@ Call these functions only at load time!
* `minetest.register_can_bypass_userlimit(function(name, ip))`
* Called when `name` user connects with `ip`.
* Return `true` to by pass the player limit
+* `minetest.register_on_modchannel_message(func(channel_name, sender, message))`
+ * Called when an incoming mod channel message is received
+ * You should have joined some channels to receive events.
+ * If message comes from a server mod, `sender` field is an empty string.
+* `minetest.register_on_modchannel_signal(func(channel_name, signal))`
+ * Called when a valid incoming mod channel signal is received
+ * Signal id permit to react to server mod channel events
+ * Possible values are:
+ 0: join_ok
+ 1: join_failed
+ 2: leave_ok
+ 3: leave_failed
+ 4: event_on_not_joined_channel
+ 5: state_changed
### Other registration functions
* `minetest.register_chatcommand(cmd, chatcommand definition)`
@@ -2773,6 +2787,14 @@ and `minetest.auth_reload` call the authetification handler.
* spread these updates to neighbours and can cause a cascade
of nodes to fall.
+### Mod channels
+You can find mod channels communication scheme in `docs/mod_channels.png`.
+
+* `minetest.mod_channel_join(channel_name)`
+ * Server joins channel `channel_name`, and creates it if necessary. You
+ should listen from incoming messages with `minetest.register_on_modchannel_message`
+ call to receive incoming messages
+
### Inventory
`minetest.get_inventory(location)`: returns an `InvRef`
@@ -3256,6 +3278,21 @@ These functions return the leftover itemstack.
Class reference
---------------
+### ModChannel
+
+An interface to use mod channels on client and server
+
+#### Methods
+* `leave()`: leave the mod channel.
+ * Server leaves channel `channel_name`.
+ * No more incoming or outgoing messages can be sent to this channel from server mods.
+ * This invalidate all future object usage
+ * Ensure your set mod_channel to nil after that to free Lua resources
+* `is_writeable()`: returns true if channel is writeable and mod can send over it.
+* `send_all(message)`: Send `message` though the mod channel.
+ * If mod channel is not writeable or invalid, message will be dropped.
+ * Message size is limited to 65535 characters by protocol.
+
### `MetaDataRef`
See `StorageRef`, `NodeMetaRef` and `ItemStackMetaRef`.
diff --git a/doc/mod_channels.png b/doc/mod_channels.png
new file mode 100644
index 000000000..08fdfca29
--- /dev/null
+++ b/doc/mod_channels.png
Binary files differ