Table of Contents

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:

Event( "UseSkill", "Magic" )
{
    *effect %PLAYER% 1
    Sleep(10)
    *effect %PLAYER% 1
}

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:

Event( "UseItem", "Alarm Clock" )
{
    sysSetTimer( 10, "Alarm", "" )
}

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

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:

Event( "PreAccessBuilding", "10" )
{
    $hasKeys = sysPlayerInventory( "Keys" )
    if ( $hasKeys == 0 )
    {  
        *msg %PLAYER% You cannot access this building without keys
        CancelTransaction()
    }
}

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:

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()
    }
}

RestoreContext

SetBuildingContext

sysArraySize

TBD

PlayerTaskStartSetTime

TBD

CustomEvent

Triggers a custom event TBD