Player

The Player class is a static service for managing player connections and sessions. Players are identified by unique IDs and can be kicked, banned, and queried for information.

Error Handling Pattern

This API uses the "Error or Nil" pattern.

• If a function succeeds, it returns nil for the error parameter
• If a function fails, it returns a string error message

Static Service: Player

Function	Description	Scope
Player.Kick	Kicks a player from the server	S
Player.Ban	Bans a player from the server	S
Player.Unban	Unbans a player by ban ID	S
Player.GetBans	Gets all active bans	S
Player.GetPlayerCount	Gets the number of connected players	S
Player.GetOnlinePlayers	Gets all connected player IDs	S
Player.GetName	Gets the name of a player	S
Player.SetName	Sets the name of a player	S
Player.GetDimension	Gets the player's current dimension	S
Player.SetDimension	Sets the player's dimension	S

Functions

Player.Kick

S Server Only

local err = Player.Kick(playerId, reason)

Parameters:

• playerId (string): The ID of the player to kick S
• reason (string): Optional. The reason for the kick S

Returns:

• err: nil on success, or a string error message

Player.Ban

S Server Only

local banId, err = Player.Ban(playerId, duration, reason)

Parameters:

• playerId (string): The ID of the player to ban S
• duration (number): Ban duration in minutes (0 for permanent) S
• reason (string): Optional. The reason for the ban S

Returns:

• banId (string): Unique identifier for the created ban (or nil on failure)
• err: nil on success, or a string error message

Player.Unban

S Server Only

local err = Player.Unban(banId)

Parameters:

• banId (string): The ID of the ban to remove S

Returns:

• err: nil on success, or a string error message

Player.GetBans

S Server Only

local bans, err = Player.GetBans()

Parameters:

• None

Returns:

• bans (table): Array of ban objects (or nil on failure)
  • banId (string): Unique identifier for the ban
  • playerId (string): ID of the banned player
  • duration (number): Ban duration in minutes (0 = permanent)
  • reason (string): Reason for the ban
  • bannedBy (string): ID/name of who performed the ban
  • timestamp (number): Unix timestamp when the ban was created
  • expires (number): Unix timestamp when the ban expires (nil if permanent)
• err: nil on success, or a string error message

Player.GetPlayerCount

S Shared (Client & Server)

local count, err = Player.GetPlayerCount()

Parameters:

• None

Returns:

• count (number): The number of connected players (or nil on failure)
• err: nil on success, or a string error message

Player.GetOnlinePlayers

S Shared (Client & Server)

local players, err = Player.GetOnlinePlayers()

Parameters:

• None

Returns:

• players (table): Array of player IDs for all connected players (or nil on failure)
• err: nil on success, or a string error message

Player.GetName

S Shared (Client & Server)

local name, err = Player.GetName(playerId)

Parameters:

• playerId (string): The ID of the player S

Returns:

• name (string): The player's name (or nil on failure)
• err: nil on success, or a string error message

Player.SetName

S Server Only

local err = Player.SetName(playerId, name)

Parameters:

• playerId (string): The ID of the player S
• name (string): The new name for the player (1-22 chars, ASCII 33-126, no spaces, case-insensitive) S

Returns:

• err: nil on success, or a string error message

Notes:

• Names are case-insensitive ("Player" and "player" are treated as the same name)
• Only ASCII characters 33-126 are allowed (no spaces)

Player.GetDimension

S Shared (Client & Server)

local dimension, err = Player.GetDimension(playerId)

Parameters:

• playerId (string): The ID of the player S

Returns:

• dimension (number): The player's current dimension (or nil on failure)
• err: nil on success, or a string error message

Player.SetDimension

S Server Only

local err = Player.SetDimension(playerId, dimension)

Parameters:

• playerId (string): The ID of the player S
• dimension (number): The dimension to set the player to (0-65535) S

Returns:

• err: nil on success, or a string error message

Constants & Constraints

Constant	Value	Description
Player.MAX_REASON_LENGTH	256	Maximum characters for kick/ban reason
Player.MAX_BAN_DURATION	525960	Maximum ban duration in minutes (~1 year)
Player.MIN_NAME_LENGTH	1	Minimum characters for player name
Player.MAX_NAME_LENGTH	22	Maximum characters for player name
Player.VALID_NAME_CHARS	ASCII 33-126	See name validation rules above
Player.MIN_DIMENSION	0	Minimum dimension value
Player.MAX_DIMENSION	65535	Maximum dimension value

Events

Server Events

Event	Description	Parameters
onPlayerKicked	Triggered when a player is kicked	playerId (string), reason (string), kickedBy (string)
onPlayerBanned	Triggered when a player is banned	playerId (string), banId (string), duration (number), reason (string), bannedBy (string)
onPlayerUnbanned	Triggered when a player is unbanned	banId (string), playerId (string), unbannedBy (string)
onKickError	Triggered when a kick operation fails	playerId (string), error (string)
onBanError	Triggered when a ban operation fails	playerId (string), error (string)
onUnbanError	Triggered when an unban operation fails	banId (string), error (string)

Event Handlers

onPlayerKicked

S Server Only

AddEventHandler('onPlayerKicked', function(playerId, reason, kickedBy)
    -- Player was kicked
end)

Parameters:

• playerId (string): ID of the kicked player
• reason (string): Reason for the kick
• kickedBy (string): ID/name of who performed the kick

onPlayerBanned

S Server Only

AddEventHandler('onPlayerBanned', function(playerId, banId, duration, reason, bannedBy)
    -- Player was banned
end)

Parameters:

• playerId (string): ID of the banned player
• banId (string): Unique identifier for the ban
• duration (number): Ban duration in minutes (0 = permanent)
• reason (string): Reason for the ban
• bannedBy (string): ID/name of who performed the ban

onKickError

S Server Only

AddEventHandler('onKickError', function(playerId, error)
    -- Kick operation failed
end)

Parameters:

• playerId (string): ID of the player that failed to be kicked
• error (string): Error message describing the failure

onBanError

S Server Only

AddEventHandler('onBanError', function(playerId, error)
    -- Ban operation failed
end)

Parameters:

• playerId (string): ID of the player that failed to be banned
• error (string): Error message describing the failure

onPlayerUnbanned

S Server Only

AddEventHandler('onPlayerUnbanned', function(banId, playerId, unbannedBy)
    -- Player was unbanned
end)

Parameters:

• banId (string): ID of the ban that was removed
• playerId (string): ID of the unbanned player
• unbannedBy (string): ID/name of who performed the unban

onUnbanError

S Server Only

AddEventHandler('onUnbanError', function(banId, error)
    -- Unban operation failed
end)

Parameters:

• banId (string): ID of the ban that failed to be removed
• error (string): Error message describing the failure

Error Codes

• ERR_PLAYER_NOT_FOUND: Player does not exist or is not connected
• ERR_PLAYER_ALREADY_KICKED: Player is already being kicked
• ERR_PLAYER_ALREADY_BANNED: Player is already banned
• ERR_INVALID_REASON: Reason is empty or too long
• ERR_INVALID_DURATION: Ban duration is negative or exceeds maximum
• ERR_PERMISSION_DENIED: Insufficient permissions to kick/ban
• ERR_BAN_CREATION_FAILED: Failed to create ban record
• ERR_DATABASE_ERROR: Database error while processing ban
• ERR_CANNOT_KICK_SELF: Cannot kick the administrator performing the action
• ERR_CANNOT_BAN_SELF: Cannot ban the administrator performing the action
• ERR_PROTECTED_PLAYER: Player has protection from kick/ban
• ERR_BAN_NOT_FOUND: Ban ID does not exist
• ERR_BAN_ALREADY_REMOVED: Ban has already been removed
• ERR_INVALID_NAME: Player name is empty, too long/short, or contains invalid characters (only ASCII 33-126, no spaces)
• ERR_NAME_TAKEN: Player name is already in use by another player (case-insensitive)
• ERR_NAME_CHANGE_COOLDOWN: Player name was changed too recently
• ERR_INVALID_DIMENSION: Dimension value is out of valid range (0-65535)