Auth

Auth is the account/authentication API.

• Server is authoritative for all auth mutations.
• Client can call the same mutation methods, but they execute asynchronously through server requests.

Error Handling Pattern

• Success: err == nil
• Failure: err is an error code string

Selector Model

Functions that accept a target selector support:

• number -> playerId (session id)
• string with c_ prefix -> clientId
• string with a_ prefix -> accountId

Account ID Format

• New registrations generate deterministic account IDs: a_<normalizedUsername>.
• Example: username Done => accountId = a_done.
• Account IDs are the recommended ACL principal for per-user command permissions.

Function List

Function	Description	Scope
Auth.Register	Create a new account.	S
Auth.Login	Login to an account.	S
Auth.Logout	Logout the current account session.	S
Auth.IsLoggedIn	Check whether target is logged in.	S
Auth.GetAccountId	Get logged-in account id for target.	S
Auth.GetDisplayName	Get display name for target.	S
Auth.SetDisplayName	Set display name (online unique).	S
Auth.GetCountry	Get profile country code for target.	S
Auth.SetCountry	Set profile country code for target.	S
Auth.GetAccountRole	Get persistent account role.	S
Auth.SetAccountRole	Set persistent account role.	S

Event List

Event	Description	Scope
auth:registered	Emitted on successful account registration.	S
auth:logged_in	Emitted on successful login.	S
auth:logged_out	Emitted on successful logout.	S
auth:display_name_changed	Emitted when display name changes.	S
auth:country_changed	Emitted when profile country changes.	S
custom:auth_result	Auth mutation result event sent to client requesters.	C

Functions

Auth.Register

S Shared (Client Request + Server Authority)

local result, err = Auth.Register(username, password)

Returns:

• Server call: result = accountId
• Client call: result = requestId (async request token)

Notes:

• Register is rejected with ERR_ALREADY_LOGGED_IN when the invoking player is already logged in.

Auth.Login

S Shared (Client Request + Server Authority)

local result, err = Auth.Login(username, password, options)

Returns:

• Server call: result = accountId
• Client call: result = requestId (async request token)

Parameters:

• options (table, optional)
• target (number|string, optional): server/admin path for explicit target player selector.

Notes:

• Login is rejected with ERR_ALREADY_LOGGED_IN when target session is already logged in.
• Login is rejected with ERR_BANNED when an active ban matches target accountId or clientId.

Auth.Logout

S Shared (Client Request + Server Authority)

local result, err = Auth.Logout(options)

Returns:

• Server call: result = nil
• Client call: result = requestId (async request token)

Parameters:

• options (table, optional)
• target (number|string, optional): server/admin path for explicit target player selector.

Auth.IsLoggedIn

S Shared (Client & Server)

local isLoggedIn, err = Auth.IsLoggedIn(target)

Auth.GetAccountId

S Shared (Client & Server)

local accountId, err = Auth.GetAccountId(target)

Auth.GetDisplayName

S Shared (Client & Server)

local displayName, err = Auth.GetDisplayName(target)

Auth.SetDisplayName

S Shared (Client Request + Server Authority)

local result, err = Auth.SetDisplayName(name, options)

Returns:

• Server call: result = nil
• Client call: result = requestId (async request token)

Parameters:

• options (table, optional)
• target (number|string, optional): server/admin path for explicit target player selector.

Display name rules:

• length: 1..22
• allowed characters: ASCII 33..126 only (no spaces)
• names are unique among connected players (case-insensitive)
• color codes are supported using inline #RRGGBB segments (for example #0fc0fcDone)

Auth.GetCountry

S Shared (Client & Server)

local countryCode, err = Auth.GetCountry(target)

Returns:

• countryCode (string): normalized lowercase catalog code, for example de, us, gb, xx

Auth.SetCountry

S Shared (Client Request + Server Authority)

local result, err = Auth.SetCountry(countryCode, options)

Returns:

• Server call: result = nil
• Client call: result = requestId (async request token)

Parameters:

• countryCode (string): normalized country/catalog code
• options (table, optional)
• target (number|string, optional): server/admin path for explicit target player selector.

Auth.GetAccountRole

S Server Only

local role, err = Auth.GetAccountRole(accountId)

Auth.SetAccountRole

S Server Only

local err = Auth.SetAccountRole(accountId, role)

Built-in Event

auth:registered

S Server Only

Payload fields:

• playerId (number)
• clientId (string | nil)
• accountId (string)
• username (string | nil)
• displayName (string | nil)
• role (string | nil)
• connectedAt (number)

auth:logged_in

S Server Only

Payload fields:

• playerId (number)
• clientId (string)
• accountId (string)
• username (string | nil)
• displayName (string | nil)
• newDisplayName (string | nil)
• role (string | nil)
• connectedAt (number)

auth:logged_out

S Server Only

Payload fields:

• playerId (number)
• clientId (string)
• accountId (string | nil)
• displayName (string | nil)
• role (string | nil)
• connectedAt (number)

auth:display_name_changed

S Server Only

Payload fields:

• playerId (number)
• clientId (string)
• accountId (string | nil)
• oldDisplayName (string | nil)
• newDisplayName (string | nil)
• displayName (string | nil)
• countryCode (string | nil)
• oldCountryCode (string | nil)
• newCountryCode (string | nil)
• role (string | nil)
• connectedAt (number)

auth:country_changed

S Server Only

Payload fields:

• playerId (number)
• clientId (string)
• accountId (string | nil)
• displayName (string | nil)
• countryCode (string | nil)
• oldCountryCode (string | nil)
• newCountryCode (string | nil)
• role (string | nil)
• connectedAt (number)

custom:auth_result

C Client Only

This event is emitted by the server after client auth mutation requests (Register, Login, Logout, SetDisplayName, SetCountry).

Payload fields:

• requestId (string | nil)
• action (register | login | logout | set_display_name | set_country)
• ok (boolean)
• error (string | nil)
• playerId (number)
• clientId (string)
• accountId (string | nil)
• displayName (string | nil)
• countryCode (string | nil)
• role (string | nil)
• loggedIn (boolean)

Example:

local pending = {}

local reqId, err = Auth.Login("player_one", "secret")
if err then
    return print("login request failed: " .. err)
end
pending[reqId] = true

AddEventHandler("custom:auth_result", function(event)
    local p = event.payload
    if not p or not p.requestId or not pending[p.requestId] then
        return
    end

    pending[p.requestId] = nil

    if not p.ok then
        return print("auth failed: " .. tostring(p.error))
    end

print("auth ok: action=" .. tostring(p.action) .. " account=" .. tostring(p.accountId))
end)

Client UI note:

• custom:auth_result only covers mutation requests initiated through Auth.* on the client.
• If a resource also needs to react to out-of-band auth state changes (for example a /logout command), observe player:updated and inspect loggedIn / reason there.

Role Model

• ACL (acl.json) is the permission policy source.
• Account role in runtime/mtadm.db (SQLite) is persistent identity data (normal, admin, ...).
• Runtime role is resolved from account role during authenticated session.

Error Codes

• ERR_ALREADY_EXISTS
• ERR_ALREADY_LOGGED_IN
• ERR_BANNED
• ERR_INVALID_CREDENTIALS
• ERR_NOT_LOGGED_IN
• ERR_NAME_IN_USE
• ERR_INVALID_NAME
• ERR_PERMISSION_DENIED
• ERR_INVALID_ROLE
• ERR_RATE_LIMIT
• ERR_NOT_CONNECTED
• ERR_STORAGE_UNAVAILABLE
• ERR_NOT_FOUND
• ERR_INVALID_COUNTRY