Network - stingray.Network namespace reference - Stingray Lua API Reference
Description
The Network object is the main interface to the system used for playing multiplayer games over the network.
To use this system, you must first set it up it by calling an init_...() function that determines which network subsystem to use: init_lan_client(), init_steam_client(), [init_psn_client()], [init_xboxlive_client()] etc.
You can only have one network subsystem running at any one time.
After initializing the network, you use the lobby functionality of the network subsystem you are using to either create a new lobby or find an existing one (using a lobby browser). See the interface for the network subsystem you are using: LAN, Steam, PSN or Xbox Live.
Every frame, as long as your client is running, make sure that you call Network.update().
When you have enough players in a lobby, you can start a new GameSession: an object that manages a running multiplayer game. You use the same object no matter which network subsystem you are using.
Once you are completely done with using the network, you should call the shutdown_...() function for the network subsystem you are using: e.g. shutdown_lan_client(), shutdown_steam_client(), [shutdown_psn_client()], [shutdown_xboxlive_client()], etc.
Note that other network functionality, such as DLC, Steam [Leaderboards] and [Achievements], etc. are not found here.
Other related reference items 
Functions
 |
config_hash ( config_resource )
Constructs a hash based on the contents of a network configuration data file.
|
config_resource : | string |
The resource name of the .network_config data file to hash. |
| This function does not return any values. |
This can be used to determine if two peers are compatible.
| |
create_game_session ( ) : stingray.GameSession
Creates a new game session.
|
| This function does not accept any parameters. |
|
The newly created game session. |
You can only have one game session running at any one time. If you have an existing session, you must shut it down first by calling shutdown_game_session() before creating a new one.
Note: Both the server and the client should call create_game_session(): the server should do this when it starts the game, and the client when it drops into the game.
Other related reference items
| |
enable_qos ( min_peer_kbps, initial_peer_kbps, max_total_kbps )
Enables the Quality of Service system, which tries to adapt the upload limit to fit the
bandwidth capacity.
|
min_peer_kbps : | number |
The minimum upload speed allowed, in kbit/s. |
initial_peer_kbps : | number |
The initial upload speed, in kbit/s. |
max_total_kbps : | number |
The maximum upstream bandwidth allowed, in kbit/s. This is used to limit traffic on dedicated servers that serve several games. |
| This function does not return any values. |
Other related reference items
| |
fatal_error ( ) : boolean
Indicates whether or not a fatal network error has occurred that will prevent any further network
operations.
|
| This function does not accept any parameters. |
boolean |
Returns true if a fatal network error has occurred, or false otherwise. |
Your game should respond to this condition by shutting down the Network object and dropping the player into offline mode.
For example, this condition may occur if the player signs out of the PlayStation Network during a game.
| |
game_session ( ) : stingray.GameSession
Returns the current game session.
|
| This function does not accept any parameters. |
|
The current game session, or nil if no game session has been set up yet. |
| |
peer_id ( ) : string
Returns an id that uniquely identifies this peer.
|
| This function does not accept any parameters. |
string |
A string that uniquely identifies this peer on the network, or nil if no peer ID has been set up yet. |
- In a LAN game, the id is a random number.
- On Steam, this will be the player's Steam ID.
If no peer ID has yet been established, this function will return nil. This can happen on PlayStation4, where the peer ID isn't known until a connection to a room has been established.
Other related reference items
| |
ping ( player_id ) : number
Pings the specified peer and returns the time taken for the ping.
|
player_id : | string |
The ID of the peer you want to connect to. |
number |
The time it takes for a ping to reach that player, or 0 if no connection to that player exists. |
Other related reference items
| |
reliable_send_buffer_left ( peer_id ) : number
Returns the size in bytes left to fill in the reliable send buffer for a specific peer.
|
peer_id : | string |
Identifies the peer. |
number |
The size of the buffer in bytes, or 0 if the peer does not exist. |
Initially, when a new peer joins a session, it is common to send some information over before the new peer can begin playing. Game object creation messages are spread over several frames so as to not overload the buffers that hold the information that has not yet been received on the other end. After all game objects have been transmitted successfully, you get a callback saying so. RPC messages have to be handled in a similar manner, if you are sending a lot of data when a peer joins a session; however, this is not handled internally by the engine. You can use this function to determine if it is best to stop sending RPC messages until there is more space left in the send buffer.
Note: Do not fill the buffer completely, since the engine may also send data that you are not aware of.
| |
Shuts down the current GameSession, if any.
|
| This function does not accept any parameters. |
| This function does not return any values. |
Other related reference items
| This function does not accept any parameters. |
| This function does not return any values. |
See the [ReplaySession] documentation for details.
Other related reference items
| |
update ( dt, callback_object )
Updates the network system, and notifies you via callbacks of events that have occurred
and RPC messages that have been sent since your last update.
|
dt : | number |
The delta time since the last call to update(), in seconds. |
callback_object : | table |
A table that contains a set of callback functions that are invoked to respond to events that occur during the networked game session. |
| This function does not return any values. |
For each event or RPC message, a function of the callback_object table will be called immediately during the update() call.
In the case of RPC messages sent by other peers, the functions invoked are determined by the names of the messages you set up in your .network_config data file. See the RPC object documentation for details.
In the case of game events, there is a pre-set list of callback functions that you should implement in your callback object to handle the various kinds of game events that may occur:
- game_object_created(id, creator_id)
Notifies you that the game object identified by id was created by peer creator_id.
- game_object_destroyed(id, destroyer_id)
Notifies you that the game object identified by id was destroyed by peer destroyer_id.
- 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.
- game_object_sync_done(peer_id)
Notifies you that all game objects have been synchronized with the specified remote peer after a new peer was added, so from now on RPC calls will be ordered with respect to game object creation messages. Before this callback, you are not guaranteed that RPC calls and game object creation calls arrive in the same order they are called.
- game_session_disconnect(host_id)
Notifies you that you have been disconnected from the game session by the game session host. Either you are kicked out, or the game session host left the game.
If you want to reduce network latency slightly, you can instead call update_receive() to receive network communications, respond to them in your game, and then update_transmit() later in the same frame.
Other related reference items
| |
update_receive ( dt, callback_object ) |
dt : | number |
The delta time since the last call to update(), in seconds. |
callback_object : | table |
A table that contains a set of callback functions that are invoked to respond to events that occur during the networked game session. For details, see the description for update(). In order to reduce latency by one frame, you can call update_receive() and update_transmit(), in that order, instead of a single call to update(). That way, you may be able to respond to the received information within the same frame, before transmitting. |
| This function does not return any values. |
Other related reference items
| |
update_transmit ( )
In order to reduce latency by one frame, you can call update_receive() and update_transmit(), in that order,
instead of a single call to update().
|
| This function does not accept any parameters. |
| This function does not return any values. |
That way, you may be able to respond to the received information within the same frame, before transmitting.
Other related reference items
| |
write_dump_tag ( details )
If the networking system is configured in the settings.ini file to write a log of all network activity,
this function writes a tag with the specified name into the log file.
|
details : | string |
The string to write in the network log file. |
| This function does not return any values. |
When you use the Network Analyzer tool to examine the network log file, these tags are shown as vertical markers in the bandwidth graphs.
Configuration
The elements in this group are related to configuring the network connection.
| |
message_info ( message_name ) : network_message_info
Returns a table that contains metadata about the specified message type, such as its priority, expected
arguments, etc.
|
message_name : | string |
The name of the RPC message type you want to retrieve information about, which must correspond to the name of a message specified in your .network_config data file. |
|
A table that contains metadata about the specified message type. |
Other related reference items
| |
object_info ( object_name ) : network_object_info
Returns a table that contains metadata about the specified game object type, such as its priority, data fields, etc.
|
object_name : | string |
The name of the game object type you want to retrieve information about, which must correspond to the name of an object specified in your .network_config data file. |
|
A table that contains metadata about the specified game object type. |
Other related reference items
| |
set_max_transmit_rate ( time )
Sets the minimum time that can elapse between successive transmits.
|
time : | number |
The new minimum time between successive transmits, in seconds. |
| This function does not return any values. |
The default value is 0.03.
| |
set_ping_resend_time ( time )
Sets the time between keep-alive messages when there is no response.
|
time : | number |
The new time before sending a keep-alive message, in seconds. |
| This function does not return any values. |
The default value is 0.5.
| |
set_ping_send_time ( time )
Sets the time between a keep-alive response and the next keep-alive message.
|
time : | number |
The new time before sending a keep-alive message, in seconds. |
| This function does not return any values. |
The default value is 1.0.
| |
set_pong_timeout ( time )
Sets the timeout before a receiver is considered lost.
|
time : | number |
The new maximum time before a receiver is assumed lost, in seconds. |
| This function does not return any values. |
The default value is 60.0.
| |
set_resend_time ( time )
Sets the time in seconds before resending any packets that are assumed to have been dropped.
|
time : | number |
The new resend time to set, in seconds. |
| This function does not return any values. |
The default value is 0.2.
| |
type_info ( type_name ) : network_type_info
Returns a table that contains metadata about the specified data type, such as the number of bits used
by the engine to compress values of that type, minimum and maximum values, etc.
|
type_name : | string |
The name of the data type you want to retrieve information about, which must correspond to the name of a type specified in your .network_config data file. |
|
A table that contains metadata about the specified data type. |
Other related reference items
Data types
Identifiers for different data types, used by the Network.type_info() function.
 |
ARRAY : integer
Data type for arrays.
|
| |
BOOL : integer
Data type for boolean values.
|
Other related reference items 
| |
FLOAT : integer
Data type for floating-point numbers.
|
| |
IDSTRING32 : integer
Data type for IdString32.
|
| |
IDSTRING64 : integer
Data type for IdString64.
|
| |
INT : integer
Data type for integer numbers.
|
| |
QUATERNION : integer
Data type for quaternion rotations.
|
| |
RESOURCE_ID : integer
Data type for resource IDs.
|
| |
STRING : integer
Data type for string values.
|
| |
UINT64 : integer
Data type for 64-bit integer values.
|
| |
VECTOR3 : integer
Data type for three-dimensional vector values.
|
Debugging
The elements in this group are related to debugging networked games.
| |
log ( log_level )
Sets the level of information that will be sent to the debugging console.
|
log_level : | integer |
May be any value from the logging level group, such as MESSAGES or WARNINGS. |
| This function does not return any values. |
Other related reference items
Debugging log levels
Log levels that you can pass to Network.log().
| |
MESSAGES : integer
Game object creation, migration and destruction messages are printed, as well as warnings.
|
Other related reference items
| |
SILENT : integer
No debugging output at all.
|
| |
SPEW : integer
Game object updates and detailed information are printed, as well as everything above.
|
| |
WARNINGS : integer
Only warnings.
|
Other related reference items
Development only
The elements in this group are only available in development builds.
Do not use them in your final builds.
| |
create_replay_session ( dump_file ) : stingray.GameSession
Starts a new replay session.
|
dump_file : | string |
The path to a file that contains a dump of the network session. |
|
A new GameSession object set up as a "Replay Session". |
See the GameSession object documentation for details.
Other related reference items
| |
disable_qos_peer ( peer_id )
Disables the Quality of Service system for communications with the specified peer.
|
peer_id : | string |
The ID of the peer for which to disable Quality of Service. |
| This function does not return any values. |
You can re-enable it by calling enable_qos_peer().
Only available in development builds, for the purposes of debugging the Quality of Service system. Note that you must enable Quality of Service by calling enable_qos() in order for this function to have any effect.
Other related reference items
| |
enable_qos_peer ( peer_id )
Re-enables the Quality of Service system for communications with the specified peer,
after it was disabled by a call to disable_qos_peer().
|
peer_id : | string |
The ID of the peer for which to re-enable Quality of Service. |
| This function does not return any values. |
Only available in development builds, for the purposes of debugging the Quality of Service system. Note that you must enable Quality of Service by calling enable_qos() in order for this function to have any effect.
Other related reference items
Explicit connections
The elements in this group are related to configuring explicit connections.
| |
connections ( ) : string[]
Returns a list of all peers with active connections.
|
| This function does not accept any parameters. |
string[] |
A table that lists the peer IDs. 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. |
| |
create_connection ( peer_id ) : integer
Creates a new connection to the specified peer.
|
peer_id : | string |
The unique ID of the peer you want to connect to. |
integer |
An ID for the newly created connection |
There can be at most one connection to any particular peer, so you cannot call this function if a connection to the peer already exists.
Note that directly connecting to a peer in this way is only supported by certain transport layers (e.g. Steam). In other transport layers (e.g. PSN), connections are always set up by rooms and lobbies, so there is no way to connect directly to a peer.
| |
destroy_connection ( peer_id )
Disconnects from the specified peer, if a connection currently exists.
|
peer_id : | string |
The unique ID of the peer you want to disconnect from. |
| This function does not return any values. |
Note that you cannot destroy a connection that is used by higher layers of the network stack, so you must call is_used() first in order to check that the connection can be destroyed before you call this function.
Other related reference items
| |
has_connection ( peer_id ) : integer?
Returns the ID of the connection to the specified peer, if one exists.
|
peer_id : | string |
The unique ID of the peer you want to test. |
integer? |
The ID of the connection to this peer, or nil if no connection exists. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| |
is_broken ( peer_id ) : boolean
Indicates whether or not the connection to the specified peer is broken: i.e. if the networking system
can no longer transmit messages to that peer.
|
peer_id : | string |
The peer whose connection will be tested. |
boolean |
Returns true if the connection is broken, or false otherwise. |
| |
is_used ( peer_id ) : boolean
Indicates whether or not the connection to the specified peer is in use by higher-level layers of the
networking system, such as rooms, lobbies, game sessions, etc.
|
peer_id : | string |
The peer whose connection will be tested. |
boolean |
Returns true if the connection is in use, or false otherwise. |
You cannot explicitly destroy a connection while it is being used, so this function must return false before you can call destroy_connection(). If this function returns true, and you want to close the connection, you must first shut down any lobbies, rooms, game sessions, etc. that are using the connection to this peer.
Other related reference items
| This function does not accept any parameters. |
| This function does not return any values. |
LAN Management
| |
create_lan_lobby ( lobby_port, max_members ) : stingray.LanLobby
Creates a lobby on the LAN.
|
lobby_port : | integer |
The UDP port you want to use for lobby communications. Note that this should not be the same number used as the game port in your call to init_lan_client(). Clients browsing for lobbies will specify the lobby port number, so you should use a single well-known port number for all peers running lobbies. |
max_members : | integer |
The maximum number of peers that can join this lobby. |
|
The newly created lobby object. |
When you create a new lobby using this function, you automatically join the lobby. You do not need to call join_lan_lobby().
Other related reference items
| |
init_lan_client ( config, game_port, peer_id ) : stingray.LanClient
Initializes the networking system to connect to other games on the local area network (LAN).
|
config : | string |
The name of the .network_config resource to use for setting up the client, which determines the types of game objects and RPC messages that can be used during the session. |
game_port : | integer? |
The UDP port you want to use for network communication. If you specify 0 or omit this parameter, a random free port will be picked. This is good for testing multiple network nodes on the same machine, since it ensures that port numbers won't collide. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
peer_id : | integer? |
If specified, this number will be used as the ID to identify the client to other network nodes. If omitted, a random number is assigned. Note that the peer id must be unique to all nodes on the LAN, otherwise messages will not arrive on the proper destination. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
|
The new client object. |
Make sure that you call Network.update() every frame after initializing the LAN client, and call Network.shutdown_lan_client() when you no longer need it.
Other related reference items
| |
join_lan_lobby ( address, lobby_port ) : stingray.LanLobby
Joins the lobby at the specified address.
|
address : | string |
The IP address and lobby port number of the host running the lobby. This string follows the format ip:port, and is typically retrieved from the information table returned by a call to LanLobbyBrowser.lobby(). |
lobby_port : | integer? |
The port that the lobby should use on this computer. If you specify 0 for the lobby_port, or you omit the parameter, a random free port will be used. This is good when you are testing multiple nodes on the same machine, because it means the port won't collide with the public lobby port used by create_lan_lobby(). The drawback of this approach is that if the lobby host quits and the lobby migrates to you, other nodes won't be able to find your lobby because it is running on a random port. To make the lobby publicly findable if it migrates to you, you need to use the same public port as you use in create_lan_lobby(). However, this means that you cannot run multiple network nodes on the same machine. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
|
The lobby you have joined. |
Other related reference items
| |
leave_lan_lobby ( lobby )
Leaves the specified lobby.
|
lobby : |
The lobby you want to leave. |
| This function does not return any values. |
If you are hosting the lobby, it will migrate to a different peer in the lobby. If you are the last member of the lobby, the lobby will be removed from the network.
| |
shutdown_lan_client ( client )
Shuts down the specified LanClient, previously created by a call to init_lan_client().
|
client : |
The LAN client that you want to shut down. |
| This function does not return any values. |
Other related reference items
Steam network management
| |
create_steam_lobby ( type_lobby, max_members ) : stingray.SteamLobby
Creates a SteamLobby.
|
type_lobby : | integer |
The type of lobby to create. The type can be one of the lobby type constants. |
max_members : | integer |
The maximum number of members allowed in the lobby. |
|
The newly created Steam lobby. |
When you create a lobby you automatically join it; you don't have to call join_steam_lobby().
Other related reference items
| |
init_steam_client ( config ) : stingray.SteamClient
Initializes the networking system to connect to other games as a Steam client.
|
config : | string |
The name of the * .network_config* file to use for setting up the client, which determines the types of game objects and RPC messages that can be used during the session. |
|
The new Steam client object. |
Note that Steam must be running before you can call this function. See the stingray.Steam object and the Steam.connected() function.
Other related reference items
| |
init_steam_server ( config, settings ) : stingray.SteamGameServer
Initializes the network as a Steam game server, which other Steam clients can find using the Steam server browser.
|
config : | string |
The name of the * .network_config* file that you want to use for setting up the server, which determines the types of game objects and RPC messages that can be used during the session. |
settings : |
A table that contains configuration settings for the server, expressed as key/value pairs. |
|
The newly created Steam game server. |
Other related reference items
| |
join_steam_lobby ( lobby_id ) : stingray.SteamLobby
Joins the lobby identified by the specified ID.
|
lobby_id : | integer |
The ID of the Steam lobby. |
|
A newly created SteamLobby object that represents your connection to the lobby. |
Other related reference items
| |
join_steam_server ( ip_address, password ) : stingray.SteamGameServerLobby
Joins a Steam server on the Internet.
|
ip_address : | string |
The IPv4 address in the format a.b.c.d:e, where the first four numbers are the components of the IPv4 address of the host, followed by a colon, followed by the number of the query port used by the server. For example: 127.0.0.1:27016. |
password : | string? |
The password expected by the server, if any. Only required for connecting to a password-protected server. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
|
A lobby object that tracks the connection to the server. |
A lobby object is returned that is used to check the connection progress to the server.
Other related reference items
| |
join_steam_server ( ip_address, port, password ) : stingray.SteamGameServerLobby
Joins a Steam server on the Internet.
|
ip_address : | string |
The IPv4 address in the format a.b.c.d:e, where the four numbers are the components of the IPv4 address of the host. For example: 127.0.0.1. |
port : | number |
The number of the query port used by the server. For example, 27016. |
password : | string? |
The password expected by the server, if any. Only required for connecting to a password-protected server. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
|
A lobby object that tracks the connection to the server. |
A lobby object is returned that is used to check the connection progress to the server.
| |
leave_steam_lobby ( lobby )
Leaves the specified lobby.
|
lobby : |
The Steam lobby you want to leave. |
| This function does not return any values. |
If you are hosting the lobby, it will migrate to a different user in the lobby. If you are the last member of the lobby, the lobby will be removed.
| |
leave_steam_server ( server_lobby )
Removes the server lobby and notifies the server.
|
server_lobby : |
The lobby you want to remove. |
| This function does not return any values. |
| |
shutdown_steam_client ( client )
Shuts down a SteamClient created by init_steam_client().
|
client : |
The Steam client that you want to shut down. |
| This function does not return any values. |
| |
shutdown_steam_server ( server )
Shuts down a SteamGameServer created by init_steam_server().
|
server : |
The Steam game server you want to shut down. |
| This function does not return any values. |
Steam Lobby types
Constants used to represent the different types of Steam lobby.
| |
STEAM_LOBBY_FRIENDS_ONLY : integer
Indicates that the lobby Can be joined by friends.
|
| |
STEAM_LOBBY_INVISIBLE : integer
Indicates that the lobby is not visible to other friends, but can returned by a search.
|
| |
STEAM_LOBBY_PRIVATE : integer
Indicates that the lobby can only be joined by invitees.
|
| |
STEAM_LOBBY_PUBLIC : integer
Indicates that the lobby is visible in the lobby list.
|