QCherry: Document authoritative player name functions

2026-08-04T16:29:59Z

Document authoritative player name functions

New page

= setPlayerName =
Changes a connected player's authoritative multiplayer name.

== Syntax ==
<syntaxhighlight lang="lua">
bool setPlayerName(int playerId, string playerName)
</syntaxhighlight>

== Parameters ==
{| class="wikitable"
! Name !! Type !! Required !! Description
|-
| <code>playerId</code> || <code>int</code> || yes || The connected player whose name will be changed.
|-
| <code>playerName</code> || <code>string</code> || yes || A unique name containing 3-16 ASCII letters, digits, spaces, underscores or hyphens.
|}

== Returns ==
Returns <code>true</code> when the server accepts the new name; otherwise returns <code>false</code>.

== Examples ==
Create a private /name command:
<syntaxhighlight lang="lua" line>
addCommandHandler("name", function(playerId, commandName, ...)
local requestedName = table.concat({...}, " ")

if setPlayerName(playerId, requestedName) then
outputChatBox("Your name is now " .. getPlayerName(playerId) .. ".", playerId)
else
outputChatBox("That player name is invalid or already in use.", playerId)
end
end)
</syntaxhighlight>

== Notes ==
* Available only in server-side resource scripts.
* Names are trimmed and must be 3-16 characters long.
* Allowed characters are A-Z, a-z, 0-9, spaces, underscores and hyphens. Consecutive spaces are rejected.
* Names must be unique among connected players; uniqueness is checked case-insensitively.
* Successful changes are replicated to clients and raise <code>onPlayerNameChange</code>.

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

SetPlayerName - Revision history

QCherry: Document authoritative player name functions