Multiplayer Scripting
This page aims to explain notions and specificities of Multiplayer Scripting and its differences with Singleplayer Scripting.
It features three parts:
Notions and general knowledge
The basics
- 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.
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.
- commands arguments and effects can be either local or global:
| Template:EffArg | a local argument means an argument that is processed on the machine where the command is executed |
| Template:EffArg | a global argument means any argument, even a remote one |
| Template:EffArg | a local effect means that the effect will only happen on the machine where the command is executed |
| Template:EffArg | a global effect means that all the computers will receive it |
Different machines and how to target them
| Machine | Conditions | Is server | Is player | Is JIP |
|---|---|---|---|---|
| Dedicated Server | isDedicated
|
Template:task/ | Template:task | Template:task |
| Player Server | hasInterface && isServer
|
Template:task/ | Template:task/ | Template:task |
| Player Client | hasInterface && not isServer
|
Template:task | Template:task/ | Template:task |
| JIP Player Client | hasInterface && didJIP
|
Template:task | Template:task/ | Template:task/ |
| Headless Client | not hasInterface && not isServer
|
Template:task | Template:task | Template:task |
| JIP Headless Client | not hasInterface && not isServer && didJIP
|
Template:task | Template:task | Template:task/ |
For an extended version for all games, click
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:local myLogic
| Targeted machine | Operation Flashpoint | Arma 1 | Arma 2 | Arma 3 |
|---|---|---|---|---|
| Dedicated Server A server without a human player behind it |
isServer && isNull player | isServer && isNull player | isDedicated | isDedicated |
| Player Server A server hosted by a player |
isServer && not isNull player | isServer && not isNull player | isServer && not isDedicated | hasInterface && isServer |
| Server Any server, dedicated or hosted |
isServer | isServer | isServer | isServer |
| Player Client A player connected since the lobby |
not isServer && not isNull player | not isServer && not isNull player | not isServer && not isNull player | hasInterface && not isServer |
| JIP Player Client A player connected in the middle of a mission |
N/A | not isServer && isNull player | not isServer && isNull player | hasInterface && didJIP |
| Headless Client A client without a human player behind it (used to offload server calculations) |
N/A | not hasInterface && not isServer | ||
| JIP Headless Client Headless client connected during the ongoing mission |
N/A | not hasInterface && not isServer && didJIP | ||
- 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.
This function doesn't make the JIP distinction and should be used along didJIP.
General information about locality
- about player:
- 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 playerreturns 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
Code examples
| Code | Argu-ments | Effect | Description |
|---|---|---|---|
remoteUnit setDamage 1;
|
Template:EffArg | Template:EffArg | Any unit (local or remote) will die, and all the computers will know |
localUnit addMagazine "30Rnd_556x45_STANAG";
|
Template:EffArg | Template:EffArg | 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";
|
Template:EffArg | Template:EffArg | 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 |
localCamera cameraEffect ["Internal", "Back"];
|
Template:EffArg | Template:EffArg | 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.
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 ID of an object's owner, use owner object (MP only).
- To get the machine ID of a group's owner, use groupOwner object (MP only).
Object network ID
Every object synchronised through the network has a network ID, shortened to netId.
- To get an object's netId, use netId (MP only). SP & MP variant: BIS_fnc_netId
- To get an object from a netId, use objectFromNetId (MP only). SP & MP variant: BIS_fnc_objectFromNetId
- To get a group from a netId, use groupFromNetId (MP only). SP & MP variant: BIS_fnc_groupFromNetId
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!" remoteExec ["hint", 0, true];
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) | Template:task/ |
| publicVariableServer | Set/update a variable value from a client to the server | Template:task |
| publicVariableClient | Set/update a variable value from the local machine (not necessarily the server) to a specific client | Template:task |
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.
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 Arma on PC.
| Information | Arma 1 | Arma 2 | Arma 3 |
|---|---|---|---|
| date/time | Template:task/ | Template:task/ | Template:task/ |
| date/time + setDate/skipTime | Template:task | Template:task | Template:task/ |
| weather (overcast, fog) | Template:task | Template:task/ | Template:task/ |
| weather + setOvercast/setFog/setRain/setLightnings | Template:task | Template:task | Template:task/ |
| time passed since mission start (time command) | unknown | unknown | Template:task/ |
| publicVariable-sent variables (Number, String, Text, Array, Code) | Template:task/ | Template:task/ | Template:task/ |
| publicVariable-sent variables (nil) | Template:task | Template:task | Template:task/ |
| setVariable-assigned variables (when alternative syntax's public parameter is set to true) | N/A | Template:task/ | Template:task/ |
| remoteExec- and remoteExecCall-executed code if JIP prerequisites are met | N/A | Template:task/ | |
See also Join In Progress.
See also
- Headless Client
- Commands by effects and arguments locality
- Initialization Order
- Arma 3 Remote Execution
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).
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.
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
- use the -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 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:
- In your arma3server.exe's server.cfg:
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
-showScriptErrorsflag)- If you use one screen for the first client and the other screen for the second client, use
-noPause -windowlauncher 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
- 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