Multiplayer Reference
Class Game<P>
Namespace: PlayerIO.GameLibrary
Language: C# / .NET
The base class for all Player.IO Games. Inherit from this class to build your game.
The Game class is the main serverside class of a Multiplayer Game. It contains methods that are called when messages are received, when players joins or leaves the game, and methods to interact with the players that are in the game.
It's an abstract class, so you must create your game by inheriting from it.
The Game class is also generic which means that it's parameterized and must be told what class is used to represent a player connected to a game. The player class must inherit from PlayerIO.GameLibrary.BasePlayer.
Example
Here is a simple bare-bones game and player implementation that simply broadcasts all received messages to all connected users. A bounce server if you will.
Properties | |||
|---|---|---|---|
| public bool |
True if the game is currently running in the development server, False if the game is running in production. |
||
| public virtual int |
How many players are currently connected to this game room. |
||
| public Client |
Access to the Player.IO webservices |
||
| public IEnumerable<P> |
An enumerable list of all the players connected. Use foreach to loop over all the players. |
||
| public bool |
Should new Player objects have their .PayVault objects loaded before they join the game?. |
||
| public bool |
Should new Player objects have their .PlayerObject loaded before they join the game?. |
||
| public RoomData |
The data for the room. Room data is given when the room is created, returned when rooms are listed, and can be changed by the serverside game code. |
||
| public string |
The id of the current room. This is the same id that would be used when calling JoinRoom(...) from a client. |
||
| public bool |
If the room is visible when listing rooms. Can be changed by your game code on the server. |
||
Methods | |||
| public Timer |
Creates a new timer for calling a specified method at some interval. |
||
| public virtual bool |
Called whenever a player attempts to join: If you override this method, simply return true to allow the join, and false to disallow the join. If you don't override it, it will allow everyone by default. |
||
| public void |
Broadcast a message to all connected players |
||
| public void |
Broadcast a message to all connected players |
||
| public virtual void |
This method is called when a game is closed. |
||
| public virtual void |
This method is called when a game is created. |
||
| public virtual Image |
Generate an image that can be displayed in the development server |
||
| public virtual void |
Called when data is received from the player. |
||
| public void |
Causes the development server to display the image returned by GenerateDebugImage(); |
||
| public Timer |
Schedules a one-time callback in the future |
||
| public virtual void |
Called by the hosting server (in the production game server cluster) when it enters the NoJoin state. The game should take action accordingly. |
||
| public virtual void |
Called whenever a client has joined the room. |
||
| public virtual void |
Called whenever a client leaves the room. The room is closed when the last person leaves the room. |
||
InDevelopmentServer
True if the game is currently running in the development server, False if the game is running in production.
Return Value
PlayerCount
How many players are currently connected to this game room.
Return Value
PlayerIO
Access to the Player.IO webservices
Return Value
Players
An enumerable list of all the players connected. Use foreach to loop over all the players.
Return Value
PreloadPayVaults
Should new Player objects have their .PayVault objects loaded before they join the game?.
Return Value
PreloadPlayerObjects
Should new Player objects have their .PlayerObject loaded before they join the game?.
Return Value
RoomData
The data for the room. Room data is given when the room is created, returned when rooms are listed, and can be changed by the serverside game code.
Return Value
Example
RoomId
The id of the current room. This is the same id that would be used when calling JoinRoom(...) from a client.
Return Value
Visible
If the room is visible when listing rooms. Can be changed by your game code on the server.
This property is useful when you want to create a room, spend some amount of time setting it up, and when that is done mark it as visible for others who list rooms.
Return Value
AddTimer
Creates a new timer for calling a specified method at some interval.
Arguments
| Action | callback |
| The method to be used for callbacks. Example usage: delegate(){ Console.WriteLine("called"); } | |
| int | interval |
| The interval in milliseconds between callbacks |
Return Value
| Timer | |
AllowUserJoin
Called whenever a player attempts to join: If you override this method, simply return true to allow the join, and false to disallow the join. If you don't override it, it will allow everyone by default.
Note that the user has not fully joined the game when this method is called, so Broadcast messages won't reach the user.
Arguments
| P | player |
Return Value
| bool | |
Broadcast
Broadcast a message to all connected players
Arguments
| string | type |
| the type of the message to broadcast | |
| params object[] | parameters |
| the data of the message to broadcast |
Broadcast
Broadcast a message to all connected players
Arguments
| Message | message |
| the message to broadcast |
GameClosed
This method is called when a game is closed.
GameStarted
This method is called when a game is created.
GenerateDebugImage
Generate an image that can be displayed in the development server
Return Value
| Image | |
GotMessage
Called when data is received from the player.
Arguments
| P | player |
| Message | message |
RefreshDebugView
Causes the development server to display the image returned by GenerateDebugImage();
ScheduleCallback
Schedules a one-time callback in the future
Arguments
| Action | callback |
| The method to be used for callbacks. Example usage: delegate(){ Console.WriteLine("called"); } | |
| int | dueTime |
| The offset time in milliseconds for the timeout. Example: 1 second in the future is 1000 |
Return Value
| Timer | |
ServerEnteredNoJoin
Called by the hosting server (in the production game server cluster) when it enters the NoJoin state. The game should take action accordingly.
In order to support updating the system without abruptly ending games, rolling restarts are used which moves servers through 3 states:
- Live: Games can be created/joined and everything is perfect.
- NoCreate: No new instances can be created on the server (they'll just be created on any of the many other servers in the player.io cluster).
- NoJoin: Nobody can join the instances running on this server.
Servers will start in Live. When the system requires an update, the server will enter NoCreate and stay there for many hours (12-24). By then, most of the instances will have closed by natural causes (players leaving the games) and very few games will be left on the server.
The server then enters NoJoin where nobody can join the last few remaning instances. The NoJoin state lasts for about 6 hours, which gives the last few remaining games time to finish. The server will then shutdown where it's highly unlikely that any games remain.
Since potentially games might still be running at the end of NoJoin (although it's highly unlikely), the ServerEnteredNoJoin method is called whenever the server changes state into NoJoin.
This gives games the flexibility to handle the rolling restarts in a manner suited to their game. Only persistent games (MMO's) will need to use this method, and the most likely usecase is that they send out a "zone under maintenence, please reconnect" message to their client code, which simply rejoins the zone which will then be created on another server.
UserJoined
Called whenever a client has joined the room.
Arguments
| P | player |
UserLeft
Called whenever a client leaves the room. The room is closed when the last person leaves the room.
Arguments
| P | player |