Interface: on-screen text and the HUD overlay

The game's own screens, mod windows and button sounds are in Screens and windows; keys and the mouse in Keys and the mouse.

Come here when your mod shows something to the player: a short message, a counter that stays on screen, a small panel with buttons, a text field the player types into, or a drawn shape such as a radial menu.

A first example: a counter in the lower left corner that a console command updates.

import blse

packs = [3]

def drink(name, args):
    packs[0] = packs[0] - 1
    blse.hud_set('mymod_packs', 'Blood packs: %d' % packs[0], 0.02, 0.9, '#FF4040')   # same id: updated in place
    blse.show_text('You drink a blood pack.')

def on_level(topic, data):
    blse.hud_set('mymod_packs', 'Blood packs: %d' % packs[0], 0.02, 0.9, '#FF4040')

blse.subscribe('blse.level_init', on_level)
blse.add_command('drink', drink, 'drink: use a blood pack')

Read this first

• Two different tools. show_text hands a message to the game, which shows it for a few seconds. The HUD overlay (hud_*) is BLSE's own layer of text, boxes, images and shapes that stay on screen until you remove them.
• show_text and hud_cursor need a running level (else RuntimeError). HUD elements can be set at any time; they are drawn while a level is shown (and, with hud_in_menus, also over menus, see Screens and windows).
• HUD elements are not saved and stay across loads and level changes until removed. Python's elements are removed when Python starts again with the engine: set them again when your script runs.
• Positions and sizes are fractions of the screen, from 0 to 1: (0, 0) is the top left corner, (1, 1) the bottom right, 0.5 the middle. Font sizes are in pixels.
• Use ids of your own ('mymod_packs'): all Python scripts share the same ids, and at most 64 elements exist at once (every mod and plugin together).
• Bad arguments raise ValueError (an id that is too long, a position outside 0..1, a bad colour); a full overlay (64 elements) raises RuntimeError.

Words used on this page#

• HUD: the game's interface drawn over play (health, blood, the compass). BLSE's overlay is drawn on top of it.
• Element: one thing on the overlay (a text, a box, an image, a line, a shape, a text field), named by an id you choose: 1 to 63 characters, no control characters. Setting an id again changes that element.
• Colour: '#RRGGBB' (red, green, blue in hexadecimal, 00 to FF) or '#RRGGBBAA' with alpha, the opacity (00 invisible, FF solid). '#FF000080' is half-transparent red.
• Material: a .vmt file under materials/ that tells the game how to draw a texture; the path is given without materials/ and .vmt.
• Cursor mode: a state in which the mouse moves a pointer on the screen instead of turning the view, so the player can click HUD elements.
• Focus: the text field that receives the keyboard; only one at a time.
• Owner: who made an element: 'python' for every Python script, or a plugin's name. Each owner has its own ids. Events report the owner so you can ignore other mods' elements.
• Payload: the text an event hands to your handler: several fields separated by NUL characters (character 0), read with data.split('\0'). Numbers in it are text: convert them with int() or float().
• Convex: a shape without dents (every corner points outwards), such as a triangle, a square or a pie slice narrower than half a circle.

On-screen text#

blse.show_text(text[, kind]) (b0.5.16, recognized builds) shows text to the player through the game's own text messages:

import blse
blse.show_text('Your sire would be proud.')
blse.show_text('Blood: 100% restored', 'top')

Any characters are safe (% is escaped for the game's formatting); text longer than about 190 bytes is cut. A word starting with # is replaced if the game has a localization entry with that name. Raises RuntimeError if no level is running.

blse.show_text#

blse.show_text(text[, kind])   # -> 1

Shows a short message through the game's own text messages. Use it for feedback the player reads once ("Saved", "You found a key"); for text that must stay, use hud_set.

• text (str): the message. A text starting with $ is looked up in the mods' translation files (b0.5.43).
• kind (str, optional): 'center' (default), 'top' or 'console', see the table above. Another word raises ValueError.
• Returns 1. Raises RuntimeError if no level runs, or if this game version is not recognized.

blse.show_text('The door is locked.')
blse.show_text('Debug: entered the alley', 'console')

HUD overlay#

Text elements that stay on screen while a level runs, drawn every frame on top of the game's interface (b0.5.18, requires the analyzed vguimatsurface.dll, which both the original game and the Unofficial Patch ship):

import blse
blse.hud_set('blood', 'Blood packs: 3', 0.02, 0.9, '#FF4040')
blse.hud_set('blood', 'Blood packs: 2', 0.02, 0.9, '#FF4040')   # update in place
blse.hud_remove('blood')

Up to 64 elements in all; text up to 255 bytes (UTF-8). Elements are hidden while a game screen is open (the game menu, inventory, character screen, dialogs; not the console) and are not saved: they stay until removed, also across loads and level changes. Elements from Python are cleared on an engine restart; set them again when your script runs.

blse.hud_set#

blse.hud_set(id, text, x, y[, color[, size[, align[, valign]]]])   # -> 1

Shows a text on the overlay, or changes one already shown with this id. Use it for anything the player should see for longer: a counter, a timer, a label on a panel.

• id (str): the element's name, 1 to 63 characters. An element of another kind with this id (a box, an image) becomes a text.
• text (str): the text, UTF-8, up to 255 bytes. A text starting with $ is translated (translations, b0.5.43).
• x, y (float): where it is drawn, fractions of the screen, 0 to 1. By default the top left corner of the text; see align and valign.
• color (str, optional): '#RRGGBB' or '#RRGGBBAA'; default white '#FFFFFF'.
• size (int, optional): the font height in pixels, 8 to 96; default 24.
• align (str, optional): 'left', 'center' or 'right': which part of the text x gives. Left out: unchanged ('left' for a new element).
• valign (str, optional, b0.5.26): 'top', 'middle' or 'bottom': which part of the text y gives. Left out: unchanged ('top' for a new element).
• Returns 1. Raises ValueError for a bad id, text, position, size, colour or alignment, and RuntimeError when 64 elements exist already or the overlay is not available.

blse.hud_set('mymod_title', 'Elysium', 0.5, 0.1, '#C0A060', 40, 'center')

blse.hud_remove and blse.hud_clear#

blse.hud_remove(id)   # -> 1 or 0
blse.hud_clear()      # -> None

hud_remove removes one of Python's elements (of any kind): 1 if it existed, else 0. hud_clear removes every element set from Python (all scripts), not plugins' ones.

blse.hud_remove('mymod_title')

Text, alignment and sizes#

blse.hud_set(id, text, x, y[, color[, size[, align[, valign]]]]): valign (b0.5.26) is 'top' (default: y is the top edge), 'middle' or 'bottom', for example to center a label on a box; align is 'left' (default: x is the left edge), 'center' (x is the middle) or 'right' (x is the right edge). Left out, they stay as they were (a new element is left/top), so updating the text of an aligned element does not undo hud_align. blse.hud_align(id, align[, valign]) changes them; blse.hud_size(id) returns (w, h) as fractions of the screen (text as last drawn; None before the first draw), for laying out boxes around text.

The overlay is shown and hidden in step with the game's own HUD: hidden under game screens, the Esc menu and loading screens, and faded in together with the HUD as the loading screen fades out after "click to continue", also when loading a save.

blse.hud_align#

blse.hud_align(id, align[, valign])   # -> 1 or 0

Changes which point of a text x and y stand for, without setting the text again. Use 'center' to center a label on a button.

• align: 'left', 'center' or 'right'. valign (optional): 'top', 'middle' or 'bottom'; left out, unchanged. Another word raises ValueError.
• Returns 1, or 0 if Python has no such element (or it is not a text).

blse.hud_align('mymod_title', 'center', 'middle')

blse.hud_size#

blse.hud_size(id)   # -> (w, h) or None

The size of an element as fractions of the screen. For a text it is the size as last drawn, so it is known only after the next frame; for a shape it is its bounding box (the smallest box around it). Use it to fit a box around a text.

• Returns (w, h) (floats), or None if Python has no such element or a text was not drawn yet.

size = blse.hud_size('mymod_title')
if size:
    blse.hud_box('mymod_title_bg', 0.5 - size[0] / 2 - 0.01, 0.1 - 0.01, size[0] + 0.02, size[1] + 0.02)

Boxes, images and clicks#

Elements are drawn in the order they were first created, so later ones are on top; setting an id again keeps its place, even when its kind changes (hud_set on a box id turns it into text). The clickable area of a text element is its drawn size.

blse.hud_box#

blse.hud_box(id, x, y, w, h[, color[, border]])   # -> 1

A filled rectangle: a panel background, a bar, a button.

• id: as for hud_set.
• x, y (float): the top left corner, 0 to 1. w, h (float): width and height, more than 0 and at most 1.
• color (str, optional): the fill; default '#00000080' (half-transparent black). Alpha 00 draws no fill (only the border).
• border (str, optional): the colour of a 1-pixel outline; None or '' (default) for none.
• Returns 1. Raises ValueError for bad values and RuntimeError when the overlay is full or not available.

# A health bar: a dark frame and a red fill 70% wide.
blse.hud_box('mymod_bar_bg', 0.02, 0.95, 0.2, 0.02, '#000000A0', '#FFFFFF60')
blse.hud_box('mymod_bar', 0.02, 0.95, 0.2 * 0.7, 0.02, '#C02020FF')

blse.hud_image#

blse.hud_image(id, material, x, y, w, h[, color])   # -> 1

Draws a material (a picture) stretched over a rectangle: an icon, a logo, a portrait.

• material (str): the path under materials/ without .vmt ('interface/mainmenu/vtm_title'), 1 to 127 characters of A-Z a-z 0-9 _ / . -, not starting with / and without ...
• x, y, w, h: as for hud_box.
• color (str, optional): a tint; default white (unchanged). An alpha below FF makes it see-through.
• Returns 1. Raises ValueError / RuntimeError as hud_box.

blse.hud_image('mymod_logo', 'interface/mainmenu/vtm_title', 0.3, 0.05, 0.4, 0.1)

blse.hud_clickable#

blse.hud_clickable(id[, on])   # -> 1 or 0

Makes one of Python's elements react to clicks in cursor mode (on 1, the default) or not (on 0). Clicks are sent as blse.hud_click.

• Returns 1 if Python has an element with this id, else 0.

blse.hud_cursor#

blse.hud_cursor([on])   # -> 1

Turns cursor mode on (on 1, the default) or off (0) for Python. While any mod has it on, the mouse moves a pointer instead of turning the view, mouse buttons do not reach the game, and clicks are sent as blse.hud_click. Turn it on when your panel opens and off when it closes.

• Returns 1. Raises RuntimeError if no level runs, or if this game version is not recognized.

Note: it ends by itself at every level change.

blse.hud_click#

Fires for every mouse click in cursor mode, also on empty screen.

Payload, in order:

• id: the topmost clickable element under the pointer, or '' for none;
• button: 'MOUSE1' (left), 'MOUSE2' (right), 'MOUSE3' (middle), or 'MWHEELUP' / 'MWHEELDOWN' for the wheel;
• x, y: where, as fractions of the screen, as text with 4 decimals ('0.5123');
• owner: who made the element: 'python', a plugin's name, or '' when no element was hit.

Every script sees every click: check owner == 'python' and your own ids. A left click on a text field also focuses it; a left click elsewhere ends text entry (see Text entry fields).

def on_click(topic, data):
    elem, button, x, y, owner = data.split('\0')
    if owner == 'python' and elem == 'mymod_ok' and button == 'MOUSE1':
        blse.log('OK at %s, %s' % (x, y))
blse.subscribe('blse.hud_click', on_click)

import blse
def open_menu():
    blse.hud_box('menu', 0.3, 0.3, 0.4, 0.3, '#101018C0', '#C0A060')
    blse.hud_box('ok', 0.42, 0.5, 0.16, 0.06, '#205020E0', '#FFFFFF')
    blse.hud_set('ok_label', 'OK', 0.48, 0.515)
    blse.hud_clickable('ok')
    blse.hud_cursor(1)
def on_click(topic, data):
    elem, button, x, y, owner = data.split('\0')
    if owner == 'python' and elem == 'ok':
        for i in ('menu', 'ok', 'ok_label'): blse.hud_remove(i)
        blse.hud_cursor(0)
blse.subscribe('blse.hud_click', on_click)

blse.hud_hover: id, owner = data.split('\0'), the clickable element (or input) under the pointer in cursor mode changed ('' when it left every element); checked every game frame (b0.5.25).

blse.hud_hover#

(b0.5.25) Fires in cursor mode when the pointer moves onto another clickable element (or text field), or off all of them. Use it to highlight a button under the pointer.

Payload, in order: id (the element now under the pointer, '' for none), owner ('python', a plugin's name, or '' for none).

def on_hover(topic, data):
    elem, owner = data.split('\0')
    color = '#205020E0'
    if owner == 'python' and elem == 'mymod_ok':
        color = '#40A040E0'
    blse.hud_box('mymod_ok', 0.42, 0.5, 0.16, 0.06, color, '#FFFFFF')
blse.subscribe('blse.hud_hover', on_hover)

Lines, shapes, rotation and fonts#

Since b0.5.49, drawn with the game's own surface functions (DrawLine and DrawTexturedPolygon), so a mod can draw a wheel, a gauge or an arrow in code. Shapes are elements like the others: same ids, drawing order, hud_remove, hud_clickable, hud_in_menus. Their points are fractions of the screen and may lie between -1 and 2, so a shape can reach past the screen's edges (the surface clips it). Nothing is drawn or made unless a mod creates such an element.

Clicks on shapes hit the shape itself (a polygon's inside, a strip's quads, a line within a few pixels, a turned box or image by its turned outline), not their bounding box. hud_size gives a shape's bounding box. blse.screen_size() (b0.5.49) returns (width, height) in pixels as the overlay last drew (None before the first frame): positions are fractions of a screen that is usually not square, so multiply a round shape's x offsets by height / width.

Fonts are made through the game's surface once it has drawn a frame and kept (up to 64 face/size/weight/option combinations, shared with menu_set_font); each font is an ANSI font (characters 0-255), like the default one. Until it can be made, or if it cannot be made, the text uses the default font.

A ring segment (an arc of a radial menu) as a strip, and a wheel built from such segments (Python 2.1, no math needed beyond sin/cos):

import blse, math
def arc_points(cx, cy, r_outer, r_inner, a0, a1, steps):
    # Pairs (outer, inner) from angle a0 to a1 (degrees, 0 = up, clockwise). The screen is wider than
    # tall: x radii are scaled by the aspect ratio so the ring is round (0.75 for 4:3).
    aspect = 0.75
    points = []
    i = 0
    while i <= steps:
        a = (a0 + (a1 - a0) * i / float(steps)) * math.pi / 180.0  # no math.radians in Python 2.1
        s, c = math.sin(a), math.cos(a)
        points.append((cx + r_outer * s * aspect, cy - r_outer * c))
        points.append((cx + r_inner * s * aspect, cy - r_inner * c))
        i = i + 1
    return points

def show_wheel(selected):
    i = 0
    while i < 8:
        color = '#30303090'
        if i == selected: color = '#C02020C0'
        blse.hud_strip('wedge%d' % i, arc_points(0.5, 0.5, 0.3, 0.12, i * 45 + 2, i * 45 + 43, 8), color, '#FFFFFF60')
        blse.hud_clickable('wedge%d' % i)
        i = i + 1
    blse.hud_line('needle', 0.5, 0.5, 0.5, 0.3, '#FFFFFF', 3)
    blse.hud_set('label', 'Radio', 0.5, 0.5, '#FFFFFF', 28, 'center', 'middle')
    blse.hud_font('label', 'Georgia', 700, 'italic')

Slow motion needs nothing new: blse.set_cvar('host_timescale', '0.3') slows the game. BLSE has no full-screen effects for Python (blur, colour filters): a game effect material drawn as a full-screen hud_image is low resolution and covers the HUD. A tint is a full-screen hud_box; native plugins can draw effects with Direct3D 9 (see the plugin page "Drawing with Direct3D 9").

blse.hud_line#

blse.hud_line(id, x0, y0, x1, y1[, color[, width]])   # -> 1

(b0.5.49) A straight line from (x0, y0) to (x1, y1): a needle, a pointer, a separator.

• Points: fractions of the screen, -1 to 2 (beyond the edges is allowed; the part off screen is not drawn).
• color (str, optional): default white. width (int, optional): 1 to 32 pixels, default 1.
• Returns 1. Raises ValueError for bad values, RuntimeError when the overlay is full or not available.

blse.hud_line('mymod_needle', 0.5, 0.5, 0.6, 0.35, '#FFFFFF', 3)

blse.hud_polygon and blse.hud_strip#

blse.hud_polygon(id, points[, color[, border]])   # -> 1
blse.hud_strip(id, points[, color[, border]])     # -> 1

(b0.5.49) Filled shapes from a list of points. hud_polygon draws one convex shape (a triangle, an arrow head, a diamond). hud_strip draws a band of four-cornered pieces, for rings, arcs and thick curves.

• points: a list (or tuple) of (x, y) pairs (lists or tuples of two numbers), each -1 to 2. Polygon: 3 to 128 points, in order around the shape. Strip: an even number, 4 to 128, as pairs (outer, inner): points 1-2 and 3-4 make the first piece, 3-4 and 5-6 the next, and so on. A wrong type raises TypeError; a wrong count or position ValueError.
• color (str, optional): the fill, default white; alpha 00 for none.
• border (str, optional): a 1-pixel outline; None or '' for none. On a strip it runs along the outer points and back along the inner ones.
• Returns 1. Raises RuntimeError when the overlay is full or not available.

# An arrow head pointing up.
blse.hud_polygon('mymod_arrow', [(0.5, 0.40), (0.52, 0.44), (0.48, 0.44)], '#FFD040')

blse.hud_rotate#

blse.hud_rotate(id, degrees)   # -> 1 or 0

(b0.5.49) Turns a box or an image around its centre, clockwise; 0 is upright. The turn stays when you set the element again.

• degrees (float): any value between -1000000 and 1000000 (taken modulo 360).
• Returns 1, or 0 if Python has no such element, it is not a box or an image, or the angle is out of range.

blse.hud_rotate('mymod_logo', 15)

blse.hud_font#

blse.hud_font(id, face[, weight[, options]])   # -> 1 or 0

(b0.5.49) Draws a text element or a text field in another font.

• face (str or None): a font name Windows knows ('Georgia', 'Courier New') or one the game installed; up to 63 characters, without ", \ or /. None or '' gives back the default font (Tahoma, weight 700).
• weight (int, optional): 100 (thin) to 900 (black), default 400 (normal); 700 is bold.
• options (str, optional): words from 'italic', 'underline', 'strikeout', separated by spaces or commas.
• Bad values raise ValueError. Returns 1, or 0 if Python has no such element or it is not a text or a text field.

blse.hud_font('mymod_title', 'Georgia', 700, 'italic')

blse.screen_size#

blse.screen_size()   # -> (width, height) or None

(b0.5.49) The screen's size in pixels as the overlay last drew it, or None before the first frame. Use it to keep round shapes round: multiply x offsets by height / float(width).

size = blse.screen_size()
if size:
    aspect = size[1] / float(size[0])     # 0.75 at 4:3

Text entry fields#

Since b0.5.36, dragging with the left button in a field selects text, and Shift+click extends the selection. The console key closes the field's text entry and opens the console. With the console open, its window takes the mouse: HUD elements cannot be clicked until it is closed (as in b0.5.24). Esc ends text entry; to close your own panel with Esc, block it while the panel is open (see below).

A left click on a field in cursor mode focuses it (white outline, blinking caret) and puts the caret where it was clicked. Editing (b0.5.26): Left/Right, Ctrl+Left/Right (by word), Home, End, Backspace and Delete (held keys repeat; the numpad keys with Num Lock off); Shift with those selects, Ctrl+A selects all; Ctrl+C, Ctrl+X and Ctrl+V copy, cut and paste through the Windows clipboard (pasted line breaks become spaces); typing replaces the selection. Long text scrolls to keep the caret in view. While a field has focus, keys pressed in play type into it and do not reach the game (they are still sent as blse.key_down with where 'text'), so the player does not move or jump while typing; long text scrolls to show its end. Changing focus with hud_focus sends no events.

To let Esc close your panel instead of opening the game menu, block it while the panel is open: blse.block_key('ESCAPE'), and react to blse.key_down with 'ESCAPE' and 'game'; unblock it when the panel closes.

blse.hud_input#

blse.hud_input(id, x, y, w, h[, text[, size[, max]]])   # -> 1

A text field the player can type into (a name, a search, a chat line). The player clicks it in cursor mode, or you give it the keyboard with hud_focus.

• id, x, y, w, h: as for hud_box.
• text (str, optional): sets the field's text (UTF-8, cut to max). None (default) keeps the current text; a new field starts empty. Not translated.
• size (int, optional): font height, 8 to 96 pixels; default 20.
• max (int, optional): the longest text in characters, 1 to 1023 (b0.5.36; 255 before); default 64.
• Returns 1. Raises ValueError for bad values (also a text over 4 times max bytes), RuntimeError when the overlay is full or not available.

blse.hud_input('mymod_name', 0.35, 0.45, 0.3, 0.05, '', 20, 32)
blse.hud_cursor(1)
blse.hud_focus('mymod_name')

blse.hud_multiline and blse.hud_hint#

blse.hud_multiline(id[, on])   # -> 1 or 0
blse.hud_hint(id, hint)        # -> 1 or 0

(b0.5.36) hud_multiline lets a text field hold several lines (on 1, the default) or one (0; line breaks become spaces). hud_hint sets a faint text shown while the field is empty, such as "Type a name"; None or '' removes it, a $ text is translated, at most 1020 bytes.

• Both return 1, or 0 if Python has no such element or it is not a text field (or the hint is too long).

blse.hud_multiline('mymod_note', 1)
blse.hud_hint('mymod_note', 'Write a note...')

blse.hud_focus and blse.hud_input_text#

blse.hud_focus([id])        # -> 1 or 0
blse.hud_input_text(id)     # -> str

hud_focus(id) gives one of Python's text fields the keyboard, as a click on it does: 1 if it is a text field of Python's, else 0. hud_focus() (or '') ends text entry if one of Python's fields has it, and returns 1. Changing focus this way sends no events.

hud_input_text(id) returns the field's current text (UTF-8). Raises ValueError if Python has no text field with this id.

name = blse.hud_input_text('mymod_name')

blse.hud_text_changed, blse.hud_text_submit and blse.hud_text_cancel#

Events of text fields. All three have the same payload, in order: id (the field), text (its text now, UTF-8), owner ('python' or a plugin's name).

• blse.hud_text_changed: after each change of the text (a typed character, Backspace, Delete, cut or paste).
• blse.hud_text_submit: Enter was pressed (Ctrl+Enter in a several-line field). The field loses focus; the text stays.
• blse.hud_text_cancel: Escape, or a left click outside the field. The field loses focus; the text stays.

def on_submit(topic, data):
    elem, text, owner = data.split('\0')
    if owner == 'python' and elem == 'mymod_name':
        blse.log('name: ' + text)
        blse.hud_input('mymod_name', 0.35, 0.45, 0.3, 0.05, '')    # empty again
blse.subscribe('blse.hud_text_submit', on_submit)