Persistent Room Properties
Properties is a collection of data associated with a room in the form of key-value pairs. If a user wants to create a room for a specific purpose or associate any meta data with it, he can specify this as a collection of properties. For example you want to create a room according to the user’s level, then you would add <”level”,”beginner”> as a property and pass that to the createRoom api.
Once created, you can always add or update a room’s properties as well.
- roomId Id of the room.
- tableProperties Properties as key-value pair that will be set for the room.
- removeArray Properties that will be removed for the room
This API updates the properties associated with the given room on the server. The result is provided in the onUpdatePropertyDone callback of the RoomListener. All subscribed users will also receive a notification when this happens in the onUserChangeRoomProperty callBack of the NotificationListener.
Appwarp gives developers APIs that allow a user to place a lock on a property. While a property is locked by a user, any other client request to update or lock that property will fail. Only users who are currently inside the room can lock it’s properties. For locked properties there is a table in the room which maintain all locked properties and the lock owner’s name. If a user leaves the room then the properties locked by that user are automatically unlocked. This is extremely useful in solving distributed synchronization issues.
Lets take an easy arbitration game example:
Rules are: every room has max n(4 here) users. To play the game every user have to select an avatar. If any user have selected an avatar no other user can select the same. If any user leaves the room then his avatar is again available.
This problem can be easily solved using lock property concept of appwarp.
- Create room with max four users.
- Define four properties corresponding to the avatars.
- User joins the room and is presented with the list of available avatars (unlocked properties).
- If a user selects any avatar then lock this property for this user.
- When a user leaves room then locked property by this user will automatically be unlocked.
- properties properties to be lock in joined room
Sends a lockProperties request to the server. Result of the request is provided in the onLockPropertiesDone callback of the RoomRequestListener.
- unlockProperties key of properties to be unlock in room`
Sends a unlockProperties request to the server. Result of the request is provided in the onunlockPropertiesDone callback of the RoomRequestListener.
To filter rooms based on properties, developers can use the following API.
- properties Properties of the room to be joined.
This retrieves information of all the rooms that contain the specified properties from the server. Result is provided in the onGetMatchedRoomsDone callback of the ZoneListener. It is useful in filtering rooms if your game can have a large number of game rooms.
Lets say your game has multiple rooms with different properties (e.g. level) Now when a player logs in and you want him to join any room with “intermediate” level, you will need to use the following method by adding <”level”, “intermediate”> to the properties collection :
- tableProperties Properties of the room to be joined
It sends a join room match making request to the server. Result of the request is provided in the onJoinRoomDone callback of the RoomListener
Lets say you are developing a game and the game can only start once all n players have joined the game room. To support a quick-play mode in which users can immediately join a game with random players and start playing, you will need to do the following:
- Get a list of all rooms
- Get information of each room one by one
- For each room; check the number of players in the room.
- Continue till a room with n users is found.
- Join the room so that the room has n players now and the game can start.
This can be solved using a single match-making APIs call
- minUsers Number of minimum users in room to be joined`
- maxUsers Number of maximum users in room to be joined`
- maxPreferred flag to specify search priority for room to be joined`
Sends a join room match making request to the server with the criterion being that at least minUsers and at most maxUsers must be present in the room to be joined. Result of the request is provided in the onJoinRoomDone callback of the RoomListener.
- minUsers minimum number of users in the rooms`
- maxUsers maximum number of users in the rooms`
Retrieves information of the rooms that contain at least minUsers and at most maxUsers in them. Result is provided in the onGetMatchedRoomsDone callback and is useful in fetching a filtered list of rooms.
- A room has a property table size limit of 2048 bytes (calculated by considering properties as a JsonObject) If the developers adds more properties which exceed this limit, it will result in a failure with WarpResponseCode = 7 // size issue
- There are also constraints on methods which get lists of room data with matchmaking (getRoomWithProperties and getRoomInRange) filters. The size of the list containing the room data will not exceed 100. These are there so that the size of the messages exchanged between the client and the server are not too large.
Tip: Defining properties is important and should be clearly thought through while designing your game. Keep the properties required to a minimum and avoid using long strings as keys or values.
We have added simple android application which illustrates the use of match making APIs. It can be similarly done for all other SDK flavors. View Code