遊戲API SmartFoxServer 2X
SmartFoxServer 2X提供了一套專門用於遊戲建立和管理的客戶端和伺服器API，包括公共和私人遊戲，遊戲邀請，使用者和房間匹配等等。新的Game API基於三個基本構件：
MatchExpression (匹配表示式)：它們允許以非常自然的方式建立搜尋條件，然後可以將其傳遞給MatchingEngine，以對客戶和使用者執行任何型別的查詢
Invitations (邀請)：這是一個通用的邀請系統，允許您管理多個私人遊戲邀請，但也可以在許多其他活動中使用
SFSGame類：SFSGame是專門用於管理遊戲和提供高階遊戲管理的獨特服務的新型房間
這三個元件是非常通用的，可以單獨用於特定任務或協調編排，以建立高階伺服器行為，您將在幾秒鐘內學習。
»概述
SmartFoxServer類公開了一個getAPIManager（）方法，這又允許您訪問SFS2X框架中的所有不同的API子集。 APIManager提供：
getSFSApi（）：返回對基本SFS2X API的引用
getBuddyApi（）：返回對Buddy List API子集的引用
getGameApi（）：返回對Game API子集的引用
我們現在將專注於Game API。
»匹配表示式
匹配表示式以任何通用程式語言中的“if”條件構建：它們像資料庫中的查詢一樣工作。這是一個Java示例，讓您開始：
MatchExpression exp = new MatchExpression('rank' 表示式由三個要素組成：
變數名
匹配運算子
值
此外，任何數量的表示式都可以與邏輯AND / OR運算子連結在一起，就像常規程式碼一樣。 在上面的例子中，我們建立了一個表示式，它將檢查一個等級值> 5和一個國家值==“義大利”。
但是，這套條件適用於哪裡？ 通常表示式用於匹配使用者（通過他們的使用者變數）和房間（通過他們的房間變數）。 標準的SFS2X API提供了兩個有用的方法，稱為findUsers（）和findRooms（），您可以在其中執行任何匹配表示式，並獲取過濾的使用者/客戶端集。
一個小例子會更好地澄清：
List<User> matchingUsers = sfsApi.findUsers(zone.getUserList(), exp, 50);第一個引數提供了一個使用者物件的列表，用於搜尋當前區域內的所有使用者。 第二個引數是我們剛剛在本節開頭建立的匹配表示式，最後一個數字（50）是返回元素數量的可選限制。 在這種情況下，我們希望搜尋不超過50個匹配的元素（如果我們通過0搜尋將返回所有匹配的使用者）。
搜尋選項不僅限於使用者/房間變數名稱。 事實上，Matching引擎提供了兩個額外的類，RoomProperties和UserProperties，您可以在其中訪問Room和User類的許多特定屬性。
這是一個匹配特定房間屬性和變數的示例：
// 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);上述程式碼將匹配所有具有至少一個空閒播放器插槽的遊戲房間，並將其中的isStarted變數設定為false。 此外，搜尋將僅在被稱為“象棋”的房間組中執行。
“ 高階功能
匹配表示式提供了通過巢狀資料結構（如SFSObject和SFSArray）進行搜尋的高階功能。 這是通過非常簡單的點語法表示式完成的。 這是一個如何工作的例子：
MatchExpression exp = new MatchExpression("europe.italy.capital", StringMatch.EQUALS, "Rome")上面的例子深入到一個名為歐洲的SFSObject中，以義大利物件（另一個SFSObject）為最後讀取它的String欄位大小並與另一個String匹配。 這裡還有一個使用SFSObject和SFSArray的例子：
MatchExpression exp = new MatchExpression("europe.italy.majorCities.3.name", StringMatch.EQUALS, "Milan")從義大利物件我們獲得一個majorCities SFSArray，我們抓住它的第三個專案（.3表示式意味著’給我index = 3的元素）。該專案又是一個SFSObject，其名稱屬性我們最終與一個String進行比較。
匹配表示式的力量並沒有在此結束。如果需要執行復雜的搜尋，您可以執行多個匹配通行證。例如，您可以執行第一個匹配並獲取已過濾的房間列表，然後使用它來應用另一個表示式來進一步優化搜尋，依此類推。
此外，您將在本文後面將結合SFSGame課程，瞭解Match Express的更多有趣的用法。
有關Match Expression的更多詳細資訊，我們建議您參考com.smartfoxserver.v2.entities.match包下的javadoc。
»邀請
SmartFoxServer 2X中的邀請系統提供了一個通用框架，用於向一個以上的連線使用者傳送邀請，並輕鬆管理其響應以及邀請的到期。邀請可以用來挑戰遊戲中的玩家，邀請好友到使用者的地方，請求具體任務的許可權，例如將邀請的使用者新增到好友列表中等等。
建立邀請非常簡單，因為需要四個基本引數：
邀請者：使用者啟動邀請
邀請者：受邀的使用者/播放器/好友
到期時間：被邀請者回復的秒數
自定義引數：通用SFSObject包含特定的邀請引數（訊息，圖片，遊戲詳細資訊等）
受邀使用者將收到邀請，並能在規定的時間內回覆。如果需要，一個簡單的ACCEPT或REFUSE程式碼就是需要回復加上一個帶有響應引數的可選SFSObject。如果在預期的秒數內沒有響應傳送到伺服器，邀請將被視為“拒絕”。
public class GameInvitation extends SFSExtension
{
private ISFSGameApi gameAPI;
@Override
public void init()
{
gameAPI = SmartFoxServer.getInstance().getAPIManager().getGameApi();
}
public void sendInvitation()
{
// Prepare Invitation object 準備邀請物件
User inviter = getParentZone().getUserByName("Fozzie");
User invitee = getParentZone().getUserByName("Gonzo");
// We set the timeout for a reply to 50 seconds 我們將答覆的超時設定為50秒
Invitation invitation = new SFSInvitation(inviter, invitee, 50);
// Send the invitation 傳送邀請
gameAPI.sendInvitation(invitation, new InvitationCallback()
{
@Override
public void onRefused(Invitation invObj, ISFSObject params)
{
// Handle the refused invitation 處理被拒絕的邀請
}
@Override
public void onExpired(Invitation invObj)
{
// Handle the expired invitation 處理過期的邀請
}
@Override
public void onAccepted(Invitation invObj, ISFSObject params)
{
// Handle the accepted invitation 處理接受的邀請
}
});
}
}有關Invitations的更多詳細資訊，請檢查javadoc，特別是SFSGameAPI類和com.smartfoxserver.v2.entities.invitation包。附加資訊也可在客戶端API文件中找到。
»SFSGame
SFSGame類擴充套件了房間的正常功能，增加了將遊戲設定為公開或私有的功能，並提供系統將在遊戲中邀請的受邀人員的列表。此外，如果玩家人數不足以開始遊戲，系統將能夠邀請更多的人。
可以通過提供匹配表示式將每個遊戲配置為匹配特定型別的使用者。該表示式包含針對想要加入遊戲的每個使用者進行檢查的標準，並提供過濾玩家的意圖。
讓我們看一個例子：使用者Kermit設定了以下兩個使用者變數：
等級：10
BestScore：2500
他想玩，所以他選擇一個公共的SFSGame，並試圖加入。不幸的是，SFSGame表示式設定如下：（Rank> 10）OR（BestScore> 3000）
任何加入遊戲的嘗試都將被拒絕，因為玩家不符合SFSGame標準。
建立SFSGame型別的房間類似於建立一個普通房間。在客戶端，您將找到CreateRoomRequest類和CreateSFSGameRequest類，它們都採用設定物件：特別是RoomSettings和SFSGameSettings。
以下是與常規房間相比，SFSGame可以採取的其他引數的快速概述：
isGamePublic：一個公共遊戲可以被變數與SFSGame播放器匹配表示式匹配的任何玩家加入。如果沒有使用表示式，則遊戲將被任何使用者加入。私人遊戲是基於SFSGame建立者提供的邀請（請參閱以下邀請的Players屬性），因此他們通常不需要指定匹配表示式。
minPlayersToStartGame：玩家開始遊戲的最小數量。如果遊戲已經執行，並且玩家數量低於此限制，遊戲將被停止（請參閱下面的notifyGameStartedViaRoomVariable屬性）。
invitePlayers（僅限私人遊戲）SFSGame中邀請的玩家名單。每個玩家將收到一個邀請活動，並能夠在時間內回覆（請參閱下面的invitationExpiryTime屬性）。
searchableRooms：（僅限私人遊戲）一個客房列表，其中Game API可以搜尋更多的玩家邀請。如果被邀請的人數小於minPlayersToStartGame屬性中設定的值，API將尋找更多的玩家。這樣你可以將你的朋友新增到遊戲中，讓系統找到更多的玩家來啟動它。這種機制只有在遊戲第一次啟動時才會起作用，而不是每次使用者數量都低於最小值。
如果您需要每次遊戲停止時搜尋並邀請更多玩家，您可以通過SFSApi.findUsers（）方法輕鬆實現。
leaveLastJoinedRoom：成功加入後自動移除前一個房間的玩家，以防他們收到邀請並接受。
playerMatchExpression：一個表示式來匹配玩家願意玩遊戲;預設情況下不使用表示式。
spectatorMatchExpression：一個表達，以配合願意協助遊戲的觀眾;預設情況下不使用表示式。
invitationExpiryTime：允許邀請玩家接受/拒絕的時間量。
invitationParams：可邀請的自定義引數。這些可以提供有關邀請者，遊戲，邀請資訊等的詳細資訊。
notifyGameStartedViaRoomVariable：自動更新一個保留的房間變數，以表示遊戲開始/停止。房間變數使用全域性設定在房間外廣播。這可以在客戶端使用來顯示可用遊戲列表中的遊戲狀態。
保留的房間變數可以在com.smartfoxserver.v2.entities.variables.ReservedRoomVariables類中找到。
最後，請注意，SFSGame類擴充套件了SFSRoom，可以視為系統中的任何其他房間。 SFSGame物件可以被使用並傳遞給任何與基礎房間介面一起工作的方法或功能（這對於伺服器端和客戶端均有效）。
»快速遊戲加入
Game API提供的另一個功能（客戶端和伺服器端）都是QuickJoinGame請求。通過提供匹配表示式和客房列表（SFSGame型別）或房間組，系統可以搜尋匹配的房間，並立即在遊戲動作中傳送玩家。
像往常一樣，一個例子就是澄清這個概念：
// 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) )上述客戶端ActionScript 3程式碼試圖從遊戲排名變數大於3且小於8的撲克或blackJack房間組中快速加入任何遊戲中。幕後系統還將確保房間是 鍵入SFSGame，至少有一個播放器插槽可用。 如果沒有找到符合這些條件的房間，則使用者將重新啟動加入錯誤。
重要
QuickJoinGame功能專門用於支援Match Expression的SFSGame型別的房間; 所有其他房間型別將被忽略。