The Universal World Owner's Manual

User Tools

Site Tools

Trace: • system_functions
scripting:reference:system_functions

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
scripting:reference:system_functions [2020/01/29 04:33] – mitscripting: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) (Note also the list of [[Scripting:Reference:Special System Control Functions|special system control functions]] which includes special cases like the 'Sleep' function etc)
  
 +[[Scripting:Reference:system_functions:TextFunctions|Text Functions]] \\
 [[Scripting:Reference:system_functions:PlayerStatusFunctions|Player Information]] \\ [[Scripting:Reference:system_functions:PlayerStatusFunctions|Player Information]] \\
 [[Scripting:Reference:system_functions:PlayerInventoryAndWealthFunctions|Inventory and Wealth manipulation]] \\ [[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:PlayerBuildingOwnershipFunctions|Building Ownership]] \\
-[[Scripting:Reference:system_functions:ConstructionFunctions]] \\ +[[Scripting:Reference:system_functions:TownFunctions|Town information and control]] \\ 
-[[Scripting:Reference:system_functions:SubgameFunctions]] \\+[[Scripting:Reference:system_functions:MathsFunctions|Maths Functions]] \\ 
 +[[Scripting:Reference:system_functions:EntityFunctions|Entity Functions]] \\ 
 +[[Scripting:Reference:system_functions:MiscFunctions|Misc. other functions]] \\
  
 +For a full(ish) alphabetical list of script functions : [[Scripting:Reference:system_functions:FullFunctionList|Alphabetical Function List]]
  
-===== Building Functions ===== +[[Scripting:Reference:system_functions:TextFunctions|Text Functions]]\\ For providing names of items, players, skills etc; converting names to IDs and vice versa  \\ 
- +[[Scripting:Reference:system_functions:PlayerStatusFunctions|Player Information]]\\ Get information about the player ; what skills, inventory, health they have etc \\ 
-==== sysAmountInStocks ==== +[[Scripting:Reference:system_functions:PlayerInventoryAndWealthFunctions|Inventory and Wealth manipulation]] \\ 
-^ Format | sysAmountInStocks( [Item_Name or Num] )| +Add items and wealth to the player \\ 
-^ Description | Returns the amount of the item currently in the building's stocks | +[[Scripting:Reference:system_functions:BuildingInformationFunctions|Building Information]]: Provides information about a building and its contents (and functions to change the building UI) \\ 
-^ Parameters | Item Name or number | +[[Scripting:Reference:system_functions:WorldMapFunctions|World map functions]]: Get map coordinates for items in the world, convert map to world coordinates and vice versa \\ 
-^ Example | ''**$amountInBuilding = sysAmountInStocks("Wood")**'' | +[[Scripting:Reference:system_functions:ConstructionFunctions]]\\ 
- +For construction of buildings and other permanent or transient items on the world \\ 
-==== sysGetBuyPrice ==== +[[Scripting:Reference:system_functions:SubgameFunctions|Scripted Subgames]]\\ 
-^ Format | sysGetBuyPrice [Item] ) | +System for creating and controlling subgames which groups of players can participate in \\ 
-^ Description | Returns the 'Buy Price' set for this item in the currently accessed building | +[[Scripting:Reference:system_functions:PlayerBuildingOwnershipFunctions|Building Ownership]]\\ 
-^ Parameters | Item name or number  | +Querying and controlling the ownership status of buildings \\ 
-^ Returns | 'Buy Price' of the item in denari | +[[Scripting:Reference:system_functions:TownFunctions|Town information and control]]\\ 
-^ Notes | Related commands: *setbuyprice [BuildingID] [Item] [Price] | +Info about towns and functions to modify the status of town buildings \\ 
-//Example//:<note> +[[Scripting:Reference:system_functions:MathsFunctions|Maths Functions]]\\ 
-<code>Event( "AccessBuilding", "2" ) +Maths functions such as rand, sin, cos etc \\ 
-{ +[[Scripting:Reference:system_functions:EntityFunctions|Entity Functions]]\\ 
-    $buyPrice = sysGetBuyPrice( "Flour" ) +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' 
-    $buyPriceText = sysGetPriceText( $buyPrice ) +[[Scripting:Reference:system_functions:MiscFunctions|Misc. other functions]]\\ 
- +General other uncategorised bits
-    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 \\ 
-\\ 
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