棋牌协议说明书.doc

游戏服务器通信协议设计说明书 UniSync Protocol V1.5文档编号：UniSheng-2004-08-21-yx-1联盛TeveQ游戏服务器设计 （Ver 1.5）协议设计书项目负责人 ：乐祥北京联盛无限科技有限公司版权所有，违者必纠版数改版年月日改版记事确认查阅执行初版2004/07/27乐祥V1.32004/09/14乐祥V1.42004/10/11新协议追加，强化用户体验乐祥V1.52005/04/09聊天管理乐祥版数制定/ 改订日位置制定理由/ 改定要点/ 废止理由备注初版1.02004/07/27全章新规2004/09/083173181添加HLD命令减少协议传输中的冗余问题2添加CHG命令2004/09/0911 游戏列表不从web获取，改成通过MGS入口server获取2 VER命令中添加oemid参数2004/09/1032追加 登陆类对话框的用户响应V1.32004/09/141 参考韩松文档追加新功能2 删除DLG命令，改用FRM命名2004/09/273.91.增加画网格命令2004/09/283.33.43.213.221. GML命令中增加游戏服务器分层次管理功能2. 删除游戏人数UCT命令3. 删除HLD命令4. 删除CHG命令2004/10/063.20增加广告命令：ADVV1.42004/10/113.63.73.81. 增加用户注册命令：REG命令2. 增加找回密码命令：GWD命令3. 增加修改用户资料命令：MOD命令2004/10/123.33.193.203.211. GML 1 命令中增加ip和port2. GML 3 命令中增加tag标志房间是否满员3. 增加聊天命令 CHT4. 增加显示信息命令 SHW5. 增加用户操作命令 OPR2004/10/133.13.53.23.33.20.33.20.43.211. 修改PLT命令参数说明2. 修改登录命令 LGN3. 修改版本检查命令的响应 VER4. 修改游戏列表,增加GML 1请求命令 5. 参考军强Review结果，修改SHW命令添加是否在线标志6. 参考军强Review结果,修改OPR命令 操作成功res项为空2004/10/183.21. 修改版本响应命令，增加一个有新版本但老版本可以继续使用的命令2004/10/193.20.33.20.43.20.51. 参考军强建议，返回信息中增加用户级别和财富2. SHW 4命令的响应中增加tag参数，标识请求命令的类型2004/10/203.273.20.53.20.63.20.71. 增加游戏房间操作命令 PLY，处理用户在游戏大厅选择座位然后等待进入游戏的状态变化2. 增加道具类别命令2004/10/213.71. 找回密码，增加一个UQ参考军强建议2004/10/223.83.20.33.20.41. 用户修改资料中，添加新老密码，防止别人恶意修改2. 好友和黑名单列表中增加用户性别字段2004/10/233.253.3.11. 增加游戏服务器向登录服务器发送退出命令2. 获取游戏类表中增加sectionid返回2004/10/253.21.61. 使用道具命令在客户端和游戏服务器之间使用2004/10/263.191. 增加命令：新消息通知，退出聊天2. 修改CHT 1命令2004/10/273.253.27.43.27.53.27.21. 退出命令中增加：2:用户游戏中强行退出2. 增加游戏开始通知命令3. 增加游戏结束通知命令4. 修改房间状态变化的发送方式：无须客户端请求，服务器自动发送2004/10/283.20.81. 增加上线标志通知命令2004/10/293.20.83.251. 上线标志通知中增加游戏id2. 退出命令中增加游戏id2004/10/303.53.20.83.251. LGN命令中增加sectionid参数2. SHW 7命令中增加sectionid参数3. EXT命令中增加sectionid参数2004/11/013.27.23.27.31. 房间状态信息中，座位上没人的不发送状态信息减少信息冗余2. 删除PLY 4命令中的uq参数，减少冗余3. 增加用户离开游戏大厅命令2004/11/033.271. 座位方位编号修改(0,1,2,3 - 2,3,1,0)2004/11/053.281. 增加游戏超时通知命令2004/11/103.20.91. 增加获取系统帮助信息处理命令2004/11/113.293.301. 增加客户端使用区域通知命令RGN2. 增加超时时钟停止控制通知2004/11/153.61. 参考强的建议,增加推荐人的uq2004/11/163.11. 通知客户端如何装载图标2004/11/203.27.41. 采纳军强的建议增加超时类型2. 修改PLT相应命令，删除图层，放到BMG命令中3. 增加通知客户端图片装载方法BMG命令2004/11/223.323.331. 和军强讨论决定增加对话框命令DLG2. 增加和悔认输命令2004/11/293.331. 参考军强的建议，V1.4版本不传alttxt参数2004/12/013.321. 军强讨论结果DLG命令中增加type参数2004/12/033.20.21. 修改获取对手信息命令2004/12/063.20.103.27.51. 增加查询用户是否在线命令2. 修改游戏结束通知命令2004/12/093.19.11. 军强讨论结果修改聊天信息命令2004/12/103.20.11. 修改获取对手信息和用户自己信息的通讯方向，改成客户端向游戏服务器直接发送2004/12/153.19.33.3.11. 增加聊天信息详细说明，包括聊天常用语定义2. 游戏主列表中追加游戏图标id字段2004/12/163.101. MNU命令中增加menuid字段2004/12/213.20.21. 获取对手信息SHW 9 - SHW 10,9已经被使用2004/12/223.51. 军强讨论确定增加快速进入游戏功能，修改LGN 1命令，增加LGN 3命令2004/12/233.27.13.61. 增加：通知客户端游戏桌游戏已经开始，统一使用PLY命令2. 注册命令中增加字段：用户头像id和个人签名2004/12/2741. 插入一节4 ,获取登陆服务器的ip地址2004/12/283.27.53.51. 游戏结束通知中增加一个参数winflag通知客户端用户输赢和的情况2. 增加说明用户不能快速进入游戏的返回说明2005/01/033.81. 修改用户资料中，获取的时候返回头像id和个性签名2005/01/043.111. 追加BGD 6命令说明，原来的BGD 6命令改称BGD 7命令2005/01/053.27.51. PLY 6命令后的参数位置调整，客户端会存在参数长度越界的问题2005/01/063.61. 用户注册信息中增加用户出生日期字段2005/01/113.21. 增加help,tips,adv信息版本2005/01/123.19.13.321. 修改layout2005/01/133.341. 增加游戏控制权标志通知命令 TAG2005/01/173.13.351. 修改PLT响应命令 step checkonlinetimespan2. 增加ONL命令2005/01/183.61. 参考军强建议调整birthday字段的位置2005/01/203.81. 修改用户资料中增加birthday,recomid字段2005/01/223.21. 新版本中不提供prog_ver给客户端2005/01/263.203.27.53.27.23.27.11. 修改SHW 1命令，增加字段2. 修改游戏结果通知命令，便于客户端动画显示3. PLY 3命令中增加sublevel字段4. PLY 2命令中增加sublevel字段2005/01/313.81. MOD 3命令直接表示修改成功，不返回uq和密码2005/02/013.23. 261. 广告不传具体的内容，传送广告编号id2. 修改ADV命令，支持动态获取具体广告内容2005/02/043. 221. 修改动画命令，梭哈动画特殊处理2005/02/243.261. ADV命令增加参数userid2005/02/253.20.111. 增加SHW 11命令2005/02/283.20.91. 修改SHW 8命令，获取具体的帮助信息2005/03/013.20.121. 增加SHW 12命令，获取用户的星辰运势2005.03.023.43.20.121. 警告命令修改，特别说明2. SHW 12命令响应中增加astroindex2005/03/053.43.20.121. ALT命令增加类别22.增加三个指数2005/03/113.20.11. 级别TTL添加2005/03/233.11. 增加4参数，标示是否给Kjava发送激活指令2005/04/063.191.修改聊天协议，支持图文混合和用户自定义聊天V1.52005/04/093.51.增加spthumbnail字段2. 增加3.20.13/14/15节，实现合作伙伴广告发布功能3. 增加3.19.6节修改3.19.3节，实现信息广播功能 2005/04/183.3.41. 增加GML 4命令/响应2005/04/22471. 增加休闲游戏扩展指令集2. 修改第7节为协议加密算法说明，删除原来的手机型号，具体的手机型号说明参考其他文档2005.04.273.27.21. PLY 3命令中增加用户呢称2005.05.043.19.6-101. 增加留言板功能指令2. 增加管理员使用特殊指令2005.05.173.11. 增加origin中的参数42005.05.244.31. 增加道具方向参数目前连连看和对对碰使用2005.06.064.31. 增加x,y参数泡泡龙俄罗斯专用2005.06.144.11. 增加STS 3指令2005.06.153.41. ALT指令增加类型3，需要响应2005.06.273.21.增加ClientID参数，标识每个客户端2005.07.063.13.21.71.增加协议版本参数2. 增加搜索好友指令2005.07.133.21.71. 增加showid参数2005.07.153.19.81.增加showid参数2005.07.213.121. ITEM增加Digital属性2005.07.283.27.11.PLY 1 增加toolflag参数控制房间是否有道具2005.07.293.21.73.213.19.73.27.13.3.43.61. 检索条件中增加年龄段+城市2. 修改OPR命令的响应3. 增加OPR 8指令4. 增加OPR 9指令5. 发送留言的回复指令修改6. 参考军强建议，有无道具放到PLY 1处7. gamid ：18000分给聊天室专用8. 注册中增加城市字段2005.08.193.20.103.19.101. 增加子命令2标识游戏币更新2. 删除留言中增加全部删除指令2005.08.223.21.103.21.113.19.11.增加点券和游戏币兑换相关指令2.聊天标题中增加头像2005.08.293.19.21. 增加头像2. 增加CHT 3指令响应2010.1.83.361. 增加AMY指令2. 修改LGN REG指令3. 增加PLY 8指令 目 录1概述102屏幕控制113协议命令集123.1平台检查 PLT143.2版本检查 VER153.3游戏列表 GML173.3.1获取游戏列表173.3.2获取游戏分区列表183.3.3获取游戏房间列表183.3.4获取游戏房间列表扩展193.4警告 ALT203.5登录 LGN213.6注册 REG223.7找回密码 GWD233.8修改用户资料 MOD243.9表单 FRM已经取消不用实现263.10菜单 MNU313.11屏幕背景 BGD323.12屏幕元素 ITM343.13光标 CUR383.14静态文本 TXT393.15滚动文本 SIP已经取消不用实现393.16空闲 IDL403.17游戏控制权 CTL403.18游戏动作 ACT413.19聊天 CHT413.19.1获取聊天信息413.19.2选择聊天对象433.19.3发送聊天信息443.19.4新消息通知453.19.5退出聊天453.19.6游戏中广播信息通知453.19.7发送留言463.19.8获取留言463.19.9回复留言473.19.10删除留言483.20显示信息 SHW483.20.1获取用户信息493.20.2获取对手信息523.20.3获取好友列表523.20.4获取黑名单列表533.20.5获取用户道具533.20.6获取道具类别543.20.7获取道具类别中道具543.20.8上线标志通知553.20.9获取系统帮助信息553.20.10查询用户是否在线563.20.11获取用户最新配置563.20.12获取用户星辰运势573.20.13获取合作伙伴广告信息583.20.14获取合作伙伴广告分类详细信息583.20.15获取合作伙伴广告详细信息593.21用户操作 OPR593.21.1添加好友593.21.2删除好友603.21.3添加黑名单603.21.4删除黑名单613.21.5购买道具613.21.6使用道具613.21.7检索好友623.21.8添加好友请求633.21.9添加好友请求应答633.21.10获取兑换比率633.21.11兑换点券/游戏币643.22动画 ANM653.23快捷键 FKY已经取消不用实现653.24暂停 SLP已经取消不用实现663.25退出 EXT663.26广告 ADV673.27游戏房间操作 PLY673.27.1通知房间座位673.27.2游戏房间状态汇报683.27.3游戏玩家状态变化693.27.4游戏开始通知703.27.5游戏结束通知713.27.6游戏结束通知713.28游戏超时通知EXP713.29客户端使用区域通知 RGN723.30通知客户端游戏超时控制停止 TTP723.31通知客户端图片装载方法 BMG723.32对话框命令 DLG733.33和悔认命令 BOS743.34游戏控制权标志通知命令 TAG753.35客户端在线通知命令 ONL753.36充值命令 AMY764TeveQ休闲协议命令集基本协议扩展774.1玩家状态 STS784.2实时数据 HTY814.3使用道具 MGT815系统管理员使用指令885.1发布公告885.2踢人885.3查询用户量886获取登陆服务器ip地址897分隔符898协议加密909获取移动手机号码9010参考文件901 概述本文档制订的是适用于“棋牌世界”里的所有棋牌类游戏（包括麻将）的通信协议，该协议由一些基本的控制命令组成，与具体的游戏规则无关。本协议主要说明手机游戏与服务器之间进行通信的基本内容，包括手机游戏对服务器的请求（Request），服务器的应答（Response）。本游戏服务器支持多种Client端，包括手机、PC等。虽然各种Client端游戏程序界面和运行的硬件平台各不相同，但是由于所有的Client与Server的通信采用的是相同的游戏协议，因此也都能够进行游戏。MGS 1 MGS 2 MGSLoginServer DBS 图1-1系统总体结构图对于手机端，支持三大平台：KJAVA平台（中国移动-CMCC）和BREW平台，UniJava平台（中国联通-UNICOM）。手机游戏首先通过登录LoginServer（以下缩写为LGS）来得到棋牌游戏列表（每款游戏对应一个服务器），用户选择游戏后，就自动与相应的游戏服务器连接。游戏用户分区管理。每个服务器管理固定数量的用户，一旦用户数量超过极限，就增加新的服务器来处理，而软件本身不做任何改动。棋牌世界实现了智能机器人功能。当一个人等待对手时间过长时（如10秒），手机游戏服务器（Mobile Game Server：以下简称MGS）自动启动机器人与真人进行比赛。在比赛过程中，如果某个人因断线或退出时，在等待一定时间后，MGS也自动启动机器人来替换他。该比赛者断线后重新进入，如果比赛还未结束，他可以旁观机器人替自己完成当前局的比赛，这局比赛完后，MGS自动关闭机器人，原比赛继续加入。2 屏幕控制由于手机端的游戏程序是抽象了“棋牌世界”的所有游戏，而不是针对某款具体的游戏，需要将这些“棋牌”类游戏的所有屏幕表现的元素和动作进行抽象。因此，需要服务器来根据具体的游戏和具体的手机屏幕大小来给手机端游戏程序发送命令，控制手机来绘制游戏屏幕。主要的屏幕控制对象包括：（1）屏幕背景；（2）图片元素： 对棋类游戏：棋盘、棋子、对牌类游戏：牌个人头像、按钮、图标、轮流标记（3）文本（4）菜单（5）对话框手机端的屏幕永远都是全部绘制，具体的绘制内容是由MGS针对用户选择的不同游戏和游戏的进展发送不同的命令来完成的。3 协议命令集本协议的内容是一个高度抽象的描述性协议，每条命令执行一个基本的屏幕显示，而在实际使用中，用户的一个操作可能包含了多个命令的组合，每条命令都以换行符结束。本协议是基于文本字符流的，每个数据包就是一个命令行，命令行的结束标志是一个换行符。这样做的一个最大好处是服务器端在开发过程中，可以不依赖Client端程序而直接通过Telnet程序来独立地进行对服务器的调试和测试。协议主要以命令行的形式来实现，这些命令的基本格式为： CMD param_1，param_2，param_n一个完整的命令包括3个组成部分：n 命令标识CMD表示命令标识符（命令标识符必须大写）；统一用3个大写字符来表示各个功能命令；n 命令参数param_1, param_2, param_n为命令参数命令参数必须小写，除非客户的信息里包括大写字符n 命令结束符换行符必须使用换行符（n）表示一个命令行的结束。备注：命令符与参数之间用空格符分隔；各个参数之间用逗号（，）分隔。协议制订基本原则主要有下面3条：n 冗余性。协议中的每条命令不包括任何冗余数据，尽量缩短命令的长度，减少网络通信量。n 准确性。协议中的每条命令，其信息必须全面、精确，不存在二义性。n 安全性。协议中还必须考虑服务器和手机端程序的安全性，防止任何可能的对游戏的恶意篡改。本式样书中定义的命令集如下表：No.Commd命令全称功能1PLTPlatForm平台检查2VERVersion版本检查3GMLGameList游戏列表4ALTAlert警告5LGNLogin登录6REGRegister注册7GWDGetPassword获取密码8MODModification修改用户资料9FRMForm表单10MNUMenu菜单11BGDBackground屏幕背景12ITMItem屏幕元素13CURCursor光标14TXTText静态文本15SIPSlip滚动文本16IDLIdle空闲17CTLControl游戏控制权18ACTAction游戏动作19CHTChat聊天20SHWShow显示信息21OPROperation用户操作22ANMAnimation动画23FKYFlashKey快捷键24SLPSleep暂停25EXTExit退出26ADVAdvertise广告27PLYPlayer Status玩家状态变化命令28EXPExpire超时命令29RGNClient Region客户端使用区域通知命令30TTPTimeoutStop客户端超时停止控制命令31BMGBuilder Image组装图片命令32DLGDialog对话框命令33BOSBackOneStep棋类中的认输，和棋和悔棋命令34TAGTag游戏控制权标志图标通知命令（当前版本仅限中国象棋,五子棋和黑白棋）35ONLOnline客户端定期给服务器发送在线标志36BRDBroadcast Message管理员发布公告信息37TKOTickOut Player管理员踢人38CHKCheck Online Player count管理员查询用户量下面将具体地对每条命令进行消息描述：3.1 平台检查PLT说明：本命令是手机给服务器（LGS/MGS）发送的第一条命令。检查手机端平台：KJava平台，BREW平台，UniJava平台。由于MGS与KJava手机采用UTF8编码，而与BREW手机采用UNICODE编码，所以本命令需要按ANSI格式发送，以便于MGS确定客户端手机平台类型。l 用户请求 （客户端 - 服务器）命令格式PLT sp,mobileplat, modelname,origin, w, h, fw, fh,protocolversion说明手机平台检查命令。参数说明参数说明spsp编号mobileplat手机平台0：缺省（ANSI）1：KJAVA平台（UTF8） - 发送激活指令2：BREW平台（Unicode）3：UniJava平台（UTF8）4：KJAVA平台（UTF8） - 不发送激活指令modelname手机型号名称，例如：BREWPHONE，NK3650等等origin客户端来源1 : CDMA 2 : KJava3 : UniJava4 : Kjava休闲系列发送扩展游戏列表w,h手机屏幕大小fw, fh手机字体大小protocolversion当前协议版本，版本用字符串表示，例如：USP15,表示当前版本为：UniSync Protocol V1.5通过协议版本参数可以实现版本的向下兼容。当前版本为： USP15l PLT命令响应 （ 游戏服务器/登陆服务器 - 客户端）命令格式PLT checkonlinetimespan说明通知客户端定时向服务器发送是否在线命令的时间周期参数说明参数说明checkonlinetimespan客户端定时向服务器发送是否在线命令的时间周期（单位：秒）由于运营商网关延迟，造成服务器不能及时检测用户掉线（例如：对于Brew手机的关盖，拔电池，突然没电），为了及时检测用户是否在线，需要客户端定时给服务器发送ONL命令，通知服务器客户端还在线。客户端给服务器发送ONL的时机应该是用户没有任何socket数据收发的情况下累计时间到达checkonlinetimespan。3.2 版本检查VER检查客户端程序版本。本操作在LGS上完成。如果客户端程序需要更新，LGS需要提醒用户，由用户自己去下载最新的客户端程序。l VER (客户端-服务器)命令格式VER clientid, model, pro_ver,res_ver,ad_ver,help_ver,tips_ver说明手机端程序向LGS发送版本检查命令。参数说明参数说明clientid客户端的标识号码，长度50个字符。客户端统一编号，编号从1开始，每个不同的客户端分配一个唯一的识别ID。对于KJava客户端，采用jar包名作为识别号码（不包含.jar）model手机型号名称，例如：BREWPHONE，NK3650等等pro_ver手机端程序的版本号res_ver手机端程序的资源文件版本号ad_ver系统广告版本help_ver系统帮助信息版本保留tips_ver系统tips版本此命令是用户连接服务器后，发送的第二条命令。 l VER命令响应 (服务器-客户端)命令格式VER res,resurl,resextname,resid,adttl,adid,helpmsg,tipsmsg,newres_ver,newad_ver,newhelp_ver,newtips_ver说明服务器向客户端发送版本检查的响应信息。参数说明参数说明res0 - 版本检查成功1 - 客户端有新版本,老版本可以继续使用2 - 客户端程序版本太低，必须下载新版本3 - 客户端资源版本太低4 - 客户端广告内容版本太低5 - 客户端帮助信息版本太低6 - 客户端Tips信息版本太低7 最新的版本号当res=3,4,5,6,7的时候需要分析res后面的内容resurl资源文件所在的urlresextname资源文件扩展名，例如：png ， gifresid需要更新的资源id号，多个资源id用逗号分割adttl广告信息的标题adid广告信息的编号helpmsg系统帮助信息tipsmsg系统Tips信息newres_ver最新的客户端资源版本号newad_ver最新的客户端广告信息版本号newhelp_ver最新的客户端帮助信息版本号newtips_ver最新的可户端Tips信息版本号 表示可选 表示多个客户端收到res 7 命令的时候，需要保存最新的各相关项目的版本号，下次再登陆的时候，应该给服务器发送最新的版本号。客户端必须保证所有需要更新的资源都被正确更新了以后，才能保存最新的版本。资源更新只限头像和表情，其他资源不能动态更新如果用户需要查看详细的广告信息，客户端需要根据adid，从登陆服务器或游戏服务获取。详细的命令请参考ADV命令注 对于不需要更新的版本号，版本号设置为03.3 游戏列表GML用户登录成功以后，LGS首先向客户端发送GML 1命令，客户端得到游戏主类信息包括游戏id，游戏名，当前用户量和当前人数最多的服务器的ip地址和通讯端口。当用户选择一个游戏的时候，自动进入用户登录时候人数最多的游戏服务器。用户可以通过客户端的设置工具选择不同的游戏服务器分区或游戏房间。客户端根据用户的选择向服务器发送获取游戏分区信息（GML 2命令），LGS收到GML 2命令，发送游戏分区信息给用户，客户端根据用户的选择向服务器发送获取游戏房间信息（GML 3命令），LGS收到GML 3命令，发送游戏分区内的房间信息给用户。3.3.1 获取游戏列表l 客户端向服务器发送获取游戏列表命令格式GML 1说明客户端向LGS发送该命令，获取游戏主类列表信息参数说明参数类型说明l 服务器响应命令格式GML 1, game_id, game_name,imgid ,usercount,ip,port ,sectionid说明参数说明参数类型说明game_id游戏编号game_name游戏名称以五子棋游戏为例：五子棋imgid游戏对应的小图标idusercount游戏用户量ip当前最多用户量的游戏服务器的ipport当前最多用户量的游戏服务器的通讯端口sectionid游戏分区id 表示可以多个重复如果没内容，则只返回GML 13.3.2 获取游戏分区列表l 客户端向服务器发送获取游戏分区信息命令格式GML 2, game_id说明参数说明参数类型说明game_id游戏编号l 服务器向客户端发送游戏分区信息命令格式GML 2, section_id,name,usercount说明参数说明参数类型说明section_id游戏分区编号name游戏分区名usercount本分区内用户量 表示可以多个重复如果没内容，则只返回GML 23.3.3 获取游戏房间列表l 客户端向服务器发送获取游戏房间信息命令格式GML 3,game_id, section_id说明参数说明参数类型说明game_id游戏编号section_id游戏分区编号l 服务器向客户端发送游戏分区内房间信息命令格式GML 3, name,ip,port,usercount,tag说明参数说明参数类型说明name游戏房间名ip游戏房间的ip地址port游戏房间的通讯端口usercount游戏房间内用户量tag人数是否已满（0：未满，1：满） 表示可以多个重复如果没内容，则只返回GML 33.3.4 获取游戏房间列表扩展l 客户端向登陆服务器发送获取游戏信息命令格式GML 4说明参数说明参数类型说明l 登陆服务器向客户端发送游戏房间信息命令格式GML 4,gamecount,gamid,gamename,imgid,usercount,roomcount,roomid, roomname,comment,ip,port,needmoney,usercount,supportcount说明当前版本，客户端不需要给登陆服务器发送GML 4命令，当客户端登陆成功以后，登陆服务器将主动发送GML 4的响应信息给客户端。参数说明参数类型说明gamecount游戏的个数gameid游戏编号编号：18000作为聊天室专门使用，客户端判断是18000的时候需要显示聊天室对应的图标。gamename游戏名称imgid游戏的小图标id usercount游戏目前在线人数roomcount游