KDScriptCustom HUD elements


KDStatMeter displays a meter (bar, gem, or other indicator) on screen that reflects the value of a numeric property, quest variable, or other setting. The meter might be used to display health, visibility, alertness, etc. of the player or an AI; time elapsed or remaining; progress towards an objective; or any other numeric value. This is a custom HUD element script; see the custom HUD elements documentation for more details.


ParameterTypeDescriptionDefault value
stat_meterbooleanwhether to initially display the stat metertrue
stat_meter_stylestringthe style of meter to draw (see below)progress
stat_meter_imagestringpath to a bitmap or name of a symbol (see below)@square or @none
stat_meter_spacingintegerspace between units of the meter, in pixels8
stat_meter_textstringname of a text string or special string (see below)@none
stat_meter_positionstringwhere to draw the display on screen (see below)nw
stat_meter_offset_xintegerdistance to offset along x axis, in pixels0
stat_meter_offset_yintegerdistance to offset along y axis, in pixels0
stat_meter_orientstringhow the meter is arranged (see below)horiz
stat_meter_widthintegerthe width of the meter or unit, in pixels(see below)
stat_meter_heightintegerthe height of the meter or unit, in pixels(see below)
stat_source_qvarstringwhich quest variable to use as the statistic
stat_source_propertystringwhich property to use as the statistic
stat_source_fieldstringwhich field within a property to use
stat_source_componentstringwhich component of a vector property/field to use
stat_source_objectobjectwhich object to use for a property(self)
stat_range_minrealthe lowest possible value of the statistic(see below)
stat_range_maxrealthe highest possible value of the statistic(see below)
stat_range_lowintegerthe percentage at or below which a value is considered low25
stat_range_highintegerthe percentage at or above which a value is considered high75
stat_color_bgcolorcolor of the meter's background area0x000000 (black)
stat_color_lowcolorcolor of the meter's content if its value is low0xff0000 (red)
stat_color_medcolorcolor of the meter's content if its value is medium0xffff00 (yellow)
stat_color_highcolorcolor of the meter's content if its value is high0x00ff00 (green)

Appearance of meter

The stat_meter parameter determines whether the meter is initially enabled (visible) or not. The meter can be turned on or off during the mission by sending this object a StatMeterOn or StatMeterOff message.

The stat_meter_style parameter determines what visual style of meter is drawn, from among these values:

A progress bar is drawn that is gradually filled based on the statistic.
A number of individual images or symbols are drawn based on the statistic.
A solid area is drawn whose image or color changes based on the statistic.

The stat_meter_image parameter determines a bitmap image or symbol to use in drawing the meter, depending on style:

The stat_meter_text parameter determines what text, if any, is displayed next to the meter. Only horizontal meters may display text; on vertical meters, this parameter is ignored. This parameter does not contain the text itself; it is either one of the special values listed below or the name of a string in the strings\hud.str file.

No text is displayed (meter only).
For property sources, the name of the stat_source_object, as defined in the Inventory→Object Name property, is displayed. For quest variable sources, the value of stat_source_qvar is used as the name of a string in strings\hud.str.
For property sources only, the description of the stat_source_object, as defined in the Inventory→Long Description property, is displayed.

Dimensions of meter

The stat_meter_position parameter determines where on the screen the meter is drawn, from among these values:

The meter is drawn in the center of the screen.
north, south,
east, west
The meter is drawn at the center of the specified edge of the screen (where north is up, west is left, etc.).
nw, se, sw, se
The meter is drawn at the specified corner of the screen.

The stat_meter_offset_x and stat_meter_offset_y parameters determine how far, in pixels, to offset the meter from the position calculated by stat_meter_position.

The stat_meter_orient parameter determines how a progress or units meter is arranged, either:

A horizontal progress bar or series of units is drawn. For elements at the left of the screen, higher values are towards the right; for those on the right, towards the left.
A vertical progress bar or series of units is drawn. For elements at the bottom of the screen, higher values are towards the top; for those on the top, towards the bottom.

The stat_meter_width and stat_meter_height parameters determine the size of a progress or gem meter (exclusive of any text) or of a single unit of a units meter. If a bitmap image is specified in stat_meter_image, these parameters are ignored. Otherwise, they default to 32×32 for units meters and 128×32 for all others. For a progress or gem meter with vert orientation, the values are inverted, with stat_meter_width determining the height and vice versa.

The source statistic

The statistic displayed by the meter can be sourced from either an object property or a quest variable.

The stat_source_qvar parameter names a quest variable that provides the statistic. The variable may be set at mission or campaign level.

The stat_source_property parameter names a property that provides the statistic. Use an internal Dark Engine property name (e.g. PhysState for Physics→Model→State); these can be found using the list_props command (the Log→Dump property list menu item).

The stat_source_field parameter names the field within a property that provides the statistic. This parameter may only be and must be set if stat_source_property names a property with more than one field. The field name should be exactly as it appears in the property dialog (e.g. Rot Velocity within the PhysState property).

The stat_source_component parameter names the component of a vector value that provides the statistic. This parameter may only be and must be set if the property/field providing the statistic is a vector (has three values in a row). This parameter should then be set to x, y, or z (first, second, or third value, respectively).

The stat_source_object parameter determines the object that provides a property statistic. It may be an object name or an object number, though the former is recommended. This parameter may only be set if stat_source_property is set; its default is the object on which this script is placed.

Range and coloration

Several aspects of the meter depend on where the statistic value falls within a range of possible values.

The stat_range_min and stat_range_max parameters determine the lowest and highest possible values, respectively, of the statistic. These are used to convert the statistic to a percentage. If the current value falls outside this range, it will be clamped within the range. The parameters' defaults depend on the source statistic:

Level field of the AI_Visibility property
minimum = 0,
maximum = 100
HitPoints property
minimum = 0,
maximum = value of MAX_HP property
all other statistics
minimum = 0,
maximum = 1

The stat_range_low parameter is a percentage (between minimum and maximum values) threshold at or below which the statistic value is considered to be low. Likewise, the value is considered high if its percentage is at or above the stat_range_high parameter. Together, these determine when to display the meter with special coloring or imagery.

For progress and units meters, the foreground elements of the meter (progress bar, unit symbols, border, and text) are colored based on where the current value falls within the range: low (stat_color_low), medium (stat_color_med), or high (stat_color_high). The stat_color_bg parameter defines the color of background elements of the meter.

For gem meters, color is handled differently: the color smoothly transitions from the low color to the medium color to the high color based on the statistic value, while the background color is used for a border.

This script is part of the KDScript module. Copyright © 2012–2013 Kevin Daughtridge. See introduction for details.