tbamud/doc/color.txt

If you have any additions, corrections, ideas, or bug reports please stop by the
Builder Academy at telnet://tbamud.com:9091 or email rumble@tbamud.com -- Rumble

Using Color In tbaMUD 
Originally by Jeremy Elson 

This document is a description of how to write C code which displays messages
to players in color in the tbaMUD game engine. Its intended audience is for 
Coders of tbaMUD. 

tbaMUD allows you to create colorful messages by using ANSI control sequences.
Each player may select what <20>level<65> of color he/she desires from the four 
levels <20>off,<2C> <20>brief,<2C> <20>normal,<2C> and <20>complete.<2E> Each player can select his/her
color level by using the TOGGLE COLOR command from within the MUD; you as the 
programmer must decide which messages will be colored for each of the color 
levels. 

All files in which you wish to use color must have the line: 

#include "screen.h" 

This should be put in after all other includes in the beginning of the file. 

There are 8 colors available <20> <20>normal,<2C> red, green, yellow, blue, magenta, 
cyan and white. They are accessible by sending control sequences as part of 
another string, for example: 

sprintf(buf, "If you<6F>re %shappy%s and you know it clap " 
             "%d of your hands.\n\r", x, y, num_of_hands); 
send_to_char(ch, buf); 

In this example, x and y are the <20>on<6F> and <20>off<66> sequences for the color you 
want. There are 2 main series of color macros available for you to use (don<6F>t 
actually use <20>x<EFBFBD> and <20>y,<2C> of course!): the K series and the CC series. The CC 
(Conditional Color) series is recommended for most general use. 

The name of the actual sequence starts with the name of its series, plus a 
3-letter color code, as follows: 

Normal: NRM 
Red: RED 
Yellow: YEL 
Green: GRN 
Blue: BLU 
Magenta: MAG 
Cyan: CYN 
White: WHT 

For example, white in the K series is KWHT; blue in the CC series is 
CCBLU() (arguments defined below). 

The K series requires no arguments, and is simply a macro to the ANSI color 
code. Therefore, if you use a K-series color code, the color will ALWAYS be 
sent, even if the person you<6F>re sending it to has color off. This can very bad.
Some people who do not have ANSI-compatible terminals will see garbage 
characters instead of colors. If the terminal correctly ignores ANSI color 
codes, then nothing will show up on their screen at all. The K series is mainly
used to print colors to a string if the player<65>s color level will later be 
tested manually (for an example, see do_gen_com in act.comm.c). 

The recommended series is the CC series (i.e. CCNRM(), CCRED(), etc.) The CC 
series macros require two arguments <20> a pointer to the character to whom the 
string is being sent, and the minimum color level the player must be set to in 
order to see the color. Color sent as 'brief' (formerly known as sparse it was 
changed for consistancy with the syslog command) (C_SPR) will be seen by people
with color set to sparse, normal, or complete; color sent as <20>normal<61> (C_NRM) 
will be seen only by people with color set to normal or complete; color sent as
<EFBFBD>complete<EFBFBD> (C_CMP) will be seen only by people with color set to complete. 

To illustrate the above, an example is in order: 

#include "screen.h" 
/* include screen.h in all files that you use color in */ 

ACMD(do_showcolor) 
{ 
char buf[300]; 

sprintf(buf, "Don<6F>t you just love %scolor%s, %scolor%s, " "%sCOLOR%s!\n\r", 
CCBLU(ch, C_CMP), CCNRM(ch, C_CMP), CCYEL(ch, C_NRM), CCNRM(ch, C_NRM), 
CCRED(ch, C_SPR), CCNRM(ch, C_SPR)); 
send_to_char(ch, buf); 
} 

What does this do? For people with color set to Complete, it prints: 
   Don<6F>t you just love color, color, COLOR! (blue) (yellow) (red) 

People who have color set to Normal will see: 
   Don<6F>t you just love color, color, COLOR! (yellow) (red) 

People who have color set to Sparse will see: 
   Don<6F>t you just love color, color, COLOR! (red) 

People who have color set to Off will see: 
   Don<6F>t you just love color, color, COLOR! (no color, as you<6F>d expect) 

There are several common pitfalls with using the CC series of color macros: 

Do not confuse CCNRM with C_NRM. CCNRM() is a macro to turn the color back to
normal; C_NRMis a color level of <20>normal.<2E> Always make sure that every pair of 
<EFBFBD>on<EFBFBD> and <20>off<66> codes are at the same color level. For example: 

WRONG: sprintf(buf, "%sCOLOR%s\n\r", CCBLU(ch, C_NRM), CCNRM(ch, C_CMP)); 

This is wrong because if someone has their color level set to Normal, the CCBLU
code will be sent but the CCNRM command will not, causing all subsequent output
to be blue. 

WRONG: sprintf(buf, "%sCOLOR%s\n\r", CCBLU(ch, C_CMP), CCNRM(ch, C_NRM)); 

The above statement is also wrong, although not as bad. In this case, someone
with color set to Normal will (correctly) not get the CCBLU code, but will then
unnecessarily get the CCNRM code. Never send a color code if you don<6F>t have to.
The codes are several bytes long, and cause a noticeable pause at 2400 baud. 

This should go without saying, but don<6F>t ever send color at the C_OFF level. 

Special precautions must be taken when sending a colored string to a large 
group of people. You can<61>t use the color level of <20>ch<63> (the person sending the
string) <20> each person receiving the string must get a string appropriately 
colored for his/her level. In such cases, it is usually best to set up two 
strings (one colored and one not), and test each player<65>s color level 
individually (see do_gen_comin act.comm.c for an example).