Merge pull request #15 from wsor4035/modchannels

Document modchannels

doc/modchannels.adoc

@@ -0,0 +1,96 @@
+= Modchannels
+
+Allows server side mods (SSMs) communication to client side mods (CSMs) and vice versa.
+
+== Server Side API
+
+=== Functions
+
+==== minetest.mod_channel_join(channel_name)
+
+* `channel_name`: string, modchannel name
+
+Returns an object for use with <<Methods>>. 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
+* `message`: string, message
+
+Used for handling messages received from the client.
+
+=== Methods
+
+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`
+
+TIP: Set the channel to `nil` afterwords to free resources
+
+==== channel:is_writeable()
+
+* Returns `bool`: `true` true if the channel is writeable, `false` if it's not.
+
+==== channel:send_all(message)
+
+* `message`: string, limited to 65535 bytes
+
+Sends to all SSMs and CSMs on the channel.
+
+CAUTION: The message will not if channel is not writable or invalid.
+
+== Client Side API
+
+=== Functions
+
+==== minetest.mod_channel_join(channel_name)
+
+* `channel_name`: string, modchannel name
+
+Returns an object for use with <<Methods>>. 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
+* `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
+[start=0]
+. join_ok
+. join_failed
+. leave_ok
+. leave_failed
+. 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`.
+
+==== channel:leave()
+
+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
+
+==== channel:is_writeable()
+
+* Returns `bool`: `true` true if the channel is writeable, `false` if it's not.
+
+==== channel:send_all(message)
+
+* `message`: string, limited to 65535 bytes
+
+Sends to all SSMs and CSMs on the channel.
+
+CAUTION: The message will not if channel is not writable or invalid.