Multiplayer Scripting – Arma Reforger
biki>Lou Montana (Add JIP definition) |
Lou Montana (talk | contribs) m (1 revision imported) |
(No difference)
| |
Revision as of 10:03, 18 May 2022
Multiplayer Scripting in Enfusion is based on Replication - it determines which machine does what in a situation.
When a Prefab entity is created on the server (and has a replication node set to broadcast), it is replicated on other network machines for them to see a representation of this object. This created representation is called a proxy – more information below.
Network
The Arma Reforger network architecture is a classical one with one server to which clients connect. Clients do not communicate between each others, they communicate with the server which redistributes data.
Server
The Server is the core network machine: it is the central system that receives and redistributes network information. There is only one server per multiplayer game, and the multiplayer game is destroyed if the server loses connection (server role does not get transferred).
Client
A Client is a machine that is connected to the server. A client is everything else that is not the server.
Join in Progress
A client can join after a game has started (even leave and join again) depending on the scenario. Such client is known as JIP, standing for Join in Progress.
Replication
Replication (shortened as RPL) is the name of the system used to replicate an entity or effect on all the concerned machines. For example, when a grenade explodes the damage is calculated on the server, whereas the visual effect is broadcast (replicated) to all the clients.
Remote Procedure Call (shortened as RPC) is the system allowing to queue network messages on other machines.
Preamble
The network structure is based on server-client relationship; Scripting and RPC Replication methods, on the other hand, should be oriented towards Roles - code should be written on authority role principle, server-client principle should be avoided:
- is the entity present on this machine the Authority?
- if not, the local entity is a Proxy
- if so, is it an Owner entity?
See the next chapters for further explanations.
Entity Role
When an entity gets created on a network machine, this entity is the Authority and this role is set in stone; it can never get changed or transferred.
If the network machine is the server, the entity's existence is broadcast to other network machines; the authority (server's entity) is represented on each client by locally-created entities named Proxies (local representation of the authority's reference).
- For an entity created on the server:
- the server hosts the authority entity
- the entity is replicated as proxy on other machines
- ownership can be given and taken by the authority
- For an entity created on a client:
- the client hosts the authority entity
- the server being unaware of it, the entity is not replicated on any network machine
Authority
The Authority is the reference entity.
All mission objects belong to the server; the server has almost if not all the authority entities.
Proxy
A Proxy is an entity that represents an authority on another machine; it only receives entity updates from the authority and cannot send network updates about it - unless the machine has been designated owner (see below).
Owner
An Owner is a special entity role that comes in addition to an authority or a proxy. An owner entity is the entity that has minor rights on the entity such as owner-specific methods. Only one machine can own an entity. The server can be an owner, and ownership can be transferred by the authority.
A client owner is only a machine with an "elevated" proxy access, being able to use RPC methods about this entity towards the authority (and only towards the authority).
Ownership behaviour example:
- a machinegun car exists on the server; the server is hosting the authority and is the owner of it
- a player enters the car as the driver; the host (the server) gives car's ownership to the player's machine, which becomes the owner of the car
- another player enters the car's machinegun; the host (still and always the server) gives machinegun's ownership to this player's machine, which becomes the owner of the car's machinegun entity
- the server keeps authority of this car and its machinegun - it is the one that overrides all clients' positions/states
- when said players leave their respective entities, the server takes ownership back
RPC Call
An RPC call is an entity method's call through the network, e.g from the authority to its proxies (on other machines). Specific targets can be defined, such as "all proxies" or "owner only".
Join In Progress
Join In Progress is the fact of having a client that connects to the server while a multiplayer game is already running.
Streaming
An entity is not always present on all machines. Streaming is the way of saving network and CPU process by only sending relevant entities' information.
Relevance
Relevance is a value decided authority-side by the engine that sets whether or not a proxy should be streamed to a network machine or not, in order to save network messages and CPU cycles.
A simple example would be a car that is five kilometres away from a player is not relevant to that player; so the proxy on this player's machine is deleted by the replication system automatically, and re-created/synchronised again when it becomes relevant (e.g close-by) again.
Special Cases
The authority always exists, as it is the reference entity for replication.
The owner entity is always present on its machine; it is never unloaded/reloaded depending on relevance unless ownership is taken away.
Broadcast
An RPC call with broadcast as a target will send the message on machines that have said entity present on their system; as seen above, a proxy owner entity is guaranteed to exist on
Operations Order
Current loading order:
| Order | Operation |
|---|---|
| 1 | entity hierarchy creation |
| 2 | RplLoad operations |
| 3 | member variable values in unguaranteed order
triggering their respective {hl|onRplName}} methods |
Code
Entity methods get executed with the Rpc method using their RplRpc attribute to determine the targets.
Rpc Method
The Rpc method (present in both GenericEntity and GenericComponent) is the starting point to trigger a network-friendly code call.
Rpc(Rpc_MyMethod, parameter1, parameter2);
The engine will make it so that this method will call the provided one where it needs to be, depending on the RplRpc target method attribute.
By convention, methods that can be called through replication are prefixed with the Rpc_ prefix: e.g Rpc_MyMethod().
the RpcAsk_ prefix is used by the owner to ask the authority to do an action (sender = owner, receiver = authority).
the RpcDo_ prefix is used by the authority to do an action (sender = authority, receiver = owner proxy or all proxies).
Usage
void Rpc(func method, void p0 = NULL, void p1 = NULL, void p2 = NULL, void p3 = NULL, void p4 = NULL, void p5 = NULL, void p6 = NULL, void p7 = NULL);
Network-wise, a method RPC is added to a list of "to do tasks"; it means that they might be sent separately, or all in one network packet. The order of the calls between two machines is however guaranteed.
RplRpc Attribute
The RplRpc attribute is to decorate an entity's method, allowing the engine to run said method on targeted machines through the Rpc method.
[RplRpc(RplChannel.Reliable, RplRcver.Owner)]
Usage
Here is RplRpc attribute's signature:
void RplRpc(RplChannel channel, RplRcver rcver, RplCondition condition = RplCondition.None, string customConditionName = "")
| Parameter | Usage | ||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| channel | RplChannel enum, can be one of:
| ||||||||||||||||||||||||||||||||||
| rcver (receiver) | RplRcver enum, can be one of:
| ||||||||||||||||||||||||||||||||||
| condition | RplCondition enum, can be one of:
| ||||||||||||||||||||||||||||||||||
| customConditionName | if condition has been set to Custom, customConditionName must be set to the name of the method to be checked. This method must return a bool.
Example: class RplClass
{
[RplProp(onRplName: "OnBroadcastValueUpdated", condition: RplCondition.Custom, customConditionName: "RpcConditionMethod")]
protected bool m_iBroadcastValue;
void OnBroadcastValueUpdated()
{
// this method will only run on proxies if authority's RpcConditionMethod returns true
}
[RplRpc(RplChannel.Reliable, RplRcver.Server)]
void RpcAsk_Method()
{
m_iBroadcastValue = 33;
Replication.BumpMe();
}
bool RpcConditionMethod()
{
return m_iBroadcastValue < 50;
}
}
| ||||||||||||||||||||||||||||||||||
= RPL call is processed over the network
= RPL call is abandoned
RplProp Attribute
The RplProp attribute is to decorate an object's property, allowing the engine to synchronise values on network machines.
Only a change on the authority and notifying the replication system with Replication.BumpMe() method will trigger a broadcast to other machines (see the BumpMe section).
Usage
Here is RplProp attribute's signature:
void RplProp(RplGroup group = RplGroup.Mandatory, string onRplName = "", ScriptCtx ctx = NULL, RplCondition condition = RplCondition.None, string customConditionName = "")
| Parameter | Usage |
|---|---|
| group | RplGroup enum, can be one of:
|
| onRplName | The method name to be called on proxies when the property's value is changed on the authority (and synchronised with Replication.BumpMe() method). |
| ctx | Script context - engine only, unused script-side |
| condition | RplCondition, can be one of:
|
| customConditionName | if condition has been set to Custom, customConditionName must be set to the name of the method to be checked. This method must return a bool.
Example: class RplClass
{
[RplProp(onRplName: "OnBroadcastValueUpdated", condition: RplCondition.Custom, customConditionName: "RpcConditionMethod")]
protected bool m_iBroadcastValue;
void OnBroadcastValueUpdated()
{
// this method will only run on proxies if authority's RpcConditionMethod returns true
}
[RplRpc(RplChannel.Reliable, RplRcver.Server)]
void RpcAsk_Method()
{
m_iBroadcastValue = 33;
Replication.BumpMe();
}
bool RpcConditionMethod()
{
return m_iBroadcastValue < 50;
}
}
|
RplSave/RplLoad
RplSave
RplSave is the method called on the authority's side to write custom synchronisation data.
RplLoad
RplLoad is the method called on the streamed entity after the entity, its components and the whole entities hierarchy to which it belongs has been loaded, if any.
It is called immediately after initialisation but before anything else (EOnFrame, etc).
Replication Class
The Replication class is a very useful Replication tool, holding the following methods (only the most used ones are listed here).
FindId
Return the provided entity's id. should be an RplId
If the entity does not have one, it returns Replication.INVALID_ID.
FindItem
Return the provided id's entity.
If no entities have the provided id, it returns null.
FindOwner
Return the owner machine's network id.
If the entity has no owner id, it returns Replication.INVALID_IDENTITY.
BumpMe
This method tells the Replication system that at least one property has been updated and that the change(s) should be broadcast.
Examples
For the sake of the examples, let's assume that:
- the server hosts the ComputerEntity authority entity
- a client hosts the owner entity
RplRpc
In the following code:
- the protected RpcAsk_Authority_Method method is set to be RPC-called on the authority
- the protected RpcDo_Owner_Method method is set to be RPC-called on the owner
- the protected RpcDo_Broadcast_Method method is set to be RPC-called on every proxy
We assume the public TurnOn method has been triggered owner-side, making the following events happen:
- the TurnOn method calls the RpcAsk_Authority_Method through RPC; as stated earlier, this method executes on the authority's machine - the server in this case
- the RpcAsk_Authority_Method method (running on the authority):
- prints "authority-side code" in the authority machine's logs
- calls the PlayMusic method on the authority
- calls the RpcDo_Broadcast_Method method on all the proxies (see below)
- calls the RpcDo_Owner_Method method on the owner's proxy (see below)
- the RpcDo_Broadcast_Method method (running on every proxy, including owner's):
- prints "proxy-side code" in proxy machines' logs
- calls the PlayMusic method on the proxy
- the RpcDo_Owner_Method method (running on the owner's proxy):
- prints "owner-side code"
The end result:
- all the machines' instances:
- called the PlayMusic method and played the "OSWelcome" music
- the authority's machine has
- "authority-side code" in the logs - had the server been the owner too, "owner-side code" would be present as well
- the owner's machine has
- "proxy-side code" then "owner-side code" in the logs (the order is guaranteed)
- all other machines have
- "proxy-side code" in the logs
class ComputerEntity : IEntity
{
protected bool m_bIsTurnedOn; // this value is edited only on authority's side
[RplRpc(RplChannel.Reliable, RplRcver.Server)]
protected void RpcAsk_Authority_Method(bool turningOn)
{
Print("authority-side code");
if (turningOn == m_bIsTurnedOn) // the authority has authority
{
return; // prevent useless network messages
}
m_bIsTurnedOn = turningOn;
PlayMusic(turnOn); // play music on authority
Rpc(RpcDo_Broadcast_Method, turningOn); // send the music broadcast request
Rpc(RpcDo_Owner_Method); // run specific code on the owner's entity (that may or may not be the authority)
}
[RplRpc(RplChannel.Reliable, RplRcver.Owner)]
protected void RpcDo_Owner_Method()
{
Print("owner-side code");
}
[RplRpc(RplChannel.Reliable, RplRcver.Broadcast)]
protected void RpcDo_Broadcast_Method(bool turningOn)
{
Print("proxy-side code");
PlayMusic(turningOn);
}
protected void PlayMusic(bool turningOn)
{
if (turningOn)
{
SomeSoundClass.PlayMusic(this, "OSWelcome");
}
else
{
SomeSoundClass.PlayMusic(this, "OSGoodbye");
}
}
// public methods
void TurnOn()
{
Rpc(RpcAsk_Authority_Method, true);
}
void TurnOff()
{
Rpc(RpcAsk_Authority_Method, false);
}
}
RplProp
In the following code:
- the m_bIsTurnedOn property is set to update to all the proxies on authority value's modification
- the m_bIsTurnedOn property is set to execute the OnTurnedOnUpdated method on proxies when its value is updated by Replication (JIP included)
We assume the public TurnOn method has been triggered owner-side, making the following events happen:
- the TurnOn method calls the RpcAsk_Authority_Method through RPC; as stated earlier, this method executes on the authority's machine - the server in this case
- the RpcAsk_Authority_Method method (running on the server):
- sets LED colour on the server
- sets the m_bIsTurnedOn property to "true" on the authority; as the m_bIsTurnedOn property is set to broadcast its changes thanks to the RplProp attribute, the change is broadcast to every proxy machine
- the OnTurnedOn method is triggered on proxies and "The proxy has been updated" is printed
The end result:
- all the machines' instances:
- have the m_bIsTurnedOn property set to "true"
- have their light set to green
- the authority:
- printed "authority-side code"
- all the proxies:
- printed "proxy-side code"
class ComputerEntity : IEntity
{
[RplProp(onRplName: "OnTurnedOnUpdated")]
protected bool m_bIsTurnedOn = false; // this value is to be updated by the authority, not set locally by proxies (even owner)
// if it is set locally, the change will not broadcast and there will be a difference between the proxy and the authority
// this state discrepancy will last until authority's next update broadcast
[RplRpc(RplChannel.Reliable, RplRcver.Server)]
protected void RpcAsk_Authority_Method(bool turningOn)
{
if (turningOn == m_bIsTurnedOn)
{
return; // prevent useless network messages
}
Print("authority-side code");
m_bIsTurnedOn = turningOn; // m_bIsTurnedOn is changed only in an authority-targeting method
// it will broadcast over the network automatically due to Replication setting (line 3)
SetLedLightColour(); // SetLedLightColour is not automatically called on the authority
Replication.BumpMe(); // tell the Replication system this entity has changes to be broadcast
// the Replication system will update the member variable AFTER RpcAsk_Authority_Method is done
}
protected void OnTurnedOnUpdated()
{
Print("proxy-side code"); // this method is called on proxies when m_bIsTurnedOn is updated through Replication
// it is NOT called on the authority
SetLedLightColour();
}
protected void SetLedLightColour()
{
if (m_bIsTurnedOn)
{
SomeLightClass.SetLedLightColour(this, Color.Green);
}
else
{
SomeLightClass.SetLedLightColour(this, Color.Red);
}
}
// public methods
void TurnOn()
{
if (m_bIsTurnedOn) // m_bIsTurnedOn can be read from any entity
{
return;
}
Rpc(RpcAsk_Authority_Method, true);
}
void TurnOff()
{
if (!m_bIsTurnedOn)
{
return;
}
Rpc(RpcAsk_Authority_Method, false);
}
}
RplSave/RplLoad
Without RplSave/RplLoad override, the following entity would be created with m_iSoldierId, m_iH ealth and m_bHadLunch set to their default value, as these are not decorated with RplProp.
class SCR_RplTestSoldier : IEntity
{
[RplProp()]
protected string m_sName = "Player 1"; // joining in progress automatically synchronises RplProp variables
protected int m_iSoldierId = 12345678;
protected int m_iHealth = 100; // range 0..100
protected bool m_bHadLunch = false;
protected string m_sSoldierDogTag = "PID 1234"; // let's assume length can change
// Called on the authority when an entity gets streamed
override bool RplSave(ScriptBitWriter writer)
{
// m_sName is automatically synchronised, no need to do it manually
writer.Write(m_iSoldierId, 32); // write 32 bits of soldier ID - int is 32 bits in size
writer.Write(m_iHealth, 7); // write 7 bits of health - 7 bits are enough if the value cannot go over 100 (7 bits range is 0..127)
writer.WriteBool(m_bHadLunch); // write 1 bit only
writer.WriteInt(m_sSoldierDogTag.Length()); // write following string's length as it can change
writer.Write(m_sSoldierDogTag, 8 * m_sSoldierDogTag.Length()); // one character is 1 byte (8 bits)
return true;
}
// Called on the streamed proxy
override bool RplLoad(ScriptBitReader reader)
{
// m_sName is automatically synchronised, no need to do it manually
if (!reader.Read(m_iSoldierId, 32)) // read 32 bits of data - the authority wrote soldier ID first, so it needs to be read first
{
return false;
}
if (!reader.Read(m_iHealth, 7)) // read 7 bits of data - the authority wrote health second, so it needs to be read second
{
return false;
}
if (!reader.ReadBool(m_bHadLunch)) // read 1 bit only
{
return false;
}
int dogTagLength;
if (!reader.ReadInt(dogTagLength)) // read string's length
{
return false;
}
m_sSoldierDogTag = ""; // string should be emptied before being filled otherwise it could be only partially updated, e.g
// old string = "PID 1234"
// new string = "a b c"
// result = "a b c234"
if (!reader.Read(m_sSoldierDogTag, dogTagLength)) // read the whole string
{
return false;
}
return true;
}
}
|}