Encoded Text

Context: HL Kit … Multiple Sources

While not exactly a true "building block", encoded text is an important facet of the visual presentation for any game system. Encoded text is the term used for inserting control over colors, fonts, and even bitmaps within text strings. If you want to highlight a word within a string in red, you'll use encoded text. If you want to change the font size for a few works or put a keyword in bold, you'll use encoded text. You can also insert bitmaps into the text stream with encoded text, which makes it possible to do things like display the sequence of dots for traits within the World of Darkness game system.

The encoding syntax uses the characters '{' and '}' to identify the special codes, much like HTML uses the '<' and '>' characters to wrap special codes. The text found between the '{' and '}' characters is interpreted based on the table given below.

{br}	Inserts a carriage return into the text at this position.
{nbsp}	Inserts a non-breaking space into the text at this position. Word-wrapping behavior is not allowed to occur on a non-breaking space, so the space is tied to whatever other text appears before and/or after it. This can be useful for placing padding around text that changes foreground and/or background colors.
{spc}	From this point forward in the text, all sequences of multiple spaces are collapsed into a single space.
{b} {/b}	Text following the "{b}" sequence is rendered in bold. This persists until the "{/b}" sequence turns off bold rendering.
{i} {/i}	Text following the "{i}" sequence is rendered in italics. This persists until the "{/i}" sequence turns off italics rendering.
{u} {/u}	Text following the "{u}" sequence is underlined. This persists until the "{/u}" sequence turns off underline rendering.
{super} {/super}	Text following the "{super}" sequence is displayed in superscript. This persists until the "{/super}" sequence turns off superscript rendering.
{font name}	From this point forward in the text, the font with the specified "name" will be used for output. The prevailing size and style are used in conjunction with the new font. NOTE! Use of a font that is not a standard Windows font will result in the new font being ignored on any computer that does not possess the font. So be sure to only use standard Windows fonts if you plan on distributing your data files to others.
{size value}	From this point forward in the text, the font size is changed to the given "value". In order to support fractional point sizes, the value is the number of quarter-points, so a value of 40 would translate to a point size of 10, while a value of 38 would translate to a point size of 9.5. The prevailing font and style are used in conjunction with the new size.
{revert}	From this point forward in the text, the original default font characteristics are restored. All states for bold, italics, and underline are reset to off, regardless of the default font characteristics restored. The primary use for this encoding is to output some text in the default font, configure the text properly for a short segment, and then revert to outputting the rest of the text in the original font. This way, the same encoded text works consistently even when the default font varies between situations.
{text xxxxxx}	This sequence changes the foreground text color to the color given by "xxxxxx". The format for the color uses standard HTML color syntax, with each character representing a hexadecimal digit. The first two characters define the Red color value, the next two Green, and the last two Blue. For example, the encoding "{text ff0080}" specifies a Red value of "ff", a Green value of "00", and a Blue value of "80". To revert the foreground text color back to the default, use a color value of "010101". NOTE! For additional details on specifying colors via the HTML syntax, please refer to one of the many websites that provide this information, such as http://www.w3schools.com/Html/html_colors.asp.
{back xxxxxx}	This sequence changes the background text color to the color given by "xxxxxx". The color format uses standard HTML syntax, as described for "{text}" above. To disable use of a background color and display text transparently, use a color value of "010101".
{align position}	From this point forward in the text, each new line of text will be aligned based on the given "position". The position must be one of the following values: "left" for left-aligned text, "right" for right-aligned text, or "center" for centered text.
{vert value}	Vertical spacing is immediately inserted into the output, with "value" indicating the number of pixels worth of gap to insert.
{horz value}	Horizontal spacing is immediately inserted into the output, with "value" indicating the number of pixels worth of gap to insert.
{offset value}	From this point forward, every new line of text has "value" pixels of horizontal spacing inserted at the start of the line. The offset persists, allowing large blocks of text to be inset from other text. You can turn off the offset by applying an equivalent negative offset. Repeated uses of "offset" are cumulative.
{indent value}	From this point forward, every new paragraph of text gains an indentation behavior dictated by "value". If "value" is positive, normal indentation logic is used and the first line of each paragraph is indented that number of pixels. If "value" is negative, a hanging indent is applied, with the second and subsequent lines being indented the specified number of pixels (as an absolute value). Repeated uses of "indent" are cumulative, except for a value of zero, which turns off any active indent behavior.
{bmp name}	Inserts into the output the bitmap image with the file name of "name.bmp" that resides in the data file directory for the game system. This bitmap is assumed to be transparent, with the pixel at (0,0) indicating the transparent color. For example, the code "{bmp foo}" would insert the bitmap file named "foo.bmp" that is found in the game system directory. NOTE!  If the bitmap is not found or the output doesn't support encoding, the "name" is inserted as text. So if the filename is "[R].bmp" and referenced as "{bmp [R]}", the text inserted would be "[R]". NOTE!  By default, bitmaps are never scaled when output, but individual styles can explicitly enable scaling of bitmaps inserted via encoded text. If scaling is enabled, the bitmaps may not look ideal due to the scaling.
{bmpscale factor name}	As {bmp name}, above, except the the bitmap is scaled by a factor of "factor" (from 2-9) before being output. For example, if you create a bitmap "somebitmap.bmp" with a size of 400x400 and then output it using {bmpscale 4 somebitmap}, it will be drawn with a size of 100x100. This can be useful for drawing bitmaps at large scales, then shrinking them down for use on high-dpi mediums (such as printed pages). NOTE! This is only recommended for use on output sheets. Due to the windows bitmap resizing algorithm, results of this will likely be poor if used on the screen.
{meta behavior}	The behavior specifies a new rendering behavior that will persist until it is again changed. The specified behavior must be one of the following values: bmpfull – Bitmaps embedded in the encoded text are vertically centered within the full height of the text, including the region of any descender. bmpbaseline – Bitmaps embedded in the encoded text are vertically centered between the baseline of the text and the top edge of the text. This is the default behavior used by encoded text. revert – All behavior changes applied via "meta" special codes are reverted to their default state.
{macro name}	Looks for the macro with the unique id given by name and processes the contents of that macro as if it were found in the text instead. This means that macros MAY include encoded text that will be properly processed when the macro is evaluated. NOTE! Macros MAY be nested within each other, but only to a limited extent, so use nesting sparingly. If a macro references another macro within it, the nested macro will be correctly processed, up to a small number of nesting levels. NOTE! If an undefined macro is referenced, a message of the form "[Undefined macro: name]" is inserted into the resulting text where the macro would be.
{ref name}	Designates the start of a reference region (or "hot zone") that the user can click within to obtain additional information. The name specifies the predefined reference to show when the user clicks in the zone. The zone spans all text from this point forward until the zone is terminated. Terminating a reference zone is accomplished by leaving the name blank. The following is an example of using a reference: "before {ref foo}hot zone{ref} after". NOTE! If an undefined reference is used, a message of the form "[Undefined reference: name]" is displayed when the reference hot zone is clicked within by the user.
{url name}	Designates the start of a hot zone corresponding to an internet URL. The name specifies the actual URL to which the user will be sent when the zone is clicked within (e.g. "http://www.wolflair.com"). The zone spans all text from this point forward until the zone is terminated. Terminating a URL zone is accomplished by leaving the name blank. The following is an example of using a URL zone: "before {url http://www.wolflair.com}hot zone{url} after". NOTE! When clicked, Windows is instructed to launch the default web browser that is currently configured by the user and to load the specified URL into that browser. If no browser is properly configured, an error will be reported. If the URL is invalid, the web browser will report that to the user.
\n	Identical to "{br}". This is a programming convenience for automated conversion programs written in C/C++.

IMPORTANT! Not everything within HL makes use of encoded text, so be sure to check the documentation first. If you use encoded text in a place where it's not supported, you will see your embedded special codes within the text displayed.

NOTE! Encoded text sequences ignore case, so "{BR}" is identical to "{br}". Exceptions to this are macro and reference names, which are case-sensitive. Similarly, URLs are case-sensitive if the website being addressed uses case-sensitive URLs.

NOTE! If the text within an encoding does not correctly match one of the codes defined above, the text is left unchanged, except as noted above.