wolfhacklua API 1.1 Forum

Session timer

A small widget showing the time of day, how long the script has been running this session, and how long you have spent in a match. It remembers the total across sessions. Drag it by its top strip while the menu is open.

Permissions: none. API: 1.0.

Session timer v1.0.0 no permissions
Download session-timer.lua
session-timer.lualua
--@name Session timer
--@version 1.0.0
--@author wolfhack docs
--@api 1.0
--@description A draggable widget with the clock, the time since the script started, and the time spent in a match. The total across sessions is saved.
-- No permissions needed. Drag the widget by its top strip while the menu is open.

local W, H = 176, 64

local session_start = time.now()   -- the session "starts" when the script loads (or when you press Reset on the tab)
local match_total = 0              -- seconds spent in matches this session
local match_since = nil            -- time.now() when the current match began
local lifetime = store.get("lifetime", 0)   -- seconds across all sessions, saved
local last_save = time.now()

local function fmt(sec)
  sec = math.max(0, math.floor(sec))
  local h, m, s = sec // 3600, (sec % 3600) // 60, sec % 60
  if h > 0 then return string.format("%d:%02d:%02d", h, m, s) end
  return string.format("%02d:%02d", m, s)
end

local function match_seconds()
  return match_total + (match_since and (time.now() - match_since) or 0)
end

-- The ingame event fires when a match starts or ends, not at load, so the first frame reads the current state once.
events.once("frame", function()
  if data.snapshot().in_game then match_since = time.now() end
end)

events.on("ingame", function(inside)
  if inside then
    match_since = time.now()
  elseif match_since then
    match_total = match_total + (time.now() - match_since)
    match_since = nil
  end
end)

-- Save the running total now and then, and when the script goes away.
local function save()
  lifetime = lifetime + (time.now() - last_save)
  last_save = time.now()
  store.set("lifetime", lifetime)
end
timer.every(30, save)
events.on("unload", save)

ui.widget{
  id = "timer", name = "Session timer", size = { W, H }, pos = { 0.02, 0.4 },
  draw = function(w)
    draw.rect(0, 0, w.w, w.h, color.alpha(0x101418FF, store.get("opacity", 0.86)), 6)
    draw.rect(0, 6, 3, w.h - 12, store.get("accent", 0x750851FF))
    local pattern = store.get("h24", true) and "%H:%M:%S" or "%I:%M:%S %p"
    draw.text(14, 10, 0xF0F0F0FF, os.date(pattern, time.wall()), { size = 18 })
    draw.text(14, 34, 0xA8B0B8FF, "session   " .. fmt(time.now() - session_start), { size = 12 })
    draw.text(14, 48, 0xA8B0B8FF, "in match  " .. fmt(match_seconds()), { size = 12 })
  end,
}

ui.tab("Session timer", function()
  ui.card("Widget", function()
    ui.toggle("h24", "24-hour clock", true)
    ui.slider("opacity", "Background opacity", 0, 1, 0.86)
    ui.color("accent", "Accent line", 0x750851FF)
  end, { width = 0.5 })

  ui.card("Time", function()
    ui.note("Total time with this script on: " .. fmt(lifetime + (time.now() - last_save)))
    if ui.button("Reset this session") then
      session_start = time.now()
      match_total = 0
      if match_since then match_since = time.now() end
    end
    if ui.button("Clear the saved total", { variant = "danger" }) then
      lifetime = 0
      last_save = time.now()
      store.set("lifetime", 0)
    end
  end, { width = 0.5 })
end)

How it works#

A widget. ui.widget{ id, name, size, pos, draw } registers a box on the overlay. Its draw function draws in widget coordinates, with (0, 0) at the widget's top left, and the drawing is clipped to the widget. pos = { 0.02, 0.4 } is a fraction of the free space of the screen, so the widget sits in the same relative place at any resolution; the user's drag is saved automatically.

Time since the script started. time.now() is the seconds since the script loaded. The Reset button only moves session_start, so the displayed session time restarts from zero.

Time in matches. The ingame event fires when a match starts or ends. It does not fire at load, so a script switched on in the middle of a match would miss the start; the script therefore reads data.snapshot().in_game once, on its first frame (events.once("frame", ...)), to pick up a match that is already running. The ingame handler then records match_since when a match begins and adds the elapsed time to match_total when it ends. While a match is running, match_seconds() adds the open interval.

Saving. timer.every(30, save) writes the running total every 30 seconds, and the unload handler writes it a last time. store.set("lifetime", ...) is saved to disk by the host. If the overlay crashes you lose at most 30 seconds.

Buttons. ui.button(label, options) returns true on the frame it is clicked, so it is used directly in an if. The second button uses the "danger" variant for a destructive action.

Cleanup. The timer, the event handlers, the widget and the tab are removed by the host. The unload handler is the only cleanup the script needs to do itself.

Ideas to extend it#

  • Show the time since the last map change using the map event.
  • Add a ui.keybind and the input permission to pause the timer.
  • Format the lifetime total in hours with string.format("%.1f h", lifetime / 3600).
API 1.1 · source docs-src/pages/examples/session-timer.md