Events

addGlobalHandler

• Overview:
  • Register a global handler for the specified DOM event.
• Syntax:
  • success = addGlobalHandler(event_type_name, handler);
• Parameters:
  • event type name [wstring], handler [fragment or function]
• Returns:
  • whether it was actually newly registered [bool]
• Notes:

removeGlobalHandler

• Overview:
  • Remove a previously registered global handler for the specified DOM event.
• Syntax:
  • success = removeGlobalHandler(event_type_name, handler);
• Parameters:
  • event type name [wstring], handler [fragment or function]
• Returns:
  • whether it was successfully removed [bool]
• Notes:

Timer

setTimeout

• Overview:
  • Request a callback be executed after the specified delay.
• Syntax:
  • setTimeout(delayed_func, 100);
• Parameters:
  • callback [fragment or function], delay in milliseconds [int]
• Returns:
• Notes:
  • Scripts and functions registered this way are called on the first simulation frame after the specified period has elapsed. If this causes multiple segments of code to be executed in the same frame, relative timing is maintained. Delays of 0 milliseconds cause code to be executed on the following simulation frame. If more than one script or function is scheduled to execute in the same millisecond, the order of execution is undefined. Code is scheduled in simulation time, and is therefore suspended while the game is paused or frozen. Granularity of timing is also limited to 1/(Simulation frame rate); currently 100ms. The called function or script executes in the same scope as the code that called setTimeout (amongst other things, the 'this' reference is usually maintained)

setInterval

• Overview:
  • Request a callback be executed periodically.
• Syntax:
  • setInterval(atlasUpdateInfoWindow, 500);
• Parameters:
  • callback [fragment or function], initial delay in ms [int], period in ms [int] OR
  • callback [fragment or function], period in ms [int] (initial delay = period)
• Returns:
• Notes:
  • setTimeout's notes apply here as well.

cancelInterval

• Overview:
  • Cause all periodic functions registered via setInterval to no longer be called.

• Syntax:
  • cancelInterval();
• Parameters:
• Returns:
• Notes:
  • Execution continues until the end of the triggered function or script fragment, but is not triggered again.

Debug

crash

• Overview:
  • Deliberately cause the game to crash.
• Syntax:
  • crash()
• Parameters:
• Returns:
• Notes:
  • Currently implemented via access violation (read of address 0)
  • Useful for testing the crashlog/stack trace code.

forceGC

• Overview:
  • Force a JS GC (garbage collection) cycle to take place immediately.
• Syntax:
  • forceGC()
• Parameters:
• Returns:
• Notes:
  • Writes an indication of how long this took to the console.

Misc. Script System

getGlobal

• Overview:
  • Returns the global object.
• Syntax:
  • global = getGlobal()
• Parameters:
• Returns:
  • global object
• Notes:
  • Useful for accessing an object from another scope.

Misc. Engine Interface

writeLog

• Overview:
  • Write values to the log file.
• Syntax:
  • writeLog("string", 1234);
• Parameters:
  • any number of any type.
• Returns:
• Notes:
  • Each argument is converted to a string and then written to the log.
  • Output is in NORMAL style (see LOG).

setCursor

• Overview:
  • Change the mouse cursor.
• Syntax:
  • setCursor("action-attack")
• Parameters:
  • cursor name [string] (i.e. basename of definition file and texture)
• Returns:
• Notes:
  • Cursors are stored in "art\textures\cursors"

getFPS

• Overview:
  • Return the global frames-per-second value.
• Syntax:
  • fps = getFPS()
• Parameters:
• Returns:
  • FPS [int]
• Notes:
  • This value is recalculated once a frame. We take special care to filter it, so it is both accurate and free of jitter.

exit

• Overview:
  • Cause the game to exit gracefully.
• Syntax:
  • exit();
• Parameters:
• Returns:
• Notes:
  • Exit happens after the current main loop iteration ends (since this only sets a flag telling it to end)

vmem

• Overview:
  • Write an indication of total/available video RAM to console.
• Syntax:
  • vmem()
• Parameters:
• Returns:
• Notes:
  • Not supported on all platforms.
  • Only a rough approximation; do not base low-level decisions ("should I allocate one more texture?") on this.

_rewriteMaps

• Overview:
  • Trigger a rewrite of all maps.
• Syntax:
  • _rewriteMaps();
• Parameters:
• Returns:
• Notes:
  • Usefulness is unclear. If you need it, consider renaming this and updating the docs.

_lodbias

• Overview:
  • Change the LOD bias.
• Syntax:
  • _lodbias(bias)
• Parameters:
  • LOD bias [float]
• Returns:
• Notes:
  • value is as required by GL_TEXTURE_LOD_BIAS.
  • useful for adjusting image "sharpness" (since it affects which mipmap level is chosen)

Miscellany

v3dist

• Overview:
  • Return distance between 2 points.
• Syntax:
  • dist = v3dist(v1,v2);
• Parameters:
  • 2 position vectors [CVector3D]
• Returns:
  • Euclidean distance [float]
• Notes:

buildTime

• Overview:
  • Return the date/time at which the current executable was compiled.
• Syntax:
  • date = buildTime(0); see below
• Parameters:
  • none -> "$date $time"
  • 0 -> "$date"
  • 1 -> "$time"
• Returns:
  • date and/or time [string]
• Notes:
  • Displayed on main menu screen; tells non-programmers which auto-build they are running. Could also be determined via .EXE file properties, but that's a bit more trouble.
  • To be exact, the date/time returned is when scriptglue.cpp was last compiled; since the auto-build does full rebuilds, that is moot.

getLanguageID

• Overview:
  • Returns a string value of the language version currently being used by the localisation system.
• Syntax:
  • ReturnString = getLanguageID()
• Parameters:
  • None
• Returns:
  • Language name (eg "English").
• Notes: