root/1.8.3/trunk/game/txt/hlp/pennchat.hlp

& CHAT
& comsys
  CHAT SYSTEM

  The MUSH has a built-in chat system with many different channels.
  These channels vary from MUSH to MUSH; ask at your local site or
  use @channel/list to see which ones are available.

  You can talk to many people on the MUSH via the chat system, without
  needing to be in the same room as them. Use the "@channel" command
  to join, leave, or check who is on a channel, and use the "@chat"
  or "+" command to communicate.

  If you examine yourself, you will see a list of channels that you are
  currently listening to. Some channels are restricted to wizards or
  administrators only. See the following help topics for details:
    @chat, @channel, @cemit, @clock, cwho()

& +
& @chat
  @chat <channel> = <message>
  +<channel> <message>

  This tells everyone on <channel> your <message>. You can prepend
  <message> with ':' or ';' to pose instead of talk. This command can
  also be formatted:  +<channel> <message>
  You do not need to type the complete name of the channel, only as
  many letters as needed to make it distinct from another channel
  that you're also on.

  Note: if you use the '+' form of this command, and you do not
  use the name of a known channel, your command will be processed
  as normal, preventing user-defined commands like "+last" from
  being clobbered by the chat system.

See also: chat, CHAN_USEFIRSTMATCH
& @CHATFORMAT
  @chatformat <object>[= <message>]

  The @chatformat attribute is evaluated when an object receives
  a channel message. The evaluated result, is displayed to the
  player, otherwise the default message is shown. A null result,
  as long as the attribute exists, shows nothing.

  Registers:
    %0:  The 'type' of the message. It is a single character that
         will always be set:
           '"', ';' or ':' for say, semipose and pose, respectively.
           '|' for an @cemit.
           '@' for a "system" message - such as "Walker has connected."
    %1:  The channel name. e.g: "Public" "Admin" "Softcode"
    %2:  The message as typed (post-evaluation, if necessary) by the
         speaker.  Be warned, though - If type is '@', then %2 will
         contain the entire message, and will include the name of
         the speaker that caused it.
    %3:  The speaker name, unless channel is set NO_NAME.
    %4:  The speaker's channel title, unless none is set, or the
         channel is NO_TITLE.
    %5:  The original message.

    If The channel is NO_NAME, and the speaker either has no title or
    the channel is also set NO_TITLE, then %3 will be "Someone"

(continued in help @chatformat2)
See also: @chat, @pageformat, speak()
& @CHATFORMAT2
  Examples:

  Walker's preferred @chatformat, which strips all ansi out, wraps
  every line to your width and prefixes them with <ChannelName>:

    @chatformat me=<%1> [switch(%0,@,%2,edit(wrap(speak(&[if(%4,%4%b)]%3,
         %0[stripansi(%2)]),sub(width(%!),add(4,strlen(%1)))),%r,%r<%1>%b))]

  If you're on a system with chat_strip_quote set to "no", you might
  want to change the "%0%2" arg to speak() to '[switch(%0,",%2,%0%2)]'

  Suppose you want it just like the old version, but anytime somebody
  says your name, you want it all in red:

    @chatformat me=ansi(if(strmatch(%2,*[name(%!)]*),r,n),%5)

(More examples in help @chatformat3)
& @CHATFORMAT3
  A popular feature in clients now available in PennMUSH directly:
  Let's suppose you want "Public" channel chatter to all be green,
  "Softcode" to be blue and "Admin" to be cyan.

    @chatformat me=ansi(switch(%1,Public,g,Softcode,b,Admin,c,n),%5)

  Maybe you dislike players who re-@name themselves a lot:

    &playernames me=#6061:Walker #7:Javelin #6388:Cheetah
    @chatformat me=<%1> [switch(%0,@,%2,speak(&[if(%4,%4%b)][firstof(
           after(grab(v(playernames),%#:*),:),%3)],%2))]

  Or you're writing a loggerbot, and you want to convert all channel
  input to HTML:

    @chatformat me=CHAT:%1:[edit(switch(%0,@,%2,speak(if(%4,%4%b)%3,%0%2)),
           &,&amp;,<,&lt;,>,&gt;,%r,<BR>,%b%b,%b&nbsp;)]

See also: @chat, @pageformat, speak()
& CHAN_USEFIRSTMATCH
  CHAN_USEFIRSTMATCH (any type)

  When this flag is set on an object that uses the chat system,
  channel name matching will default to the first matching channel
  in cases of ambiguity. Without this flag, attempting to use an
  ambiguous partial channel name will produce an error.

& @cemit
& @nscemit
  @cemit[/noisy|/silent][/noeval] <channel>=<message>
  @nscemit[/noisy|/silent][/noeval] <channel>=<message>

  This command allows <message> to be directly broadcasted to the
  players on <channel>. No channel-prefix is prepended unless the
  /noisy switch is given or the noisy_cemit config option is yes and
  /silent is not given.  If the /noeval switch is given, the <message>
  is not evaluated. This command is intended for use in writing
  extended chat systems.

  @nscemit is a wizard-only version that does not include nospoof
  information in broadcasts.

See also: chat
& @channel
  @channel/list [<channel-prefix>]
  @channel/what [<channel-prefix>]
  @channel/on <channel>[=<player>]
  @channel/off <channel>[=<player>]

  The basic form of this command allows you to see the available
  channels, and join or leave a channel. You do not need to type the
  complete name of the channel, only as many letters as needed to make
  it distinct from other channels.

  Wizards may add and remove other players from channels by providing
  a player name as a second argument.

  Channels may be restricted in who can join them and/or speak on
  them. @channel/list will show you the channel's name, number of users,
  number of message since last restart, access information, and your
  status. See "help channel-list" for an explanation of how to read
  the listing.

  @channel/what will show you the channel's name, access information,
  and a description of the channel's purpose.

  More commands are provided in "help @channel2".
  
See also: chat
& @channel2
  @channel/who <channel>
  @channel/hide <channel> = <yes|no>
  @channel/title <channel> = <string>

  The @channel/who command shows you who is currently on a channel,
  if you are permitted to see it.

  Some channels allow their users to hide from the @channel/who list.
  If you're on such a channel and are permitted to hide, you can
  use @channel/hide <channel>=yes to hide yourself, and
  @channel/hide <channel>=no to reappear.

  @channel/title lets you set a title to appear before your name
  when you speak on the channel. If you leave the channel, your
  title is cleared; use @channel/gag instead (see help @channel3).
  You should escape any commas in your title with backslashes.

  See "help @channel3" for more.
& @channel3
  @channel/mute <channel> = <yes|no>
  @channel/gag <channel> = <yes|no>
  @channel/recall <channel> [ = <lines|duration>[,<start line>] ]

  Some channels broadcast messages when players connect or disconnect from
  the MUSH. If you don't want to hear those messages, use @channel/mute
  <channel>=yes. To resume hearing the messages, use @channel/mute
  <channel>=no or @channel/unmute <channel>. Leave out <channel>
  to mute or unmute all channels.

  If you want to remain on a channel but not receive any messages
  on the channel, use @channel/gag <channel>=yes. To resume hearing,
  use @channel/gag <channel>=no (or @channel/ungag <channel>). When
  you disconnect, the channel will be automatically ungagged for you.
  Leave out <channel> to gag or ungag all channels.  If the channel does
  not have the "open" priv, you can not speak on it while you are gagged.

  @channel/recall shows you the most recent messages on the channel;
  the number of messages depends on how the channel is configured, but
  can be limited by specifying <lines> to show and a <start line> to
  start display from.  If <lines> is an elapsed time, like '1h',
  messages from within the given interval will be recalled.  You must
  be on a channel to recall from it.

  See "help @channel4" for more.
& @channel4
  @channel/add <channel> [= <priv>]
  @channel/delete <channel>
  @channel/desc <channel> = <desc>
  @channel/rename <channel> = <new name>

  @channel/add creates a new channel. On some MUSHes, any player
  can create a new channel, though there will be a cost associated
  with creation (see @config chat). Possible <priv> specifications:
  * "player" - players may use the channel
  * "object" - objects may use the channel
  * "admin" - only royalty/wizards/chat_privs may use the channel
  * "wizard" - only wizards may use the channel
  * "quiet" - channel will not show connection messages
  * "open" - you may speak even if you aren't listening to the channel
  * "hide_ok" - you may hide from the channel who list.
  * "notitles" - chantitles are not displayed in channel messages.
  * "nonames" - player names are not displayed in channel messages.
  * "nocemit" - @cemit is prohibited on the channel.
  * "interact" - Interaction rules (defined in local.c) are applied to 
    the channel
  Specifications may be combined, space-separated. Default is determined
  by the 'channel_flags' @config option, or 'player' if not set.

  @channel/delete removes a channel. You must own it or be Wizard.
  @channel/desc sets the channel's description, shown on @channel/what.
    Descriptions are limited to 256 characters. If there are any commas
    in the description, the whole string should be enclosed in {}'s.
  @channel/rename is used to rename a channel.

  See "help @channel5" for more. See also "help @clock".
& @channel5
  @channel/priv <channel> = <new priv level>
  @channel/wipe <channel>
  @channel/buffer <channel> = <lines>
  @channel/decompile[/brief] <channel>
  @channel/chown <channel> = <new owner>

  The "priv" switch sets the channel's access privileges to those specified.
  The "wipe" switch clears a channel of players without deleting it.
  The "buffer" switch sets the maximum number of full-length lines that
  the channel will buffer for @chan/recall. Many more shorter lines may
  actually be buffered. Setting it to 0 turns off buffering.

  The "decompile" and "chown" switches can only be used by Wizards.
  @channel/decompile produces a decompile of matching channels. If the
  /brief switch is included, players on the channel aren't listed.
  @channel/chown allows a Wizard to change the owner of a channel.

& channel-list
Here's the legend for reading the @channel/list output:

Channel Name               Num Users Num Msgs  Access Locks     Status  Buf
Sample                             1        0 [DPOWQHo jsmvh*] [On  QH]   4
                                               ||||||| ||||||   |   ||    |
Channel is DISABLED----------------------------/|||||| ||||||   |   ||    |
Channel allows PLAYERS--------------------------/||||| ||||||   |   ||    |
Channel allows OBJECTS---------------------------/|||| ||||||   |   ||    |
Channel is Wizard-only (W) or Admin-only (A)------/||| ||||||   |   ||    |
Channel is QUIET-----------------------------------/|| ||||||   |   ||    |
Channel is HIDE_OK----------------------------------/| ||||||   |   ||    |
Channel is OPEN (non-members can speak on it)--------/ ||||||   |   ||    |
Channel has @clock/join set----------------------------||||||   |   ||    |
Channel has @clock/speak set----------------------------/||||   |   ||    |
Channel has @clock/mod set-------------------------------/|||   |   ||    |
Channel has @clock/see set--------------------------------/||   |   ||    |
Channel has @clock/hide set--------------------------------/|   |   ||    |
Player is the owner of the channel--------------------------/   |   ||    |
Player is currently on/off/gagging the channel------------------/   ||    |
If on, player has the channel muted---------------------------------/|    |
If on, player is hiding on the channel-------------------------------/    |
Size of the channel buffer in full-length lines---------------------------/
& @clock
  @clock/join <channel> [= <key>]
  @clock/speak <channel> [= <key>]
  @clock/see <channel> [= <key>]
  @clock/hide <channel> [= <key>]
  @clock/mod <channel> [= <key>]

  The @clock command modifies the a lock on a chat channel if the
  extended chat system is in use. If no key is specified, the
  lock is unlocked. Evaluation locks will not work with @clock. 
  See help @clock2 for information on using indirect locks.

  The "join" lock restricts who can join the channel.
  The "speak" lock restricts who can speak to the channel.
  The "see" lock restricts who can see the channel on @channel/list
  The "hide" lock restricts @channel/hide if the channel is hide_ok.
  The "mod" lock restricts who can modify the channel. If you pass the
  mod lock on the channel, you can do anything short of deleting it.

  When new channels are added, the mod lock is set to the creator/owner,
  and all other locks are unlocked.

  See help @clock2 for how to use indirect locks to lock a channel to
  anything.

& @clock2
If user-defined locks are available, you can use indirect @clocks
to lock a channel to a lock of any type (including evaluation locks)
on a VISUAL object. This channel can only be joined by an UNFINDABLE player:

  >@clock/join unfindchannel=@#10
  >@lock/user:ChanJoinLock #10=isunfind/1
  >&isunfind #10=[hasflag(%#,unfindable)]
  >@set #10 = VISUAL

@clock                  Corresponding default user: lock for object
join                    ChanJoinLock
speak                   ChanSpeakLock
see                     ChanSeeLock
hide                    ChanHideLock
mod                     ChanModLock

You can lock multiple channels to the same object by specfiying a
specific indirect lock instead of the default one:

  >@clock/join onechannel=@#10/onechanneljoin
  >@clock/join anotherchannel=@#10/anotherchanneljoin
  >@lock/user:onechanneljoin #10 = 1
  >@lock/user:anotherchanneljoin #10 = isunfind/1
& COWNER()
  cowner(<channel>)

  Returns the dbref of the owner of a channel.
& CTITLE()
  ctitle(<channel>,<object>)

  Returns <object>'s @chan/title on <channel>. You must either
  be able to examine the object, or it must visible be on a channel
  which you are allowed to join.
& CSTATUS()
  cstatus(<channel>,<object>)

  Returns <object>'s status with respect to <channel>, which may be
  "Off", "On", or "Gag". You must either be able to examine the object,
  or it must visible be on the channel; "Off" is returned for
  objects that you can not see on the channel.
& CDESC()
& CUSERS()
& CMSGS()
& CBUFFER()
  cdesc(<channel>)
  cusers(<channel>)
  cmsgs(<channel>)
  cbuffer(<channel>)

  Return the description, number of users, number of messages,
  or buffer size of <channel>, respectively. This information is
  also displayed in @chan/list.
& CWHO()
  cwho(<channel>)
 
  This returns a list of connected dbrefs who are on <channel>. 
  When used by mortals, hidden/DARK players do not appear on the list.
& CEMIT()
  cemit(<channel>, <message>[, <noisy>])

  Sends a message to all players listening to the given chat channel.
  See help @cemit for details.

  If the third argument is a true value, the channel name will be
  prepended to the message, behaving like @cemit/noisy.
& CFLAGS()
& CLFLAGS()
  cflags(<channel>)
  cflags(<channel>,<object>)
  clflags(<channel>)
  clflags(<channel>,<object>)

  With one argument, cflags() returns a list of flags set on the
  given channel, represented as a string of characters. See
  'help channel-list' for the list of flags (they appear in the
  "Access" column). You must be able to see the channel to use this
  function.

  With two arguments, cflags() returns a list of flags for that
  object on that channel, currently a string consisting of zero
  or more of "G" (gagging), "Q" (muted), and "H" (hidden).
  You must be able to see that channel and to examine the object
  to use this function. If the object is not on the channel, an
  error is returned.

  The clflags versions return a space-separated list of flag names,
  rather than a string of flag characters.
& CHANNELS()
  channels([<delimiter>])
  channels(<object>)
  channels(<object>[,<delimiter>])

  With no arguments, channels() returns the list of all channel names
  which are visible to the player. With two arguments, returns the list
  of channel names to which the object is listening, delimited by
  <delimiter>.

  With one argument, the behavior is ambiguous. If the argument
  matches an object, returns the list of names to which the object
  is listening, space-delimited. If not, it's treated as a no-argument
  case with a delimiter.

  If you don't have permission to examine the object, you only see 
  those channels to which the object belong for which you have 
  permission to join (or are joined to).
& CLOCK()
  clock(<channel>[/<locktype>][, <new lock>])

  With one argument, returns the value of a lock on a channel, if you
  own the channel or are See_All.  If no locktype is given, "JOIN" 
  is assumed.
  With two arguments, sets the lock if you would be able to do so via
  @clock.

See also: @clock
& CRECALL()
  crecall(<channel>[, <lines> [, <start line> [, <osep> [, <timestamps?> ]]]])

  This function is the functional form of @chan/recall, and returns a
  string containing the recalled lines from the channel, separated by
  <osep>. If <timestamps?> is a true value, the recalled lines will
  include their timestamps; otherwise, they will not.

See also: @channel3
& Channel functions
  Channel functions work with the channel system.

  cbuffer()     cdesc()       cemit()       cflags()      channels()
  clflags()     clock()       cmsgs()       cowner()      crecall()
  cstatus()     ctitle()      cusers()      cwho()