Difference between revisions of "Multiplayer Scripting"

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Change obsolete network functions description)
m (Fix 1)
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{SideTOC|0.9}}
 
{{SideTOC|0.9}}
{{Stub}}
 
  
This page aims to explain notions and specificities of [[Multiplayer Scripting]] and its differences with Singleplayer Scripting.<br />
+
This page aims to explain notions and specificities of [[Multiplayer Scripting]] and its differences with Singleplayer Scripting.<br>
 
It features three parts:
 
It features three parts:
 
# [[#Notions and general knowledge|Notions and general knowledge]]
 
# [[#Notions and general knowledge|Notions and general knowledge]]
Line 13: Line 12:
 
== The basics ==
 
== The basics ==
  
 +
<div style="float: right">[[File:network client-server.png|thumb|Client-Server relationship]]</div>
 
* In Multiplayer, players are connected to a '''server'''.
 
* In Multiplayer, players are connected to a '''server'''.
 
** The server is a machine that distributes information among clients, such as unit positions, vehicle speeds, etc.
 
** The server is a machine that distributes information among clients, such as unit positions, vehicle speeds, etc.
Line 18: Line 18:
 
* A machine connected to a server is called a '''client'''.
 
* A machine connected to a server is called a '''client'''.
 
** Clients can join a mission ''after'' it started: they are considered "[[Join In Progress|JIP]]" and scripting should be adapted to them. See the [[#Join In Progress|Join In Progress]] chapter for more information.
 
** Clients can join a mission ''after'' it started: they are considered "[[Join In Progress|JIP]]" and scripting should be adapted to them. See the [[#Join In Progress|Join In Progress]] chapter for more information.
 +
<br>
  
{{Informative|In Singleplayer, the game acts as a player-hosted server ({{Inline code|[[isServer]]}} returns {{Inline code|[[true]]}}).}}
+
{{Informative | In Singleplayer, the game acts as a player-hosted server ({{Inline code|[[isServer]]}} returns {{Inline code|[[true]]}}).}}
{{Warning|Some Multiplayer commands do '''not''' work in Singleplayer, such as {{Inline code|[[netId]]}} !<br />
+
{{Warning | Some Multiplayer commands do '''not''' work in Singleplayer, such as {{Inline code|[[netId]]}} !<br>
 
The other way around, some Singleplayer commands do not work in Multiplayer (e.g  {{Inline code|[[setAccTime]]}}).}}
 
The other way around, some Singleplayer commands do not work in Multiplayer (e.g  {{Inline code|[[setAccTime]]}}).}}
  
Line 27: Line 28:
  
 
=== Definitions ===
 
=== Definitions ===
* '''LOCAL''' is an attribute for the machine where the command/script/function is executed.
+
 
 +
* '''LOCAL''' is an attribute for the machine where the command/script/function is executed or the AI calculated.
 
** to check if an argument is local, use the [[local]] command
 
** to check if an argument is local, use the [[local]] command
* '''REMOTE''' means '''non local'''. All player-controlled soldiers are remote units to a dedicated server, for example.
+
* '''REMOTE''' means '''non local''' - on another machine. All player-controlled soldiers are remote units to a dedicated server, for example.
 
** to check if an argument is remote, simply use {{Inline code|[[not]] [[local]] ''myObject''}}
 
** to check if an argument is remote, simply use {{Inline code|[[not]] [[local]] ''myObject''}}
 
* [[:Category:Scripting_Commands|commands]] arguments and effects can be either '''local''' or '''global''':
 
* [[:Category:Scripting_Commands|commands]] arguments and effects can be either '''local''' or '''global''':
 
{|
 
{|
|style="padding-right: 0.5em;"|{{EffArg|cmd|arg|local}}
+
| style="padding-right: 0.5em;" | {{EffArg|cmd|arg|local}}
|a '''local''' argument means an argument that is processed on the machine where the command is executed
+
| a '''local''' argument means an argument that is processed on the machine where the command is executed
 
|-
 
|-
|{{EffArg|cmd|arg|global}}
+
| {{EffArg|cmd|arg|global}}
|a '''global''' argument means any argument, even a remote one
+
| a '''global''' argument means any argument, even a remote one
 
|-
 
|-
|{{EffArg|cmd|eff|local}}
+
| {{EffArg|cmd|eff|local}}
|a '''local''' effect means that the effect will only happen on the machine where the command is executed
+
| a '''local''' effect means that the effect will only happen on the machine where the command is executed
 
|-
 
|-
|{{EffArg|cmd|eff|global}}
+
| {{EffArg|cmd|eff|global}}
|a '''global''' effect means that all the computers will receive it
+
| a '''global''' effect means that all the computers will receive it
 
|}
 
|}
See [[Locality in Multiplayer]] for more information.
 
  
 
=== Different machines and how to target them ===
 
=== Different machines and how to target them ===
{|class="bikitable" style="text-align: center"
+
 
 +
{| class="bikitable" style="text-align: center"
 
|+ Valid for {{arma3}}
 
|+ Valid for {{arma3}}
!Machine
+
! Machine
!Conditions
+
! Conditions
!Is server
+
! Is server
!Is player
+
! Is player
!Is JIP
+
! Is JIP
 
|-
 
|-
|Dedicated Server
+
| Dedicated Server
|<code>[[isDedicated]]</code>
+
| <code>[[isDedicated]]</code>
|{{task/}}
+
| {{task/}}
|{{task}}
+
| {{task}}
|{{task}}
+
| {{task}}
 
|-
 
|-
|Player Server
+
| Player Server
|<code>[[hasInterface]] && [[isServer]]</code>
+
| <code>[[hasInterface]] && [[isServer]]</code>
|{{task/}}
+
| {{task/}}
|{{task/}}
+
| {{task/}}
|{{task}}
+
| {{task}}
 
|-
 
|-
|Player Client
+
| Player Client
|<code>[[hasInterface]] && not [[isServer]]</code>
+
| <code>[[hasInterface]] && not [[isServer]]</code>
|{{task}}
+
| {{task}}
|{{task/}}
+
| {{task/}}
|{{task}}
+
| {{task}}
 
|-
 
|-
|[[Join In Progress|JIP]] Player Client
+
| [[Join In Progress|JIP]] Player Client
|<code>[[hasInterface]] && [[didJIP]]</code>
+
| <code>[[hasInterface]] && [[didJIP]]</code>
|{{task}}
+
| {{task}}
|{{task/}}
+
| {{task/}}
|{{task/}}
+
| {{task/}}
 
|-
 
|-
|[[Arma 3 Headless Client|Headless Client]]
+
| [[Arma 3 Headless Client|Headless Client]]
|<code>not [[hasInterface]] && not [[isServer]]</code>
+
| <code>not [[hasInterface]] && not [[isServer]]</code>
|{{task}}
+
| {{task}}
|{{task}}
+
| {{task}}
|{{task}}
+
| {{task}}
 
|-
 
|-
|JIP Headless Client
+
| JIP Headless Client
|<code>not [[hasInterface]] && not [[isServer]] && [[didJIP]]</code>
+
| <code>not [[hasInterface]] && not [[isServer]] && [[didJIP]]</code>
|{{task}}
+
| {{task}}
|{{task}}
+
| {{task}}
|{{task/}}
+
| {{task/}}
 
|}
 
|}
'''For an extended version for all games, click "Show text"'''
+
'''For an extended version for all games, click''' <spoiler>
<spoiler>
+
{{Informative | Before {{GVI|ofp|1.99}} and [[isServer]], server could be detected by placing a [[Game Logic]] in the editor that would remain local to the server, then using the following:<code>[[local]] myLogic</code>}}
{|class="bikitable" style="line-height: normal; text-align: center"
+
 
!Targeted machine
+
 
!{{ofp}}
+
{| class="bikitable" style="line-height: normal; text-align: center"
!{{arma}}
+
! Targeted machine
!{{arma2}}
+
! {{ofp}}
!{{arma3}}
+
! Arma 1
 +
! {{arma2}}
 +
! {{arma3}}
 
|-
 
|-
!'''Dedicated Server'''<br />
+
! '''Dedicated Server'''<br><small>A server without a human player behind it</small>
<small>A server without a human player behind it</small>
+
| [[isServer]] && [[isNull]] [[player]]
|[[local]] myLogic && [[isNull]] [[player]]
+
| [[isServer]] && [[isNull]] [[player]]
|[[isServer]] && [[player]] != [[player]]
+
| [[isDedicated]]
|[[isDedicated]]
+
| [[isDedicated]]
|[[isDedicated]]
 
 
|-
 
|-
!'''Player Server'''<br />
+
! '''Player Server'''<br><small>A server hosted by a player</small>
<small>A server hosted by a player</small>
+
| [[isServer]] && [[not]] [[isNull]] [[player]]
|[[local]] myLogic && [[not]] [[isNull]] [[player]]
+
| [[isServer]] && [[not]] [[isNull]] [[player]]
|[[isServer]] && [[not]] [[isDedicated]]
+
| [[isServer]] && [[not]] [[isDedicated]]
|[[isServer]] && [[not]] [[isDedicated]]
+
| [[hasInterface]] && [[isServer]]
|[[hasInterface]] && [[isServer]]
 
 
|-
 
|-
!'''Server'''<br />
+
! '''Server'''<br><small>Any server, dedicated or hosted</small>
<small>Any server, dedicated or hosted</small>
+
| [[isServer]]
|[[local]] myLogic
+
| [[isServer]]
|[[isServer]]
+
| [[isServer]]
|[[isServer]]
+
| [[isServer]]
|[[isServer]]
 
 
|-
 
|-
<!--
+
! '''Player Client'''<br><small>A player connected since the lobby</small>
!'''Player-controller machine'''<br />
+
| [[not]] [[isServer]] && [[not]] [[isNull]] [[player]]
<small>Any machine controlled '''with''' a human player behind it</small>
+
| [[not]] [[isServer]] && [[not]] [[isNull]] [[player]]
|[[not]] [[isNull]] [[player]]
+
| [[not]] [[isServer]] && [[not]] [[isNull]] [[player]]
|[[not]] [[isNull]] [[player]]
+
| [[hasInterface]] && [[not]] [[isServer]]
|[[not]] [[isNull]] [[player]]
 
|[[hasInterface]]
 
 
|-
 
|-
-->
+
! '''JIP Player Client'''<br><small>A player connected in the middle of a mission</small>
!'''Player Client'''<br />
+
| {{n/a}}
<small>A player connected since the lobby</small>
+
| [[not]] [[isServer]] && [[isNull]] [[player]]
|[[not]] [[local]] myLogic && [[not]] [[isNull]] [[player]]
+
| [[not]] [[isServer]] && [[isNull]] [[player]]
|[[not]] [[isServer]] && [[not]] [[isNull]] [[player]]
+
| [[hasInterface]] && [[didJIP]]
|[[not]] [[isServer]] && [[not]] [[isNull]] [[player]]
 
|[[hasInterface]] && [[not]] [[isServer]]
 
 
|-
 
|-
!'''JIP Client'''<br />
+
! '''Headless Client'''<br><small>A client without a human player behind it<br>(used to offload server calculations)</small>
<small>A player connected in the middle of a mission</small>
+
| colspan="3" {{n/a}}
|''N/A''
+
| [[not]] [[hasInterface]] && [[not]] [[isServer]]
|[[not]] [[isServer]] && [[isNull]] [[player]]
 
|[[not]] [[isServer]] && [[isNull]] [[player]]
 
|[[hasInterface]] && [[didJIP]]
 
 
|-
 
|-
!'''Headless Client'''<br />
+
! '''JIP Headless Client'''<br><small>Headless client connected during the ongoing mission</small>
<small>A client without a human player behind it<br />
+
| colspan="3" {{n/a}}
(used to offload server calculations)</small>
+
| [[not]] [[hasInterface]] && [[not]] [[isServer]] && [[didJIP]]
|colspan="3"|''N/A''
 
|[[not]] [[hasInterface]] && [[not]] [[isServer]]
 
|-
 
!'''JIP Headless Client'''<br />
 
<small>Headless client connected during the ongoing mission</small>
 
|colspan="3"|''N/A''
 
|[[not]] [[hasInterface]] && [[not]] [[isServer]] && [[didJIP]]
 
 
|}
 
|}
 
</spoiler>
 
</spoiler>
Line 160: Line 147:
 
* If you want to know if the current machine is a server (Dedicated Server or Player Server), use {{Inline code|[[isServer]]}}.
 
* If you want to know if the current machine is a server (Dedicated Server or Player Server), use {{Inline code|[[isServer]]}}.
 
* If you want to know if the current machine has a player (Player Server included), use {{Inline code|[[hasInterface]]}}.
 
* If you want to know if the current machine has a player (Player Server included), use {{Inline code|[[hasInterface]]}}.
 +
 
{{Feature arma3|Since {{arma3}}, a server-only init file is available: '''initServer.sqf''' (see [[Event Scripts]])}}
 
{{Feature arma3|Since {{arma3}}, a server-only init file is available: '''initServer.sqf''' (see [[Event Scripts]])}}
 +
 +
{{Feature arma3 | '''[[BIS_fnc_getNetMode]]''' can be used to have a string value representing the local machine status ("DedicatedServer", "Server", "HeadlessClient", "Client", "SinglePlayer" ).<br>
 +
This function doesn't make the JIP distinction and should be used along [[didJIP]].}}
  
 
=== General information about locality ===
 
=== General information about locality ===
 +
 
* about [[player]]:
 
* about [[player]]:
 
** a [[player]]'s unit is '''always''' local to the (human) player's machine
 
** a [[player]]'s unit is '''always''' local to the (human) player's machine
Line 179: Line 171:
  
 
=== Locality changes ===
 
=== Locality changes ===
 +
 
* if the player-leader dies, the AI is transferred to the machine where the new leader is local (server in case of AI, client in case of another player)
 
* if the player-leader dies, the AI is transferred to the machine where the new leader is local (server in case of AI, client in case of another player)
 
* [[join|joining]] AI units will change locality to the new leader's computer
 
* [[join|joining]] AI units will change locality to the new leader's computer
 
* locality will change from server to client when a player gets in an empty vehicle
 
* locality will change from server to client when a player gets in an empty vehicle
 
* locality can also change in the event of a [[Team Switch]] or usage of [[selectPlayer]]
 
* locality can also change in the event of a [[Team Switch]] or usage of [[selectPlayer]]
{{Informative|Since {{arma3}} the [[Arma 3: Event Handlers#Local|"Local" Event Handler]] triggers when an object's locality is changed.}}
+
{{Feature arma3|Since {{arma3}} the [[Arma 3: Event Handlers#Local|"Local" Event Handler]] triggers when an object's locality is changed.}}
  
 
=== Code examples ===
 
=== Code examples ===
{|class="bikitable"
+
 
!Code
+
{| class="bikitable"
!Argu-ments
+
! Code
!Effect
+
! Argu-ments
!Description
+
! Effect
 +
! Description
 
|-
 
|-
|<code>remoteUnit [[setDamage]] 1;</code>
+
| <code>remoteUnit [[setDamage]] 1;</code>
|align="center"|{{EffArg|cmd|arg|global}}
+
| align="center" | {{EffArg|cmd|arg|global}}
|align="center"|{{EffArg|cmd|eff|global}}
+
| align="center" | {{EffArg|cmd|eff|global}}
|Any unit (local or remote) will die, and all the computers will know
+
| Any unit (local or remote) will die, and all the computers will know
 
|-
 
|-
|<code>localUnit [[addMagazine]] "30Rnd_556x45_STANAG";</code>
+
| <code>localUnit [[addMagazine]] "30Rnd_556x45_STANAG";</code>
|align="center"|{{EffArg|cmd|arg|local}}
+
| align="center" | {{EffArg|cmd|arg|local}}
|align="center"|{{EffArg|cmd|eff|global}}
+
| align="center" | {{EffArg|cmd|eff|global}}
|Only a local unit can have its inventory edited with this command, but all the machines will be notified: if a player looks into the ''localUnit'' inventory, the added magazine will be there
+
| Only a local unit can have its inventory edited with this command, but all the machines will be notified: if a player looks into the ''localUnit'' inventory, the added magazine will be there
 
|-
 
|-
|<code>remoteUnit [[setFace]] "Miller";</code>
+
| <code>remoteUnit [[setFace]] "Miller";</code>
|align="center"|{{EffArg|cmd|arg|global}}
+
| align="center" | {{EffArg|cmd|arg|global}}
|align="center"|{{EffArg|cmd|eff|local}}
+
| align="center" | {{EffArg|cmd|eff|local}}
|Any unit (local or remote) can get its face changed, but the new face will not be propagated through the network. Only the local machine's player will see the effect of the command
+
| Any unit (local or remote) can get its face changed, but the new face will not be propagated through the network. Only the local machine's player will see the effect of the command
{{Informative|This command should ideally be '''executed on every machine''', for example with:
+
{{Informative | This command should ideally be '''executed on every machine''', for example with:
 
  [remoteUnit, "Miller"] [[remoteExec]] ["setFace", 0, true];
 
  [remoteUnit, "Miller"] [[remoteExec]] ["setFace", 0, true];
 
See [[#Remote Execution|Remote Execution]] paragraph for more information.}}
 
See [[#Remote Execution|Remote Execution]] paragraph for more information.}}
 
|-
 
|-
|<code>localCamera [[cameraEffect]] ["Internal", "Back"];</code>
+
| <code>localCamera [[cameraEffect]] ["Internal", "Back"];</code>
|align="center"|{{EffArg|cmd|arg|local}}
+
| align="center" | {{EffArg|cmd|arg|local}}
|align="center"|{{EffArg|cmd|eff|local}}
+
| align="center" | {{EffArg|cmd|eff|local}}
|Only a local camera can be entered, and of course only the local machine will see through this camera
+
| Only a local camera can be entered, and of course only the local machine will see through this camera
 
|}
 
|}
  
Line 220: Line 214:
  
 
Network IDs identify machines and network objects. They can be used to target proper machines with remote execution; see [[#Remote Execution|Remote Execution]] chapter for more information.
 
Network IDs identify machines and network objects. They can be used to target proper machines with remote execution; see [[#Remote Execution|Remote Execution]] chapter for more information.
{{Warning|'''A machine ID''' ([[owner|ownerID]]) is not to be confused with '''an object's network ID''' ([[netId]]).}}
+
{{Warning | '''A machine ID''' ([[owner|ownerID]]) is not to be confused with '''an object's network ID''' ([[netId]]).}}
  
 
=== Machine network ID ===
 
=== Machine network ID ===
Every machine, including the server, has a '''network ID'''.<br />
+
 
A server has an ID of '''2''', every new client has the next number (the first client will be number '''3''', second client number '''4''', etc.)
+
Every machine, including the server, has a '''network ID'''.<br>
 +
A server always has an ID of '''2''', every new client has the next number (the first client will be number '''3''', second client number '''4''', etc.)
 
* To get the current machine's ID, use [[clientOwner]].
 
* To get the current machine's ID, use [[clientOwner]].
 
* To get the machine's ID of an object's owner, use [[owner]] ''object''  (MP only).
 
* To get the machine's ID of an object's owner, use [[owner]] ''object''  (MP only).
 
* To get the machine's ID of a group's owner, use [[groupOwner]] ''object'' (MP only).
 
* To get the machine's ID of a group's owner, use [[groupOwner]] ''object'' (MP only).
<!--
+
 
TODO: confirm this information
+
{{Informative | '''0''' and '''1''' are special values:
{{Important|A client disconnecting and reconnecting to the same server will keep its network ID, even if other clients connected in the meantime!}}
+
* '''0''' means '''everyone''' (including the server)
-->
+
* '''1''' means '''current machine''' but '''{{Color|darkred|is not implemented}}''' and should '''not''' be used.}}
  
 
=== Object network ID ===
 
=== Object network ID ===
 +
 
Every object synchronised through the network has a network ID, shortened to '''netId'''.
 
Every object synchronised through the network has a network ID, shortened to '''netId'''.
 
* To get an object's netId, use [[netId]] (MP only). '''SP &amp; MP variant:''' [[BIS_fnc_netId]]
 
* To get an object's netId, use [[netId]] (MP only). '''SP &amp; MP variant:''' [[BIS_fnc_netId]]
Line 249: Line 245:
  
 
{{arma3}} alpha introduced [[BIS_fnc_MP]] ('''obsolete''' since {{arma3}} v1.50, use the above version):
 
{{arma3}} alpha introduced [[BIS_fnc_MP]] ('''obsolete''' since {{arma3}} v1.50, use the above version):
  ["Message to everyone, including JIP  players!", "hint", true, true] call BIS_fnc_MP;  {{codecomment|// obsolete since {{arma3}} v1.50, use [[remoteExec]] or [[remoteExecCall]]}}
+
  ["Message to everyone, including JIP  players!", "hint", true, true] call BIS_fnc_MP;  {{cc|obsolete since {{arma3}} v1.50, use [[remoteExec]] or [[remoteExecCall]]}}
  
 
{{arma2}} introduced the [[Multiplayer framework]] (not present in {{arma3}}):
 
{{arma2}} introduced the [[Multiplayer framework]] (not present in {{arma3}}):
  {{codecomment|// Having the Functions module placed in the editor}}
+
  {{cc|having the Functions module placed in the editor}}
 
  waitUntil { not isNil "BIS_MPF_InitDone"; };
 
  waitUntil { not isNil "BIS_MPF_InitDone"; };
 
  [nil, nil, rHINT, "Message to everyone!"] call RE;
 
  [nil, nil, rHINT, "Message to everyone!"] call RE;
  
 
=== PublicVariable commands ===
 
=== PublicVariable commands ===
 +
 
PublicVariable commands allow to send '''global''' variables to specified machines.
 
PublicVariable commands allow to send '''global''' variables to specified machines.
 
* Network reception is guaranteed
 
* Network reception is guaranteed
 
* Short variable names should be used for network performance
 
* Short variable names should be used for network performance
 
* These commands shouldn't be used intensely for the same reason
 
* These commands shouldn't be used intensely for the same reason
{|class="bikitable"
+
{| class="bikitable"
!Command
+
! Command
!Effect
+
! Effect
![[Join In Progress|JIP]] synchronised
+
! [[Join In Progress|JIP]] synchronised
 
|-
 
|-
|[[publicVariable]]
+
| [[publicVariable]]
|Set/update a variable value from the local machine to all the other machines (including server)
+
| Set/update a variable value from the local machine to all the other machines (including server)
|align="center"|{{task/}}
+
| align="center" | {{task/}}
 
|-
 
|-
|[[publicVariableServer]]
+
| [[publicVariableServer]]
|Set/update a variable value '''from a client to the server'''
+
| Set/update a variable value '''from a client to the server'''
|align="center"|{{task}}
+
| align="center" | {{task}}
 
|-
 
|-
|[[publicVariableClient]]
+
| [[publicVariableClient]]
|Set/update a variable value '''from the local machine''' (not necessarily the server) '''to a specific client'''
+
| Set/update a variable value '''from the local machine''' (not necessarily the server) '''to a specific client'''
|align="center"|{{task}}
+
| align="center" | {{task}}
 
|}
 
|}
  
 
==== How it works ====
 
==== How it works ====
 
The server has the variable {{Inline code|ABC_Score}} to broadcast:
 
The server has the variable {{Inline code|ABC_Score}} to broadcast:
  ABC_Score = 5; {{codecomment|// sets the value}}
+
  ABC_Score = 5; {{cc|sets the value}}
  [[publicVariable]] "ABC_Score" {{codecomment|// publishes the variable (do not forget the quotes!)}}
+
  [[publicVariable]] "ABC_Score" {{cc|publishes the variable (do not forget the quotes!)}}
 
This sends the variable name and value to the clients.
 
This sends the variable name and value to the clients.
 
* If the variable is not yet declared on their machine, it will declare it as well.
 
* If the variable is not yet declared on their machine, it will declare it as well.
Line 291: Line 288:
  
 
=== setVariable command ===
 
=== setVariable command ===
Available since {{arma2}} the '''public''' version of the [[setVariable]] command allows you to store a variable into an object and spread this variable across the network.
+
 
 +
Available since {{arma2}}, the '''public''' version of the [[setVariable]] command (alternative syntax) allows you to store a variable into an object and spread this variable across the network.
 
{{Feature arma3|In {{arma3}} it is possible to broadcast the [[nil]] value, thus deleting the variable from the target.}}
 
{{Feature arma3|In {{arma3}} it is possible to broadcast the [[nil]] value, thus deleting the variable from the target.}}
  
Line 300: Line 298:
 
* [[Arma 3: Event Handlers/addMissionEventHandler#PlayerConnected|"PlayerConnected" mission Event Handler]]
 
* [[Arma 3: Event Handlers/addMissionEventHandler#PlayerConnected|"PlayerConnected" mission Event Handler]]
 
* [[Arma 3: Event Handlers/addMissionEventHandler#PlayerDisconnected|"PlayerDisconnected" mission Event Handler]]
 
* [[Arma 3: Event Handlers/addMissionEventHandler#PlayerDisconnected|"PlayerDisconnected" mission Event Handler]]
{{Informative|Before {{arma3}} v1.57, use [[BIS_fnc_addStackedEventHandler]] for [[onPlayerConnected]]/[[onPlayerDisconnected]].}}
+
{{Informative | Before {{arma3}} v1.57, use [[BIS_fnc_addStackedEventHandler]] for [[onPlayerConnected]]/[[onPlayerDisconnected]].}}
  
  
Line 306: Line 304:
  
 
A client state is the client's connection state. It can be obtained with [[getClientState]] and [[getClientStateNumber]] commands on both server and clients.
 
A client state is the client's connection state. It can be obtained with [[getClientState]] and [[getClientStateNumber]] commands on both server and clients.
{|class="bikitable"
+
{| class="bikitable"
![[getClientStateNumber]]
+
! [[getClientStateNumber]]
![[getClientState]]
+
! [[getClientState]]
!Description
+
! Description
 
|-
 
|-
|0
+
| 0
|"NONE"
+
| "NONE"
|No client (or singleplayer)
+
| No client (or singleplayer)
 
|-
 
|-
|1
+
| 1
|"CREATED"
+
| "CREATED"
|Client is created
+
| Client is created
 
|-
 
|-
|2
+
| 2
|"CONNECTED"
+
| "CONNECTED"
|Client is connected to server, message formats are registered
+
| Client is connected to server, message formats are registered
 
|-
 
|-
 
|3
 
|3
|"LOGGED IN"
+
| "LOGGED IN"
|Identity is created
+
| Identity is created
 
|-
 
|-
|4
+
| 4
|"MISSION SELECTED"
+
| "MISSION SELECTED"
|Mission is selected
+
| Mission is selected
 
|-
 
|-
|5
+
| 5
|"MISSION ASKED"
+
| "MISSION ASKED"
|Server was asked to send / not send mission
+
| Server was asked to send / not send mission
 
|-
 
|-
|6
+
| 6
|"ROLE ASSIGNED"
+
| "ROLE ASSIGNED"
|Role was assigned (and confirmed)
+
| Role was assigned (and confirmed)
 
|-
 
|-
|7
+
| 7
|"MISSION RECEIVED"
+
| "MISSION RECEIVED"
|Mission received
+
| Mission received
 
|-
 
|-
|8
+
| 8
|"GAME LOADED"
+
| "GAME LOADED"
|Island loaded, vehicles received
+
| Island loaded, vehicles received
 
|-
 
|-
|9
+
| 9
|"BRIEFING SHOWN"
+
| "BRIEFING SHOWN"
|Briefing was displayed
+
| Briefing was displayed
 
|-
 
|-
|10
+
| 10
|"BRIEFING READ"
+
| "BRIEFING READ"
|Ready to play mission
+
| Ready to play mission
 
|-
 
|-
|11
+
| 11
|"GAME FINISHED"
+
| "GAME FINISHED"
|Game was finished
+
| Game was finished
 
|-
 
|-
|12
+
| 12
|"DEBRIEFING READ"
+
| "DEBRIEFING READ"
|Debriefing read, ready to continue with next mission
+
| Debriefing read, ready to continue with next mission
 
|}
 
|}
  
Line 367: Line 365:
 
== Join In Progress ==
 
== Join In Progress ==
  
A [[Join In Progress|JIP]] player will have many information synchronised by the game before accessing the mission itself. JIP was introduced in [[{{arma}}]].
+
A [[Join In Progress|JIP]] player will have many information synchronised ([[publicVariable]]'d and [[setVariable]] server variables for example) by the game before accessing the mission itself. JIP was introduced in [[:Category:{{ofpe}}|{{ofpe}}]] on XBox and [[{{arma}}]] on PC.
{|class="bikitable"
+
{| class="bikitable"
!Information
+
! Information
!Arma 1
+
! Arma 1
!{{arma2}}
+
! {{arma2}}
!{{arma3}}
+
! {{arma3}}
 
|-
 
|-
|date/time
+
| date/time
|align="center"|{{task/}}
+
| align="center" | {{task/}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
 
|-
 
|-
|date/time + [[setDate]]/[[skipTime]]
+
| date/time + [[setDate]]/[[skipTime]]
|align="center"|{{task}}
+
| align="center" | {{task}}
|align="center"|{{task}}
+
| align="center" | {{task}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
 
|-
 
|-
|weather ([[overcast]], [[fog]])
+
| weather ([[overcast]], [[fog]])
|align="center"|{{task}}
+
| align="center" | {{task}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
 
|-
 
|-
|weather + [[setOvercast]]/[[setFog]]/[[setRain]]/[[setLightnings]]
+
| weather + [[setOvercast]]/[[setFog]]/[[setRain]]/[[setLightnings]]
|align="center"|{{task}}
+
| align="center" | {{task}}
|align="center"|{{task}}
+
| align="center" | {{task}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
 
|-
 
|-
|time passed since mission start ([[time]] command)
+
| time passed since mission start ([[time]] command)
|align="center"|''unknown''
+
| align="center" | ''unknown''
|align="center"|''unknown''
+
| align="center" | ''unknown''
|align="center"|{{task/}}
+
| align="center" | {{task/}}
 
|-
 
|-
|[[publicVariable]]-sent variables ([[Number]], [[String]], [[Text]], [[Array]], [[Code]])
+
| [[publicVariable]]-sent variables ([[Number]], [[String]], [[Text]], [[Array]], [[Code]])
|align="center"|{{task/}}
+
| align="center" | {{task/}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
 
|-
 
|-
|[[publicVariable]]-sent variables ([[nil]])
+
| [[publicVariable]]-sent variables ([[nil]])
|align="center"|{{task}}
+
| align="center" | {{task}}
|align="center"|{{task}}
+
| align="center" | {{task}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
 
|-
 
|-
|[[setVariable]]-assigned variables (when alternative syntax's ''public'' parameter is set to true)
+
| [[setVariable]]-assigned variables (when alternative syntax's ''public'' parameter is set to true)
|align="center"|''N/A''
+
| {{n/a}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
|align="center"|{{task/}}
+
| align="center" | {{task/}}
 
|-
 
|-
|[[remoteExec]]- and [[remoteExecCall]]-executed code if ''JIP'' prerequisites are met
+
| [[remoteExec]]- and [[remoteExecCall]]-executed code if ''JIP'' prerequisites are met
|align="center"|''N/A''
+
| colspan="2" {{n/a}}
|align="center"|''N/A''
+
| align="center" | {{task/}}
|align="center"|{{task/}}
 
 
|}
 
|}
See [[Join In Progress]] for more information.
+
See also [[Join In Progress]].
 +
{{Warning | All the '''initialisation fields''' code get executed again for '''each and every JIP connecting player'''.<br>
 +
This means that code with global effect {{EffArg|cmd|eff|global}} (such as [[setDamage]]) '''WILL''' be re-executed (depending on locality)!}}
  
  
Line 425: Line 424:
  
 
* [[Arma 3 Headless Client|Headless Client]]
 
* [[Arma 3 Headless Client|Headless Client]]
* [[Locality in Multiplayer]]
 
 
* [[:Category:Commands by effects and arguments locality|Commands by effects and arguments locality]]
 
* [[:Category:Commands by effects and arguments locality|Commands by effects and arguments locality]]
 
** [[:Category:Commands requiring server side execution|Server-only commands]]
 
** [[:Category:Commands requiring server side execution|Server-only commands]]
Line 434: Line 432:
 
= Structuring Multiplayer code =
 
= Structuring Multiplayer code =
  
{{wip}}
 
  
 +
== Responsibilities ==
  
== Responsibilities ==
+
* The '''server''' initialises and works with '''variables'''
 +
* A connecting or connected '''player-client''' gets the mission data from the server
 +
* Once an objective is reached, '''the server tells the players''' ''via'' [[remoteExec]]/[[remoteExecCall]], [[publicVariable]] or [[setVariable]]
 +
* Players can get their client-side UI code triggered by the server
 +
See [[#Different machines and how to target them|earlier chapter]] about how to target specific machines.
  
 
=== Server ===
 
=== Server ===
The '''Server''' must be considered as the one ruler of the mission. He is the game's referee and all the decisions should come from it. All the values on the server should be considered as '''true'''.<br />
+
 
 +
The '''Server''' must be considered as the one ruler of the mission. He is the game's referee and all the decisions should come from it. All the values on the server should be considered as '''true'''.<br>
 
Consider the server as a powerful machine where you can put all the mission conditions and heavy scripting on.
 
Consider the server as a powerful machine where you can put all the mission conditions and heavy scripting on.
 
In case of a very heavy mission, the server can be assisted by [[Arma 3 Headless Client|Headless Clients]] (this involves a per-mission specific design).
 
In case of a very heavy mission, the server can be assisted by [[Arma 3 Headless Client|Headless Clients]] (this involves a per-mission specific design).
  
 
Server-side code must gather or wait all the variables (potentially from client-side scripts and [[publicVariableServer]]) and take and broadcast its decisions accordingly using [[publicVariable]].
 
Server-side code must gather or wait all the variables (potentially from client-side scripts and [[publicVariableServer]]) and take and broadcast its decisions accordingly using [[publicVariable]].
 +
 +
Server-side code should ideally '''not''' make any reference to a [[player]] variable considering a server can potentially be '''dedicated''', unless you want to force this mission to be player-hosted (such as {{arma2}}'s campaign).
 +
{{Informative | Use [[allPlayers]], [[BIS_fnc_listPlayers]], [[playableUnits]] (and [[switchableUnits]] for SP compatibility) to refer to players.}}
  
 
=== Client ===
 
=== Client ===
 +
 
The '''Client''' must be considered as an average machine that can leave the game at any moment.
 
The '''Client''' must be considered as an average machine that can leave the game at any moment.
'''No mission-vital code must be executed on its side''' and '''no decisions must be taken client-side'''.<br />
+
'''No mission-vital code must be executed on its side''' and '''no decisions must be taken client-side'''.<br>
 
Again, '''one must expect that any client can disconnect at any moment'''.
 
Again, '''one must expect that any client can disconnect at any moment'''.
  
The client executes all the (local) UI code ([[Post process effects]], [[Dialog Control|Dialogs]], etc.)
+
The client executes all the (local) UI code ([[Post process effects]], [[Arma: GUI Configuration|Dialogs]], etc.)<br>
 +
The player's machine should not deal with a great piece of code.
 +
{{Important | Do not forget that a server '''can''' be a player, and therefore should execute player code in that case.}}
 +
The proper way to check for player-side condition is
 +
[[if]] ([[hasInterface]]) [[then]] { (…) };
 +
Note that the following example is '''incorrect''':
 +
[[if]] ([[isServer]]) [[then]]
 +
{
 +
(…)
 +
}
 +
  else {{cc|'''WRONG:''' a server CAN be a player}}
 +
{
 +
(…)
 +
};
 +
 
 +
 
 +
== Code writing ==
 +
 
 +
The usual four steps of coding are the following:
 +
* Think it well
 +
** If you cannot figure out how to write your code, say what you want to do out loud or write it down in your language, then replace it by code little by little.
 +
* Make it work
 +
** use the [[Arma 3 Startup Parameters#Developer Options|-showScriptErrors]] startup parameter to see your code errors.
 +
* Make it readable
 +
** name your variables properly, as if you had to give it to someone that should get it without the need of explaining
 +
* Optimise then
 +
** use more performance-friendly commands, reduce your search radius and loop frequencies once everything works.
 +
 
 +
See [[Code Optimisation#Rules|Code Optimisation - Rules]] for advices and more information.
  
  
Line 461: Line 496:
  
 
= Testing locally =
 
= Testing locally =
 +
  
 
To properly test MP scripting locality issues, it is recommended to run a '''dedicated server''' and connect with '''two''' clients. In order to do so:
 
To properly test MP scripting locality issues, it is recommended to run a '''dedicated server''' and connect with '''two''' clients. In order to do so:
 
* In your arma3server.exe's [[server.cfg]]:
 
* In your arma3server.exe's [[server.cfg]]:
 
<syntaxhighlight lang="cpp">
 
<syntaxhighlight lang="cpp">
loopback = true; // force LAN-only server
+
loopback = true; // force LAN-only server
kickDuplicate = 0; // disable duplicate Arma kick
+
kickDuplicate = 0; // disable duplicate Arma kick
  
// needed in case of Headless Client test only
+
// needed in case of Headless Client test only
headlessClients[] = { "127.0.0.1" };
+
headlessClients[] = { "127.0.0.1" };
localClient[] = { "127.0.0.1" };
+
localClient[] = { "127.0.0.1" };
 
</syntaxhighlight>
 
</syntaxhighlight>
 
* Run Arma 3 twice from Steam and connect each (with {{Inline code|-showScriptErrors}} flag)
 
* Run Arma 3 twice from Steam and connect each (with {{Inline code|-showScriptErrors}} flag)
** If you use one screen for the first client and the other screen for the second client, use {{Inline code|-noPause -window}} launcher options. This will not pause render if the window doesn't have focus.
+
** If you use one screen for the first client and the other screen for the second client, use {{Inline code|-noPause -window}} launcher options. This will not pause render if the window doesn't have focus.<!--
 +
-->{{Important | Be sure to disable [[BattlEye]] or it will close any additional instances.}}
 
* Try your mission and check for script errors:
 
* Try your mission and check for script errors:
 
** on client's screens and [[arma.RPT|RPT files]]
 
** on client's screens and [[arma.RPT|RPT files]]
Line 482: Line 519:
 
** in a Dedicated Server-hosted game
 
** in a Dedicated Server-hosted game
  
{{Informative|Of course, nothing prevents you to invite friends to play your mission and report bugs!}}
+
{{Informative | Of course, nothing prevents you to invite friends to play your mission and report bugs!}}
  
  

Revision as of 11:05, 18 June 2020

This page aims to explain notions and specificities of Multiplayer Scripting and its differences with Singleplayer Scripting.
It features three parts:

  1. Notions and general knowledge
  2. Structuring Multiplayer code
  3. Testing locally


Notions and general knowledge

The basics

Client-Server relationship
  • In Multiplayer, players are connected to a server.
    • The server is a machine that distributes information among clients, such as unit positions, vehicle speeds, etc.
    • The server can be either a dedicated machine, or hosted by a player; in the latter it means the server can have a player unit.
  • A machine connected to a server is called a client.
    • Clients can join a mission after it started: they are considered "JIP" and scripting should be adapted to them. See the Join In Progress chapter for more information.


In Singleplayer, the game acts as a player-hosted server (isServer returns true).
Some Multiplayer commands do not work in Singleplayer, such as netId !
The other way around, some Singleplayer commands do not work in Multiplayer (e.g setAccTime).


Locality

Definitions

  • LOCAL is an attribute for the machine where the command/script/function is executed or the AI calculated.
    • to check if an argument is local, use the local command
  • REMOTE means non local - on another machine. All player-controlled soldiers are remote units to a dedicated server, for example.
    • to check if an argument is remote, simply use not local myObject
  • commands arguments and effects can be either local or global:
Arguments of this scripting command have to be local to the client the command is executed on a local argument means an argument that is processed on the machine where the command is executed
Arguments of this scripting command don't have to be local to the client the command is executed on a global argument means any argument, even a remote one
Effects of this scripting command are not broadcasted over the network and remain local to the client the command is executed on a local effect means that the effect will only happen on the machine where the command is executed
Effects of this scripting command are broadcasted over the network and happen on every computer in the network a global effect means that all the computers will receive it

Different machines and how to target them

Valid for Arma 3
Machine Conditions Is server Is player Is JIP
Dedicated Server isDedicated Ico ok.png Ico none.png Ico none.png
Player Server hasInterface && isServer Ico ok.png Ico ok.png Ico none.png
Player Client hasInterface && not isServer Ico none.png Ico ok.png Ico none.png
JIP Player Client hasInterface && didJIP Ico none.png Ico ok.png Ico ok.png
Headless Client not hasInterface && not isServer Ico none.png Ico none.png Ico none.png
JIP Headless Client not hasInterface && not isServer && didJIP Ico none.png Ico none.png Ico ok.png

For an extended version for all games, click Show text


  • If you want to know if the current machine is a server (Dedicated Server or Player Server), use isServer.
  • If you want to know if the current machine has a player (Player Server included), use hasInterface.
Arma 3 logo black.png
Since Arma 3, a server-only init file is available: initServer.sqf (see Event Scripts)
Arma 3 logo black.png
BIS_fnc_getNetMode can be used to have a string value representing the local machine status ("DedicatedServer", "Server", "HeadlessClient", "Client", "SinglePlayer" ).
This function doesn't make the JIP distinction and should be used along didJIP.

General information about locality

  • about player:
    • a player's unit is always local to the (human) player's machine
    • a dedicated server doesn't have a player unit (isNull player returns true)
    • to know if a certain unit is a player, use isPlayer
  • groups and AI:
    • an AI group with a player-leader will be local to the player's computer
    • a subordinate player being in a player-lead group will remain local to its computer (see bulletpoint #1)
  • objects:
    • a driven vehicle is always local to the machine of its driver (not the commander's, not the gunner's)
    • terrain objects (buildings, vegetation, roads etc.) are local everywhere (local nearestBuilding player returns true on every client)
    • editor-placed objects and empty vehicles are local to the server
    • editor-placed triggers are created on every machine unless specified otherwise ("Server Only" Eden Editor option ticked)
    • units created with createUnit will be local to the computer that issued the command
    • objects and vehicles created with createVehicle will be local to the computer that issued the command

Locality changes

  • if the player-leader dies, the AI is transferred to the machine where the new leader is local (server in case of AI, client in case of another player)
  • joining AI units will change locality to the new leader's computer
  • locality will change from server to client when a player gets in an empty vehicle
  • locality can also change in the event of a Team Switch or usage of selectPlayer
Arma 3 logo black.png
Since Arma 3 the "Local" Event Handler triggers when an object's locality is changed.

Code examples

Code Argu-ments Effect Description
remoteUnit setDamage 1; Arguments of this scripting command don't have to be local to the client the command is executed on Effects of this scripting command are broadcasted over the network and happen on every computer in the network Any unit (local or remote) will die, and all the computers will know
localUnit addMagazine "30Rnd_556x45_STANAG"; Arguments of this scripting command have to be local to the client the command is executed on Effects of this scripting command are broadcasted over the network and happen on every computer in the network Only a local unit can have its inventory edited with this command, but all the machines will be notified: if a player looks into the localUnit inventory, the added magazine will be there
remoteUnit setFace "Miller"; Arguments of this scripting command don't have to be local to the client the command is executed on Effects of this scripting command are not broadcasted over the network and remain local to the client the command is executed on Any unit (local or remote) can get its face changed, but the new face will not be propagated through the network. Only the local machine's player will see the effect of the command
This command should ideally be executed on every machine, for example with:
[remoteUnit, "Miller"] remoteExec ["setFace", 0, true];
See Remote Execution paragraph for more information.
localCamera cameraEffect ["Internal", "Back"]; Arguments of this scripting command have to be local to the client the command is executed on Effects of this scripting command are not broadcasted over the network and remain local to the client the command is executed on Only a local camera can be entered, and of course only the local machine will see through this camera


Network ID

Network IDs identify machines and network objects. They can be used to target proper machines with remote execution; see Remote Execution chapter for more information.

A machine ID (ownerID) is not to be confused with an object's network ID (netId).

Machine network ID

Every machine, including the server, has a network ID.
A server always has an ID of 2, every new client has the next number (the first client will be number 3, second client number 4, etc.)

  • To get the current machine's ID, use clientOwner.
  • To get the machine's ID of an object's owner, use owner object (MP only).
  • To get the machine's ID of a group's owner, use groupOwner object (MP only).
0 and 1 are special values:
  • 0 means everyone (including the server)
  • 1 means current machine but is not implemented and should not be used.

Object network ID

Every object synchronised through the network has a network ID, shortened to netId.


Sending information across network

Remote Execution

Since Arma 3 v1.50, remoteExec and remoteExecCall efficient engine network commands are available:

["Message to everyone, including JIP players!", 0, true] remoteExec ["hint"];

See Arma 3 Remote Execution for more information.

Arma 3 alpha introduced BIS_fnc_MP (obsolete since Arma 3 v1.50, use the above version):

["Message to everyone, including JIP  players!", "hint", true, true] call BIS_fnc_MP;  // obsolete since Arma 3 v1.50, use remoteExec or remoteExecCall

Arma 2 introduced the Multiplayer framework (not present in Arma 3):

// having the Functions module placed in the editor
waitUntil { not isNil "BIS_MPF_InitDone"; };
[nil, nil, rHINT, "Message to everyone!"] call RE;

PublicVariable commands

PublicVariable commands allow to send global variables to specified machines.

  • Network reception is guaranteed
  • Short variable names should be used for network performance
  • These commands shouldn't be used intensely for the same reason
Command Effect JIP synchronised
publicVariable Set/update a variable value from the local machine to all the other machines (including server) Ico ok.png
publicVariableServer Set/update a variable value from a client to the server Ico none.png
publicVariableClient Set/update a variable value from the local machine (not necessarily the server) to a specific client Ico none.png

How it works

The server has the variable ABC_Score to broadcast:

ABC_Score = 5;				// sets the value
publicVariable "ABC_Score"	// publishes the variable (do not forget the quotes!)

This sends the variable name and value to the clients.

  • If the variable is not yet declared on their machine, it will declare it as well.
  • If the variable already exists, the value is overridden by the server's value.
  • If the variable changes again on the server, it has to be manually publicVariable'd once again!
  • A JIP player will synchronise server's publicVariable'd variables before executing init.sqf. See Initialization Order for more information.
    • A JIP player will not synchronise publicVariableClient-received variables after he disconnects/reconnects. Only server-known public variables sent with publicVariable will be synchronised.

setVariable command

Available since Arma 2, the public version of the setVariable command (alternative syntax) allows you to store a variable into an object and spread this variable across the network.

Arma 3 logo black.png
In Arma 3 it is possible to broadcast the nil value, thus deleting the variable from the target.


Player connection events

The following commands will execute given code when a player is connecting or disconnecting. This code will run for players connecting in the lobby and for JIP players!


Client state

A client state is the client's connection state. It can be obtained with getClientState and getClientStateNumber commands on both server and clients.

getClientStateNumber getClientState Description
0 "NONE" No client (or singleplayer)
1 "CREATED" Client is created
2 "CONNECTED" Client is connected to server, message formats are registered
3 "LOGGED IN" Identity is created
4 "MISSION SELECTED" Mission is selected
5 "MISSION ASKED" Server was asked to send / not send mission
6 "ROLE ASSIGNED" Role was assigned (and confirmed)
7 "MISSION RECEIVED" Mission received
8 "GAME LOADED" Island loaded, vehicles received
9 "BRIEFING SHOWN" Briefing was displayed
10 "BRIEFING READ" Ready to play mission
11 "GAME FINISHED" Game was finished
12 "DEBRIEFING READ" Debriefing read, ready to continue with next mission


Join In Progress

A JIP player will have many information synchronised (publicVariable'd and setVariable server variables for example) by the game before accessing the mission itself. JIP was introduced in Operation Flashpoint: Elite on XBox and Armed Assault on PC.

Information Arma 1 Arma 2 Arma 3
date/time Ico ok.png Ico ok.png Ico ok.png
date/time + setDate/skipTime Ico none.png Ico none.png Ico ok.png
weather (overcast, fog) Ico none.png Ico ok.png Ico ok.png
weather + setOvercast/setFog/setRain/setLightnings Ico none.png Ico none.png Ico ok.png
time passed since mission start (time command) unknown unknown Ico ok.png
publicVariable-sent variables (Number, String, Text, Array, Code) Ico ok.png Ico ok.png Ico ok.png
publicVariable-sent variables (nil) Ico none.png Ico none.png Ico ok.png
setVariable-assigned variables (when alternative syntax's public parameter is set to true) N/A Ico ok.png Ico ok.png
remoteExec- and remoteExecCall-executed code if JIP prerequisites are met N/A Ico ok.png

See also Join In Progress.

All the initialisation fields code get executed again for each and every JIP connecting player.
This means that code with global effect Effects of this scripting command are broadcasted over the network and happen on every computer in the network (such as setDamage) WILL be re-executed (depending on locality)!


See also


Structuring Multiplayer code

Responsibilities

  • The server initialises and works with variables
  • A connecting or connected player-client gets the mission data from the server
  • Once an objective is reached, the server tells the players via remoteExec/remoteExecCall, publicVariable or setVariable
  • Players can get their client-side UI code triggered by the server

See earlier chapter about how to target specific machines.

Server

The Server must be considered as the one ruler of the mission. He is the game's referee and all the decisions should come from it. All the values on the server should be considered as true.
Consider the server as a powerful machine where you can put all the mission conditions and heavy scripting on. In case of a very heavy mission, the server can be assisted by Headless Clients (this involves a per-mission specific design).

Server-side code must gather or wait all the variables (potentially from client-side scripts and publicVariableServer) and take and broadcast its decisions accordingly using publicVariable.

Server-side code should ideally not make any reference to a player variable considering a server can potentially be dedicated, unless you want to force this mission to be player-hosted (such as Arma 2's campaign).

Use allPlayers, BIS_fnc_listPlayers, playableUnits (and switchableUnits for SP compatibility) to refer to players.

Client

The Client must be considered as an average machine that can leave the game at any moment. No mission-vital code must be executed on its side and no decisions must be taken client-side.
Again, one must expect that any client can disconnect at any moment.

The client executes all the (local) UI code (Post process effects, Dialogs, etc.)
The player's machine should not deal with a great piece of code.

Do not forget that a server can be a player, and therefore should execute player code in that case.

The proper way to check for player-side condition is

if (hasInterface) then { (…) };

Note that the following example is incorrect:

if (isServer) then
{
	(…)
}
 else // WRONG: a server CAN be a player
{
	(…)
};


Code writing

The usual four steps of coding are the following:

  • Think it well
    • If you cannot figure out how to write your code, say what you want to do out loud or write it down in your language, then replace it by code little by little.
  • Make it work
  • Make it readable
    • name your variables properly, as if you had to give it to someone that should get it without the need of explaining
  • Optimise then
    • use more performance-friendly commands, reduce your search radius and loop frequencies once everything works.

See Code Optimisation - Rules for advices and more information.


See also


Testing locally

To properly test MP scripting locality issues, it is recommended to run a dedicated server and connect with two clients. In order to do so:

loopback = true;	// force LAN-only server
kickDuplicate = 0;	// disable duplicate Arma kick

// needed in case of Headless Client test only
headlessClients[]	= { "127.0.0.1" };
localClient[]		= { "127.0.0.1" };
  • Run Arma 3 twice from Steam and connect each (with -showScriptErrors flag)
    • If you use one screen for the first client and the other screen for the second client, use -noPause -window launcher options. This will not pause render if the window doesn't have focus.
      Be sure to disable BattlEye or it will close any additional instances.
  • Try your mission and check for script errors:
  • To ensure all cases, your mission should ideally work properly:
    • in Singleplayer
    • in Player-hosted Multiplayer
    • in a Dedicated Server-hosted game
Of course, nothing prevents you to invite friends to play your mission and report bugs!


See Also