QCherry: Document 0.1a Lua API, identities, moderation and synchronized spells

2026-08-27T11:36:25Z

Document 0.1a Lua API, identities, moderation and synchronized spells

New page

= banPlayer =
Persists a verified client-serial ban and disconnects the connected player.

== Syntax ==
<syntaxhighlight lang="lua">
bool banPlayer(int playerId [, int minutes = 0 [, string reason = "Banned by a server resource"]])
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player identifier.
|-
| <code>minutes</code> || <code>int</code> || no || Optional duration in whole minutes. Use <code>0</code> for a permanent ban; the maximum is 5,256,000 minutes (10 years).
|-
| <code>reason</code> || <code>string</code> || no || Optional non-empty reason of at most 160 bytes without control characters.
|}

== Returns ==
Returns <code>true</code> only when the serial ban is persisted and the player's disconnect is accepted. Returns <code>false</code> for an invalid or unauthenticated player, invalid arguments, or a persistence failure.

== Examples ==
Ban a player for one hour:
<syntaxhighlight lang="lua" line>
if not banPlayer(playerId, 60, "Repeated griefing") then
outputDebugString("The ban could not be persisted.", 1)
end
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* The ban is stored by verified client serial in the server's local <code>bans.json</code>. It is distinct from global master-list bans and from any account-ban table maintained by a gamemode.
* This function does not grant or check a gamemode permission such as <code>admin.ban</code>. The calling resource must authorize the command or action before invoking it.
* A successful call immediately revokes voice, ends the gameplay connection and closes the game client. The launcher displays the ban reason, and the normal <code>onPlayerQuit</code> event follows. There is no separate <code>onPlayerBan</code> event.
* Omitting <code>minutes</code> or passing <code>0</code> creates a permanent ban.

[[Category:Lua Functions]]
[[Category:Server Functions]]
[[Category:Player Functions]]

BanPlayer - Revision history

QCherry: Document 0.1a Lua API, identities, moderation and synchronized spells