=== Player Information Functions ===

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**.

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..

==== sysGetPlayerID ====
^ Format | sysGetPlayerID( Player Name )|
^ Description | Returns the ID for a specified player name |
^ Returns | Player ID |
//Example//: <note>
<code>Event( "Custom", "Special" )
{
    $playerID = sysGetPlayerID( "Bob" )
    if ( $playerID <= 0 )
    {
        *msg %PLAYER% Bob doesn't exist on this world
    }
    else
    {
        *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>
</note>


==== sysIsPlayerIDOnline ====
^ Format | sysIsPlayerIDOnline( Player ID )|
^ Description | Used to determine if the specified player is currently online on the world |
^ Returns | **1** if the player is connected, **0** if not |
^ Example | ''**$isOnline = sysIsPlayerIDOnline(32)**'' |

==== sysIsInSpawnZone ====
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 |
^ Returns | **1** if the player is in the region, **0** if not |
^ Example | ''**$isInDefaultSpawnZone = sysIsInSpawnZone(0)**'' |

==== sysPlayerIsInTown ====
Example : ''**$var = sysPlayerIsInTown("Home Town"))**''  \\
Returns 1 if the current player is within the boundaries of the specified town, 0 if not \\

==== sysNumPlayersOnTeam ====
Example : ''**$var = sysNumPlayersOnTeam(3)**'' \\
Returns the number of players currently online and in the specified team  \\


==== sysPlayerSkillLevel ====
Example : ''**$var = sysPlayerSkillLevel("Farmer")**'' \\
Returns the current player's skill level for the skill named (0 means the player does not yet have this skill) \\

==== sysPlayerIsLearningSkill ====
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 //
//