客户端游戏接入大厅说明
客户端游戏接入QQGame游戏大厅，由大厅拉起游戏进程，并与QQGame进行数据等交互；同时，客户端游戏需要按大厅要求的格式准备安装包，大厅进行游戏的安装及更新。文档中定义大厅打安装包规则、拉起游戏进程命令行参数及与大厅通信的详细内容，对客户端进行接入时，请勿必仔细阅读此文档，确认需要实现的内容。
一、游戏进程启动参数
| 参数格式：ID=XXX,Key=YYYY,PROCPARA=ZZZZZ | ||||
| 参数项 | ID | Key | PROCPARA | |
| 参数说明 | openid | openkey | 进程通信参数 | |
| 最大长度 | 36 | 256 | 128 | |
| 参数作用 | 用于游戏与后台连接，实现拉取玩家信息、支付等功能 | 用于游戏和大厅建立进程通信，大厅通过这个连接来判断游戏是否在线，并通过这个通道来进行游戏与大厅间的数据通信 | ||
| 使用注意 | openid、openkey，为必需项，游戏业务需要用到； PROCPARA，为必需项，大厅要求游戏必须与大厅建立进程通信。 | |||
| 常见反馈问题 | 1、游戏在安装后，会被拉起多次？ 答：请在游戏进程拉起时，对启动参数进行判断，ID、Key、PROCPARA是必须的数据，如果没有这些数据，请直接退出启动流程，不要启动游戏。 |
|||
二、进程通信
| 进程通信组件 | 公共组件 | 请用大厅根目录下：QQGameProcMsgHelper.dll |
| 接口文件 | demo\QQGameProcMsgHelper\Include\ClientProcMsgObject_i.h有定义各接口函数作用及用法 | |
| 实现内容 | 用ClientProcMsgObject来与大厅进行连接与数据通信组件及接口使用方法请参考demo\TestProcDll中 | |
| 接入方案 | 两种方案如下： 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侧接入同事确认开通“多帐号登录”功能 | ||
| 大厅发给游戏的： | ||
| SC_BOSSKEY 0x00000003 老板键 数据项：int值,0是隐藏，1是显示 使用场景：大厅老板键（Alt+Q）隐藏和显示时 |
||
| SC_WND_BRINGTOP 0x00000004 通知游戏界面最新展示 使用场景：游戏窗口被其它程序遮盖，在大厅中再点app图标时，把游戏窗口拉到最前 |
||
| SC_RESPONSE_NEWCONN 0x0000000B 大厅同意游戏请求新起连接 nDataLen：长度，abyData：连接名，字符串 详情请查阅【游戏多进程与大厅连接】部分 |
||
| SC_RESPONSE_NEWCONN_RUFUSE 0x0000000C 大厅拒绝游戏请求新进程连接 详情请查阅【游戏多进程与大厅连接】部分 |
||
| 游戏多进程与大厅连接 | 使用场景 | 游戏有多个进程，而且有类似的逻辑例如：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）其次，检查与大厅建立的连接是否一直到游戏结束时，才退出； |
|
| 只有一个进程与大厅进行通信连接的情况来说，确认这个进程一直到游戏结束才退出即可；多个进程和大厅连接时，请确认连接一直都成功而且存在，直到游戏结束。 案例：某游戏有多个进程，与大厅连接的进程很早退出，但游戏主进程还在，但大厅通过进程通信检测到游戏进程已经退出，这样会判断游戏退出，导致在线数据不对。 | ||
三、游戏安装包打包及有关配置
| 游戏exe版本及关联配置文件 | |
| 配置文件 | 创建config.ini文件到游戏的第一级目录下，如已有这个文件，请直接添加下面所列内容，保证不与游戏的配置重复即可 |
| 要求文件必有的内容（数据项为例子，请参考）： [Public] Version=30212410 ——游戏版本号，8位数字 GameID=10120 ——QQGame侧分配的游戏appid，由接入负责人分配给到 ExeName=Client.exe ——游戏进程名字，由QQGame拉起的进程 [QgiMustHave] DestRootFolder = hlddz ——游戏安装目录名字 QgiName=hlddz.qgi ——安装包名字，可按自己的版本规则合名，如hlddzBeta2.qgi |
|
| 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，QQGame提供 |
| 使用方法 | 1、“新版本目录”请指向新版本文件的目录； 2、“旧版本目录”不需手动指定，软件自定义的默认路径即可，软件会自动将以前制作安装包时版本文件保存下来；用来直接生成部分更新包； 3、“输出目录”指定安装包生成的位置。 4、“开始”。 5、到自己指定的输出目录中，可以看到打包出来的结束，包含以下内容： 一个qgi包，一个exe包，名字都为Config.ini中QgiName中配置的名字；如果以前发布过版本，则还会存在和以前版本对应的部分安装包，qgi格式； 举例如下图所示：  |
| 安装包测试 | 目前是打好安装包，发布到外网测试区，进行安装测试 |
| 游戏版本发布 | |
| 版本信息（发布时开发商提供） | 游戏方提供新版本游戏的安装包、部分更新包（首次发布没有）给到QQGame的接口人后，还需提供如下版本信息： 最新版本号：这次发布的游戏版本号，与Config.ini中Version一致 外网最低可玩版本号：游戏要求的可运行的最低的版本号，在外网小于这个版本的，大厅会将其进行升级 提示更新版本号：小于这个版本号，大厅会提前用户有新版本可以选择更新 可部分更新版本号：从这个版本号开始的版本，都有部分更新包 第一次版本发布时，上面四个版本号都为发布版本的版本号 |
| 常见反馈问题 | 1、游戏下载后安装失败 请看下【Exe版本号】部分，比对config.ini中Version和exe属性中的版本号是否一致 |