Class MatchmakingClientService

The client service for matchmaking.

Inheritance

object

IdentifiableObject

DependencyObject

AttachableObject

Service

UpdatableService

MatchmakingClientService

Implements

IDependencyObject

Inherited Members

Service.OnLoaded()

Service.OnAttached()

Service.OnActivated()

Service.Start()

Service.OnDeactivated()

Service.OnDestroy()

AttachableObject.AttachableStateChanged

AttachableObject.IsEnabled

AttachableObject.State

AttachableObject.IsLoaded

AttachableObject.IsAttached

AttachableObject.IsActivated

AttachableObject.IsStarted

AttachableObject.IsDestroyed

AttachableObject.ShouldBeActivated

AttachableObject.Destroy()

AttachableObject.DependencyBroken()

DependencyObject.Dependencies

DependencyObject.OnDependencyRemoved

IdentifiableObject.Id

IdentifiableObject.IdHasChanged(Guid)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Evergine.Networking.Client

Assembly: Evergine.Networking.dll

Syntax

public class MatchmakingClientService : UpdatableService, IDependencyObject

Constructors

MatchmakingClientService()

Initializes a new instance of the MatchmakingClientService class.

Declaration

public MatchmakingClientService()

Properties

ApplicationIdentifier

Gets or sets the application Identifier. Used by the matchmaking server to separate players by different game.

Declaration

public string ApplicationIdentifier { get; set; }

Property Value

Type	Description
string

ClientApplicationVersion

Gets or sets the version of your client. A new version also creates a new "virtual app" to separate players from older client versions.

Declaration

public string ClientApplicationVersion { get; set; }

Property Value

Type	Description
string

ClientState

Gets the current state this client is in. Careful: several states are "transitions" that lead to other states.

Declaration

public ClientStates ClientState { get; }

Property Value

Type	Description
ClientStates

ConnectionTimeout

Gets or sets the connection timeout. Default value is 25 seconds.

Declaration

public TimeSpan ConnectionTimeout { get; set; }

Property Value

Type	Description
TimeSpan

CurrentRoom

Gets the current room this client is connected to (null if none available).

Declaration

public LocalNetworkRoom CurrentRoom { get; }

Property Value

Type	Description
LocalNetworkRoom

IsConnected

Gets a value indicating whether this client is currently connected or connecting to the matchmaking server.

Declaration

public bool IsConnected { get; }

Property Value

Type	Description
bool

Remarks

This is even true while switching servers. Use IsConnectedAndReady to check only for those states that enable you to send Operations.

IsConnectedAndReady

Gets a value indicating whether your connection to the matchmaking server is ready to accept operations.

Declaration

public bool IsConnectedAndReady { get; }

Property Value

Type	Description
bool

LocalPlayer

Gets the local player is never null but not valid unless the client is in a room, too. The ID will be -1 outside of rooms.

Declaration

public LocalNetworkPlayer LocalPlayer { get; }

Property Value

Type	Description
LocalNetworkPlayer

NetworkFactory

Gets or sets the factory used to create the INetworkClient peer.

Declaration

public INetworkFactory NetworkFactory { get; set; }

Property Value

Type	Description
INetworkFactory

PingInterval

Gets or sets the ping interval. Default value is 4 seconds.

Declaration

public TimeSpan PingInterval { get; set; }

Property Value

Type	Description
TimeSpan

RoomsInLobby

Gets a "list" that is populated while being in the lobby.

Declaration

public IEnumerable<RoomInfo> RoomsInLobby { get; }

Property Value

Type	Description
IEnumerable<RoomInfo>

Methods

ConnectAsync(NetworkEndpoint)

Connects the client to the specified matchmaking server asynchronously.

Declaration

public Task<bool> ConnectAsync(NetworkEndpoint serverEndpoint)

Parameters

Type	Name	Description
NetworkEndpoint	serverEndpoint	The matchmaking server endpoint.

Returns

Type	Description
Task<bool>	An a value indicating whether the connection was succeed or not.

Exceptions

Type	Condition
InvalidOperationException	You can't call Connect method while is connected to a matchmaking server. Call before to Disconnect() method. or ApplicationIdentifier must have a valid value before trying to connect.

CreateMessage()

Creates a new outgoing message.

Declaration

public OutgoingMessage CreateMessage()

Returns

Type	Description
OutgoingMessage	The create outgoing message.

CreateRoomAsync(RoomOptions)

Creates a new room on the server (or fails if the name is already in use).

Declaration

public Task<EnterRoomResultCodes> CreateRoomAsync(RoomOptions options)

Parameters

Type	Name	Description
RoomOptions	options	Contains the parameters and properties of the new room. See RoomOptions class for a description of each.

Returns

Type	Description
Task<EnterRoomResultCodes>	A value indicating if the operation was successful (requires connection to matchmaking server).

Remarks

If you don't want to create a unique room-name, pass null or "" as name and the server will assign a roomName (a GUID as string). Room names are unique.

This method can only be called while the client is connected to a matchmaking server. You should check IsConnectedAndReady before calling this method. Alternatively, check the returned boolean value.

Even when sent, the Operation will fail (on the server) if the roomName is in use.

While the matchmaking server is creating the game, the State will be Joining. The state Joining is used because the client is on the way to enter a room (no matter if joining or creating). It's set immediately when this method sends the Operation.

If successful, the client will enter the room. When you're in the room, this client's State will become Joined (both, for joining or creating it). Subscribe to ClientStateChanged event to check for states.

When entering the room, this client's Player Custom Properties will be sent to the room. Use CustomProperties to set them, even while not yet in the room. Note that the player properties will be cached locally and sent to any next room you would join, too.

Disconnect()

Disconnects this client from any matchmaking server and sets the ClientState if the connection is successfully closed.

Declaration

public void Disconnect()

DiscoverServers(int)

Starts the process to discover servers in the local network with the same ApplicationIdentifier, ClientApplicationVersion and port. Register to ServerDiscovered event to be know about discovered servers.

Declaration

public void DiscoverServers(int port)

Parameters

Type	Name	Description
int	port	The port.

Exceptions

Type	Condition
InvalidOperationException	ApplicationIdentifier must have a valid value before trying to connect. or You can't call discovery method while is connected to a matchmaking server. Call before to Disconnect() method.

JoinOrCreateRoomAsync(RoomOptions)

Joins a specific room by name. If the room does not exist (yet), it will be created implicitly.

Declaration

public Task<EnterRoomResultCodes> JoinOrCreateRoomAsync(RoomOptions options)

Parameters

Type	Name	Description
RoomOptions	options	Contains the parameters and properties of the new room. See RoomOptions class for a description of each.

Returns

Type	Description
Task<EnterRoomResultCodes>	A value indicating if the operation was successful (requires connection to matchmaking server).

Remarks

Unlike JoinRoomAsync(string), this operation does not fail if the room does not exist. This can be useful when you send invitations to a room before actually creating it: Any invited player (whoever is first) can call this and on demand, the room gets created implicitly.

If you set room properties in RoomOptions, they get ignored when the room is existing already. This avoids changing the room properties by late joining players. Only when the room gets created, the RoomOptions are set in this case.

If the room is full or closed, this will fail.

This method can only be called while the client is connected to a server. You should check IsConnectedAndReady before calling this method. Alternatively, check the returned boolean value.

While the server is joining the game, the State will be Joining. It's set immediately when this method sends the Operation.

If successful, the client will enter the room. When you're in the room, this client's State will become Joined (both, for joining or creating it). Subscribe to ClientStateChanged event to check for states.

When entering the room, this client's Player Custom Properties will be sent to the room. Use CustomProperties to set them, even while not yet in the room. Note that the player properties will be cached locally and sent to any next room you would join, too.

JoinRoomAsync(string)

Joins a room by roomName. Useful when using room lists in lobby or when you know the name otherwise.

Declaration

public Task<EnterRoomResultCodes> JoinRoomAsync(string name)

Parameters

Type	Name	Description
string	name	The name of the room to join. Must be existing already, open and non-full or can't be joined.

Returns

Type	Description
Task<EnterRoomResultCodes>	A value indicating if the operation was successful (requires connection to matchmaking server).

Remarks

This method is useful when you are using a lobby to list rooms and know their names. A room's name has to be unique (per game version).

If the room is full, closed or not existing, this will fail.

This method can only be called while the client is connected to a matchmaking server. You should check IsConnectedAndReady before calling this method. Alternatively, check the returned boolean value.

While the matchmaking server is creating the game, the State will be Joining. The state Joining is used because the client is on the way to enter a room (no matter if joining or creating). It's set immediately when this method sends the Operation.

If successful, the client will enter the room. When you're in the room, this client's State will become Joined (both, for joining or creating it). Subscribe to ClientStateChanged event to check for states.

When joining a room, this client's Player Custom Properties will be sent to the room. Use CustomProperties to set them, even while not yet in the room. Note that the player properties will be cached locally and sent to any next room you would join, too.

It's usually better to use JoinOrCreateRoomAsync(RoomOptions) for invitations. Then it does not matter if the room is already setup.

LeaveRoom()

Leaves the CurrentRoom and returns to the lobby.

Declaration

public bool LeaveRoom()

Returns

Type	Description
bool	If the current room could be left (impossible while not in a room).

OnDetach()

Invoked when the object is detached.

Declaration

protected override void OnDetach()

Overrides

Service.OnDetach()

SendToCurrentRoom(OutgoingMessage, DeliveryMethod)

Sends a user data message to the all remote players in the current room.

Declaration

public bool SendToCurrentRoom(OutgoingMessage messageToSend, DeliveryMethod deliveryMethod)

Parameters

Type	Name	Description
OutgoingMessage	messageToSend	The message to be sent.
DeliveryMethod	deliveryMethod	The delivery method.

Returns

Type	Description
bool	If the message can be sent to the current room (impossible while not in a room).

SendToPlayer(OutgoingMessage, RemoteNetworkPlayer, DeliveryMethod)

Sends a user data message to the a remote player in the current room.

Declaration

public bool SendToPlayer(OutgoingMessage messageToSend, RemoteNetworkPlayer remotePlayer, DeliveryMethod deliveryMethod)

Parameters

Type	Name	Description
OutgoingMessage	messageToSend	The message to be sent.
RemoteNetworkPlayer	remotePlayer	The remote player that should receive the message.
DeliveryMethod	deliveryMethod	The delivery method.

Returns

Type	Description
bool	If the message can be sent to the current room (impossible while not in a room).

SendToServer(OutgoingMessage, DeliveryMethod)

Sends a user data message to the matchmaking server.

Declaration

public void SendToServer(OutgoingMessage messageToSend, DeliveryMethod deliveryMethod)

Parameters

Type	Name	Description
OutgoingMessage	messageToSend	The message to be sent.
DeliveryMethod	deliveryMethod	The delivery method.

Update(TimeSpan)

Updates this instance.

Declaration

public override void Update(TimeSpan gameTime)

Parameters

Type	Name	Description
TimeSpan	gameTime	The elapsed game time since the last update.

Overrides

UpdatableService.Update(TimeSpan)

Events

ClientStateChanged

Occurs when this client's State is changed.

Declaration

public event EventHandler<ClientStates> ClientStateChanged

Event Type

Type	Description
EventHandler<ClientStates>

Remarks

This can be useful to react to being connected, joined into a room, etc.

CurrentRoomSynchronized

Occurs when a the current room is refreshed.

Declaration

public event EventHandler CurrentRoomSynchronized

Event Type

Type	Description
EventHandler

Remarks

This occurs only when the client is in the room.

MessageReceivedFromCurrentRoom

Occurs when a user data message from the current room is received by the client.

Declaration

public event EventHandler<MessageFromPlayerEventArgs> MessageReceivedFromCurrentRoom

Event Type

Type	Description
EventHandler<MessageFromPlayerEventArgs>

Remarks

This occurs only when the client is in a room.

MessageReceivedFromPlayer

Occurs when a user data message from a player in the same room is received by the client.

Declaration

public event EventHandler<MessageFromPlayerEventArgs> MessageReceivedFromPlayer

Event Type

Type	Description
EventHandler<MessageFromPlayerEventArgs>

Remarks

This occurs only when the client is in a room.

MessageReceivedFromServer

Occurs when a user data message from the matchmaking server is received by the client.

Declaration

public event EventHandler<MessageReceivedEventArgs> MessageReceivedFromServer

Event Type

Type	Description
EventHandler<MessageReceivedEventArgs>

RoomsInLobbySynchronized

Occurs when a the Room Info list is refreshed.

Declaration

public event EventHandler RoomsInLobbySynchronized

Event Type

Type	Description
EventHandler

Remarks

This occurs only when the client is in the lobby. This can be useful to refresh a list of available rooms.

ServerDiscovered

Occurs when a new matchmaking server with the same ApplicationIdentifier and ClientApplicationVersion is discovered. Occurs when a new matchmaking server is discovered

Declaration

public event EventHandler<HostDiscoveredEventArgs> ServerDiscovered

Event Type

Type	Description
EventHandler<HostDiscoveredEventArgs>

Implements

IDependencyObject

Extension Methods

ReflectionHelper.GetMemberAssembly(object)

ReflectionHelper.GetTypeName(object)