Script Permissions

Script Permissions

A server resource's scripts may only do what the server's Access Control List allows. Each API call is a right function.<name> checked for the object resource.<name>.

The defaults

With no acl.toml lines of your own, every resource may call every function except seven privileged ones:

Right	Call
function.kickPlayer	kickPlayer
function.banPlayer	banPlayer
function.mutePlayer	mutePlayer
function.startResource	startResource
function.stopResource	stopResource, and cancelling another resource's start in onResourcePreStart
function.restartResource	restartResource
function.executeCommand	executeCommand, which also needs command.<the line's first word>

A privileged call without its right returns false and the reason, and the reason is logged, e.g. afk does not hold function.kickPlayer: the built-in defaults deny function.kickPlayer to every resource; ….

An operator can also take any other function away from a resource, for example:

acl create Quiet
acl add Quiet resource.board
acl deny Quiet function.playSoundFor

board's playSoundFor then raises an error ("access denied") and does nothing.

Asking for rights

A resource lists the rights it needs in its resource.toml:

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

When the resource starts, its requests are recorded as pending; a pending request grants nothing. The operator decides at the console or the remote console:

Command	What
aclrequest list [resource]	the requests and their state
aclrequest allow <resource> <right or all>	grants
aclrequest deny <resource> <right or all>	refuses

Decisions are kept in acl.toml and take effect at once, even for a running resource. The log at the start says permission requests pending (`aclrequest list`): afk: function.kickPlayer.

Checking a right yourself

hasObjectPermissionTo(object, right) asks whether a connected player or a resource's root holds a right. Use it in your own admin features before acting for a player:

addEventHandler("onPlayerJoin", root, function()
    if hasObjectPermissionTo(source, "command.kick") then
        print("admins: " .. getPlayerName(source) .. " may kick")
    end
end)

With the operator's

acl create Admins
acl add Admins player.fb75078116a2cf894538131440d08b160f305aeba5a4c14b7b4fa7d1e472b573
acl allow Admins command.kick

that player's join logs admins: Snow Fox may kick; anyone else's logs nothing.

A player's rights come from the groups that name player.<id>, its address ip.<range>, or player.*.

What scripts can never do

• Write a rider: positions, speed, results. The riding and its checks are the server's.
• Reach files, processes or the network.
• Act faster than an operator: at most one kick, ban and mute per player and 16 resource or command orders per tick.
• Keep a privilege that was revoked: each order is checked again when it is carried out.

In single player

A gamemode's server scripts running in single player have no ACL: every privileged call is refused there.