SFS2X Docs / AdvancedTopics / game-api

» The Game API

SmartFoxServer 2X provides a new set of client and server API specifically designed for game creation and management, including public and private games, game invitations, User and Room matching and lots more. The new Game API are based on three fundamental building blocks:

These three components are highly versatile and can be either used singularly for a specific task or orchestrated together to create advanced server behaviors, as you will learn with the Game API.

» Overview

The easiest way to introduce the new Game API is by briefly presenting each of the components in the framework.
Just as a reminder, the SmartFoxServer class exposes a getAPIManager() method which in turn allows you to access all the different API in the SFS2X framework.

APIManager provides:

Match Expressions

Match Expressions are built like "if" conditions in any common programming language: they work like queries in a database. Here's a Java example to get you started: 

 
MatchExpression exp = new MatchExpression('rank', NumberMatch.GREATER_THAN, 5).and('country', StringMatch.EQUALS, 'Italy')

Expressions are made of three elements:

Additionally any number of expressions can be linked together with a logical AND / OR operator, just like in regular code. In the above example we have created an expression that will check for a rank value > 5 and a country value == "Italy".

But... where is this set of conditions applied to? Normally expressions are used to match Users (via their User Variables) and Rooms (via their Room Variables). The standard SFS2X API provide two useful methods called findUsers() and findRooms() where you can execute any MatchExpression and obtain the filtered set of Users/Rooms.

A small example will clarify this better: 

 
List<User> matchingUsers = sfsApi.findUsers(zone.getUserList(), exp, 50);

The first argument provides a List of Users where to search, in this case all Users inside the current Zone. The second parameter is the expression we just created at the beginning of the article, and the last number (50) is an optional limit for the amount of returned elements. In this case we want the search for no more than 50 matching elements. (If we passed 0 the serach would return all Users that match)

The search options are not just limited to User/Room Variables name. In fact the Matching engine provides two extra classes, RoomProperties and UserProperties, where you can access many specific attributes of the Room and User class.

This is an example of matching specific Room properties and Variables:

 
// Prepare match expression
MatchExpression exp = new MatchExpression(RoomProperties.IS_GAME, BoolMatch.EQUALS, true).and
					(RoomProperties.HAS_FREE_PLAYER_SLOTS, BoolMatch.EQUALS, true).and
					("isGameStarted", BoolMatch.EQUALS, false);
 
// Search Rooms
List<Rooms> joinableRooms = sfsApi.findRooms(zone.getRoomListFromGroup("chess"), exp, 0);

The above code will match all game Rooms that have at least one free player slot and where the isStarted variable is set to false. Additionally the search will be performed only in the Room Group called "chess".

» Advanced features

The Match expression offer advanced capabilities for searching through nested data structures such as SFSObject and SFSArray. This is done via a very simple dot-syntax expressions. Here's an example of how it works: 

 
MatchExpression exp = new MatchExpression("europe.italy.capital", StringMatch.EQUALS, "Rome")

The above example goes down deep into an SFSObject called europe, taking the italy object (another SFSObject) and finally reading its String field capital and matching it with another String. Here is one more examples using SFSObject and SFSArray: 

 
MatchExpression exp = new MatchExpression("europe.italy.majorCities.3.name", StringMatch.EQUALS, "Milan")

From the italy object we obtain a majorCities SFSArray and we grab the third item in it (the .3 expression means 'give me the element at index == 3'). The item is again an SFSObject whose name property we finally compare to a String.

The power of Match Expression doesn't end here. You can run multiple passes of matching if you need complex searches to be performed. For example you can run a first match and obtain a list of filtered Rooms and then use it to apply another expression to further refine your search, and so on and so forth.
Also you will learn more interesting usages of Match Expressions in conjunction with the SFSGame class later in this very article.

For more details on Match Expression we recommend to consult the javadoc, under the com.smartfoxserver.v2.entities.match package

Invitations

The invitation system included in SFS2X provides a generic framework for sending invitations to one ore more connected User(s) and easily manage their responses and the expiry of the invitation itself. Invitations can be used to challenge players in a game, invite buddies to the User's place, ask permissions for specific task such as adding the invited User in the Buddy List etc...

Creating an invitation is very simple, four basic parameters are needed:

Invited Users can reply to the invitation with

The invited User will receive the invitation and will be able to reply within the specified amount of time. A simple ACCEPT or REFUSE code is all it takes to reply plus an optional SFSObject with response parameters, if needed. In case no response is sent to the server within the expected number of seconds, the invitation will be considered as "refused".

For more details about Invitations check the javadoc, specfically the SFSGameAPI class and the com.smartfoxserver.v2.entities.invitation package.

SFSGame

The SFSGame class extends the normal capabilities of a Room, adding the ability to set the Game as public or private and providing a list of invited people that the system will invite in the game. Additionally the system will be able to invite more people if the number of players is not sufficient to start the game.

Each game can be configured to match specific types of Users by providing a Match Expression. The expression contains criteria that are checked against each User that wants to join the game and provides a mean for filtering players.

Let's see an example: user Kermit has two variables set.

He wants to play, chooses a public SFSGame and attempts to join it. Unfortunately the SFSGame expression is set as follows: (Rank > 10) OR (BestScore > 3000)
Any attempt to join the Game will be refused because the player doesn't match the SFSGame criteria.

Creating an SFSGame Room is similar to creating a normal Room. On the client side you will find the CreateRoomRequest class and the CreateSFSGameRequest class, both taking a settings object: specifically RoomSettings and SFSGameSettings.

The following is a quick overview of the additional parameters that an SFSGame can take, compared to a regular Room:

Finally it is important to note that the SFSGame class extends SFSRoom and can be treated as any other Room in the system. SFSGame objects can be used and passed around to any method or function that works with the base Room interface. (this is valid for both server and client side)

Quick Join Games

Another feature offered by the Game API (both client and server side) is the QuickJoinGame feature. By providing a MatchExpression and a list of Rooms (of type SFSGame) or a Room Group the system can search for matching Rooms and immediately teleport the player in the game action.

As usual an example will clarify the concept:

 
// Prepare a match expresison
var expr:MatchExpression = new MatchExpression("rank", NumberMatch.GREATER_THAN, 3).and("rank", NumberMatch.LESS_THAN, 8)
 
// An array of Room Groups where we want the search to take place
var whereToSearch:Array = ["poker", "blackJack"]
 
// Fire the request and jump into the game!
sfs.send( new QuickJoinGameRequest(expr, whereToSearch) )

The above client Actionscript code attempts to quick join the User in any game from the poker or blackJack Room Groups where the Game rank variable is > 3 and < 8. Behind the scenes the system will also make sure that the Rooms are of type SFSGame and that there is at least one player slot available. If no Room matching these criteria is found a join error will be fired back at the User.

IMPORTANT:
the QuickJoinGame feature works exclusively with Rooms of type SFSGame which support a MatchExpression, all other Rooms types will be ignored.