Annikka/evennia
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Update and clean up docs

Browse source
This commit is contained in:
Griatch 2022-11-20 01:36:35 +01:00
parent b84fab9300
commit 615e828abf
9 changed files with 380 additions and 478 deletions
Download patch file Download diff file Expand all files Collapse all files

153
docs/source/Concepts/Colors.md
View file

@ -16,26 +16,52 @@ So a good rule of thumb is to use colour to enhance your game but don't *rely* o
critical information. If you are coding the game, you can add functionality to let users disable
colours as they please, as described [here](../Howtos/Manually-Configuring-Color.md).
To see which colours your client support, use the default `@color` 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 `ANSI`-colour codes in `evennia/utils/ansi.py`.
Evennia supports two color standards:
- `ANSI` - 16 foreground colors + 8 background colors. Widely supported.
- `Xterm256` - 128 RGB colors, 32 greyscales. Not always supported in old clients.
To see which colours your client support, use the default `color` command. This will list all
available colours for ANSI and Xterm256 along with the codes you use for them. The
central ansi/xterm256 parser is located in [evennia/utils/ansi.py](api:evennia.utils.ansi).
## ANSI colours
Evennia supports the `ANSI` 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 **r**ed, **g**reen,
**y**ellow, **b**lue, **m**agenta, **c**yan, **w**hite and black. They are abbreviated by their
first letter except for black which is abbreviated with the letter **x**. 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 [Xterm256](#xterm256-colours) extension behind the scenes to offer
them anyway).
Evennia supports the `ANSI` standard for text. This is by far the most supported MUD-color standard, available in all but the most ancient mud clients.
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.
For the webclient, Evennia will translate the codes to CSS tags.
| Tag | Effect |
| ---- | ----- |
| \|n | end all color formatting, including background colors. |
|\|r | bright red foreground color |
|\|g | bright green foreground color |
|\|y | bright yellow foreground color |
|\|b | bright blue foreground color |
|\|m | bright magentaforeground color |
|\|c | bright cyan foreground color |
|\|w | bright white foreground color |
|\|x | bright black (dark grey) foreground color |
|\|R | normal red foreground color |
|\|G | normal green foreground color |
|\|Y | normal yellow foreground color |
|\|B | normal blue foreground color |
|\|M | normal magentaforeground color |
|\|C | normal cyan foreground color |
|\|W | normal white (light grey) foreground color |
|\|X | normal black foreground color |
| \|\[# | background colours, e.g. \|\[c for bright cyan background and \|\[C a normal cyan background. |
| \|!# | foreground color that inherits brightness from previous tags. Always uppcase, like \|!R |
| \|h | make any following foreground ANSI colors bright (no effect on Xterm colors). Use with \|!#. Technically, \|h\|G == \|g. |
| \|H | negates the effects of \|h, return foreground to normal (no effect on Xterm colors) |
| \|/ | line break. Use instead of Python \\n when adding strings from in-game. |
| \|- | tab character when adding strings in-game. Can vay per client, so usually better with spaces. |
| \|_ | a space. Only needed to avoid auto-cropping at the end of a in-game input |
| \|* | invert the current text/background colours, like a marker. See note below. |
Here is an example of the tags in action:
@ -44,35 +70,11 @@ Here is an example of the tags in action:
|[rThis text has red background.|n This is normal text.
|b|[yThis is bright blue text on yellow background.|n This is normal text.
- `|n` - this tag will turn off all color formatting, including background colors.
- `|#`- markup marks the start of foreground color. The case defines if the text is "bright" or
"normal". So `|g` is a bright green and `|G` is "normal" (darker) green.
- `|[#` is used to add a background colour to the text. The case again specifies if it is "bright"
or "normal", so `|[c` starts a bright cyan background and `|[C` a darker cyan background.
- `|!#` 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
`|!R` for red. The difference between e.g. `|!R` and `|R` is that
`|!R` will "inherit" the brightness setting from previously set color tags, whereas `|R` will
always reset to the normal-intensity red. The `|#` format contains an implicit `|h`/`|H` tag in it:
disabling highlighting when switching to a normal color, and enabling it for bright ones. So `|btest
|!Rtest2` will result in a bright red `test2` since the brightness setting from `|b` "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 `|!` style tags.
- `|h` is used to make any following foreground ANSI colors bright (it has no effect on Xterm
colors). This is only relevant to use with `|!` type tags and will be valid until the next `|n`,
`|H` or normal (upper-case) `|#` tag. This tag will never affect background colors, those have to be
set bright/normal explicitly. Technically, `|h|!G` is identical to `|g`.
- `|H` negates the effects `|h` and returns all ANSI foreground colors (`|!` and `|` types) to
'normal' intensity. It has no effect on background and Xterm colors.
Note: The ANSI standard does not actually support bright backgrounds like `|[r` - the standard
only supports "normal" intensity backgrounds. To get around this Evennia implements these as [Xterm256 colours](#xterm256-colours) 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.
> Note: The ANSI standard does not actually support bright backgrounds like `|[r` - the standard
only supports "normal" intensity backgrounds. To get around this Evennia instead implements these
as [Xterm256 colours](#xterm256-colours) 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.
If you want to display an ANSI marker as output text (without having any effect), you need to escape
it by preceding its `|` with another `|`:
If you want to display an ANSI marker as output text (without having any effect), you need to escape it by preceding its `|` with another `|`:
```
say The ||r ANSI marker changes text color to bright red.
@ -83,22 +85,12 @@ ansi art that uses `|` with a letter directly following it.
Use the command
@color ansi
color ansi
to get a list of all supported ANSI colours and the tags used to produce them.
A few additional ANSI codes are supported:
- `|/` A line break. You cannot put the normal Python `\n` line breaks in text entered inside the
game (Evennia will filter this for security reasons). This is what you use instead: use the `|/`
marker to format text with line breaks from the game command line.
- `` This will translate into a `TAB` 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.
- `|_` This is a space. You can usually use the normal space character, but if the space is *at the
end of the line*, Evennia will likely crop it. This tag will not be cropped but always result in a
space.
- `|*` This will invert the current text/background colours. Can be useful to mark things (but see
below).
### Caveats of `|*`
@ -140,44 +132,45 @@ manually instead.
### Xterm256 Colours
The _Xterm256_ standard is a colour scheme that supports 256 colours for text and/or background.
The _Xterm256_ standard is a colour scheme that supports 256 colours for text and/or background. It can be combined freely with ANSI colors (above), but some ANSI tags don't affect Xterm256 tags.
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.
|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.
| Tag | Effect |
| ---- | ---- |
| \|### | foreground RGB (red/green/blue), each from 0 to 5. |
| \|\[### | background RGB |
| \|=# | a-z foreground greyscale, where `a` is black and `z` is white. |
| \|\[=#| a-z background greyscale
- `|###` - markup consists of three digits, each an integer from 0 to 5. The three digits describe
the amount of **r**ed, **g**reen and **b**lue (RGB) components used in the colour. So `|500` means
maximum red and none of the other colours - the result is a bright red. `|520` 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.
- `|[###` - this works the same way but produces a coloured background.
- `|=#` - markup produces the xterm256 gray scale tones, where `#` is a letter from `a` (black) to
`z` (white). This offers many more nuances of gray than the normal `|###` markup (which only has
four gray tones between solid black and white (`|000`, `|111`, `|222`, `|333` and `|444`)).
- `|[=#` - this works in the same way but produces background gray scale tones.
Some examples:
| Tag | Effect |
| ---- | ---- |
| \|500 | bright red |
| \|050 | bright green |
| \|005 | bright blue |
| \|520 | red + a little green = orange |
|\|555 | pure white foreground |
|\|230 | olive green foreground |
|\|\[300 | text with a dark red background |
|\|005\|\[054 | dark blue text on a bright cyan background |
|\|=a | greyscale foreground, equal to black |
| \|=m | greyscale foreground, midway between white and black.
| \|=z | greyscale foreground, equal to white |
| \|\[=m | greyscale background |
Xterm256 don't use bright/normal intensity like ANSI does; intensity is just varied by increasing/decreasing all RGB values by the same amount.
If you have a client that supports Xterm256, you can use
@color xterm256
color xterm256
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 `@options` 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.
into a few blocks of colors, it means Xterm256 is not supported and ANSI are used as a replacement. You can use the `options` 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.
## More reading
There is an [Understanding Color Tags](../Howtos/Understanding-Color-Tags.md) tutorial which expands on the
use of ANSI color tags and the pitfalls of mixing ANSI and Xterms256 color tags in the same context.
There is an [Understanding Color Tags](../Howtos/Understanding-Color-Tags.md) tutorial which expands on the use of ANSI color tags and the pitfalls of mixing ANSI and Xterms256 color tags in the same context.