System variables
- System variables are hard-coded into HeroEngine. For the nodes which are handled in HSL, see System nodes
System variables are words that are hardcoded into the game engine, which can be used to refer to certain types of data. For example, if a scripter wants to refer to the name of the script that is currently running, they can do this with the system variable SYSTEM.EXEC.THISSCRIPT.
Some of these system variables are read-only, and should not be changed. Some may be modified within a script, and their values will last for the duration of that script's run: RUNLIMIT, CPULIMIT, and CALLSTACKLIMIT
| System Variable | Type | Description |
SYSTEM.CONFIG. |
string | the HeroScript package for accessing configuration values |
SYSTEM.EXEC.THISSCRIPT |
ScriptRef | the current executing script |
SYSTEM.EXEC.THISFUNCTION |
string | name of the current function |
SYSTEM.EXEC.CALLEDBYSCRIPT |
ScriptRef | previous script in the call stack |
SYSTEM.EXEC.CALLEDBYFUNCTION |
string | previous function in the call stack |
SYSTEM.EXEC.RUNLIMIT |
TimeInterval | specifies how much time is allowed to pass before the original function called for this event finishes. If the original function has not finished when this time has passed, execution stops with a Script Error. This limit is bad for use in client-side script since the rate of script actions performed depends on the hardware and concurrent activity. What value to use depends entirely on what the script is doing. Currently defaults to an hour. |
SYSTEM.EXEC.CPULIMIT |
TimeInterval | specifies how much processing time, in milliseconds, is allowed to occur before the original function called for this event finishes. If the original function has not finished when this time has passed, execution stops with a Script Error. Processing time includes most time that elapses while the computer is performing the script actions. It does not include time spent by the computer doing other activities such as scanning for viruses. This limit is bad for use in client-side script since the rate of script actions performed depends on the hardware. What value to use depends entirely on what the script is doing. Currently defaults to 00:00:03 (three seconds). |
SYSTEM.EXEC.CALLSTACKLIMIT |
Integer | A new stack is initiated each time a function is called. It has a current default value of 50. This acts primarily as a means to limit recursive calls from going running all the way to the RUN/CPULIMITs which could potentially use up a significant amount of memory before it hit those limits. |
SYSTEM.EXEC.CPUTIME |
TimeInterval | Returns currently used amount of corresponding CPULIMIT |
SYSTEM.EXEC.RUNTIME |
TimeInterval | Returns currently used amount of corresponding RUNLIMIT |
SYSTEM.EXEC.CALLSTACKSIZE |
Integer | Returns currently used amount of corresponding CALLSTACKLIMIT |
SYSTEM.HSL.LOCATION |
string | Shows the current script, function, and line number |
SYSTEM.INFO.PLAYERCHARACTER |
NodeRef | another way to obtain the noderef that is currently considered the player |
SYSTEM.INFO.WORLDANCHOR |
NodeRef | This is the absolute base client node. Node ID is 999999. This should not be used as a data storage node. Use SYSTEM.NODE.PROTOTYPENAME instead. |
SYSTEM.NODE.PROTOTYPENAME |
NodeRef | This is one of two possible ways to get a NodeRef to a system node. See System Nodes for more details. |
SYSTEM.REMOTE.FROMSCRIPT |
string | name of the script that made a remote call to start the current script execution (See RemoteCall2) |
SYSTEM.REMOTE.FROMFUNCTION |
string | name of the function that made a remote call to start the current script execution |
SYSTEM.REMOTE.FROMNODE |
ID | ID of the node (me node) that made a remote call to start the current script execution |
SYSTEM.REMOTE.FROMAREA |
ID | name of the script that made a remote call to start the current script execution |
SYSTEM.REMOTE.FROMINSTANCE |
ID | ID of the area instance number that made a remote call to start the current script execution |
SYSTEM.REMOTE.CLIENT |
ID | account node ID of the client that made a remote call to start the current script execution |
SYSTEM.REMOTE.ERROR |
string | A description for failed server to client calls |
SYSTEM.REMOTE.TOSCRIPT |
string | The script to be called (None if it is a class method call) |
SYSTEM.REMOTE.TOFUNCTION |
string | The function or method that was being sought |
SYSTEM.REMOTE.TONODE |
ID | Node ID for the method that was being sought |
SYSTEM.REMOTE.TOAREA |
ID | Area ID of the server being called |
SYSTEM.REMOTE.TOINSTANCE |
ID | Area instance number of the server that was being called |
SYSTEM.TIME.NOW |
DateTime | The synchronized DateTime between client and server. This system variable is updated at the beginning of script invocation, and is not updated again during the frame. This provides for fast access to a date time. The value of NOW is in Coordinated Universal Time (UTC) on the server, if you want local machine time you must adjust for the timezone. On the client, the user's OS localize time zone is used. |
SYSTEM.TIME.RAW |
integer | microsecond time value suitable for measuring time within a single process. This system variable is updated as it is used but is only able to give you resolution to approximately 15ms. Ultimately, we may switch this to use multimedia timers (or the linux equivalent when talking about servers running on linux) which would provide a resolution of approximatley 1 millisecond. |
SYSTEM.TIME.NULLTIME |
TimeInterval | Null time interval (ie 0:00:00.000) |
SYSTEM.TIME.MILLISECONDSTOTAL |
Integer | HeroEngine's equivalent to unix time, (ie milliseconds since an arbitrary date 1900 in our case). It uses the same synchronized clock as SYSTEM.TIME.NOW. |
SYSTEM.TIME.STARTDATE |
DateTime | This is the arbitrary oldest date that can be represented. January 1st, 12:00:00.001 1900 |
There is also a special global variable called NONE which can be used with Script and Node references. For more information, please see the section on Data Types.
Examples
n.mainScript = SYSTEM.EXEC.THISSCRIPT println(SYSTEM.EXEC.THISSCRIPT.name) println(SYSTEM.EXEC.CALLEDBYSCRIPT.name) println(SYSTEM.EXEC.CALLEDBYFUNCTION.name)
Time
Time is one of those very tricky subjects about which there are entire articles written, from HeroScript the maximum resolution supported is approximately 15 milliseconds(as seen in SYSTEM.TIME.RAW). Ultimately, we may choose to switch SYSTEM.TIME.RAW to utilize multimedia timers (or the linux equivalent when talking about servers running on linux) which would give us a resolution of approximately 1 millisecond. Tracking time at even greater resolution requires even greater trickery using QueryPerformanceCounter...which has a hardware dependent resolution, the profiling external functions use the QueryPerformanceCounter to achieve their resolution.
So....the greatest resolution you can get using SYSTEM.TIME.* is around the 15 millisecond resolution (using RAW), if it takes less than 15 milliseconds then it'll appear as 0.
SYSTEM.TIME.NOW is only updated at the beginning of script invocation to provide fast access to a date time.
