remoteExec: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
No edit summary
(Undo revision 250586 by 7erra (talk))
Tag: Undo
Line 194: Line 194:
</dl>
</dl>
<!-- DISCONTINUE Notes -->
<!-- DISCONTINUE Notes -->
{{subst:Preload/Note|
As a comment to {{User|KC Grimes}} note: The [[remoteExec]]'ed function only has to exist on the target machine. For example:
<code>{{cc|initPlayerLocal.sqf}}
TAG_fnc_testRemote = {
[[hint]] "Remote Exec Received";
};</code>
<code>{{cc|Execute on dedicated server:}}
[] remoteExec ["TAG_fnc_testRemote", -2];</code>
Will display a hint for every client.

Revision as of 01:35, 5 March 2021



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). Read Arma 3: Remote Execution for more information about remote execution, security features and JIP techniques.
ⓘ
Just like remoteExecCall, remoteExec can be used in SP; the behaviour is the same as in MP.
ⓘ
The direct execution of call or spawn via remoteExec (or remoteExecCall) 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 remoteExec (or remoteExecCall).
Groups:
Multiplayer

Syntax

Syntax:
params remoteExec [functionName, targets, JIP]
Parameters:
params: Anything
Example for scripted function: // <params> spawn fnc_someScriptedFunction; <params> remoteExec ["fnc_someScriptedFunction", targets, JIP]; Examples for script commands of every kind: // someScriptCommand; [] remoteExec ["someScriptCommand", targets, JIP]; // someScriptCommand <params>; [<params>] remoteExec ["someScriptCommand", targets, JIP]; // <params1> someScriptCommand <params2>; [<params1>, <params2>] remoteExec ["someScriptCommand", targets, JIP];
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
    • When 0, the function or command will be executed globally, i.e. on the server and every connected client, including the one where remoteExec was originated.
    • When 2, it will be executed only on the server.
    • When 3, 4, 5... 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 remoteExec ["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 remoteExec 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 remoteExec statement will be attached to the given Object or Group, passed directly by reference or by their netId: _netId = "this is my car" remoteExec ["hint", 0, car]; or _netId = "this is my car" remoteExec ["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 remoteExec 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:remoteExec ["", car]; or remoteExec ["", 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.
ⓘ
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.
⚠
There could be only one JIP message with the same JIP ID in the JIP queue. This means that if one tries to remoteExec again with the existing JIP ID, the JIP message which is already in the JIP queue will be overwritten. Passing true for JIP param autogenerates unique ID, therefore adding new message in the JIP queue each time. All other options have potential to overwrite existing JIP message.
Return Value:
Return value needed

Alternative Syntax

Syntax:
remoteExec [functionName, targets, JIP]
Parameters:
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
    • When 0, the function or command will be executed globally, i.e. on the server and every connected client, including the one where remoteExec was originated.
    • When 2, it will be executed only on the server.
    • When 3, 4, 5... 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 remoteExec ["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 remoteExec 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 remoteExec statement will be attached to the given Object or Group, passed directly by reference or by their netId: _netId = "this is my car" remoteExec ["hint", 0, car]; or _netId = "this is my car" remoteExec ["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 remoteExec 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:remoteExec ["", car]; or remoteExec ["", 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.
ⓘ
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.
⚠
There could be only one JIP message with the same JIP ID in the JIP queue. This means that if one tries to remoteExec again with the existing JIP ID, the JIP message which is already in the JIP queue will be overwritten. Passing true for JIP param autogenerates unique ID, therefore adding new message in the JIP queue each time. All other options have potential to overwrite existing JIP message.
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" remoteExec ["hint"];
Example 2:
// runs hint "hello" on first connected client "hello" remoteExec ["hint", 3];
Example 3:
// runs hint "hello" everywhere but server "hello" remoteExec ["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" remoteExec ["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" remoteExec ["hint", -2, "some_JIP_ID"];
Example 6:
// runs "someFuncWithNoArgs" on each connected client remoteExec ["someFuncWithNoArgs"];
Example 7:
// removes a message identified by "IamUnique" from the JIP queue remoteExec ["", "IamUnique"];
Example 8:
// all clients will have their ammo set to 1 for their current weapon {player setAmmo [primaryWeapon player, 1];} remoteExec ["bis_fnc_call", 0];
Example 9:
// Object obj will have its ammo set to 1 where it is local [obj,[primaryWeapon obj, 1]] remoteExec ["setAmmo", obj];
Example 10:
myJipID = "hello" remoteExec ["", 0]; if (isNil "myJipID") then { hint "empty function name is not allowed"; };

Additional Information

See also:
remoteExecCall remoteExecutedOwner isRemoteExecuted isRemoteExecutedJIP Arma 3: Remote Execution canSuspend BIS_fnc_MP

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 December 29, 2015 - 20:28 (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 March 24, 2016 - 14:09 (UTC)
R3vo
The INCORRECT way to call reveal command on a certain object for every player: [player, _desired_object] remoteExec ["reveal", 0]; In this case player object will be the object obtained on the computer where remoteExec is initiated. If it is dedicated server, player will be objNull, if it is client, player would be player object on this client. In any case this will not reveal _desired_object for all connected players.

The CORRECT way: [_desired_object, {player reveal _this}] remoteExec ["call", 0]; The _desired_object will be identical on every client, this is what we want, but player will refer to individual player on each client, so _desired_object will be revealed to all connected players.
Posted on May 25, 2016 - 18:23 (UTC)
Killzone Kid
When adapting mission from dedicated server for SP, if target used in remoteExec is -2 (execute on every client but not server), in SP this will not execute since client is server in SP. To work around, the target could be set using isMultiplayer condition like this: "123" remoteExec ["hint", [0, -2] select isMultiplayer]; This will execute hint on every client in MP on dedicated server (target -2) and will also execute it in SP (target 0).
Posted on May 28, 2016 - 20:51 (UTC)
R3vo
While KK's solution works fine in sp missions and on dedicated servers, it will not work properly for hosted missions.
Solution: [0,0.5] remoteExec ['fadeRadio',[0,-2] select isDedicated,true];
Singleplayer: isDedicated returns false -> code is executed everywhere (0)
Hosted: isDedicated returns false -> code is executed everywhere including host (0)
Dedicated: isDedicated returns true -> code is executed everywhere excluding server(-2)
Posted on Jan 30, 2017 - 18:35 (UTC)
Pierre MGI
[some params] remoteExec ['some command',2,true]; will fail, as you can't use JIP and remoteExec on server only
[some params] remoteExec ['some command',2]; // works
Posted on May 10, 2017 - 20:10 (UTC)
Killzone Kid
To remoteExec: titleText ["Test Message", "PLAIN", 1]; Use [["Test Message", "PLAIN", 1]] remoteExec ["titleText"];
Posted on April 22, 2018 - 15:29 (UTC)
KC Grimes
It seems that only global functions can be executed, as opposed to local. <params> remoteExec ["fnc_someScriptedFunction", targets, JIP]; //Works
<params> remoteExec ["_fnc_someScriptedFunction", targets, JIP]; //Does not work
Retrieved from "https://community.bistudio.com/wiki?title=remoteExec&oldid=250588"