====== Special System Control Functions ======

This page contains a list of special functions that are used to control how the scripting engine behaves. For example, you can use ''CustomEvent'' to trigger a specified script event, or use ''Sleep'' to pause the execution of a script for a while.


==== Sleep ====
^ Format : | Sleep( [time] ) |
^ Description : | Pauses the event for a period of time. Cannot currently be used in a function (only an event). |
^ Parameters: | [time] - Sleep time in 1/10ths of a second |
//Example//:<note>
<code>Event( "UseSkill", "Magic" )
{
    *effect %PLAYER% 1
    Sleep(10)
    *effect %PLAYER% 1
}
</code>
</note>

==== sysSetTimer ====
^ Format | sysSetTimer ( [interval (seconds)], [eventname], [eventparams] ) |
^ Description | After the specified period of time a 'Timer' event will be triggered. |
^ Parameters | **[interval]** - Number of seconds to pass before the timer event is triggered |
^ | **[eventname]** - Name of the timer event to be triggered |
^ | **[eventparams]** - Parameter values to be passed in to the timer event |
^ Returns | **[TimerID]** - ID number of the timer which can be used with ***killtimer [ID]** to cancel a timer |
^ Notes | The context in the subsequent Timer event will be the same as the event that activated the timer. |
//Example//: <note>
<code>Event( "UseItem", "Alarm Clock" )
{
    sysSetTimer( 10, "Alarm", "" )
}

Event( "Timer", "Alarm" )
{
    *msg %PLAYER% Your alarm clock started ringing 10 seconds later
}
</code>
</note>

==== sysDeleteTimer ====
TBD \\
\\

==== CancelTransaction ====
^ Format | CancelTransaction () |
^ Description | This is a special script function used to notify the game that the normal processing for an event should be cancelled. In some types of event (a 'Custom' one for instance) this does nothing, in others it can be used to easily add scripted logic to the game - e.g. Calling CancelTransaction() in a "PreAccessBuilding" event can be used to control whether a player can access a particular building type |
//Example//:<note>
<code>Event( "PreAccessBuilding", "10" )
{
    $hasKeys = sysPlayerInventory( "Keys" )
    if ( $hasKeys == 0 )
    {  
        *msg %PLAYER% You cannot access this building without keys
        CancelTransaction()
    }
}
</code>
</note>

==== SetContext ====
^ Format | SetContext( [Player ID] )|
^ Description | Changes the script context to the specified playerID. When the context is changed, all operations and functions will be applied to the new player - e.g. gPlayerVar[..] accesses the new player ID's variables, sysPlayerInventory checks the new player's inventory. |
^ Parameters | Player ID |
^ Returns | None |
^ Notes | Use **RestoreContext** to set the context back to the original player |
//Example//: <note>
<code>Event( "UseItem", "Potion" )
{
    SetContext( $gTargetID )
    $targetHasShield = sysPlayerInventory( "Shield" )
    RestoreContext()
    
    if ( $targetHasShield > 0 )
    {
        *msg %PLAYER% You cannot use the potion on %TARGET% as they have a shield
        CancelTransaction()
    }
}
</code>
</note>

==== RestoreContext ====

==== SetBuildingContext ====


==== sysArraySize ====
TBD //
//


==== PlayerTaskStartSetTime ====
TBD \\
\\

==== CustomEvent ====
Triggers a custom event
TBD \\
\\