• Introduction
• Connecting with the cloud
• Rooms
• Lobby
• Request/Response/Subscribe SDK model
• AppWarp Billing

AppWarp is a cloud container for your realtime multiplayer games and applications. It sandboxes applications based on their API keys. AppWarp client-side SDKs expose the powerful constructs for the application’s users to interact in virtual rooms and lobbies. It provides APIs to perform operations such as joining a room, subscribing for notifications, sending chat messages and generic byte arrays to exchange game specific data. All this allows you to easily build real-time multiplayer applications such as card games, board games, first person shooter games etc.

This is a prerequisite to your game play. It establishes an authenticated session with your game’s container on the AppWarp cloud service. There are two things to understand here. The client requesting the connection with your games cloud container is authenticated using the API Key and Secret Key that is given when the SDK is initialized. If the API key and Secret key pair given in initialize is incorrect, it will lead to an authentication error. The other thing to note is the userid passed as a parameter when connecting to your cloud container is always unique amongst the clients that are concurrently connected to your container as 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 second one will get an authentication error. It is up to the developer to ensure uniqueness of userids when connecting. For example – you can use the player’s facebook id to guarantee this or use the App42 user service.

Troubleshooting Connection failed issues

• Verify that your app is of type Warp cloud as mentioned here
• Verify that the client is not behind a firewall that blocks outgoing connections to port 12346 (AppWarp cloud servers listen on this port)
• If using Android, ensure that you have added internet permission to your application’s manifest

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 three kinds of rooms in appwarp cloud (differ in their lifetime).

• Static room

These are the rooms that the developer can create from inside AppHQ console (developer 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. AppHq console will display the properties that the room was created with and not necessarily the current properties of the room as they can be changed through client SDKs.

• Dynamic room

These are the rooms that are created by invoking the create room client SDK api. Such rooms will automatically get destroyed if they remain empty for 60 minutes. These room’s properties are also dynamic and can be updated or removed through out its lifetime through the update room properties API.

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 takes care of all the synchronization and timer logic and developers don’t need to worry about it on the client side.

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.

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 the lobby is different than subscribing to a room. When a user subscribes to a lobby – it will in addition to the lobby specific notifications, it also receives user join/leave and room 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).

Details of our plans can be found on our pricing page. In a nutshell, developers get billed based on their usage of AppWarp. As the primary cost driver is bandwidth, we bill developers based on the number of messages their app exchanges with the AppWarp server. So this is the sum of messages sent plus the number of messages received.

We identify your app through the API Key and Secret Key you use to initialize the SDK and the session (once connected) then gets associated with your app. We then sum over the messages exchanged during the lifetime of the session and add them to your app’s usage.

Lets take an example of a 3 player game room with players A, B and C in it. Now if player A sends an updatePeers request to the room, the following messages are counted –

->Request from A to the server (1 message)
->Response from server back to A (1 message)
-> onUpdatePeersRecieved notification to all 3 players in the room from the server (3 messages)

Hence a total of 5 messages.

We don’t believe in billing based on CCUs (Concurrently Connected Users) as we feel this is unfair to the developers. For instance – if your game’s average CCUs is 25 but occasionally on weekends your CCUs spike to 100, you will end up buying a 100 CCU package just for those couple of days in a month.