Server Monitor — computercraft.petroid.xyz

A CC:Tweaked peripheral block that exposes server performance metrics, online player info, and player lookup (UUID to name and back). Automatically pushes events when players join or leave the server.

Peripheral Type

ptr_utilities:server_monitor

Setup

Craft a Server Monitor
Place it next to a CC:Tweaked computer
Wrap it: local mon = peripheral.find("ptr_utilities:server_monitor")

Events

`player_join`

Fired when any player joins the server.

local event, name, uuid, firstTimeThisSession = os.pullEvent("player_join")
-- name                 = player's username
-- uuid                 = player's UUID string
-- firstTimeThisSession = true if the player hasn't joined since server start

`player_first_join`

Fired when a player joins for the very first time (not in the persistent known-players cache).

local event, name, uuid = os.pullEvent("player_first_join")
-- name = player's username
-- uuid = player's UUID string

`player_leave`

Fired when any player leaves the server.

local event, name, uuid = os.pullEvent("player_leave")
-- name = player's username
-- uuid = player's UUID string

Methods

Performance Metrics

Method	Returns	Description
`getTPS()`	double	Server ticks per second (20.0 = perfect).
`getMSPT()`	double	Milliseconds per tick (50.0 = perfect).
`getMemory()`	table	JVM memory info: `used`, `max`, `percentage`.
`getCPUUsage()`	double	System CPU usage as percentage (0-100). Returns -1 if unavailable.

Memory table:

{
    used       = 1234567,   -- bytes
    max        = 8589934592,
    percentage = 14.4
}

Online Players

Method	Returns	Description
`getPlayers()`	table[]	List of online players, each with `name`, `uuid`, `ping`.
`getPlayerPing(uuid)`	int	Ping in milliseconds for the given player.

Player entry:

{
    name = "Petroid_",
    uuid = "550e8400-e29b-41d4-a716-446655440000",
    ping = 42
}

Player Lookup (UUID and Name)

Method	Returns	Description
`uuidToName(uuid)`	string\|nil	Resolve a UUID to a username. Checks online players first, then the persistent cache.
`nameToUuid(name)`	string\|nil	Resolve a username to a UUID string. Checks online players first, then the persistent cache.

First-Time Joiners

Method	Returns	Description
`getFirstTimeJoiners()`	string[]	UUIDs of players who joined for the first time this server session.

Example: TPS monitor

local mon = peripheral.find("ptr_utilities:server_monitor")

while true do
    local tps = mon.getTPS()
    local mspt = mon.getMSPT()
    local mem = mon.getMemory()
    print(string.format("TPS: %.1f | MSPT: %.1f | Mem: %.1f%%",
        tps, mspt, mem.percentage))
    os.sleep(5)
end

Example: Welcome new players

local mon = peripheral.find("ptr_utilities:server_monitor")

while true do
    local event, name, uuid = os.pullEvent("player_first_join")
    print("FIRST JOIN: " .. name .. " (" .. uuid .. ")")
    -- Could send a welcome message, give items, trigger a door, etc.
end

Example: Online player list

local mon = peripheral.find("ptr_utilities:server_monitor")

local players = mon.getPlayers()
for _, p in ipairs(players) do
    print(p.name .. " - " .. p.ping .. "ms")
end