From 6f1c90720402415b62fb4d5e809ec7dbc1cd7f96 Mon Sep 17 00:00:00 2001 From: Loïc Blot Date: Tue, 26 Sep 2017 00:11:20 +0200 Subject: 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 --- doc/client_lua_api.md | 32 ++++++++++++++++++++++++++++++++ doc/lua_api.txt | 39 ++++++++++++++++++++++++++++++++++++++- doc/mod_channels.png | Bin 0 -> 349332 bytes 3 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 doc/mod_channels.png (limited to 'doc') 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 Binary files /dev/null and b/doc/mod_channels.png differ -- cgit v1.2.3