User Tools

Site Tools


scripting:reference:system_functions

This is an old revision of the document!


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.

(Note also the list of special system control functions which includes special cases like the 'Sleep' function etc)

PlayerStatusFunctions BuildingFunctions ConstructionFunctions SubgameFunctions

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 up to 64 inventory slots.

Example:

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

sysGetNearestPlayer

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:

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

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

Format sysIsPlayerIDOnline( [Player ID] )
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
Example $isOnline = sysIsPlayerIDOnline(32)

sysIsInSpawnZone

Format sysIsInSpawnZone( [SpawnZone Type/ID] )
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
Example $isInDefaultSpawnZone = sysIsInSpawnZone(0)

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 = sysPlayerSkillLevel(“Farmer”)
Returns the current player's skill level for the skill named (0 means the player does not yet have this skill)

sysPlayerIsLearningSkill

Example : $isLearning = sysPlayerIsLearningSkill(“Farmer”)
Returns 1 if the player is currently learning the specified skill, 0 if not.

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

Format sysAmountInStocks( [Item_Name or Num] )
Description Returns the amount of the item currently in the building's stocks
Parameters Item Name or number
Example $amountInBuilding = sysAmountInStocks(“Wood”)

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

Format sysGetSellPrice( [Item_Name or Num] )
Description Returns the price that the item is currently set for sale at (Or 0 if it is not currently for sale)
Parameters Item Name or number

Example:

Event( "AccessBuilding", "12" )
{
    osdcreate( OSDBUILDING, "Building", "Example" )
    $woodSellPrice = sysGetSellPrice( "Wood" )  
    if ( $woodSellPrice == 0 )
    {
        osdaddat( TEXT, 100, 100, 400, 0, "", "Not currently selling wood" )   
    }
    else
    { 
        $woodSellPriceText = sysGetPriceText( $woodSellPrice )
        osdaddat( TEXT, 100, 100, 400, 0, "", "Currently selling wood at $woodSellPriceText" )
    }
    osdactivate()
}

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", "13" )
{
    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" )
    }
    osdactivate()
}

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

Format sysAddBuilding ( [Building Type], [Owner ID], [MapX], [MapY], [ [Building_Name], [Construction Amount 1], [Construction Amount 2] ] ) )
Description Used to add a new building to your world
Parameters Building Type number
Owner player ID
Map Coordinate X
Map Coordinate Y
(Optional) Building Name
(Optional) Construction Amount 1
(Optional) Construction Amount 2
Returns 1 if the building was added to the world, 0 if not

Example:

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

    $valid = sysIsBuildingPositionValid( $nBuildingType )
    if ( $valid = 1 )
    {
	$buildingName = sysGetTextEntry()
	$didAdd = sysAddBuilding( nBuildingType,$gPlayerID,$gPlayerX,$gPlayerY,$buildingName )
    }
}

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

Format sysGetRealTimeTextForDays ( [Number of game days] )
Description Returns a text description of the time that will pass for the specified number of game days
Parameters Number of game days
Returns Time text

Example:

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

Battle game Functions

BattleSetPreludeTime

BattleSetNumRounds

BattleSetRoundTime

BattleSetRoundScore

BattleSendChallenge

Maths Functions

sysRand

Format sysRand ( [MAX_NUM] )
Description Returns a random number between 1 and the value specified
Example $var = Rand(500)

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

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
}

Misc other functions

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

sysRaceIsActive

TBD

scripting/reference/system_functions.1580293812.txt.gz · Last modified: 2020/01/29 04:30 by mit

Except where otherwise noted, content on this wiki is licensed under the following license: Public Domain
Public Domain Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki