Differences

This shows you the differences between two versions of the page.

--- scripting:reference:system_functions [2020/01/28 17:50] – external edit 127.0.0.1
+++ scripting:reference:system_functions [2020/02/17 19:10] (current) – mit
@@ Line 5: / Line 5: @@
 (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 =====
+[[Scripting:Reference:system_functions:TextFunctions|Text Functions]] \\
+[[Scripting:Reference:system_functions:PlayerStatusFunctions|Player Information]] \\
+[[Scripting:Reference:system_functions:PlayerInventoryAndWealthFunctions|Inventory and Wealth manipulation]] \\
+[[Scripting:Reference:system_functions:BuildingInformationFunctions|Building Information]] \\
+[[Scripting:Reference:system_functions:WorldMapFunctions|World map functions]] \\
+[[Scripting:Reference:system_functions:ConstructionFunctions]] \\
+[[Scripting:Reference:system_functions:SubgameFunctions|Scripted Subgames]] \\
+[[Scripting:Reference:system_functions:PlayerBuildingOwnershipFunctions|Building Ownership]] \\
+[[Scripting:Reference:system_functions:TownFunctions|Town information and control]] \\
+[[Scripting:Reference:system_functions:MathsFunctions|Maths Functions]] \\
+[[Scripting:Reference:system_functions:EntityFunctions|Entity Functions]] \\
+[[Scripting:Reference:system_functions:MiscFunctions|Misc. other functions]] \\
-==== sysAddToInventory ====
+For a full(ish) alphabetical list of script functions : [[Scripting:Reference:system_functions:FullFunctionList|Alphabetical Function List]]
-^ 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//: <note>
-<code>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
-    }
-}
-</code></note>
-==== 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//: <note>
-<code>Event( "Custom", "ListInventory" )
-{
-    $loop = 0
-    while( $loop < 64 )
-    {
-       $itemNum = sysGetInventoryItemIndex( $loop )
-       if ( $itemNum != 0 )
-       {
-          *msg %PLAYER% Item $loop : $itemNum
-       }
-    }
-}
-</code>
-</note>
-==== sysGetNearestPlayer ====
+[[Scripting:Reference:system_functions:TextFunctions|Text Functions]]\\ For providing names of items, players, skills etc; converting names to IDs and vice versa  \\
-^ Format | sysGetNearestPlayer( [WorldX], [WorldY] )|
+[[Scripting:Reference:system_functions:PlayerStatusFunctions|Player Information]]\\ Get information about the player ; what skills, inventory, health they have etc \\
-^ Description | Returns the ID of the player closest to the specified world coordinate |
+[[Scripting:Reference:system_functions:PlayerInventoryAndWealthFunctions|Inventory and Wealth manipulation]] \\
-^ Parameters | World Coordinate X,Y |
+Add items and wealth to the player \\
-^ Returns | Player ID |
+[[Scripting:Reference:system_functions:BuildingInformationFunctions|Building Information]]: Provides information about a building and its contents (and functions to change the building UI) \\
-//Example//: <note>
+[[Scripting:Reference:system_functions:WorldMapFunctions|World map functions]]: Get map coordinates for items in the world, convert map to world coordinates and vice versa \\
-<code>
+[[Scripting:Reference:system_functions:ConstructionFunctions]]\\
-$kSpecialBuildingRecordNum = 10
+For construction of buildings and other permanent or transient items on the world \\
+[[Scripting:Reference:system_functions:SubgameFunctions|Scripted Subgames]]\\
+System for creating and controlling subgames which groups of players can participate in \\
+[[Scripting:Reference:system_functions:PlayerBuildingOwnershipFunctions|Building Ownership]]\\
+Querying and controlling the ownership status of buildings \\
+[[Scripting:Reference:system_functions:TownFunctions|Town information and control]]\\
+Info about towns and functions to modify the status of town buildings \\
+[[Scripting:Reference:system_functions:MathsFunctions|Maths Functions]]\\
+Maths functions such as rand, sin, cos etc \\
+[[Scripting:Reference:system_functions:EntityFunctions|Entity Functions]]\\
+System for creating 'entities' in the world - these are models/objects that you can control from script, including the ability to set off standard behaviours such as 'attack the player'
+[[Scripting:Reference:system_functions:MiscFunctions|Misc. other functions]]\\
+General other uncategorised bits
-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
-}
-</code>
-</note>
-==== sysGetPlayerID ====
-^ Format | sysGetPlayerID( [Player Name] )|
-^ Description | Returns the ID for a specified player name |
-^ Parameters | Player Name |
-^ Returns | Player ID |
-//Example//: <note>
-<code>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
-    }
-}
-</code>
-</note>
-==== 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//: <note>
-<code>Event( "PreAccessBuilding", "10" )
-{
-    $hasKeys = sysPlayerInventory( "Keys" )
-    if ( $hasKeys == 0 )
-    {
-       *msg %PLAYER% You cannot access this building without keys
-       CancelTransaction()
-    }
-}
-</code>
-</note>
-==== 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//: <note>
-<code>Event( "Custom", "CountBuildings" )
-{
-    $numOwned = sysPlayerGetNumBuildingsOfType( $gPlayerID, 10 )
-    *msg %PLAYER% You currently own $numOwned type 10 buildings
-}
-</code>
-</note>
-==== 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//:<note>
-<code>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
-    }
-}
-</code>
-</note>
-==== 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//:<note>
-<code>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
-    }
-}
-</code>
-</note>
-===== 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//:<note>
-<code>Event( "AccessBuilding", "2" )
-{
-    $buyPrice = sysGetBuyPrice( "Flour" )
-    $buyPriceText = sysGetPriceText( $buyPrice )
-    osdcreate( OSDBUILDING, "BakeryOSD", "Bakery" )
-    osdaddat( 200, 100, 200, 40, "Sell|Flour", "Buying flour ($buyPriceText)" )
-    osdactivate()
-}
-</code>
-</note>
-==== 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//:
-<note>
-<code>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()
-}
-</code>
-</note>
-==== 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//:<note>
-<code>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()
-}
-</code>
-</note>
-==== sysGetBuildingName ====
-^ Format | sysGetBuildingName( [BuildingID] ) |
-^ Description | Returns the building name for a particular ID |
-^ Parameters | Building ID number  |
-^ Returns | The building name |
-//Example//:<note>
-<code>Event( "UseItem", "Map" )
-{
-    $nearestTownID = sysGetNearestTown( $gPlayerWorldX, $gPlayerWorldY )
-    $nearestTownName = sysGetBuildingName( $nearestTownID )
-    *msg %PLAYER% The nearest town is $nearestTownName
-}
-</code>
-</note>
-==== 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//:<note>
-<code>Event( "PlaceAnyBuilding", "" )
-{
-    $buildingType = $gParam[1]
-    $isValid = sysIsBuildingPositionValid( $buildingType )
-    if ( $isValid == 1 )
-    {
-	$buildingName = sysGetTextEntry()
-	$constrAmount = -1
-	$didAdd = sysAddBuildingWorld( $buildingType,$gPlayerID,$gPlayerWorldX,$gPlayerWorldY,$buildingName,$constrAmount )
-    }
-}
-</code>
-</note>
-==== 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//: <note>
-<code>Event( "PlaceAnyBuilding", "" )
-{
-    $nBuildingType = $gParam[1]
-    $valid = sysIsBuildingPositionValid( $nBuildingType )
-    if ( $valid = 1 )
-    {
-	$buildingName = sysGetTextEntry()
-	$didAdd = sysAddBuilding( nBuildingType,$gPlayerID,$gPlayerX,$gPlayerY,$buildingName )
-    }
-}
-</code>
-</note>
-==== 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//: <note>
-<code>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 )
-	}
-    }
-}
-</code>
-</note>
-===== 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//: <note>
-<code>Event( "UseItem", "TileTeleport" )
-{
-    $tileCenterX = sysGetTileCenter( $gPlayerWorldX )
-    $tileCenterY = sysGetTileCenter( $gPlayerWorldY )
-    *setposworld %PLAYER% $tileCenterX $tileCenterY
-}
-</code>
-</note>
-==== 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//: <note>
-<code>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 )
-	}
-    }
-}
-</code>
-</note>
-==== sysGetNearestForest ====
-===== Text Functions =====
-==== sysGetPlayerName ====
-^ Format | sysGetPlayerName( [PlayerID] )|
-^ Description | Returns the name of the specified player|
-^ Parameters | Player ID |
-^ Returns | Player Name |
-//Example//: <note>
-<code>Event( "UseItem", "Potion" )
-{
-    $targetName = sysGetPlayerName( $gTargetID )
-    *msg %PLAYER% You used the potion while targeting $targetName
-}
-</code>
-</note>
-==== 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//: <note>
-<code>Event( "UseItem", "Potion" )
-{
-    $itemNum = sysGetItemNum( "Potion" )
-    *msg %PLAYER% The item number is $itemNum
-}
-</code>
-</note>
-==== 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//: <note>
-<code>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
-    }
-}
-</code>
-</note>
-==== 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//: <note>
-<code>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
-    }
-}
-</code>
-</note>
-==== 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//: <note>
-<code>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
-    }
-}
-</code>
-</note>
-===== 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//: <note>
-<code>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
-    }
-}
-</code>
-</note>
-==== 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//: <note>
-<code>Event( "AccessBuilding", "1" )
-{
-    $dist = sysGetDist( $gPlayerWorldX, $gPlayerWorldY, $gBuildingWorldX, $gBuildingWorldY )
-    *msg %PLAYER% You accessed the building from $dist cm away
-}
-</code>
-</note>
-===== 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//: <note>
-<code>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!
-    }
-}
-</code>
-</note>
-==== sysRaceIsActive ====
-TBD \\
-\\