KDScript → Custom HUD elements →

KDStatMeter

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.

Parameters

Parameter	Type	Description	Default value
`stat_meter`	boolean	whether to initially display the stat meter	`true`
`stat_meter_style`	string	the style of meter to draw (see below)	`progress`
`stat_meter_image`	string	path to a bitmap or name of a symbol (see below)	`@square` or `@none`
`stat_meter_spacing`	integer	space between units of the meter, in pixels	`8`
`stat_meter_text`	string	name of a text string or special string (see below)	`@none`
`stat_meter_position`	string	where to draw the display on screen (see below)	`nw`
`stat_meter_offset_x`	integer	distance to offset along x axis, in pixels	`0`
`stat_meter_offset_y`	integer	distance to offset along y axis, in pixels	`0`
`stat_meter_orient`	string	how the meter is arranged (see below)	`horiz`
`stat_meter_width`	integer	the width of the meter or unit, in pixels	(see below)
`stat_meter_height`	integer	the height of the meter or unit, in pixels	(see below)
`stat_source_qvar`	string	which quest variable to use as the statistic	—
`stat_source_property`	string	which property to use as the statistic	—
`stat_source_field`	string	which field within a property to use	—
`stat_source_component`	string	which component of a vector property/field to use	—
`stat_source_object`	object	which object to use for a property	(self)
`stat_range_min`	real	the lowest possible value of the statistic	(see below)
`stat_range_max`	real	the highest possible value of the statistic	(see below)
`stat_range_low`	integer	the percentage at or below which a value is considered low	`25`
`stat_range_high`	integer	the percentage at or above which a value is considered high	`75`
`stat_color_bg`	color	color of the meter's background area	`0x000000` (black)
`stat_color_low`	color	color of the meter's content if its value is low	`0xff0000` (red)
`stat_color_med`	color	color of the meter's content if its value is medium	`0xffff00` (yellow)
`stat_color_high`	color	color of the meter's content if its value is high	`0x00ff00` (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:

progress: A progress bar is drawn that is gradually filled based on the statistic.
units: A number of individual images or symbols are drawn based on the statistic.
gem: 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:

For a units meter, if it is set to one of the predefined symbols (other than @arrow), the named symbol will be drawn as the unit. Otherwise, this parameter should be set to a relative path to a bitmap image that will be drawn as the unit. If the image cannot be loaded, the default @square unit will be drawn instead. The stat_meter_spacing parameter determines the space in pixels left between each unit image or symbol.
For a gem meter, the stat_meter_image may be a relative path to the first of a series of bitmap frames in the usual Dark Engine naming pattern (e.g. meter.png, meter_1.png, meter_2.png, etc.). The frame displayed will be based on the value of the statistic, with the first frame representing the lowest values and the last frame the highest. All frames should be the same size, as only the size of the first frame will be checked.
Images are not supported for progress meters, but a similar effect can be obtained with the gem 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.

@none: No text is displayed (meter only).
@name: 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.
@description: 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:

center: 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:

horiz: 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.
vert: 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.