- Documentation
- Players
Category
Players
All Lua functions and events in the Players category, on the server and the client.
Server functions 79
countReturns the number of players in a team.Players In Team forceForces the map open for a player (or everyone:Player Map root).getReturns the players who are alive and in the world.Alive Players getReturns the players who are dead or have not spawned yet.Dead Players getReturns the names of game HUD components that can be hidden separately:Hud Component Names ammo,armour(orarmor),breath,clock,health,money,weapon,wanted,area_name,vehicle_name,radio,radar,all.getReturns the player's account. When the player is not logged in, it returns a guest account.Player Account getReturns the last anti-cheat information reported by the client on join.Player ACInfo getReturns the player's risk level from the anti-cheat (Trilogy Protect): a table with the fieldsPlayer ACRisk points(risk points),violations(number of detected violations) andbyRule(number of violations per rule). Read only: a script can use it e.g. to notify admins, but it does not affect the protection's kicks and bans.getReturns the player's level fromPlayer Admin Level admins.xml:"player","moderator","admin"or"owner".getReturns a value announced for the player (e.g. in the server list).Player Announce Value getReturns the player's armour (0-100).Player Armour getReturns the motion blur level set for the player (0-255, default 36).Player Blur Level getReturns the number of players on the server.Player Count getReturns a HUD component appearance property set withPlayer Hud Component Property setPlayerHudComponentProperty.getReturns how many milliseconds the player has been idle (not moving or pressing keys).Player Idle Time getReturns the player's IP address.Player IP getReturns the player's language chosen in the launcher (the same one the client sees inPlayer Localization getLocalization). Useful for sending messages to everyone in their own language. A player with an older client gets Polish.getReturns the world rectangle shown on the player's open map.Player Map Bounding Box getReturns the player's map opacity (0-255).Player Map Opacity getReturns the colour of the nametag above the player's head.Player Nametag Color getReturns the nametag look set for the player withPlayer Nametag Style setPlayerNametagStyle(a table with the fieldsenabled,distance,showDistance,scale,color,background).getReturns the players whose data value under a key equals the given one.Players By Data getReturns the level of script debug messages the player sees (0-3).Player Script Debug Level getReturns the player's Client ID: a stable device identifier that cannot be forged. Use it for bans and linking accounts.Player Serial getReturns the players in a team.Players In Team getReturns the player's team.Player Team getReturns the player's client version.Player Version getReturns the list of the player's voice recipients.Player Voice Broadcast To getReturns the player's voice channel set withPlayer Voice Channel setPlayerVoiceChannel.getReturns the list of players this player does not hear (set withPlayer Voice Ignore From setPlayerVoiceIgnoreFrom).getReturns a random player from the server.Random Player giveGives the player money.Player Money isChecks whether a player is exempt from cheat detection byPlayer ACExempt setPlayerACExempt.isChecks whether a player is still on the server. Useful in delayed functions.Player Connected isChecks whether the player's crosshair is visible. The game does not allow hiding the crosshair on its own, so it is visible as long as the whole HUD (Player Crosshair Visible "all") is.isChecks whether the player has entered the world (after the first spawn).Player In World isReturnsPlayer Loading trueuntil the player enters the world for the first time. After the first spawn it isfalsefor good. UnlikeisPlayerSpawnedit does not go back totrueafter death.isChecks whether the player can open the map.Player Map Enabled isChecks whether the map is forced for the player byPlayer Map Forced forcePlayerMap.isChecks whether the player has the map open right now.Player Map Visible isChecks whether a player is muted in chat.Player Muted isChecks whether the player has the game's in-vehicle radio on.Player Radio Enabled isChecks whether slow motion is on for the player: on the weapon wheel (Player Slow Motion Enabled "wheel"), on stunts ("stunt") or both ("all").isChecks whether the player is in the world and alive. After death it returnsPlayer Spawned falseuntil the next spawn.isChecks whether the player gets tired when sprinting (no by default).Player Stamina Enabled redirectMoves a player to another server. Without an address it reconnects them to the same one.Player resendAsks the client to resend anti-cheat information.Player ACInfo resendAsks the client to resend the list of game modifications.Player Mod Info resetRestores a HUD component's default appearance (one property or all of them).Player Hud Component Property setTurns cheat detection off or on for a player. Use it when a resource intentionally gives a player flying, aim assistance or unusual movement, so the protection does not treat it as cheating. Admins are exempt automatically. The exemption lasts until the player leaves the server.Player ACExempt setSets a value announced for the player, e.g. a score shown in the server list.Player Announce Value setSets the player's armour (0-100).Player Armour setSets the motion blur for a player (0-255,Player Blur Level rootfor everyone).setStores a HUD component's appearance: one property or a whole table. Properties:Player Hud Component Property posX,posY,size,fillColor,fillColorSecondary,textColor,alignment,drawBlackBorder,drawPercentage,blinkingTimeLimit,textOutline,textShadow,useFontTexture.setAllows or forbids the player to open the map.Player Map Enabled setStores the player's map opacity (0-255).Player Map Opacity setSets the player's money. The in-game counter shows the server's balance.Player Money setMutes or unmutes a player in chat.Player Muted setChanges the player's nickname. FiresPlayer Name onPlayerChangeNick.setSets the colour of the nametag above the player's head (everyone sees it; it takes precedence over the colour fromPlayer Nametag Color setPlayerNametagStyle). The player's nickname in chat uses this colour too.setShows or hides the player's nametag.Player Nametag Showing setSets the look of the built-in nametags above other players' heads as seen by this player (or everyone:Player Nametag Style root). Pass only the fields to change; the rest stay. Fields:enabled(bool,falsehides the built-in nametags, e.g. when a resource draws its own withdxDrawText),distance(metres, 0 = no limit),showDistance(bool, the "12 m" suffix after the nickname),scale(0.4–4, text size),color(a colour fromtocolororfalse= default colour),background(a background colour fromtocolororfalse= no background). A single player's colour, text and hiding (setPlayerNametagColor,setPlayerNametagText,setPlayerNametagShowing) take precedence over the style. After reconnecting set the style again.setChanges the nametag text.Player Nametag Text falserestores the nickname.setTurns the game's in-vehicle radio on or off for a player (or everyone:Player Radio Enabled root). Off gives silence instead of GTA stations, for your own script radio.setSets which script debug messages the player sees (0 none, 1 errors, 2 plus warnings, 3 everything).Player Script Debug Level setTurns slow motion on or off for a player: on the weapon wheel (Player Slow Motion Enabled "wheel"), on stunts ("stunt") or both.setTurns sprint stamina on or off for a player (or everyone:Player Stamina Enabled root). Off by default, so the character runs without getting tired.setAssigns a player to a team.Player Team nilorfalseremoves them from the team. FiresonPlayerTeamChange.setSets who hears the player's voice: one element, a list of elements, orPlayer Voice Broadcast To nil(everyone).setSets a player's voice channel. InPlayer Voice Channel "channels"mode players with the same channel hear each other anywhere on the map, like over a radio, while nearby players still hear each other normally in 3D. In other modes the channel has no effect.nilor an empty string removes the player from the channel.setSets whom the player does not hear.Player Voice Ignore From setMutes or unmutes a player in voice chat. A muted player's voice is not sent to anyone. Muting set with this function takes priority overPlayer Voice Muted mutedByDefaultin the server settings.setSets the player's wanted level (0-6 stars).Player Wanted Level setTurns voice chat on or off on the server.Voice Enabled setChanges one voice chat setting. The change takes effect immediately for all players. Names and ranges are the same as inVoice Setting getVoiceSettings; numbers out of range are clamped (e.g.range500 gives 250).pushToTalkKeyis a key name like inbindKey("z","lalt","mouse4","f5") and is only the default key: a player who picked their own in the ESC menu keeps it.setChanges several voice chat settings at once. The others stay unchanged. If any value is bad, nothing is changed.Voice Settings spawnSpawns a player at the given place: position, rotation, skin, interior and dimension.Player takeTakes money from the player.Player Money takeTakes a screenshot of the player's game (JPEG, without the overlay). The result arrives in thePlayer Screen Shot onPlayerScreenShotevent.
Client functions 2
getReturns how loud a player is talking right now:Player Voice Level -1when silent, and while talking a level from0(quiet) to3(loud). Useful for your own talk indicators.getReturns the local player's talk key: their own from the ESC menu or, if they did not pick one, the server's default key. The second value is a name to show on screen.Voice Push To Talk Key
Shared functions 19
getReturns the player whose computer runs the script. TheLocal Player localPlayervariable gives the same. On the server it returnsfalse.getFinds a player by nickname. On the client letter case does not matter.Player From Name getReturns the player's money. The server holds the balance; the in-game counter only displays it.Player Money getReturns the player's nickname.Player Name getReturns the nametag text (the nickname by default).Player Nametag Text getReturns the player's ping in milliseconds.Player Ping getReturns all players. The same asPlayers getElementsByType("player").getReturns the player's wanted level (0-6 stars). Only the server gives stars; the game never does on its own.Player Wanted Level getReturns all of the server's voice chat settings as a table. Keys:Voice Settings enabled,mode("proximity"– heard nearby,"global"– everyone hears everyone,"channels"– nearby plus channels),range(range in metres, 3–250, default 40),minDistance(up to this distance the voice has full volume, default 2),falloff(volume drop with distance:"linear","inverse","exponential"),wallDamping(damping through walls 0–1, default 0.75),pushToTalk,pushToTalkKey(default talk key,"z"),bitrate(quality in kb/s, 8–64, default 32),occlusion,reverb,vehicleMuffle(muffled inside a closed car),indicator(icon above the speaker) andmutedByDefault(new players are muted). The client gets the same table as the server.isChecks whether the game's hints and tutorials are enabled for a player (Player Help Texts Enabled setPlayerHelpTextsEnabled). On the client it checks the local player.isChecks whether a game HUD component is visible for the player (according toPlayer Hud Component Visible setPlayerHudComponentVisible). A component with no setting of its own follows"all".isChecks whether the player's nametag is shown.Player Nametag Showing isChecks whether a player is talking through voice chat right now. On the client, for the local player it means their microphone is transmitting.Player Talking isChecks whether a player is muted in voice chat: byPlayer Voice Muted setPlayerVoiceMutedor, if that function was not used, by the server settingmutedByDefault. Also works on the client.isChecks whether the player sees the game's WASTED screen after death.Player Wasted Screen Enabled isChecks whether voice chat is enabled on the server.Voice Enabled setTurns the game's hints and tutorials on or off (the San Andreas help box, e.g. the first time you pull a driver out of a car). They are off by default. On the server you pass a player orPlayer Help Texts Enabled root(everyone); on the client the change only affects that player.setShows or hides a game HUD component. Each component works on its own: hiding money keeps health, armour, the weapon, the clock and the rest of the HUD in place.Player Hud Component Visible "all"affects all of them at once (including the radar) and clears earlier settings of single components. Components:ammo,armour(orarmor),breath,clock,health,money,weapon,wanted,area_name,vehicle_name,radio,radar,all. The setting survives death and respawn; after reconnecting set it again (e.g. inonPlayerJoin).setTurns on the game's WASTED screen (text and red overlay) after the player dies. Off by default.Player Wasted Screen Enabled
Server events 27
onArrives right afterPlayer ACInfo onPlayerJoinwith information about the player's game modifications. The detected list is empty because the client does not detect them yet.onA player changed their nick (e.g.Player Change Nick setPlayerName).onA client script tried to change a protected element data key: a key set by the server withPlayer Changes Protected Data setElementData(..., "deny"), or any key whenserver-config.jsonhas"element_data_client_changes": "deny". The change is rejected and the player gets the server value back.onA player is connecting to the server, before their element is created. You can reject the connection, e.g. because of the nick or a ban.Player Connect onThe element under the player's feet changed (a vehicle or an object they stand on).Player Contact onA player took damage: from a weapon, a fall, a vehicle or an explosion. For a grenade or rocket explosionPlayer Damage attackeris the player who caused it.onA player joined the server. A good place for a greeting, login and the first spawn.Player Join onArrives afterPlayer Mod Info onPlayerACInfo, only when the client found files that are not part of the game in its folder:.pak/.utoc/.ucaspackages inContent/Paksother thanpakchunk0andpakchunk1, or.asiplugins. You can kick the player based on it.onA player was muted (Player Mute setPlayerMuted). A muted player cannot chat.onThe player's connection stalled (statusPlayer Network Status 0, no data for over 12 seconds) or came back (1).onA player left the server. The player element still exists, so you can save their data. Reasons are in Polish, e.g.Player Quit "rozlaczony"(disconnected) or"przekroczony czas oczekiwania"(timed out).onThe player has loaded the game and appeared in the world for the first time. A good place for a welcome, because the player can already see the screen.Player Ready onA resource started on a player's client (after theirPlayer Resource Start onClientResourceStart), once per resource start. From now on you can send themtriggerClientEventfrom this resource.onThe result ofPlayer Screen Shot takePlayerScreenShotarrives: a JPEG of the player's game frame (without the script overlay) or information that it failed.onA player appeared in the world (the first time or after death), e.g. afterPlayer Spawn spawnPlayer.onA player kills someone silently with a knife from behind. You can block the kill; otherwise the victim getsPlayer Stealth Kill onPlayerWastedwithstealth=true.onA player moved in a way that is impossible in the game (a teleport or too high a speed). Script teleports, spawns and interior entries do not count. It only works when the server config hasPlayer Suspicious Move "anticheat": true. The server itself undoes nothing and kicks nobody; the script decides the punishment (automatic kicking after a threshold is enabled with"anticheat_kick": true).onA player aims at something else: a player, a ped, an object, a vehicle or nothing. Checked every 250 ms.Player Target onA player changed team (Player Team Change setPlayerTeam).onA player sends too many events and actions (over 100 per second). It may be a client script bug or a flooding attempt.Player Trigger Event Threshold onA player triggered an event the server does not know or that does not allow client calls (Player Trigger Invalid Event addEvent(name, true)).onA player was unmuted.Player Unmute onA player started talking through voice chat (start of an utterance). You can block it: then nobody hears this utterance until the player stops talking.Player Voice Start onA player stopped talking through voice chat. It also happens when the player's voice stopped arriving (e.g. a lost connection). It does not happen for an utterance blocked inPlayer Voice Stop onPlayerVoiceStart.onA player died: from a weapon, in an accident, an explosion or by a script.Player Wasted onA player's GPS waypoint disappeared: removed on the map, by a script or the player reached it.Player Waypoint Remove onA player has a new game GPS waypoint (confirmed by their game): placed with a right click on the ESC map or by a script.Player Waypoint Set
Client events 7
onAnother player's animation. The event is registered, but the current client does not send these reports yet, so it does not arrive for now.Client Player Anim onAnother player's game reported a hit: aClient Player Hit datatable with the target element number (target), damage (damage), weapon (w) and body part (bp).onAnother player joined the server.Client Player Join onAnother player left the server.Client Player Quit onA player (local or another) appeared in the world.Client Player Spawn onA player (local or another) died.Client Player Wasted onA player fired a firearm: you or another nearby player whose shots are shown in your game. It arrives once per bullet, with the muzzle point and the hit point. The game collects shots only while some script listens to this event.Client Player Weapon Fire