Multiplayer Scripting

From Bohemia Interactive Community
Revision as of 21:16, 28 January 2019 by Lou Montana (talk | contribs) (Page creation)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Template:Informative Template:SideTOC Template:Stub

The basics

  • In Multiplayer, players are connected to a server that distributes information among them.
  • 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.
  • Players 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.

Template:Informative Template:Warning


Locality

Definitions

  • LOCAL is an attribute for the machine where the command/script/function is executed.
    • to check if a unit is local, use the local command
  • REMOTE means non local. All players 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 unit, 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

See Locality in Multiplayer for more information.

Different machines

Machine Conditions
Dedicated Server Template:Inline code
Player Server Template:Inline code
Client Template:Inline code
JIP Client Template:Inline code
Headless Client Template:Inline code
  • If you want to know if the current machine is a server (Dedicated Server or Player Server), use Template:Inline code.
  • If you want to know if the current machine has a player (Player Server included), use Template:Inline code.

Template:Warning

General information about locality

  • a player's unit is always local to the player's machine.
  • 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)
  • a driven vehicle is always local to its driver (not the commander, not the gunner)
    • terrain objects (buildings, vegetation, roads etc.) are local everywhere (Template:Inline code 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 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
  • a driver gets in an empty vehicle, locality will change from server to player
  • locality can also change in the event of a ||Team Switch]] or usage of selectPlayer

Code examples

Code Argu-ments Effect Description
Template:Inline code Template:EffArg Template:EffArg Any unit (local or remote) will die, and all the computers will know
Template:Inline code 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
Template:Inline code 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

Template:Informative

Template:Inline code 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. Template:Warning

Machine network ID

Every machine, including the server, has a network ID.
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.)

  • 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).

Template:Important

Mission object ID

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


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
publicVariable Set/update a variable value from the local machine to all the other machines (including server)
publicVariableServer Set/update a variable value from a client to the server
publicVariableClient Set/update a variable value from the local machine (not necessarily the server) to a specific client

Template:Important

How it works

The server has the variable Template:Inline code to send to everyone. It sets the variable value with Template:Inline code, it then uses Template:Inline code (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 public 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.


Remote Execution

Arma 2 introduced the (now obsolete) Multiplayer framework, used as follow:

waitUntil{ not isNil "BIS_MPF_InitDone"; };
[nil, nil, rHINT, "Message to everyone!"] call RE;

Arma 3 alpha introduced BIS_fnc_MP:

["Message to everyone, including JIP  players!", "hint", true, true] call BIS_fnc_MP;

Template:Warning


Arma 3 (> v1.50):

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

See Arma 3 Remote Execution for more information.


onPlayerConnected/onPlayerDisconnected events

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

Template:Informative


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 by the game. JIP was introduced in Arma.

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 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 N/A Template:task/

See Join In Progress for more information.


See also