Named Color Token System

This project enables 146 color names to be used as color-changing tokens in dialogue, object names and descriptions and PC chat messages. Instead of using hard-to-remember <CUSTOMxxxx> tokens or hard-to-type NWN ASCII tokens (such as <c~!!>), you can now use simple named color tokens like this: <ncOrange>this text is now orange</nc>. This project also provides a library for color token generation from RGB and HSV color structs.

A demo module is provided.

DESCRIPTION

Names of colors available through this project come from SVG color list. There is a total of 147 of them, but one had to be removed since it had too long name (NWN limits token length to 16 characters). That was color named LightGoldenrodYellow. There are similar colors, so no big deal.
 
All named color tokens start with "nc" characters and use CamelCase, for example <ncYellowGreen>. To reset text color to default white, use </nc> token. A complete list of them may be found in HTML file next to this readme. This is more than most (if not all) modules will ever need.
 
Because of 16 character limit, some color names had to be abbreviated in following fashion:

• Instead of "Light" in name, there is "L", i.e. <ncLGreen></nc> for LightGreen.
• Instead of "Medium" in name, there is "M", i.e. <ncMOrchid></nc> for MediumOrchid.
• Instead of "Dark" in name, there is "D", i.e. <ncDGoldenrod></nc> for DarkGoldenrod.

This project also modifies the <StartHiglight> default toolset token by changing its resulting color from badly visible blue to the same green as <StartAction>. This change is done via stringtokens.2da override.

Named color tokens work with dialogue instantly - no scripting is needed at all. However in order to apply them to object names and descriptions, you have to use a script. One is provided in the erf file: ncts_apply. Make any object execute it and its name and description will be updated.

If you want to use named color tokens in scripts, refer to ncts_include script in the erf file and to API presented below (see builder notes).

Since version 1.2 it is possible to generate every possible ASCII color token with scripts using RGB or HSV color components. Conversion between these two color spaces is also possible with provided functions.

Since version 2.0 it is possible to colorize PC chat messages. This is done with single OnPlayerChat event handler script. Just add tokens to the text like you would type a conversation - they will be applied when the message is send. Module builders need to enable this functionality. One such chat-handling script is provided in the erf file: ncts_chat.

CHANGELOG

2.0 (2019-01-15)

• Full rewrite of the project (no compatibility with previous versions).
• Changed data container from tlk to 2da, dropping the need for the talk table when using NCTS script library (only hak file is needed and the scripts, obviously) - to use the tokens in dialogue stringtokens.2da and the talk table are still required.
• Added possibility to use tokens in PC chat messages (see ncts_chat).
• Renamed 2da files in project's hak file - prefixed them with "named".
• Changed names of all API functions to be more compact (they also start now with "NCTS_").
• Optimized NCTS_ApplyNamedColorTokens function (faster and with better error handling - invalid color tokens are copied verbatim to output).
• Added new function: NCTS_SanitizeColorTokens (useful for user-provided input sanitization (i.e. in PC chat messages).
• Added helper function (NCTS_PreviewNamedColorsTokens) displaying all available named color tokens in caller PC's message log.

1.3 (2018-10-27)

• Fixed StartAction, StartCheck and StartHighlight tokens. Thanks, Tarot_Redhand.

1.2 (2018-10-09)

• Divided program logic between three 2das: stringtokens.2da and two new files: colortokens.2da and colorvalues.2da (only first one is required in override for tokens to work directly in dialogue, other two are for scripts and can be normally accessed by the game from hak file).
• Expanded color value ranges from 32-255 to 1-255 - this allows in-game color display to be almost equal to SVG colors (0 is treated as 1).
• Renamed API function names to be more explanatory.
• Added HSV support.
• Expanded RGB support.
• Added functions generating color tokens from RGB and HSV colors.
• Added functions converting between RGB and HSV colors.

1.1 (2018-09-30)

• Fixed bug with female PCs.

1.0 (2018-09-28)

• Initial release.

INSTALLATION

This project can be installed in two different ways, depending on what kind of functionality is required. Both are possible at the same time.

1. If you want to use named tokens in dialogue directly (i.e. when they are manually written into conversations by module builders):

• Extract named_colors.tlk from tlk folder from project's archive into tlk folder of the game.
• Extract stringtokens.2da from override folder from project's archive into override folder of the game.

2. If you want to use named tokens in scripts (or apply them to dialogue via scripts), object names and descriptions or PC chat messages:

• Extract named_colors.hak from hak folder from project's archive into hak folder of the game.
• If you are module builder, import contents of named_colors.erf from project's erf folder into your module (players can skip this step).

Attention: if you choose option 1 above, stringtokens.2da placed in the override folder will affect your whole installation of NWN. This should have no negative impact on other modules, but may also cause problems with non-english versions of the game.