mirror of
https://github.com/polserver/polserver
synced 2026-08-13 08:23:08 -04:00
12d6186d10
* Fix SCRIPTOPT_CAN_ACCESS_OFFLINE_MOBILES * Add SCRIPTOPT_SURVIVE_ATTACHED_DISCONNECT * wip beginning work on templatization * Use PolModule in pol-specific modules * wip, creating PolModule with getXYZParam * wip 1, moving getXYZ to UOExecutor * compilable with PolObjectImp / PolApplicObj * add type guard * wip, change signatures change signatures of script_method, script_method_id, and custom_script_method * compilable (windows) * linux fixes * namespace fixes * remove uoexhelp * formatting * compilable - move can_access_offline_mobiles back to uoexec - add guildscrobj and partyscrobj sources - move EGuildRefObjImp and EPartyRefObjImp - wip, implement asUOExec - formatting uoexec.cpp,.h * finish uoexec() helper * some cleanup
276 lines
15 KiB
XML
276 lines
15 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>12/23/2017</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>
|
|
</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" />
|
|
<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. 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 1.</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 )</prototype>
|
|
<parameter name="text" value="String"/>
|
|
<explain>write text to the console, and to the log file includes context (calling script name)</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 )</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."/>
|
|
<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{})</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" />
|
|
<explain>Creates an HTTP request, and returns the returned data as a string.</explain>
|
|
<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>
|
|
<return>Response data as a string.</return>
|
|
</function>
|
|
</ESCRIPT>
|