SmartFoxServer 2X JavaScript server API

Class: GameApi

GameApi

The GameApi class provides specialized API calls for advanced game functionalities. It contains methods to search opponents based on matching criteria, challenge other players or send invitations to join a game, start quick games and more.

See also

new GameApi()

Developers never istantiate the GameApi class: this is done internally by the SmartFoxServer 2X API; get a reference to it using the Extension's getGameApi method.

Methods

createGame(zone, settings [, owner] [, fireClientEvent] [, fireServerEvent])

Creates a new Room of type SFSGame.

The SFSGame class extends the normal capabilities of a Room, adding the ability to set the game as private and provide a list of users that the system will invite to play automatically. Additionally the system is be able to invite more users if the number of players is not sufficient to start the game.

See also:
Parameters:
Name Type Argument Default Description
zone SFSZone The SFSZone object representing the Zone the SFSGame should be created into.
settings CreateSFSGameSettings The SFSGame configuration object.
owner SFSUser <optional>
 null The SFSUser object representing the owner of the SFSGame; if null is passed, the "Server" will be the owner.
fireClientEvent boolean <optional>
 false If true, a client-side ROOM_ADD event will be fired to notify the SFSGame creation.
fireServerEvent boolean <optional>
 false If true, a server-side event of type SFSEventType.ROOM_ADDED will be fired to notify the SFSGame creation.
Throws:
Returns:
The SFSGame object representing the Room of type SFSGame just created.
Type
SFSGame
Example

In this example we create a public SFSGame, using a Match Expression to make the Room joinable by players from United States and with a rank greater than or equal to 50 only.

var cgs = new CreateSFSGameSettings();
cgs.setName("battle-room-173");
cgs.setMaxUsers(4);
cgs.setMaxSpectators(0);
cgs.setGame(true);
cgs.setGamePublic(true);
cgs.setMinPlayersToStartGame(4);

// Set a Match Expression to filter players willing to join
var exp = new MatchExpression("country", StringMatch.EQUALS, "US");
exp.and("rank", NumberMatch.GREATER_THAN_OR_EQUAL_TO, 50);
cgs.setPlayerMatchExpression(exp);

// Create the SFSGame
getGameApi().createGame(getParentZone(), cgs, null, true, true);

quickJoinGame(user, expression, zone, searchItem, roomToLeave)

Quickly joins a user in an Room of type SFSGame.

When this method is called, the API:

  • if a Zone and Group name are passed, matches the provided Match Expression in the scope (Zone+Group) to find a list of possible Rooms that the player can join;
  • matches the user properties with the Match Expression assigned to the SFSGames in the list (if any - see the GameApi#createGame method).
The first SFSGames that matches the user properties is joined, otherwise an error is returned.
Parameters:
Name Type Description
user SFSUser The SFSUser object representing the user to join in the SFSGame.
expression MatchExpression A Match Expression containing the Room search criteria to find the appropriate SFSGame to join the user in.
zone SFSZone The SFSZone object representing the Zone where to search available SFSGames in. This is ignored if a list of SFSGame objects is passed as the next parameter.
searchItem string | Array.<SFSGame> The name of a Room Group or a list of SFSGame objects where to search an available SFSGame in.
roomToLeave SFSRoom A SFSRoom object representing the Room to leave after having successfully joined the SFSGame.
Throws:
A SFSJoinRoomException exception if an error occurs during the SFSGame joining process.
Returns:
The SFSGame object representing the SFSGame that was joined.
Type
SFSGame

replyToInvitation(invitedUser, invitationId, reply [, params] [, fireClientEvent])

Sends a reply to an invitation.

Replying to an invitation means to accept or refuse it.

See also:
Parameters:
Name Type Argument Default Description
invitedUser SFSUser The SFSUser object representing the user who received the invitation.
invitationId number The id of the invitation, which can be retrieved from the SFSInvitation object received by the invited client.
reply InvitationResponse One of the invitation replies provided in the InvitationResponse enum; only ACCEPT and REFUSE are valid replies, while EXPIRED is reserved to the system.
params SFSObject <optional>
 A SFSObject containing custom parameters to be attached to the reply.
fireClientEvent boolean <optional>
 false If true, a client-side INVITATION_REPLY event will be fired to notify the reply.

sendInvitation(inviter, invitees, expirySeconds, invCallBackHandler [, params])

Sends an invitation to a user.

An invitation can be sent for various purposes, such as joining a Room (both regular and game ones), adding a friend to the Buddy List, etc.

See also:
Parameters:
Name Type Argument Description
inviter SFSUser The SFSUser object representing the user sending the invitation.
invitees Array.<SFSUser> A list of SFSUser objects representing the recipients of the invitation.
expirySeconds number The amount of time allowed to each invitee to accept or refuse the invitation.
invCallBackHandler invCallBackHandler The object that will handle the reply to the invitation (accept or refuse).
params SFSObject <optional>
 A SFSObject containing custom parameters to be attached to the invitation (e.g. a message).

sendJoinRoomInvitation(target, inviter, invitees, expirySeconds [, asSpect] [, leaveLastJoinedRoom] [, params])

Invites a user to join an existing Room of any type.

If the invitation is accepted, the invitee will be automatically joined in the target Room.

Parameters:
Name Type Argument Default Description
target SFSRoom A SFSRoom object representing the Room to invite the invitees to.
inviter SFSUser The SFSUser object representing the user sending the invitation.
invitees Array.<SFSUser> A list of SFSUser objects representing the recipients of the invitation.
expirySeconds number The amount of time allowed to each invitee to accept or refuse the invitation.
asSpect boolean <optional>
 false If true, the provided list of invitees will be joined as spectators (where applicable, i.e. Rooms of type game).
leaveLastJoinedRoom boolean <optional>
 false If true, the users joining the target Room will leave the previously joined Room.
params SFSObject <optional>
 A SFSObject containing custom parameters to be attached to the invitation (e.g. a message).