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)

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 games.

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. Be 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. The default value is 25 seconds.

Declaration

public TimeSpan ConnectionTimeout { get; set; }

Property Value

Type	Description
TimeSpan

CurrentRoom

Gets the current room to which this client is connected (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, who is never null but not valid unless the client is in a room. 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. The default value is 4 seconds.

Declaration

public TimeSpan PingInterval { get; set; }

Property Value

Type	Description
TimeSpan

RoomsInLobby

Gets a list that is populated while 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>	A value indicating whether the connection was successful or not.

Exceptions

Type	Condition
InvalidOperationException	You can't call the Connect method while connected to a matchmaking server. Call the Disconnect() method first. 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 created 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 the RoomOptions class for a description of each.

Returns

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

Remarks

If you don't want to create a unique room name, pass null or "" as the name, and the server will assign a roomName (a GUID as a 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 the 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 join as well.

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 the ServerDiscovered event to be notified 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 the discovery method while connected to a matchmaking server. Call the Disconnect() method before.

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 the 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 are ignored when the room already exists. This avoids changing the room properties by late-joining players. Only when the room gets created, are the RoomOptions 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 the 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 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 already exist, be open, and not full or cannot be joined.

Returns

Type	Description
Task<EnterRoomResultCodes>	A value indicating if the operation was successful (requires connection to the 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 does not exist, 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 (whether joining or creating). It's set immediately when this method sends the operation.

If successful, the client will enter the room. When you are in the room, this client's state will become Joined (both for joining or creating it). Subscribe to the 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 set up.

LeaveRoom()

Leaves the CurrentRoom and returns to the lobby.

Declaration

public bool LeaveRoom()

Returns

Type	Description
bool	Indicates whether 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 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	True 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 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 who 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 user data 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 for reacting to being connected, joining a room, etc.

CurrentRoomSynchronized

Occurs when 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 happens 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 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.

Declaration

public event EventHandler<HostDiscoveredEventArgs> ServerDiscovered

Event Type

Type	Description
EventHandler<HostDiscoveredEventArgs>

Implements

IDependencyObject

Extension Methods

ReflectionHelper.GetMemberAssembly(object)

ReflectionHelper.GetTypeName(object)