remoteExecCall: Difference between revisions
Jump to navigation
Jump to search
Lou Montana (talk | contribs) m (moved the JIP default value closer to title for visibility and consistence) |
(added alternative, unary syntax) |
||
Line 38: | Line 38: | ||
<code>// <params1> someScriptCommand <params2>; | <code>// <params1> someScriptCommand <params2>; | ||
[<params1>, <params2>] [[remoteExecCall]] ["someScriptCommand", targets, JIP];</code> | [<params1>, <params2>] [[remoteExecCall]] ["someScriptCommand", targets, JIP];</code> | ||
|= | |= Parameter 1 | ||
|p2= '''[functionName, targets, JIP]''': [[Array]]|= | |p2= '''[functionName, targets, JIP]''': [[Array]]|= Parameter 2 | ||
|p3= '''functionName''': [[String]] - function or command name. <br/> | |p3= '''functionName''': [[String]] - function or command name. <br/> | ||
While any function can be used, only commands and functions defined in [[CfgRemoteExec]] will be executed. | While any function can be used, only commands and functions defined in [[CfgRemoteExec]] will be executed. | ||
|= | |= Parameter 3 | ||
|p4= '''targets''' (Optional): [default: 0 = everyone] | |p4= '''targets''' (Optional): [default: 0 = everyone] | ||
* [[Number]] - Only 0 and 2 are special. When 0, the function or command will be executed globally, i.e. on the server and every connected client, including the one where [[remoteExecCall]] was originated. When 2, it will be executed only on the [[isServer|server]]. When 3, 4, 5...etc it will be executed on the client where [[clientOwner]] ID matches the given number. When number is negative, the effect is inverted. -2 means execute on every client but not the server. -12, for example, means execute on the server and every client, but not on the client where [[clientOwner]] ID is equal to 12. | * [[Number]] - Only 0 and 2 are special. When 0, the function or command will be executed globally, i.e. on the server and every connected client, including the one where [[remoteExecCall]] was originated. When 2, it will be executed only on the [[isServer|server]]. When 3, 4, 5...etc it will be executed on the client where [[clientOwner]] ID matches the given number. When number is negative, the effect is inverted. -2 means execute on every client but not the server. -12, for example, means execute on the server and every client, but not on the client where [[clientOwner]] ID is equal to 12. | ||
Line 50: | Line 50: | ||
* [[Group]] - the function will be executed only on clients where the player is in the specified group. In order to execute the function where group is [[local]] pass owner of the group as param: <br><tt>_myGroup [[remoteExecCall]] ["deleteGroup", [[groupOwner]] _myGroup];</tt> | * [[Group]] - the function will be executed only on clients where the player is in the specified group. In order to execute the function where group is [[local]] pass owner of the group as param: <br><tt>_myGroup [[remoteExecCall]] ["deleteGroup", [[groupOwner]] _myGroup];</tt> | ||
* [[Array]] - array of any of types listed above. | * [[Array]] - array of any of types listed above. | ||
|= | |= Parameter 4 | ||
|p5= ''' JIP''' (Optional): [default: false]<br><br> | |p5= ''' JIP''' (Optional): [default: false]<br><br> | ||
* [[String]] or [[Boolean]] - If [[true]], function generates a unique ID for the message and the message itself is added to the JIP queue and executed for every JIP. If a non-empty string is given, it is treated a custom ID of the message and the message itself is added to the JIP queue overriding any [[remoteExecCall]] message with the same ID. Otherwise, no ID is generated and no message is placed into the JIP queue. (see also Example 7 on how to remove previously set function from JIP queue)<br><br> | * [[String]] or [[Boolean]] - If [[true]], function generates a unique ID for the message and the message itself is added to the JIP queue and executed for every JIP. If a non-empty string is given, it is treated a custom ID of the message and the message itself is added to the JIP queue overriding any [[remoteExecCall]] message with the same ID. Otherwise, no ID is generated and no message is placed into the JIP queue. (see also Example 7 on how to remove previously set function from JIP queue)<br><br> | ||
* [[Object]] or [[Group]] or [[netId]] - The persistent execution of the given [[remoteExecCall]] statement will be attached to the given [[Object]] or [[Group]], passed directly by reference or by their [[netId]]: <tt>_netId = "this is my car" [[remoteExecCall]] ["hint", 0, car];</tt> or <tt>_netId = "this is my car" [[remoteExecCall]] ["hint", 0, [[netId]] car];</tt>Upon success, the command will return [[netId]] of the used [[Object]] or [[Group]] or [[netId]]. When [[Object]] or [[Group]] is deleted and becomes [[objNull]] or [[grpNull]], the persistent [[remoteExecCall]] statement is automatically removed from JIP queue. Manual removal of the JIP statement could be done by passing either [[Object]], [[Group]] or [[netId]] as usual:<tt>[[remoteExecCall]] ["", car];</tt> or <tt>[[remoteExecCall]] ["", [[netId]] car];</tt>When JIP param is [[String]] in format "[[Number]]:[[Number]]", the string will be tested first whether or not it is the valid [[netId]] of an existing [[Object]] or [[Group]], and if not the execution will be aborted, if yes, that [[Object]] or [[Group]] will be used to set persistent execution.|= | * [[Object]] or [[Group]] or [[netId]] - The persistent execution of the given [[remoteExecCall]] statement will be attached to the given [[Object]] or [[Group]], passed directly by reference or by their [[netId]]: <tt>_netId = "this is my car" [[remoteExecCall]] ["hint", 0, car];</tt> or <tt>_netId = "this is my car" [[remoteExecCall]] ["hint", 0, [[netId]] car];</tt>Upon success, the command will return [[netId]] of the used [[Object]] or [[Group]] or [[netId]]. When [[Object]] or [[Group]] is deleted and becomes [[objNull]] or [[grpNull]], the persistent [[remoteExecCall]] statement is automatically removed from JIP queue. Manual removal of the JIP statement could be done by passing either [[Object]], [[Group]] or [[netId]] as usual:<tt>[[remoteExecCall]] ["", car];</tt> or <tt>[[remoteExecCall]] ["", [[netId]] car];</tt>When JIP param is [[String]] in format "[[Number]]:[[Number]]", the string will be tested first whether or not it is the valid [[netId]] of an existing [[Object]] or [[Group]], and if not the execution will be aborted, if yes, that [[Object]] or [[Group]] will be used to set persistent execution.|= Parameter 5 | ||
|p6= Note: JIP mostly makes sense for messages doing changes local to client (not directly synchronized over the network). Otherwise, after remoteExec is executed, depending on the contents of the global JIP queue there is a chance a new message could be added to it, unnecessary increasing the number of messages sent to any newly connected client. | |p6= Note: JIP mostly makes sense for messages doing changes local to client (not directly synchronized over the network). Otherwise, after remoteExec is executed, depending on the contents of the global JIP queue there is a chance a new message could be added to it, unnecessary increasing the number of messages sent to any newly connected client. | ||
E.g. calling "..remoteExec ["setFuel"..]" is fine, however, calling "..remoteExec ["publicVariable",..]" is not. |= | E.g. calling "..remoteExec ["setFuel"..]" is fine, however, calling "..remoteExec ["publicVariable",..]" is not. |= Parameter 6 | ||
| [[Anything]] - Nil in case of error. [[String]] otherwise. If JIP is not requested this is an empty string, if JIP is requested, it is the JIP ID. See the topic [[Function#Return_Values|Function]] for more information. |= Return value | | [[Anything]] - Nil in case of error. [[String]] otherwise. If JIP is not requested this is an empty string, if JIP is requested, it is the JIP ID. See the topic [[Function#Return_Values|Function]] for more information. |= Return value | ||
_________________________________________________________________________________________________________________ | |||
|s2= [[remoteExecCall]] [functionName, targets, JIP] |= Syntax 2 | |||
|p21= '''[functionName, targets, JIP]''': [[Array]]|= Parameter 1 | |||
|p22= '''functionName''': [[String]] - function or command name. <br/> | |||
While any function can be used, only commands and functions defined in [[CfgRemoteExec]] will be executed. | |||
|= Parameter 2 | |||
|p23= '''targets''' (Optional): [default: 0 = everyone] | |||
* [[Number]] - Only 0 and 2 are special. When 0, the function or command will be executed globally, i.e. on the server and every connected client, including the one where [[remoteExecCall]] was originated. When 2, it will be executed only on the [[isServer|server]]. When 3, 4, 5...etc it will be executed on the client where [[clientOwner]] ID matches the given number. When number is negative, the effect is inverted. -2 means execute on every client but not the server. -12, for example, means execute on the server and every client, but not on the client where [[clientOwner]] ID is equal to 12. | |||
* [[Object]] - the function will be executed only where unit is local | |||
* [[String]] - the function will be executed only where object or group defined by the variable with passed name is local | |||
* [[Side]] - the function will be executed only on clients where the player is on the specified side. | |||
* [[Group]] - the function will be executed only on clients where the player is in the specified group. In order to execute the function where group is [[local]] pass owner of the group as param: <br><tt>_myGroup [[remoteExecCall]] ["deleteGroup", [[groupOwner]] _myGroup];</tt> | |||
* [[Array]] - array of any of types listed above. | |||
|= Parameter 3 | |||
|p24= ''' JIP''' (Optional): [default: false]<br><br> | |||
* [[String]] or [[Boolean]] - If [[true]], function generates a unique ID for the message and the message itself is added to the JIP queue and executed for every JIP. If a non-empty string is given, it is treated a custom ID of the message and the message itself is added to the JIP queue overriding any [[remoteExecCall]] message with the same ID. Otherwise, no ID is generated and no message is placed into the JIP queue. (see also Example 7 on how to remove previously set function from JIP queue)<br><br> | |||
* [[Object]] or [[Group]] or [[netId]] - The persistent execution of the given [[remoteExecCall]] statement will be attached to the given [[Object]] or [[Group]], passed directly by reference or by their [[netId]]: <tt>_netId = "this is my car" [[remoteExecCall]] ["hint", 0, car];</tt> or <tt>_netId = "this is my car" [[remoteExecCall]] ["hint", 0, [[netId]] car];</tt>Upon success, the command will return [[netId]] of the used [[Object]] or [[Group]] or [[netId]]. When [[Object]] or [[Group]] is deleted and becomes [[objNull]] or [[grpNull]], the persistent [[remoteExecCall]] statement is automatically removed from JIP queue. Manual removal of the JIP statement could be done by passing either [[Object]], [[Group]] or [[netId]] as usual:<tt>[[remoteExecCall]] ["", car];</tt> or <tt>[[remoteExecCall]] ["", [[netId]] car];</tt>When JIP param is [[String]] in format "[[Number]]:[[Number]]", the string will be tested first whether or not it is the valid [[netId]] of an existing [[Object]] or [[Group]], and if not the execution will be aborted, if yes, that [[Object]] or [[Group]] will be used to set persistent execution.|= Parameter 4 | |||
|p25= Note: JIP mostly makes sense for messages doing changes local to client (not directly synchronized over the network). Otherwise, after remoteExec is executed, depending on the contents of the global JIP queue there is a chance a new message could be added to it, unnecessary increasing the number of messages sent to any newly connected client. | |||
E.g. calling "..remoteExec ["setFuel"..]" is fine, however, calling "..remoteExec ["publicVariable",..]" is not. |= Parameter 5 | |||
|r2= [[Anything]] - Nil in case of error. [[String]] otherwise. If JIP is not requested this is an empty string, if JIP is requested, it is the JIP ID. See the topic [[Function#Return_Values|Function]] for more information. |= Return value | |||
____________________________________________________________________________________________ | ____________________________________________________________________________________________ | ||
Revision as of 17:24, 5 April 2018
Description
- Description:
- Asks server to execute given scripted function or script command on given target PC. The environment chosen for the execution is as follows:
- Scripted function - unscheduled environment (suspension is NOT allowed).
- Script command - unscheduled environment (suspension is NOT allowed).
Template:note - Groups:
- Uncategorised
Syntax
- Syntax:
- params remoteExecCall [functionName, targets, JIP]
- Parameters:
- params: Anything
Example for scripted function:// <params> call fnc_someScriptedFunction; <params> remoteExecCall ["fnc_someScriptedFunction", targets, JIP];
Examples for script commands of every kind:// someScriptCommand; [] remoteExecCall ["someScriptCommand", targets, JIP];
// someScriptCommand <params>; [<params>] remoteExecCall ["someScriptCommand", targets, JIP];
// <params1> someScriptCommand <params2>; [<params1>, <params2>] remoteExecCall ["someScriptCommand", targets, JIP];
- [functionName, targets, JIP]: Array
- functionName: String - function or command name.
While any function can be used, only commands and functions defined in CfgRemoteExec will be executed. - targets (Optional): [default: 0 = everyone]
- Number - Only 0 and 2 are special. When 0, the function or command will be executed globally, i.e. on the server and every connected client, including the one where remoteExecCall was originated. When 2, it will be executed only on the server. When 3, 4, 5...etc it will be executed on the client where clientOwner ID matches the given number. When number is negative, the effect is inverted. -2 means execute on every client but not the server. -12, for example, means execute on the server and every client, but not on the client where clientOwner ID is equal to 12.
- Object - the function will be executed only where unit is local
- String - the function will be executed only where object or group defined by the variable with passed name is local
- Side - the function will be executed only on clients where the player is on the specified side.
- Group - the function will be executed only on clients where the player is in the specified group. In order to execute the function where group is local pass owner of the group as param:
_myGroup remoteExecCall ["deleteGroup", groupOwner _myGroup]; - Array - array of any of types listed above.
- JIP (Optional): [default: false]
- String or Boolean - If true, function generates a unique ID for the message and the message itself is added to the JIP queue and executed for every JIP. If a non-empty string is given, it is treated a custom ID of the message and the message itself is added to the JIP queue overriding any remoteExecCall message with the same ID. Otherwise, no ID is generated and no message is placed into the JIP queue. (see also Example 7 on how to remove previously set function from JIP queue)
- Object or Group or netId - The persistent execution of the given remoteExecCall statement will be attached to the given Object or Group, passed directly by reference or by their netId: _netId = "this is my car" remoteExecCall ["hint", 0, car]; or _netId = "this is my car" remoteExecCall ["hint", 0, netId car];Upon success, the command will return netId of the used Object or Group or netId. When Object or Group is deleted and becomes objNull or grpNull, the persistent remoteExecCall statement is automatically removed from JIP queue. Manual removal of the JIP statement could be done by passing either Object, Group or netId as usual:remoteExecCall ["", car]; or remoteExecCall ["", netId car];When JIP param is String in format "Number:Number", the string will be tested first whether or not it is the valid netId of an existing Object or Group, and if not the execution will be aborted, if yes, that Object or Group will be used to set persistent execution.
- String or Boolean - If true, function generates a unique ID for the message and the message itself is added to the JIP queue and executed for every JIP. If a non-empty string is given, it is treated a custom ID of the message and the message itself is added to the JIP queue overriding any remoteExecCall message with the same ID. Otherwise, no ID is generated and no message is placed into the JIP queue. (see also Example 7 on how to remove previously set function from JIP queue)
- Note: JIP mostly makes sense for messages doing changes local to client (not directly synchronized over the network). Otherwise, after remoteExec is executed, depending on the contents of the global JIP queue there is a chance a new message could be added to it, unnecessary increasing the number of messages sent to any newly connected client. E.g. calling "..remoteExec ["setFuel"..]" is fine, however, calling "..remoteExec ["publicVariable",..]" is not.
- Return Value:
- Anything - Nil in case of error. String otherwise. If JIP is not requested this is an empty string, if JIP is requested, it is the JIP ID. See the topic Function for more information.
Alternative Syntax
- Syntax:
- remoteExecCall [functionName, targets, JIP]
- Parameters:
- [functionName, targets, JIP]: Array
- functionName: String - function or command name.
While any function can be used, only commands and functions defined in CfgRemoteExec will be executed. - targets (Optional): [default: 0 = everyone]
- Number - Only 0 and 2 are special. When 0, the function or command will be executed globally, i.e. on the server and every connected client, including the one where remoteExecCall was originated. When 2, it will be executed only on the server. When 3, 4, 5...etc it will be executed on the client where clientOwner ID matches the given number. When number is negative, the effect is inverted. -2 means execute on every client but not the server. -12, for example, means execute on the server and every client, but not on the client where clientOwner ID is equal to 12.
- Object - the function will be executed only where unit is local
- String - the function will be executed only where object or group defined by the variable with passed name is local
- Side - the function will be executed only on clients where the player is on the specified side.
- Group - the function will be executed only on clients where the player is in the specified group. In order to execute the function where group is local pass owner of the group as param:
_myGroup remoteExecCall ["deleteGroup", groupOwner _myGroup]; - Array - array of any of types listed above.
- JIP (Optional): [default: false]
- String or Boolean - If true, function generates a unique ID for the message and the message itself is added to the JIP queue and executed for every JIP. If a non-empty string is given, it is treated a custom ID of the message and the message itself is added to the JIP queue overriding any remoteExecCall message with the same ID. Otherwise, no ID is generated and no message is placed into the JIP queue. (see also Example 7 on how to remove previously set function from JIP queue)
- Object or Group or netId - The persistent execution of the given remoteExecCall statement will be attached to the given Object or Group, passed directly by reference or by their netId: _netId = "this is my car" remoteExecCall ["hint", 0, car]; or _netId = "this is my car" remoteExecCall ["hint", 0, netId car];Upon success, the command will return netId of the used Object or Group or netId. When Object or Group is deleted and becomes objNull or grpNull, the persistent remoteExecCall statement is automatically removed from JIP queue. Manual removal of the JIP statement could be done by passing either Object, Group or netId as usual:remoteExecCall ["", car]; or remoteExecCall ["", netId car];When JIP param is String in format "Number:Number", the string will be tested first whether or not it is the valid netId of an existing Object or Group, and if not the execution will be aborted, if yes, that Object or Group will be used to set persistent execution.
- String or Boolean - If true, function generates a unique ID for the message and the message itself is added to the JIP queue and executed for every JIP. If a non-empty string is given, it is treated a custom ID of the message and the message itself is added to the JIP queue overriding any remoteExecCall message with the same ID. Otherwise, no ID is generated and no message is placed into the JIP queue. (see also Example 7 on how to remove previously set function from JIP queue)
- Note: JIP mostly makes sense for messages doing changes local to client (not directly synchronized over the network). Otherwise, after remoteExec is executed, depending on the contents of the global JIP queue there is a chance a new message could be added to it, unnecessary increasing the number of messages sent to any newly connected client. E.g. calling "..remoteExec ["setFuel"..]" is fine, however, calling "..remoteExec ["publicVariable",..]" is not.
- Return Value:
- Anything - Nil in case of error. String otherwise. If JIP is not requested this is an empty string, if JIP is requested, it is the JIP ID. See the topic Function for more information.
Examples
- Example 1:
// runs hint "hello" on each connected client "hello" remoteExecCall ["hint"];
- Example 2:
// runs hint "hello" on first connected client "hello" remoteExecCall ["hint", 3];
- Example 3:
// runs hint "hello" everywhere but server "hello" remoteExecCall ["hint", -2];
- Example 4:
// runs hint "hello" everywhere but server, JIPs the message // and returns e.g. "3_1" as a unique JIP id myJipID = "hello" remoteExecCall ["hint", -2, true];
- Example 5:
// runs hint "hello" everywhere but server, JIPs the message under ID "some_JIP_ID" // replacing any previous message with this ID in the JIP queue. "hello" remoteExecCall ["hint", -2, "some_JIP_ID"];
- Example 6:
// runs "someFuncWithNoArgs" on each connected client remoteExecCall ["someFuncWithNoArgs"];
- Example 7:
// removes a message identified by "IamUnique" from the JIP queue remoteExecCall ["", "IamUnique"];
- Example 8:
// all clients will have their ammo set to 1 for their current weapon {player setAmmo [primaryWeapon player, 1];} remoteExecCall ["bis_fnc_call", 0];
- Example 9:
// Object obj will have its ammo set to 1 where it is local [obj,[primaryWeapon obj, 1]] remoteExecCall ["setAmmo", obj];
- Example 10:
myJipID = "hello" remoteExecCall ["", 0]; if (isNil "myJipID") then { hint "empty function name is not allowed"; };
Additional Information
- See also:
- remoteExecisRemoteExecutedisRemoteExecutedJIPremoteExecutedOwnercanSuspendBIS_fnc_MPRemote Execution
Notes
-
Report bugs on the Feedback Tracker and/or discuss them on the Arma Discord or on the Forums.
Only post proven facts here! Add Note
- Posted on July 16, 2015 - 09:17 (UTC)
- Killzone Kid
-
Removal of persistent call must be in the following format <no argument> remoteExecCall [<empty string>, <JIP id>]. For example:
remoteExecCall ["", "5:8"];
- Posted on December 29, 2015 - 20:31 (UTC)
- AgentRev
-
remoteExec and remoteExecCall are currently filtered by BattlEye's remoteexec.txt, the string analyzed by BE is formatted the same way as the following example's output:
format ["%1 %2", functionName, str params]
If CfgRemoteExec class Functions is set to mode = 1;, the following remoteexec.txt exclusion can be used to safely allow all whitelisted *_fnc_* functions taking an array as parameter to go through:!="\w+?_fnc_\w+? \[.*\]"
Any attempt to exploit this exclusion using other RE methods like createUnit will run into "Error Missing ;" without any malicious code being executed. Mod makers should refrain from remote-executing raw commands from clients, as they require individual exclusions, and instead use *_fnc_* functions taking an array as parameter, which are covered by the above exclusion.
- Posted on May 10, 2017 - 20:13 (UTC)
- Killzone Kid
-
To remoteExecCall:
titleText ["Test Message", "PLAIN", 1];
Use[["Test Message", "PLAIN", 1]] remoteExecCall ["titleText"];