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)

Player Information
Inventory and Wealth manipulation
Building Ownership
ConstructionFunctions
SubgameFunctions

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.1580294000.txt.gz · Last modified: 2020/01/29 04:33 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