服务端--房间基类 More...

Public Member Functions
def	__init__
	房间类的构造函数
def	cghall_init
	房间初始化函数(重载)
def	cghall_clean
	房间类的清除函数(重载)
def	cghall_on_init_roomname
	初始化房间名(重载)
def	cghall_on_init_extra
	初始化房间的扩展属性(重载)
def	cghall_can_enter_room
	判断玩家能否进入此房间(重载)
def	cghall_on_player_enter_room
	玩家进入房间(重载)
def	cghall_on_player_leave_room
	玩家离开房间(重载)
def	cghall_tell_hall_game_start
	房间通知大厅游戏开始(主动调用)
def	cghall_tell_hall_game_end
	房间通知大厅游戏结束(主动调用)
def	cghall_tell_hall_player_ready
	房间通知大厅玩家的准备状态(主动调用)
def	cghall_tell_hall_player_leave_room
	房间通知大厅玩家需要离开房间(主动调用)
def	cghall_get_player_num
	获取房间内的当前玩家人数(主动调用)
def	cghall_has_started
	判断游戏是否已经开始(主动调用)
def	cghall_set_buf
	设置玩家的buf(主动调用)
def	cghall_set_tag
	设置排行榜的某个玩家的某个tag(主动调用)
def	cghall_sync_tag
	同步房间内所有玩家的排行榜数值到排行榜服务器(主动调用)
def	cghall_query_rank
	查询指定玩家的某个排行榜的排名(主动调用)
def	cghall_on_query_rank_result
	查询指定玩家的某个排名的结果(重载)
def	cghall_set_item
	设置某玩家的道具(主动调用)
def	cghall_buy_item
	请求购买道具(主动调用)
def	cghall_on_buy_result
	购买道具的结果(重载)
def	cghall_add_achievement
	添加成就(主动调用)
def	cghall_on_add_achievement_result
	成就添加的结果(重载)
def	cghall_inc_score
	增加分数(主动调用)
def	cghall_inc_win_count
	增加一局胜局(主动调用)
def	cghall_inc_draw_count
	增加一局平局(主动调用)
def	cghall_inc_lose_count
	增加一局败局(主动调用)
def	cghall_inc_break_count
	增加一局断线局(主动调用)
def	cghall_reset_score_and_count
	重置某玩家的分数和所有局数(主动调用)
def	cghall_broadcast
	房间内广播消息(主动调用)
def	cghall_broadcast_raw
	房间内广播字符串(主动调用)
def	cghall_send
	发送消息给指定玩家(主动调用)
def	cghall_send_raw
	发送字符串给指定玩家(主动调用)
def	cghall_set_sock_nodelay
	设置socket的TCP_NODELAY选项为1, 不使用Nagle算法(主动调用)
def	cghall_create_timer
	创建一个定时器对象(主动调用)
def	cghall_tell_hall_update_attribute
	更新房间属性(主动调用)
def	cghall_tell_hall_update_extra
	更新房间3个扩展属性(主动调用)
def	cghall_on_recv_msg
	收到玩家发来的消息(重载)
def	cghall_get_player_by_uid
	通过uid取得玩家对象(重载)
def	cghall_get_player_by_hid
	通过hid取得玩家对象(重载)
def	cghall_inc_coin
	增加玩家的coin数量(主动调用)
def	cghall_update_player_matchlvl
	更新玩家的配对等级(主动调用)
def	cghall_on_update_player_money
	玩家的钱有更新(重载)
def	cghall_get_serverid
	获得当前服务器的编号(主动调用)
def	cghall_get_static_rooms
	获得所有静态房间的信息(主动调用)
def	cghall_execute_sql
	发送一条非查询的sql语句
def	cghall_execute_sql_fetchall
	发送一条查询的sql语句
def	cghall_execute_many_sqls
	发送多条sql语句
def	cghall_get_room2client_msgmgr
	取得房间和客户端之间的消息管理器
def	cghall_set_static_room_ready
	设置此静态房间已经准备好
def	cghall_on_server_need_shutdown
	服务器即将关闭(重载)
def	cghall_on_clean_static_room
	服务器关闭, 需要关闭静态房间(重载)
def	cghall_set_static_room_clean
	静态房间通知系统此房间可以关闭(主动调用)
def	cghall_send_system_data
	发送全服系统广播(主动调用)
def	cghall_req_friends
	请求好友列表(主动调用)
def	cghall_friends_result
	请求好友信息的结果(重载)
def	cghall_forward_to_uid
	请求给其他房间的玩家转发消息(主动调用)
def	cghall_on_recv_forwarded_data
	收到来自其他房间转发来的消息(重载)
def	cghall_gametime_start
	玩家实际有效游戏时间计时开始(主动调用)
def	cghall_gametime_stop
	玩家实际有效游戏时间计时结束(主动调用)
def	cghall_query_player_info
	向数据库查询指定玩家的基本信息(主动调用)
def	cghall_on_recv_player_info
	向数据库查询指定玩家的基本信息的返回结果(重载)
def	cghall_query_player_bufmap
	向数据库查询指定玩家的buf信息(主动调用)
def	cghall_on_recv_player_bufmap
	向数据库查询指定玩家的buf信息的返回结果(重载)
Public Attributes
	room_id
	房间号类型: int 范围: [0, 4294967295]
	room_host
	创建此房间的uid 类型: int 范围: [0, 4294967295]
	max_num
	此房间允许进入的最大人数可在房间创建完毕之后通过调用HallRoom.cghall_tell_hall_update_attribute函数进行修改类型: int 范围: [0, 4294967295]
	game_mode
	此房间的当前模式可在房间创建完毕之后通过调用HallRoom.cghall_tell_hall_update_attribute函数进行修改类型: int 范围: (0, 4294967295]
	log
	RoomLog类的实例, 请尽量使用此模块写日志
	room_name
	房间名称可通过重载HallRoom.cghall_on_init_roomname函数, 在房间创建时给房间设定名称可在房间创建完毕之后通过调用HallRoom.cghall_tell_hall_update_attribute函数进行修改类型: str
	room_extra1
	房间提供的扩展属性1 此扩展属性会传给大厅, 供游戏扩展大厅中的房间列表使用可通过重载HallRoom.cghall_on_init_extra函数, 在房间创建时更新extra 可在房间创建完毕后通过调用HallRoom.cghall_tell_hall_update_extra函数进行修改类型: int 范围: [0, 4294967295]
	room_extra2
	房间提供的扩展属性2 此扩展属性会传给大厅, 供游戏扩展大厅中的房间列表使用可通过重载HallRoom.cghall_on_init_extra函数, 在房间创建时更新extra 可在房间创建完毕后通过调用HallRoom.cghall_tell_hall_update_extra函数进行修改类型: int 范围: [0, 4294967295]
	room_extra3
	房间提供的扩展属性3 此扩展属性会传给大厅, 供游戏扩展大厅中的房间列表使用可通过重载HallRoom.cghall_on_init_extra函数, 在房间创建时更新extra 可在房间创建完毕后通过调用HallRoom.cghall_tell_hall_update_extra函数进行修改类型: int 范围: [0, 4294967295]
Static Public Attributes
int	ERROR_BUY_OK = 0
	购买返回的错误码: 成功
int	ERROR_BUY_LITTLE_MONEY = 1
	购买返回的错误码: 钱不够
int	ERROR_BUY_PARAMS_ERROR = 2
	购买返回的错误码: 参数错误
int	ERROR_BUY_DB_ERROR = 3
	购买返回的错误码: 数据库错误
int	ERROR_BUY_TIMEOUT = 4
	购买返回的错误码: 数据库处理超时
int	ERROR_BUY_MONEY_LOCKED = 5
	购买返回的错误码: 钱被锁
int	ERROR_BUY_UNKNOWN = 6
	购买返回的错误码: 未知错误
int	ERROR_BUY_OVER_ONE_YEAR = 7
	购买返回的错误码: 时效型道具时效超过1年

Detailed Description

服务端--房间基类

游戏通过继承这个类, 实现房间逻辑
玩家的数据也只能此类提供的方法进行操作

房间被创建后, 通过网络消息和第三方创建的定时器消息不停的触发房间运转.

这里的函数主要分成2类:

需要第三方重载的函数; 此类函数系统会在合适的时机被系统调用
需要第三方主动调用的函数; 此类函数第三方根据游戏需要在何时的时机主动调用

建议第三方至少重载此类的以下4个函数:

HallRoom.cghall_init 房间创建成功后系统会立即调用此函数
第三方可在此函数中进行房间的初始化
HallRoom.cghall_clean 房间需要被销毁的时候系统会调用此函数
第三方可在这里进行一些资源释放
HallRoom.cghall_on_player_enter_room 有玩家进入此房间时, 系统会调用此函数
第三方可在这里获取到该玩家的详细信息
HallRoom.cghall_on_player_leave_room 玩家离开房间时系统会调用此函数
第三方可在此函数中进行一些玩家离开的处理工作

Constructor & Destructor Documentation

def __init__	(	self,
		room_id = `0`,
		name = `''`,
		mode = `0`,
		host = `0`,
		pwd = `''`,
		max_num = `0`,
		can_match = `False`
	)

房间类的构造函数

不建议在构造函数中做房间相关的初始化
建议在cghall_init的函数中做房间相关的初始化

Member Function Documentation

def cghall_init ( self )

房间初始化函数(重载)

在此类对象创建成功之后, 系统会立即调用此函数
游戏可根据需要重载此函数, 在此函数中做一些关于房间的初始化

def cghall_clean ( self )

房间类的清除函数(重载)

房间被销毁时系统会主动调用此函数
第三方可通过重载此函数, 在这里进行房间内的资源释放

def cghall_on_init_roomname	(	self,
		name
	)

初始化房间名(重载)

如果希望在房间刚建立的时候, 能够对房间名进行修改, 则可重载此函数
此函数在房间类创建时被调用, 返回值赋值给HallRoom.room_name,并通知大厅
如果不重载此函数, 动态房间将以客户端传来的名字作为房间名;静态房间将以模式名称作为房间名字.

Parameters:

name	创建时客户端传来的房间名称

Return values:

string 希望真正赋值的房间名称

def cghall_on_init_extra	(	self,
		extra1,
		extra2,
		extra3
	)

初始化房间的扩展属性(重载)

如果希望在房间刚建立的时候, 能够对房间的3个扩展属性进行修改, 则可重载此函数
此函数在房间类创建时被调用, 返回值赋值给相应的HallRoom.extra*,并通知大厅
如果不重载此函数, 将以客户端传来的extra*赋值给房间的3个扩展属性

Parameters:

extra1	客户端创建房间时传来的扩展属性1
extra2	客户端创建房间时传来的扩展属性2
extra3	客户端创建房间时传来的扩展属性3

Return values:

tuple 分别是新的extra1, extra2, extra3

def cghall_can_enter_room	(	self,
		player
	)

判断玩家能否进入此房间(重载)

玩家进入房间之前系统会调用此接口判断玩家能否进入此房间
第三方可重载此函数, 以根据游戏逻辑决定是否让玩家进入此房间

Parameters:

player 大厅提供的hall_player.HallPlayer的实例,
请只用此实例进行能否进入的判断, 不要对这个实例进行引用或做其他初始化
因为此player最后不一定要进入这个房间

Return values:

(ok,desc) ok是bool类型, 表示是否允许玩家进入房间; True: 允许, False不允许;
desc是字符串, 如果ok是True, 则desc没有特别意义
如果ok是False, 则是玩家不能进入此房间的原因描述

def cghall_on_player_enter_room	(	self,
		player,
		obj
	)

玩家进入房间(重载)

有玩家进入此房间时, 系统会调用此函数

Parameters:

player	大厅提供的hall_player.HallPlayer的实例在player身上第三方可读到iTownSDK提供的此玩家的基本数据;
obj	此参数已作废, 仅为保留接口而留着

def cghall_on_player_leave_room	(	self,
		hid
	)

玩家离开房间(重载)

大厅告知房间: 此玩家必须离开房间
可能是大厅强迫玩家离开此房间
也可能是房间调用了HallRoom.cghall_tell_hall_player_leave_room而触发

Parameters:

hid	离开此房间的玩家的hid

def cghall_tell_hall_game_start ( self )

房间通知大厅游戏开始(主动调用)

房间内的游戏开始时, 第三方需要调用此接口通知大厅:此房间游戏已开始

def cghall_tell_hall_game_end ( self )

房间通知大厅游戏结束(主动调用)

房间内的游戏结束时, 第三方需要调用此接口通知大厅:此房间游戏已结束

def cghall_tell_hall_player_ready	(	self,
		hid,
		ready = `True`
	)

房间通知大厅玩家的准备状态(主动调用)

房间内的玩家准备时, 第三方需要调用此接口通知大厅:玩家当前的准备状态

Parameters:

hid	玩家的hid
ready	当前是否准备状态; True-准备; False-未准备;

def cghall_tell_hall_player_leave_room	(	self,
		hid,
		channelid = `-1`
	)

房间通知大厅玩家需要离开房间(主动调用)

玩家需要离开房间时需要房间主动调用此接口以通知大厅:某玩家需要离开此房间
大厅处理后会触发HallRoom.cghall_on_player_leave_room

Parameters:

hid	需要离开此房间的玩家的hid

def cghall_get_player_num ( self )

获取房间内的当前玩家人数(主动调用)

Return values:

int	当前房间内的玩家人数

def cghall_has_started ( self )

判断游戏是否已经开始(主动调用)

Return values:

bool	True-游戏已开始; False-游戏未开始

def cghall_set_buf	(	self,
		hid,
		bufid,
		data
	)

设置玩家的buf(主动调用)

设置某玩家的buf内容

Parameters:

hid	玩家的hid
bufid	需要修改的buf字段, 'buf0'-'buf15'
data	bufid对应的内容字符串长度不能超过256,超过部分在写回数据库时,将自动截断

def cghall_set_tag	(	self,
		hid,
		tagid,
		value
	)

设置排行榜的某个玩家的某个tag(主动调用)

通过此函数可设置某玩家的某个排行榜的数值
数据将会被系统缓存一定的时间或玩家离开服务器时才提交给排行榜
如果第三方逻辑依赖排行榜数据,可在游戏结束时主动调用HallRoom.cghall_sync_tag函数

Parameters:

hid	玩家的hid
tagid	需要设定的排行榜的tag字段, 它可以是: hall_consts.RANKTAG_1, hall_consts.RANKTAG_2,hall_consts.RANKTAG_3,hall_consts.RANKTAG_4,hall_consts.RANKTAG_5, 这里设定的tagid必须是在初始化时通过hall_callback.set_rank_conf接口设置过的排行榜的tag 否则系统将抛异常以提示
value	此玩家在此排行榜对应的数值类型: int, 范围: [-2147483648, 2147483647] 如果想把此玩家的此排行榜数值清空, value可设置为None

Return values:

bool	True表示此tag添加成功, False表示此请求不合理, 请注意查看error日志

def cghall_sync_tag	(	self,
		hidlist = `[]`
	)

同步房间内所有玩家的排行榜数值到排行榜服务器(主动调用)

在默认情况下, 玩家的排行榜数值(tagmap中的数值)将被服务器缓存一定时间才被提交到排行榜服务器
如果游戏希望尽快提交可在游戏结束时主动调用此函数, 以便把房间内所有玩家的排行榜数值立即提交到排行榜服务器
但提交过于频繁带来的服务器压力问题需要第三方权衡
2次调用间隔至少要超过1分钟

Parameters:

hidlist [list] 需要同步排行数值的玩家hid列表;
空list表示房间内所有玩家; 如果房间有旁观, 请设定非旁观玩家的hid列表

Return values:

bool	True表示请求已经提交; False表示此请求不合理, 注意查看日志;

def cghall_query_rank	(	self,
		hidlist,
		querytag,
		querymode,
		tag = `None`
	)

查询指定玩家的某个排行榜的排名(主动调用)

此函数向排行榜服务器发起一个查询排名的请求
在使用此函数之前, 建议先调用HallRoom.cghall_sync_tag, 把玩家的排行数值提交到排行榜服务器
但提交过于频繁带来的服务器压力问题需要第三方权衡
2次调用间隔至少要超过1分钟

Parameters:

hidlist	[list] 需要查询排名的玩家hid列表
querytag	[string] 需要查询的排行榜tag, 需要在hall_callback.set_rank_conf中设置过的tag*之一: 它可以是: hall_consts.RANKTAG_1 hall_consts.RANKTAG_2 hall_consts.RANKTAG_3 hall_consts.RANKTAG_4 hall_consts.RANKTAG_5
querymode	[int] 需要查询的排行榜类型, 它的数值可以是: hall_consts.RANKMODE_HISTORY hall_consts.RANKMODE_TODAY hall_consts.RANKMODE_WEEK
tag	[任意类型] 查询时提供给第三方设置的一个标识位, 在查询返回时将把此tag放在回调函数中

def cghall_on_query_rank_result	(	self,
		code,
		tag,
		rankmap
	)

查询指定玩家的某个排名的结果(重载)

在成功调用了HallRoom.cghall_query_rank且排行榜系统返回排名后, SDK将主动调用此函数

Parameters:

code	[int] 错误码, 可能数值包括: hall_consts.ERROR_QUERYRANK_OK 查询成功; hall_consts.ERROR_QUERYRANK_TIMEOUT 查询超时; hall_consts.ERROR_QUERYRANK_UNKNOWN 未知错误;
tag	[任意类型] 在HallRoom.cghall_query_rank时第三方设定的tag参数
rankmap	[dict] 排名的map, 格式为{uid: 排名(int)}, 当排名在排行榜的实时排名以外(目前SDK设定的是只对前1万名进行排名), 则排名为0

def cghall_set_item	(	self,
		hid,
		itemtype,
		timeitem,
		inccount = `0`,
		value = `None`,
		msg = `None`,
		status = `None`,
		deadtime = `None`
	)

设置某玩家的道具(主动调用)

第三方可通过此接口修改玩家的道具
如果该道具不存在, 则相当于新增加一个道具

Note:: 收费道具不能通过此接口增加道具, 不能延长时效(deadtime), 不能增加数量(inccount).

Parameters:

hid	玩家的hid
itemtype	道具的编号
timeitem	是否时效型道具
inccount	对道具数量的操作, 正数表示增加,负数表示减少注意:收费道具不能增加数量, 只能通过购买来增加数量
value	此道具的int的自由存储空间, None表示不修改此值
msg	此道具的64字节的自由存储空间, None表示不修改
status	道具状态, None表示不修改, 非None只有三种数值: game_item.CGItem.ITEM_STATUS_ACTIVE: 表示此道具当前有效 game_item.CGItem.ITEM_STATUS_USELESS:表示此道具当前无效, 但保留在数据库中 game_item.CGItem.ITEM_STATUS_CAN_DEL:表示此道具当前无效, 且可在数据库中删除
deadtime	此道具的有效时间戳, None表示不修改, 收费道具不可延长deadtime 当时间超过deadtime时, 表示此道具无效不要求游戏时时刻刻检查道具是否过期只要在玩家登录时有效, 即可认为一直有效, 直到下次登录为止

def cghall_buy_item	(	self,
		hid,
		tag,
		itemtype,
		count,
		value = `None`,
		msg = `None`
	)

请求购买道具(主动调用)

此接口发起一个购买请求, 在系统处理完购买请求后, 将触发HallRoom.cghall_on_buy_result
在调用此接口发起购买请求后, 该道具将自动被系统锁住
被锁住的道具, 只读, 不能写, 不能购买, 如果强制写或购买, 系统将抛异常
通过game_item.CGItem.is_lock接口判断某道具当前是否被锁状态
在购买返回后(即回调HallRoom.cghall_on_buy_result后)此道具将被自动解锁
只有通过yuanbao来购买的道具(即在初始化时通过hall_callback.set_sales_item_conf设置过的道具) 才可通过此接口进行购买, 否则将抛异常

Parameters:

hid	发起购买请求的玩家的hid
tag	[任意类型] 购买时供第三方设置的一个标识位, 在购买返回时将把此tag放在回调函数中
itemtype	道具编号, 必须是收费道具的编号
count	道具数量, 必须大于0, 否则将购买失败
value	提供给此道具的int自由存储空间, 为None表示不修改原有的数值
msg	提供给次道具的64字节的字符串自由存储空间, 为None表示不修改原有的数值

Return values:

code	购买请求的错误码, 数值为: hall_consts.ERROR_BUY_OK: 购买请求成功发送出去, 具体是否购买成功, 需要以cghall_on_buy_result为准 hall_consts.ERROR_BUY_OVER_ONE_YEAR:道具时效超过1年 hall_consts.ERROR_BUY_LITTLE_MONEY:钱不够 hall_consts.ERROR_BUY_PARAMS_ERROR: 参数错误, 比如count<=0

def cghall_on_buy_result	(	self,
		hid,
		code,
		tag,
		item,
		use_yuanbao,
		left_yuanbao
	)

购买道具的结果(重载)

购买道具有了结果后系统将回调此函数

Parameters:

hid	此道具的属主的hid
code	购买结果的错误码, 数值为: hall_consts.ERROR_BUY_OK: 购买成功 hall_consts.ERROR_BUY_OVER_ONE_YEAR:道具时效超过1年 hall_consts.ERROR_BUY_LITTLE_MONEY:钱不够 hall_consts.ERROR_BUY_PARAMS_ERROR:参数错误 hall_consts.ERROR_BUY_DB_ERROR:数据库错误 hall_consts.ERROR_BUY_TIMEOUT:数据库处理超时 hall_consts.ERROR_BUY_MONEY_LOCKED:钱被锁 hall_consts.ERROR_BUY_UNKNOWN:未知错误
tag	发起购买请求时设定的tag参数
item	如果购买成功则item是购买的CGItem对象, 已加入大厅的player.itemmap中
use_yuanbao,:	本次购买使用掉的钱
left_yuanbao,:	本次购买后剩余的钱(已更新至大厅的player.yuanbao中)

def cghall_add_achievement	(	self,
		hid,
		tag,
		achid,
		score
	)

添加成就(主动调用)

发起给某玩家添加成就的请求
在请求有结果后将回调HallRoom.cghall_on_add_achievement_result
achid需要在hall_callback.set_achieve_conf中设置过
score需要与hall_callback.set_achieve_conf中设置的score一致
一个成就一个玩家只能获取一次

Parameters:

hid	玩家的hid
tag	发起请求时设定的一个标识, 将在回调中原值返回
achid	成就id
score	此成就对应的成就分

Return values:

bool	True表示此请求已经成功发出; False表示此请求不合理, 请查看Error日志.

def cghall_on_add_achievement_result	(	self,
		hid,
		uid,
		tag,
		ok,
		achid
	)

成就添加的结果(重载)

添加成就有结果后, 将回调此函数
如果添加成功, 则该成就已经更新至player.achmap中

Parameters:

hid	玩家的hid
uid	玩家的uid
tag	发起请求时设定的一个标识
ok	是否添加成功
achid	该成就id

def cghall_inc_score	(	self,
		hid,
		delta
	)

增加分数(主动调用)

增加某玩家的分数(player.score)

Parameters:

hid	玩家的hid
delta	需要增加的分数增量; delta>0表示增加分数; delta<0表示减少分数

def cghall_inc_win_count	(	self,
		hid
	)

增加一局胜局(主动调用)

使某玩家的胜局(player.win_count)加1

Parameters:

hid 玩家的hid

def cghall_inc_draw_count	(	self,
		hid
	)

增加一局平局(主动调用)

使某玩家的平局(player.draw_count)加1

Parameters:

hid 玩家的hid

def cghall_inc_lose_count	(	self,
		hid
	)

增加一局败局(主动调用)

使某玩家的败局(player.lose_count)加1

Parameters:

hid 玩家的hid

def cghall_inc_break_count	(	self,
		hid
	)

增加一局断线局(主动调用)

使某玩家的断线局数(player.break_count)加1

Parameters:

hid 玩家的hid

def cghall_reset_score_and_count	(	self,
		hid
	)

重置某玩家的分数和所有局数(主动调用)

使某玩家的分数(score)和所有局数(win_count, lose_count, draw_count, break_count)都清为0

Parameters:

hid 玩家的hid

def cghall_broadcast	(	self,
		msgobj,
		exclude = `[]`
	)

房间内广播消息(主动调用)

把消息广播给房间内的所有除了exclude内的其他玩家
此函数调用与下面的调用等价
HallRoom.cghall_broadcast_raw(msgobj.to_string(), exclude)

Parameters:

msgobj	需要发送的消息对象
exclude	广播需要排除的玩家, 数据类型是list, 元素是玩家的hid

def cghall_broadcast_raw	(	self,
		data,
		exclude = `[]`
	)

房间内广播字符串(主动调用)

把消息广播给房间内的所有除了exclude内的其他玩家

Parameters:

data	需要发送的字符串
exclude	广播需要排除的玩家, 数据类型是list, 元素是玩家的hid

def cghall_send	(	self,
		hid,
		obj
	)

发送消息给指定玩家(主动调用)

此函数等价于:
HallRoom.cghall_send_raw(hid, obj.to_string())

Parameters:

hid	玩家的hid
obj	需要发送的消息对象

def cghall_send_raw	(	self,
		hid,
		data
	)

发送字符串给指定玩家(主动调用)

Parameters:

hid	玩家的hid
data	需要发送的字符串

def cghall_set_sock_nodelay ( self )

设置socket的TCP_NODELAY选项为1, 不使用Nagle算法(主动调用)

默认情况下是使用Nagle算法
如果需要修改设置, 请在房间初始化是设置
设置后, 每当有玩家进入房间时系统将自动设置该玩家的socket选项

def cghall_create_timer	(	self,
		seconds,
		callback,
		forever = `False`,
		name = `''`,
		params = `()`
	)

创建一个定时器对象(主动调用)

创建的定时器对象, 在不需要时请主动调用该对象的delete函数, 清除定时器
需要使用定时器时, 请使用此接口创建; 尽量不要用pttimer模块直接创建

Parameters:

seconds	多少秒后回调, 可以是小数, 但是只能精确到小数点后1位
callback	定时器的回调函数
forever	此定时器执行完一次回调之后是否继续开始下一次的定时回调
name	给定时器命名, 主要方便打日志时查看
params	callback的参数列表, 如果只有一个参数, 记得要加逗号和括号, 即:(a,)

def cghall_tell_hall_update_attribute	(	self,
		gamemode = `None`,
		maxnum = `None`,
		roomname = `None`
	)

更新房间属性(主动调用)

在房间创建后如果想再修改模式,房间最大人数,房间名称等, 可通过此函数通知大厅, None表示不修改
静态房间不允许修改gamemode!!

Parameters:

gamemode	游戏模式, None表示不修改
maxnum	此房间的最大人数, 必须符合该模式的人数范围, 且最大人数不能比当前人数少, None表示不修改
roomname	房间名字, None表示不修改由于界面显示的问题, 房间名称长度建议不大于10个字(不区分汉字和字母)

def cghall_tell_hall_update_extra	(	self,
		extra1 = `None`,
		extra2 = `None`,
		extra3 = `None`
	)

更新房间3个扩展属性(主动调用)

在房间创建后如果想再房间的room_extra*, 可通过此函数通知大厅, None表示不修改

Parameters:

extra1	房间的扩展属性1, None表示不修改
extra2	房间的扩展属性2, None表示不修改
extra3	房间的扩展属性3, None表示不修改

def cghall_on_recv_msg	(	self,
		player,
		msg
	)

收到玩家发来的消息(重载)

当服务器初始化时调用hall_callback.register_game_room_msgdefine_and_callback接口设定的第二个参数callbackmap为空时, 服务端收到客户端的消息后会回调此函数, 由房间对客户端消息自行分发

Parameters:

player	是通过HallRoom.cghall_get_player_by_uid获得的对象
msg	是客户端发来的消息, 通过msg.get_class_name()可得到此消息的名称

def cghall_get_player_by_uid	(	self,
		uid
	)

通过uid取得玩家对象(重载)

默认情况下此函数返回大厅的player对象
此函数返回的对象将成为所有房间消息回调的player参数

Parameters:

uid 玩家的uid

Return values:

player对象将传递给消息回调函数

def cghall_get_player_by_hid	(	self,
		hid
	)

通过hid取得玩家对象(重载)

默认情况下此函数返回大厅的player对象
目前此函数暂时没有使用

Parameters:

hid 玩家的hid

Return values:

player对象

def cghall_inc_coin	(	self,
		hid,
		delta
	)

增加玩家的coin数量(主动调用)

通过此函数可增加玩家的coin的数量

Parameters:

hid	玩家的hid
delta	增量, delta>0表示增加数量, delta<0表示减少数量

def cghall_update_player_matchlvl	(	self,
		hid,
		matchlvl
	)

更新玩家的配对等级(主动调用)

当玩家配对等级有变化时, 可通过此函数设定新的配对等级

Parameters:

hid	玩家的hid
matchlvl	配对等级

def cghall_on_update_player_money	(	self,
		hid
	)

玩家的钱有更新(重载)

当非此游戏导致玩家的钱有变化时, 系统将通过此函数通知第三方玩家刷新玩家的钱

Parameters:

hid 玩家的hid

def cghall_get_serverid ( self )

获得当前服务器的编号(主动调用)

获取本房间所在的服务器编号

def cghall_get_static_rooms ( self )

获得所有静态房间的信息(主动调用)

Return values:

roomlist [list] 每个元素是一个静态房间的信息 hall_object.HallStaticRoomInfo 的实例

def cghall_execute_sql	(	self,
		sql,
		param = `{}`,
		key = `0`,
		callback = `None`,
		tag = `None`
	)

发送一条非查询的sql语句

此函数发送的sql后, 只会执行execute, 不会fetchall, 所以此接口只能发送非查询语句
sql和param一起组成一条完整的sql语句, 比如:

   sql = "UPDATE mytable SET property = %(property)s WHERE uid=%(uid)s"
   param = {'property': 'ABCDEFG', 'uid': 12345 }

放在param中的参数, 会自动进行escape; 如果param为空字典,参数写在sql中, 请自行保证参数的安全性

sql操作有结果后, 如果设置了callback则会执行callback函数, callback的参数列表如下:

 callback(code, tag, result)

code可以是如下值:
hall_consts.ERROR_SQL_OK sql执行成功;
hall_consts.ERROR_SQL_TIMEOUT sql执行超时;
hall_consts.ERROR_SQL_FAIL sql执行失败;
当sql执行成功, result为有效值: int 表示该操作影响的记录条数

Parameters:

sql	一条简单sql语句
param	sql的参数,类型: dict
key	具有相同key的sql语句会被串行执行, key=0表示该sql语句没有依赖, 类型:int, 范围: [0, 4294967295]
callback	此sql有结果之后的回调函数; None表示不需要回调;
tag	[任意类型] 异步回调的标志

def cghall_execute_sql_fetchall	(	self,
		sql,
		param = `{}`,
		key = `0`,
		callback = `None`,
		tag = `None`
	)

发送一条查询的sql语句

此函数发送的sql后, 系统会执行execute然后fetchall, 所以此接口只能发送查询语句
sql和param一起组成一条完整的sql语句, 比如:

   sql = "SELECT property, uid FROM mytable WHERE uid=%(uid)s"
   param = {'property': 'ABCDEFG', 'uid': 12345 }

放在param中的参数, 会自动进行escape; 如果param为空字典,参数写在sql中, 请自行保证参数的安全性

sql操作有结果后, 如果设置了callback则会执行callback函数, callback的参数列表如下:

 callback(code, tag, result)

code可以是如下值:
hall_consts.ERROR_SQL_OK sql执行成功;
hall_consts.ERROR_SQL_TIMEOUT sql执行超时;
hall_consts.ERROR_SQL_FAIL sql执行失败;
当sql执行成功, result为有效值, 格式为: ({}, ...) 是一个tuple, 每个元素是一个字典为查询的结果

Parameters:

sql	一条简单sql语句
param	sql的参数, 类型: dict
key	具有相同key的sql语句会被串行执行, key=0表示该sql语句没有依赖, 类型:int, 范围: [0, 4294967295]
callback	此sql有结果之后的回调函数; None表示不需要回调;
tag	[任意类型] 异步回调的标志

def cghall_execute_many_sqls	(	self,
		sql_and_param_list,
		key = `0`,
		callback = `None`,
		tag = `None`
	)

发送多条sql语句

一次发送多条sql语句, 这些语句在一个事务之中, 即如果成功即全部成功; 否则全部失败.
sql操作有结果后, 如果设置了callback则会执行callback函数, callback的参数列表如下:

 callback(code, tag, result)

code可以是如下值:
hall_consts.ERROR_SQL_OK sql执行成功;
hall_consts.ERROR_SQL_TIMEOUT sql执行超时;
hall_consts.ERROR_SQL_FAIL sql执行失败;
当sql执行成功, result为有效值, 是一个tuple, 每个元素对应一个sql的操作结果.
举例:

 sql_insert = "INSERT INTO mytable (uid, name) VALUES (%(uid)s, %(name)s)"
 param_insert_1 = {'uid': 123, 'name': 'netease'}
 param_insert_2 = {'uid': 345, 'name': 'iTownSDK'}
 sql_select = "SELECT uid, name FROM mytable"
 param_select = {}
 sql_and_param_list = [[sql_insert, param_insert_1, False],
                                                [sql_insert, param_insert_2, False], 
                                                [sql_select, param_select, True], ]
 self.cghall_execute_many_sqls(sql_and_param_list, callback=on_my_callback)

则在callback的result结果为:

 ( 1, 1, ({'uid': 123, 'name': 'netease'}, {'uid': 345, 'name': 'iTownSDK'}), )

Parameters:

sql_and_param_list	[list] 每个元素又是一个list,元素的格式为:[sql,param, isquery] 其中sql和param的意义与HallRoom.cghall_execute_sql的意义相同; isquery表示此sql是否查询,是否需要fetchall, 如果isquery为真, 则等效于:HallRoom.cghall_execute_sql_fetchall, 如果isquery为假, 则等效于:HallRoom.cghall_execute_sql; 因此,sql_and_param_list的格式为: [ [sql,param,isquery], [sql,param,isquery],...]
key	具有相同key的sql语句会被串行执行, key=0表示该sql语句没有依赖, 类型:int, 范围:[0, 4294967295]
callback	此sql有结果之后的回调函数; None表示不需要回调;
tag	[任意类型] 异步回调的标志

def cghall_get_room2client_msgmgr ( self )

取得房间和客户端之间的消息管理器

Return values:

msgmgr 消息管理器对象

def cghall_set_static_room_ready ( self )

设置此静态房间已经准备好

静态房间会在服务器启动时进行初始化;
任何静态房间, 都需要在自己的逻辑初始化完毕之后调用此函数, 告知服务器房间准备好
服务器会等所有静态房间都调用了此接口之后, 才认为服务器启动完成, 才允许玩家登录

def cghall_on_server_need_shutdown	(	self,
		timeout,
		why
	)

服务器即将关闭(重载)

服务器即将关机时, 将通过此函数通知所有房间, 建议游戏在收到此消息后停止再开一局新游戏

Parameters:

timeout	服务器将在多少秒后开始踢人关机, 类型:int, 范围:[0, 4294967295]
why	服务器关机时的提示语, 类型: str

def cghall_on_clean_static_room ( self )

服务器关闭, 需要关闭静态房间(重载)

静态房间收到此消息说明服务器已经把所有用户踢完, 静态房间请根据自己的需要做好相关数据的保存
当数据保存完毕, 房间可以被销毁时, 请调用cghall_set_static_room_clean通知系统, 否则系统将一直无法关闭

def cghall_set_static_room_clean ( self )

静态房间通知系统此房间可以关闭(主动调用)

静态房间做完数据保存工作,可以关闭时, 请调用此接口通知系统

def cghall_send_system_data	(	self,
		data,
		extra1 = `0`,
		extra2 = `0`,
		extra3 = `0`
	)

发送全服系统广播(主动调用)

调用此接口可发送全服广播, 服务器2次广播的时间间隔, 至少需要间隔10秒钟.
2次广播的时间间隔是指全服调用这个接口的时间间隔, 不仅仅是指本房间.
此接口一般用于系统级别的广播, 比如系统活动通知, 服务器需要临时关服通知等.
使用此接口时, 服务器的负载将随着在线人数的增加而大幅增加, 因此请控制使用频率.

服务器将参数中的data, extra1, extra2, extra3的数值广播给所有在线玩家(包括大厅和房间内的玩家)

Parameters:

data	系统广播的内容, 类型:str, 长度建议控制在300以内, 当长度超过1000时将不发送广播;
extra1	系统广播的内容, 类型:int, 范围: [0, 4294967295]
extra2	系统广播的内容, 类型:int, 范围: [0, 4294967295]
extra3	系统广播的内容, 类型:int, 范围: [0, 4294967295]

def cghall_req_friends	(	self,
		uid
	)

请求好友列表(主动调用)

调用此接口, 请求获取本房间中指定玩家的好友信息;
1) 此接口只能请求本房间中的玩家好友列表;
2) 两次请求之间, 间隔不能少于5秒;
3) 如果上次请求结果还没返回, 则不能再次请求;
如果请求成功发送出去, 此接口会返回True, 且通过cghall_friends_result告知好友的结果;
否则此接口返回False, 请求失败;

Parameters:

uid	请求玩家的uid, 此uid必须在此房间中;

Return values:

bool	请求是否成功发送出去;

def cghall_friends_result	(	self,
		uid,
		friendmap
	)

请求好友信息的结果(重载)

成功通过主动调用cghall_req_friends后, 系统将回调此函数来告知房间指定uid的好友信息;
在在线开发环境下, 这里返回的好友数据, 是真实的;
在离线开发环境下, 这里返回的好友数据, 是20001-20010中模拟出来,且数据是随机的;

Parameters:

uid 玩家的uid

friendmap 好友的信息, 格式为dict,
key是好友的uid, value内容是:{'nick': 昵称, 'shape': 玩家头像, 'online': 是否在线, 'ingame': 是否在此游戏中, 'twoway': 对方是否也加自己为好友}
friendmap格式如下:
{ uid: ## 好友的uid
{'nick': '好友的昵称', 'shape': 玩家头像, 'online': 此好友是否在线, 'ingame': 是否在此游戏中, 'twoway': 对方是否也加自己为好友},
}

def cghall_forward_to_uid	(	self,
		touid,
		data
	)

请求给其他房间的玩家转发消息(主动调用)

调用此接口, 给在其他房间的玩家转发消息.
如果该玩家不在房间中, 则消息将被丢弃.

Parameters:

touid	[int] 消息的接受者的uid(此uid不能在本房间中)
data	[string] 消息内容, 长度不要超过10240

Return values:

bool	消息是否被转发出去, 目前只有以下情况会返回False, 其他情况返回True: touid 在本房间中 data内容长度超过10240

def cghall_on_recv_forwarded_data	(	self,
		touid,
		data
	)

收到来自其他房间转发来的消息(重载)

收到来自其他房间转发过来, 给touid的消息;

Parameters:

touid	[int] 此消息是发送给本房间内的touid用户的
data	[string] 消息内容

def cghall_gametime_start	(	self,
		hid
	)

玩家实际有效游戏时间计时开始(主动调用)

平台需要统计每个玩家的有效的游戏时间
因此需要游戏在玩家开始进行有效游戏时, 调用cghall_gametime_start接口开始计时
在玩家有效游戏时间结束时, 调用cghall_gametime_stop接口,停止计时
在调用过cghall_gametime_start之后在调用cghall_gametime_stop之前, 再次调用cghall_gametime_start, 将以后者为准, 前面的时间将抛弃;
如果在调用过cghall_gametime_start之后, 知道玩家离开此房间, 都没再调用cghall_gametime_stop接口, 则cghall_gametime_start之后的时间将被抛弃, 不做记录;
即一次有效的游戏时间, 应该是cghall_gametime_start和cghall_gametime_stop都被调用了, 才会生效;

Parameters:

hid 玩家的hid

Return values:

bool	返回True表示开始计时; 返回False表示调用失败-目前失败的原因是此hid不在此房间中

def cghall_gametime_stop	(	self,
		hid
	)

玩家实际有效游戏时间计时结束(主动调用)

在玩家有效游戏时间结束时, 调用此接口
更多详细说明请查看cghall_gametime_start的API说明;

Parameters:

hid 玩家的hid

Return values:

bool	返回True表示计时成功, 返回False表示计时失败-可能此hid不在此房间中,可能是之前没有调用cghall_gametime_start接口;

def cghall_query_player_info	(	self,
		uid
	)

向数据库查询指定玩家的基本信息(主动调用)

此接口向数据库发起一次查询, 因此建议仅对非本房间的玩家进行此操作;
查询有返回后,会通过回调cghall_on_recv_player_info函数通知房间;

Parameters:

uid	需要查询的玩家uid

def cghall_on_recv_player_info	(	self,
		code,
		uid,
		info
	)

向数据库查询指定玩家的基本信息的返回结果(重载)

此接口是cghall_query_player_info结果的回调

Parameters:

code	查询结果的错误码: hall_consts.ERROR_QUERY_OK: 查询成功 hall_consts.ERROR_QUERY_TIMEOUT: 服务器内部错误,查询超时 hall_consts.ERROR_QUERY_NOUSER: 查询用户数据失败: 该用户不曾登录此游戏 hall_consts.ERROR_QUERY_FAILED: 查询用户数据失败: 服务器内部错误,未知错误类型,此时服务器应该有traceback了
uid	被查询的玩家uid
info	查询的用户数据, info格式为: info = { 'nickname': '', # hall_player.HallPlayer.nickname 'coin': 0, # hall_player.HallPlayer.coin 'score': 0, # hall_player.HallPlayer.score 'win_count': 0, # hall_player.HallPlayer.win_count 'lose_count': 0, # hall_player.HallPlayer.lose_count 'draw_count': 0, # hall_player.HallPlayer.draw_count 'break_count': 0,# hall_player.HallPlayer.break_count }

def cghall_query_player_bufmap	(	self,
		uid
	)

向数据库查询指定玩家的buf信息(主动调用)

此接口向数据库发起一次查询, 因此建议仅对非本房间的玩家进行此操作;
查询有返回后,会通过回调cghall_on_recv_player_bufmap函数通知房间;

Parameters:

uid	需要查询的玩家uid

def cghall_on_recv_player_bufmap	(	self,
		code,
		uid,
		bufmap
	)

向数据库查询指定玩家的buf信息的返回结果(重载)

此接口是cghall_query_player_bufmap结果的回调
hall_consts.ERROR_QUERY_OK: 查询成功
hall_consts.ERROR_QUERY_TIMEOUT: 服务器内部错误,查询超时
hall_consts.ERROR_QUERY_NOUSER: 查询用户数据失败: 该用户不曾登录此游戏
hall_consts.ERROR_QUERY_FAILED: 查询用户数据失败: 服务器内部错误,未知错误类型,此时服务器应该有traceback了

Parameters:

uid 被查询的玩家uid

bufmap

查询的用户的buf数据, bufmap格式与hall_player.HallPlayer.buf一致

   bufmap = {
       'buf0': '', # value是该buf的实际内容, 格式为字符串;
       'buf1': '',
       'buf2': '',
       'buf3': '',
       'buf4': '',
       'buf5': '',
       'buf6': '',
       'buf7': '',
       'buf8': '',
       'buf9': '',
       'buf10': '',
       'buf11': '',
       'buf12': '',
       'buf13': '',
       'buf14': '',
       'buf15': '',
   }

HallRoom Class Reference

Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation