MOGS API 文档

# 适配层相关接口

测试环境URL https://test.mogs.qq.com:10007
测试环境L5 192000068:84146

# 开始单局游戏

# 接口名

测试环境 https://test.mogs.qq.com:10007/start_battle
  • URL请求参数说明
参数 类型 是否必填 描述
game_id uint64_t 是 GameId，是游戏的唯一标识
plat_id int32 是 请求来源：1. 有乐 2. 电竞 3. mogs

  • 有乐及电竞平台请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
battle_id string 是 房间id
game_version string 否 游戏版本号
force_check_mode int32 否 强校验模式,0表示默认(不满足绝大多数则走强校验),1表示不走强检验,2表示必须走强校验
callback_server Object 是 结果上报回调地址
    addr_type int32 是 1:L5 2:北极星 3:http
    addr_info string 是 addr_type=1时表示namespace:mod:cmd:urlpath
addr_type=2时表示namespace:server_name:urlpath
addr_type=3时表示全路径url
lockstep_room_conf Object 是 帧同步房间参数配置
    wait_time int32 是 房间创建后自动开始的等待时长(ms)，根据需求设置
    room_life_period_ms int32 是 房间开始后的生命周期(ms)，根据需求设置，大于游戏最大时长
    frame_interval_ms int32 是 帧间隔(ms)（建议30或60）
    start_game_min_user_count int32 是 自动开始的最少玩家数（不考虑观战建议255）
    need_play_from_first_frame_on_reconn int32 是 重连后是否获取首帧（建议1）
    broadcast_to_self int32 是 是否广播给自己（建议1）
    use_udp int32 是 是否使用UDP
match_result Object 是 匹配的结果信息
    game_id int32 是 GameId
    mode_id int32 是 模式id，事先约定的游戏配置
如果游戏的玩法可以由人数直接确定，可以不依赖该值；
如果游戏同样的人数由多种玩法，比如5v5爆破、5v5团战，
则需要依赖该值进行处理，该值需要实现约定好；
    player_list []Object 是 玩家列表
        uid string 是 玩家uid
        camp_id int32 是 玩家所在的阵营id
        is_ai int32 是 是否AI
        grade_score int32 否 段位积分
        play_times int32 否 用户历史场次数
        data_list []int32 否 用户存储的数据列表，需要事先约定好，游戏可用作相关判断
        user_match_from int32 否 用户匹配来源，仅做统计用途
        is_observer int32 否 是否观战玩家，观战玩家须指定is_ai为0
    • 响应参数说明（Json格式）
字段名 类型 描述
battle_id string 房间id
expire_time int32 超时秒时间戳，超过该时间未收到游戏结算信息，有乐测会认为该局超时并做异常处理，可以按照理论最大时长设置
battle_access_info string 局维度的信息，该信息会透传给web测，具体内容格式由游戏侧负责，比如记录服务器的地址以及单局房间相关信息
player_list []Object 如果需要针对特定用户记录信息的话，可以选择使用该字段
    uid string 玩家uid
    user_access_info string 用户维度的信息，该信息户透传给web测，具体内容格式由游戏侧负责
    lockstep_player_id uint32 帧同步玩家id
  • 使用示例:
--1v1 请求包体
curl -X POST -d '{
  "base_header": {
      "cmd": 11
  },
  "start_battle_req": {
      "battle_id": "13578912132434235",
      "force_check_mode":2,
      "callback_server":{
          "addr_type":1,
          "addr_info":"Development:192000066:84340:/report_battle_result",
      },
      "lockstep_room_conf":{
          "broadcast_to_self":1,
          "frame_interval_ms":60,
          "need_play_from_first_frame_on_reconn":1,
          "room_life_period_ms":1860000,
          "start_game_min_user_count":255,
          "use_udp":1,
          "wait_time":30000
      },
      "match_result": {
          "game_id": 301,
          "mode_id": 1,
          "player_list": [{
              "uid": "1234567888",
              "camp_id": 0,
              "is_ai": 0,
              "grade_score": 123,
              "play_times": 15,
              "data_list": [12,2]
          },
          {
              "uid": "1234567999",
              "camp_id": 1,
              "is_ai": 0,
              "grade_score": 321,
              "play_times": 15,
              "data_list": [11,5]
          }]
      }
  }
}' 'https://test.mogs.qq.com:10007/start_battle?game_id=10000&plat_id=1'

-- 回包示例
{
    "base_header": {
        "cmd": 11,
        "err_code": 0,
        "err_msg": "succ"
    },
    "start_battle_rsp": {
        "battle_id": "13578912132434235",
        "expire_time": 1572499139,
        "battle_access_info": "server_id=12&room_id=34",
        "player_list": [
            {
                "uid": "1234567888",
                "user_access_info": "token=abcd&playerid=1"
            },
            {
                "uid": "1234567999",
                "user_access_info": "token=abcd&playerid=2"
            }
        ]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

  • mogs平台请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
room_id uint64 是 房间id
game_version string 否 游戏版本号
cancel_force_check bool 否 是否取消强校验
addr_type int32 是 1:L5 2:北极星 3:http
addr_info string 是 addr_type=1时表示namespace:mod:cmd:urlpath
addr_type=2时表示namespace:server_name:urlpath
addr_type=3时表示全路径url
lockstep_conf Object 是 帧同步房间参数配置
    wait_time int32 是 房间创建后自动开始的等待时长(ms)，根据需求设置
    room_life_period_ms int32 是 房间开始后的生命周期(ms)，根据需求设置，大于游戏最大时长
    frame_interval_ms int32 是 帧间隔(ms)（建议30或60）
    start_game_min_user_count int32 是 自动开始的最少玩家数（不考虑观战建议255）
    need_play_from_first_frame_on_reconn int32 是 重连后是否获取首帧（建议1）
    broadcast_to_self int32 是 是否广播给自己（建议1）
    use_udp int32 是 是否使用UDP
player_list []Object 是 真实玩家列表
watch_list []Object 是 观战玩家列表
battle_info string 否 自定义透传数据 不超过 65535
    • 响应参数说明（Json格式）
字段名 类型 描述
room_id uint64 房间id
lockstep_room_id uint64 帧同步服务器返回的房间id
room_life_period_ms int32 房间最大存活时间 单位为毫秒
token_list []Object 如果需要针对特定用户记录信息的话，可以选择使用该字段
    player_id string 玩家uid
    token string 帧同步房间token
    lockstep_player_id uint32 帧同步玩家id
  • 使用示例:
curl -X POST -d '{
      "room_id": "13578912132434235",
      "cancel_force_check":false,
      "game_version":"1.0.0",
      "addr_type":1,
      "addr_info":"Development:192000066:84340:/report_battle_result",
      "lockstep_conf":{
          "broadcast_to_self":1,
          "frame_interval_ms":60,
          "need_play_from_first_frame_on_reconn":1,
          "room_life_period_ms":1860000,
          "start_game_min_user_count":255,
          "use_udp":1,
          "wait_time":30000
      },
      "player_list": ["aaa","bbb"],
      "watch_list": ["ccc"],
      "battle_info":"112"
  }' 'https://test.mogs.qq.com:10007/start_battle?game_id=10000&plat_id=1'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 查询游戏结果

# 接口名

测试环境 https://test.mogs.qq.com:10007/query_battle_result
  • URL请求参数说明
参数 类型 是否必填 描述
game_id uint64_t 是 GameId，是游戏的唯一标识
plat_id int32 是 请求来源：1. 有乐 2. 电竞 3. mogs

  • 有乐及电竞平台请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
battle_id string 是 房间id
    • 响应参数说明（Json格式）
字段名 类型 描述
battle_id string 房间id
battle_result_flag int32 游戏对局标识 0:正常 1:异常
battle_result []Object 如果需要针对特定用户记录信息的话，可以选择使用该字段
    uid string 玩家uid
    camp_id int32 玩家所在的阵营id
    rank int32 混战类型（单阵营）上报玩家的排名，对战类型（多阵营）上报玩家所在阵营的排名；排名从1开始，允许并列；
    result int32 对战类型（多阵营）上报玩家所在阵营的胜负信息1:胜 0:平 -1:负
  • 使用示例:
--请求示例
curl -X POST -d '{
    "base_header": {
        "cmd": 12
    },
    "query_battle_result_req": {
        "battle_id": "13578912132434235"
    }
}' 'https://test.mogs.qq.com:10007/query_battle_result?game_id=10000&plat_id=1'

-- 回包示例
{
    "base_header": {
        "cmd": 12
    },
    "query_battle_result_rsp": {
        "battle_id": "13578912132434235",
        "battle_result_flag": 0,
        "battle_result": [{
            "uid": "1234567888",
            "camp_id": 0,
            "rank": 1,
            "result": 1
        },
        {
            "uid": "1234567999",
            "camp_id": 1,
            "rank": 2,
            "result": -1
        }]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

  • mogs平台请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
room_id uint64 是 房间id
    • 响应参数说明（Json格式）
字段名 类型 描述
room_id uint64 房间id
report_info string SDK上报的battle_result结构
  • 使用示例:
curl -X POST -d '{"room_id": "13578912132434235"}' 'https://test.mogs.qq.com:10007/query_battle_result?game_id=10000&plat_id=1'
1

# 查询房间信息

# 接口名

测试环境 https://test.mogs.qq.com:10007/query_battle
  • URL请求参数说明
参数 类型 是否必填 描述
game_id uint64_t 是 GameId，是游戏的唯一标识
plat_id int32 是 请求来源：1. 有乐 2. 电竞 3. mogs

  • 有乐及电竞平台请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
battle_id string 是 房间id
    • 响应参数说明（Json格式）
字段名 类型 描述
battle_id string 房间id
player_list []Object 如果需要针对特定用户记录信息的话，可以选择使用该字段
    uid string 玩家uid
    user_access_info string 用户维度的信息，该信息户透传给web测，具体内容格式由游戏侧负责
    lockstep_player_id uint32 帧同步玩家id
  • 使用示例:
--请求示例
curl -X POST -d '{
    "base_header": {
        "cmd": 12
    },
    "query_battle_req": {
        "battle_id": "13578912132434235"
    }
}' 'https://test.mogs.qq.com:10007/query_battle?game_id=10000&plat_id=1'

-- 回包示例
{
    "base_header": {
        "cmd": 12
    },
    "query_battle_rsp": {
        "battle_id": "13578912132434235",
        "player_list": [
            {
                "uid": "1234567888",
                "user_access_info": "token=abcd&playerid=1"
            },
            {
                "uid": "1234567999",
                "user_access_info": "token=abcd&playerid=2"
            }
        ]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

  • mogs平台请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
room_id uint64 是 房间id
    • 响应参数说明（Json格式）
字段名 类型 描述
room_id uint64 房间id
lockstep_room_id uint64 帧同步服务器返回的房间id
token_list []Object 如果需要针对特定用户记录信息的话，可以选择使用该字段
    player_id string 玩家uid
    token string 帧同步房间token
    lockstep_player_id uint32 帧同步玩家id
  • 使用示例:
curl -X POST -d '{"room_id": "13578912132434235"}' 'https://test.mogs.qq.com:10007/query_battle?game_id=10000&plat_id=1'
1

# 退出房间

# 接口名

测试环境 https://test.mogs.qq.com:10007/leave_battle
  • URL请求参数说明
参数 类型 是否必填 描述
game_id uint64_t 是 GameId，是游戏的唯一标识
plat_id int32 是 请求来源：1. 有乐 2. 电竞 3. mogs
openid string 是 玩家uid, 有乐和电竞平台不需要传

  • 有乐及电竞平台请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
battle_id string 是 房间id
uid string 是 玩家uid
    • 响应参数说明（Json格式）
字段名 类型 描述
  • 使用示例:
--请求示例
curl -X POST -d '{
    "base_header": {
        "cmd": 13
    },
    "leave_battle_req": {
        "battle_id": "13578912132434235"
    }
}' 'https://test.mogs.qq.com:10007/leave_battle?game_id=10000&plat_id=1'

-- 回包示例
{
    "base_header": {
        "cmd": 13,
        "err_code": 0
    },
    "leave_battle_rsp": {}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

  • mogs平台请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
room_id uint64 是 房间id
token string 是 创建房间下发的 token
    • 响应参数说明（Json格式）
字段名 类型 描述
ret int32 错误码
error_msg string 错误码
  • 使用示例:
curl -X POST -d '{"room_id":"123","token": "123"}' 'https://test.mogs.qq.com:10007/leave_battle?game_id=10000&plat_id=1&openid=efg'
1

# 客户端SDK上报退出房间

# 接口名

测试环境 https://test.mogs.qq.com:10007/clientleave_battle
  • URL请求参数说明
参数 类型 是否必填 描述
game_id uint64_t 是 GameId，是游戏的唯一标识
plat_id int32 是 请求来源：1. 有乐 2. 电竞 3. mogs
openid string 是 玩家uid, 有乐和电竞平台不需要传

  • 请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
room_id uint64 是 房间id
token string 是 创建房间下发的 token
    • 响应参数说明（Json格式）
字段名 类型 描述
ret int32 错误码
error_msg string 错误码
  • 使用示例:
curl -X POST -d '{"room_id":"123","token": "123"}' 'https://test.mogs.qq.com:10007/clientleave_battle?game_id=10000&plat_id=1&openid=efg'
1

# 客户端SDK上报结算结果

# 接口名

测试环境 https://test.mogs.qq.com:10007/clientreport_battle
  • URL请求参数说明
参数 类型 是否必填 描述
game_id uint64_t 是 GameId，是游戏的唯一标识
plat_id int32 是 请求来源：1. 有乐 2. 电竞 3. mogs
openid string 是 玩家uid

  • SDK请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
room_id uint64 是 房间id
report_info string 是 结算上报透传信息,打包好的结果数据，比如需要回传的battle_result结构
token string 是 创建房间下发的 token
    • 响应参数说明（Json格式）
字段名 类型 描述
ret int32 错误码
error_msg string 错误码
  • 使用示例:
curl -X POST -d '{"room_id":"123","report_info": "hello world", "token":"1111"}' 'https://test.mogs.qq.com:10007/clientreport_battle?game_id=10000&plat_id=1&openid=efg'
1

# 适配层回调上报结算结果

使用创建房间请求中的addr_type和addr_info信息来回调平台服务器上报结算结果

  • 有乐及电竞平台回调请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
battle_id string 是 房间id
    • 响应参数说明（Json格式）
字段名 类型 描述
battle_id string 房间id
player_list []Object 如果需要针对特定用户记录信息的话，可以选择使用该字段
    uid string 玩家uid
    user_access_info string 用户维度的信息，该信息户透传给web测，具体内容格式由游戏侧负责
    lockstep_player_id uint32 帧同步玩家id
    • 回包错误码
错误码 错误描述 可能原因
-1 服务器内部异常 有乐服务器内部处理异常，可以找有乐具体查询原因
101 请求参数异常 错误描述中会有详细的错误原因，比如battle_id字段不存在；battle_result中的result的值不正确；
301001 battle_id不存在 battle_id传错了，或者对应单局已经失效,对于超时的单局，有乐会按照超时进行处理，不需要再上报结果
301002 参与游戏的用户列表不一致 强烈建议上报开局的所有用户，不管是否参与游戏
301003 该对局已经上报并且成功处理 重复上报同一对局，该battle_id对应的单局之前上报并且已经被成功处理过。
  • 使用示例:
-- 1v1
{
    "base_header": {
        "cmd": 31
    },
    "report_battle_result_req": {
        "battle_id": "13578912132434235",
        "battle_result_flag": 0,
        "battle_result_code": 0,
        "battle_result": [{
            "uid": "1234567888",
            "camp_id": 0,
            "rank": 1,
            "result": 1,
            "score": 123,
            "play_flag": 0,
            "punishment_flag": 0,
            "data_list": [6, 8, 10],
            "data_idx_list": [0, 2, 3]
        },
        {
            "uid": "1234567999",
            "camp_id": 1,
            "rank": 2,
            "result": -1,
            "score": 100,
            "play_flag": 0,
            "punishment_flag": 0,
            "data_list": [11, 13, 14],
            "data_idx_list": [0, 2, 3]
        }]
    }
}

-- 回包示例
{
    "base_header": {
        "cmd": 31,
        "err_code": 0,
        "err_msg": "succ"
  },
  "report_battle_result_rsp": {
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

  • mogs平台请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
room_id uint64 是 房间id
report_info string 是 结算上报透传信息,打包好的结果数据，比如需要回传的battle_result结构
    • 响应参数说明（Json格式）
字段名 类型 描述
ret int32 错误码
error_msg string 错误码
  • 使用示例:
{
    "room_id": "13578912132434235",
    "report_info": [{
        "uid": "1234567888",
        "camp_id": 0,
        "rank": 1,
        "result": 1,
        "score": 123,
        "play_flag": 0,
        "punishment_flag": 0,
        "data_list": [6, 8, 10],
        "data_idx_list": [0, 2, 3]
    },
    {
        "uid": "1234567999",
        "camp_id": 1,
        "rank": 2,
        "result": -1,
        "score": 100,
        "play_flag": 0,
        "punishment_flag": 0,
        "data_list": [11, 13, 14],
        "data_idx_list": [0, 2, 3]
    }]
}

{
    "ret": 0,
    "error_msg": ""
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# MOGS后台请求关闭房间

# 接口名

测试环境 https://test.mogs.qq.com:10007/close_battle
  • URL请求参数说明
参数 类型 是否必填 描述
game_id uint64_t 是 GameId，是游戏的唯一标识
plat_id int32 是 请求来源：1. 有乐 2. 电竞 3. mogs
openid string 是 玩家uid

  • 请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
room_id uint64 是 房间id
lockstep_room_id uint64 是 帧同步服务器返回的房间id
reason_code int32 是 离开原因code
reason_detail string 是 离开原因
    • 响应参数说明（Json格式）
字段名 类型 描述
ret int32 错误码
error_msg string 错误码
  • 使用示例:
curl -X POST -d '{"room_id":"123","lockstep_room_id": "123", "reason_code":0,"reason_detail":"1111"}' 'https://test.mogs.qq.com:10007/close_battle?game_id=10000&plat_id=1&openid=efg'
1

# 客户端SDK上报拉取帧数据

# 接口名

测试环境 https://test.mogs.qq.com:10007/pullframe_battle
  • URL请求参数说明
参数 类型 是否必填 描述
game_id uint64_t 是 GameId，是游戏的唯一标识
plat_id int32 是 请求来源：1. 有乐 2. 电竞 3. mogs
openid string 是 玩家uid

  • SDK请求参数说明（Json格式）

    • Body请求参数说明（Json格式）
参数 类型 是否必填 描述
room_id uint64 是 房间id
frame_begin int32 是 开始帧
frame_end int32 是 结束帧
    • 响应参数说明（Json格式）
字段名 类型 描述
ret int32 错误码
frame_begin int32 开始帧
frame_end int32 结束帧
frame_list []Object 帧数据列表
    frameID uint32 帧id
    lagFrameNum uint32
    timeStamp uint32
    tickMS uint32
    dataList []Object
        userID uint32
        data string
        statusFlag bool
        seqID uint32
  • 使用示例:
curl -X POST -d '{"room_id":"123","frame_begin": 100, "frame_end":120}' 'https://test.mogs.qq.com:10007/pullframe_battle?game_id=10000&plat_id=1&openid=efg'
1

← 配表流程 →