User Tools

Site Tools


scripting:reference:system_functions

This is an old revision of the document!


Table of Contents

System Functions

The scripting engine provides a set of 'System Functions', usually preceded by sys. Below is the complete list of system functions currently available.

Special Scripting Language Functions

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
}

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

sysArraySize

TBD

Player-status Functions

sysAddToInventory

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:

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

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 16 inventory slots.

Example:

Event( "Custom", "ListInventory" )
{
    $loop = 0
    while( $loop < 16 )
    {
       $itemNum = sysGetInventoryItemIndex( $loop )
       if ( $itemNum != 0 )
       {
          *msg %PLAYER% Item $loop : $itemNum
       }
    }
}

sysGetPlayerID

Format sysGetPlayerID( [Player Name] )
Description Returns the ID for a specified player name
Parameters Player Name
Returns Player ID

Example:

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

sysIsPlayerIDOnline

Example : $var = sysIsPlayerIDOnline(32))
Returns 1 if the specified player (BillingID) is currently online, 0 if not

sysIsInSpawnZone

Example : $var = sysIsInSpawnZone(2))
Returns 1 if the current player is in the specified spawn zone, 0 if not

sysIsInTown

Example : $var = sysIsInTown(“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

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:

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

sysPlayerSkillLevel

Example : $var = PlayerSkillLevel(“Farmer”)
Returns the current player's skill level for the skill named

sysPlayerIsLearningSkill

TBD

sysGetNearestPlayer

TBD

Player Building Ownership Functions

sysPlayerGetNumBuildingsOfType

Format sysPlayerGetNumBuildingsOfType ( [PlayerID], [BuildingType] )
Description Returns the number of buildings of a particular type that the specified player currently owns
Parameters [PlayerID] - ID number of the player
[BuildingType] - Building type number
Returns Number owned

Example:

Event( "Custom", "CountBuildings" )
{
    $numOwned = sysPlayerGetNumBuildingsOfType( $gPlayerID, 10 )
    *msg %PLAYER% You currently own $numOwned type 10 buildings
}

sysPlayerGetNearestOwnedBuildingOfType

Format sysPlayerGetNearestOwnedBuildingOfType ( [PlayerID], [BuildingType], [WorldX], [WorldY] )
Description Locates the nearest building of the specified type owned by the player. If no WorldX, WorldY is specified, the players current position is used instead
Parameters Player ID number
Building type number
WorldX, WorldY
Returns BuildingID or 0 if the player doesn't own a building of that type

Example:

Function	FindNearestBuildingOfType( $buildingType )
{
    $buildingID = sysPlayerGetNearestOwnedBuildingOfType( $gPlayerID, $buildingType )
    if ( $buildingID == 0 )
    {
        *msg %PLAYER% You don't own any type $buildingType buildings
    }
    else
    {
        $buildingName = sysGetBuildingName( $buildingID )
        *msg %PLAYER% The nearest type $buildingType building that you own is $buildingName
    }
}

sysPlayerGetOwnedBuilding

Format sysPlayerGetOwnedBuilding ( [PlayerID], [Index] )
Description Used to get the IDs of buildings owned by the player
Parameters [PlayerID] - Player ID number
[Index] - Number in the list of owned buildings
Returns BuildingID or 0 if the player doesnt own that many buildings

Example:

Function	SendOwnedBuildingsList( $playerID )
{
    $playerName = sysGetPlayerName( $playerID )

    $loop = 1
    while( $loop < 10 )
    {
        $buildingID = sysPlayerGetOwnedBuilding( $playerID, $loop )
	// No more buildings
       if ( $buildingID == 0 )
       {
	   return
	}
	 
	$buildingName = sysGetBuildingName( $buildingID )
	*msg $playerName Building $loop : ID = $buildingID ( $buildingName )
	$loop += 1
    }
}

Building Functions

sysAmountInStocks

Example : $var = sysAmountInStocks(“Bongos” ))
Returns the amount of the item named currently in the player's inventory.

sysGetBuyPrice

Format sysGetBuyPrice [Item] )
Description Returns the 'Buy Price' set for this item in the currently accessed building
Parameters Item name or number
Returns 'Buy Price' of the item in denari
Notes Related commands: *setbuyprice [BuildingID] [Item] [Price]

Example:

Event( "AccessBuilding", "2" )
{
    $buyPrice = sysGetBuyPrice( "Flour" )
    $buyPriceText = sysGetPriceText( $buyPrice )

    osdcreate( OSDBUILDING, "BakeryOSD", "Bakery" )
    osdaddat( 200, 100, 200, 40, "Sell|Flour", "Buying flour ($buyPriceText)" )
    osdactivate()
}

sysGetSellPrice

Example : $var = sysAmountInStocks(“Bongos” ))
TBD

sysGetEmployeeID

Format sysGetEmployeeID( [Index] )
Description Returns the employee player ID for the currently accessed building. Buildings can have up to 16 employees.
Parameters Index (0 - 15)
Returns PlayerID of the employee or 0 if none is set for this index

Example:

Event( "AccessBuilding", "12" )
{
    osdcreate( OSDBUILDING, "Building", "Example" )
    $employeeID = sysGetEmployeeID( 0 )
    if ( $employeeID != 0 )
    {
        $employeeName = sysGetPlayerName( $employeeID )
        osdaddat( TEXT, 100, 100, 400, 0, "", "Employee : $employeeName" )   
    }
    else
    { 
        osdaddat( TEXT, 100, 100, 400, 0, "", "There is no-one currently employed at this building" )
    }
    osdcreate()
}

sysGetBuildingName

Format sysGetBuildingName( [BuildingID] )
Description Returns the building name for a particular ID
Parameters Building ID number
Returns The building name

Example:

Event( "UseItem", "Map" )
{
    $nearestTownID = sysGetNearestTown( $gPlayerWorldX, $gPlayerWorldY )
    $nearestTownName = sysGetBuildingName( $nearestTownID )
    *msg %PLAYER% The nearest town is $nearestTownName
}

sysGetMaxJobs

TBD

Construction

sysIsBuildingPositionValid

Format sysIsBuildingPositionValid( [Building Type] )
Description Checks whether the player's current position is a valid place to add a building of the specified type
Parameters Building Type number
Returns 1 if the position is valid, 0 if not

Example:

Event( "PlaceAnyBuilding", "" )
{
    $buildingType = $gParam[1]
    $isValid = sysIsBuildingPositionValid( $buildingType )
    if ( $isValid == 1 )
    {
	$buildingName = sysGetTextEntry()
	$constrAmount = -1
	$didAdd = sysAddBuildingWorld( $buildingType,$gPlayerID,$gPlayerWorldX,$gPlayerWorldY,$buildingName,$constrAmount )
    }
}

sysAddBuilding

TBD

sysAddBuildingWorld

TBD

sysGetBuildingTypeName

TBD

sysGetConstructionMaterialsAmount

TBD

sysAddLocalBackgroundModel

TBD

sysDeleteLocalBackgroundModel

TBD

sysDeleteAllLocalBackgroundModels

TBD

sysAddBackgroundModels

TBD

Town Functions

sysGetNearestTown

sysTownGetRelationship

sysTownGetNumBuildingsOfType

Format sysTownGetNumBuildingsOfType( [TownBuildingID], [BuildingType] )
Description Returns the number of buildings of this type currently exist within the specified town. Useful for when you want to script a system that limits the number of a particular type of building per town
Parameters BuildingID of the town to query
Type number of the building to check
Returns Number of this type of building in the town

Example:

Event( "PlaceAnyBuilding", "" )
{
    $nBuildingType = $gParam[1]

    $nearestTownID = sysGetNearestTown( $gPlayerWorldX, $gPlayerWorldY )
    $numInTown = sysTownGetNumBuildingsOfType( $nearestTownID, $nBuildingType )
    if ( $numInTown >= 3 )
    {
       *msg %PLAYER% There can only be 3 of each type of building in each town
       CancelTransaction()
    }
    else
    {
	$valid = sysIsBuildingPositionValid( $nBuildingType )
	if ( $valid = 1 )
	{
		$buildingName = sysGetTextEntry()
		$constrAmount = -1
		$didAdd = sysAddBuildingWorld( $nBuildingType,$gPlayerID,$gPlayerWorldX,$gPlayerWorldY,$buildingName,$constrAmount )
	}
    }
}

World / Map Functions

sysGetTileCenter

Format sysGetTileCenter ( [World X or Y] )
Description Returns the world coordinate value for the center of the map tile nearest to the specified position
Parameters [World X or Y] - World coordinate value
Returns World coordinate of tile center

Example:

Event( "UseItem", "TileTeleport" )
{
    $tileCenterX = sysGetTileCenter( $gPlayerWorldX )
    $tileCenterY = sysGetTileCenter( $gPlayerWorldY )
    *setposworld %PLAYER% $tileCenterX $tileCenterY
}

sysMapToWorld

Format sysMapToWorld ( [Map X or Y] )
Description Converts a map coordinate to a world coordinate
Parameters [Map X or Y] - Map coordinate value
Returns World coordinate

Notes: There are 2 coordinate systems used in the game ; Map Coordinates range from 0 to 255 (for the default map size), 0 to 511 or 0 to 1023 (if using a larger map size) and they correspond to the 'tiles' that make up the landscape. World coordinates are in centimeters.

sysWorldToMap

Format sysWorldToMap ( [Map X or Y] )
Description Converts a world coordinate to a map coordinate
Parameters [World X or Y] - World coordinate value
Returns Nearest map coordinate value

sysGetBuildingAtWorldPos

sysWorldGetNumBuildingsOfType

Format sysWorldGetNumBuildingsOfType( [BuildingType] )
Description Returns the number of buildings of this type currently existing within the world. Useful for when you want to script a system that limits the number of a particular type of building
Parameters Type number of the building to check
Returns Number of this type of building currently in the world

Example:

Event( "PlaceAnyBuilding", "" )
{
    $nBuildingType = $gParam[1]

    $numInWorld = sysWorldGetNumBuildingsOfType( $nBuildingType )
    if ( $numInWorld >= 1 )
    {
       *msg %PLAYER% There can only be 1 of each type of building in the world
       CancelTransaction()
    }
    else
    {
	$valid = sysIsBuildingPositionValid( $nBuildingType )
	if ( $valid = 1 )
	{
		$buildingName = sysGetTextEntry()
		$constrAmount = -1
		$didAdd = sysAddBuildingWorld( $nBuildingType,$gPlayerID,$gPlayerWorldX,$gPlayerWorldY,$buildingName,$constrAmount )
	}
    }
}

sysGetNearestForest

Text Functions

sysGetPlayerName

Format sysGetPlayerName( [PlayerID] )
Description Returns the name of the specified player
Parameters Player ID
Returns Player Name

Example:

Event( "UseItem", "Potion" )
{
    $targetName = sysGetPlayerName( $gTargetID )
    *msg %PLAYER% You used the potion while targeting $targetName
}

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
Parameters Item Name
Returns Item number

Example:

Event( "UseItem", "Potion" )
{
    $itemNum = sysGetItemNum( "Potion" )
    *msg %PLAYER% The item number is $itemNum
}

sysGetSkillNum

TBD

sysGetPriceText

Format sysGetPriceText ( [Price] )
Description Returns a text string displaying the price value expressed in a short format - e.g 2s 3d
Parameters Price value (in denari)
Returns Price text

Example:

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

sysGetDateText

Format sysGetDateText( [Unix Time] )
Description Returns a text string displaying the date and time
Parameters Unix time (Number of seconds since 1 Jan 1970)
Returns Text of the date and time (e.g. “31st December 2014 18:00” )

Example:

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

sysGetTimeText

TBD

sysGetRealTimeTextForDays

TBD

Context Functions

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

Battle game Functions

BattleSetPreludeTime

BattleSetNumRounds

BattleSetRoundTime

BattleSetRoundScore

BattleSendChallenge

Misc other functions

sysRand

Example : $var = Rand(500)
Returns a random number between 1 and the value specified

sysRealTime

Format sysRealTime ( [Type] )
Description Returns details of the current real time (according to the server clock)
Parameters Type field specifying the date or time to fetch
Returns Depending on the type field:
Year - returns the current year (e.g. 2014)
Month - returns the current month number (1 to 12)
Day - returns the current day number (1 to 31)
Hour - returns the current hour (0 to 23)
Minute - returns the current minute (0 to 59)
Second - returns the current second (0 to 59)
UnixTime - number of seconds passed since 1st Jan, 1970

Example:

Event( "UseItem", "Tea" )
{
   $hour = sysRealTime( "Hour" )
   if ( $hour < 18 )
   {
      *msg %PLAYER% Tea can only be used at tea-time (6pm - 8pm)
    }
    else if ( $hour >= 20 )
    {
      *msg %PLAYER% Tea can only be used at tea-time (6pm - 8pm)    
    }
    else
    {
        *notifylarge %PLAYER% Tea-time!
    }
}

sysGetDist

Format sysGetDist ( [X1], [Y1], [X2], [Y2] )
Description Calculates the distance between two points
Parameters Point 1 X,Y
Point 2 X,Y
Returns Distance

Example:

Event( "AccessBuilding", "1" )
{
    $dist = sysGetDist( $gPlayerWorldX, $gPlayerWorldY, $gBuildingWorldX, $gBuildingWorldY )
    *msg %PLAYER% You accessed the building from $dist cm away
}

sysSin

Format sysSin ( [ANGLE], [SCALE] )
Description Returns a sine value
Parameters Angle - 0 to 360 degrees
Scale - Scale applied to the result from the sine function (which normally returns a value from -1 to 1
Returns Scaled sine value

Example:

Event( "Custom", "TreeCircle" )
{
    $angle = 0
    while ( $angle < 360 )
    {
        $posX = sysSin( $angle, 100 )
        $posY = sysCos( $angle, 100 )
        $posX += $gPlayerWorldX
        $posY += $gPlayerWorldY
        *addtree 1,$posX,$posY
        $angle += 36        
    }
}

sysCos

Format sysCos ( [ANGLE], [SCALE] )
Description Returns a cosine value
Parameters Angle - 0 to 360 degrees
Scale - Scale applied to the result from the cosine function (which normally returns a value from -1 to 1
Returns Scaled cosine value

Example: See sysSin above

PlayerTaskStartSetTime

TBD

CustomEvent

Triggers a custom event TBD

sysRaceIsActive

TBD

scripting/reference/system_functions.1424441433.txt.gz · Last modified: (external edit)