GameSession - stingray.GameSession object reference - Stingray Lua API Reference
Description
The GameSession object is responsible for replicating and synchronizing game objects between the peers that participate in a networked game session.
You get a new game session by calling Network.create_game_session().
To the GameSession, a game object is just a table of fields (keys and values) identified by an ID. When you create a game object, you become its owner, and you get back an ID that you can use to manipulate the object. As owner, you can change the values of the object fields. The changes you make get replicated to all other peers. If you delete the object, that too gets replicated.
Game objects can have different types. Each type has its own set of keys and values, which you define in the .network_config data file.
Typically, game objects represent something in the game world, such as units, physical bodies, etc., but the GameSession layer does not care about that. It is the responsibility of the user to move data back and forth between the network game objects and the real world entities. The GameSession is responsible only for notifying other peers about changes to the state of the fields in the game objects.
Ownership of game objects can be moved between peers in the session. This can be used to set up network load balancing, or to get a better fidelity of the play experience (the owner of an object does not have to worry about lag or synchronization problems when interacting with it).
When a remote node has created, destroyed or migrated a game object, you get notified by a callback to the callback object that you provided to Network.update(). See the Network.update() description for details.
Replay Sessions
In development builds, you can replay a network game session by calling the Network.create_replay_session() function, and passing that function a network log file created during a previous game session. In a replay session, the GameSession object functions exactly as it did in the original game session -- it responds to all of the network events stored in the log file as if they were just executed by connected clients -- and you can call the same functions to control the game session. However, since the network events are all recorded, you can test and re-test exactly the same sequence of actions carried out by the remote peers. This may help you diagnose problems with your networked games.
The main difference between a regular game session and a replay session is that in a regular game session the network callback object is not notified of your own changes; however, in a replay session, the network callback object receives callback notifications of all game object changes, regardless of which peer initiated the action.
In addition, the synchronization state for peers does not exist in replay sessions, since you are only observing and not transmitting yourself.
Note that this feature is experimental.
Setting up a replay session
To create a replay session:
- Set up your game's settings.ini file to record network activity to a log file. For example:
network = {
log = "%APPDATA%\\Company\\Project\\network_dumps\\network-%DATE%-%TIME%-%RANDOM%.ndp"
}
Create a log by playing through a regular networked game session.
After closing the session, call Network.create_replay_session(log_filename) to create a replay session based on the events recorded in the network log file.
Play through the replay session, calling Network.update() every frame as usual.
When you are done, close the replay session by calling Network.shutdown_replay_session() instead of Network.shutdown_game_session().
Constructors and accessors 
Other related reference items
Host
Functions that can be called by the game session host.
 |
add_peer ( self, peer_id ) Adds the peer with the specified peer ID to the session.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
peer_id : | string | The ID of the peer you want to add to the session. |
| This function does not return any values. |
Only the session host can add peers.
Other related reference items
| |
make_game_session_host ( self )Makes this game instance the session host for the game session.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
| This function does not return any values. |
You can only call this on a session that was just created, and that has no other peers in it. The host of the session is the only one that can add peers to or remove peers from the session.
When you call this function, you automatically also join the session.
| |
remove_peer ( self, peer_id, callback_object )Removes the peer with the specified ID from the session.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
peer_id : | string | The ID of the peer you want to remove from the session. |
callback_object : | table | An object that will be notified through a callback function for each game object owned by the removed peer that is destroyed when the peer is removed. |
| This function does not return any values. |
Only the session host can remove peers.
Removing a peer may cause game objects owned by that peer to be destroyed. For each destroyed game object, the following function is called on the callback object you pass to this function.
- game_object_destroyed(id, destroyer_id)
Notifies you that the game object identified by id was destroyed by peer destroyer_id.
This is the same as the game_object_destroyed() callback function that can be invoked by Network.update(), so you may be able to use the same callback object you provide to the Network.update() function when you call GameSession.remove_peer().
| |
shutdown_game_session_host ( self )Called by the game session host to shut down the session and notify the peers.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
| This function does not return any values. |
Host migration
Functions that involve changes to the host.
| |
disconnect_from_host ( self )Disconnects this peer from the session host, if a communication error has occurred.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
| This function does not return any values. |
Note that unlike leave(), which attempts to inform the host that the peer is leaving the session, this call will leave the session without informing the host. Since it is intended to be called when there is a host error, there is no point in informing the host that we are leaving.
Note that just like with leave(), calling disconnect_from_host() is a request to be disconnected. The disconnect doesn't happen immediately, but during the next network update.
Other related reference items
| |
host_error ( self ) : booleanIndicates whether or not an error has occurred communicating with the game session host.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
boolean |
Returns true if an error has occurred communicating with the session host, or false otherwise. |
You should handle the error either by calling disconnect_from_host() to shut down your game session, or by calling migrate_game_session_host() on one of the peers to have that peer assume the role as host.
Other related reference items
| |
migrate_game_session_host ( self )Makes the peer calling this function take over the role of host for the specified game session.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
| This function does not return any values. |
You are only allowed to call this if the communcation with the current host is broken: i.e. if host_error() returns true.
In a session with multiple peers, only one of the peers should call migrate_game_session_host(), since a session cannot have multiple hosts. The recommended way of solving this is to have all peers compare their peer ID, which is accessible through Network.peer_id(), to the list of all peers in the session, which is accessible through GameSession.peers(). The peer with the lowest peer ID should then call migrate_game_session_host() to assume the role of host.
Other related reference items
Game objects
Functions that involve creating and managing game objects.
| |
create_game_object ( self, type, fields ) : integerCreates a new game object of the specified type.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
type : | string | The type of game object to create, as configured in the .network_config data file. |
fields : | table | A table that contains starting values for the new object's data fields. |
integer |
A unique ID for the newly created game object. |
The fields table provides starting values for the data fields maintained by the game object. The members that you can set up in this table are determined by the fields you have configured for this type of game object in the .network_config data file. For example:
myGameObject = stingray.GameSession.create_game_object(mySession, "enemy", { position = Vector3(0,0,0), hitpoints = 50 } )
| |
destroy_game_object ( self, object_id )Destroys the specified game object.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
object_id : | integer | The ID of the game object to destroy. |
| This function does not return any values. |
This function can only be called by the peer that owns the game object.
| |
game_object_exists ( self, object_id ) : booleanIndicates whether or not a game object exists with the specified ID.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
object_id : | integer | The ID of the game object to test. |
boolean |
Returns true if an object with the specified ID exists in the session, or false otherwise. |
| |
game_object_field ( self, object_id, field ) : anyReturns the data maintained by the specified game object in the specified data field.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
object_id : | integer | The ID of the game object whose value will be retrieved. |
field : | string | The name of the field whose value you want to retrieve. |
any |
The value currently stored in the specified field of the game object. The type of this value depends on the data type configured for the field in the .network_config data file. |
| |
game_object_is_type ( self, object_id, object_type ) : booleanIndicates whether or not the specified game object is an instance of a specified game object type.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
object_id : | integer | The ID of the game object to test. |
object_type : | string | The type of game object, as set up in the .network_config data file. |
boolean |
Returns true if the game object is an instance of the specified type, or false otherwise. |
Note that the comparison is done internally rather than providing direct access to the object's type, since the type is stored internally using a hashed value.
| |
game_object_owned ( self, object_id ) : booleanIndicates whether or not the peer calling this function is the owner of the specified game object.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
object_id : | integer | The ID of the game object to test. |
boolean |
Returns true if this peer is the owner of the game object, or false otherwise. |
| |
game_object_owner ( self, object_id ) : stringRetrieves the peer that owns the specified game object.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
object_id : | integer | The ID of the game object to test. |
string |
The peer ID of the peer that owns the game object. |
| |
migrate_game_object ( self, object_id, new_peer_id, callback_object )Changes ownership of the specified game object to the specified peer.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
object_id : | integer | The ID of the game object to migrate to a new owner. |
new_peer_id : | string | The peer ID of the new owner. |
callback_object : | table | An object that will be notified through a callback function when the game object is migrated, if you are either the current owner or the new owner of the game object. |
| This function does not return any values. |
This function can only be called by the host of the game session.
If you are the current owner or the new owner of the game object, the callback object you provide to this function will get notified immediately by invoking one of the following callbacks:
- game_object_migrated_to_me(id, old_owner_id)
Notifies you that you have now become the owner of the game object identified by id. The old_owner_id parameter identifies the peer that previously owned the game object.
- game_object_migrated_away(id, new_owner_id)
Notifies you that you are no longer the owner of the game object identified by id. The new_owner_id parameter identifies the peer that now owns the game object.
In any case, the previous owner and the new owner will be notified of the migration during the next call to Network.update().
| |
objects_owned_by ( self, peer_id ) : integer[]Retrieves a list of all game objects owned by the specified peer.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
peer_id : | string | The peer ID of the peer. |
integer[] |
A table that contains the IDs of all game objects owned by the peer. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown. |
| |
set_game_object_field ( self, object_id, field, value )Stores the specified value in the specified data field of the specified game object.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
object_id : | integer | The ID of the game object whose value will be set. |
field : | string | The name of the field whose value you want to set. |
value : | any | The value to store in the specified field of the game object. The type of this value depends on the data type configured for the field in the .network_config data file. |
| This function does not return any values. |
This function can only be called by the peer that owns the game object.
| |
set_game_object_priority ( self, object_id, peer_id, priority )Sets the priority of the specified game object for the specified peer.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
object_id : | integer | The ID of the game object whose priority will be set. |
peer_id : | string | The peer ID of the peer. |
priority : | number | The new priority to set for the game object. |
| This function does not return any values. |
Note that this requires the Quality of Service (QoS) system to be enabled for the networking system. See Network.enable_qos().
| |
unit_synchronizer ( self ) : stingray.UnitSynchronizerRetrieves the unit synchronizer for the specified session.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
|
The UnitSynchronizer for this session, if any. |
You can use this object to aid in synchronizing object creation, movement, and removal. See the UnitSynchronizer description for details.
Peers
Functions for finding other peers in the session.
| |
other_peers ( self ) : string[]Retrieves a list of the IDs of all peers connected to the session, not including the peer calling this function.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
string[] |
A table that contains the IDs of all other peers in the session. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown. |
| |
peers ( self ) : string[]Retrieves a list of the IDs of all peers connected to the session, including the peer calling this function.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
string[] |
A table that contains the IDs of all peers in the session. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown. |
Other related reference items
| |
synchronized_peers ( self ) : string[]Retrieves a list of all peers that have completed their initial synchronization of game objects.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
string[] |
A table that contains the IDs of all synchronized peers. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown. |
| |
synchronizing_peers ( self ) : string[]Retrieves a list of all peers that are still synchronizing initial game objects.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
string[] |
A table that contains the IDs of peers in the initial process of synchronizing their game objects. The [] notation indicates that this type is an array: a table in which the keys of the members are sequential integers, and the value of each element is an instance of the type shown. |
Note that when each peer completes its initial synchronization, all other peers will receive a callback through the callback object provided to Network.update().
In a replay session, this function always returns an empty list, since synchronization does not occur. See the GameSession description for details on replay sessions.
Session control
Functions for joining and leaving game sessions.
| |
broken_connection ( self ) : string?Detects broken connections to other peers in the game session.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
string? |
The ID of a peer with a broken connection if any, or nil. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
Can be called only by the session host. If the connection to a peer has become broken, this function will return that peer's ID. The session host should respond by removing the peer from the session, after destroying or migrating its objects.
If all connections are good, the function will return nil.
If there is more than one broken connection, you will need to call this function repeatedly in order to detect them all.
In a replay session, this function always returns nil, since broken connection states are not recorded in the network log. See the GameSession description for details on replay sessions.
| |
game_session_host ( self ) : stringRetrieves the ID of the peer that is currently acting as the host for the game session.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
string |
The peer ID of the session host |
| |
in_session ( self ) : booleanIndicates whether or not this peer is currently connected to the specified game session.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
boolean |
Returns true if the peer calling this function is connected to the session, or false otherwise. |
If this function returns false, you have been removed from the session because of a bad connection or because the session host has kicked you out. In either case, you should shut down the session.
In a replay session, this function always returns true, since there is always a session. See the GameSession description for details on replay sessions.
Other related reference items
| |
leave ( self )Called by a peer to tell the session host that it wants to leave the session.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
| This function does not return any values. |
After calling this, you should wait until in_session() returns false before shutting down the session. This ensures that all other peers are informed that you have left the session.
Other related reference items
| |
wants_to_leave ( self ) : string?Detects peers in the game session that have requested to leave the session.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. |
string? |
The ID of a peer who has requested to leave the session, or nil. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
Can be called only by the session host. The session host should respond by removing the peer from the session after destroying or migrating its objects.
If no peers want to leave, the function will return nil.
If more than one peer wants to leave, you will need to call this function repeatedly in order to detect them all.
In a replay session, this function always returns nil, since leave requests are not recorded in the network log. See the GameSession description for details on replay sessions.
Settings
Functions that involve creating and managing game objects.
| |
set_interpolation_lag_compensation ( self, time )Sets how far in advance interpolations will be, in order to look smooth when updates for game objects do not occur frequently.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
time : | number | The interpolation compensation threshold, in seconds. |
| This function does not return any values. |
A higher value will be more tolerant of missing updates, but will be more delayed relative to the point of view of a game object's owner.
The default value is 0.015.
| |
set_perfhud_pie_update_interval ( self, time )Sets the interval between updates of the upload and download pies in the network performance HUD.
|
self : | Specifies the object instance that this function will act on. You may use the colon : calling syntax to call this function on an instance of this object. If you do so, you must omit this parameter. For more information, see this Stingray help topic, or this page in the Lua documentation. | |
time : | number | The new update interval, in seconds. |
| This function does not return any values. |
A short interval will find spikes, but will change rapidly.
The default is 1.