角色系统综述 #

#lfeng/wellplay/能力综述/角色系统

角色系统是在Wellplay中同步记录游戏中玩家角色数据的系统，以便支持一些需要基于角色数据的业务。

目前，角色系统仅用于为奖励系统提供筛选支持，如果不需要使用奖励系统，可以不使用角色系统。

应用场景 #

在游戏中，一个玩家可以有多个角色，每个角色都会有属性，例如生命值、等级等，而不同的游戏又有不同的属性，如竞速游戏中有加速度而没有魔法值等。

在奖励系统中，允许向指定角色发放奖励，也允许在指定时间内，满足一些属性条件（如 ~等级>50~ ）的角色领取奖励。

因此，开发者可以通过SDK的接口在Wellplay中创建角色，并根据需要设置角色的属性。

核心业务流程 #

关于登录Wellplay #

由于角色系统依赖于账户系统，所以如果要使用角色系统，则必须确保玩家在登录游戏时，及时完成Wellplay社区的登录，以便确保关于角色的操作可以顺利进行。

托管账户模式下，可以调用客户端的相关接口起调Wellplay的登录界面。
独立账户模式下，可以在用户完成游戏内登录流程后立即调用相关接口完成登录。

使用角色系统的接口前，开发者应先引导玩家登陆Wellplay。

角色ID（Role ID） #

角色的唯一标识，开发者应预留至少36位的字符串用于存储。

角色属性（Role Property） #

角色的属性字段有如下特性：

属性字段通过Key-Value的键值对方式来表示。
~属性名-Key~ 操作属性的基本标识，同一个应用不允许用同名属性；为String类型，仅支持英文大小写、数字和下划线，长度为1到16个字符。
~属性值-Value~ 为String类型，支持任意合法的utf8字符，长度为1到16个字符。

类似php等脚本语言的设计，如果Value的字符串本身描述了一个合法的int64数值，则在必要时它会被视作int64的数值并进行数值处理，但仅支持int64。

创建属性字段 #

目前角色系统默认不会有任何属性，开发者如果需要使用角色属性的功能，必须先在管理后台创建属性字段（定义~属性名-Key~），一个应用目前最多允许设置32种属性，如果需要更多的属性，请联系管理员。

修改属性字段 #

由于属性设置后会绑定到已有角色，目前不支持删除已有的属性，但可以修改已有的属性名，修改已有的属性名会影响通过SDK接口操作属性时使用的Key，不会对Value产生任何影响。

修改/设置指定角色的属性值 #

同一个应用下的所有角色会都会拥有全部属性字段，默认情况下取值为空字符串””。开发者可以通过相关接口修改指定角色的属性值，以实现数据同步。

创建角色 #

由于不同的游戏设计不同，开发者需要在客户端，根据业务实际自行创建角色及同步角色的属性，创建角色后，系统会返回该角色的唯一ID（RoleID），开发者应自行记录RoleID与自身应用中对应角色的映射关系。通过SDK创建角色时，角色会从属于当前登陆的Wellplay账户，用户未登录当前账户时，无法通过SDK的接口操作与该角色相关的业务。

默认情况下，一个用户可以最多创建16个角色，如果希望创建更多，可以与管理员联系。

提供⻆色ID给Wellplay #

由于SDK无法主动获得游戏登录的角色变化情况，所以使用角色系统时，每当客户端需要在游戏切换角色时，主动调用SDK相关的接口，告知SDK当前登录的角色已经发生了变化，以便SDK在需要时展示/推送与该角色有关信息（例如展示该角色可以领取的奖励）。

/*
	从游戏方传入⻆⾊ID（每次需要RoleID的时候都会从该回调中获取）。
	@param roleBlock 传⼊roleID供SDK使⽤用
*/
+ (void)giveRoleID:(RoleIDBlock)roleBlock;

// 例:
[LFPlay giveRoleID:^NSString *{
	// 请在这里返回当前玩家登陆的角色对应的WellplayRoleID
	return @"wpRoleID";
}];

删除角色 #

开发者可以根据需要主动删除指定角色。