Changes between Version 1 and Version 2 of ScriptGlue


Ignore:
Timestamp:
Feb 23, 2008, 9:31:12 PM (16 years ago)
Author:
Jan Wassenberg
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • ScriptGlue

    v1 v2  
    11This module defines the table of all functions callable from JS. it's required by the interpreter; we make use of the opportunity to document them all in one spot. we thus obviate having to dig through all the other headers. most of the functions are implemented here; as for the rest, we only link to their docs (duplication is bad).
    22Since these functions are called by JS code, we give script syntax, not that of the native implementation (if you are adding a function, simply copy the signature of another function).
    3 
    4 = Events =
    5 
    6 == addGlobalHandler ==
    7  * '''Overview:'''
    8   * Register a global handler for the specified DOM event.
    9  * '''Syntax:'''
    10   * success = addGlobalHandler(event_type_name, handler);
    11  * '''Parameters:'''
    12   * event type name [wstring], handler [fragment or function]
    13  * '''Returns:'''
    14   * whether it was actually newly registered [bool]
    15  * '''Notes:'''
    16   *
    17 
    18 == removeGlobalHandler ==
    19  * '''Overview:'''
    20   * Remove a previously registered global handler for the specified DOM event.
    21  * '''Syntax:'''
    22   * success = removeGlobalHandler(event_type_name, handler);
    23  * '''Parameters:'''
    24   * event type name [wstring], handler [fragment or function]
    25  * '''Returns:'''
    26   * whether it was successfully removed [bool]
    27  * '''Notes:'''
    28   *
    29 
    30 = Timer =
    31 
    32 == setTimeout ==
    33  * '''Overview:'''
    34   * Request a callback be executed after the specified delay.
    35  * '''Syntax:'''
    36   * setTimeout(delayed_func, 100);
    37  * '''Parameters:'''
    38   * callback [fragment or function], delay in milliseconds [int]
    39  * '''Returns:'''
    40   *
    41  * '''Notes:'''
    42   * 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)
    43 
    44 == setInterval ==
    45  * '''Overview:'''
    46   * Request a callback be executed periodically.
    47  * '''Syntax:'''
    48   * setInterval(atlasUpdateInfoWindow, 500);
    49  * '''Parameters:'''
    50   * callback [fragment or function], initial delay in ms [int], period in ms [int] OR
    51   * callback [fragment or function], period in ms [int] (initial delay = period)
    52  * '''Returns:'''
    53   *
    54  * '''Notes:'''
    55   * setTimeout's notes apply here as well.
    56 
    57 == cancelInterval ==
    58  * '''Overview:'''
    59   * Cause all periodic functions registered via setInterval to no longer be called.
    60 
    61  * '''Syntax:'''
    62   * cancelInterval();
    63  * '''Parameters:'''
    64   *
    65  * '''Returns:'''
    66   *
    67  * '''Notes:'''
    68   * Execution continues until the end of the triggered function or script fragment, but is not triggered again.
    69 
    70 = Debug =
    71 
    72 == crash ==
    73  * '''Overview:'''
    74   * Deliberately cause the game to crash.
    75  * '''Syntax:'''
    76   * crash()
    77  * '''Parameters:'''
    78   *
    79  * '''Returns:'''
    80   *
    81  * '''Notes:'''
    82   * Currently implemented via access violation (read of address 0)
    83   * Useful for testing the crashlog/stack trace code.
    84 
    85 == forceGC ==
    86  * '''Overview:'''
    87   * Force a JS GC (garbage collection) cycle to take place immediately.
    88  * '''Syntax:'''
    89   * forceGC()
    90  * '''Parameters:'''
    91   *
    92  * '''Returns:'''
    93   *
    94  * '''Notes:'''
    95   * Writes an indication of how long this took to the console.
    96 
    97 = Misc. Script System =
    98 
    99 == getGlobal ==
    100  * '''Overview:'''
    101   * Returns the global object.
    102  * '''Syntax:'''
    103   * global = getGlobal()
    104  * '''Parameters:'''
    105   *
    106  * '''Returns:'''
    107   * global object
    108  * '''Notes:'''
    109   * Useful for accessing an object from another scope.
    110 
    111 = Misc. Engine Interface =
    112 
    113 == writeLog ==
    114  * '''Overview:'''
    115   * Write values to the log file.
    116  * '''Syntax:'''
    117   * writeLog("string", 1234);
    118  * '''Parameters:'''
    119   * any number of any type.
    120  * '''Returns:'''
    121   *
    122  * '''Notes:'''
    123   * Each argument is converted to a string and then written to the log.
    124   * Output is in NORMAL style (see LOG).
    125 
    126 == setCursor ==
    127  * '''Overview:'''
    128   * Change the mouse cursor.
    129  * '''Syntax:'''
    130   * setCursor("action-attack")
    131  * '''Parameters:'''
    132   * cursor name [string] (i.e. basename of definition file and texture)
    133  * '''Returns:'''
    134   *
    135  * '''Notes:'''
    136   * Cursors are stored in "art\textures\cursors"
    137 
    138 == getFPS ==
    139  * '''Overview:'''
    140   * Return the global frames-per-second value.
    141  * '''Syntax:'''
    142   * fps = getFPS()
    143  * '''Parameters:'''
    144   *
    145  * '''Returns:'''
    146   * FPS [int]
    147  * '''Notes:'''
    148   * This value is recalculated once a frame. We take special care to filter it, so it is both accurate and free of jitter.
    149 
    150 == exit ==
    151  * '''Overview:'''
    152   * Cause the game to exit gracefully.
    153  * '''Syntax:'''
    154   * exit();
    155  * '''Parameters:'''
    156   *
    157  * '''Returns:'''
    158   *
    159  * '''Notes:'''
    160   * Exit happens after the current main loop iteration ends (since this only sets a flag telling it to end)
    161 
    162 == vmem ==
    163  * '''Overview:'''
    164   * Write an indication of total/available video RAM to console.
    165  * '''Syntax:'''
    166   * vmem()
    167  * '''Parameters:'''
    168   *
    169  * '''Returns:'''
    170   *
    171  * '''Notes:'''
    172   * Not supported on all platforms.
    173   * Only a rough approximation; do not base low-level decisions ("should I allocate one more texture?") on this.
    174 
    175 == _rewriteMaps ==
    176  * '''Overview:'''
    177   * Trigger a rewrite of all maps.
    178  * '''Syntax:'''
    179   * _rewriteMaps();
    180  * '''Parameters:'''
    181   *
    182  * '''Returns:'''
    183   *
    184  * '''Notes:'''
    185   * Usefulness is unclear. If you need it, consider renaming this and updating the docs.
    186 
    187 == _lodbias ==
    188  * '''Overview:'''
    189   * Change the LOD bias.
    190  * '''Syntax:'''
    191   * _lodbias(bias)
    192  * '''Parameters:'''
    193   * LOD bias [float]
    194  * '''Returns:'''
    195   *
    196  * '''Notes:'''
    197   * value is as required by GL_TEXTURE_LOD_BIAS.
    198   * useful for adjusting image "sharpness" (since it affects which mipmap level is chosen)
    199 
    200 = Miscellany =
    201 
    202 == v3dist ==
    203  * '''Overview:'''
    204   * Return distance between 2 points.
    205  * '''Syntax:'''
    206   * dist = v3dist(v1,v2);
    207  * '''Parameters:'''
    208   * 2 position vectors [CVector3D]
    209  * '''Returns:'''
    210   * Euclidean distance [float]
    211  * '''Notes:'''
    212   *
    213 
    214 == buildTime ==
    215  * '''Overview:'''
    216   * Return the date/time at which the current executable was compiled.
    217  * '''Syntax:'''
    218   * date = buildTime(0); // see below
    219  * '''Parameters:'''
    220   * none -> "$date $time"
    221   * 0    -> "$date"
    222   * 1    -> "$time"
    223  * '''Returns:'''
    224   * date and/or time [string]
    225  * '''Notes:'''
    226   * 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.
    227   * To be exact, the date/time returned is when scriptglue.cpp was last compiled; since the auto-build does full rebuilds, that is moot.