From 1a3930f9dff4818e8459939bcf7010fe0d8a9476 Mon Sep 17 00:00:00 2001 From: unknown <24964441+wsor4035@users.noreply.github.com> Date: Sun, 2 Jan 2022 15:54:51 -0500 Subject: [PATCH 01/11] document server side modchannels --- doc/modchannels.adoc | 49 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 doc/modchannels.adoc diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc new file mode 100644 index 0000000..a66a5fc --- /dev/null +++ b/doc/modchannels.adoc @@ -0,0 +1,49 @@ += Modchannels + +allows ssm(server side mods) comunication to csm(client side mods) and vice versa. + +== minetest.x api + +=== minetest.mod_channel_join(channel_name) + +* `channel_name`: string, modchannel name +* returns ref for use with <> +* creates channel if not existing and joins the server on that channel +* listen for messages on this channel with `minetest.register_on_modchannel_message` + +=== minetest.register_on_modchannel_message(function(channel_name, sender, message)) + +* `channel_name`: string, modchannel name (already joined) +* `sender`: string, empty if from a ssm, player name if from a client +* `message`: string, message + +== methods + +=== leave() + +* server leaves the channel, no more messages from this channel on `minetest.register_on_modchannel_message` +* set the ref to nil afterwords to free resources + +=== is_writeable() + +* returns boolean, true if the channel is writeable + +=== send_all(message) + +* `message`: string, limited to 65535 characters +* sends to all ssm and csm on the channel +* message will drop if channel is not writable or invalid + + + + + + + + + + + + + + From a8865e0cdefeed623ab13b8d12e2ed2f0dfd3fb1 Mon Sep 17 00:00:00 2001 From: unknown <24964441+wsor4035@users.noreply.github.com> Date: Sun, 2 Jan 2022 15:56:57 -0500 Subject: [PATCH 02/11] delete blank space --- doc/modchannels.adoc | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc index a66a5fc..f1cbe4f 100644 --- a/doc/modchannels.adoc +++ b/doc/modchannels.adoc @@ -32,18 +32,4 @@ allows ssm(server side mods) comunication to csm(client side mods) and vice vers * `message`: string, limited to 65535 characters * sends to all ssm and csm on the channel -* message will drop if channel is not writable or invalid - - - - - - - - - - - - - - +* message will drop if channel is not writable or invalid \ No newline at end of file From de5722890c461d36416e4684bd5781099b2bdc46 Mon Sep 17 00:00:00 2001 From: unknown <24964441+wsor4035@users.noreply.github.com> Date: Sun, 2 Jan 2022 23:50:53 -0500 Subject: [PATCH 03/11] document client side modchannels --- doc/modchannels.adoc | 65 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 56 insertions(+), 9 deletions(-) diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc index f1cbe4f..792db57 100644 --- a/doc/modchannels.adoc +++ b/doc/modchannels.adoc @@ -1,34 +1,81 @@ = Modchannels -allows ssm(server side mods) comunication to csm(client side mods) and vice versa. +allows server side mods(SSMs) comunication to client side mods(CSMs) and vice versa. -== minetest.x api +== Server Side API -=== minetest.mod_channel_join(channel_name) +=== Functions + +==== minetest.mod_channel_join(channel_name) * `channel_name`: string, modchannel name -* returns ref for use with <> +* returns ref for use with <> * creates channel if not existing and joins the server on that channel * listen for messages on this channel with `minetest.register_on_modchannel_message` -=== minetest.register_on_modchannel_message(function(channel_name, sender, message)) +==== minetest.register_on_modchannel_message(function(channel_name, sender, message)) * `channel_name`: string, modchannel name (already joined) * `sender`: string, empty if from a ssm, player name if from a client * `message`: string, message -== methods +=== Methods -=== leave() +==== leave() * server leaves the channel, no more messages from this channel on `minetest.register_on_modchannel_message` * set the ref to nil afterwords to free resources -=== is_writeable() +==== is_writeable() * returns boolean, true if the channel is writeable -=== send_all(message) +==== send_all(message) + +* `message`: string, limited to 65535 characters +* sends to all ssm and csm on the channel +* message will drop if channel is not writable or invalid + +== Client Side API + +=== Functions + +==== minetest.mod_channel_join(channel_name) + +* `channel_name`: string, modchannel name +* returns ref for use with <> +* creates channel if not existing and joins the server on that channel +* listen for messages on this channel with `minetest.register_on_modchannel_message` + +==== minetest.register_on_modchannel_message(function(channel_name, sender, message)) + +* `channel_name`: string, modchannel name (already joined and recieved acknowledgement) +* `sender`: string, empty if from a ssm, player name if from a client +* `message`: string, message + +==== minetest.register_on_modchannel_signal(function(channel_name, signal)) +* `channel_name`: string, channel name that the signal has come in on +* `signal`: integer, 0 - 5 +[start=0] +. join_ok +. join_failed +. leave_ok +. leave_failed +. event_on_not_joined_channel +. state_changed + +=== Methods + +==== leave() + +* server leaves the channel, no more messages from this channel on `minetest.register_on_modchannel_message` +* set the ref to nil afterwords to free resources + +==== is_writeable() + +* returns boolean, true if the channel is writeable + +==== send_all(message) * `message`: string, limited to 65535 characters * sends to all ssm and csm on the channel From 1e29cab1c6d6d3f3b38a8919c337c37e266a1fe9 Mon Sep 17 00:00:00 2001 From: unknown <24964441+wsor4035@users.noreply.github.com> Date: Sun, 2 Jan 2022 23:57:54 -0500 Subject: [PATCH 04/11] characters -> bytes --- doc/modchannels.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc index 792db57..cec8fdb 100644 --- a/doc/modchannels.adoc +++ b/doc/modchannels.adoc @@ -32,7 +32,7 @@ allows server side mods(SSMs) comunication to client side mods(CSMs) and vice ve ==== send_all(message) -* `message`: string, limited to 65535 characters +* `message`: string, limited to 65535 bytes * sends to all ssm and csm on the channel * message will drop if channel is not writable or invalid @@ -77,6 +77,6 @@ allows server side mods(SSMs) comunication to client side mods(CSMs) and vice ve ==== send_all(message) -* `message`: string, limited to 65535 characters +* `message`: string, limited to 65535 bytes * sends to all ssm and csm on the channel * message will drop if channel is not writable or invalid \ No newline at end of file From fe0524f994a3c99b6f18e8bda4481e7592ee5419 Mon Sep 17 00:00:00 2001 From: unknown <24964441+wsor4035@users.noreply.github.com> Date: Mon, 3 Jan 2022 23:58:47 -0500 Subject: [PATCH 05/11] small format tweaks --- doc/modchannels.adoc | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc index cec8fdb..455d932 100644 --- a/doc/modchannels.adoc +++ b/doc/modchannels.adoc @@ -1,6 +1,6 @@ = Modchannels -allows server side mods(SSMs) comunication to client side mods(CSMs) and vice versa. +Allows server side mods (SSMs) communication to client side mods (CSMs) and vice versa. == Server Side API @@ -21,16 +21,18 @@ allows server side mods(SSMs) comunication to client side mods(CSMs) and vice ve === Methods -==== leave() +NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. + +==== channel:leave() * server leaves the channel, no more messages from this channel on `minetest.register_on_modchannel_message` * set the ref to nil afterwords to free resources -==== is_writeable() +==== channel:is_writeable() * returns boolean, true if the channel is writeable -==== send_all(message) +==== channel:send_all(message) * `message`: string, limited to 65535 bytes * sends to all ssm and csm on the channel @@ -66,16 +68,18 @@ allows server side mods(SSMs) comunication to client side mods(CSMs) and vice ve === Methods -==== leave() +NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. + +==== channel:leave() * server leaves the channel, no more messages from this channel on `minetest.register_on_modchannel_message` * set the ref to nil afterwords to free resources -==== is_writeable() +==== channel:is_writeable() * returns boolean, true if the channel is writeable -==== send_all(message) +==== channel:send_all(message) * `message`: string, limited to 65535 bytes * sends to all ssm and csm on the channel From ef9ef4d1b5a87999062fe2a04c838f3a1b97b433 Mon Sep 17 00:00:00 2001 From: unknown <24964441+wsor4035@users.noreply.github.com> Date: Tue, 4 Jan 2022 00:25:20 -0500 Subject: [PATCH 06/11] langauge tweaks --- doc/modchannels.adoc | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc index 455d932..f899df0 100644 --- a/doc/modchannels.adoc +++ b/doc/modchannels.adoc @@ -9,9 +9,8 @@ Allows server side mods (SSMs) communication to client side mods (CSMs) and vice ==== minetest.mod_channel_join(channel_name) * `channel_name`: string, modchannel name -* returns ref for use with <> -* creates channel if not existing and joins the server on that channel -* listen for messages on this channel with `minetest.register_on_modchannel_message` + +Returns a object for use with <>. Creates the channel if it does not exist and joins the channel. ==== minetest.register_on_modchannel_message(function(channel_name, sender, message)) @@ -25,8 +24,9 @@ NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. ==== channel:leave() -* server leaves the channel, no more messages from this channel on `minetest.register_on_modchannel_message` -* set the ref to nil afterwords to free resources +The server will leave the channel, meaning no more messages from this channel on `minetest.register_on_modchannel_message` + +TIP: set the ref to nil afterwords to free resources ==== channel:is_writeable() @@ -45,9 +45,8 @@ NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. ==== minetest.mod_channel_join(channel_name) * `channel_name`: string, modchannel name -* returns ref for use with <> -* creates channel if not existing and joins the server on that channel -* listen for messages on this channel with `minetest.register_on_modchannel_message` + +Returns a object for use with <>. Creates the channel if it does not exist and joins the channel. ==== minetest.register_on_modchannel_message(function(channel_name, sender, message)) @@ -72,8 +71,9 @@ NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. ==== channel:leave() -* server leaves the channel, no more messages from this channel on `minetest.register_on_modchannel_message` -* set the ref to nil afterwords to free resources +The server will leave the channel, meaning no more messages from this channel on `minetest.register_on_modchannel_message` + +TIP: set the ref to nil afterwords to free resources ==== channel:is_writeable() From 718e731905da93d6e1a494e47478a40ddc4c071e Mon Sep 17 00:00:00 2001 From: unknown <24964441+wsor4035@users.noreply.github.com> Date: Tue, 4 Jan 2022 00:27:57 -0500 Subject: [PATCH 07/11] ref -> channel object --- doc/modchannels.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc index f899df0..b8cf147 100644 --- a/doc/modchannels.adoc +++ b/doc/modchannels.adoc @@ -26,7 +26,7 @@ NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. The server will leave the channel, meaning no more messages from this channel on `minetest.register_on_modchannel_message` -TIP: set the ref to nil afterwords to free resources +TIP: set the channel to nil afterwords to free resources ==== channel:is_writeable() @@ -73,7 +73,7 @@ NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. The server will leave the channel, meaning no more messages from this channel on `minetest.register_on_modchannel_message` -TIP: set the ref to nil afterwords to free resources +TIP: set the channel to nil afterwords to free resources ==== channel:is_writeable() From 13b683dea5b418f82a31bcced6b54f3d87daa593 Mon Sep 17 00:00:00 2001 From: unknown <24964441+wsor4035@users.noreply.github.com> Date: Tue, 4 Jan 2022 00:31:10 -0500 Subject: [PATCH 08/11] styling --- doc/modchannels.adoc | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc index b8cf147..aee2466 100644 --- a/doc/modchannels.adoc +++ b/doc/modchannels.adoc @@ -35,8 +35,10 @@ TIP: set the channel to nil afterwords to free resources ==== channel:send_all(message) * `message`: string, limited to 65535 bytes -* sends to all ssm and csm on the channel -* message will drop if channel is not writable or invalid + +Sends to all SSMs and CSMs on the channel. + +TIP: The message will drop if channel is not writable or invalid == Client Side API @@ -82,5 +84,7 @@ TIP: set the channel to nil afterwords to free resources ==== channel:send_all(message) * `message`: string, limited to 65535 bytes -* sends to all ssm and csm on the channel -* message will drop if channel is not writable or invalid \ No newline at end of file + +Sends to all SSMs and CSMs on the channel. + +TIP: The message will drop if channel is not writable or invalid \ No newline at end of file From 3940703fc9579f4c929b80eb614a62b11b20dbbf Mon Sep 17 00:00:00 2001 From: unknown <24964441+wsor4035@users.noreply.github.com> Date: Tue, 4 Jan 2022 00:52:25 -0500 Subject: [PATCH 09/11] address review request --- doc/modchannels.adoc | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc index aee2466..6602c85 100644 --- a/doc/modchannels.adoc +++ b/doc/modchannels.adoc @@ -10,14 +10,16 @@ Allows server side mods (SSMs) communication to client side mods (CSMs) and vice * `channel_name`: string, modchannel name -Returns a object for use with <>. Creates the channel if it does not exist and joins the channel. +Returns an object for use with <>. Creates the channel if it does not exist and joins the channel. ==== minetest.register_on_modchannel_message(function(channel_name, sender, message)) * `channel_name`: string, modchannel name (already joined) -* `sender`: string, empty if from a ssm, player name if from a client +* `sender`: string, empty if from a SSM, player name if from a client * `message`: string, message +Used for handling messages received from the client. + === Methods NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. @@ -26,11 +28,11 @@ NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. The server will leave the channel, meaning no more messages from this channel on `minetest.register_on_modchannel_message` -TIP: set the channel to nil afterwords to free resources +TIP: Set the channel to `nil`` afterwords to free resources ==== channel:is_writeable() -* returns boolean, true if the channel is writeable +* Returns `bool`: `true` true if the channel is writeable, `false` if it's not. ==== channel:send_all(message) @@ -38,7 +40,7 @@ TIP: set the channel to nil afterwords to free resources Sends to all SSMs and CSMs on the channel. -TIP: The message will drop if channel is not writable or invalid +Caution: The message will not if channel is not writable or invalid. == Client Side API @@ -48,14 +50,16 @@ TIP: The message will drop if channel is not writable or invalid * `channel_name`: string, modchannel name -Returns a object for use with <>. Creates the channel if it does not exist and joins the channel. +Returns an object for use with <>. Creates the channel if it does not exist and joins the channel. Is equivalent to the the server side function. ==== minetest.register_on_modchannel_message(function(channel_name, sender, message)) * `channel_name`: string, modchannel name (already joined and recieved acknowledgement) -* `sender`: string, empty if from a ssm, player name if from a client +* `sender`: string, empty if from a SSM, player name if from a client * `message`: string, message +Used for handling messages received from the client. Is equivalent to the the server side function. + ==== minetest.register_on_modchannel_signal(function(channel_name, signal)) * `channel_name`: string, channel name that the signal has come in on * `signal`: integer, 0 - 5 @@ -73,13 +77,13 @@ NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. ==== channel:leave() -The server will leave the channel, meaning no more messages from this channel on `minetest.register_on_modchannel_message` +The client will leave the channel, meaning no more messages from this channel on `minetest.register_on_modchannel_message` -TIP: set the channel to nil afterwords to free resources +TIP: Set the channel to `nil`` afterwords to free resources ==== channel:is_writeable() -* returns boolean, true if the channel is writeable +* Returns `bool`: `true` true if the channel is writeable, `false` if it's not. ==== channel:send_all(message) @@ -87,4 +91,4 @@ TIP: set the channel to nil afterwords to free resources Sends to all SSMs and CSMs on the channel. -TIP: The message will drop if channel is not writable or invalid \ No newline at end of file +Caution: The message will not if channel is not writable or invalid. \ No newline at end of file From a439070021646ae63e2377721cf12cac1183e542 Mon Sep 17 00:00:00 2001 From: wsor4035 <24964441+wsor4035@users.noreply.github.com> Date: Tue, 4 Jan 2022 01:07:10 -0500 Subject: [PATCH 10/11] Apply suggestions from code review Co-authored-by: benrob0329 --- doc/modchannels.adoc | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc index 6602c85..8350df6 100644 --- a/doc/modchannels.adoc +++ b/doc/modchannels.adoc @@ -28,7 +28,7 @@ NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. The server will leave the channel, meaning no more messages from this channel on `minetest.register_on_modchannel_message` -TIP: Set the channel to `nil`` afterwords to free resources +TIP: Set the channel to `nil` afterwords to free resources ==== channel:is_writeable() @@ -40,7 +40,7 @@ TIP: Set the channel to `nil`` afterwords to free resources Sends to all SSMs and CSMs on the channel. -Caution: The message will not if channel is not writable or invalid. +CAUTION: The message will not if channel is not writable or invalid. == Client Side API @@ -71,6 +71,7 @@ Used for handling messages received from the client. Is equivalent to the the se . event_on_not_joined_channel . state_changed +Used to handle signals generated by the mod channel system. === Methods NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. @@ -79,7 +80,7 @@ NOTE: `channel` here means the object returned by `minetest.mod_channel_join`. The client will leave the channel, meaning no more messages from this channel on `minetest.register_on_modchannel_message` -TIP: Set the channel to `nil`` afterwords to free resources +TIP: Set the channel to `nil` afterwords to free resources ==== channel:is_writeable() @@ -91,4 +92,4 @@ TIP: Set the channel to `nil`` afterwords to free resources Sends to all SSMs and CSMs on the channel. -Caution: The message will not if channel is not writable or invalid. \ No newline at end of file +CAUTION: The message will not if channel is not writable or invalid. \ No newline at end of file From 5924beb7d168ed5c9d9a835ed40d7f8b3faf109e Mon Sep 17 00:00:00 2001 From: wsor4035 <24964441+wsor4035@users.noreply.github.com> Date: Tue, 4 Jan 2022 01:15:35 -0500 Subject: [PATCH 11/11] Update doc/modchannels.adoc Co-authored-by: benrob0329 --- doc/modchannels.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/modchannels.adoc b/doc/modchannels.adoc index 8350df6..9336508 100644 --- a/doc/modchannels.adoc +++ b/doc/modchannels.adoc @@ -72,6 +72,7 @@ Used for handling messages received from the client. Is equivalent to the the se . state_changed Used to handle signals generated by the mod channel system. + === Methods NOTE: `channel` here means the object returned by `minetest.mod_channel_join`.