## Chapter 23. Multiplayer Example

## Introduction

Multiplayer Example is the simplest possible example for demonstrating how to initiate a multiplayer game with the new framework provided by `XFuBluetoothMultiNetwork`. The example has two to four 'players' who ignite light bulbs that are seen on other devices in the game. The purpose of the example is to show how to initiate a multiplayer game and how to send the state over the air to other game participants.

The Multiplayer Example uses the standard X-Forge network architecture with the network communication classes, data receivers, serializable packets etc. All the packets that are used to implement the game are defined in `Packets.h`. Each packet type is implemented as a class that inherits from a base packet class called `Packet`.

Most of the multiplayer functionality is implemented in the multiplayer handler class (`MultiPlayerHandler`). The multiplayer handler handles the participant discovery, session initialization and handshaking, game state updates and disconnection.

Multiplayer Example shows also how to build the communication so that it works in both Bluetooth and Inet networking environments. A majority of the multiplayer code doesn't care if the network type is Bluetooth or Internet. Only one type at a time is supported, and this is selected using a preprocessor definition. Currently, only two X-Forge platforms are supported: desktop Windows and Symbian. If the application is for desktop Windows, Internet is used and `NETWORK_TYPE_INET` is defined, otherwise `NETWORK_TYPE_BT` is defined.

The number of players in the example has been limited to four, but in theory, it is possible to create eight-player multiplayer games with the `XFuBluetoothMultiNetwork`. However, in normal fast paced 3D game, having eight players in the game will more than double the amount of sent traffic compared to four players. That may be too much for Bluetooth's bandwidth.

The Multiplayer Example uses the following terms in classnames and comments:

- Initiator - Game server or host which sends the connection initiation packet to all the other participants. Game server here isn't necessarily listening for connections, it just works as a logical hub of the game data among all participants
- Participant - Game client which waits for the initiator to send the handshake packet.

## About XFuBluetoothMultiNetwork

The new multiplayer framework in the `XFuBluetoothMultiNetwork` works in reversed client-server relation to the `XFuBluetoothNetwork`. This is due to the Bluetooth networking architecture which allows only one incoming connection to the terminal. In the `XFuBluetoothNetwork` the game host works as a Bluetooth slave, listening for incoming connections like in the traditional networking architecture. The game client i.e. the Bluetooth master terminal connects to the game server and the multiplayer game is initiated. Using the same approach with more than 2 players in the game would be impossible, because Bluetooth slaves accept only one incoming connection and that is from the particular Bluetooth master terminal, whose Bluetooth band they are in. In the new framework the game server connects to client, i.e. game server sends the connection initiator packet to the clients.

The new multiplayer network is star-shaped system, where the game server (the Bluetooth master terminal) connects to all the game participants (the Bluetooth slave terminals). The next problem is how the game server should know which clients to connect. In the `XFuBluetoothMultiNetwork` the game clients advertise themselves to the game server with SDP protocol. The game clients have to be started before the game server. This is to get the SDP advertising set up before the game server starts its service discovery. After a successful discovery the game server has a list of available game clients. It shows the list to the user who can select which participants will be accepted to the game. When the names have been selected, the game server connects to the clients and the game may begin.

Good and compulsory reading for all X-Forge networking programmers is the Multiplayer Games chapter in Game Engine part.

## Game Flow

### Session Initialization

Using Bluetooth, the game initiator uses the Bluetooth native service discovery protocol to search for available game participants. This is presented to the multiplayer handler in the same way as when using Internet. Using Internet as the network type, participant discovery works so that all the participants turns on the advertiser and the game initiator detects all advertisers and maintains a list of these, which is then displayed in the user interface.

Once the game initiator selects all participants from the user interface, it starts sending game connect packets to them. The game connect packets include a game connect token, which is a magic token that must match the game connect token on the participant. If the token is invalid, the participant will quietly reject the connection request from the initiator.

When the participant receives a valid game connect token, it accepts the initiator and sends a handshake packet to the initiator and stops the advertiser. When the initiator receives the handshake packet it sends a game init packet back to the participant telling his playerID and the number of 'players' in the game. Every participant has a connection state which will be updated to CONNECTED state when the game initialization packet has been sent.

### The Gameplay

During the gameplay, the game clients send their state to the game server every 250 milliseconds. The server propagates these and its own state among all clients.

### Ending a Game

A game client can exit the game at any time. When this happens, the client sends a disconnect packet to the game server to inform it that it has left the game. This is handled in exactly the same was as if the connection was lost for some technical reason. When game client disconnects, and there are still left players in the game, the game continues until there are no other participants left.

Currently, disconnect packet's aren't propagated from server to other participants. The disconnected state of a participant is shown in ledState variable that is propagated among all participants by the server.

## Class Overview

The following briefly describes the roles of the classes in the example:

- `MultiPlayerExample` defines the main application and its state changes
- `MainMenuScreen` implements the main menu of the game
- `ConnectingScreen` implements the participant list in the host
- `GameScreen` implements actual 'game' output
- `Packet` defines the types of packets that are sent over network
- `MultiPlayerHandler` the main multiplayer functionality class
- `ClientListEntry` defines an entry in the client list in the `ConnectingScreen`
- `ClientStateEntry` represents the state of one client that there is a connection to
- `GameState` represents the state of the light bulbs
- `UIImageFactory` defines methods for drawing buttons and checkboxes for the example
- `Screen`Basic screen and user interface functionality

|  | X-Forge Documentation Confidential Copyright © 2003 Fathammer