Script Examples

Script Examples

Every example here was run on a server; the log lines are what it printed (time stamps left out). More examples: the welcome resource on Server Resources (a module, storage, a console command, a client HUD line and a server–client round trip), teams on Events and Messages (element data a player may write, checked by the server) and admins on Script Permissions.

A join check

Holds every join for a second while it "checks", and refuses one name at once.

joincheck/resource.toml:

[resource]
name = "joincheck"
version = "1.0.0"
api = 1
type = "script"

[scripts]
server = ["server/*.luau"]

joincheck/server/main.luau:

-- Holds every join for a second and refuses one name.
addEventHandler("onPlayerConnecting", root, function(name, keyId, join)
    print("joincheck: " .. name .. " (" .. keyId .. ") wants to join")
    if name == "Nobody" then
        cancelEvent() -- refused at once
        return
    end
    deferJoin(join)
    updateJoin(join, "checking your name")
    setTimer(function()
        acceptJoin(join)
        print("joincheck: let " .. name .. " in")
    end, 1000, 1)
end)

A player named "Nobody" is refused with "the server's scripts refused the join"; anyone else sees "The server holds your join: checking your name" for a second and joins:

scripts: joincheck: joincheck: Snow Fox (<the player's id: 64 hex digits>) wants to join
scripts: joincheck: joincheck: let Snow Fox in

(The server's log shows a script's line whole, up to 4 096 bytes.)

• A join no handler holds or refuses is let in.
• With several resources holding one join, the player is let in when every one of them accepted, and refused as soon as one refuses. A resource that stops while it holds a join refuses it.
• A join held longer than 120 seconds is refused. At most 64 joins are held at once, 4 per address.

Exports between resources, and a privileged call

scores offers two functions; afk requires it, calls them, and has a console command that kicks everyone, for which it asks the operator for the right.

scores/resource.toml:

[resource]
name = "scores"
version = "1.2.0"
api = 1
type = "library"

[scripts]
server = ["server/*.luau"]

scores/server/main.luau:

-- Offers two functions to other resources.
local best: { [string]: number } = {}

exports("record", function(name: string, points: number): boolean
    if points > (best[name] or 0) then
        best[name] = points
        return true
    end
    return false
end)

exports("best", function(name: string): number?
    return best[name]
end)

afk/resource.toml:

[resource]
name = "afk"
version = "1.0.0"
api = 1
type = "script"

[scripts]
server = ["server/*.luau"]

[dependencies]
require = ["scores >= 1.0, < 2"]

[permissions]
request = ["function.kickPlayer"]

afk/server/main.luau:

-- Uses another resource's exports, and a privileged call.
addEventHandler("onPlayerJoin", root, function()
    local name = getPlayerName(source) or "rider"
    exports.scores:record(name, 1200)
    print("afk: " .. name .. " best " .. tostring(exports.scores:best(name)))
end)

-- `kickall` in the console: needs function.kickPlayer
addCommandHandler("kickall", function(player, command)
    for _, p in getPlayers() do
        local ok, why = kickPlayer(p, "the server is resting")
        print("afk: kick " .. (getPlayerName(p) or "?") .. ": " .. tostring(ok) .. (why and (", " .. why) or ""))
    end
end)

With start = ["joincheck", "afk"] (scores starts first, as afk requires it), a player joining, and the console lines kickall, aclrequest list, aclrequest allow afk function.kickPlayer, kickall:

resources: started afk 1.0.0, scores 1.2.0
permission requests pending (`aclrequest list`): afk: function.kickPlayer
scripts: afk: afk: Snow Fox best 1200
scripts: ran kickall
scripts: afk: kickPlayer: refused: afk does not hold function.kickPlayer: the … (211 bytes)
scripts: afk: afk: kick Snow Fox: false, afk does not hold function.kickPlayer… (217 bytes)
1 requests:
  afk function.kickPlayer: pending (asked 2026-11-07 21:56 UTC)
aclrequest: afk: function.kickPlayer allowed by console (1 decided)
scripts: ran kickall
scripts: afk: afk: kick Snow Fox: true
ending the connection of "Snow Fox" (fb75078116a2cf89) from 127.0.0.1: Operator (the server is resting)

The player's game shows "the server is resting".