Chat Channels

MoreCommands allows to create Chat Channels which basically means Chat Rooms. Such a Chat Channel consists of the
following components:

A parent channel (except for the master channel)

Optionally multiple child channels

A List of Members

A Channel Policy which determines who is allowed to be a member of the channel

Because of this structure Chat Channels are organized in a tree-structure. This picture shows
an example of a configuration of Chat Channels:

Knowing this structure this is how to use the Chat Channel system:

Joining/Leaving Chat Channels:
A player is allowed to be in mutliple branches of the channel-tree,
but he can't be in multiple channels of the same branch. A "Branch" contains
all child channels starting from a parent channel. See this
picture for a visualization:
As you can see, on the right picture, a player is member of two channels in the
same branch while on the left, he is member of four channels in different branches.
The right situation is not allowed. If a player wants to join a child
channel, he first has to leave the current channel and then join the child channel.
This e.g. means that if a player is a member of the master channel, he HAS to leave
that channel no matter which channel he wants to join. Generally, a player can't be
a member of any child of a channel if he is member of a parent channel, so he can't
be twice or more times in a branch where the branch's root starts at the first parent
channel of which the player is a member.
The commands to leave and join channels are the following:

/chatchannel join &ltCHANNEL&gt/chatchannel leave &ltCHANNEL&gt

The channels of which a player is a member are saved so you don't have to rejoin them
when leaving the game. If none of the channels a player is member of is available (e.g.
because they were deleted) the player is moved into the master channel.

Use of Channel Policies:
A Channel Policy determines which players are allowed in a chat channel.
There are currently three default channel policies: open, whitelist and blacklist.
The "open" channel policy allows everyone to join, the "whitelist" policy only
specific players and the "blacklist" policy allows everyone but specific players
to join.
The properties of a Channel Policy are specified in json format and vary depeding on
the actual policy (Continue reading to learn about the format).
The Command to change the channel policy or the properties of the current policy
is the following:

It is important to note that Channel Policies are inherited. This means that
a child channel always requires members to fulfill the channel policies of ALL of its
parents. E.g. an open channel that is a child of a whitelist channel still requires all
members to be accepted by the whitelist.
It may be the case that by changing a channel's policy, players are not accepted anymore
In this case they are moved to another channel. The next point describes how the channel
into which they are moved is determined.

Creating/Destroying Chat Channels:
The creation of Chat Channels is constrained by several restrictions as well.
E.g. it is not allowed for a channel to have a parent that is already a child
(This won't be doable using the command anyway). Also the master channel can't
be destroyed. It is possible the configure a channel so that it doesn't receive
chat messages from its parent. The commands to create and destroy chat
channels are the following:

As you can see, there is a parameter DESTROY_CHILDREN for destroying chat channels
This parameter must be true or false and indicates whether child channels should be destroyed
as well, if this true the wil be destroyed. Otherwise their parent is set to the parent of
the destroyed channel. Effectively this means, if this is true, the whole subtree is removed
and otherwise only the given channel is removed. The last parameter specifies a proposed
channel to which players in the affected channels should be moved. If this is not
specified the players will be moved to the first appropriate parent channel, if
this is possible (remember that the player is not allowed to be in two branches, so
if he is an another branch of a parent channel, he can't be moved into that channel).

Storage of Chat Channels:
All Chat Channels are stored in a file called "chatChannels.json" (located in "minecraft_installation_folder/
config/morecommands"). As the file ending says, this file must be formatted in the JSON format. If you don't know
what this is, just google it or see Settings for a brief description.
The file is structured the following way:

The file MUST contain a json array which specifies all child channels of the master channel.
Each such channel is described by a json object with the following properties:

name:
This must be a json string and represents the name of the channel. Note that every name
must be unique and may appear only once!

receiveParentMessages:
This must be a json boolean value, this means true or false. This property
is optional, if it is omitted true is used as default value. Otherwise, this property
indicates whether a channel should receive messages from its parent channel.

policy:
This must be a json object and drescribes the channel policy. It is optional and if it is
omitted, the "open" channel policy will be used as default. Otherwise the structure of this
property depends on the type of the policy. In every case, no matter which policy, there
must be a type property which is a json string and describes the name of the policy
The names are the following: "open" for the open policy and "whitelist" respectively "blacklist"
For the whitelist and blacklist policies. The open policy requires no further properties. The
whitelist and blacklist policy both require a players property which must be a json
array which consists of json strings. Each such string must be a player name and tells
the policy which players are on the whitelist respectively on the blacklist. Optionally
there may be a proposedNewChannel property which must be a json string. This must
be a channel name and describes a proposed new channel for players which have to leave
the channel due to a policy change (e.g. when the whitelist changes). See item 3 for more
details.

children:
This property is optional and describes all the children of this channel. It must be a
json array and again contains Chat Channels so this whole structure can be nested to
describe the channel tree.

Here is an example of this file which describes the channel tree from above:

By default every message a player sends is distributed on all channels of which he is member
and therefore all child channels (except if such a channel is configured not to receive parent
messages). All server messages are distributed on the master channel. Outputs from commands
are not considered as normal chat messages and not distributed on any channel.

By default every message which is distributed on a channel has a prefix with the channel name, e.g.
"[MASTER] Im a cool message". If you want to disable that prefix, see Config
to see how you can do that.