客户端游戏接入QQGame游戏大厅，由大厅拉起游戏进程，并与QQGame进行数据等交互；同时，客户端游戏需要按大厅要求的格式准备安装包，大厅进行游戏的安装及更新。文档中定义大厅打安装包规则、拉起游戏进程命令行参数及与大厅通信的详细内容，对客户端进行接入时，请勿必仔细阅读此文档，确认需要实现的内容。
现QQGame游戏大厅支持两种方式与游戏建立进程间通信：websocket与管道。两种方式的命令行参数和协议格式不同，游戏可选择一种。推荐使用websocket方式，因为协议格式是json明文方式更方便联调检查。
websocket通信和协议
游戏进程命令行参数
大厅拉起游戏进程时，会带上以下命令行参数，游戏进程要进行解析使用
|
参数格式：id=XXXX key=YYYY pfkey=ZZZZ port=8888 |
||||
|
参数项 |
id |
key |
pfkey |
port |
|
参数说明 |
Openid |
Openkey |
pfkey |
端口号 |
|
最大长度 |
36 |
256 |
256 |
|
|
参数作用 |
用于游戏与后台连接， 实现拉取玩家信息、支付等功能 |
支付参数，详见 |
|
用于游戏和大厅建立websocket连接 |
大厅与游戏通信
使用websocket进行通信，大厅作为服务端，游戏作为客户端。
(1)通信连接
游戏进程从命令行参数取得Openid和端口号，拼接URL并进行websocket连接，后续通信均基于该连接进行
注意：游戏进程启动后需尽快进行连接。超时时间30秒。
例如，命令行参数是：
id=XXXX key=YYYY pfkey=ZZZZ port=8888
拼接后的URL如下：
ws://127.0.0.1:8888/websocket/XXXX
(2) 通信协议
游戏 to 大厅
|
项目 |
命令 |
说明 |
是否必须 |
|
游戏退出 |
{"cmd":"game_exit"} |
游戏退出前通知大厅 |
必须 |
|
打开页面 |
{ "cmd":"open_web", "caption":"窗口标题", "url":"https://qqgame.qq.com", "width":1440, "height":900 } |
游戏请求大厅带登录态打开页面。 仅支持腾讯域的页面 |
可选 |
|
打开支付 |
{ "cmd":"pay", "param":"xxxxx" } |
param请参考： 客户端游戏支付页接入中的购买商品-使用大厅提供的购买页部分。 |
可选 |
|
购买蓝钻 |
{ "cmd":"buy_vip", "param":"xxxxx" } |
param请参考： 客户端游戏支付页接入中的开通蓝钻部分。 窗口关闭后，会返回"vip_info"消息。 |
可选 |
|
项目 |
命令 |
说明 |
是否必须 |
|
老板键 |
{"cmd":"boss_key", "show":0} |
游戏侧跟进参数show显示或隐藏游戏界面。 show：0隐藏，非0显示 |
必须 |
|
前置显示 |
{"cmd":"bring_to_top"} |
游戏收到该消息后，前置显示界面 |
必须 |
|
页面关闭 |
{"cmd":"web_close"} |
open_web请求的页面关闭时，通知游戏。 |
可选 |
|
支付关闭 |
{"cmd":"pay_close"} |
支付页关闭时，通知游戏 |
可选 |
|
购买蓝钻 页面关闭 |
{"cmd":"buy_vip_close"} |
购买蓝钻页面关闭，游戏需刷新蓝钻信息。参考： |
可选 |
管道通信和协议（旧的连接方式，不建议使用）
游戏进程启动参数
|
参数格式：ID=XXX,Key=YYYY,PROCPARA=ZZZZZ |
|||
|
参数项 |
ID |
Key |
PROCPARA |
|
参数说明 |
openid |
openkey |
进程通信参数 |
|
最大长度 |
36 |
256 |
128 |
|
参数作用 |
用于游戏与后台连接，实现拉取玩家信息、支付等功能 |
用于游戏和大厅建立进程通信，大厅通过这个连接来判断游戏是否在线，并通过这个通道来进行游戏与大厅间的数据通信 |
|
|
使用注意 |
openid、openkey，为必需项，游戏业务需要用到； PROCPARA，为必需项，大厅要求游戏必须与大厅建立进程通信。 |
||
|
常见反馈问题 |
1、游戏在安装后，会被拉起多次？ 答：请在游戏进程拉起时，对启动参数进行判断，ID、Key、PROCPARA是必须的数据，如果没有这些数据，请直接退出启动流程，不要启动游戏。 |
||
进程通信
|
进程通信 |
源码示例 |
在《pc客户端游戏demo》中，《TestClient_Demo_C++》《TestClient_Demo_C#》两个不同语言的demo可供参考。 |
|
接入方案 |
两种方案如下： 1、游戏客户端有一个进程始终与大厅通信，直到游戏退出才退出； 2、游戏客户端有多个进程与大厅通信，始终保证进行通信一直存在到游戏退出，采用此方案请关注【游戏多进程与大厅连接】 |
|
|
通信协议 |
数据结构定义 |
#define MAX_PROCMSG_DATABUF_LEN 64*1024 typedef struct stProcMsgData { int nCommandID; //协议ID，下面一栏给出现有的各ID定义及用法 int nDataLen; //buffer长度 BYTE abyData[MAX_PROCMSG_DATABUF_LEN]; //buffer，如果有需要传递的数据，全部放这里 }PROCMSG_DATA; |
|
|
协议ID |
游戏发给大厅的： |
|
CS_GAME_EXIT 0x00000001 游戏进程退出通知大厅 |
||
|
CS_REQ_NEWCONNECTION 0x0000000B 请求建立新连接 使用场景：多进程与大厅通信，详情请查阅【游戏多进程与大厅连接】部分 |
||
|
CS_REQ_NEWACCOUNT??0x0000000C 请求其它账号登录 需要与QQGame侧接入同事确认开通“多帐号登录”功能 |
||
|
CS_CLIENT_GAME_PAY_WEB 0X00000050 客户端游戏请求打开支付页面 nDataLen：长度，abyData：支付参数，字符串 支付参数请参考：客户端游戏支付页接入 |
||
|
CS_CLIENT_GAME_BUY_VIP_WEB 0X00000051 客户端游戏请求打开购买蓝钻页面 nDataLen：长度，abyData：支付参数，字符串 支付参数请参考：客户端游戏支付页接入 |
||
|
大厅发给游戏的： |
||
|
SC_BOSSKEY 0x00000003 老板键 数据项：int值,0是隐藏，1是显示 使用场景：大厅老板键（Alt+Q）隐藏和显示时 |
||
|
SC_WND_BRINGTOP 0x00000004 通知游戏界面最新展示 使用场景：游戏窗口被其它程序遮盖，在大厅中再点app图标时，把游戏窗口拉到最前 |
||
|
SC_RESPONSE_NEWCONN 0x0000000B 大厅同意游戏请求新起连接 nDataLen：长度，abyData：连接名，字符串 详情请查阅【游戏多进程与大厅连接】部分 |
||
|
SC_RESPONSE_NEWCONN_RUFUSE 0x0000000C 大厅拒绝游戏请求新进程连接 详情请查阅【游戏多进程与大厅连接】部分 |
||
|
SC_CLIENT_GAME_PAY_WEB 0X00000050 大厅通知游戏购买页面关闭 |
||
|
SC_CLIENT_GAME_BUY_VIP_WEB 0X00000051 大厅通知游戏蓝钻购买页面关闭 购买蓝钻页面关闭，游戏需刷新蓝钻信息。参考： |
||
|
使用场景 |
游戏有多个进程，而且有类似的逻辑例如：Launcher.exe先运行，负责更新版本等业务，版本更新后Launcher.exe就退出，拉起游戏的主进程Main.exe；这样的情况下，由于大厅只能维护一条连接，即只识别Launcher.exe，该exe退出后，大厅会识别为游戏已经退出。 如果游戏是类似上面的这种逻辑，则需要仔细看下面内容，按下面所引导的方法接入游戏。 |
|
|
使用方法 |
（先定义场景：游戏先起A.exe，然后起B.exe，A.exe结束，后面可能又起C.exe，B.exe退出...） 游戏应该这样处理： 1、启动A.exe，用大厅启动的命令行参数中PROCPARA来与大厅建立连接； 2、退出A.exe前，向大厅发消息SC_RESPONSE_NEWCONN请求建立新连接； 3、收到大厅发来的消息SC_RESPONSE_NEWCONN后，从abyData中解出连接名，传给B.exe，与大厅建立新连接，A.exe进程结束退出； 若收到SC_RESPONSE_NEWCONN_RUFUSE，表示大厅不会建立新连接，则A.exe不能退出，这种情况很少，只是用来预防偶然因为bug导致请求新链接次数太多，陷入错误循环。 4、同理，如果又要退出B.exe，启动C.exe，则重新进行步骤2向大厅发起请求，等待回复。。。以此类推。 |
|
|
常见反馈问题 |
1、游戏在线人数不对，偏少，或者在线时长不对？ 答：1）首先，请检查游戏与大厅连接是否成功，即检查是否有OnConnectSucc接口的回调； 2）其次，检查与大厅建立的连接是否一直到游戏结束时，才退出； 只有一个进程与大厅进行通信连接的情况来说，确认这个进程一直到游戏结束才退出即可；多个进程和大厅连接时，请确认连接一直都成功而且存在，直到游戏结束。 案例：某游戏有多个进程，与大厅连接的进程很早退出，但游戏主进程还在，但大厅通过进程通信检测到游戏进程已经退出，这样会判断游戏退出，导致在线数据不对。 |
|
|
2、游戏耗时下载资源初始化完成后，连接管道时失败？答： 大厅有管道连接30秒超时机制，当大厅启动游戏进程时就开始搭建好管道等待连接。如果30秒没有管道连接过来，会认为连接超时把之前搭建的管道清除。所以在大厅启动游戏进程后，游戏进程必须立刻连接管道，再进行耗时的初始化步骤避免此问题。 |
||
游戏安装包打包及有关配置
|
游戏exe版本及关联配置文件 |
|
|
配置文件 |
创建config.ini文件到游戏的第一级目录下，如已有这个文件，请直接添加下面所列内容，保证不与游戏的配置重复即可 |
|
要求文件必有的内容（数据项为例子，请参考）： [Public] Version=30212410 ——游戏版本号，8位数字 GameID=10120 ——QQGame侧分配的游戏appid，由接入负责人分配给到 ExeName=Client.exe ——游戏进程名字，由QQGame拉起的进程 RunningExeName=snake.exe —— 为了统一接入成长守护平台，snake.exe是用蛇蛇这款游戏举例，实际为游戏真正的进程名 [QgiMustHave] DestRootFolder = hlddz ——游戏安装目录名字 QgiName=hlddz.qgi ——安装包名字，可按自己的版本规则合名，如hlddzBeta2.qgi
[QgiChooseHave] NeedRegisterExe = 0 ——安装完后是否需要使用/regserver命令启动Client.exe进程 |
|
|
Exe版本号 |
8位数字，规则： 30212410=3*10000000+2*100000+124*100+10 ——> 3.2.124.10 3.2.124.10，是配置到config.ini文件ExeName项中游戏进程Client.exe的版本号，请将其确认写到Exe的文件版本中，可以通过属性来检查，举例如下图： |
|
Exe版本号 |
8位数字，规则： 30212410=3*10000000+2*100000+124*100+10 ——> 3.2.124.10 3.2.124.10，是配置到config.ini文件ExeName项中游戏进程Client.exe的版本号，请将其确认写到Exe的文件版本中，可以通过属性来检查，举例如下图：  |
|
版本号要求 |
1、8位数字，exe属性中配置与config.ini中版本号一致； 2、游戏新版本的版本号必须递增，否则会影响更新。 |
|
游戏安装包打包指引 |
|
|
工具 |
QgiMaker，点击下载
|
|
使用方法 |
1、“新版本目录”请指向新版本文件的目录； 2、“旧版本目录”不需手动指定，软件自定义的默认路径即可，软件会自动将以前制作安装包时版本文件保存下来；用来直接生成部分更新包； 3、“输出目录”指定安装包生成的位置。 4、“开始”。 5、到自己指定的输出目录中，可以看到打包出来的结束，包含以下内容： 一个qgi包，一个exe包，名字都为Config.ini中QgiName中配置的名字；如果以前发布过版本，则还会存在和以前版本对应的部分安装包，qgi格式； 举例如下图所示：  |
|
安装包测试 |
目前是打好安装包，发布到外网测试区，进行安装测试 |
|
游戏版本发布 |
|
|
版本信息（发布时开发商提供） |
游戏方提供新版本游戏的安装包、部分更新包（首次发布没有）给到QQGame的接口人后，还需提供如下版本信息： 最新版本号：这次发布的游戏版本号，与Config.ini中Version一致 外网最低可玩版本号：游戏要求的可运行的最低的版本号，在外网小于这个版本的，大厅会将其进行升级 提示更新版本号：小于这个版本号，大厅会提前用户有新版本可以选择更新 可部分更新版本号：从这个版本号开始的版本，都有部分更新包 第一次版本发布时，上面四个版本号都为发布版本的版本号 |
|
常见反馈问题 |
1、游戏下载后安装失败 请看下【Exe版本号】部分，比对config.ini中Version和exe属性中的版本号是否一致 |
demo演示
请见 pc客户端游戏demo