====== 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 [[Scripting:Reference:Special System Control Functions|special system control functions]] which includes special cases like the 'Sleep' function etc) ===== 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
    }
}

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


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

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

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
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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