Basic Concepts

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

Introduction

Top

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
applications users to interact in virtual rooms and lobbies. It provides APIs to perform operations such as
joining a room, subscribing for notications, sending chat messages and generic byte arrays to exchange
game specic data. All this allows you to easily build real-time multiplayer applications such as card games,
board games, rst person shooter games etc.

Connecting with the cloud

Top

This is a prerequisite to your game play. It establishes an authenticated session with your games 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 rst 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 players 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 rewall 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 applications manifest

Rooms

Top

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 (dier 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 xed 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 rooms 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 xed 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 notication 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 dont need to worry about it on the client side.
Dierence 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 notications for such actions from other
players, a user needs to subscribe to that room.
This dierentiation gives you another feature where in a user can observe a rooms events like a spectator
without actually taking part in the game room.

Lobby

Top

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 nd 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 dierent than subscribing to a room. When a user subscribes to a lobby it will in addition to the
lobby specic notications, it also receives user join/leave and room create/delete notications 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.

Request/Response/Subscription Model

Top

AppWarp client SDKs follow a request/response/notication 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 notications, one has to subscribe to the resource. Once subscribed, the server will send the
notications related to the resource to all the subscribed clients. On the client side, the SDK will deliver all
the notications it receives to the registered notication listeners (similar to request listeners) again using
the standard Observer Pattern. For example if you have subscribed a room and have added a notication
listener to WarpClient, whenever a joined user sends a chat message, the OnChatReceived event on the
notication 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).

AppWarp billing

Top

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 apps 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 notication to all 3 players in the room from the server (3 messages)
Hence a total of 5 messages.
We dont believe in billing based on CCUs (Concurrently Connected Users) as we feel this is unfair to the
developers. For instance if your games 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.