Menu
Lumberyard
Developer Guide (Version 1.12)

Exposing an Entity to the Network

CryLua is deprecated and will be removed in a future version of Lumberyard.

Note

This page contains information on using Lua scripting to work with the legacy Entity system. These Lua scripts use the legacy script context. Starting with Lumberyard 1.8, Lua scripts use the new behavior context that replaces the legacy script context. Scripts that were written before the integration of the behavior context no longer work in Lumberyard versions 1.8 and later. For information on updating Lua code from legacy script context to the new behavior context, see the migration notes for Lumberyard 1.8. For information on using Lua with Lumberyard's new component entity system, see Writing Lua Scripts for the Component Entity System and the Network Binding section in particular.

A script entity can be a serialized value on the network. This approach is done by setting the values on the server and having them automatically synchronized on all the clients. It also makes it possible to invoke client/server RMI functions.

Keep in mind the following limitations:

  • There is no notification when a serialized value has changed.

  • Values are controlled on the server only, there is no way to set values on the client.

Exposing a Script Entity to CryNetwork

To define the network features of an entity, call the ScriptBind function Net.Expose(), as illustrated in the following code. This code is written inside a Lua script within the global space, rather than in a function.

Net.Expose { Class = DeathMatch, ClientMethods = { ClVictory = { RELIABLE_ORDERED, POST_ATTACH, ENTITYID, }, ClNoWinner = { RELIABLE_ORDERED, POST_ATTACH, }, ClClientConnect = { RELIABLE_UNORDERED, POST_ATTACH, STRING, BOOL }, ClClientDisconnect = { RELIABLE_UNORDERED, POST_ATTACH, STRING, }, ClClientEnteredGame = { RELIABLE_UNORDERED, POST_ATTACH, STRING, }, }, ServerMethods = { RequestRevive = { RELIABLE_UNORDERED, POST_ATTACH, ENTITYID, }, RequestSpectatorTarget = { RELIABLE_UNORDERED, POST_ATTACH, ENTITYID, INT8 }, }, ServerProperties = { busy = BOOL, }, };

RMI functions

The RMI function is defined in either the ClientMethods and ServerMethods tables passed to the Net.Expose() function.

Order flags:

  • UNRELIABLE_ORDERED

  • RELIABLE_ORDERED

  • RELIABLE_UNORDERED

The following descriptors control how the RMI is scheduled within the data serialization.

RMI attach flag Description
NO_ATTACH No special control (preferred)
PRE_ATTACH Call occurs before data serialized
POST_ATTACH Call occurs after the data serialized

The following example shows a function declaration:

function DeathMatch.Client:ClClientConnect(name, reconnect)

The following examples illustrate a function call:

self.allClients:ClVictory( winningPlayerId );
self.otherClients:ClClientConnect( channelId, player:GetName(), reconnect );
self.onClient:ClClientConnect( channelId, player:GetName(), reconnect );

See RMI Functions for more details.

Note

Note: Script networking doesn't have an equivalent to the dependent object RMIs.

ServerProperties table

The entity table also contains a ServerProperties table that indicates which properties need to be synchronized. This is also the place to define the variable type of the value.

Exposing a Script Entity to CryAction

In addition, you must create a game object in CryAction and bind the new game object to the network game session. The following example shows the code placed in the OnSpawn() function:

CryAction.CreateGameObjectForEntity(self.id); CryAction.BindGameObjectToNetwork(self.id);

You can also instruct the game object to receive a per-frame update callback, as in the following function call to CryAction:

CryAction.ForceGameObjectUpdate(self.id, true);

The script entity receive the OnUpdate() function callback of its Server table.

function Door.Server:OnUpdate(frameTime) -- some code end

Note

Adding update callback code to your script entity can decrease the performance of a game.