AppWarp S2 game server is composed of intuitive components (game room, zones etc.) that your application uses to interact with your game clients. The server application can modify/extend the component’s behavior through their interfaces and adaptors. The client side SDKs are used to interact with these server components from the client-side game application running on the end-user’s device.

Each game client must first connect with the game server. This is a prerequisite to your game play as this establishes an authenticated session with your game’s server side running over AppWarp S2. Before you call the connect API – you need to specify the application zone (identified by an appkey) and the host address (IP address or FQDN). These two are specified when you initialize the client side SDK (WarpClient) singleton. The connect API takes two arguments – a username and a string for authentication data. The username must be unique amongst the clients that are concurrently connected to the application zone. This is because its used to identify players in rooms and lobbies. If two clients try to connect with the same userid, then the first one will win and the earlier one is not allowed to connect. The authentication data parameter is useful if you are planning to employ custom server side authentication. For example you can pass a signed password or oauth token to your server side as the authentication data and then validate it on the server.

This is where all the game play happens. AppWarp SDK provides APIs to join/leave, subscribe/unsubscribe, edit room properties etc. A user can at a time be present only in one room. So if a user joins a room and then requests to join another room – it will be removed from the former. The number of users in a room and other meta information about a room can be retrieved using the getLiveRoomInfo api. A room has three required static properties that are required at the time of its creation.

• maxUsers property of a room determines how many users a room can accomodate concurrently. If a room is full, and a user tries to join it, the room join request will fail.
• room name property can be used by developers to give a user friendly display name associated with the room.
• room owner property of a room can be used by developers to manage access to a room based on the locally connected user. For example only if the current user is the same as the owner of a room – allow it to delete the room. The implementation and usage of this room owner property is up to the developer.

There are two kinds of rooms in appwarp cloud (differ in their lifetime).

• Static room

These are the rooms that the developer can create from inside dashboard. Such rooms will never get automatically destroyed unless the developer deletes them through the console. These are particularly useful when you have a fixed number of rooms in your game. These rooms are persisted on the server in an HSQL database that you specify in the server configuration file. This allows the server to reload these rooms even if you stop and restart the server application.

• Dynamic room

These are the rooms that are created by invoking the create room client SDK api. Such rooms are not persisted in the HSQL database on the server and thus are lost if the server application is restarted. when the last joined user in such a room will leave. These rooms can also be deleted programmatically from the client-side SDK as well as the server side SDK.

Once users have joined a room, they can use APIs to send string based chat messages or byte array update peers. These apis result in a broadcast of the message to all users that have subscribed to the room. These apis are where you build the realtime multiplayer interactions for example sending each other your players coordinates, moves etc.

• Turn Based room

These are special kind of dynamic rooms. These rooms are designed for turn based rooms where the users have a fixed amount of time allotted to make their move, else the turn passes to the next user. Only on a users turn, is it allowed to send a move request to the server. Once the move changes, the server issues an automatic notification onMoveCompleted to all the subscribed users of the room with the move meta data and the next player whose turn it is. The server-side component takes care of all the synchronization and timer logic. Developers can modify and extend the server side behavior to suit their game’s logic. This is also illustrated in the Rummy cards game samples described in the samples section.

Difference between joining and subscribing a room

When a user joins a room, it becomes a part of it, i.e. it can interact with other players in that room by sending chat messages and update peers. But to be able to receive notifications for such actions from other players, a user needs to subscribe to that room.

This differentiation gives you another feature where in a user can observe a rooms events like a spectator without actually taking part in the game room. By default, when a user joins a room its automatically also subscribed to it. You can then alter the subscription status by using the subscribe/unsubscribe APIs.

A lobby is a special kind of room which is automatically created when your app is created. It can be used to build experiences where users can hang around and chat with each other without actively playing in one of the game rooms and still being connected to your game in AppWarp. So if a user is unable to find a room to play in or is waiting for one of its buddies to join – he/she can wait in the lobby. Subscribing to a lobby is different than subscribing to a room. When a user subscribes to a lobby – it will in addition to the lobby specific notifications, also receive user join/leave and create/delete notifications from all other rooms as well. This is much like how in a real home, if you are in the lobby – you can see who is leaving and entering in the adjacent rooms. Similar to rooms, a user can not simultaneously be joined to a room and a lobby. If a user is joined to a lobby and then joins a room, it will be removed from the lobby. Using a lobby in your game is optional.

AppWarp client SDKs follow a request/response/notification asynchronous model. For each api request made from the client, a response is generated from the server. The responses are delivered on the corresponding request listeners registered with AppWarp client. This is using the standard Observer Pattern. For example, the response for a room join request will be delivered as a event to the registered room request listeners.

To receive notifications, one has to subscribe to the resource. Once subscribed, the server will send the notifications related to the resource to all the subscribed clients. On the client side, the SDK will deliver all the notifications it receives to the registered notification listeners (similar to request listeners) again using the standard Observer Pattern. For example if you have subscribed a room and have added a notification listener to WarpClient, whenever a joined user sends a chat message, the OnChatReceived event on the notification listener will be invoked. The event has information about the the resource (room id in this case) which generated the event and the event data itself (chat message in this case).