Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-19 14:26:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/1.0-dev/Concepts/Colors.html
Evennia docbuilder action 3165f49b4c Updated HTML docs
2022-02-06 18:34:09 +00:00

318 lines
No EOL
25 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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>Colors &#8212; 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" />
<link rel="next" title="Web Features" href="Web-Features.html" />
<link rel="prev" title="Clickable links" href="Clickable-Links.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="right" >
<a href="Web-Features.html" title="Web Features"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Clickable-Links.html" title="Clickable links"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Concepts-Overview.html" accesskey="U">Core Concepts</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Colors</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 class="tex2jax_ignore mathjax_ignore" id="colors">
<h1>Colors<a class="headerlink" href="#colors" title="Permalink to this headline"></a></h1>
<p><em>Note that the Documentation does not display colour the way it would look on the screen.</em></p>
<p>Color can be a very useful tool for your game. It can be used to increase readability and make your
game more appealing visually.</p>
<p>Remember however that, with the exception of the webclient, you generally don’t control the client
used to connect to the game. There is, for example, one special tag meaning “yellow”. But exactly
<em>which</em> hue of yellow is actually displayed on the user’s screen depends on the settings of their
particular mud client. They could even swap the colours around or turn them off altogether if so
desired. Some clients don’t even support color - text games are also played with special reading
equipment by people who are blind or have otherwise diminished eyesight.</p>
<p>So a good rule of thumb is to use colour to enhance your game but don’t <em>rely</em> on it to display
critical information. If you are coding the game, you can add functionality to let users disable
colours as they please, as described <a class="reference internal" href="../Howtos/Manually-Configuring-Color.html"><span class="doc std std-doc">here</span></a>.</p>
<p>To see which colours your client support, use the default <code class="docutils literal notranslate"><span class="pre">&#64;color</span></code> command. This will list all
available colours for ANSI and Xterm256 along with the codes you use for them. You can find a list
of all the parsed <code class="docutils literal notranslate"><span class="pre">ANSI</span></code>-colour codes in <code class="docutils literal notranslate"><span class="pre">evennia/utils/ansi.py</span></code>.</p>
<section id="ansi-colours">
<h2>ANSI colours<a class="headerlink" href="#ansi-colours" title="Permalink to this headline"></a></h2>
<p>Evennia supports the <code class="docutils literal notranslate"><span class="pre">ANSI</span></code> standard for text. This is by far the most supported MUD-color standard,
available in all but the most ancient mud clients. The ANSI colours are <strong>r</strong>ed, <strong>g</strong>reen,
<strong>y</strong>ellow, <strong>b</strong>lue, <strong>m</strong>agenta, <strong>c</strong>yan, <strong>w</strong>hite and black. They are abbreviated by their
first letter except for black which is abbreviated with the letter <strong>x</strong>. In ANSI there are “bright”
and “normal” (darker) versions of each color, adding up to a total of 16 colours to use for
foreground text. There are also 8 “background” colours. These have no bright alternative in ANSI
(but Evennia uses the <a class="reference internal" href="#xterm256-colours"><span class="std std-doc">Xterm256</span></a> extension behind the scenes to offer
them anyway).</p>
<p>To colour your text you put special tags in it. Evennia will parse these and convert them to the
correct markup for the client used. If the user’s client/console/display supports ANSI colour, they
will see the text in the specified colour, otherwise the tags will be stripped (uncolored text).
This works also for non-terminal clients, such as the webclient. For the webclient, Evennia will
translate the codes to HTML RGB colors.</p>
<p>Here is an example of the tags in action:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> |rThis text is bright red.|n This is normal text.
|RThis is a dark red text.|n This is normal text.
|[rThis text has red background.|n This is normal text.
|b|[yThis is bright blue text on yellow background.|n This is normal text.
</pre></div>
</div>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">|n</span></code> - this tag will turn off all color formatting, including background colors.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|#</span></code>- markup marks the start of foreground color. The case defines if the text is “bright” or
“normal”. So <code class="docutils literal notranslate"><span class="pre">|g</span></code> is a bright green and <code class="docutils literal notranslate"><span class="pre">|G</span></code> is “normal” (darker) green.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|[#</span></code> is used to add a background colour to the text. The case again specifies if it is “bright”
or “normal”, so <code class="docutils literal notranslate"><span class="pre">|[c</span></code> starts a bright cyan background and <code class="docutils literal notranslate"><span class="pre">|[C</span></code> a darker cyan background.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|!#</span></code> is used to add foreground color without any enforced brightness/normal information.
These are normal-intensity and are thus always given as uppercase, such as
<code class="docutils literal notranslate"><span class="pre">|!R</span></code> for red. The difference between e.g. <code class="docutils literal notranslate"><span class="pre">|!R</span></code> and <code class="docutils literal notranslate"><span class="pre">|R</span></code> is that
<code class="docutils literal notranslate"><span class="pre">|!R</span></code> will “inherit” the brightness setting from previously set color tags, whereas <code class="docutils literal notranslate"><span class="pre">|R</span></code> will
always reset to the normal-intensity red. The <code class="docutils literal notranslate"><span class="pre">|#</span></code> format contains an implicit <code class="docutils literal notranslate"><span class="pre">|h</span></code>/<code class="docutils literal notranslate"><span class="pre">|H</span></code> tag in it:
disabling highlighting when switching to a normal color, and enabling it for bright ones. So <code class="docutils literal notranslate"><span class="pre">|btest</span> <span class="pre">|!Rtest2</span></code> will result in a bright red <code class="docutils literal notranslate"><span class="pre">test2</span></code> since the brightness setting from <code class="docutils literal notranslate"><span class="pre">|b</span></code> “bleeds over”.
You could use this to for example quickly switch the intensity of a multitude of color tags. There
is no background-color equivalent to <code class="docutils literal notranslate"><span class="pre">|!</span></code> style tags.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|h</span></code> is used to make any following foreground ANSI colors bright (it has no effect on Xterm
colors). This is only relevant to use with <code class="docutils literal notranslate"><span class="pre">|!</span></code> type tags and will be valid until the next <code class="docutils literal notranslate"><span class="pre">|n</span></code>,
<code class="docutils literal notranslate"><span class="pre">|H</span></code> or normal (upper-case) <code class="docutils literal notranslate"><span class="pre">|#</span></code> tag. This tag will never affect background colors, those have to be
set bright/normal explicitly. Technically, <code class="docutils literal notranslate"><span class="pre">|h|!G</span></code> is identical to <code class="docutils literal notranslate"><span class="pre">|g</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|H</span></code> negates the effects <code class="docutils literal notranslate"><span class="pre">|h</span></code> and returns all ANSI foreground colors (<code class="docutils literal notranslate"><span class="pre">|!</span></code> and <code class="docutils literal notranslate"><span class="pre">|</span></code> types) to
‘normal’ intensity. It has no effect on background and Xterm colors.</p></li>
</ul>
<blockquote>
<div><p>Note: The ANSI standard does not actually support bright backgrounds like <code class="docutils literal notranslate"><span class="pre">|[r</span></code> - the standard
only supports “normal” intensity backgrounds. To get around this Evennia instead implements these
as <a class="reference internal" href="#xterm256-colours"><span class="std std-doc">Xterm256 colours</span></a> behind the scenes. If the client does not support
Xterm256 the ANSI colors will be used instead and there will be no visible difference between using
upper- and lower-case background tags.</p>
</div></blockquote>
<p>If you want to display an ANSI marker as output text (without having any effect), you need to escape
it by preceding its <code class="docutils literal notranslate"><span class="pre">|</span></code> with another <code class="docutils literal notranslate"><span class="pre">|</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">say</span> <span class="n">The</span> <span class="o">||</span><span class="n">r</span> <span class="n">ANSI</span> <span class="n">marker</span> <span class="n">changes</span> <span class="n">text</span> <span class="n">color</span> <span class="n">to</span> <span class="n">bright</span> <span class="n">red</span><span class="o">.</span>
</pre></div>
</div>
<p>This will output the raw <code class="docutils literal notranslate"><span class="pre">|r</span></code> without any color change. This can also be necessary if you are doing
ansi art that uses <code class="docutils literal notranslate"><span class="pre">|</span></code> with a letter directly following it.</p>
<p>Use the command</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>@color ansi
</pre></div>
</div>
<p>to get a list of all supported ANSI colours and the tags used to produce them.</p>
<p>A few additional ANSI codes are supported:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">|/</span></code> A line break. You cannot put the normal Python <code class="docutils literal notranslate"><span class="pre">\n</span></code> line breaks in text entered inside the
game (Evennia will filter this for security reasons). This is what you use instead: use the <code class="docutils literal notranslate"><span class="pre">|/</span></code>
marker to format text with line breaks from the game command line.</p></li>
<li><p>`` This will translate into a <code class="docutils literal notranslate"><span class="pre">TAB</span></code> character. This will not always show (or show differently) to
the client since it depends on their local settings. It’s often better to use multiple spaces.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|_</span></code> This is a space. You can usually use the normal space character, but if the space is <em>at the
end of the line</em>, Evennia will likely crop it. This tag will not be cropped but always result in a
space.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|*</span></code> This will invert the current text/background colours. Can be useful to mark things (but see
below).</p></li>
</ul>
<section id="caveats-of">
<h3>Caveats of <code class="docutils literal notranslate"><span class="pre">|*</span></code><a class="headerlink" href="#caveats-of" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">|*</span></code> tag (inverse video) is an old ANSI standard and should usually not be used for more than to
mark short snippets of text. If combined with other tags it comes with a series of potentially
confusing behaviors:</p>
<ul>
<li><p>The <code class="docutils literal notranslate"><span class="pre">|*</span></code> tag will only work once in a row:, ie: after using it once it won’t have an effect again
until you declare another tag. This is an example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Normal</span> <span class="n">text</span><span class="p">,</span> <span class="o">|*</span><span class="nb">reversed</span> <span class="n">text</span><span class="o">|*</span><span class="p">,</span> <span class="n">still</span> <span class="nb">reversed</span> <span class="n">text</span><span class="o">.</span>
</pre></div>
</div>
<p>that is, it will not reverse to normal at the second <code class="docutils literal notranslate"><span class="pre">|*</span></code>. You need to reset it manually:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Normal</span> <span class="n">text</span><span class="p">,</span> <span class="o">|*</span><span class="nb">reversed</span> <span class="n">text</span><span class="o">|</span><span class="n">n</span><span class="p">,</span> <span class="n">normal</span> <span class="n">again</span><span class="o">.</span>
</pre></div>
</div>
</li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">|*</span></code> tag does not take “bright” colors into account:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">|</span><span class="n">RNormal</span> <span class="n">red</span><span class="p">,</span> <span class="o">|</span><span class="n">hnow</span> <span class="n">brightened</span><span class="o">.</span> <span class="o">|*</span><span class="n">BG</span> <span class="ow">is</span> <span class="n">normal</span> <span class="n">red</span><span class="o">.</span>
</pre></div>
</div>
</li>
</ul>
<p>So <code class="docutils literal notranslate"><span class="pre">|*</span></code> only considers the ‘true’ foreground color, ignoring any highlighting. Think of the bright
state (<code class="docutils literal notranslate"><span class="pre">|h</span></code>) as something like like <code class="docutils literal notranslate"><span class="pre">&lt;strong&gt;</span></code> in HTML: it modifies the <em>appearance</em> of a normal
foreground color to match its bright counterpart, without changing its normal color.</p>
<ul>
<li><p>Finally, after a <code class="docutils literal notranslate"><span class="pre">|*</span></code>, if the previous background was set to a dark color (via <code class="docutils literal notranslate"><span class="pre">|[</span></code>), <code class="docutils literal notranslate"><span class="pre">|!#</span></code>) will
actually change the background color instead of the foreground:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>|*reversed text |!R now BG is red.
</pre></div>
</div>
</li>
</ul>
<p>For a detailed explanation of these caveats, see the [Understanding Color Tags](Understanding-Color-
Tags) tutorial. But most of the time you might be better off to simply avoid <code class="docutils literal notranslate"><span class="pre">|*</span></code> and mark your text
manually instead.</p>
</section>
<section id="xterm256-colours">
<h3>Xterm256 Colours<a class="headerlink" href="#xterm256-colours" title="Permalink to this headline"></a></h3>
<p>The <em>Xterm256</em> standard is a colour scheme that supports 256 colours for text and/or background.
While this offers many more possibilities than traditional ANSI colours, be wary that too many text
colors will be confusing to the eye. Also, not all clients support Xterm256 - these will instead see
the closest equivalent ANSI color. You can mix Xterm256 tags with ANSI tags as you please.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>|555 This is pure white text.|n This is normal text.
|230 This is olive green text.
|[300 This text has a dark red background.
|005|[054 This is dark blue text on a bright cyan background.
|=a This is a greyscale value, equal to black.
|=m This is a greyscale value, midway between white and black.
|=z This is a greyscale value, equal to white.
|[=m This is a background greyscale value.
</pre></div>
</div>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">|###</span></code> - markup consists of three digits, each an integer from 0 to 5. The three digits describe
the amount of <strong>r</strong>ed, <strong>g</strong>reen and <strong>b</strong>lue (RGB) components used in the colour. So <code class="docutils literal notranslate"><span class="pre">|500</span></code> means
maximum red and none of the other colours - the result is a bright red. <code class="docutils literal notranslate"><span class="pre">|520</span></code> is red with a touch
of green - the result is orange. As opposed to ANSI colors, Xterm256 syntax does not worry about
bright/normal intensity, a brighter (lighter) color is just achieved by upping all RGB values with
the same amount.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|[###</span></code> - this works the same way but produces a coloured background.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|=#</span></code> - markup produces the xterm256 gray scale tones, where <code class="docutils literal notranslate"><span class="pre">#</span></code> is a letter from <code class="docutils literal notranslate"><span class="pre">a</span></code> (black) to
<code class="docutils literal notranslate"><span class="pre">z</span></code> (white). This offers many more nuances of gray than the normal <code class="docutils literal notranslate"><span class="pre">|###</span></code> markup (which only has
four gray tones between solid black and white (<code class="docutils literal notranslate"><span class="pre">|000</span></code>, <code class="docutils literal notranslate"><span class="pre">|111</span></code>, <code class="docutils literal notranslate"><span class="pre">|222</span></code>, <code class="docutils literal notranslate"><span class="pre">|333</span></code> and <code class="docutils literal notranslate"><span class="pre">|444</span></code>)).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">|[=#</span></code> - this works in the same way but produces background gray scale tones.</p></li>
</ul>
<p>If you have a client that supports Xterm256, you can use</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>@color xterm256
</pre></div>
</div>
<p>to get a table of all the 256 colours and the codes that produce them. If the table looks broken up
into a few blocks of colors, it means Xterm256 is not supported and ANSI are used as a replacement.
You can use the <code class="docutils literal notranslate"><span class="pre">&#64;options</span></code> command to see if xterm256 is active for you. This depends on if your
client told Evennia what it supports - if not, and you know what your client supports, you may have
to activate some features manually.</p>
</section>
</section>
<section id="more-reading">
<h2>More reading<a class="headerlink" href="#more-reading" title="Permalink to this headline"></a></h2>
<p>There is an <a class="reference internal" href="../Howtos/Understanding-Color-Tags.html"><span class="doc std std-doc">Understanding Color Tags</span></a> tutorial which expands on the
use of ANSI color tags and the pitfalls of mixing ANSI and Xterms256 color tags in the same context.</p>
</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="#">Colors</a><ul>
<li><a class="reference internal" href="#ansi-colours">ANSI colours</a><ul>
<li><a class="reference internal" href="#caveats-of">Caveats of <code class="docutils literal notranslate"><span class="pre">|*</span></code></a></li>
<li><a class="reference internal" href="#xterm256-colours">Xterm256 Colours</a></li>
</ul>
</li>
<li><a class="reference internal" href="#more-reading">More reading</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Clickable-Links.html"
title="previous chapter">Clickable links</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Web-Features.html"
title="next chapter">Web Features</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Concepts/Colors.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="Colors.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="right" >
<a href="Web-Features.html" title="Web Features"
>next</a> |</li>
<li class="right" >
<a href="Clickable-Links.html" title="Clickable links"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Concepts-Overview.html" >Core Concepts</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Colors</a></li>
</ul>
<div class="develop">develop branch</div>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink