hub-stats.lua Verlihub User Count Display Bot

Created: 2026/07/02 19:41:27 America/Chicago
By: admin
Views: 0

The hub-stats.lua script builds a bot-like user-list entry that displays current hub statistics. A hub can show online users, operators, total share, or a compact status marker without running a separate external bot process.

This script focuses on display only. It reads simple counters, builds a short name such as !_Stats_128U_4Ops, and leaves expensive work outside the hub process.

What This Script Does

The script builds a display name from configured hub statistics.

Example display names:

!_Users_128
!_Hub_128_Online
!_Stats_128U_4Ops
!_Share_24.5TB

Common uses include:

  • Showing current users online.
  • Showing operators online.
  • Showing total hub share when the Lua API exposes it cheaply.
  • Showing peak users when your build exposes that counter.
  • Showing registered users when your build exposes that counter.
  • Creating a compact hub status marker.
  • Adding a live stats entry to the user list.

The exact counters available depend on the Verlihub Lua plugin API exposed by your Verlihub version.

Requirements

This script requires:

  • Verlihub installed and running.
  • The Verlihub Lua plugin installed.
  • The Lua plugin enabled in Verlihub.
  • Permission to load and unload Lua scripts.
  • A writable script directory for Verlihub Lua files.
  • A Verlihub Lua build that can expose user-list display data or call a name-generation function from a display entry.

Before loading the script, confirm that the Lua plugin is active:

!pluglist

If the Lua plugin is not listed, load or enable it first from the parent Lua setup article.

Use a dedicated script directory:

mkdir -p /PATH/TO/HUB/scripts

Place the script at:

/PATH/TO/HUB/scripts/hub-stats.lua

For production systems, only trusted administrators or the Verlihub service user should write to that directory. Do not use world-writable permissions.

Load And Unload Commands

Load the script:

!luaload /PATH/TO/HUB/scripts/hub-stats.lua

Unload the script:

!luaunload /PATH/TO/HUB/scripts/hub-stats.lua

If you edit the script, unload it and load it again:

!luaunload /PATH/TO/HUB/scripts/hub-stats.lua
!luaload /PATH/TO/HUB/scripts/hub-stats.lua

Use the full absolute path unless your Verlihub Lua plugin configuration supports relative paths.

Script Code

-- Script: hub-stats.lua
-- Purpose: Displays hub statistics as a bot-like user-list entry.
-- Scope: Lightweight display bot only.
-- Notes: Available statistics depend on the Verlihub Lua API exposed by your build.

name = ""
class = 3
description = "Hub Stats Bot"
speed = "100"
email = ""
share = "0"
prefix = "!_Stats_"
postfix = ""
interval = 60
counter = 0
show_users = true
show_ops = true
show_share = false

function SafeCall(callback, fallback)
    local ok, result = pcall(callback)

    if ok and result ~= nil then
        return result
    end

    return fallback
end

function FormatShare(bytes)
    local value = tonumber(bytes)

    if value == nil then
        return "0B"
    end

    if value >= 1099511627776 then
        return string.format("%.1fTB", value / 1099511627776)
    end

    if value >= 1073741824 then
        return string.format("%.1fGB", value / 1073741824)
    end

    if value >= 1048576 then
        return string.format("%.1fMB", value / 1048576)
    end

    if value >= 1024 then
        return string.format("%.1fKB", value / 1024)
    end

    return tostring(value) .. "B"
end

function GetUserCount()
    -- Replace this function body if your Verlihub Lua API uses a different call.
    return SafeCall(function()
        return VH:GetUsersCount()
    end, 0)
end

function GetOperatorCount()
    -- Replace this function body if your Verlihub Lua API uses a different call.
    return SafeCall(function()
        return VH:GetOperatorsCount()
    end, 0)
end

function GetTotalShare()
    -- Replace this function body if your Verlihub Lua API uses a different call.
    return SafeCall(function()
        return VH:GetTotalShare()
    end, 0)
end

function GetStatsText()
    local parts = {}

    if show_users then
        table.insert(parts, tostring(GetUserCount()) .. "U")
    end

    if show_ops then
        table.insert(parts, tostring(GetOperatorCount()) .. "Ops")
    end

    if show_share then
        table.insert(parts, FormatShare(GetTotalShare()))
    end

    if table.getn(parts) == 0 then
        return "Online"
    end

    return table.concat(parts, "_")
end

function GetName()
    return prefix .. GetStatsText() .. postfix
end

Configuration Options

name

name = ""

The base name value for the bot-like entry.

In this script, the visible name is generated by GetName(), so name can usually stay empty.

class

class = 3

Controls the displayed class or profile level of the bot-like entry.

The meaning of class values depends on the hub configuration. Use a value that matches how the stats entry should appear in the user list.

description

description = "Hub Stats Bot"

The description shown for the bot-like entry.

Examples:

description = "Hub Stats Bot"
description = "Users Online"
description = "Hub Status"
description = "Live Hub Stats"

speed

speed = "100"

The connection speed value displayed for the bot-like entry. This is cosmetic. It does not control how often the script updates.

email

email = ""

The email field shown for the bot-like entry. Leave it empty unless you want to display a contact address.

share

share = "0"

The share size displayed for the bot-like entry. For a stats display bot, 0 is appropriate unless you want the entry to show a decorative share value.

prefix

prefix = "!_Stats_"

Text placed before the generated stats.

Examples:

prefix = "!_Stats_"
prefix = "!_Hub_"
prefix = "!_Users_"
prefix = "[Stats] "

Choose a prefix that sorts clearly in the hub user list.

postfix

postfix = ""

Text placed after the generated stats.

Examples:

postfix = ""
postfix = "_Online"
postfix = "_Hub"

interval

interval = 60

Controls how often the display entry should update.

Recommended values:

ValueMeaning
30More responsive. Useful for busy hubs.
60Recommended default.
300Lower activity. Useful for quiet hubs.

Avoid low values. Hub statistics do not need to update every second.

counter

counter = 0

Internal counter used by the script. Do not change this unless you are modifying the script logic.

show_users

show_users = true

Controls whether the display name includes the current online user count.

Example output:

!_Stats_128U

show_ops

show_ops = true

Controls whether the display name includes the current operator count.

Example output:

!_Stats_128U_4Ops

show_share

show_share = false

Controls whether the display name includes total hub share.

Example output:

!_Stats_128U_4Ops_24.5TB

Enable this only when your Verlihub Lua API exposes a reliable total share value.

API Compatibility Notes

The example script uses these functions:

VH:GetUsersCount()
VH:GetOperatorsCount()
VH:GetTotalShare()

Your Verlihub Lua plugin version may expose different function names. If the script loads but always displays zero, adjust the API calls used by the counter functions.

The main functions to edit are:

function GetUserCount()
    return SafeCall(function()
        return VH:GetUsersCount()
    end, 0)
end

function GetOperatorCount()
    return SafeCall(function()
        return VH:GetOperatorsCount()
    end, 0)
end

function GetTotalShare()
    return SafeCall(function()
        return VH:GetTotalShare()
    end, 0)
end

Replace those calls with the functions supported by your Verlihub Lua plugin version.

Example Configurations

User Count Only

prefix = "!_Users_"
postfix = "_Online"
interval = 60
show_users = true
show_ops = false
show_share = false

Example display:

!_Users_128U_Online

Users And Operators

prefix = "!_Stats_"
postfix = ""
interval = 60
show_users = true
show_ops = true
show_share = false

Example display:

!_Stats_128U_4Ops

Total Share Display

prefix = "!_Share_"
postfix = ""
interval = 300
show_users = false
show_ops = false
show_share = true

Example display:

!_Share_24.5TB

Compact Hub Status

prefix = "!_Hub_"
postfix = ""
interval = 60
show_users = true
show_ops = true
show_share = true

Example display:

!_Hub_128U_4Ops_24.5TB

For most hubs, start with users and operators only:

prefix = "!_Stats_"
postfix = ""
interval = 60
show_users = true
show_ops = true
show_share = false

This keeps the display short enough for normal user lists.

If the hub user list is crowded, use a shorter display:

prefix = "!_U_"
postfix = ""
interval = 60
show_users = true
show_ops = false
show_share = false

If total share calculation is expensive or unreliable in your Verlihub version, keep it disabled:

show_share = false

Testing The Script

After loading the script, check the hub user list for the generated stats entry.

Confirm that:

  • The entry appears only once.
  • The displayed user count is correct.
  • The displayed operator count is correct.
  • Total share displays correctly if enabled.
  • The name is not too long for the user list.
  • The update interval is reasonable.
  • The entry disappears after unloading the script.
  • Reloading the script does not create duplicates.

If the display always shows zero, review the API compatibility section.

Troubleshooting

The Script Does Not Load

Check that the Lua plugin is active:

!pluglist

Check the file path:

!luaload /PATH/TO/HUB/scripts/hub-stats.lua

Use the absolute path if relative paths do not work.

Stats Always Show Zero

This usually means the Lua API function names do not match your Verlihub plugin version.

Check the functions used in:

GetUserCount()
GetOperatorCount()
GetTotalShare()

Then replace the example VH:* calls with the functions supported by your installation.

Entry Name Is Too Long

Disable some fields or shorten the prefix.

Example:

prefix = "!_S_"
show_share = false

Display Updates Too Often

Increase the interval.

Recommended:

interval = 60

For quiet hubs:

interval = 300

Duplicate Entries Appear

Unload the script:

!luaunload /PATH/TO/HUB/scripts/hub-stats.lua

Then load it again:

!luaload /PATH/TO/HUB/scripts/hub-stats.lua

If duplicates continue, restart the Lua plugin or Verlihub service during a maintenance window.

Safety Notes

This script should stay lightweight. Do not add:

  • External HTTP requests.
  • Database queries on every update.
  • File scanning.
  • Long loops.
  • Blocking sleep calls.
  • Per-user expensive calculations.

Stats display scripts should read simple hub counters and update the display name. If a value is expensive to calculate, cache it outside the hub process.

Maintenance Notes

Keep a backup before changing the script:

cp /PATH/TO/HUB/scripts/hub-stats.lua /PATH/TO/HUB/scripts/hub-stats.lua.bak

If using Git:

cd /PATH/TO/HUB/scripts
git add hub-stats.lua
git commit -m "Update hub-stats.lua settings"

When changing only the prefix, postfix, interval, or enabled stats, no logic changes are required.

Suggested Future Improvements

Possible later versions could add:

  • Peak user count display.
  • Registered user count display.
  • Hub uptime display.
  • Total share display by unit.
  • Separate display entries for users and share.
  • Operator-only stats command.
  • Daily high-water mark tracking.
  • File-based stats snapshot logging.

Add only the statistics that users or operators will read. Too much information makes the user-list entry harder to scan.

Parent Page

Verlihub Lua Script Library

Lua scripts for Verlihub display bots, helper commands, timed messages, user-list entries, validation helpers, and small hub automation tasks.