External Server Protocol

Introduction

ExternalMessage is the unified interaction protocol (also called external-server protocol). It is the default protocol for interaction with game clients. Concepts here are divided into two parts:

1. Unified interaction protocol: the protocol used to communicate with game clients, i.e., ExternalMessage.
2. Generic wrapping protocol: mainly solves protocol fragmentation, helping developers reduce large amounts of work.

tip

If you use SDK, this section is usually not required.

Proto File

tip

Please provide this .proto file to frontend developers. If SDK is used, this can be skipped.

In addition to the primary ExternalMessage, the proto file also provides several wrapper protocols.

syntax = "proto3";
package com.iohao.message;
// ExternalMessage. cn: 对外服数据协议
message ExternalMessage {
  // Request command type: 0 heartbeat, 1 business .
  // cn: 请求命令类型: 0 心跳，1 业务
  int32 cmd_code = 1;
  // Protocol switch, used for protocol-level switch control, such as security encryption verification, etc. : 0 no verification
  // cn: 协议开关，用于一些协议级别的开关控制，比如 安全加密校验等。 : 0 不校验
  optional int32 protocol_switch = 2;
  // Business routing (high 16 bits for main, low 16 bits for sub)
  // cn: 业务路由（高16为主, 低16为子）
  optional int32 cmd_merge = 3;
  // Response code: 0: success, others indicate errors
  // cn: 响应码: 0:成功, 其他为有错误
  optional sint32 response_status = 4;
  // Verification message (error message, exception message), usually when responseStatus == -1001, there will be a value
  // 验证信息（错误消息、异常消息），通常情况下 responseStatus == -1001 时， 会有值
  optional string valid_msg = 5;
  // Business request data
  // 业务请求数据
  optional bytes data = 6;
  // Message tag number; set by the front-end when requesting, and will be carried by the server when responding; (similar to transparent transmission parameters)
  // 消息标记号；由前端请求时设置，服务器响应时会携带上；（类似透传参数）
  optional int32 msg_id = 7;
}

// int wrapper class. cn: int 包装类
message IntValue {
  sint32 value = 1;
}

// int list wrapper class. cn: int list 包装类
message IntValueList {
  // intList、intArray
  repeated sint32 values = 1;
}

// long wrapper class. cn: long 包装类
message LongValue {
  sint64 value = 1;
}

// long list wrapper class. cn: long list 包装类
message LongValueList {
  // longList、longArray
  repeated sint64 values = 1;
}

// string wrapper class. cn: string 包装类
message StringValue {
  string value = 1;
}

// bool wrapper class. cn: string list 包装类
message StringValueList {
  // stringList、stringArray
  repeated string values = 1;
}

// bool wrapper class. cn: bool 包装类
message BoolValue {
  bool value = 1;
}

// bool list wrapper class. cn: bool list 包装类
message BoolValueList {
  // boolList、boolArray
  repeated bool values = 1;
}

// pb object list wrapper class. cn: 对象 list 包装类
message ByteValueList {
  // pb object List、pb object Array
  // pb 对象 List、pb 对象 Array
  repeated bytes values = 1;
}

About passthrough parameter msg_id

warning

By default, this only takes effect in request/response mode, i.e., action methods with return values.

ExternalMessage.msg_id works like a passthrough parameter. If you do not need this behavior, you can ignore the field.

Frontend can set msg_id in external protocol. After server receives and processes request, it returns msg_id back in response. If SDK is used, this can be ignored because SDK auto-assigns msg_id for each request.

ExternalMessage

ExternalMessage is the unified interaction protocol and default protocol for client-server interaction.

Client requests to server are divided into two types:

1. Heartbeat request: required field is cmd_code = 0; other fields ignored.
2. Business request: required fields are cmd_code = 1, cmd_merge; others optional, see table below.

Request Description

Usage when sending 【business request】
Field name	Required	Description
cmd_code	✅	cmd_code must be 1.
protocol_switch	Ignore	Reserved for developers.
cmd_merge	✅	Route.
response_status	Ignore	In server response, 0 means success; others are error codes.
valid_msg	Ignore	Error message.
data	Optional	Business parameters; server receives this field.
msg_id	Optional	Set by client, returned unchanged by server in response.

Response Description

When writing actions, framework places the newHelloMessage object below into ExternalMessage.data.

@ActionController(1)
public class DemoAction {
    @ActionMethod(0)
    public HelloMessage here(HelloMessage message) {
        HelloMessage newHelloMessage = ...
        return newHelloMessage;
    }
}

Description when responding to 【business request】
Field name	Description
cmd_code	value is 1
cmd_merge	current action route value
response_status	in server response, 0 means success; others are error codes
valid_msg	error message
data	object returned by action is put here
msg_id	set by client, returned unchanged by server

xxxValue Generic Wrapping Protocol

xxxValue is the framework-provided wrapper protocol type, mainly used to solve protocol fragmentation.

syntax = "proto3";

message IntValue {
  sint32 value = 1;
}

message IntValueList {
  repeated sint32 values = 1;
}

message LongValue {
  sint64 value = 1;
}

message LongValueList {
  repeated sint64 values = 1;
}

message StringValue {
  string value = 1;
}

message StringValueList {
  repeated string values = 1;
}

message BoolValue {
  bool value = 1;
}

message BoolValueList {
  repeated bool values = 1;
}

message ByteValueList {
  repeated bytes values = 1;
}

Summary

This section described the ExternalMessage unified interaction protocol and the generic wrapping protocol. The generic wrapping protocol mainly solves protocol fragmentation and can reduce substantial development effort.

If there are no special requirements, it is recommended to use framework-provided ExternalMessage for frontend interaction.