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.GameSessionCreates 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 ( ) : booleanIndicates 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.GameSessionReturns 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 ( ) : stringReturns 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 ) : numberPings 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 ) : numberReturns 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_infoReturns 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_infoReturns 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_infoReturns 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 : integerData type for boolean values.
|
Other related reference items 
| |
FLOAT : integerData type for floating-point numbers.
|
| |
IDSTRING32 : integerData type for IdString32.
|
| |
IDSTRING64 : integerData type for IdString64.
|
| |
INT : integerData type for integer numbers.
|
| |
QUATERNION : integerData type for quaternion rotations.
|
| |
RESOURCE_ID : integerData type for resource IDs.
|
| |
STRING : integerData type for string values.
|
| |
UINT64 : integerData type for 64-bit integer values.
|
| |
VECTOR3 : integerData 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 : integerGame object creation, migration and destruction messages are printed, as well as warnings.
|
Other related reference items
| |
SILENT : integerNo debugging output at all.
|
| |
SPEW : integerGame object updates and detailed information are printed, as well as everything above.
|
| |
WARNINGS : integerOnly 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.GameSessionStarts 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 ) : integerCreates 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 ) : booleanIndicates 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 ) : booleanIndicates 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.LanLobbyCreates 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.LanClientInitializes 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.LanLobbyJoins 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
PSN Management
| |
create_psn_room ( name, max_members ) : integerCreates a room on the PlayStation Network with the specified type and name.
|
name : | string | The name of the new room. |
max_members : | integer | The maximum number of peers that can join this room. |
integer |
An ID that identifies the newly created room. |
When you create a new room using this function, you automatically join the room. You do not need to call join_psn_room().
Other related reference items
| |
init_psn_client ( config ) : stingray.PsnClientInitializes the networking system to connect to other games through the PlayStation Network (PSN).
|
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. |
|
The new client object. |
Other related reference items
| |
join_psn_room ( room_id ) : stingray.PsnRoomJoins the room with the specified ID.
|
room_id : | string | The ID of the room you want to join. This string is typically retrieved from the information table returned by a call to PsnRoomBrowser.room(). |
|
The room you have joined. |
Other related reference items
| |
leave_psn_room ( room )Leaves the specified room.
|
room : | The room you want to leave. |
| This function does not return any values. |
If you are hosting the room, it will migrate to a different peer in the room. If you are the last member of the room, the room will be removed from the network.
| |
shutdown_psn_client ( client )Shuts down the specified PsnClient, previously created by a call to init_psn_client().
|
client : | The PSN client that you want to shut down. |
| This function does not return any values. |
Steam network management
| |
create_steam_lobby ( type_lobby, max_members ) : stingray.SteamLobbyCreates 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.SteamClientInitializes 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.SteamGameServerInitializes 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.SteamLobbyJoins 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.SteamGameServerLobbyJoins 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.SteamGameServerLobbyJoins 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 : integerIndicates that the lobby Can be joined by friends.
|
| |
STEAM_LOBBY_INVISIBLE : integerIndicates that the lobby is not visible to other friends, but can returned by a search.
|
| |
STEAM_LOBBY_PRIVATE : integerIndicates that the lobby can only be joined by invitees.
|
| |
STEAM_LOBBY_PUBLIC : integerIndicates that the lobby is visible in the lobby list.
|
Xbox Live Management
| |
clean_sessions ( user_id )Leaves all session the user is associated with, used to clean up stale and leaked sessions.
|
user_id : | integer | Id of the user whose sessions are to be cleaned |
| This function does not return any values. |
It is good practice to do this before the user starts to matchmake or create sessions. This function runs asynchronously, use clean_sessions_status() to monitor the status.
There is no need to free this job once it is completed and it may transition to stingray.SessionJobStatus.NOT_RUNNING instead of stingray.SessionJobStatus.COMPLETE automatically when finished.
Ensure that all sessions have been freed before calling.
Other related reference items
| |
clean_sessions_status ( ) : integerReturns the status of the clean sessions operation.
|
| This function does not accept any parameters. |
integer |
Status of the clean session operation started with clean_sessions(). May be any of the SessionJobStatus(network.xbl.work_status) constants. |
Other related reference items
| |
clear_activity ( user_id )Clears the activity of the supplied user.
|
user_id : | integer | Id of the user to clear activity for. |
| This function does not return any values. |
This function runs asynchronously, use clear_activity_status() to monitor the status.
There is no need to free this job once it is completed.
Note: This function is, unlike set_activity(), session independent.
Other related reference items
| |
clear_activity_status ( user_id ) : integerReturns the status of the clear user activity operation.
|
user_id : | integer | Id of the user to get clear activity operation status for. |
integer |
Status of the clear user activity started with clear_activity(). May be any of the SessionJobStatus(network.xbl.work_status) constants. |
Other related reference items
| |
create_multiplayer_session ( user_id, session_name, session_template_name, create_as_host, session_keywords ) : integerStarts the asynchronous job of creating and joining a session.
|
user_id : | integer | Id of the user to create session for. |
session_name : | string | Name of the session. Should be all lower-case characters. |
session_template_name : | string | Name of the session template. Should be all lower-case characters. |
create_as_host : | boolean | True if the supplied user should be set as session host. |
session_keywords : | string[]? | Optional table of string representing keywords for the session. Strings must not be empty and at most made of 63 characters. 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. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Session id, used to reference this session in the lua interfaces. |
You can track the status of the session with stingray.MultiplayerSession.status().
Deprecated please use create_multiplayer_session_host and create_multiplayer_session_client Returns a session_id user to track the session.
This should only be called for the main user on each console. If there are multiple local users they should be added to the session with stingray.Network.join_local_multiplayer_session().
Use stingray.MultiplayerSession.leave() to leave the session. When the asynchronous task is finished you need to call stingray.Network.free_multiplayer_session() to free the session resources.
create_as_host should be set as false when joining a remote host found through matchmaking.
Other related reference items
| |
create_multiplayer_session_client ( user_id, session_name, session_template_name, xbox_user_id_member_reservation ) : integerStarts the asynchronous job of creating and joining a session.
|
user_id : | integer | Id of the user to create session for. |
session_name : | string | Name of the session. Should be all lower-case characters. |
session_template_name : | string | Name of the session template. Should be all lower-case characters. |
xbox_user_id_member_reservation : | integer[]? | Optional table of Xbox User ID to reserve place as members. 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. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Session id, used to reference this session in the lua interfaces. |
You can track the status of the session with stingray.MultiplayerSession.status().
Returns a session_id user to track the session.
This should only be called for the main user on each console. If there are multiple local users they should be added to the session with stingray.Network.join_local_multiplayer_session().
Use stingray.MultiplayerSession.leave() to leave the session. When the asynchronous task is finished you need to call stingray.Network.free_multiplayer_session() to free the session resources.
| |
create_multiplayer_session_host ( user_id, session_name, session_template_name, session_keywords, min_number_members, max_number_members, xbox_user_id_member_reservation ) : integerStarts the asynchronous job of creating and joining a session.
|
user_id : | integer | Id of the user to create session for. |
session_name : | string | Name of the session. Should be all lower-case characters. |
session_template_name : | string | Name of the session template. Should be all lower-case characters. |
min_number_members : | integer? | Optional min numbers of members in session. If this threshold is not met, members fail the initialization step. Default to 0 which uses the session template. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
max_number_members : | integer? | Optional maximum numbers of members in session. Default to 0 which uses the session template if not specified there it will be 100. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
session_keywords : | string[]? | Optional table of string representing keywords for the session. Strings must not be empty and at most made of 63 characters. 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. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
xbox_user_id_member_reservation : | integer[]? | Optional table of Xbox User ID to reserve place as members. 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. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Session id, used to reference this session in the lua interfaces. |
You can track the status of the session with stingray.MultiplayerSession.status().
Returns a session_id user to track the session.
This should only be called for the main user on each console. If there are multiple local users they should be added to the session with stingray.Network.join_local_multiplayer_session().
Use stingray.MultiplayerSession.leave() to leave the session. When the asynchronous task is finished you need to call stingray.Network.free_multiplayer_session() to free the session resources.
| |
free_get_activity_details ( session_lookup_id )Frees the resources beloging to the asynchronous task started with stingray.Network.get_activity_details().
|
session_lookup_id : | integer | Id of the session lookup to be freed. |
| This function does not return any values. |
Note that the result can only be freed when stingray.Network.get_activity_details_status() returns stingray.SessionJobStatus.COMPLETE or stingray.SessionJobStatus.FAILED.
Other related reference items
| |
free_handle_to_description ( session_lookup_id )Frees the resources belonging to the asynchronous task started with stingray.Network.handle_to_description().
|
session_lookup_id : | integer | Id of the session lookup to be freed. |
| This function does not return any values. |
Note that the result can only be freed when stingray.Network.handle_to_description_status() returns stingray.SessionJobStatus.COMPLETE or stingray.SessionJobStatus.FAILED.
Other related reference items
| |
free_multiplayer_session ( session_id )Frees up the resources used by the session with supplied id.
|
session_id : | integer | Id of the session to be freed. |
| This function does not return any values. |
Ensure that stingray.MultiplayerSession.status() returns stingray.MultiplayerSession.SHUTDOWN before calling.
Other related reference items
| |
get_activity_details ( user_id, xuids ) : integerStarts the asynchronous task of getting user activity details.
|
user_id : | integer | Id of the user to do use for the activity lookup. |
xuids : | string[] | Xuids of the users to have their acrivities fetched. 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. |
integer |
Id, used to reference this get activity details task in the lua interfaces. |
The status can be monitored with stingray.Network.get_activity_details_status() and the result can be retrieved with stingray.Network.get_activity_details_result().
When the get activity details task is finished it must be freed by calling stingray.Network.free_get_activity_details().
Other related reference items
| |
get_activity_details_result ( session_lookup_id ) : activity_details*Result from the get activity details task
|
session_lookup_id : | integer | Id of the session lookup to get result for. |
|
Activity detais for users that have an activity set. The * notation indicates that there may be zero or more instances of the specified type. |
Note that the result can only be retrieved when stingray.Network.get_activity_details_status() returns stingray.SessionJobStatus.COMPLETE.
Other related reference items
| |
get_activity_details_status ( get_activites_id ) : integer |
get_activites_id : | integer | Id of the get activity details task to get status for. |
integer |
Returns the status of the get activity details task started with stingray.Network.get_activity_details(). May be any of the SessionJobStatus(network.xbl.work_status) constants. |
Other related reference items
| |
handle_to_description ( user_id, handle ) : integerStarts the asynchronous session lookup task for the supplied user.
|
user_id : | integer | Id of the user to do the session lookup for. |
handle : | string | Session handle, it must not be empty and at most made of 63 characters. |
integer |
Session lookup id, used to reference this session lookup job in the lua interfaces. |
The status can be monitored with stingray.Network.handle_to_description_status() and the result can be retrieved with stingray.Network.handle_to_description_result().
When the session lookup is finished it must be freed by calling stingray.Network.free_handle_to_description().
Other related reference items
| |
handle_to_description_result ( session_lookup_id ) : string, stringResult from the session lookup.
|
session_lookup_id : | integer | Id of the session lookup to get result for. |
string |
Session name |
string |
Session template name |
Note that the result can only be retrieved when stingray.Network.handle_to_description_status() returns stingray.SessionJobStatus.COMPLETE.
Other related reference items
| |
handle_to_description_status ( session_lookup_id ) : integer |
session_lookup_id : | integer | Id of the session lookup to get status for. |
integer |
Returns the status of the session lookup started with stingray.Network.handle_to_description(). May be any of the SessionJobStatus(network.xbl.work_status) constants. |
Other related reference items
| |
init_xboxlive_client ( config )Initializes the networking system to connect to other games through Xbox Live.
|
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. |
| This function does not return any values. |
Ensure that no Xbox Live Client exists before calling this function by using with xboxlive_client_exists().
Make sure that you have matching service config ids in settings.ini (under the service_config_id key) and in the AppXManifest before calling.
Other related reference items
| |
invite_friends ( user_id, session_id, min_selection, max_selection, custom_invite_id )Open the system UI to select friends and send them an invite.
|
user_id : | integer | Id of the user to create session for. |
session_id : | integer | Id of the session to join. |
min_selection : | integer | Minimum number of people that must be selected. This number can be zero. The number must not be greater than the value of max_selection. |
max_selection : | integer | Maximum number of people that can be selected. |
custom_invite_id : | string? | Optional id of a custom invite string to use. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
Other related reference items
| |
invite_friends_list ( user_id, session_id, friend_xuids, custom_invite_id )This will start the asynchronous job of sending game invites to friends without opening the system ui.
|
user_id : | integer | Id of the user to create session for. |
session_id : | integer | Id of the session to join. |
friend_xuids : | string[] | List of xbox user ids to friends to invite to the specified 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. |
custom_invite_id : | string? | Optional id of a custom invite string to use. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
| This function does not return any values. |
| |
join_local_multiplayer_session ( user_id, session_id ) : integerStarts the asynchronous job of joining a local user to a session.
|
user_id : | integer | Id of the user to create session for. |
session_id : | integer | Id of the session to join. |
integer |
Session Id |
You can track the status of the session with stingray.MultiplayerSession.status().
This function should be used when there are multiple local users that need to be added to the session. Ensure that the session created with stingray.Network.create_multiplayer_session() has finished its initial asynchronous work before calling.
Other related reference items
| |
set_activity ( user_id, session_id )Sets the activity of the user to the supplied session.
|
user_id : | integer | Id of the user to set activity for. |
session_id : | integer | Id of the session to set the activity to. |
| This function does not return any values. |
This function is run asynchronously in the associated session. You can track the status of the session with stingray.MultiplayerSession.status().
Note: This function depends on the supplied session, ensure that stingray.MultiplayerSession.status() returns stingray.MultiplayerSession.READY before calling.
Other related reference items
| |
set_presence ( user_id, presence_id, is_active_in_title ) : integerThis functions sets the presence string for the specified user.
|
user_id : | integer | Id of the user to set presence for. |
presence_id : | string | Id of the string presence is to be set to. |
is_active_in_title : | boolean? | Specifies whether the user is actually using the current title or not. Defaults to true. The ? notation indicates that this type is optional: there may be zero or one instances of it. |
integer |
Id of the set presence job. |
Use stingray.Network.set_presence_status() to track progress of the operation. The system will automatically clean up the job when it is finished.
Other related reference items
| |
set_presence_status ( set_precense_job_id ) : integer |
set_precense_job_id : | integer | Id of the set precense job to get status for. |
integer |
Returns the status of the session lookup started with stingray.Network.set_presence(). Will be one of the stingray.SessionJobStatus constants. There is no need to free this job once it is completed and it will transition to stingray.SessionJobStatus.NOT_RUNNING instead of stingray.SessionJobStatus.COMPLETE automatically when finished. |
Other related reference items
| |
Shuts down the Xbox Live Client created with init_xboxlive_client().
|
| This function does not accept any parameters. |
| This function does not return any values. |
| |
xboxlive_client_exists ( ) : booleanUse this function to ensure that only one Xbox Live Client exists at any given time.
|
| This function does not accept any parameters. |
boolean |
True if the Xbox Live Client exists. |
Other related reference items