角色 - PlayerService

角色模型

sgtcloud为各种类型的游戏设计了一个通用的结构化（schema）角色模型Player，这个对象中抽象了角色名称，等级，头像，金钱等属性，可以供开发者存储，更新，查询（暂不提供删除），并且保留了一些可以复用的冗余字段，例如装备。适合轻量级的休闲或者解谜等游戏直接使用。如果是重度游戏，例如角色扮演，策略等类型，角色信息中包含较多自定义结构和属性的，类似于背包，技能等，应该考虑使用角色扩展来存储，更新和查询。如果您的游戏使用的角色数据信息是二进制的，可以使用content字段来保存，但是该字段无法查询，读写性能也较差，不建存储超过1KB的数据。

角色等价于一个游戏内的游戏角色，一个用户在一个游戏内可以创建并且维护多个角色，拥有不同的id，并且可以维护其对应的在线存档。
物理上，角色信息存储在分服以后的那台服务器上，所以当你变更过路由策略以后（例如修改渠道），可能会导致服务器上的角色信息找不到。
目前角色实体是一个模版，一些字段可以灵活的重用，如果有更多地自定义数据，暂时可以考虑用在线存档在维护。

SgtApi.PlayerService.create(player, callback)

创建一个角色

var player = SgtApi.entityFactory('Player');
player.name = '测试玩家AAA';
player.level = 1;
player.money = 999;

var playerId = null;
SgtApi.PlayerService.create(player, function(result, data) {
    if (result) {   //创建成功
        playerId = data.id; //把角色对象的值赋给playerId
    }
});

SgtApi.PlayerService.getPlayerById(playerId, callback)

通过角色id获取角色信息

SgtApi.PlayerService.getPlayerById(playerId, function(result, data) {
    if (result) {
        data;
    }
});

SgtApi.PlayerService.update(player, callback)

更新角色信息

player.name = '测试玩家BBB';
player.level = 2;
player.money = 1000;

SgtApi.PlayerService.update(player, function(result, data){
    if (result) {
        data;
    }
});

SgtApi.PlayerService.deletePlayerByPlayerId(playerId, callback)

通过playerId删除角色及相关信息

SgtApi.PlayerService.downloadSave(playerId, callback)

下载存档

SgtApi.PlayerService.getByLastLoginTime(lastLoginTime, start, limit, callback);

根据最后登陆时间查找角色

SgtApi.PlayerService.getByName(playerName, start, limit, callback);

根据角色名查找角色

SgtApi.PlayerService.getByUserId(userId, callback);

根据用户ID查找角色

SgtApi.PlayerService.getFriendsMaxNumber(playerId, callback);

获取指定角色的好友上限

SgtApi.PlayerService.getOneByUserId(userId, callback);

通过用户ID查找其中的一个角色

SgtApi.PlayerService.getPlayerByCustomId(customId, callback);

通过自定义ID获取角色信息

SgtApi.PlayerService.searchPlayerByLastLogin(limit, callback);

随机返回若干个最近登录的player

SgtApi.PlayerService.searchPlayersByLastLoginCondition(lastLoginTime, limit, excludePlayerIds, callback);

根据条件过滤并随机查询若干个最近登录的player

SgtApi.PlayerService.setFriendsMaxNumber(playerId, number, callback);

设置指定角色的好友上限

SgtApi.PlayerService.uploadSave(save, callback);

上传存档

Class: Player

id 主键非自增，不能为空
serverId 服务器
customId自定义ID
userId 用户ID (opensocial中)
name 名字
gender 性别 [1 男 0 女]
lastLoginTime 最后登录时间
level 等级
vip VIP等级
money 金钱

Class: PlayerExtra

角色扩展信息公共父类，所有开发者扩展的角色信息要么继承这个类，要么在自己的扩展类中添加playerId字段

playerId 角色ID

Class: Save

id 主键
playerId 角色ID
lastUploadTime 最后上传时间
content 存档内容
downFlag 是否可下载存档标识