Violet

Profiles

On this page

The core.profiles module lets a script read the user's saved settings profiles and switch the session between them — the same profiles shown in the web menu's profile bar.

Profile metadata (id and name) is mirrored on the client and kept up to date as profiles are created, renamed, or deleted, so reading the list or the active profile is instant and safe to call every tick — there is no round-trip to the server. Switching a profile applies that profile's full saved settings, which takes a moment to propagate.

Functions

core.profiles.list() -> table

Returns an array of the user's settings profiles, ordered as in the web menu. Each entry is a table:

FieldTypeDescription
idnumberStable profile id. Pass this to switch() to avoid name clashes.
namestringProfile name as shown in the web menu.
activebooleantrue for the profile currently applied to this session.

Reads from the local metadata cache, so it returns immediately.

lua
for _, p in ipairs(core.profiles.list()) do
    core.log((p.active and "* " or "  ") .. p.name .. "  (#" .. p.id .. ")")
end

core.profiles.get_active() -> table | nil

Returns the profile currently applied to this session as { id = number, name = string }, or nil if no profile is active.

lua
local active = core.profiles.get_active()
core.log("Active profile: " .. (active and active.name or "(none)"))

core.profiles.switch(profile: string | number) -> boolean

Switches the session to a saved profile, identified by name or by id. Returns true if the profile exists and the switch has started (or it is already the active profile), or false if the name/id isn't found or a switch is already in progress.

Tip

Pass a name for readability (core.profiles.switch("Bossing")), or an id from list() when profile names might collide.

Switching is asynchronous

switch() returning true means the swap was accepted, not that the new settings are live yet — the profile's full settings load and apply a moment later. While a switch is in flight, further switch() calls return false until it finishes (reads stay instant). To act once the swap lands, poll get_active() until it reports your target profile.

lua
if not core.profiles.switch("Bossing") then
    core.log_error("Switch rejected — unknown profile, or a switch is already running")
end

Example: report profile changes

Logs the profile list once on load, then reports whenever the active profile changes — whether the swap came from this script, another script, or the web menu.

lua
plugin = {
    name        = "Profile Watcher",
    version     = "1.0.0",
    author      = "you",
    description = "Logs the profile list and reports active-profile changes",
    load        = true,
}

local last_active

function on_map_load()
    for _, p in ipairs(core.profiles.list()) do
        core.log((p.active and "* " or "  ") .. p.name)
    end
end

function on_tick()
    local active = core.profiles.get_active()
    local name = active and active.name or "(none)"
    if name ~= last_active then
        last_active = name
        core.log("Active profile is now: " .. name)
    end
end