Rewrite Lua UI interface

[rr-]

Checklist

• I have read the coding conventions
• I have added a changelog entry about what my pull request accomplishes, or it is an internal change

Description

Adds a new Lua module, trx.signal, and rewrites trx.ui around it. Signals track values and report when they change. Widgets are built once and update only when their signals change, instead of being redrawn every frame. Crucially, widgets stick around once added, and stay in place until removed with trx.ui.regions.remove, which is different from what we have in the C API. We still emit primitive draws on every frame, but these are only direct draws (put text on this X,Y; put a gradient rectangle there) – the Lua widgets orchestrate those with as few changes as possible across, and are orthogonal to the C widgets.

The screen is now split into nine named regions across three bands, replacing the old six. Regions reserve space for script widgets alongside the engine UI, preventing them from overlapping each other.

-- A signal reports when its value changes. The engine owns some; a script
-- polls its own once a tick, and reads a setting as one.
local hp = trx.lara.signals.hp
local music = trx.signal.config("audio.enable_music")
local in_play = trx.signal.polled(function()
  return trx.game.is_playable and not trx.cutscenes.is_playing
end)

-- Signals derive from each other, and combine with `&`, `|` and `~`.
local fill = trx.signal.combine(hp, trx.lara.signals.max_hp, function(hp, max_hp)
  return hp / max_hp
end)
local shown = in_play & ~music

-- A widget is built once and follows the signals it was given.
local panel = trx.ui.widgets.Stack({
  children = {
    trx.ui.widgets.Label({ text = hp:map(tostring) }),
    trx.ui.widgets.Bar({ type = trx.ui.BarType.LARA_HP, value = fill }),
  },
  spacing = 2,
  align = trx.ui.HAlign.CENTER,
  shown = shown,
})

trx.ui.regions.place(trx.ui.Region.TOP_LEFT, panel)

-- A script that lays its own out asks a region for room, then draws into it.
local slot
trx.events.on_ui_draw(function(region)
  if region == trx.ui.Region.BOTTOM_RIGHT then
    local w, h = trx.ui.primitive.measure_text("00:00:00")
    slot = trx.ui.primitive.reserve(region, w, h)
  end
end)

trx.events.on_ui_paint(function()
  local x, y = trx.ui.primitive.slot_box(slot)
  if x ~= nil then
    trx.ui.primitive.text("00:00:00", x, y)
  end
end)

-- `trx.events.on_tick` and `trx.signal.tick` happen once per game tick,
-- whether a level is being played or a menu is open.
trx.events.on_tick(function() end)

A level script's widgets and signals last until the level ends, just like its event handlers. A global script's last for the whole session unless stopped early.

No migration notice, since the previous UI Lua integration was never released.

The Race for the Iris clock is the first widget using this system and now persists instead of being redrawn every frame. Nothing else uses the new system yet.

Resolves #5351 / TRX185

Testing

• The clock appears once Von Croy sets off and counts up
• The clock holds still while a cutscene plays
• The clock stays on screen across a save and a load
• The clock leaves the screen for good when the finish is reached
• Bars that are configured to appear in the top-center region do not overlap the clock

[github-actions]

Download the built assets for this pull request:

• TRX-1.10.2-360-g98f2c99-Linux.zip
• TRX-1.10.2-360-g98f2c99-TombEditor.zip
• TRX-1.10.2-360-g98f2c99-Windows.zip

[aredfan]

Issues:

• The clock stops counting when saving and reloading.
• The clock persists onscreen when issuing commands such as /play 2 or /title.
• When Lara is sliding down the slope at the start of the 2nd level, save and reload, and the clock doesn't appear after the intro cutscene.

[aredfan]

New issue:

• At the start of level 2, there is a collision that prevents Lara from reaching the bottom of the slope.

[rr-]

@aredfan I think this is unrelated and also should be happening on develop - can we confirm?

[aredfan]

@aredfan I think this is unrelated and also should be happening on develop - can we confirm?

I just had a quick look at the latest dev snapshot, it seems the bug doesn't manifest there.

[rr-]

Sorry – fixed all :happybat: