Legacy:Replication Block

From Unreal Wiki, The Unreal Engine Documentation Site
Jump to navigation Jump to search

In UnrealScript Class Syntax, the replication block specifies which of the variables and/or functions declared in a class are replicated. It is optional and only variables and functions mentioned in this block are actually replicated. Variables of a class that aren't mentined are initialized with their default values on clients.

Syntax

replication
{
  reliable/unreliable if ( replication condition )
    identifiers;
}

Replication condition

The replication condition is a boolean expression which tells the engine when something should be replicated to a remote machine. You can use functions in this expression, but it really isn't recommended because it will slow things down and can cause undesireable results. Usually the expressions are simple and based around the replication properties listed below.

Identifiers

The identifiers part is a comma-separated list of variables or functions for replication. An identifier can appear only once in the whole replication block, so cannot have different replication properties based on some condition. You cannot override replication conditions like you can functions and states. This also applies to functions and properties that don't appear in the replication block and thus have an empty replication condition.

Reliable and Unreliable

Understanding this lets you optimize your network usage.

All replicated variables are reliable: They are all guaranteed to reach the client, even if they may arrive in the wrong order.

Note: Pawns have code that prevent them from appearing jumpy, although the effects of this can still be seen at times when the player bounces back and forth in a somewhat laggy game.....location updates are being received out of order.

Replicated functions exist in both reliable and unreliable forms:

A reliable function is guaranteed to reach the client. A reliable function is repeatedly sent over the network until the client acknowledges it. This can lead to a one second delay or more if it has to resend the message. Functions that are not called very frequently, and which will cause the user's experience to be unsatisfactory if missed, should be replicated reliably. BroadcastMessage and BroadcastLocalizedMessage, for example, are reliable to ensure that the user gets the message.

An unreliable function simply results in a network message being sent, then the server is done. This is a lot lighter on network and server resources but if the network is heavily loaded the call might not take place on the client. The client's update to the server about its position is replicated unreliably: Since the client sends these updates to the server every single tick (in ServerMove, if you're wondering), it does not matter if some of them never reach the server. Since each update is timestamped, the server knows which ones to discard if they are out of order due to lag. In this scenario, the server can be assured of getting updates from the client, while not requiring that they ALL be sent.

Since you don't want to bog down the network connection with reliable updates about where the client is looking or moving, unreliable is best in this situation. The server only needs to get most of them to work great.

Examples

Let's have a look at a typical replication block:

<uscript> replication {

 reliable if ( Role == ROLE_Authority )
   RemainingMinute, bStopCountDown, GameEndedComments,
   NumPlayers;
 reliable if ( bNetInitial && (Role==ROLE_Authority) )
   GameName, GameClass, bTeamGame, ServerName, ShortName, AdminName,
   AdminEmail, Region, MOTDLine1, MOTDLine2, 
   MOTDLine3, MOTDLine4,RemainingTime, ElapsedTime;

} </uscript>

This one defines two groups of replicated variables in the GameReplicationInfo (UT) class. Here you can already see the most important part of a replication condition, the actor's Role. Either the Role or the RemoteRole is always present in a replication condition.

Variables can only be replicated from the authorative version of an actor (i.e. from the server) to the clients. These replication conditions can become quite complex if it helps saving bandwidth, as this example from the Actor (UT2003) class shows:

<uscript>

 unreliable if ( (!bSkipActorPropertyReplication || bNetInitial) && bReplicateMovement
     && (((RemoteRole == ROLE_AutonomousProxy) && bNetInitial)
         || ((RemoteRole == ROLE_SimulatedProxy) && (bNetInitial || bUpdateSimulatedPosition)
             && ((Base == None) || Base.bWorldGeometry))
         || ((RemoteRole == ROLE_DumbProxy) && ((Base == None) || Base.bWorldGeometry))) )
   Location;

</uscript>

So whether the location of an actor is replicated depends on the actor's RemoteRole and whether bReplicateMovement is True. The bSkipActorPropertyReplication can be used to cut down replication of actor class variables to only the initial replication.

Useful Replication Properties

Variables only valid during replication

bClientDemoNetFunc 
True if we're client-side demo recording and this call originated from the remote.
bClientDemoRecording 
This machine is currently recording a clientside demo.
bDemoRecording 
This machine is currently recording a demo.
bNetInitial 
True during the first time all variables are replicated for this actor.
bNetOwner 
True when the replication target is this actor's Owner.

Only UT

bNetFeel 
Player collides with/feels it in network play.
bNetHear 
Player hears it in network play.
bNetSee 
Player sees it in network play.
bSimulatedPawn 
True if this is a Pawn (UT) and simulated proxy.

Only UT2003

bDemoOwner 
Demo recording driver owns this actor.
bNetDirty 
True when a property was changes since the last time it was replicated.
bNetRelevant 
Actor is currently relevant. Only valid server side and only when replicating variables.
bRepClientDemo 
The remote machine is currently recording a demo.
Level.ReplicationViewer 
during replication, set to the playercontroller to which actors are currently being replicated
Level.ReplicationViewTarget 
during replication, set to the viewtarget to which actors are currently being replicated

Other Useful Variables

In UT

bClientAnim 
If True, AmbientSound and animations are replicated also to the owning client.

In UT2003

These properties are used in the Actor class replication block.

bNoRepMesh 
Don't replicate the Mesh.
bReplicateAnimations 
Whether SimAnim should be replicated.
bReplicateInstigator 
Whether the Instigator should be replicated.
bReplicateMovement 
Whether properties relevant for movement like Location, Rotation, Velocity, etc. should be replicated. Unlike bSkipActorPropertyReplication this also affects the initial replication.
bSkipActorPropertyReplication 
Used by ReplicationInfo classes that don't need to know all the Actor class properties on the clients. When set to True only the initial replication replicates the Actor class properties.
bUpdateSimulatedPosition 
Whether the actor's Location, Rotation and Velocity should be updated for Simulated Proxies.

Related Topics

Discussion

VitalOverdose So are the first set of variables in the list only valid for ut2004?

EricBlade: I think lack of specific version means that they are valid for all versions..

Wormbo: You could have answered that question with a short search through the source code.

Vitaloverdose I thought it might need labling so the next person wouldnt have to.