remoteExecCall

From Bohemia Interactive Community
Revision as of 17:04, 2 January 2021 by Ansin11 (talk | contribs) (Reworked examples, some other changes)
Jump to navigation Jump to search



Arma 3 logo black.png1.50
Hover & click on the images for description

Description

Description:
Asks the server to execute the given function or script command on the given target machine(s). Execution always takes place in the unscheduled environment; suspension is not allowed.
Read Arma 3: Remote Execution for more information about remote execution, security features and JIP techniques.
ⓘ
Just like remoteExec, remoteExecCall can be used in SP; the behaviour is the same as in MP.
⚠
The "Call" in remoteExecCall does not mean that the execution of the remote executed function / command will happen right away, it just means that the execution of the function / command will take place in the unscheduled environment:

remoteExecCall ["fnc1"]; call fnc2; // It is possible that fnc1 is executed after fnc2.

call fnc1; call fnc2; // fnc2 will always be executed after fnc1.
ⓘ
The direct execution of call or spawn via remoteExecCall (or remoteExec) should be avoided to prevent issues in cases where the remote execution of call or spawn is blocked by CfgRemoteExec. Instead it is recommended to create a function which is then excecuted by remoteExecCall (or remoteExec).
Groups:
Multiplayer

Syntax

Syntax:
params remoteExecCall [functionName, targets, JIP]
Parameters:
params: Anything - The parameter(s) for the function / command specified in the functionName parameter.
[functionName, targets, JIP]: Array
functionName: String - Function or command name.
While any function or command can be used here, only those defined in CfgRemoteExec will actually be executed.
targets (Optional, default: 0):
  • Number (See also: Machine network ID) -
    • 0: The function / command will be executed globally, i.e. on the server and every connected client, including the machine where remoteExecCall originated.
    • 2: The function / command will only be executed on the server.
    • Other number: The function / command will be executed on the machine where clientOwner matches the given number.
    • Negative number: The effect is inverted: -2 means every client but not the server, -12 means the server and every client, except for the client where clientOwner returns 12.
  • Object - The function / command will be executed where the given Object is local.
  • String - Interpreted as an Identifier (variable name). The function / command will be executed where the Object or Group identified by the variable with the provided name is local.
  • Side - The function / command will be executed on machines where the player is on the specified side.
  • Group - The function / command will be executed on machines where the player is in the specified group.
    In order to execute the function / command where the group is local, use the groupOwner of the group: _myGroup remoteExecCall ["deleteGroup", groupOwner _myGroup];
  • Array - Array of any combination of the types listed above.
JIP (Optional, default: false):
  • Boolean - If true, a unique JIP ID is generated and the remoteExecCall statement is added to the JIP queue from which it will be executed for every JIP.
  • String -
    • If the string is empty, it is interpreted as false.
    • If the string is in format "Number:Number" (e.g. "0:0"), it is interpreted as a netId (see below).
    • Else the string is treated as a custom JIP ID and the remoteExecCall statement is added to the JIP queue, replacing statements that have the same JIP ID.
  • Object, Group or netId - The persistent execution of the remoteExecCall statement is attached to the given Object or Group.
    When the Object or Group is deleted, the remoteExecCall statement is automatically removed from the JIP queue.
See also Example 7 on how to remove statements from the JIP queue.
Return Value:
  • nil - In case of error.
  • String - In case of success.
    • If the JIP parameter was false or an empty string, the return value is "".
    • If the JIP parameter was true or a custom JIP ID, the JIP ID is returned.
    • If the JIP parameter was an Object, a Group or a netId, the (corresponding) netId is returned.

Alternative Syntax

Syntax:
remoteExecCall [functionName, targets, JIP]
Parameters:
[functionName, targets, JIP]: Array
functionName: String - See the main syntax above for more details.
targets (Optional, default: 0): Number, Object, String, Side, Group or Array - See the main syntax above for more details.
JIP (Optional, default: false): Boolean, String, Object, Group or netId - See the main syntax above for more details.
Return Value:
nil or String - See the main syntax above for more details.

Examples

Example 1:
Execute hint "Example 1"; on all connected machines: "Example 1" remoteExecCall ["hint"];
Example 2:
Execute hint "Example 2"; on the first connected client: "Example 2" remoteExecCall ["hint", 3];
Example 3:
Execute hint "Example 3"; everywhere except on the server: "Example 3" remoteExecCall ["hint", -2];
Example 4:
Execute hint "Example 4"; everywhere except on the server and add the statement to the JIP queue: _result = "Example 4" remoteExecCall ["hint", -2, true]; // _result is a unique JIP ID, e.g. "3_1".
Example 5:
Execute hint "Example 5"; everywhere except on the server and add the statement to the JIP queue using a custom JIP ID: _result = "Example 5" remoteExecCall ["hint", -2, "My_JIP_ID"]; // _result is "My_JIP_ID". If there already was a statement with the JIP ID "My_JIP_ID" in the JIP queue, that statement has now been overwritten.
Example 6:
Execute ME_fnc_myFunction on all connected machines - note that the function does not receive any arguments: remoteExecCall ["ME_fnc_myFunction"];
Example 7:
Remove statements from the JIP queue: remoteExecCall ["", "My_JIP_ID"]; // The persistent statement with the JIP ID "My_JIP_ID" is removed from the JIP queue. remoteExecCall ["", MyObject]; // The persistent statement attached to MyObject is removed from the JIP queue.
Example 8:
Execute call {player setAmmo [primaryWeapon player, 1];}; on machines where the player is in MyGroup: {player setAmmo [primaryWeapon player, 1];} remoteExecCall ["call", MyGroup]; Note that, while being a valid statement, [player, [primaryWeapon player, 1]] remoteExecCall ["setAmmo", MyGroup]; does not have the same effect as the code above. This is because the arguments player and primaryWeapon player are not resolved on the target machine(s), but on the machine executing remoteExecCall.

Additional Information

See also:
remoteExecisRemoteExecutedisRemoteExecutedJIPremoteExecutedOwnercanSuspendBIS_fnc_MPArma 3: Remote 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+? \[[\S\s]*\]" 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"];
Posted on January 17, 2020 - 15:05 (UTC)
Dscha
To send/execute custom functions and pass arguments (in this case to every connected Client, except the dedicated server):
[
[10,0],
{
player setAmmo [primaryWeapon player, (_this select 0)];
player setDamage (_this select 1)];
}
] remoteExecCall ["call", -2];
Retrieved from "https://community.bistudio.com/wiki?title=remoteExecCall&oldid=181093"