mirror of
https://github.com/evennia/evennia.git
synced 2026-03-18 13:56:30 +01:00
518 lines
No EOL
44 KiB
HTML
518 lines
No EOL
44 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>Channels — Evennia 1.0-dev documentation</title>
|
||
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<link rel="shortcut icon" href="../_static/favicon.ico"/>
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
</head><body>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Channels</a></li>
|
||
</ul>
|
||
<div class="develop">develop branch</div>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="channels">
|
||
<h1>Channels<a class="headerlink" href="#channels" title="Permalink to this headline">¶</a></h1>
|
||
<p>In a multiplayer game, players often need other means of in-game communication
|
||
than moving to the same room and use <code class="docutils literal notranslate"><span class="pre">say</span></code> or <code class="docutils literal notranslate"><span class="pre">emote</span></code>.</p>
|
||
<p><em>Channels</em> allows Evennia’s to act as a fancy chat program. When a player is
|
||
connected to a channel, sending a message to it will automatically distribute
|
||
it to every other subscriber.</p>
|
||
<p>Channels can be used both for chats between <a class="reference internal" href="Accounts.html"><span class="doc">Accounts</span></a> and between
|
||
<a class="reference internal" href="Objects.html"><span class="doc">Objects</span></a> (usually Characters). Chats could be both OOC
|
||
(out-of-character) or IC (in-charcter) in nature. Some examples:</p>
|
||
<ul class="simple">
|
||
<li><p>A support channel for contacting staff (OOC)</p></li>
|
||
<li><p>A general chat for discussing anything and foster community (OOC)</p></li>
|
||
<li><p>Admin channel for private staff discussions (OOC)</p></li>
|
||
<li><p>Private guild channels for planning and organization (IC/OOC depending on game)</p></li>
|
||
<li><p>Cyberpunk-style retro chat rooms (IC)</p></li>
|
||
<li><p>In-game radio channels (IC)</p></li>
|
||
<li><p>Group telephathy (IC)</p></li>
|
||
<li><p>Walkie talkies (IC)</p></li>
|
||
</ul>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 1.0: </span>Channel system changed to use a central ‘channel’ command and nicks instead of
|
||
auto-generated channel-commands and -cmdset. ChannelHandler was removed.</p>
|
||
</div>
|
||
<section id="using-channels-in-game">
|
||
<h2>Using channels in-game<a class="headerlink" href="#using-channels-in-game" title="Permalink to this headline">¶</a></h2>
|
||
<p>In the default command set, channels are all handled via the mighty
|
||
<a class="reference external" href="../api/evennia.commands.default.comms.CmdChannel.html">channel command</a>, <code class="docutils literal notranslate"><span class="pre">channel</span></code> (or
|
||
<code class="docutils literal notranslate"><span class="pre">chan</span></code>). By default, this command will assume all entities dealing with
|
||
channels are <code class="docutils literal notranslate"><span class="pre">Accounts</span></code>.</p>
|
||
<section id="viewing-and-joining-channels">
|
||
<h3>Viewing and joining channels<a class="headerlink" href="#viewing-and-joining-channels" title="Permalink to this headline">¶</a></h3>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span> <span class="o">-</span> <span class="n">shows</span> <span class="n">your</span> <span class="n">subscriptions</span>
|
||
<span class="n">channel</span><span class="o">/</span><span class="nb">all</span> <span class="o">-</span> <span class="n">shows</span> <span class="nb">all</span> <span class="n">subs</span> <span class="n">available</span> <span class="n">to</span> <span class="n">you</span>
|
||
<span class="n">channel</span><span class="o">/</span><span class="n">who</span> <span class="o">-</span> <span class="n">shows</span> <span class="n">who</span> <span class="n">subscribes</span> <span class="n">to</span> <span class="n">this</span> <span class="n">channel</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To join/unsub a channel do</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span><span class="o">/</span><span class="n">sub</span> <span class="n">channelname</span>
|
||
<span class="n">channel</span><span class="o">/</span><span class="n">unsub</span> <span class="n">channelname</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If you temporarily don’t want to hear the channel for a while (without actually
|
||
unsubscribing), you can mute it:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span><span class="o">/</span><span class="n">mute</span> <span class="n">channelname</span>
|
||
<span class="n">channel</span><span class="o">/</span><span class="n">unmute</span> <span class="n">channelname</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="chat-on-channels">
|
||
<h3>Chat on channels<a class="headerlink" href="#chat-on-channels" title="Permalink to this headline">¶</a></h3>
|
||
<p>To speak on a channel, do</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>channel public Hello world!
|
||
</pre></div>
|
||
</div>
|
||
<p>If the channel-name has spaces in it, you need to use a ‘<code class="docutils literal notranslate"><span class="pre">=</span></code>’:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>channel rest room = Hello world!
|
||
</pre></div>
|
||
</div>
|
||
<p>Now, this is more to type than we’d like, so when you join a channel, the
|
||
system automatically sets up an personal alias so you can do this instead:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">public</span> <span class="n">Hello</span> <span class="n">world</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>This shortcut will not work if the channel-name has spaces in it.
|
||
So channels with long names should make sure to provide a one-word alias as
|
||
well.</p>
|
||
</div>
|
||
<p>Any user can make up their own channel aliases:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span><span class="o">/</span><span class="n">alias</span> <span class="n">public</span> <span class="o">=</span> <span class="n">foo</span><span class="p">;</span><span class="n">bar</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>You can now just do</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>foo Hello world!
|
||
bar Hello again!
|
||
</pre></div>
|
||
</div>
|
||
<p>And even remove the default one if they don’t want to use it</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span><span class="o">/</span><span class="n">unalias</span> <span class="n">public</span>
|
||
<span class="n">public</span> <span class="n">Hello</span> <span class="p">(</span><span class="n">gives</span> <span class="n">a</span> <span class="n">command</span><span class="o">-</span><span class="ow">not</span><span class="o">-</span><span class="n">found</span> <span class="n">error</span> <span class="n">now</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>But you can also use your alias with the <code class="docutils literal notranslate"><span class="pre">channel</span></code> command:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>channel foo Hello world!
|
||
</pre></div>
|
||
</div>
|
||
<blockquote>
|
||
<div><p>What happens when aliasing is that a <a class="reference internal" href="Nicks.html"><span class="doc">nick</span></a> is created that maps your
|
||
alias + argument onto calling the <code class="docutils literal notranslate"><span class="pre">channel</span></code> command. So when you enter <code class="docutils literal notranslate"><span class="pre">foo</span> <span class="pre">hello</span></code>,
|
||
what the server sees is actually <code class="docutils literal notranslate"><span class="pre">channel</span> <span class="pre">foo</span> <span class="pre">=</span> <span class="pre">hello</span></code>. The system is also
|
||
clever enough to know that whenever you search for channels, your channel-nicks
|
||
should also be considered so as to convert your input to an existing channel name.</p>
|
||
</div></blockquote>
|
||
<p>You can check if you missed channel conversations by viewing the channel’s
|
||
scrollback with</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span><span class="o">/</span><span class="n">history</span> <span class="n">public</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This retrieves the last 20 lines of text (also from a time when you were
|
||
offline). You can step further back by specifying how many lines back to start:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span><span class="o">/</span><span class="n">history</span> <span class="n">public</span> <span class="o">=</span> <span class="mi">30</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This again retrieve 20 lines, but starting 30 lines back (so you’ll get lines
|
||
30-50 counting backwards).</p>
|
||
</section>
|
||
<section id="channel-administration">
|
||
<h3>Channel administration<a class="headerlink" href="#channel-administration" title="Permalink to this headline">¶</a></h3>
|
||
<p>To create/destroy a new channel you can do</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span><span class="o">/</span><span class="n">create</span> <span class="n">channelname</span><span class="p">;</span><span class="n">alias</span><span class="p">;</span><span class="n">alias</span> <span class="o">=</span> <span class="n">description</span>
|
||
<span class="n">channel</span><span class="o">/</span><span class="n">destroy</span> <span class="n">channelname</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Aliases are optional but can be good for obvious shortcuts everyone may want to
|
||
use. The description is used in channel-listings. You will automatically join a
|
||
channel you created and will be controlling it. You can also use <code class="docutils literal notranslate"><span class="pre">channel/desc</span></code> to
|
||
change the description on a channel you wnn later.</p>
|
||
<p>If you control a channel you can also kick people off it:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>channel/boot mychannel = annoyinguser123 : stop spamming!
|
||
</pre></div>
|
||
</div>
|
||
<p>The last part is an optional reason to send to the user before they are booted.
|
||
You can give a comma-separated list of channels to kick the same user from all
|
||
those channels at once. The user will be unsubbed from the channel and all
|
||
their aliases will be wiped. But they can still rejoin if they like.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span><span class="o">/</span><span class="n">ban</span> <span class="n">mychannel</span> <span class="o">=</span> <span class="n">annoyinguser123</span>
|
||
<span class="n">channel</span><span class="o">/</span><span class="n">ban</span> <span class="o">-</span> <span class="n">view</span> <span class="n">bans</span>
|
||
<span class="n">channel</span><span class="o">/</span><span class="n">unban</span> <span class="n">mychannel</span> <span class="o">=</span> <span class="n">annoyinguser123</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Banning adds the user to the channels blacklist. This means they will not be
|
||
able to <em>rejoin</em> if you boot them. You will need to run <code class="docutils literal notranslate"><span class="pre">channel/boot</span></code> to
|
||
actually kick them out.</p>
|
||
<p>See the <a class="reference external" href="../api/evennia.commands.default.comms.CmdChannel.html">Channel command</a> api
|
||
docs (and in-game help) for more details.</p>
|
||
<p>Admin-level users can also modify channel’s <a class="reference internal" href="Locks.html"><span class="doc">locks</span></a>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">channel</span><span class="o">/</span><span class="n">lock</span> <span class="n">buildchannel</span> <span class="o">=</span> <span class="n">listen</span><span class="p">:</span><span class="nb">all</span><span class="p">();</span><span class="n">send</span><span class="p">:</span><span class="n">perm</span><span class="p">(</span><span class="n">Builders</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Channels use three lock-types by default:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">listen</span></code> - who may listen to the channel. Users without this access will not
|
||
even be able to join the channel and it will not appear in listings for them.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">send</span></code> - who may send to the channel.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">control</span></code> - this is assigned to you automatically when you create the channel. With
|
||
control over the channel you can edit it, boot users and do other management tasks.</p></li>
|
||
</ul>
|
||
<section id="restricting-channel-administration">
|
||
<h4>Restricting channel administration<a class="headerlink" href="#restricting-channel-administration" title="Permalink to this headline">¶</a></h4>
|
||
<p>By default everyone can use the channel command (<a class="reference external" href="../api/evennia.commands.default.comms.CmdChannel.html">evennia.commands.default.comms.CmdChannel</a>)
|
||
to create channels and will then control the channels they created (to boot/ban
|
||
people etc). If you as a developer does not want regular players to do this
|
||
(perhaps you want only staff to be able to spawn new channels), you can
|
||
override the <code class="docutils literal notranslate"><span class="pre">channel</span></code> command and change its <code class="docutils literal notranslate"><span class="pre">locks</span></code> property.</p>
|
||
<p>The default <code class="docutils literal notranslate"><span class="pre">help</span></code> command has the following <code class="docutils literal notranslate"><span class="pre">locks</span></code> property:</p>
|
||
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">locks</span> <span class="o">=</span> <span class="s2">"cmd:not perm(channel_banned); admin:all(); manage:all(); changelocks: perm(Admin)"</span>
|
||
</pre></div>
|
||
</td></tr></table></div>
|
||
<p>This is a regular <a class="reference internal" href="Locks.html"><span class="doc">lockstring</span></a>.</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">cmd:</span> <span class="pre">pperm(channel_banned)</span></code> - The <code class="docutils literal notranslate"><span class="pre">cmd</span></code> locktype is the standard one used for all Commands.
|
||
an accessing object failing this will not even know that the command exists. The <code class="docutils literal notranslate"><span class="pre">pperm()</span></code> lockfunc
|
||
checks an on-account [Permission](Building Permissions) ‘channel_banned’ - and the <code class="docutils literal notranslate"><span class="pre">not</span></code> means
|
||
that if they <em>have</em> that ‘permission’ they are cut off from using the <code class="docutils literal notranslate"><span class="pre">channel</span></code> command. You usually
|
||
don’t need to change this lock.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">admin:all()</span></code> - this is a lock checked in the <code class="docutils literal notranslate"><span class="pre">channel</span></code> command itself. It controls access to the
|
||
<code class="docutils literal notranslate"><span class="pre">/boot</span></code>, <code class="docutils literal notranslate"><span class="pre">/ban</span></code> and <code class="docutils literal notranslate"><span class="pre">/unban</span></code> switches (by default letting everyone use them).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">manage:all()</span></code> - this controls access to the <code class="docutils literal notranslate"><span class="pre">/create</span></code>, <code class="docutils literal notranslate"><span class="pre">/destroy</span></code>, <code class="docutils literal notranslate"><span class="pre">/desc</span></code> switches.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">changelocks:</span> <span class="pre">perm(Admin)</span></code> - this controls access to the <code class="docutils literal notranslate"><span class="pre">/lock</span></code> and <code class="docutils literal notranslate"><span class="pre">/unlock</span></code> switches. By
|
||
default this is something only [Admins](Building Permissions) can change.</p></li>
|
||
</ul>
|
||
<blockquote>
|
||
<div><p>Note - while <code class="docutils literal notranslate"><span class="pre">admin:all()</span></code> and <code class="docutils literal notranslate"><span class="pre">manage:all()</span></code> will let everyone use these switches, users
|
||
will still only be able to admin or destroy channels they actually control!</p>
|
||
</div></blockquote>
|
||
<p>If you only want (say) Builders and higher to be able to create and admin
|
||
channels you could override the <code class="docutils literal notranslate"><span class="pre">help</span></code> command and change the lockstring to:</p>
|
||
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
|
||
<span class="normal">2</span>
|
||
<span class="normal">3</span>
|
||
<span class="normal">4</span>
|
||
<span class="normal">5</span>
|
||
<span class="normal">6</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="c1"># in for example mygame/commands/commands.py</span>
|
||
|
||
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">default_cmds</span>
|
||
|
||
<span class="k">class</span> <span class="nc">MyCustomChannelCmd</span><span class="p">(</span><span class="n">default_cmds</span><span class="o">.</span><span class="n">CmdChannel</span><span class="p">):</span>
|
||
<span class="n">locks</span> <span class="o">=</span> <span class="s2">"cmd: not pperm(channel_banned);admin:perm(Builder);manage:perm(Builder);changelocks:perm(Admin)"</span>
|
||
</pre></div>
|
||
</td></tr></table></div>
|
||
<p>Add this custom command to your default cmdset and regular users wil now get an
|
||
access-denied error when trying to use use these switches.</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="allowing-characters-to-use-channels">
|
||
<h2>Allowing Characters to use Channels<a class="headerlink" href="#allowing-characters-to-use-channels" title="Permalink to this headline">¶</a></h2>
|
||
<p>The default <code class="docutils literal notranslate"><span class="pre">channel</span></code> command (<a class="reference external" href="../api/evennia.commands.default.comms.CmdChannel.html">evennia.commands.default.comms.CmdChannel</a>)
|
||
sits in the <code class="docutils literal notranslate"><span class="pre">Account</span></code> <a class="reference internal" href="Command-Sets.html"><span class="doc">command set</span></a>. It is set up such that it will
|
||
always operate on <code class="docutils literal notranslate"><span class="pre">Accounts</span></code>, even if you were to add it to the
|
||
<code class="docutils literal notranslate"><span class="pre">CharacterCmdSet</span></code>.</p>
|
||
<p>It’s a one-line change to make this command accept non-account callers. But for
|
||
convenience we provide a version for Characters/Objects. Just import
|
||
<a class="reference external" href="../api/evennia.commands.default.comms.CmdObjectChannel.html">evennia.commands.default.comms.CmdObjectChannel</a>
|
||
and inherit from that instead.</p>
|
||
</section>
|
||
<section id="customizing-channel-output-and-behavior">
|
||
<h2>Customizing channel output and behavior<a class="headerlink" href="#customizing-channel-output-and-behavior" title="Permalink to this headline">¶</a></h2>
|
||
<p>When distributing a message, the channel will call a series of hooks on itself
|
||
and (more importantly) on each recipient. So you can customize things a lot by
|
||
just modifying hooks on your normal Object/Account typeclasses.</p>
|
||
<p>Internally, the message is sent with
|
||
<code class="docutils literal notranslate"><span class="pre">channel.msg(message,</span> <span class="pre">senders=sender,</span> <span class="pre">bypass_mute=False,</span> <span class="pre">**kwargs)</span></code>, where
|
||
<code class="docutils literal notranslate"><span class="pre">bypass_mute=True</span></code> means the message ignores muting (good for alerts or if you
|
||
delete the channel etc) and <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> are any extra info you may want to pass
|
||
to the hooks. The <code class="docutils literal notranslate"><span class="pre">senders</span></code> (it’s always only one in the default implementation
|
||
but could in principle be multiple) and <code class="docutils literal notranslate"><span class="pre">bypass_mute</span></code> are part of the <code class="docutils literal notranslate"><span class="pre">kwargs</span></code>
|
||
below:</p>
|
||
<ol class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">channel.at_pre_msg(message,</span> <span class="pre">**kwargs)</span></code></p></li>
|
||
<li><p>For each recipient:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">message</span> <span class="pre">=</span> <span class="pre">recipient.at_pre_channel_msg(message,</span> <span class="pre">channel,</span> <span class="pre">**kwargs)</span></code> -
|
||
allows for the message to be tweaked per-receiver (for example coloring it depending
|
||
on the users’ preferences). If this method returns <code class="docutils literal notranslate"><span class="pre">False/None</span></code>, that
|
||
recipient is skipped.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">recipient.channel_msg(message,</span> <span class="pre">channel,</span> <span class="pre">**kwargs)</span></code> - actually sends to recipient.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">recipient.at_post_channel_msg(message,</span> <span class="pre">channel,</span> <span class="pre">**kwargs)</span></code> - any post-receive effects.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">channel.at_post_channel_msg(message,</span> <span class="pre">**kwargs)</span></code></p></li>
|
||
</ol>
|
||
<p>Note that <code class="docutils literal notranslate"><span class="pre">Accounts</span></code> and <code class="docutils literal notranslate"><span class="pre">Objects</span></code> both have their have separate sets of hooks.
|
||
So make sure you modify the set actually used by your subcribers (or both).
|
||
Default channels all use <code class="docutils literal notranslate"><span class="pre">Account</span></code> subscribers.</p>
|
||
</section>
|
||
<section id="channels-in-code">
|
||
<h2>Channels in code<a class="headerlink" href="#channels-in-code" title="Permalink to this headline">¶</a></h2>
|
||
<p>For most common changes, the default channel, the recipient hooks and possibly
|
||
overriding the <code class="docutils literal notranslate"><span class="pre">channel</span></code> command will get you very far. But you can also tweak
|
||
channels themselves.</p>
|
||
<p>Channels are <a class="reference internal" href="Typeclasses.html"><span class="doc">Typeclassed</span></a> entities. This means they are
|
||
persistent in the database, can have <a class="reference internal" href="Attributes.html"><span class="doc">attributes</span></a> and <a class="reference internal" href="Tags.html"><span class="doc">Tags</span></a>
|
||
and can be easily extended.</p>
|
||
<p>To change which channel typeclass Evennia uses for default commands, change
|
||
<code class="docutils literal notranslate"><span class="pre">settings.BASE_CHANNEL_TYPECLASS</span></code>. The base command class is
|
||
<a class="reference external" href="api:evennia.comms.comms.DefaultChannel"><code class="docutils literal notranslate"><span class="pre">evennia.comms.comms.DefaultChannel</span></code></a>.
|
||
There is an empty child class in <code class="docutils literal notranslate"><span class="pre">mygame/typeclasses/channels.py</span></code>, same
|
||
as for other typelass-bases.</p>
|
||
<p>In code you create a new channel with <code class="docutils literal notranslate"><span class="pre">evennia.create_channel</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">Channel.create</span></code>:</p>
|
||
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
|
||
<span class="normal"> 2</span>
|
||
<span class="normal"> 3</span>
|
||
<span class="normal"> 4</span>
|
||
<span class="normal"> 5</span>
|
||
<span class="normal"> 6</span>
|
||
<span class="normal"> 7</span>
|
||
<span class="normal"> 8</span>
|
||
<span class="normal"> 9</span>
|
||
<span class="normal">10</span>
|
||
<span class="normal">11</span>
|
||
<span class="normal">12</span>
|
||
<span class="normal">13</span>
|
||
<span class="normal">14</span>
|
||
<span class="normal">15</span>
|
||
<span class="normal">16</span>
|
||
<span class="normal">17</span>
|
||
<span class="normal">18</span>
|
||
<span class="normal">19</span>
|
||
<span class="normal">20</span>
|
||
<span class="normal">21</span>
|
||
<span class="normal">22</span>
|
||
<span class="normal">23</span>
|
||
<span class="normal">24</span>
|
||
<span class="normal">25</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">create_channel</span><span class="p">,</span> <span class="n">search_object</span>
|
||
<span class="kn">from</span> <span class="nn">typeclasses.channels</span> <span class="kn">import</span> <span class="n">Channel</span>
|
||
|
||
<span class="n">channel</span> <span class="o">=</span> <span class="n">create_channel</span><span class="p">(</span><span class="s2">"my channel"</span><span class="p">,</span> <span class="n">aliases</span><span class="o">=</span><span class="p">[</span><span class="s2">"mychan"</span><span class="p">],</span> <span class="n">locks</span><span class="o">=...</span><span class="p">,</span> <span class="n">typeclass</span><span class="o">=...</span><span class="p">)</span>
|
||
<span class="c1"># alternative</span>
|
||
<span class="n">channel</span> <span class="o">=</span> <span class="n">Channel</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="s2">"my channel"</span><span class="p">,</span> <span class="n">aliases</span><span class="o">=</span><span class="p">[</span><span class="s2">"mychan"</span><span class="p">],</span> <span class="n">locks</span><span class="o">=...</span><span class="p">)</span>
|
||
|
||
<span class="c1"># connect to it</span>
|
||
<span class="n">me</span> <span class="o">=</span> <span class="n">search_object</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s2">"Foo"</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
|
||
<span class="n">channel</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">me</span><span class="p">)</span>
|
||
|
||
<span class="c1"># send to it (this will trigger the channel_msg hooks described earlier)</span>
|
||
<span class="n">channel</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="s2">"Hello world!"</span><span class="p">,</span> <span class="n">senders</span><span class="o">=</span><span class="n">me</span><span class="p">)</span>
|
||
|
||
<span class="c1"># view subscriptions (the SubscriptionHandler handles all subs under the hood)</span>
|
||
<span class="n">channel</span><span class="o">.</span><span class="n">subscriptions</span><span class="o">.</span><span class="n">has</span><span class="p">(</span><span class="n">me</span><span class="p">)</span> <span class="c1"># check we subbed</span>
|
||
<span class="n">channel</span><span class="o">.</span><span class="n">subscriptions</span><span class="o">.</span><span class="n">all</span><span class="p">()</span> <span class="c1"># get all subs</span>
|
||
<span class="n">channel</span><span class="o">.</span><span class="n">subscriptions</span><span class="o">.</span><span class="n">online</span><span class="p">()</span> <span class="c1"># get only subs currently online</span>
|
||
<span class="n">channel</span><span class="o">.</span><span class="n">subscriptions</span><span class="o">.</span><span class="n">clear</span><span class="p">()</span> <span class="c1"># unsub all</span>
|
||
|
||
<span class="c1"># leave channel</span>
|
||
<span class="n">channel</span><span class="o">.</span><span class="n">disconnect</span><span class="p">(</span><span class="n">me</span><span class="p">)</span>
|
||
|
||
<span class="c1"># permanently delete channel (will unsub everyone)</span>
|
||
<span class="n">channel</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span>
|
||
</pre></div>
|
||
</td></tr></table></div>
|
||
<p>The Channel’s <code class="docutils literal notranslate"><span class="pre">.connect</span></code> method will accept both <code class="docutils literal notranslate"><span class="pre">Account</span></code> and <code class="docutils literal notranslate"><span class="pre">Object</span></code> subscribers
|
||
and will handle them transparently.</p>
|
||
<p>The channel has many more hooks, both hooks shared with all typeclasses as well
|
||
as special ones related to muting/banning etc. See the channel class for
|
||
details.</p>
|
||
</section>
|
||
<section id="channel-logging">
|
||
<h2>Channel logging<a class="headerlink" href="#channel-logging" title="Permalink to this headline">¶</a></h2>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 0.7: </span>Channels changed from using Msg to TmpMsg and optional log files.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 1.0: </span>Channels stopped supporting Msg and TmpMsg, using only log files.</p>
|
||
</div>
|
||
<p>The channel messages are not stored in the database. A channel is instead
|
||
always logged to a regular text log-file
|
||
<code class="docutils literal notranslate"><span class="pre">mygame/server/logs/channel_<channelname>.log</span></code>. This is where <code class="docutils literal notranslate"><span class="pre">channels/history</span> <span class="pre">channelname</span></code>
|
||
gets its data from. A channel’s log will rotate when it grows too big, which
|
||
thus also automatically limits the max amount of history a user can view with
|
||
<code class="docutils literal notranslate"><span class="pre">/history</span></code>.</p>
|
||
<p>The log file name is set on the channel class as the <code class="docutils literal notranslate"><span class="pre">log_file</span></code> property. This
|
||
is a string that takes the formatting token <code class="docutils literal notranslate"><span class="pre">{channelname}</span></code> to be replaced with
|
||
the (lower-case) name of the channel. By default the log is written to in the
|
||
channel’s <code class="docutils literal notranslate"><span class="pre">at_post_channel_msg</span></code> method.</p>
|
||
<section id="properties-on-channels">
|
||
<h3>Properties on Channels<a class="headerlink" href="#properties-on-channels" title="Permalink to this headline">¶</a></h3>
|
||
<p>Channels have all the standard properties of a Typeclassed entity (<code class="docutils literal notranslate"><span class="pre">key</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">aliases</span></code>, <code class="docutils literal notranslate"><span class="pre">attributes</span></code>, <code class="docutils literal notranslate"><span class="pre">tags</span></code>, <code class="docutils literal notranslate"><span class="pre">locks</span></code> etc). This is not an exhaustive list;
|
||
see the <a class="reference external" href="../api/evennia.comms.comms.DefaultChannel.html">Channel api docs</a> for details.</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">send_to_online_only</span></code> - this class boolean defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code> and is a
|
||
sensible optimization since people offline people will not see the message anyway.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">log_file</span></code> - this is a string that determines the name of the channel log file. Default
|
||
is <code class="docutils literal notranslate"><span class="pre">"channel_{channelname}.log"</span></code>. The log file will appear in <code class="docutils literal notranslate"><span class="pre">settings.LOG_DIR</span></code> (usually
|
||
<code class="docutils literal notranslate"><span class="pre">mygame/server/logs/</span></code>). You should usually not change this.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">channel_prefix_string</span></code> - this property is a string to easily change how
|
||
the channel is prefixed. It takes the <code class="docutils literal notranslate"><span class="pre">channelname</span></code> format key. Default is <code class="docutils literal notranslate"><span class="pre">"[{channelname}]</span> <span class="pre">"</span></code>
|
||
and produces output like `[public] …``.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">subscriptions</span></code> - this is the <a class="reference external" href="../api/evennia.comms.comms.html#SubscriptionHandler">SubscriptionHandler</a>, which
|
||
has methods <code class="docutils literal notranslate"><span class="pre">has</span></code>, <code class="docutils literal notranslate"><span class="pre">add</span></code>, <code class="docutils literal notranslate"><span class="pre">remove</span></code>, <code class="docutils literal notranslate"><span class="pre">all</span></code>, <code class="docutils literal notranslate"><span class="pre">clear</span></code> and also <code class="docutils literal notranslate"><span class="pre">online</span></code> (to get
|
||
only actually online channel-members).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">wholist</span></code>, <code class="docutils literal notranslate"><span class="pre">mutelist</span></code>, <code class="docutils literal notranslate"><span class="pre">banlist</span></code> are properties that return a list of subscribers,
|
||
as well as who are currently muted or banned.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">channel_msg_nick_pattern</span></code> - this is a regex pattern for performing the in-place nick
|
||
replacement (detect that <code class="docutils literal notranslate"><span class="pre">channelalias</span> <span class="pre"><msg</span></code> means that you want to send a message to a channel).
|
||
This pattern accepts an <code class="docutils literal notranslate"><span class="pre">{alias}</span></code> formatting marker. Don’t mess with this unless you really
|
||
want to change how channels work.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">channel_msg_nick_replacement</span></code> - this is a string on the [nick replacement</p></li>
|
||
<li><p>form](Nicks). It accepts the <code class="docutils literal notranslate"><span class="pre">{channelname}</span></code> formatting tag. This is strongly tied to the
|
||
<code class="docutils literal notranslate"><span class="pre">channel</span></code> command and is by default <code class="docutils literal notranslate"><span class="pre">channel</span> <span class="pre">{channelname}</span> <span class="pre">=</span> <span class="pre">$1</span></code>.</p></li>
|
||
</ul>
|
||
<p>Notable <code class="docutils literal notranslate"><span class="pre">Channel</span></code> hooks:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">at_pre_channel_msg(message,</span> <span class="pre">**kwargs)</span></code> - called before sending a message, to
|
||
modify it. Not used by default.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">msg(message,</span> <span class="pre">senders=...,</span> <span class="pre">bypass_mute=False,</span> <span class="pre">**kwargs)</span></code> - send the message onto
|
||
the channel. The <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> are passed on into the other call hooks (also on the recipient).</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">at_post_channel_msg(message,</span> <span class="pre">**kwargs)</span></code> - by default this is used to store the message
|
||
to the log file.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">channel_prefix(message)</span></code> - this is called to allow the channel to prefix. This is called
|
||
by the object/account when they build the message, so if wanting something else one can
|
||
also just remove that call.</p></li>
|
||
<li><p>every channel message. By default it just returns <code class="docutils literal notranslate"><span class="pre">channel_prefix_string</span></code>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">has_connection(subscriber)</span></code> - shortcut to check if an entity subscribes to
|
||
this channel.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">mute/unmute(subscriber)</span></code> - this mutes the channel for this user.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">ban/unban(subscriber)</span></code> - adds/remove user from banlist.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">connect/disconnect(subscriber)</span></code> - adds/removes a subscriber.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">add_user_channel_alias(user,</span> <span class="pre">alias,</span> <span class="pre">**kwargs)</span></code> - sets up a user-nick for this channel. This is
|
||
what maps e.g. <code class="docutils literal notranslate"><span class="pre">alias</span> <span class="pre"><msg></span></code> to <code class="docutils literal notranslate"><span class="pre">channel</span> <span class="pre">channelname</span> <span class="pre">=</span> <span class="pre"><msg></span></code>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">remove_user_channel_alias(user,</span> <span class="pre">alias,</span> <span class="pre">**kwargs)</span></code> - remove an alias. Note that this is
|
||
a class-method that will happily remove found channel-aliases from the user linked to <em>any</em>
|
||
channel, not only from the channel the method is called on.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">pre_join_channel(subscriber)</span></code> - if this returns <code class="docutils literal notranslate"><span class="pre">False</span></code>, connection will be refused.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">post_join_channel(subscriber)</span></code> - by default this sets up a users’s channel-nicks/aliases.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">pre_leave_channel(subscriber)</span></code> - if this returns <code class="docutils literal notranslate"><span class="pre">False</span></code>, the user is not allowed to leave.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">post_leave_channel(subscriber)</span></code> - this will clean up any channel aliases/nicks of the user.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">delete</span></code> the standard typeclass-delete mechanism will also automatically un-subscribe all
|
||
subscribers (and thus wipe all their aliases).</p></li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<p class="logo"><a href="../index.html">
|
||
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
|
||
</a></p>
|
||
<div id="searchbox" style="display: none" role="search">
|
||
<h3 id="searchlabel">Quick search</h3>
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="../search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</div>
|
||
<script>$('#searchbox').show(0);</script>
|
||
<p><h3><a href="../index.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Channels</a><ul>
|
||
<li><a class="reference internal" href="#using-channels-in-game">Using channels in-game</a><ul>
|
||
<li><a class="reference internal" href="#viewing-and-joining-channels">Viewing and joining channels</a></li>
|
||
<li><a class="reference internal" href="#chat-on-channels">Chat on channels</a></li>
|
||
<li><a class="reference internal" href="#channel-administration">Channel administration</a><ul>
|
||
<li><a class="reference internal" href="#restricting-channel-administration">Restricting channel administration</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#allowing-characters-to-use-channels">Allowing Characters to use Channels</a></li>
|
||
<li><a class="reference internal" href="#customizing-channel-output-and-behavior">Customizing channel output and behavior</a></li>
|
||
<li><a class="reference internal" href="#channels-in-code">Channels in code</a></li>
|
||
<li><a class="reference internal" href="#channel-logging">Channel logging</a><ul>
|
||
<li><a class="reference internal" href="#properties-on-channels">Properties on Channels</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<div role="note" aria-label="source link">
|
||
<!--h3>This Page</h3-->
|
||
<ul class="this-page-menu">
|
||
<li><a href="../_sources/Components/Channels.md.txt"
|
||
rel="nofollow">Show Page Source</a></li>
|
||
</ul>
|
||
</div><h3>Links</h3>
|
||
<ul>
|
||
<li><a href="https://www.evennia.com">Home page</a> </li>
|
||
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
|
||
<li><a href="http://games.evennia.com">Game Index</a> </li>
|
||
<li>
|
||
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
|
||
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
|
||
<a href="https://evennia.blogspot.com/">Blog</a>
|
||
</li>
|
||
</ul>
|
||
<h3>Versions</h3>
|
||
<ul>
|
||
<li><a href="Channels.html">1.0-dev (develop branch)</a></li>
|
||
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Channels</a></li>
|
||
</ul>
|
||
<div class="develop">develop branch</div>
|
||
</div>
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2020, The Evennia developer community.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
|
||
</div>
|
||
</body>
|
||
</html> |