System variables

From HEWIKI
Jump to: navigation, search
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.

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox