ANSI Color
Overview
ANSI color in TinyMUX allows softcode to produce colored and styled text output. The server works internally with 24-bit color (16,777,216 colors) and remaps to whatever palette the player’s client supports: 16 colors, 256 colors, or full 24-bit via MXP/HTML.
ANSI escape sequences are special byte sequences (beginning with ESC [) that terminals interpret as display instructions rather than printable text. TinyMUX abstracts these sequences so that softcoders never write raw escapes directly. Instead, color is expressed through the ansi() function, percent-substitution codes, or HTML-style color notation.
The ansi() Function
ansi(<codes>, <string>[, <codes>, <string>[, ...]])
Applies color and style codes to <string>, then appends a “return to normal” sequence. Multiple code/string pairs can be given in a single call.
Color Codes
Lowercase letters set the foreground; uppercase letters set the background.
| Code | Foreground | Code | Background |
|---|---|---|---|
| x | black | X | black |
| r | red | R | red |
| g | green | G | green |
| y | yellow | Y | yellow |
| b | blue | B | blue |
| m | magenta | M | magenta |
| c | cyan | C | cyan |
| w | white | W | white |
Style Codes
| Code | Effect |
|---|---|
| h | highlight (bold/intense) |
| u | underline |
| f | flash (blink) |
| i | inverse |
| n | normal (reset) |
HTML and RGB Color Notation
For finer control, ansi() accepts HTML hex codes and decimal RGB vectors:
ansi(<#FF8040>/<#800080>, Test)—Orange text on dark purple background
ansi(<255 128 64>, Test)—Same orange as a decimal RGB vector
The / prefix marks a color as background. These extended colors require the COLOR256 flag (or HTML flag for full 24-bit).
ANSI Percent Substitutions
The %x and %X substitutions are a more efficient alternative to ansi() for inline color. For example, ansi(rBf, Color!) is equivalent to:
%xr%xB%xfColor!%xn
The %xn reset at the end is understood and therefore optional—TinyMUX appends it automatically at message boundaries.
The code following %x can take three forms:
- Single letter:
%xb,%xR,%xh,%xn, etc. - HTML hex:
%x<#RRGGBB>(e.g.,%x<#FF8040>) - Decimal RGB:
%x<R G B>(e.g.,%x<128 0 255>)
For single-letter codes, case determines foreground vs. background. For HTML/RGB forms, %x sets foreground and %X sets background.
The older %c / %C forms are equivalent to %x / %X, but %x / %X are preferred. The translate() function always produces %x / %X sequences.
Player Flags
ANSI Flag
The ANSI flag (flag letter X) must be set on a player to receive any color at all. Without it, TinyMUX strips all color and style attributes from outgoing text.
@set me=ANSI
COLOR256 Flag
When set on a player, COLOR256 enables the 256-color xterm palette. If ANSI is set but COLOR256 is not, the server remaps 256-color requests down to the nearest 16-color equivalent using the standard xterm palette values.
@set me=COLOR256
The colordepth() function returns the effective color depth for a player or port: 0 (none), 4 (16-color ANSI), 8 (256-color), or 24 (MXP/HTML).
NOBLEED Flag
The NOBLEED flag (flag letter -) causes TinyMUX to append an extra ANSI white reset after the normal reset code. This prevents color “bleed”—when a color from one message visually extends into subsequent text on some terminals. Use this flag only when necessary, as it adds overhead to every line of output.
@set me=NOBLEED
Removing Color: stripansi()
stripansi(<string>)
Returns <string> with all ANSI codes removed. This is essential when you need the plain-text content for length calculations, comparisons, or storage.
Color and String Functions
ANSI-aware string functions such as ljust(), rjust(), center(), and wrap() handle color codes correctly—they count only visible characters for padding and alignment, not the invisible escape sequences. This means colored text can be padded and wrapped without corrupting the layout.
When using strlen(), ANSI codes are excluded from the count. Use strmem() if you need the raw byte length including escape sequences.
accent() for Diacritical Marks
accent(<string>, <template>)
The accent() function produces Unicode characters with diacritical marks. Both arguments must have the same number of characters. Each character in <template> selects an accent to apply to the corresponding character in <string>:
| Template | Accent | Example Characters |
|---|---|---|
| ' | acute | A, C, E, I, N, O, S, U, Z and lowercase |
| ` | grave | A,E,I,O,U and lowercase |
| : | umlaut | A, E, I, O, U, Y and lowercase |
| ^ | circumflex | A, C, E, G, H, I, J, O, S, U, W, Y and lowercase |
| ~ | tilde | A, I, N, O, U and lowercase |
| , | cedilla | A, C, E, G, K, L, N, S, T, U and lowercase |
| - | macron | A, D, E, I, O, U and lowercase |
| v | caron | C, D, E, L, N, R, S, T, Z and lowercase |
Examples:
accent(Aule, ===:) -- produces "Aule" with diaeresis on the 'e'
accent(The Nina was a ship, The Ni~a was a ship) -- n with tilde
Practical Examples
Colored name tag:
&FORMAT_NAME me=[ansi(hc,[name(%0)])]
Status bar with background color:
think [ansi(hW, ljust(HP: 42/100,40))]
Multi-color output:
think [ansi(hr,DANGER,hy, -- ,hg,ALL CLEAR)]
Using percent-substitution in a message attribute:
@desc here=The walls glow %xra soft red%xn in the torchlight.
Terminal Compatibility
Not all clients support all ANSI features. Flash (blink) is widely ignored. The 256-color palette requires an xterm-compatible client. The 16-color palette values vary by client theme, so colors may look different than expected. TinyMUX uses the standard xterm RGB values when remapping (e.g., red = 187,0,0 normal / 255,85,85 intense).
Players who see broken output should verify that their ANSI flag is set and that their client has ANSI support enabled. Setting COLOR256 on a client that does not support it may produce garbled output.
See also: Substitution, String Manipulation.
Relevant help topics: help ansi, help ansi codes, help ansi substitution, help ansi(), help color256, help nobleed, help stripansi(), help accent(), help translate().