Sessions - BloxCord V3

Session methods let a host start and run a session (training, raid, shift, tryout, etc.) end to end from inside your experience — recruiting administration, marking attendees, running phases, issuing strikes, and closing the session out. Every session method takes an actor as the first argument (the person acting, almost always the host) and, for writes, an opts table as the second.

A session is identified by its session id (sid) — a string that starts with s, returned when you start a session. Pass that same sid to every subsequent session method.

Session lifecycle

A session moves through a fixed set of states. You advance it with sessionUpdateSession.

State	Meaning
`awaiting`	Created and gathering administration/attendees; phases not yet running.
`active`	Running. Attendees can be marked and phases started/stopped.
`ending`	Wrapping up (e.g. grading). Marks can still be adjusted.
`ended`	Closed and finalized. No further edits.
`cancelled`	Called off. Can be reached from any non-final state.

Phases

Each session has an ordered list of phases, each with a stable id and a name. A phase is either a work phase (kind: "phase" — one you start and stop, and mark attendees against) or an outcome marker (kind: "outcome"). Attendee pass/fail marks are keyed by phase id (see cells on an attendee), so a phase can be renamed without losing its marks.

getSessionReservations

Returns the upcoming reserved/scheduled session slots for your organization — useful for showing hosts what they can pick up right now. To host one, pass its rid as the mode to startSession.

local reservations = BloxCord:Invoke("getSessionReservations", actor)

Parameters

Player | table | number

required

The requesting host. See the actor object.

Returns

object[]

An array of reservation records, soonest first. Empty if there are none or the request failed.

Show reservation fields

string

The reservation id. Pass this as mode to startSession to host it.

string

The session type id this slot is for.

string | null

The human-readable session type name.

number

The scheduled start time (Unix epoch milliseconds).

string

Either "open" (anyone eligible may host) or "reserved" (locked to a specific host).

boolean

Whether this is an exclusive slot (blocks other sessions scheduled too close to it).

object | null

{ id, username } of the host it is reserved for, or null when open.

string | null

An optional note attached to the reservation.

boolean

true when the slot is within its hostable window right now.

Example

local BloxCord = game:WaitForChild("BloxCord")

local reservations = BloxCord:Invoke("getSessionReservations", host)
for _, r in ipairs(reservations or {}) do
    if r.hostableNow then
        print(("%s at %d (%s)"):format(r.typeName or r.sessionType, r.time, r.status))
    end
end

getSession

Fetches the full record of a single session by id — its phases, administration (including the host), attendees with their per-phase marks and strikes, the phases that have been started/ended, the scheduled time, and a summary once it has ended.

local session = BloxCord:Invoke("getSession", actor, sessionId)

Parameters

Player | table | number

required

The requesting user. See the actor object.

string

required

The session’s sid (e.g. "s5f3a1c9d2e4b6a8c").

Returns

table | nil

The full session record, or nil if the session was not found or the request failed.

Show session fields

string

The session id.

string | null

The session’s display name.

string

The session type id.

string

Lifecycle state — one of awaiting, active, ending, ended, cancelled.

boolean

Whether the session counts toward competitive scoring.

boolean

Whether it holds an exclusive time slot.

number | null

The scheduled start time (Unix epoch milliseconds), or null for a purely on-demand session.

number

When the session was created (ms).

number | null

When it entered active (ms), or null.

number | null

When it closed (ms), or null.

object[]

Ordered phases.

Show phase fields

string

Stable phase id (starts with p).

string

Phase name.

string

"phase" (a startable/markable phase) or "outcome" (a result marker).

number

Zero-based position in the list.

object[]

Admin roster, including the host.

Show administration fields

string

"host" or a role key from the session type.

string

The member’s UserId.

string | null

Their username.

number | null

Their group rank.

string | null

Their role name.

object[]

The attendee roster.

Show attendee fields

string

The attendee’s UserId.

string | null

Their username.

number | null

Their group rank at join time.

object

Map of phase id → boolean pass/fail mark.

object[]

Strikes as { id, reason, by, time }.

number | null

When they were added (ms).

object[]

Phase start/end marks as { phaseId, type: "start" | "end", time, by }.

object | null

The final summary once the session has ended, otherwise null.

Example

local BloxCord = game:WaitForChild("BloxCord")

local session = BloxCord:Invoke("getSession", host, "s5f3a1c9d2e4b6a8c")
if session then
    print(("%s — %s, %d attendee(s)"):format(session.name, session.state, #session.attendees))

    -- Count who passed the first work phase.
    local firstPhase = session.phases[1]
    if firstPhase then
        local passed = 0
        for _, a in ipairs(session.attendees) do
            if a.cells[firstPhase.id] then passed = passed + 1 end
        end
        print(passed .. " passed " .. firstPhase.name)
    end
end

getRunningServers

Returns your organization’s currently-running game servers, the players in each (with their ranks), and any ongoing sessions taking place in them.

local servers = BloxCord:Invoke("getRunningServers", actor)

Parameters

Player | table | number

required

The requesting user. See the actor object.

Returns

object[]

An array of running servers. Empty if none are active or the request failed.

Show server fields

string

The server id, formatted as placeId_jobId (e.g. "606849621_9a8b...").

string | null

The place id.

string | null

The Roblox job id (matches game.JobId).

number

When the server last reported in (Unix epoch milliseconds).

number

Number of players currently present.

object[]

Present players.

Show player fields

string

The player’s UserId.

string | null

Their username.

number | null

Their group rank.

object[]

Ongoing sessions in this server.

Show session fields

string

The session id.

string | null

The session name.

string

Lifecycle state.

object

{ userId, username } of the host.

object[]

Admin slots as { slotType, id, username, rank, role }.

Example

local BloxCord = game:WaitForChild("BloxCord")

for _, server in ipairs(BloxCord:Invoke("getRunningServers", host) or {}) do
    print(("%s — %d player(s), %d session(s)"):format(
        server.serverId, server.playerCount, #server.sessions))
end

startSession

Starts hosting a session in the current server. The actor becomes the host, and must meet the host requirements configured for the chosen session type. You can host on demand (right now) or pick up a scheduled reservation returned by getSessionReservations.

local result = BloxCord:Invoke("startSession", actor, opts)

Parameters

Player | table | number

required

The host starting the session. See the actor object.

table

required

Session options.

Show opts fields

string

required

The id of the session type to host (as configured in your dashboard, e.g. "training" or "raid").

string

default:"on-demand"

Either "on-demand" to start immediately, or a reservation rid (from getSessionReservations) to host that scheduled slot.

number

The session’s start time as a Unix epoch milliseconds value. Optional for on-demand sessions (defaults to now); ignored when hosting a reservation (the reservation’s time is used).

boolean

default:"false"

Request an exclusive time slot (blocks other sessions scheduled too close). Only granted if the actor has permission to schedule exclusive sessions; otherwise silently ignored.

object[]

Co-administration to add alongside the host. Each entry fills one role slot defined by the session type, and each member must qualify for that role.

Show administration entry fields

number | string

required

The member’s UserId.

string

required

The session type role slot to fill (e.g. "co_host", "supervisor").

number

required

The member’s group rank (used to validate they qualify for the role).

string

The member’s username, for display.

Returns

table | nil

The result of the host attempt, or nil if the request failed or the backend was unreachable.

Show result fields

boolean

true when the session was created.

string

The new session id (present on success). Use it for every follow-up call.

string

The initial state ("awaiting").

string

On failure, a human-readable reason (e.g. not qualified to host, server already has a session).

Examples

local BloxCord = game:WaitForChild("BloxCord")

local result = BloxCord:Invoke("startSession", host, {
    typeId = "training",
    mode = "on-demand",
    exclusive = false,
    administration = {
        { id = 123456789, roleKey = "co_host",    rank = 200, username = "Builderman" },
        { id = 987654321, roleKey = "supervisor", rank = 250, username = "Shedletsky" },
    },
})

if result and result.success then
    local sid = result.sid
    print("Hosting session", sid)
else
    warn("Could not host:", result and result.message or "request failed")
end

local BloxCord = game:WaitForChild("BloxCord")

local reservations = BloxCord:Invoke("getSessionReservations", host)
local slot = reservations and reservations[1]

if slot and slot.hostableNow then
    local result = BloxCord:Invoke("startSession", host, {
        typeId = slot.sessionType,
        mode = slot.rid,   -- host this specific reservation
    })
    print(result and result.sid)
end

sessionUpdateAttendees

Adds or removes attendees on a running session. You can add and remove in the same call. Duplicate, invalid, or already-present ids (and anyone in administration) are skipped automatically.

local result = BloxCord:Invoke("sessionUpdateAttendees", actor, opts)

Parameters

Player | table | number

required

The administrator performing the update. See the actor object.

table

required

Show opts fields

string

required

The session id.

object[]

Attendees to add (up to 60 per call).

Show add entry fields

number | string

required

The attendee’s UserId.

string

Their username, for display.

number

Their group rank.

array

An array of UserIds to remove (e.g. { 111, 222 }).

Returns

table | nil

Show result fields

boolean

true when at least one change was applied.

number

How many attendees were added.

number

How many attendees were removed.

string

On failure, the reason (e.g. attendees locked after phases begin).

Example

local BloxCord = game:WaitForChild("BloxCord")

local result = BloxCord:Invoke("sessionUpdateAttendees", host, {
    sid = sid,
    add = {
        { id = 111111111, username = "trainee_a", rank = 10 },
        { id = 222222222, username = "trainee_b", rank = 10 },
    },
    remove = { 333333333 },
})

if result and result.success then
    print(("Added %d, removed %d"):format(result.added, result.removed))
end

sessionUpdateMark

Sets or clears a single attendee’s pass/fail mark for a work phase (e.g. ticking them off for passing a checkpoint). The phase must already be started.

local result = BloxCord:Invoke("sessionUpdateMark", actor, opts)

Parameters

Player | table | number

required

The administrator performing the mark. See the actor object.

table

required

Show opts fields

string

required

The session id.

number | string

required

The attendee’s UserId.

string

required

The phase id to mark (from the session’s phases).

boolean

default:"false"

true to mark as passed, false to clear the mark.

Returns

table | nil

Show result fields

boolean

true when the mark was applied.

string

On failure, the reason (e.g. phase not started, unknown attendee).

Example

local BloxCord = game:WaitForChild("BloxCord")

-- Mark trainee 111 as passing phase "p1a2b3c4".
BloxCord:Invoke("sessionUpdateMark", host, {
    sid = sid,
    attendeeId = 111111111,
    phaseId = "p1a2b3c4",
    value = true,
})

sessionUpdateStrike

Adds a strike against an attendee (with a reason) or removes an existing one.

local result = BloxCord:Invoke("sessionUpdateStrike", actor, opts)

Parameters

Player | table | number

required

The administrator issuing/removing the strike. See the actor object.

table

required

Show opts fields

string

required

The session id.

number | string

required

The attendee’s UserId.

string

default:"add"

Either "add" or "remove".

string

The reason for the strike. Required when adding; up to 300 characters.

string

The id of the strike to remove. Required when removing (available as strike.id from the add result or an attendee’s strikes).

Returns

table | nil

Show result fields

boolean

true on success.

object

The created strike { id, reason, by, time } (only when adding).

string

On failure, the reason (e.g. missing reason, strike not found).

Examples

local BloxCord = game:WaitForChild("BloxCord")

local result = BloxCord:Invoke("sessionUpdateStrike", host, {
    sid = sid,
    attendeeId = 111111111,
    action = "add",
    reason = "Left the formation without permission",
})

local strikeId = result and result.strike and result.strike.id

local BloxCord = game:WaitForChild("BloxCord")

BloxCord:Invoke("sessionUpdateStrike", host, {
    sid = sid,
    attendeeId = 111111111,
    action = "remove",
    strikeId = strikeId,
})

sessionUpdatePhase

Controls a session’s phases. Use it to start/stop a work phase during the session, or to add/rename/delete phases.

local result = BloxCord:Invoke("sessionUpdatePhase", actor, opts)

Only one work phase can be running at a time — end the current phase before starting the next. Outcome markers cannot be deleted.

Parameters

Player | table | number

required

The administrator performing the action. See the actor object.

table

required

Show opts fields

string

required

The session id.

string

required

One of:

"start" — begin a work phase
"stop" — end the currently-running work phase
"add" — add a new phase
"rename" — rename a phase
"delete" — remove a phase

string

The target phase id. Required for start, stop, rename, and delete.

string

The phase name. Required for add and rename.

Returns

table | nil

Show result fields

boolean

true on success.

object

The created phase { id, name, kind, order } (only for add).

string

The new name (only for rename).

string

On failure, the reason (e.g. a phase is already running).

Examples

local BloxCord = game:WaitForChild("BloxCord")

BloxCord:Invoke("sessionUpdatePhase", host, { sid = sid, action = "start", phaseId = "p1a2b3c4" })
-- ... run the phase, mark attendees ...
BloxCord:Invoke("sessionUpdatePhase", host, { sid = sid, action = "stop",  phaseId = "p1a2b3c4" })

local BloxCord = game:WaitForChild("BloxCord")

local added = BloxCord:Invoke("sessionUpdatePhase", host, { sid = sid, action = "add", name = "Obstacle Course" })
local newPhaseId = added and added.phase and added.phase.id

BloxCord:Invoke("sessionUpdatePhase", host, { sid = sid, action = "rename", phaseId = newPhaseId, name = "Final Course" })
BloxCord:Invoke("sessionUpdatePhase", host, { sid = sid, action = "delete", phaseId = newPhaseId })

sessionUpdateSession

Advances the session through its lifecycle — activating it, moving it to ending, closing it out, or cancelling it.

local result = BloxCord:Invoke("sessionUpdateSession", actor, opts)

Parameters

Player | table | number

required

The administrator performing the transition. See the actor object.

table

required

Show opts fields

string

required

The session id.

string

required

The target state. Transitions are ordered:

"active" — from awaiting
"ending" — from active
"ended" — from ending
"cancelled" — from any non-final state

string

An optional reason, recorded with the transition.

Returns

table | nil

Show result fields

boolean

true when the transition was applied.

string

On failure, the reason (e.g. an invalid transition for the current state).

Example

local BloxCord = game:WaitForChild("BloxCord")

-- A full run: activate, begin wrap-up, then close out.
BloxCord:Invoke("sessionUpdateSession", host, { sid = sid, to = "active" })
BloxCord:Invoke("sessionUpdateSession", host, { sid = sid, to = "ending" })
BloxCord:Invoke("sessionUpdateSession", host, {
    sid = sid,
    to = "ended",
    reason = "Training complete",
})

​Session lifecycle

​Phases

​getSessionReservations

​Parameters

​Returns

​Example

​getSession

​Parameters

​Returns

​Example

​getRunningServers

​Parameters

​Returns

​Example

​startSession

​Parameters

​Returns

​Examples

​sessionUpdateAttendees

​Parameters

​Returns

​Example

​sessionUpdateMark

​Parameters

​Returns

​Example

​sessionUpdateStrike

​Parameters

​Returns

​Examples

​sessionUpdatePhase

​Parameters

​Returns

​Examples

​sessionUpdateSession

​Parameters

​Returns

​Example

Session lifecycle

Phases

getSessionReservations

Parameters

Returns

Example

getSession

Parameters

Returns

Example

getRunningServers

Parameters

Returns

Example

startSession

Parameters

Returns

Examples

sessionUpdateAttendees

Parameters

Returns

Example

sessionUpdateMark

Parameters

Returns

Example

sessionUpdateStrike

Parameters

Returns

Examples

sessionUpdatePhase

Parameters

Returns

Examples

sessionUpdateSession

Parameters

Returns

Example