Universal World Owners Manual

User Tools

Site Tools

Trace: • playerstatusfunctions
scripting:reference:system_functions:playerstatusfunctions

Differences

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

Link to this comparison view

Next revision		Previous revision
scripting:reference:system_functions:playerstatusfunctions [2020/01/29 10:31] – created mitscripting:reference:system_functions:playerstatusfunctions [2025/05/28 18:58] (current) – external edit 127.0.0.1
Line 1: Line 1:
-=== Player Status Functions === +=== Player Information Functions ===
-System functions that provide you information about the player+
  
-==== sysAddToInventory ==== +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**.
-^ Format | sysAddToInventory ( [Item], [Amount] )| +
-^ Description | Attempts to add an item to the current player's inventory. | +
-^ Parameters | **[Item]** - Name or number of the item | +
-^ | **[Amount]** - Amount of the item to be added | +
-^ Returns | **[Amount added]** - The actual amount of the item that was added | +
-^ Notes | This is an alternate method to calling ***grantitem [PlayerName] [Amount] [Item]** but the sys function does not message the player unlike *grantitem. Also, this function adheres to the player's capacity limit (*grantitem ignores it) - no items will be added if the player's inventory is already full. | +
-//Example//: <note> +
-<code>Event( "UseSkill", "Baker" ) +
-{ +
-    $added = sysAddToInventory( "Bread", 3 ) +
-    if ( $added > 0 ) +
-    { +
-        *msg %PLAYER% You made yourself $added Bread +
-    } +
-    else +
-    { +
-        *alert %PLAYER% You're carrying too much stuff +
-    } +
-} +
-</code></note> +
-==== sysGetInventoryItemIndex ==== +
-^ Format | sysGetInventoryItemIndex ( [index] )| +
-^ Description | Returns the item in the current player's inventory. | +
-^ Parameters | **[index]** - Inventory slot number | +
-^ Returns | **[ItemNum]** - The item number in the specified inventory slot (or 0 if the slot is empty) | +
-^ Notes | Players currently have up to 64 inventory slots. | +
-//Example//: <note> +
-<code>Event( "Custom", "ListInventory" ) +
-{ +
-    $loop = 0 +
-    while( $loop < 64 ) +
-    { +
-       $itemNum = sysGetInventoryItemIndex( $loop ) +
-       if ( $itemNum != 0 ) +
-       { +
-          *msg %PLAYER% Item $loop : $itemNum +
-       } +
-    } +
-} +
-</code> +
-</note>+
  
-==== 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 ==== ==== sysGetPlayerID ====
-^ Format | sysGetPlayerID( [Player Name] )|+^ Format | sysGetPlayerID( Player Name )|
 ^ Description | Returns the ID for a specified player name | ^ Description | Returns the ID for a specified player name |
-^ Parameters | Player Name | 
 ^ Returns | Player ID | ^ Returns | Player ID |
 //Example//: <note> //Example//: <note>
Line 85: Line 21:
         *msg %PLAYER% Bob's player ID is $playerID         *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> </code>
Line 91: Line 40:
  
 ==== sysIsPlayerIDOnline ==== ==== sysIsPlayerIDOnline ====
-^ Format | sysIsPlayerIDOnline( [Player ID] )|+^ Format | sysIsPlayerIDOnline( Player ID )|
 ^ Description | Used to determine if the specified player is currently online on the world | ^ 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 | ^ Returns | **1** if the player is connected, **0** if not |
 ^ Example | ''**$isOnline = sysIsPlayerIDOnline(32)**'' | ^ Example | ''**$isOnline = sysIsPlayerIDOnline(32)**'' |
  
 ==== sysIsInSpawnZone ==== ==== 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 | ^ 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 | ^ Returns | **1** if the player is in the region, **0** if not |
 ^ Example | ''**$isInDefaultSpawnZone = sysIsInSpawnZone(0)**'' | ^ Example | ''**$isInDefaultSpawnZone = sysIsInSpawnZone(0)**'' |
  
-==== sysIsInTown ==== +==== sysPlayerIsInTown ==== 
-Example : ''**$var = sysIsInTown("Home Town"))**''  \\+Example : ''**$var = sysPlayerIsInTown("Home Town"))**''  \\
 Returns 1 if the current player is within the boundaries of the specified town, 0 if not \\ Returns 1 if the current player is within the boundaries of the specified town, 0 if not \\
  
Line 112: Line 60:
 Returns the number of players currently online and in the specified team  \\ Returns the number of players currently online and in the specified team  \\
  
-==== sysPlayerInventory ==== 
-^ Format | sysPlayerInventory ( [Item] )| 
-^ Description | Returns the number of an item the current player currently posesses | 
-^ Parameters | **[Item]** - Name or number of the item | 
-^ Returns | Amount carried | 
-//Example//: <note> 
-<code>Event( "PreAccessBuilding", "10" ) 
-{ 
-    $hasKeys = sysPlayerInventory( "Keys" ) 
-    if ( $hasKeys == 0 ) 
-    { 
-       *msg %PLAYER% You cannot access this building without keys 
-       CancelTransaction() 
-    } 
-} 
-</code> 
-</note> 
  
 ==== sysPlayerSkillLevel ==== ==== sysPlayerSkillLevel ====
Line 137: Line 68:
 Example : ''**$isLearning = sysPlayerIsLearningSkill("Farmer")**'' \\ Example : ''**$isLearning = sysPlayerIsLearningSkill("Farmer")**'' \\
 Returns **1** if the player is currently learning the specified skill, **0** if not. \\ 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 //
 +//
 +
 +
  
scripting/reference/system_functions/playerstatusfunctions.1580293894.txt.gz · Last modified: (external edit)