mirror of
https://github.com/polserver/polserver
synced 2026-08-13 08:23:08 -04:00
aac4b7dd43
* profile cleanup, time measurement for script scheduler * missing file * profiling npc template search makes I think no longer sense * renamed variable * fixed namespace * typo * maybe now? * scheduler != tasks ... * use correct macro * convert to double * fixed runlist stats, correctly log delay * reset statistics each minute * log standard deviation instead of variance * mean instruction time * pol.cfg "DefaultPriority" (default 1) * changed the correct file and removed leftover files * reduced output * changed default prio to 10 and added docs * online docs * fixed warning * removed more leftovers
341 lines
20 KiB
XML
341 lines
20 KiB
XML
<?xml version='1.0' encoding="iso-8859-1"?>
|
|
<?xml-stylesheet type="text/xsl" href="escript.xslt" ?>
|
|
<!DOCTYPE ESCRIPT SYSTEM "escript.dtd">
|
|
<ESCRIPT>
|
|
<fileheader fname="OS.em">
|
|
<filedesc>POL System Environment Functions</filedesc>
|
|
<datemodified>09/02/2025</datemodified>
|
|
<constant>// set_script_option constants</constant>
|
|
<constant>const SCRIPTOPT_NO_INTERRUPT := 1; // if 1, script runs until it sleeps</constant>
|
|
<constant>const SCRIPTOPT_DEBUG := 2; // if 1, prints any debug info included</constant>
|
|
<constant>const SCRIPTOPT_NO_RUNAWAY := 3; // if 1, doesn't warn about runaway conditions</constant>
|
|
<constant>const SCRIPTOPT_CAN_ACCESS_OFFLINE_MOBILES := 4;</constant>
|
|
<constant>const SCRIPTOPT_AUXSVC_ASSUME_STRING := 5;</constant>
|
|
<constant>const SCRIPTOPT_SURVIVE_ATTACHED_DISCONNECT := 6; // if 1, do not kill script if attached character's client disconnects</constant>
|
|
<constant>const HTTPREQUEST_EXTENDED_RESPONSE := 0x0001; // return Dictionary with various response data instead of a String of response body</constant>
|
|
</fileheader>
|
|
|
|
<function name="GetProcess">
|
|
<prototype>GetProcess(pid := -1)</prototype>
|
|
<parameter name="pid" value="Integer process ID of a script (optional)" />
|
|
<explain>Gets a script process object for the given script's PID.</explain>
|
|
<explain>If no PID is supplied uses PID of the current script.</explain>
|
|
<return>A Script object</return>
|
|
<error>"Process not found"</error>
|
|
<error>"Invalid parameter type"</error>
|
|
<related>Script</related>
|
|
</function>
|
|
|
|
<function name="GetPid">
|
|
<prototype>GetPid()</prototype>
|
|
<explain>Returns the Process ID for this script.</explain>
|
|
<return>Integer Process ID</return>
|
|
</function>
|
|
|
|
<function name="Unload_Scripts">
|
|
<prototype>Unload_Scripts(scriptname := "")</prototype>
|
|
<parameter name="scriptname" value="String filename of script without extension (optional)" />
|
|
<explain>unload scripts from the script cache (they will be reloaded from disk on demand) currently running scripts will continue as normal.</explain>
|
|
<explain>Passing "" will unload all scripts.</explain>
|
|
<return>Number of scripts unloaded</return>
|
|
<error>"Invalid parameter type"</error>
|
|
<related>Script</related>
|
|
</function>
|
|
|
|
<function name="Set_Script_Option">
|
|
<prototype>Set_Script_Option( optnum, optval )</prototype>
|
|
<parameter name="optnum" value="Integer constant" />
|
|
<parameter name="optval" value="boolean (0/1)" />
|
|
<explain>Sets one or more options on or off for this script</explain>
|
|
<explain>Constants for this function:
|
|
<code>
|
|
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;</code></explain>
|
|
<explain>set_script_option(SCRIPTOPT_NO_INTERRUPT,1) is the same as set_critical(1)</explain>
|
|
<explain>set_script_option(SCRIPTOPT_DEBUG,1) is the same as set_debug(1)</explain>
|
|
<return>previous value</return>
|
|
<error>"Unknown Script Option"</error>
|
|
<error>"Invalid parameter type"</error>
|
|
</function>
|
|
|
|
<function name="Sleep">
|
|
<prototype>Sleep( num_seconds )</prototype>
|
|
<parameter name="num_seconds" value="Integer"/>
|
|
<explain>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.</explain>
|
|
<explain>DO NOT USE IN A CRITICAL BLOCK! Your server will freeze for the duration!</explain>
|
|
<explain>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.</explain>
|
|
<return>0 after sleep</return>
|
|
</function>
|
|
|
|
<function name="Sleepms">
|
|
<prototype>Sleepms( num_milliseconds )</prototype>
|
|
<parameter name="num_milliseconds" value="Integer"/>
|
|
<explain>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.</explain>
|
|
<explain>DO NOT USE IN A CRITICAL BLOCK! Your server will freeze for the duration!</explain>
|
|
<explain>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.</explain>
|
|
<explain>You're not likely to get any faster resolution than 10ms</explain>
|
|
<return>0 after sleep</return>
|
|
</function>
|
|
|
|
<function name="Wait_For_Event">
|
|
<prototype>Wait_For_Event( num_seconds_timeout )</prototype>
|
|
<parameter name="num_seconds_timeout" value="Integer/Double" />
|
|
<explain>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).</explain>
|
|
<explain>If no event is waiting, the script sleeps for num_seconds_timeout or until a new event arrives, with a resolution of 10ms (ie. a <code>num_seconds_timeout</code> of <code>0.01</code>). If the timeout is reached, the function returns 0.</explain>
|
|
<explain>if timeout is 0, returns immediately</explain>
|
|
<return>object on event recv, 0 on timeout</return>
|
|
</function>
|
|
|
|
<function name="Events_Waiting">
|
|
<prototype>Events_Waiting()</prototype>
|
|
<explain>Returns the number of events waiting in the event queue for this script.</explain>
|
|
<return>Integer number of events waiting</return>
|
|
</function>
|
|
|
|
<function name="Set_Priority">
|
|
<prototype>Set_Priority( priority )</prototype>
|
|
<parameter name="priority" value="Integer 1..255"/>
|
|
<explain>the priority of a script is how many instructions it executes before switching to another script.</explain>
|
|
<explain>default script priority is 10 if not changed in pol.cfg.</explain>
|
|
<return>Integer previous priority</return>
|
|
<error>"Invalid parameter type"</error>
|
|
</function>
|
|
|
|
<function name="Set_Critical">
|
|
<prototype>Set_Critical( critical )</prototype>
|
|
<parameter name="critical" value="Boolean (0/1)"/>
|
|
<explain>critical scripts run if they are not blocked, without interruption.</explain>
|
|
<explain>An infinite loop in a critical script will hang the server</explain>
|
|
<explain>Use this in blocks by setting 'critical' to 1 before the critical code and to 0 after it.</explain>
|
|
<explain>Use this function sparingly, only in parts of code that must execute without interruption</explain>
|
|
<return>1 on success</return>
|
|
<error>"Invalid parameter type"</error>
|
|
</function>
|
|
|
|
<function name="Set_Debug">
|
|
<prototype>Set_Debug( debug )</prototype>
|
|
<parameter name="debug" value="Boolean (0/1)" />
|
|
<explain>if debug=1, and the script was compiled with 'ecompile -i [script].src', each script source line will be printed as it is executed.</explain>
|
|
<explain>if debug=0, disables this output.</explain>
|
|
<return>1 on success</return>
|
|
<error>"Invalid parameter type"</error>
|
|
</function>
|
|
|
|
<function name="Start_Script">
|
|
<prototype>Start_Script( script_name, param := 0 )</prototype>
|
|
<parameter name="script_name" value="String name and path of script to run" />
|
|
<parameter name="param" value="object to pass to the script. Only one param may be passed. (optional)"/>
|
|
<explain>Starts a new script running.</explain>
|
|
<explain>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.</explain>
|
|
<return>A Script object for the started script on success.</return>
|
|
<error>"Error in script name"</error>
|
|
<error>"Script X does not exist."</error>
|
|
<error>"Unable to start script"</error>
|
|
<error>"Invalid parameter type"</error>
|
|
<related>Script</related>
|
|
</function>
|
|
|
|
<function name="Start_Skill_Script">
|
|
<prototype>Start_Skill_Script( chr, attr_name, script_name := "", param := 0 )</prototype>
|
|
<parameter name="chr" value="Character to start the script for"/>
|
|
<parameter name="attr_name" value="String of AttributeID to start the script for e.g. 'Anatomy'"/>
|
|
<parameter name="script_name" value="If given, starts this script instead of the default one" />
|
|
<parameter name="param" value="object to pass to the script. Only one param may be passed. (optional)"/>
|
|
<explain>starts for given chr and attr_name definied script (overrideable with param script_name)</explain>
|
|
<explain>param is any UObject given to skill script as second param (first is chr)</explain>
|
|
<explain>performs the same checks like normal skillusage (death,frozen,skilldelay,...)</explain>
|
|
<explain>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.</explain>
|
|
<return>A Script object for the started script on success.</return>
|
|
<related>Script</related>
|
|
</function>
|
|
|
|
<function name="Run_Script">
|
|
<prototype>Run_Script( script_name, param := 0 )</prototype>
|
|
<parameter name="script_name" value="String name and path of script to run" />
|
|
<parameter name="param" value="object to pass to the script. Only one param may be passed. (optional)"/>
|
|
<explain>Starts a new NON-CRITICAL script. Runs until the script exits, returns the return value of the started script.</explain>
|
|
<explain>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.</explain>
|
|
<return>The return value of the started script, or 1 if no value was returned</return>
|
|
<error>"Unable to read script"</error>
|
|
<error>"Script exited with an error condition"</error>
|
|
<error>"Script does not exist"</error>
|
|
<error>"Script descriptor error"</error>
|
|
</function>
|
|
|
|
<function name="Run_Script_To_Completion">
|
|
<prototype>Run_Script_To_Completion( script_name, param := 0 )</prototype>
|
|
<parameter name="script_name" value="String name and path of script to run" />
|
|
<parameter name="param" value="object to pass to the script. Only one param may be passed. (optional)"/>
|
|
<explain>Starts a new CRITICAL script. Runs until the script exits, returns the return value of the started script.</explain>
|
|
<explain>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.</explain>
|
|
<explain>Every 1000 instructions, "Script X running.." is printed to the console</explain>
|
|
<return>The return value of the started script, or 1 if no value was returned</return>
|
|
<error>"Unable to read script"</error>
|
|
<error>"Script exited with an error condition"</error>
|
|
<error>"Script does not exist"</error>
|
|
<error>"Script descriptor error"</error>
|
|
</function>
|
|
|
|
<function name="SysLog">
|
|
<prototype>SysLog( text, log_verbose:=1, console_color:="" )</prototype>
|
|
<parameter name="text" value="String"/>
|
|
<parameter name="log_verbose" value="Integer (1/0)"/>
|
|
<parameter name="console_color" value="xterm text formatting string e.g. one of the CONSOLE_COLOR constants"/>
|
|
<explain>write text to the console, and to the log file includes context (calling script name). Context will be skipped if parameter log_verbose is set to 0</explain>
|
|
<explain>
|
|
Parameter console_color needs linux or windows 11, when given ends the line with resetting the formatting ("\x1b[0m"). Via pol.cfg EnableColoredOutput color prints can be disabled. Only the console output receives the formatting strings, the pol.log output is not touched.
|
|
</explain>
|
|
<return>1 on success</return>
|
|
</function>
|
|
|
|
<function name="Clear_Event_Queue">
|
|
<prototype>Clear_Event_Queue()</prototype>
|
|
<explain>Empties the current script's event queue</explain>
|
|
<return>1 on success</return>
|
|
</function>
|
|
|
|
<function name="OpenURL">
|
|
<prototype>OpenURL( character, url )</prototype>
|
|
<parameter name="character" value="Player Character Ref" />
|
|
<parameter name="url" value="String" />
|
|
<explain>Sends an Open URL packet to the client, to open the url in their Default Browser.</explain>
|
|
<return>1 on success</return>
|
|
<error>"No client attached"</error>
|
|
</function>
|
|
|
|
<function name="Set_Event_Queue_Size">
|
|
<prototype>Set_Event_Queue_Size(size)</prototype>
|
|
<parameter name="size" value="Integer new size"/>
|
|
<explain>Changes the maximum number of events the current script will keep in the queue (additional events will be discarded).</explain>
|
|
<explain>If not called, the default size is 20 events.</explain>
|
|
<return>Integer old queue size.</return>
|
|
<error>"Invalid parameter type"</error>
|
|
</function>
|
|
|
|
<function name="Create_Debug_Context">
|
|
<prototype>Create_Debug_Context()</prototype>
|
|
<explain>TBD</explain>
|
|
<return>TBD</return>
|
|
</function>
|
|
|
|
<function name="Is_Critical">
|
|
<prototype>Is_Critical()</prototype>
|
|
<explain>Returns true if the script is critical (by using set_critical())</explain>
|
|
<return>1 if critical, else 0.</return>
|
|
</function>
|
|
|
|
<function name="OpenConnection">
|
|
<prototype>OpenConnection( host, port, scriptdef, params:=0, assume_string:=0, keep_connection:=0 )</prototype>
|
|
<parameter name="host" value="Target host"/>
|
|
<parameter name="port" value="Target port"/>
|
|
<parameter name="scriptdef" value="Name of the script to be started when the connection is established"/>
|
|
<parameter name="params" value="A struct of parameters to be sent to the script"/>
|
|
<parameter name="assume_string" value="Integer if set to 1 all communication from connection will be sent/received as raw strings."/>
|
|
<parameter name="keep_connection" value="Integer if set to 1 the connection will not timeout and will be kept alive until the auxiliary script exists."/>
|
|
<parameter name="ignore_line_breaks" value="Integer if set to 1 the connection script will receive events for all incoming socket data and not be restricted to data ending in line breaks, with CRLFs included in the event's value. The connection's transmit method will also not append a CRLF to the message."/>
|
|
<explain>Creates an outgoing TCP/IP connection to the host/port, once connection is open the scriptdef is run and</explain>
|
|
<explain> any params defined in the struct will be passed to that script. The script type should be in the form of an Auxilry Script.</explain>
|
|
<return>1 on success</return>
|
|
</function>
|
|
|
|
<function name="Debugger">
|
|
<prototype>Debugger()</prototype>
|
|
<explain>puts the script in debug state</explain>
|
|
<return>1 on success</return>
|
|
</function>
|
|
|
|
<function name="PerformanceMeasure">
|
|
<prototype>PerformanceMeasure(delta_seconds := 10, max_scripts := 100)</prototype>
|
|
<parameter name="delta_seconds" value="seconds to observe"/>
|
|
<parameter name="max_scripts" value="maximum number of scripts to be returned"/>
|
|
<explain>Monitors for given number of seconds the instructions of all scripts.</explain>
|
|
<explain>Returns struct with the following members:</explain>
|
|
<explain>total_number_observed : number of scripts alive in the timespan</explain>
|
|
<explain>total_instructions : sum of all instructions of the observed scripts</explain>
|
|
<explain>scripts : array of structs (max number is given max_scripts param) sorted by instructions amount</explain>
|
|
<explain>each scripts entry has the following members:</explain>
|
|
<explain>name : script name, if attached with name/npctemplate</explain>
|
|
<explain>instructions : number of executed instructions</explain>
|
|
<explain>pid : PID of the script</explain>
|
|
<explain>percent : percent of the total instruction amount</explain>
|
|
<return>see above</return>
|
|
</function>
|
|
|
|
<function name="HTTPRequest">
|
|
<prototype>HTTPRequest(url, method := "GET", options := struct{}, flags := 0)</prototype>
|
|
<parameter name="url" value="URL"/>
|
|
<parameter name="method" value="HTTP Method to use for request (eg. GET, POST)"/>
|
|
<parameter name="options" value="A struct containing options for the request. Available options are: 'data', a string representing the POST data; 'headers', a struct containing headers to send, where the key is the header's name and value is the header's value" />
|
|
<parameter name="flags" value="Flags to modify behavior." />
|
|
<explain>Creates an HTTP request, and returns the returned body as a string, or if HTTPREQUEST_EXTENDED_RESPONSE is passed as flags, returns a Dictionary with response data.
|
|
<code>
|
|
|
|
Example: create a POST request to a REST endpoint with custom header:
|
|
|
|
HTTPRequest("http://localhost:3000/","POST", struct{
|
|
data := "{\"stuff1\":[1,2,35]}",
|
|
headers := struct{
|
|
"Content-Type" := "application/json"
|
|
}
|
|
});
|
|
</code>
|
|
</explain>
|
|
<return>If HTTPREQUEST_EXTENDED_RESPONSE is passed as flags, returns a Dictionary with members: 'status', the numeric HTTP status code; 'statusText', the reason phrase; 'headers', a Dictionary of key-values for each header; 'body', the response text body. Otherwise, returns response body as a string.</return>
|
|
</function>
|
|
|
|
<function name="LoadExportedScript">
|
|
<prototype>LoadExportedScript( script_name, params := {} )</prototype>
|
|
<parameter name="script_name" value="String name and path of script to run" />
|
|
<parameter name="params" value="array of objects to pass to the script. Array will be unpacked and as single arguments passed (optional)"/>
|
|
<explain>Starts a new script, to be able to later call exported functions. Non-critical or critical depending on the current state of the calling script. Blocks until the program part of the script is finished. See ExportedScript documentation how to call exported functions.</explain>
|
|
<return>Array{ExportedScript,return value} The value returned is the return value of the started script, or 1 if no value was returned</return>
|
|
<related>ExportedScript</related>
|
|
</function>
|
|
|
|
<function name="GetEnvironmentVariable">
|
|
<prototype>GetEnvironmentVariable(name:="")</prototype>
|
|
<parameter name="name" value="String name of environment variable, or empty string" />
|
|
<explain>Returns the value of given environment variable, or if no name is given it returns a dictionary with all allowed environment variables.</explain>
|
|
<explain>pol.cfg AllowedEnvironmentVariablesAccess setting can be used to restrict access to the environmental variables. Provide a comma-separated list to limit scripts' access to only the variables provided. Use * to allow all variables. Default value: empty (no access)</explain>
|
|
<return>String value of given enviroment variable, or if no name is given Dictionary{String, String}</return>
|
|
<relatedcfg>pol.cfg</relatedcfg>
|
|
</function>
|
|
|
|
<function name="SendEmail">
|
|
<prototype>SendEmail( from, recipient, subject, body, bcc := 0, content_type := "text/plain" );</prototype>
|
|
<parameter name="from" value="String specifying the sender's email address" />
|
|
<parameter name="recipient" value="String (or Array of Strings) specifying the recipients' email address. Can be 0 to specify no recipients (eg. use BCC only)" />
|
|
<parameter name="subject" value="String specifying the subject of the email" />
|
|
<parameter name="body" value="String specifying the body of the email" />
|
|
<parameter name="bcc" value="String (or Array of Strings) specifying the BCC recipients' email address. Can be 0 to specify no BCC recipients" />
|
|
<parameter name="content_type" value="String specifying the content type of the email" />
|
|
<explain>Sends an email using the given parameters.</explain>
|
|
<explain>Email addresses in the `from`, `to`, and `bcc` parameters can be in the form "local-part@domain" or "Display Name <local-part@domain>".</explain>
|
|
<explain>Email server settings are specified in email.cfg.</explain>
|
|
<explain>Examples:</explain>
|
|
<explain><code>
|
|
|
|
SendEmail( "no-reply@polserver.com", "player@polserver.com", "Welcome to the shard", "Thanks for joining!" );
|
|
|
|
// Sends an HTML email to the player with BCC to two admins.
|
|
|
|
SendEmail(
|
|
"POLServer Shard <no-reply@polserver.com>",
|
|
"player@polserver.com",
|
|
"Welcome to the shard",
|
|
"Thanks for joining! You can find our server rules <a href='https://example.com/rules'>here</a>",
|
|
{ "admin-one@polserver.com", "admin-two@polserver.com" },
|
|
"text/html"
|
|
);</code></explain>
|
|
<return>1 on success</return>
|
|
<error>"Email settings are not configured"</error>
|
|
<error>"Invalid parameter type"</error>
|
|
<error>"Invalid recipient type in array"</error>
|
|
<error>"Invalid recipient type"</error>
|
|
<error>"Script can't be blocked"</error>
|
|
<error><any error message from email library></error>
|
|
<relatedcfg>email.cfg</relatedcfg>
|
|
</function>
|
|
</ESCRIPT>
|