Functions:
| Clear_Event_Queue() | |
|---|---|
| Explanation | |
| Empties the current script's event queue | |
| Return values | |
| 1 on success |
| Create_Debug_Context() | |
|---|---|
| Explanation | |
| TBD | |
| Return values | |
| TBD |
| Events_Waiting() | |
|---|---|
| Explanation | |
| Returns the number of events waiting in the event queue for this script. | |
| Return values | |
| Integer number of events waiting |
| GetProcess(pid) | |
|---|---|
| Parameters: | |
| Name | Type |
| pid | Integer process ID of a script |
| Explanation | |
| Gets a script process object for the given script's PID. | |
| Return values | |
| A Script object | |
| Errors | |
| "Process not found" | |
| "Invalid parameter type" | |
| Related | |
| Script | |
| Is_Critical() | |
|---|---|
| Explanation | |
| Returns true if the script is critical (by using set_critical()) | |
| Return values | |
| 1 if critical, else 0. |
| OpenURL( character, url ) | |
|---|---|
| Parameters: | |
| Name | Type |
| character | Player Character Ref |
| url | String |
| Explanation | |
| Sends an Open URL packet to the client, to open the url in their Default Browser. | |
| Return values | |
| 1 on success | |
| Errors | |
| "No client attached" | |
| Run_Script( script_name, param := 0 ) | |
|---|---|
| Parameters: | |
| Name | Type |
| script_name | String name and path of script to run |
| param | object to pass to the script. Only one param may be passed. (optional) |
| Explanation | |
| Starts a new NON-CRITICAL script. Runs until the script exits, returns the return value of the started script. | |
| Tip: write your script to expect a struct or array as its only parameter, so you may pass multiple pieces of data through the struct or array. | |
| Return values | |
| The return value of the started script, or 1 if no value was returned | |
| Errors | |
| "Unable to read script" | |
| "Script exited with an error condition" | |
| "Script does not exist" | |
| "Script descriptor error" | |
| Run_Script_To_Completion( script_name, param := 0 ) | |
|---|---|
| Parameters: | |
| Name | Type |
| script_name | String name and path of script to run |
| param | object to pass to the script. Only one param may be passed. (optional) |
| Explanation | |
| Starts a new CRITICAL script. Runs until the script exits, returns the return value of the started script. | |
| Tip: write your script to expect a struct or array as its only parameter, so you may pass multiple pieces of data through the struct or array. | |
| Every 1000 instructions, "Script X running.." is printed to the console | |
| Return values | |
| The return value of the started script, or 1 if no value was returned | |
| Errors | |
| "Unable to read script" | |
| "Script exited with an error condition" | |
| "Script does not exist" | |
| "Script descriptor error" | |
| Set_Critical( critical ) | |
|---|---|
| Parameters: | |
| Name | Type |
| critical | Boolean (0/1) |
| Explanation | |
| critical scripts run if they are not blocked, without interruption. | |
| An infinite loop in a critical script will hang the server | |
| Use this in blocks by setting 'critical' to 1 before the critical code and to 0 after it. | |
| Use this function sparingly, only in parts of code that must execute without interruption | |
| Return values | |
| 1 on success | |
| Errors | |
| "Invalid parameter type" | |
| Set_Debug( debug ) | |
|---|---|
| Parameters: | |
| Name | Type |
| debug | Boolean (0/1) |
| Explanation | |
| if debug=1, and the script was compiled with 'ecompile -i [script].src', each script source line will be printed as it is executed. | |
| if debug=0, disables this output. | |
| Return values | |
| 1 on success | |
| Errors | |
| "Invalid parameter type" | |
| Set_Event_Queue_Size(size) | |
|---|---|
| Parameters: | |
| Name | Type |
| size | Integer new size |
| Explanation | |
| Changes the maximum number of events the current script will keep in the queue (additional events will be discarded). | |
| If not called, the default size is 20 events. | |
| Return values | |
| Integer old queue size. | |
| Errors | |
| "Invalid parameter type" | |
| Set_Priority( priority ) | |
|---|---|
| Parameters: | |
| Name | Type |
| priority | Integer 1..255 |
| Explanation | |
| the priority of a script is how many instructions it executes before switching to another script. | |
| default script priority is 1. | |
| Return values | |
| Integer previous priority | |
| Errors | |
| "Invalid parameter type" | |
| Set_Script_Option( optnum, optval ) | |
|---|---|
| Parameters: | |
| Name | Type |
| optnum | Integer constant |
| optval | boolean (0/1) |
| Explanation | |
| Sets one or more options on or off for this script | |
| Constants for this function: | |
const SCRIPTOPT_NO_INTERRUPT := 1; // if 1, script runs until it sleeps const SCRIPTOPT_DEBUG := 2; // if 1, prints any debug info included const SCRIPTOPT_NO_RUNAWAY := 3; // if 1, doesn't warn about runaway conditions const SCRIPTOPT_CAN_ACCESS_OFFLINE_MOBILES := 4; | |
| set_script_option(SCRIPTOPT_NO_INTERRUPT,1) is the same as set_critical(1) | |
| set_script_option(SCRIPTOPT_DEBUG,1) is the same as set_debug(1) | |
| Return values | |
| previous value | |
| Errors | |
| "Unknown Script Option" | |
| "Invalid parameter type" | |
| Sleep( num_seconds ) | |
|---|---|
| Parameters: | |
| Name | Type |
| num_seconds | Integer |
| Explanation | |
| Puts the current script to sleep for num_seconds. No further instructions in this script will be processed in this script until the time expires. | |
| DO NOT USE IN A CRITICAL BLOCK! Your server will freeze for the duration! | |
| If this script is attached to a character (like a UseScript), calling detach() before the sleep will allow other scripts to run while this script sleeps. | |
| Return values | |
| 0 after sleep | |
| Sleepms( num_milliseconds ) | |
|---|---|
| Parameters: | |
| Name | Type |
| num_milliseconds | Integer |
| Explanation | |
| Puts the current script to sleep for num_milliseconds. No further instructions in this script will be processed in this script until the time expires. | |
| DO NOT USE IN A CRITICAL BLOCK! Your server will freeze for the duration! | |
| If this script is attached to a character (like a UseScript), calling detach() before the sleep will allow other scripts to run while this script sleeps. | |
| You're not likely to get any faster resolution than 10ms | |
| Return values | |
| 0 after sleep | |
| Start_Script( script_name, param := 0 ) | |
|---|---|
| Parameters: | |
| Name | Type |
| script_name | String name and path of script to run |
| param | object to pass to the script. Only one param may be passed. (optional) |
| Explanation | |
| Starts a new script running. | |
| Tip: write your script to expect a struct or array as its only parameter, so you may pass multiple pieces of data through the struct or array. | |
| Return values | |
| A Script object for the started script on success. | |
| Errors | |
| "Error in script name" | |
| "Script X does not exist." | |
| "Unable to start script" | |
| "Invalid parameter type" | |
| Related | |
| Script | |
| Syslog( text ) | |
|---|---|
| Parameters: | |
| Name | Type |
| text | String |
| Explanation | |
| write text to the console, and to the log file includes context (calling script name) | |
| Return values | |
| 1 on success | |
| System_RPM() | |
|---|---|
| Explanation | |
| returns the system RPM, which is the number of "game loop rotations" completed in the last minute. | |
| Return values | |
| Last System RPM integer |
| Unload_Scripts(scriptname := "") | |
|---|---|
| Parameters: | |
| Name | Type |
| scriptname | String filename of script without extension (optional) |
| Explanation | |
| unload scripts from the script cache (they will be reloaded from disk on demand) currently running scripts will continue as normal. | |
| Passing "" will unload all scripts. | |
| Return values | |
| Number of scripts unloaded | |
| Errors | |
| "Invalid parameter type" | |
| Related | |
| Script | |
| Wait_For_Event( num_seconds_timeout ) | |
|---|---|
| Parameters: | |
| Name | Type |
| num_seconds_timeout | Integer |
| Explanation | |
| The primary access to a script's event queue. If there is an event waiting, the function immediately returns with the event (could be a string, int, struct, etc). | |
| If no event is waiting, the script sleeps for num_seconds_timeout or until a new event arrives. If the timeout is reached, the function returns 0. | |
| if timeout is 0, returns immediately | |
| Return values | |
| object on event recv, 0 on timeout | |