===== Text Functions =====

Special text codes are used to get the names of things associated with the current script context, these are:

**%PLAYER%** : Name of the player \\
**%BUILDINGOWNER%** : Name of the owner of the building in context (where applicable)\\
**%KILLER%** : Name of the player who killed the player (Applicable in "PlayerKilled" and "RobocrowKilled" events)\\
**%TARGET%** : Name of the target of an event (e.g. "BarterRequest", "MenuOption" and 'Battle'events. Also sometimes valid in "UseItem" if the targeting system is active).\\
\\
Other system functions allow you to get the names and text representations of different aspects of your world, and convert from a text name to an ID number and vice versa:

==== sysGetPlayerName ====
^ Format | sysGetPlayerName( PlayerID )|
^ Description | Returns the name of the specified player|
^ Returns | Player Name |
//Example//: <note>
<code>Event( "UseItem", "Potion" )
{
    $targetName = sysGetPlayerName( $gTargetID )
    *msg %PLAYER% You used the potion while targeting $targetName
}
</code>
</note>

==== sysGetItemName ====
Example : ''**$var = sysGetItemName ($itemNum))**''  \\
TBD\\

==== sysGetSkillName ====
Example : ''**$var = sysGetSkillName($skillNum))**''  \\
TBD\\

==== sysGetItemNum ====
^ Format | sysGetItemNum( Item Name )|
^ Description | Gets an item number from a name|
^ Returns | Item number |
//Example//: <note>
<code>Event( "UseItem", "Potion" )
{
    $itemNum = sysGetItemNum( "Potion" )
    *msg %PLAYER% The item number is $itemNum
}
</code>
</note>

==== sysGetSkillNum ====
TBD\\

==== sysGetPriceText ====
^ Format | sysGetPriceText ( Price )|
^ Description | Returns a text string displaying the price value expressed in a short format - e.g 2s 3d |
^ Returns | Price text |
^ Notes | Price parameter is the value in denari |
//Example//: <note>
<code>Event( "UseItem", "Potion" )
{
    $price = 20
    if ( $gPlayerCash < $price )
    { 
        $priceText = sysGetPriceText( $price )
        *alert %PLAYER% You need at least $priceText to use the potion
        CancelTransaction()
    }
    else
    {
        *grantcash %PLAYER% -$price
    }
}
</code>
</note>
==== sysGetDateText ====
^ Format | sysGetDateText( Unix_Time )|
^ Description | Returns a text string displaying the date and time |
^ Returns | Text of the date and time (e.g. "31st December 2014 18:00" ) |
^ Notes | Parameter is 'Unix time' ; (Number of seconds since 1 Jan 1970) |
//Example//: <note>
<code>Event( "UseItem", "Potion" )
{
    $nextUsePotionTime = $gServerTimeVar[0]
    $currTime = sysGetRealTime( "UnixTime" )
    if ( $currTime < $nextUsePotionTime )
    {
        $useDateText = sysGetDateText( $nextUsePotionTime )
        *msg %PLAYER% You cannot use the potion until $useDateText
        CancelTransaction()
    }
    else
    {
        // Set server variable to store the next time the potion can be used - one hour from now
        $kOneHourInSeconds = 60 * 60
        $gServerTimeVar[0] = $currTime + $kOneHourInSeconds    
    }
}
</code>
</note>

==== sysGetTimeText ====
^ Format | sysGetTimeText ( Num_seconds )|
^ Description | Returns text form of the time provided in seconds using the most appropriate resolution ; i.e. if you pass 110 seconds, the text will be "1 minute and 50 seconds".. if you pass 28920 it'll be "8 hours and 2 minutes"|
^ Returns | Text representation of given time period |
//Example//: <note>
<code>Event( "&command", "TimeSinceLast" )
{
    $currTime = sysRealTime( "UnixTime" ) 
    $lastTime = $gPlayerKey["TimeSinceLast"]
    if ( $lastTime == 0 )
    {
        *msg %PLAYER% This is the first time you've used this command
    }
    else
    {
        $timeSince = $currTime - $lastTime
        $timeSinceText = sysGetTimeText( $timeSince )
        *msg %PLAYER% It has been $timeSinceText since you last used this command
    }
    $gPlayerKey["TimeSinceLast"] = $currTime
}
</code>
</note>


==== sysGetRealTimeTextForDays ====
^ Format | sysGetRealTimeTextForDays ( Number_of_game_days )|
^ Description | Returns a text description of the time that will pass for the specified number of game days, using the most appropriate resolution. (e.g. If the result is 30 seconds, it'll return "30 seconds", if the result is 36000 seconds it'll return "10 hours"  |
^ Returns | Time text |
//Example//: <note>
<code>Event( "UseItem", "Magic Potion" )
{
    $daysSinceLastUsed = $gGameDay - $gPlayerKey[LastUsedPotionDay]
    if ( $daysSinceLastUsed < 10 )
    {
        $daysUntilCanUse = 10 - $daysSinceLastUsed
        $timeText = sysGetRealTimeTextForDays( $daysUntilCanUse )
        *say You must wait $timeText until you can use the Magic Potion again
    }
    else
    {
        *effect %PLAYER% 10
        $gPlayerKey[LastUsedPotionDay] = $gGameDay
    }
}
</code>
</note>