Differences

This shows you the differences between two versions of the page.

--- scripting:reference:system_functions:playerstatusfunctions [2020/01/29 06:42] – [sysIsInTown] mit
+++ scripting:reference:system_functions:playerstatusfunctions [2023/04/15 14:00] (current) – mit
@@ Line 1: / Line 1: @@
-=== Player Status Functions ===
+=== Player Information Functions ===
-System functions that provide you information about the player
+Most of the information about the player who has triggered the script event is available through [[scripting:reference:system_value|System Values]] - e.g **$gPlayerID**, **$gPlayerCash**, **$gPlayerX** & **$gPlayerY**.
-==== sysGetNearestPlayer ====
+These system functions can provide information about other players or query extra information about the context player, such as whether they have a particular skill or if they're in a specific town..
-^ Format | sysGetNearestPlayer( [WorldX], [WorldY] )|
-^ Description | Returns the ID of the player closest to the specified world coordinate |
-^ Parameters | World Coordinate X,Y |
-^ Returns | Player ID |
-//Example//: <note>
-<code>
-$kSpecialBuildingRecordNum = 10
-Event( "UseItem", "Plunger" )
-{
-    SetBuildingContext( $kSpecialBuildingRecordNum )
-    $posX = $gBuildingWorldX
-    $posY = $gBuildingWorldY
-    $targetPlayerID = sysGetNearestPlayer( $posX, $posY )
-    $targetPlayerName = sysGetPlayerName( $targetPlayerID )
-    *say %PLAYER% used the plunger. The person closest to the special building was $targetPlayerName
-    *explodebuilding $kSpecialBuildingRecordNum
-}
-</code>
-</note>
 ==== sysGetPlayerID ====
-^ Format | sysGetPlayerID( [Player Name] )|
+^ Format | sysGetPlayerID( Player Name )|
 ^ Description | Returns the ID for a specified player name |
-^ Parameters | Player Name |
 ^ Returns | Player ID |
 //Example//: <note>
@@ Line 43: / Line 21: @@
         *msg %PLAYER% Bob's player ID is $playerID
     }
+}
+</code>
+</note>
+==== sysGetPlayerName====
+^ Format | sysGetPlayerName( PlayerID )|
+^ Description | Returns the name for a specified player ID |
+^ Returns | Player Name |
+//Example//: <note>
+<code>Event( "Custom", "Special" )
+{
+    $name = sysGetPlayerID( $gServerKey[StoredPlayerID] )
+    *msg %PLAYER% The player ID stored in the server key is for the player name $name
 }
 </code>
@@ Line 49: / Line 40: @@
 ==== sysIsPlayerIDOnline ====
-^ Format | sysIsPlayerIDOnline( [Player ID] )|
+^ Format | sysIsPlayerIDOnline( Player ID )|
 ^ Description | Used to determine if the specified player is currently online on the world |
-^ Parameters | Player ID |
 ^ Returns | **1** if the player is connected, **0** if not |
 ^ Example | ''**$isOnline = sysIsPlayerIDOnline(32)**'' |
 ==== sysIsInSpawnZone ====
-^ Format | sysIsInSpawnZone( [SpawnZone Type/ID] )|
+FIXME: This function name is inconsistent, as it only acts on the context player it needs to be renamed to 'sysPlayerIsInSpawnZone'
+^ Format | sysIsInSpawnZone( SpawnZone_Type/ID )|
 ^ Description | Used to determine if the current player is within the specified spawn zone region |
-^ Parameters | SpawnZone Type/ID |
 ^ Returns | **1** if the player is in the region, **0** if not |
 ^ Example | ''**$isInDefaultSpawnZone = sysIsInSpawnZone(0)**'' |
@@ Line 78: / Line 68: @@
 Example : ''**$isLearning = sysPlayerIsLearningSkill("Farmer")**'' \\
 Returns **1** if the player is currently learning the specified skill, **0** if not. \\
+==== sysNumPlayersWithPlayerVarVal ====
+Example : ''**sysNumPlayersWithPlayerVarVal( 6, 2 )**'' returns number of players with ''$gPlayerVar[6] == 2''. Useful for determining results of a team game. //
+//
+==== sysGenerateTopPlayerVarsList ====
+^ Format | sysGenerateTopPlayerVarsList( VarNum, Num_players_to_list )|
+^ Description | Generates a list of players sorted by the $gPlayerVar selcted. e.g. ''**sysGenerateTopPlayerVarsList(2, 5))**'' will generate a list of the top 5 players with the highest value in $gPlayerVar[2]. Your script can then access the generated list using **sysGetTopPlayer** |
+^ Returns | The number of players actually added to the list. (Only players with the PlayerVar above 0 get added) |
+\\
+==== sysGetTopPlayer ====
+^ Format | sysGetTopPlayer ( List_Index )|
+^ Description | Access the list of top players generated using sysGenerateTopPlayerVarsList. List_Index starts at 0, so ''**sysGetTopPlayer(0)**'' gets the person at the top of the list, (1) gets the second, etc. |
+^ Returns | PlayerID |
+//
+//
+==== sysGetPlayerListScore ====
+^ Format | sysGetPlayerListScore ( PlayerID )|
+^ Description | Returns the 'PlayerListScore' for the specified player. The PlayerListScore is a special score field that is replicated to the clients and can appear next to their name in the player list. |
+^ Returns | Score value |
+FIXME : Separate below into separate PlayerListScore page:
+*settings PlayerListMode  has options to show the score on the player list.\\
+commands *incplayerlistscore, *setplayerlistscore \\
+Related Subgame functions:
+SubgameActivatePlayerListScores( SubgameID, Mode )\\
+SubgameGetHighestPlayerListScore( SubgameID )\\
+SubgameNumPlayersWithPlayerListScore( SubgameID, Score )\\
+SubgameGetPlayerWithPlayerListScore( SubgameID, Score, Index )\\
+//Example//: <note>
+<code>TBD</code>
+</note>
+TBD //
+//