## DirectPlay Lobby Overview

A DirectPlay lobby server is a common place on a network that (at a minimum) tracks DirectPlay application sessions in progress, and users that are connected to the server. Users can navigate around the lobby server to find areas of interest. At any location on the lobby server, the user can chat with other users, join sessions that are in progress, or gather a group of players to start a new session.

This section discusses the following topics.

- DirectPlay Lobby Architecture
- Lobby Sessions
- Lobby Navigation
- Synchronized Launching

A lobby server's main advantage is that it acts as a central, well-known location where users can go to find sessions and other people to interact with. The lobby server manages all the network addresses of the various players and sessions and can automatically manage launching applications and connecting them to the correct address without user intervention. The management of sessions, players, and their network addresses is especially useful on the Internet, where users generally can't find opponents or get applications connected in a session easily. It also has the advantage of launching application sessions for the user without the user having to enter any network configuration information.

Lobby servers can be greatly enhanced to provide more services to the user, such as tournaments, individual score tracking and high scores, personal profiles, avatars, message boards, news, a broader user interface, authenticated membership, software updates, and so on.

A lobby-aware application is one that has been specifically developed to operate with lobby servers. There are two types of lobbies that a user can experience. An external lobby is a client application whose sole purpose is to interact with a lobby server and the other users connected to it. When the time comes to start or join an application session, the lobby client launches the application in a separate process and gives it all the information necessary to establish a connection to the session. Adding support for external lobby launching to a DirectPlay application is quite straightforward and explained further in Supporting External Lobby Launching.

An internal lobby is a lobby user interface that is integrated into the application itself. This is more difficult to implement because the application must implement the user interface for the lobby as well as that for the game. However, it has the advantage that you can customize the lobby experience to match the application's theme.

### DirectPlay Lobby Architecture

The DirectPlay lobby architecture consists of a client API that all applications, whether they are external lobby clients or applications that have a lobby client built in, use to connect to any DirectPlay-compliant lobby server. This is done through a lobby provider interface that, like a service provider, abstracts the interaction with the lobby server. The author of the lobby server application must write the lobby provider that resides on the client computer. The application calls the standard DirectPlay APIs, and the lobby provider's dynamic-link library (DLL) services these methods by communicating with the lobby server software.

The following diagram illustrates the DirectPlay lobby architecture. Different lobby client applications can connect to the same lobby server through the DirectPlay API.

At the very least, the lobby server must be able to track all the users currently connected to it, organize those players by grouping them, and synchronize the launch of an application session.

The DirectPlay API defines a common level of functionality for all lobby servers. Any generic lobby client application can connect to any generic lobby server and, through the DirectPlay API and the lobby provider architecture, they can interoperate successfully. An application can extend the basic functionality with the Send and Receive methods. A lobby client designed to work with a specific lobby server can implement extended functionality that is not defined by the DirectPlay API.

There is no separate API to communicate with a DirectPlay lobby server. Interaction with a lobby server has been abstracted so that the same IDirectPlay3 interface used to communicate in an application session can be used to communicate with the lobby server. Additional methods and messages have been added to the interface to support the additional functionality that a lobby server requires.

By using the same DirectPlay methods to interact with the lobby server, it is simple to add a lobby client interface to an application, because the same APIs and concepts are being leveraged.

### Lobby Sessions

A lobby session closely resembles a DirectPlay client/server session (see the illustration in Client/Server Session). The term lobby session refers to a connection to a lobby server where clients and the server have not been specifically written to interoperate. The term application session refers to a traditional DirectPlay session in which all the clients and the server (if any) have been specifically written to interoperate.

A DirectPlay lobby session is used to represent a connection to a lobby server. Like a DirectPlay application, the first step in using DirectPlay to communicate with a lobby server is to select which lobby provider to use and which lobby server to connect to. Like a DirectPlay application, the IDirectPlay3::EnumConnections and IDirectPlay3::InitializeConnection methods are used to do this.

The lobby client uses the same session management methods as an application client to locate and to join a lobby session; for example, EnumSessions, Open, SecureOpen, and Close. Joining a lobby session gives the client application access to all the information on the lobby server and enables the user to interact with other users on the lobby server.

Like a DirectPlay application session, the player is the basic entity in a lobby session. Each player represents a user on a client computer connected to the lobby server. There is also the server player representing the lobby server. After a lobby client connects to a lobby server (by joining the lobby session), it must establish the user's presence by creating a player and adding the player to an initial group before the player can start communicating with the server and other players. In fact, other users connected to the session won't even be aware of the new user's presence until this happens.

The same player management methods used by application sessions are used to manage players in a lobby session; for example, EnumPlayers, CreatePlayer, DestroyPlayer, GetPlayerName, SetPlayerName, and GetPlayerCaps.

Unlike a DirectPlay application session, Send and Receive generally cannot be used to exchange messages with other players. In the DirectPlay lobby architecture, any application that uses the DirectPlay API can connect to any lobby server. This means that many different lobby client applications might be present in the same lobby session, all of which were written by different developers. Simply sending a message to another client player or the server player does not guarantee that it will be interpreted correctly by the recipient application.

Common functions that require communications between clients and the server have new methods created for them. DirectPlay determines the message's format. The recipient receives a system message containing the content of the message in a well-defined data structure. For example, the IDirectPlay3::SendChatMessage method sends a text chat message to another player.

Groups take on more significance in a lobby session, because they are used to define the organization of the entire lobby server and for launching application sessions. You can create a complete hierarchy of groups to manage and organize all the players and sessions that the lobby server tracks.

For the purposes of the lobby server, groups are classified as one of two types. A standard group can contain players and other groups and is called a room. A room is primarily used as a meeting place for players to interact with other players in the context of the lobby. The room contains links to other rooms and links to the second type of group—a staging area.

A staging area group typically contains only players. A staging area is used to marshal players together in order to launch a new session. After the session has been launched, the staging area can remain in existence so that new players can join the session in progress.

Room groups are organized primarily in a hierarchical structure. A few top-level groups are created and other groups are created within existing groups. The lobby client can enumerate all the top-level groups as well as the groups contained within a group. The lobby server can also organize the groups in a web structure. Once a group is created, you can add it to another group, which creates a link between the two groups. When a lobby client enumerates groups within a group, all subgroups and linked groups are returned.

The following diagram illustrates the organization of a lobby session.

Players can be seen only in groups. They cannot be seen until they are part of a group. Players can belong to more than one group at once.

### Lobby Navigation

Players can navigate through the lobby server space simply by deleting themselves from their current group and adding themselves to a new group. At any time, the IDirectPlay3::EnumGroupsInGroup method can be called to determine what groups are linked to the current group.

In general, the scope of the lobby session visible to a player is limited by the groups the player is part of. This is done to limit the amount of information that the server must download to the client.

### Synchronized Launching

Application sessions are marshaled and launched from a staging area. One player creates a staging area and waits for other players to join it. A player can set the properties of the application session to be created through the IDirectPlay3::SetGroupConnectionSettings method. Other players who are considering joining the group can find out what the application session properties are by calling the IDirectPlay3::GetGroupConnectionSettings method. After enough players have joined the staging area, any player can call the IDirectPlay3::StartSession method to initiate the synchronized launch sequence. Every player in the staging area groups receives a DPMSG_STARTSESSION system message with a DPLCONNECTION structure. If the player is using an external lobby client, it can launch the application by using the IDirectPlayLobby2::RunApplication method. If the player is using an internal lobby, the application can use the information to establish a connection to the appropriate session by calling IDirectPlayLobby2::Connect.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.