Universal World Owners Manual

User Tools

Site Tools

Trace: • hiscoretable
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 [2015/02/20 14:06] – mitscripting:reference:system_functions [2025/05/28 16:35] (current) – external edit 127.0.0.1
Line 3: Line 3:
 The scripting engine provides a set of 'System Functions', usually preceded by **sys**. Below is the complete list of system functions currently available. The scripting engine provides a set of 'System Functions', usually preceded by **sys**. Below is the complete list of system functions currently available.
  
-===== Special Scripting Language Functions ===== +(Note also the list of [[Scripting:Reference:Special System Control Functions|special system control functions]] which includes special cases like the 'Sleep' function etc)
- +
-==== Sleep ==== +
-^ Format : | Sleep( [time] ) | +
-^ Description : | Pauses the event for a period of time. Cannot currently be used in a function (only an event). | +
-^ Parameters: | [time] - Sleep time in 1/10ths of a second | +
-//Example//:<note> +
-<code>Event( "UseSkill", "Magic" ) +
-{ +
-    *effect %PLAYER% 1 +
-    Sleep(10) +
-    *effect %PLAYER% 1 +
-} +
-</code> +
-</note> +
- +
-==== sysSetTimer ==== +
-^ Format | sysSetTimer ( [interval (seconds)], [eventname], [eventparams] ) | +
-^ Description | After the specified period of time a 'Timer' event will be triggered. | +
-^ Parameters | **[interval]** - Number of seconds to pass before the timer event is triggered | +
-^ | **[eventname]** - Name of the timer event to be triggered | +
-^ | **[eventparams]** - Parameter values to be passed in to the timer event | +
-^ Returns | **[TimerID]** - ID number of the timer which can be used with ***killtimer [ID]** to cancel a timer | +
-^ Notes | The context in the subsequent Timer event will be the same as the event that activated the timer. | +
-//Example//: <note> +
-<code>Event( "UseItem", "Alarm Clock" ) +
-{ +
-    sysSetTimer( 10, "Alarm", "" ) +
-} +
- +
-Event( "Timer", "Alarm" ) +
-{ +
-    *msg %PLAYER% Your alarm clock started ringing 10 seconds later +
-} +
-</code> +
-</note> +
- +
-==== CancelTransaction ==== +
-^ Format | CancelTransaction () | +
-^ Description | This is a special script function used to notify the game that the normal processing for an event should be cancelled. In some types of event (a 'Custom' one for instance) this does nothing, in others it can be used to easily add scripted logic to the game - e.g. Calling CancelTransaction() in a "PreAccessBuilding" event can be used to control whether a player can access a particular building type | +
-//Example//:<note> +
-<code>Event( "PreAccessBuilding", "10" ) +
-{ +
-    $hasKeys = sysPlayerInventory( "Keys" ) +
-    if ( $hasKeys == 0 ) +
-    {   +
-        *msg %PLAYER% You cannot access this building without keys +
-        CancelTransaction() +
-    } +
-} +
-</code> +
-</note>+
  
 ===== Player-status Functions ===== ===== Player-status Functions =====
Line 84: Line 33:
 ^ Parameters | **[index]** - Inventory slot number | ^ Parameters | **[index]** - Inventory slot number |
 ^ Returns | **[ItemNum]** - The item number in the specified inventory slot (or 0 if the slot is empty) | ^ Returns | **[ItemNum]** - The item number in the specified inventory slot (or 0 if the slot is empty) |
-^ Notes | Players currently have 16 inventory slots. |+^ Notes | Players currently have up to 64 inventory slots. |
 //Example//: <note> //Example//: <note>
 <code>Event( "Custom", "ListInventory" ) <code>Event( "Custom", "ListInventory" )
 { {
     $loop = 0     $loop = 0
-    while( $loop < 16 )+    while( $loop < 64 )
     {     {
        $itemNum = sysGetInventoryItemIndex( $loop )        $itemNum = sysGetInventoryItemIndex( $loop )
Line 97: Line 46:
        }        }
     }     }
 +}
 +</code>
 +</note>
 +
 +==== 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//: <note>
 +<code>
 +$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
 } }
 </code> </code>
Line 124: Line 96:
  
 ==== sysIsPlayerIDOnline ==== ==== sysIsPlayerIDOnline ====
-Example : ''**$var = sysIsPlayerIDOnline(32))**''  \\ +^ Format | sysIsPlayerIDOnline( [Player ID] )| 
-Returns 1 if the specified player (BillingID) is currently online, 0 if not \\+^ 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 ==== ==== sysIsInSpawnZone ====
-Example : ''**$var = sysIsInSpawnZone(2))**'' \\ +^ Format | sysIsInSpawnZone( [SpawnZone Type/ID] )| 
-Returns 1 if the current player is in the specified spawn zone, 0 if not \\+^ 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 ==== ==== sysIsInTown ====
Line 158: Line 136:
  
 ==== sysPlayerSkillLevel ==== ==== sysPlayerSkillLevel ====
-Example : ''**$var = PlayerSkillLevel("Farmer")**'' \\ +Example : ''**$var = sysPlayerSkillLevel("Farmer")**'' \\ 
-Returns the current player's skill level for the skill named \\+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 ===== ===== Player Building Ownership Functions =====
Line 232: Line 214:
  
 ==== sysAmountInStocks ==== ==== sysAmountInStocks ====
-Example : ''**$var = sysAmountInStocks("Bongos" ))**''  \\ +^ Format | sysAmountInStocks( [Item_Name or Num] )| 
-Returns the amount of the item named currently in the player's inventory.\\+^ Description | Returns the amount of the item currently in the building's stocks | 
 +^ Parameters | Item Name or number | 
 +^ Example | ''**$amountInBuilding = sysAmountInStocks("Wood")**'' |
  
 ==== sysGetBuyPrice ==== ==== sysGetBuyPrice ====
Line 254: Line 238:
 </note> </note>
  
-==== sysGetSellPrice==== +==== sysGetSellPrice ==== 
-Example : ''**$var = sysAmountInStocks("Bongos" ))**''  \\ +^ Format | sysGetSellPrice( [Item_Name or Num] )| 
-TBD\\ +^ 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 ==== ==== sysGetEmployeeID ====
 ^ Format | sysGetEmployeeID( [Index] ) | ^ Format | sysGetEmployeeID( [Index] ) |
Line 264: Line 267:
 ^ Returns | PlayerID of the employee or 0 if none is set for this index | ^ Returns | PlayerID of the employee or 0 if none is set for this index |
 //Example//:<note> //Example//:<note>
-<code>Event( "AccessBuilding", "12" )+<code>Event( "AccessBuilding", "13" )
 { {
     osdcreate( OSDBUILDING, "Building", "Example" )     osdcreate( OSDBUILDING, "Building", "Example" )
Line 277: Line 280:
         osdaddat( TEXT, 100, 100, 400, 0, "", "There is no-one currently employed at this building" )         osdaddat( TEXT, 100, 100, 400, 0, "", "There is no-one currently employed at this building" )
     }     }
-    osdcreate()+    osdactivate()
 } }
 </code> </code>
Line 325: Line 328:
  
 ==== sysAddBuilding ==== ==== sysAddBuilding ====
-TBD\\+^ 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 ==== ==== sysAddBuildingWorld ====
 TBD\\ TBD\\
 +==== sysGetBuildingTypeName ====
 +TBD //
 +//
 +==== sysGetConstructionMaterialsAmount ====
 +TBD //
 +//
 ==== sysAddLocalBackgroundModel ==== ==== sysAddLocalBackgroundModel ====
 TBD\\ TBD\\
Line 522: Line 555:
 </note> </note>
  
 +==== sysGetTimeText ====
 +TBD //
 +//
  
-===== Context Functions ===== +==== sysGetRealTimeTextForDays ==== 
- +^ Format | sysGetRealTimeTextForDays ( [Number of game days] )| 
-==== SetContext ==== +^ Description | Returns a text description of the time that will pass for the specified number of game days | 
-^ Format | SetContext( [Player ID] )| +^ Parameters | Number of game days | 
-^ Description | Changes the script context to the specified playerID. When the context is changed, all operations and functions will be applied to the new player - e.g. gPlayerVar[..] accesses the new player ID's variables, sysPlayerInventory checks the new player's inventory. | +^ Returns | Time text |
-^ Parameters | Player ID | +
-^ Returns | None | +
-^ Notes | Use **RestoreContext** to set the context back to the original player |+
 //Example//: <note> //Example//: <note>
-<code>Event( "UseItem", "Potion" )+<code>Event( "UseItem", "Magic Potion" )
 { {
-    SetContext( $gTargetID ) +    $daysSinceLastUsed = $gGameDay - $gPlayerKey[LastUsedPotionDay] 
-    $targetHasShield = sysPlayerInventory( "Shield" ) +    if ( $daysSinceLastUsed < 10 )
-    RestoreContext() +
-     +
-    if ( $targetHasShield > 0 )+
     {     {
-        *msg %PLAYER% You cannot use the potion on %TARGET% as they have a shield +        $daysUntilCanUse = 10 - $daysSinceLastUsed 
-        CancelTransaction()+        $timeText = sysGetRealTimeTextForDays( $daysUntilCanUse ) 
 +        *say You must wait $timeText until you can use the Magic Potion again 
 +    } 
 +    else 
 +    { 
 +        *effect %PLAYER% 10 
 +        $gPlayerKey[LastUsedPotionDay] = $gGameDay
     }     }
 } }
 </code> </code>
 </note> </note>
- 
-==== RestoreContext ==== 
- 
-==== SetBuildingContext ==== 
- 
 ===== Battle game Functions ===== ===== Battle game Functions =====
  
Line 564: Line 595:
  
  
-===== Misc other functions =====+===== Maths Functions =====
  
 ==== sysRand ==== ==== sysRand ====
-Example : ''**$var = Rand(500)**'' \\ +^ Format | sysRand ( [MAX_NUM] )| 
- Returns a random number between 1 and the value specified \\ +^ Description | Returns a random number between 1 and the value specified | 
- +^ Example | ''**$var = Rand(500)**'' |
-==== 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> +
-==== 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>+
  
 ==== sysSin ==== ==== sysSin ====
Line 648: Line 634:
 \\ \\
  
-==== PlayerTaskStartSetTime ==== +==== sysGetDist ==== 
-TBD \\ +^ 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>
  
-==== CustomEvent ==== +==== sysRaceIsActive ====
-Triggers a custom event+
 TBD \\ TBD \\
 \\ \\
scripting/reference/system_functions.1424441186.txt.gz · Last modified: (external edit)