xFont.dll for Tribes 1.41
Version 0.24
By Smokey


==========================================================================
About
==========================================================================
Plugin that adds font settings to certain HUD controls, including the following features:

- Ability to define custom fonts used in tags through for FearGuiFormattedText and CenterPrint controls.
- Added new tag to allow you to define fonts in HUDs based on font name instead of - tags.
- Change font colors within the tag as follows: where RRGGBB is a hex code for an RGB color (Note: underlying font must be WHITE).
- Change font alpha / transparency within the tag as follows: where AA is an alpha hex code from 00 to FF (0 to 255).
- Support for bitmap RGB and alpha in the tag as follows: or where AA is an alpha hex code from 00 to FF (0 to 255).
- Create alpha timers to fade font foregrounds and/or backgrounds in and out based on your parameters.
- Add a drop shadow to a font with the font tag as follows: .
- Automatically loads fonts saved in /config folder to be used by scripts/huds (e.g., config/Modules/CTFHud/CTFHud-Green.pft)
- Variable $xFont::Loaded will be set to True for use in scripts if the plugin is installed and loaded
- Preference $xFont::FixTextAlignment is configurable in Huds.cs preference file (Default: False)

==========================================================================
Requirements
==========================================================================
- xFont config files must be in config/Core/xFont
- You must be using the xLoader plugin loader and not the rasadhlp.dll/winfix loader
- xFont.ini must be installed alongside xFont.dll in /plugins folder

==========================================================================
Details
==========================================================================

Numerical Font Tags
-------------------------------------------------------------------------------------------------------
Allows you to define the fonts used in tags through for FearGuiFormattedText and CenterPrint controls through config variables.


Inline Font Tags
-------------------------------------------------------------------------------------------------------
Adds inline font tag support to SimGui::TextFormat based controls (incl. FearGuiFormattedText and CenterPrint).
This allows you to define the fonts you want to use in the control text directly using the "" tag.

Inline font tag allows you to:
1) Define in your script the font file to render
2) Change the color of the font and its transparency
3) Add a drop shadow at a custom color/transparency and offset

Formats:


[Note: Excluding the offset will default to 1,1]


font: Font filename [Example: font.pft]
fgcolor: 6-8 digit hex RGB or RGBA code for foreground color [Example: FFFFFF or FFFFFFFF]
bgcolor: 6-8 digit hex RGB or RGBA code for background color [Example: FFFFFF or FFFFFFFF]
bgoffset: x,y offset coordinates for background [Example: 1,1]

Examples:
Original font
Red font
Red font with ~50% transparency
Red font with black shadow (default offset of 1,1)
Red font with black shadow (offset of 3,3)
Red font with black shadow at %50 transparency (offset of 3,3)

Note: To use the custom font color feature, the font color of your underlying .pft file must be WHITE. Black stroke/border will work.


Font Alpha Timers
-------------------------------------------------------------------------------------------------------
This lets you set transparency for bitmap images and use timers to control alpha sequences similar to fonts above.
Create alpha timers to fade font foregrounds and/or backgrounds in and out based on your parameters.

The following functions are available:

$MyHUD::TimerID1 = xFont::NewTimer(name, startNum, endNum, stepSize, stepTime, sequenceType, [autoStart]);
xFont::ChangeTimer(name, stepSize, stepTime);
xFont::StartTimer(name, [startNum], [callbackFunc], [callbackValue]);
xFont::StopTimer(name, [endNum]);
$MyHUD::TimerID1 = xFont::TimerID(name);

The $MyHUD::TimerID1 is used in the RRGGBBAA for the foreground and/or background in place of the AA as follows:

%text = "TEXT HERE!";

The params are as follows:

name: Unique name of the timer (e.g., "MyHUD::Timer1")
startNum: Number between 0 and 255 to represent the alpha transparency value at which to start the timer.
endNum: Number between 0 and 255 to represent the alpha transparency value at which the timer progresses towards.
stepSize: Number between 1 and 255 to represent the alpha value to change at each step/tick.
stepTime: Number between 0.01 and 60 to represent the number of seconds between each step/tick.
sequenceType: Number between 0 and 3 as follows:

0 - Pulse (Progresses from [startNum] to [endNum] then back to [startNum])
[callbackFunc] called after one full pulse when it reaches [startNum]

1 - Loop (Starts at [startNum] and progresses to [endNum] then resets at [startNum])
[callbackFunc] called when [endNum] is reached

2 - Flash (Flashes between [startNum] and [endNum]. [stepSize] is ignored)
[callbackFunc] called when it reaches [startNum]

3 - Fade (Starts at [startNum] and progresses towards [endNum] and then stops)
[callbackFunc] called when timer stops at [endNum]

[autoStart]: True or False. Optional parameter to start the timer on the first render of the control (Default: False)
[callbackFunc]: Name of a Tribes script function to call when timer reaches a certain point in the sequence (as defined above)
[callbackValue]: Optional value to pass to the callbackFunc when it is called. You can pass a control ID for example.

Example:

$MyHUD::Timer1ID = xFont::NewTimer("MyHUD::Timer1", 0, 255, 25, 0.01, 0); [Note: Place NewTimer in your HUD's init() function]
xFont::StartTimer("MyHUD::Timer1");

Control::SetValue("MyHUD::Font1", "Font Test")


Note: Put [$MyHUD::Timer1ID = xFont::NewTimer()] in your HUDs's init() function so it only runs once. If you run NewTimer with a name that already exists, it will return "".


Bitmap Colors and Alpha
-------------------------------------------------------------------------------------------------------
Support for bitmap color overlays and alpha / alpha timers in the tag.
To use color overlays, your image should be a white or grayscale image for best results.

Formats:


where AA is an alpha hex code from 00 to FF (0 to 255).
where AA is an alpha hex code from 00 to FF (0 to 255).

Example:

Control::SetValue( "MyHUD::Control1", ""); ~%50 transparency of image

Control::SetValue( "MyHUD::Control2", ""); Use alpha timer to control alpha


Fix Text Alignment
-------------------------------------------------------------------------------------------------------
Preference $xFont::FixTextAlignment is configurable in the Huds.cs preference file (Default: False)
This will fix text alignment based on text control width rather than parent width


Loading Fonts
-------------------------------------------------------------------------------------------------------
By default, fonts in Tribes 1.41 are loaded from the following locations:

base/fonts.zip
base/fonts/ (supersede fonts in fonts.zip if any names are duplicate)

It is suggested that any fonts you use for the Numerical Font Tags (-) be saved to base/fonts.zip or base/fonts/ folder.

The plugin will recursively search for *.pft files in /config and load them at startup. This will allow you to save custom fonts alongside your HUD scripts/images.

For example, a config with the following files:

config/Modules/CTFHud/CTFHud.acs.cs
config/Modules/CTFHud/CTFHud-Font-10pt.pft

The custom font above can be used in your CTFHud as like so:

Control::SetValue( "CtfHUD::Status"~%slot, "("~%score~") "~%loc );

Note: You cannot duplicate existing font file names (e.g., have two MyFont.pft files in /config). For example:

config/Modules/CTFHud/MyFont.pft
config/Modules/KillHud/MyFont.pft <-- WILL NOT LOAD! Cannot use the same font filename for multiple fonts

Suggest you name custom fonts as HUDNAME-FONTNAME-SIZE.pft (e.g., CTFHud-Ubuntu-10pt.pft and KillHud-Arial-12pt.pft) to avoid name collisions.