服务器变量 SmartFoxServer 2X

服务器变量

SmartFoxServer 2X框架提供不同类型的服务器变量，可用于在Buddy列表中的用户，客户和好友之间维护同步状态。

服务器变量通常允许客户机或服务器逻辑创建自动更新的范围内的自定义值。服务器变量的三种主要类型有不同的范围：

用户变量：它们表示连接到单个用户的自定义数据。所有更新由用户在所有者加入的同一个房间中接收。换句话说，一个名为Piggy的用户将可以访问并获取有关用户Kermit的所有变量的更新，当它们都加入同一个房间时。常见的用例是存储自定义用户个人资料或游戏数据（分数，排名，年龄，兴趣，头像，游戏成就...）

房间变量：它们表示附加到Room对象的自定义数据。他们的范围是房间本身，所以用户一旦加入了特定的房间，就可以访问房间变量。还有一些方法可以使这些变量可见，并从室外接收更新。一个常见的用例是保持游戏的状态和属性（技能水平，得分，最佳分数，当前游戏状态...）

好友变量：它们表示一个或多个好友列表中附加到Buddy的自定义数据。范围是好友列表本身，所以任何在他们的列表中添加名为Gonzo的用户将会看到并接收他的变量的更新。最有用的应用是保持每个朋友实时更新自己的状态。

»一般建筑

下图说明了不同类型服务器变量的简化层次结构。在顶部，我们有可变界面定义基本属性，如名称和值。下面我们找到不同的子类，扩展基本功能，并添加新的属性，如private，persistent …

让我们更深入地了解每个属性：

name：可以是任何有效的字符串，但请记住，短名称将使用较少的字节，从而减少带宽。通常2-5个字符足以定义您的变量。

值：所有服务器变量支持几种基本类型：
    null 空（仅用于删除变量）
    boolean布尔值
    integer整数（32位）
    double双（64位双）
    string字符串（最多32768个字符）
    SFSObject
    SFSArray

isHidden：默认情况下，所有变量都不被隐藏。您可以为用户和房间变量打开此标志，以便仅在服务器端保留这些值。客户永远不会收到关于隐藏变量的任何更新。此标志仅在服务器端可用。

isPrivate：当在UserVariable或Room Variable上激活时，此标志具有不同的效果。私人用户变量只能由其各自的所有者访问。私人房间变更对房间内的所有客户都可见，但只能由所有者修改。

isPersistent：默认情况下，用户创建的房间变量从房间中删除。如果此标志已打开，则房间变量将持续，直到用户注销或断开连接（default = false）。

isGlobal：一个全球房间变量在房间外面是可见的。这意味着任何用户将能够访问它并接收更新，即使他没有加入房间。运行太多全局变量可以在高流量服务器中使用显着的带宽。使用审核（default == false）

静态变量：
虽然用户变量和好友变量只能通过代码动态创建，但房间变量也可以在配置时静态创建。您可以通过查看关于AdminTool的Zone Configurator的文档来了解更多信息。
»使用示例

下面你将会看到几个例子，说明如何在Actionscript 3中使用客户端API中的房间和用户变量。我们选择了这种语言，因为它是常用的，非常类似于C＃和Java。 将示例转换为任何其他API语言需要几乎没有任何努力。

在服务器端使用变量同样简单，并使用相同的接口和逻辑。

最后，Buddy变量在Buddy List API的最大上下文中单独处理。
用户变量

这是用户可以使用变量存储其配置文件并自动更新同一房间中的所有其他客户端的示例。

var avatarPic:UserVariable = new SFSUserVariable("avt", "MissPiggy.png");
var occupation:UserVariable = new SFSUserVariable("occ", "Acting and singing");
var location:UserVariable = new SFSUserVariable("loc", "Muppet's Show");

sfs.send( new SetUserVariablesRequest( [avatarPics, occupation, location] ));

要接收更新客户端，必须监听SFSEvent.USER_VARIABLES_UPDATE事件：

sfs.addEventListener(SFSEvent.USER_VARIABLES_UPDATE, onUserVarsUpdate);

// ...

private function onUserVarsUpdate(evt:SFSEvent):void
{      
    // The User that changed his variables
    var user:User = evt.params.user as User;

    // Do something with these values...
    trace("Location: " + user.getVariable("loc").getValue());
    trace("Occupation: " + user.getVariable("occ").getValue());

    // etc...
}

房间变量

以下是如何从客户端设置私人房间变量的简单示例：

var chatRoomTopic:RoomVariable = new SFSRoomVariable("topic", "Multiplayer Game Development");
chatRoomTopic.isPrivate = true;

sfs.send( new SetRoomVariablesRequest( [chatRoomTopic] ));

其他客户端必须正在侦听SFSEvent.ROOM_VARIABLES_UPDATE事件并处理它：

sfs.addEventListener(SFSEvent.ROOM_VARIABLES_UPDATE, onRoomVarsUpdate);

// ...

private function onRoomVarsUpdate(evt:SFSEvent):void
{
    // An array of variable names that were updated for the Room
    var changedVars:Array = evt.params.changedVars as Array;

    // Obtain the variable and show the new value
    var topicRV:RoomVariable = sfs.lastJoinedRoom.getVariable("topic");

    trace("The Room topic is now set to: " + topicRV.getValue());
}

»服务器端的变量

以下示例演示如何使用用户和房间变量在您的服务器端扩展，用Java编写。
用户变量

我们设置几个用户变量。 其中一个将是专门的服务器端，使用隐藏的属性。

private void setUserProfile(User user, int databaseId)
{
    // public user var
    UserVariable avatarPic = new SFSUserVariable("pic", "GonzoTheGreat.jpg");

    // private user var
    UserVariable dbId = new SFSUserVariable("dbId", databaseId);
    dbId.setHidden(true);

    // Set variables via the server side API
    getApi().setUserVariables(user, Arrays.asList(avatarPic, dbId));
}

房间变量

现在我们来看看房间变量。 在服务器端创建它们的有趣之处在于它们的“创建者”将是服务器本身。 就像客户端一样，创建者是发送请求的用户。

这意味着服务器创建的房间变量永远不会过期，与使用客户端API生成的变量相反。 这可以用于在需要它的任何房间中维持完全持久的值。

private void setupRoomVariables(Room room)
{
    // Private Global Room variable, no one will be able to overwrite this value
    // The topic will be visible from outside the Room
    RoomVariable chatTopic = new SFSRoomVariable("topic", "Multiplayer Game Development");
    chatTopic.setPrivate(true);
    chatTopic.setGlobal(true);

    // Secret variable, only accessible from server side
    RoomVariable isModerated = new SFSRoomVariable("isMod", true);
    isModerated.setHidden(true);

    // Set variables via the server side API
    // Passing null as the User parameter sets the ownership of the variables to the Server itself
    getApi().setRoomVariables(null, room, Arrays.asList(chatTopic, isModerated));
}

»学习更多

为了了解有关服务器变量的更多信息，我们建议您查看特定的服务器端和客户端API以供您选择的平台。 您可以在API文档部分的左侧菜单中找到所有链接。

翻译自http://docs2x.smartfoxserver.com/DevelopmentBasics/server-variables