Module for drawing on top of the game.
Every function here is available only from a trx.events.on_ui_draw handler,
and raises anywhere else: the interface is built afresh each drawn frame, and
there is no scene to add to outside one.
A handler adds to the region the game is building, which it is told the name of. Widgets land in the same stack as the health bars and the item names, so a script cannot draw over them and the player's choice of where each element sits still holds.
Widgets that hold other widgets take the body as a function rather than opening and closing by hand, so a scene stays whole even where the body fails.
Sizes are in canvas units, not screen pixels. trx.ui.canvas reports the
canvas, and trx.ui.safe_area the part of it that is free to draw in.
Text carries the same markup the rest of the game uses, and it is part of this
API: \{small} draws the rest of the line small, \{arrow up} draws an arrow,
and \{button left} draws the button the player has bound.
trx.ui.canvas (trx.ui.Area). The whole canvas. Widget sizes are in these units rather than in screen pixels, and the canvas is 640 by 480 for a 4:3 screen at the default text size. (read-only)trx.ui.safe_area (trx.ui.Area). The part of the canvas that is free to draw in: the canvas, less the margin kept at the edges, less what the game reserves at the top and the bottom for the bars and the text it puts there. (read-only)The direction a stack lays its children out in.
trx.ui.Orientation.VERTICAL = 0trx.ui.Orientation.HORIZONTAL = 1Where a stack puts its children across its width.
trx.ui.HAlign.LEFT = 0trx.ui.HAlign.CENTER = 1trx.ui.HAlign.RIGHT = 2trx.ui.HAlign.SPAN = 3trx.ui.HAlign.DISTRIBUTE = 4Where a stack puts its children down its height.
trx.ui.VAlign.TOP = 0trx.ui.VAlign.CENTER = 1trx.ui.VAlign.BOTTOM = 2trx.ui.VAlign.SPAN = 3trx.ui.VAlign.DISTRIBUTE = 4One of the nine places the interface is built in. A handler is told which one is being built and adds to it, and everything asking for a place is laid out together there rather than over what else asked for it.
The eight around the edge stack what they hold away from the edge they sit at. The middle is what the others leave, and is where a dialog goes.
trx.ui.Region.TOP_LEFT = 0trx.ui.Region.TOP_CENTER = 1trx.ui.Region.TOP_RIGHT = 2trx.ui.Region.LEFT = 3trx.ui.Region.CENTER = 4trx.ui.Region.RIGHT = 5trx.ui.Region.BOTTOM_LEFT = 6trx.ui.Region.BOTTOM_CENTER = 7trx.ui.Region.BOTTOM_RIGHT = 8Which of the game's frames to draw. The look of each follows the menu style the player chose.
trx.ui.FrameStyle.DIALOG = 0trx.ui.FrameStyle.DIALOG_HEAVY = 1trx.ui.FrameStyle.HEADING = 2trx.ui.FrameStyle.SELECTED = 3trx.ui.FrameStyle.OUTLINE = 4Which of the game's bars to draw, which decides its colors.
trx.ui.BarType.LARA_HP = 0trx.ui.BarType.LARA_HP_POISON = 1trx.ui.BarType.LARA_AIR = 2trx.ui.BarType.LARA_STAMINA = 3trx.ui.BarType.LARA_EXPOSURE = 4trx.ui.BarType.ENEMY_HP = 5trx.ui.BarType.ALLY_HP = 6trx.ui.BarType.PROGRESS = 7A rectangle on the canvas, in canvas units, counted from the top left.
Properties:
A reusable UI element drawn over the game.
A widget holds its own state. Give it signals instead of fixed values, then
register those signals with wakes_on. The widget remeasures
only when a registered signal changes.
Register every signal that the widget reads. Otherwise the widget can keep a stale cached size.
Methods:
widget:is_shown()
Returns whether the widget participates in layout.
A widget that is not shown keeps no room and leaves no gap. A hidden widget keeps its room but draws nothing.
Returns: boolean. Whether it draws.
widget:measure()
How much room the widget wants.
Returns:
widget:paint(x, y, w, h)
Draws the widget in an assigned box.
trx.ui.regions.place calls this automatically. Custom layout code can call it
during trx.events.on_ui_paint.
Parameters:
widget:release()
Detaches the widget and its children from registered signals.
Signals keep references to their listeners. Release temporary widgets when they are no longer needed. Remove a placed widget from its region before releasing it.
Returns: boolean. Whether it was still listening to anything.
widget:wake()
Invalidates the widget's cached size manually.
Returns: trx.ui.Widget. The same widget.
widget:wakes_on(...)
Registers the signals that invalidate the widget's cached size.
When one of these signals changes, the widget and its parents are measured again on the next layout pass.
Parameters:
... (trx.signal.Signal). The signals the widget reads.Returns: trx.ui.Widget. The same widget, for method chaining.
trx.ui.primitive
Low-level drawing calls and layout reservations.
Use trx.ui.widgets for normal UI. Use these primitives only when building a
custom widget. Primitive drawing does not affect region layout unless code
reserves space first.
Drawing calls are available only during trx.events.on_ui_paint. They report
an error at any other time.
trx.ui.widgets
The widgets a script builds its screen from.
A widget is created once and kept. Give it signals instead of fixed values, then
register those signals with trx.ui.Widget:wakes_on.
Put a widget on screen with trx.ui.regions.place.
trx.ui.regions
Places script widgets on the screen.
The screen has nine regions. Engine UI uses those regions for bars, overlay text, inventory-ring hints, and dialogs. A widget placed in a region stacks after the engine UI in that region.
Place a widget once when the script loads. Use signals when the widget must change later.
trx.ui.primitive.reserve(region, w, h)
Reserves space in a region and returns a slot for it.
The reservation is stacked with the engine UI in that region. Reserve space
during trx.events.on_ui_draw, then read the assigned box during
trx.events.on_ui_paint.
A slot is valid only for the scene that created it.
Parameters:
region (trx.ui.Region). Which region to keep room in.w (number). How wide, in canvas units.h (number). How tall, in canvas units.Returns: integer. The slot.
trx.ui.primitive.slot_box(slot)
Returns the box assigned to a reservation by the last layout.
Parameters:
Returns:
nil when the slot is no longer valid.trx.ui.primitive.measure_text(text, [scale])
Measures one line of text. Available at any time.
Parameters:
Returns:
trx.ui.primitive.text(text, x, y, [scale], [z])
Draws one line of text on the canvas.
Parameters:
trx.ui.primitive.to_screen(length)
Converts a canvas length to screen pixels.
The canvas is a fixed 640x480 grid, and the screen size depends on the player
settings and window. Use this with to_canvas when geometry
must align to whole screen pixels, such as an even border.
Parameters:
Returns: number. The same length in screen pixels.
trx.ui.primitive.to_canvas(pixels)
Converts a screen-pixel length to canvas units.
Use this with to_screen when geometry must align to whole
screen pixels.
Parameters:
Returns: number. The same length in canvas units.
trx.ui.primitive.panel(x, y, z, w, h, style)
Draws the box the game draws behind a dialog, in the style the player chose.
The look follows the menu style setting, so a panel drawn this way matches the game's own dialogs rather than standing apart from them.
Parameters:
x (number). The left edge.y (number). The top edge.z (integer). The draw order.w (number). The width.h (number). The height.style (trx.ui.FrameStyle). Which of the game's frames to draw.trx.ui.primitive.quad(x, y, z, w, h, color)
Draws a rectangle of one color.
Parameters:
x (number). The left edge.y (number). The top edge.z (integer). The draw order.w (number). The width.h (number). The height.color (trx.math.Color). What color to fill it with.trx.ui.primitive.gradient_quad(x, y, z, w, h, tl, tr, bl, br)
Draws a rectangle whose corners each carry a color.
Parameters:
x (number). The left edge.y (number). The top edge.z (integer). What to draw in front of.w (number). The width.h (number). The height.tl (trx.math.Color). The top-left color.tr (trx.math.Color). The top-right color.bl (trx.math.Color). The bottom-left color.br (trx.math.Color). The bottom-right color.trx.ui.primitive.image(path, x, y, w, h, [opacity])
Draws an image file in a box on the canvas.
The image is looked for where the game keeps its images, and stretches to fill the box, so a box of the image's own shape keeps that shape. The image draws under everything else the canvas holds, whatever order the calls come in.
Returns whether the game has such an image, so a script can leave the space alone where it does not.
Parameters:
path (string). The image file, named from the images directory.x (number). The left edge.y (number). The top edge.w (number). The width.h (number). The height.opacity (number, optional). How solid the image is, from 0 to 1. 1 by default.Returns: boolean. Whether the image was there to draw.
Example:
trx.ui.primitive.image("uklogo.pak", 64, 0, 512, 256)
trx.ui.primitive.sprite_count(object)
Reports how many sprites an object has.
An object the level did not load has none, so this answers whether there is
anything to draw before sprite is asked to draw it.
Parameters:
object (trx.catalog.objects). The sprite object to count.Returns: integer. How many sprites it has.
trx.ui.primitive.sprite_bounds(object, sprite_num)
Reports the edges of one sprite of an object, in canvas units at a scale of one.
The edges sit around the point the sprite is drawn at, so both left and top are usually negative. Multiply them by the scale the sprite is drawn at.
Raises where the level did not load the object, so check
trx.objects.get(object).loaded first.
Parameters:
object (trx.catalog.objects). The sprite object to read from.sprite_num (integer). Which sprite of the object to read, counted from 0.Returns:
trx.ui.primitive.sprite(object, sprite_num, x, y, z, scale, color)
Draws one sprite of an object on the canvas.
Raises where the level did not load the object, so check
trx.objects.get(object).loaded first.
Parameters:
object (trx.catalog.objects). The sprite object to draw from.sprite_num (integer). Which sprite of the object to draw, counted from 0.x (number). The left edge.y (number). The top edge.z (integer). The draw order.scale (number). Multiplies the sprite size. At 1 the sprite draws at its own size on the canvas.color (trx.math.Color). What color to tint it with.Example:
trx.ui.primitive.sprite(
trx.catalog.objects.assault_digits, 3, 100, 20, 0, 1,
trx.math.color("ffffff"))
trx.ui.primitive.gradient_sprite(object, sprite_num, x, y, z, scale, tl, tr, bl, br)
Draws one sprite of an object, with a color at each corner.
Raises where the level did not load the object, so check
trx.objects.get(object).loaded first.
Parameters:
object (trx.catalog.objects). The sprite object to draw from.sprite_num (integer). Which sprite of the object to draw, counted from 0.x (number). The left edge.y (number). The top edge.z (integer). The draw order.scale (number). Multiplies the sprite size. At 1 the sprite draws at its own size on the canvas.tl (trx.math.Color). The top-left color.tr (trx.math.Color). The top-right color.bl (trx.math.Color). The bottom-left color.br (trx.math.Color). The bottom-right color.trx.ui.widgets.Label(settings)
A line of text. Use a signal for text that changes.
Parameters:
Returns: trx.ui.Widget. The label.
trx.ui.widgets.Image(settings)
A picture from an image file, at a size the script gives.
The widget keeps its room even where the game ships no such image, so a screen built around it does not move when the image is missing.
Parameters:
settings (table). The image settings.
Keys:
path (any). The image file, named from the images directory, or a signal carrying it.w (number). The width, in canvas units.h (number). The height, in canvas units.opacity (any, optional). How solid the image is, from 0 to 1, or a signal that holds that value. 1 by default.shown (any, optional). Whether the image is shown, or a signal that holds that value.Returns: trx.ui.Widget. The image.
trx.ui.widgets.Bar(settings)
One of the game's bars, drawn with the player's bar settings.
The bar uses the same theme, border, and fill bands as the engine UI. Use a signal for a fill value that changes.
Parameters:
settings (table). The bar settings.
Keys:
type (trx.ui.BarType). The bar theme to use.value (any). The fill amount from 0 to 1, or a signal that holds it.w (number, optional). The width, in canvas units. The game's own by default.h (number, optional). The height, in canvas units. The game's own by default.shown (any, optional). Whether the bar is shown, or a signal that holds that value.Returns: trx.ui.Widget. The bar.
trx.ui.widgets.Resize(settings)
Gives a child widget an explicit size.
Use h_bars when a widget must match the height of the game's bars after the player's bar scale is applied.
Parameters:
settings (table). The resize settings.
Keys:
child (trx.ui.Widget). The child widget.w (number, optional). The width, in canvas units. Its own by default.h (number, optional). The height, in canvas units. Its own by default.h_bars (number, optional). The height in bar heights. This overrides the plain height.shown (any, optional). Whether the resized widget is shown, or a signal that holds that value.Returns: trx.ui.Widget. The resized widget.
trx.ui.widgets.Pad(settings)
Keeps a margin around a child widget.
The margin is in canvas units at the default text size, and follows the text scale the same way the widgets inside it do.
Parameters:
settings (table). The padding settings.
Keys:
child (trx.ui.Widget). The child widget.x (number, optional). The margin at the left and the right. 0 by default.y (number, optional). The margin at the top and the bottom. 0 by default.shown (any, optional). Whether the padded widget is shown, or a signal that holds that value.Returns: trx.ui.Widget. The padded widget.
trx.ui.widgets.Frame(settings)
Draws one of the game's frames behind a child widget.
The frame takes the whole box the child asks for, so pad the child where the text would otherwise sit against the edge.
Parameters:
settings (table). The frame settings.
Keys:
child (trx.ui.Widget). The child widget.style (trx.ui.FrameStyle, optional). Which frame to draw. The dialog box by default.z (integer, optional). The draw order. 160 by default, which is behind text.shown (any, optional). Whether the framed widget is shown, or a signal that holds that value.Returns: trx.ui.Widget. The framed widget.
trx.ui.widgets.Fit(settings)
Shrinks a child widget until it is within the screen.
Text keeps the size the player chose while it fits, and everything below this widget is drawn smaller where it does not. A dialog that has to hold a fixed body on a small screen wants this; a line of text that can simply wrap does not.
Parameters:
settings (table). The fit settings.
Keys:
child (trx.ui.Widget). The child widget.shown (any, optional). Whether the fitted widget is shown, or a signal that holds that value.Returns: trx.ui.Widget. The fitted widget.
trx.ui.widgets.Row(settings)
A widget with a left and right arrow beside a child widget.
Unlit arrows stay hidden but keep their room, so the child widget does not move when arrows appear or disappear.
Parameters:
settings (table). The row settings.
Keys:
child (trx.ui.Widget). The child widget placed between the arrows.left (any). Whether the left arrow is lit, or a signal that holds that value.right (any). Whether the right arrow is lit, or a signal that holds that value.spacing (number, optional). The gap between each arrow and the child widget. 15 by default.shown (any, optional). Whether the row is shown, or a signal that holds that value.Returns: trx.ui.Widget. The row.
trx.ui.widgets.Stack(settings)
Lays widgets out one after another.
Widgets that are not shown take no room and leave no gap.
Parameters:
settings (table). The stack settings.
Keys:
children (a list of table). The widgets, in the order they are laid out.orientation (trx.ui.Orientation, optional). The layout direction. Vertical by default.spacing (number, optional). The gap between one and the next. 0 by default.align (trx.ui.HAlign, optional). Where a narrower child sits in a vertical stack.v_align (trx.ui.VAlign, optional). Where a shorter child sits in a horizontal stack.shown (any, optional). Whether the stack is shown, or a signal that holds that value.Returns: trx.ui.Widget. The stack.
trx.ui.widgets.Digits(settings)
A line of text drawn from an object's sprites, one sprite per character.
The object supplies the ten digits, then a colon, a full stop, a T and an
s, in that order, which is how the assault course digits are laid out. A
space and a dash move the pen without drawing.
The widget measures nothing where the level did not load the object, so a script can keep it on screen for a level that has no digits.
Parameters:
settings (table). The digit settings.
Keys:
object (trx.catalog.objects). The sprite object to draw the characters from.text (any). The text, or a signal carrying it.color (any). What color to draw the characters in, or a signal carrying one.color_bottom (any, optional). The color the characters fade to down their height. The main color by default, which draws them flat.mark_color (any, optional). What color to draw the T in. The main color by default.mark_color_bottom (any, optional). The color the T fades to. Its own color by default.shown (any, optional). Whether the digits are shown, or a signal that holds that value.Returns: trx.ui.Widget. The digits.
Example:
trx.ui.widgets.Digits({
object = trx.catalog.objects.assault_digits,
text = timer:map(format_time),
color = trx.math.color("ffffff"),
})
trx.ui.regions.place(region, widget)
Places a widget in a region.
If the region argument is a signal, the widget moves when the signal changes.
Parameters:
region (any). The target region, or a signal that holds one.widget (trx.ui.Widget). The widget to place.Example:
trx.ui.regions.place(trx.ui.Region.TOP_LEFT, health_bar)
trx.ui.regions.remove(widget)
Removes a widget from its region.
Use this for temporary widgets. Widgets owned by a level script are removed
when the level ends. Call trx.ui.Widget:release separately to detach their
signal listeners.
Parameters:
widget (trx.ui.Widget). The widget to remove.Returns: boolean. Whether the widget was in a region.
trx.ui.regions.fallback(region, widget)
Sets the widget to draw when a region has no visible content.
A region with only non-shown widgets draws nothing. A fallback can reserve that empty place instead, for example the corner arrows shown when a bar is off screen. Each region has at most one fallback.
Parameters:
region (trx.ui.Region). The target region.widget (trx.ui.Widget). The fallback widget.